The Vocabulary Reference

This reference explains the Blueprint vocabulary that is implemented and exported by the current packages. For the implementation-backed symbol inventory, see the Live Vocabulary Inventory.

Blueprint has three planes and four grammar roles:

• declaration describes stable domain intent;
• configuration resolves scope-dependent values such as policy and grants;
• execution accepts requests and produces plans, records, and effects;
• the grammar roles are Declaration, Request, Effective Resolution, and Record.

The seven layers

Layer	Name	Plane	What belongs here
1	Field types	Declaration	Closed value interpretation, codecs, DDL mapping, and primitive validation.
2	Field tokens	Declaration	Named typed atoms, semantic fields, row access, and DB/UI/seed hints.
3	Structure	Declaration	Blueprint, module, entity, facet, relationship, lifecycle, projection, and descriptors.
4	Logic	Declaration	Predicates, actor sets, conditions, rules, invariants, and evaluator refs.
5	Work and proof	Declaration	Actions, tasks, evidence, audit envelopes, effects, and subscriptions.
6	Scope configuration	Configuration	Policies, grants, assignments, provider bindings, locks, and effective resolution.
7	Runtime effects	Execution	Queries, actions, plans, preflight, records, database/audit/outbox effects, and traces.

Audit rows, outbox entries, realtime signals, simulations, and DevTools traces are outputs of the common runtime. They are not separate domain runtimes.

Field types

FieldType is sealed so codecs, validators, and database compilers can switch exhaustively.

Member	Parameters	Meaning
TextType	maxLength?	varchar/text
IntegerType	—	integer
BigIntType	—	large integer
DoubleType	—	floating point
DecimalType	precision, scale	exact numeric; represented as String at the Dart boundary
BooleanType	—	boolean
TimestampType	withTimeZone	timestamp
DateType	—	date
IntervalType	—	interval
UuidType	—	UUID
JsonbType	—	structured JSON
EnumType	name, values	named PostgreSQL enum with stable wire values
DecisionType	—	allow/deny decision

Fields and rows

Field<T> carries name, type, human text, nullability, defaults, validation, indexes, uniqueness, and FieldDb, FieldUI, and FieldSeed hints. Composite uniqueness belongs to Entity.uniqueKeys.

Row is a typed view over Map<String, Object?>:

• maybe(field) decodes an optional value;
• require(field) decodes a required value and names the missing field;
• set(field, value) writes the encoded wire value;
• toMap() exposes the underlying map.

Field tokens

Token	Dart value	Purpose
TextField	String	text with optional maximum length
IntegerField	int	integer
BigIntField	int	large integer
DoubleField	double	floating point
DecimalField	String	exact decimal
BooleanField	bool	boolean
TimestampField	DateTime	timestamp
DateField	DateTime	date
UuidField	String	UUID
JsonbField	Map<String, Object?>	structured JSON
EnumField<E>	E	enum with a stable database enum name
ListField<T>	List<T>	JSON-backed list

Semantic field tokens

Token	Convention
CodeField	non-null indexed identity text
NameField	non-null searchable display name
DescriptionField	nullable long text
TenantIdField	non-null tenant UUID
SiteIdField	nullable site UUID
ActorField	person/actor UUID semantics
StatusField<E>	typed lifecycle/status enum with query and badge hints
EffectiveFromField / EffectiveUntilField	effective-dating timestamps
ReferenceIdField	indexed structural reference UUID
IdentifierField	generated identity from a parsed mask
QuantityField	exact quantity paired with a unit field or fixed UnitRef
MoneyField	exact money paired with a currency field or fixed CurrencyRef
FileField	structured file manifest
RelatedField<T>	view-only field flattened through a declared relationship

RelatedField chains may cross successive direct relationships, must end in a stored field, and are cycle-validated. Nested reads use relationship embedding instead.

Stable references

References point across declaration or configuration boundaries without turning those boundaries into untyped strings.

Ref	Points into
GrantRef	an IAM grant capability
QualificationRef	a training/competence capability
ActionRef	a qualified action
TaskTemplateRef	a task template
RuleRef	a declared rule
ErrorRef	a structured error definition
RemedyRef	a remedy definition
EvaluatorRef	an imperative evaluator registry entry
RoleRef / GroupRef	role and group codes
EvidenceSourceRef	an evidence producer
UnitRef / CurrencyRef	units and currencies

Prefer a typed object when the declaration owns the value, a ref when another catalog owns it, and a raw string only for runtime data identities.

Structure

Type	Contract
Blueprint	named, versioned program containing modules; bootstrap() produces EffectiveBlueprint
Module	namespace, schema, dependencies, exports, entities, task templates, invariants, errors, remedies, DB hints, UI hints, and seeds
Entity	identity, table, facets, tenancy, versioning, unique keys, projections, DB/UI/seed hints
IdentityFacet	required anchor facet; identity and composite-key fields live here
Facet	composable fields, relationships, lifecycle, actions, derived values, subscriptions, evidence, audit, and UI hints
Relationship	graph meaning plus optional explicit ReferenceIdField storage binding
EntityDescriptor	cross-module contribution of facets, aggregates, or UI metadata

Relationship kinds are belongsTo, hasOne, hasMany, and manyToMany. Cascade and embedding are independent. Rich memberships and assignments are modeled as explicit association entities.

Entity history and governed revisions

EntityVersioning is the only entity-history axis:

• EntityVersioning.none keeps the current row plus normal audit data;
• EntityVersioning.versions preserves an immutable snapshot for every save;
• const EntityVersioning.revisions(...) adds governed draft, review, effective, superseded, retired, and abandoned business revisions.

The revision declaration owns review requirements, parallel-draft policy, owned relationship refs, revision actions, and create/update audit envelopes. The runtime supplies the reserved $revision actions for creating, submitting, publishing, and abandoning revisions.

Behavior

Type	Contract
Lifecycle	state field, initial state, and deterministic transitions
Transition	from-state, to-state, trigger, rule refs, and effects
Action	payload, consistency, rules, evidence, audit, snapshots, events, effects, errors, and UI metadata
Rule	typed condition, phase, severity, structured error, and provenance
Effect	a target entity/facet/trigger plus typed payload mapping
TaskEffect	the standard effect that creates workflow work

Conditions

Condition	Meaning
AlwaysCondition / NeverCondition	boolean constants
AllCondition / AnyCondition / NotCondition	condition composition
EvaluatorCondition	registry-backed evaluator
StateIsCondition	lifecycle state check
PredicateCondition	field-predicate tree
ActorInSetCondition	actor-set membership
FieldEqualsCondition / ExistsCondition	field checks
EvidencePresentCondition	evidence check
ActorHasGrantCondition / ActorQualifiedCondition	IAM and qualification checks

Predicates and rules

FieldPredicate uses Compare, MatchEverything, MatchNothing, AllMatch, AnyMatch, and NoneMatch. Supported comparisons include equality, inequality, existence, null, and ordered comparisons.

Rule is the only predicate vocabulary. Author it on Action.rules, Entity.rules, Relationship.rules, Module.rules, or Blueprint.rules. Rule.phase is availability, beforeCommit, or afterCommit. Conditions are PredicateCondition, EvaluatorCondition, grant/policy/state checks, and boolean composites.

Actors, assignment, and work

ActorSet is the boolean algebra for access and eligibility. Leaves are ActorUser, Initiator, ActorInField, Role, Group, Grant, and Qualified; constants are Anyone and NoOne; composition uses AllOf, AnyOf, NoneOf, and Locked.

Task assignment uses UserSelector, GroupSelector, RoleSelector, and DerivedSelector inside AssignmentSpec. ClaimMode selects pooled claim or direct assignment. TaskTemplate adds a required completion action, completion strategy (ClaimSingle, ParallelAll, or Quorum), expiry duration, escalations, separation-of-duties constraints, and optional expiry template.

Every task completes through a Blueprint action and therefore produces the same action, audit, evidence, and replay records as other governed work.

Evidence and audit

Evidence declares the evidence name, kind, requirement, source, and retention reference. AuditEnvelope declares signature, reason-code, evidence, and replay requirements. Runtime EvidenceRecord, audit rows, snapshots, and ActionRecord instances preserve what was supplied and what the engine used.

When an audit envelope requires a signature, the current client/server stack supports credential re-verification, one-time electronic-signature assertions, action-digest binding, signer facts, meaning, and assertion expiry.

Policy and IAM

Policy declarations use PolicyDomain, PolicySection, PolicyParameter, and PolicyLock. PolicyScopeLadder resolves values from global through tenant, site, module, entity, facet, action, and instance scope into traced EffectivePolicy values. The effective-policy browser renders this provenance.

IAM uses:

• IamActionDescriptor for one fully-qualified product action;
• IamProductDescriptor for the product action catalog and coverage checks;
• Grant, PrincipalRef, roles, groups, and time/scope limits for assignments;
• AccessExpression and EffectiveAccess for evaluated authorization;
• vyuh_iam_ui for action catalogs, grant editing, permission matrices, and effective-permission inspection.

Public, self-service, and system actions remain in the product inventory with grantEditable: false; grant editors expose only administratively assignable actions.

Projection, query, and UI

FacetProjection, ProjectedField, QueryBehavior, and StorageBinding define the read shape. DerivedValue supports generated columns, SQL views, materialized views, and server evaluators with declared dependencies.

FieldUI, EntityUI, ListUI, DetailUI, EditorUI, RelatedUI, FacetUI, and ActionUI describe presentation intent. List layouts are TableUI, GridUI, KanbanUI, CalendarUI, TreeUI, TimelineUI, and CustomUI. Filters, sorting, grouping, layout, and saved-view state remain typed Vyuh Query ASTs.

Generic enterprise rendering belongs to vyuh_studio_ui; CDX packages own low-level controls and view mechanics; vyuh_blueprint_ui maps Blueprint metadata and protocol data into Studio contracts. Custom UI is bound through stable refs in ClientUIBindings, including forms, detail tabs, empty states, dashboard widgets, and report blocks. Declared-but-unbound refs appear in readiness diagnostics and use a deterministic placeholder.

Application and authentication declarations

BlueprintDescriptor packages modules, app descriptors, and extension refs. BlueprintDescriptorSet explicitly assembles the selected descriptors into an entity Blueprint and BlueprintApp.

BlueprintApp carries branding, portfolio discovery, workspace, shell, realtime, offline, help, search, authentication, navigation, routes, inboxes, dashboards, reports, and extension refs. AuthenticationUI declares only the client boundary: public/login/callback paths, required-auth posture, password reset availability, and replaceable widget refs. Provider availability and session policy are resolved by the server authority for the active tenant and environment.

The protocol exposes provider discovery, begin/complete authentication, login, refresh, logout, current subject, password change/reset, administrator contact, credential verification, and session revocation. BlueprintAuthenticationController derives this contract from the declared authentication entity and delegates provider-specific work through BlueprintAuthenticationProvider.

Runtime and verification

Queries and actions enter through the common protocol. The runtime evaluates conditions, actor sets, policies, rules, invariants, evidence, and audit, then produces an ExecutionPlan, ActionRecord, and typed runtime effects.

PlannedRuntimeEffect kinds cover database, audit, action-record, query-record, outbox, realtime, dry-run, and custom effects. Idempotency, request lineage, snapshots, per-effect state, and sequence fields support resume and replay.

The supported verification loop is:

1. BlueprintValidator.validate(blueprint) checks declaration integrity.
2. DbCompiler.compile(blueprint) produces DDL and runtime artifacts.
3. DatabaseInspection.from(...) exposes the exact generated schemas, tables, columns, constraints, indexes, relationships, triggers, views, and SQL.
4. SystemReadinessReport.evaluate(...) combines validation, compilation, installed-table probes, subscription installation, and delivery-worker configuration into ready, degraded, or blocked.
5. runtime preflight and execute perform request-level verification and persist the resulting records.

See the Tutorial for the progressive construction path and the Execution Replay Contract for record ordering and reconstruction.