Blueprint Execution Semantics

This document specifies how current Blueprint declarations lower into query, action, transaction, evidence, history, and workflow behavior.

1. Projections and queries

An EntityProjection declares the readable and writable shape exposed for an entity. A FacetProjection contributes facet-owned fields to that shape. ProjectedField binds a semantic field identity to storage placement, access, query behavior, and UI behavior.

NamedQuery gives a stable name to a query over one typed entity projection. The protocol carries filters, sorting, grouping, pagination, and selection as the shared Vyuh Query AST. A runtime MUST reject a field that the target projection does not expose or permit for the requested operation.

Database views and materialized views are lowering strategies for declared projections and derived values. They are not authoring sources.

2. Actions

Every mutation is an Action. An action belongs to one facet and declares:

• scope and typed payload;
• closed or extensible payload shape;
• consistency and idempotency input;
• rules and conditions;
• evidence and audit requirements;
• snapshots and errors;
• emitted domain events;
• one ordered list of typed effects; and
• the traces and values captured for explanation.

Entity create, update, and delete behavior is normalized to standard identity actions by the runtime. Domain actions remain owned by their declaring facets.

Effect algebra

Effect is the common Dart type for post-commit work. The implemented variants are:

Variant	Meaning	Delivery
ActionEffect	Invoke another Blueprint action. Effect(...) is its concise factory spelling.	Strict effects expand into the same request and transaction; eventual effects use the outbox.
WorkflowEffect	Start an immutable registered durable workflow with typed input and correlation mappings.	Transactional outbox after the source action commits.
TaskEffect	Create a task from a declared TaskTemplateRef. It specializes ActionEffect.	The ordinary action-effect channel.

All variants are authored in Action.effects, retain their list order, carry an explicit kind in canonical serialization and Explorer output, lower to PlannedRuntimeEffect, and produce ActionEffectRecord entries. There is no separate workflow-effect authoring list.

3. Request lifecycle

ActionRequest is the atomic request envelope. It carries verified context, source, lineage, execution limits, resume policy, and one or more ActionCommand values. A command identifies module.entity.facet.action, its target entity, optimistic expected version, idempotency key, and payload.

The runtime lifecycle is:

request
  -> plan
  -> preflight
  -> transactional revalidation
  -> execute
  -> durable ActionRecord
  -> explain

The ExecutionPlan is bound to a Blueprint revision and plan hash. Each PlannedActionCommand records its phases, locks, snapshots, writes, invariants, and ordered runtime effects. Execution MUST reject a record whose plan id, plan hash, or Blueprint revision does not match the persisted plan.

4. Atomic action plans

A request containing multiple commands is fail-closed by default. ActionTransactionPolicyCatalog is server-owned; request metadata cannot weaken it. If any command produces a partial-commit outcome and every command is not explicitly covered by commitSuccessfulCommands, the executor changes the request to a denied result with action.atomic_request_aborted.

The Explorer also derives an action_plan for each root action from declared action effects. That read-only plan contains ordered steps, dependencies, unresolved targets, and cycles. Its current atomicity is:

mode             single_transaction
on_step_failure  fail_plan
compensation     none_declared

This derived catalog explains same-runtime action propagation. A WorkflowEffect is an effect, but the external workflow execution is not part of that database transaction. The source transaction atomically creates its durable outbox intent.

5. Transaction boundary

The PostgreSQL executor performs the following work in one database transaction:

1. establish the verified security context;
2. consume any required one-time electronic-signature proof;
3. re-evaluate transaction-sensitive rules and invariants;
4. acquire declared locks and apply domain mutations;
5. append entity version or governed-revision history;
6. append entity audit and the action execution ledger;
7. persist failures, results, snapshots, events, and evidence; and
8. append outbox delivery intents and after-commit signal registrations.

External I/O MUST NOT occur inside this transaction. The committed outbox row is the atomic promise that post-commit work exists.

6. Evidence and provenance

SourceRef links a declaration to an SOP, policy, regulation, requirement, change control, template, document, or custom source. Evidence declares proof required from a person, system, instrument, integration, controlled document, artifact, signature, checklist, generated report, or external reference.

ActionEvidenceRecord preserves the captured proof, source, retention ref, object ref, digest, MIME facts, verification state, and time. ActionSnapshotRecord pins policy, master data, configuration, or entity values used by the decision. ActionReplayContext pins the Blueprint revision and durable ordering facts.

Required evidence, signature consumption, mutation, event records, and the execution ledger share the transaction boundary. An action MUST NOT be recorded as successfully committed if required proof failed to persist.

7. Durable workflows

WorkflowEffect, one variant in Action.effects, starts a durable workflow only after the owning action commits. It contains a typed WorkflowRef, typed Blueprint field mappings for workflow input, and an optional correlation field.

The workflow runtime resolves that reference to an immutable registered workflow code and version. The current workflow Blueprint models registered versions, runs, ordered events, commands, user tasks, signals, and typed policy configuration. Registration digest checks prevent a server from running an unknown or mismatched definition.

Blueprint remains the Dart authoring language. A workflow implementation is an execution dependency referenced by the Blueprint; it is not another Blueprint source document.

8. Versioned entities

EntityVersioning has three modes:

• none keeps current state plus ordinary audit history;
• versions appends an immutable snapshot after each successful save; and
• EntityVersioning.revisions(...) adds governed draft, review, effective, superseded, retired, and abandoned business revisions.

Revision actions use the reserved $revision facet and the action names new_revision, submit_revision, publish_revision, and abandon_revision. Revision snapshot storage may be inline JSON, content-addressed, or selected automatically by size policy. The canonical digest and workflow pins remain relational in every mode.

Optimistic expectedVersion validation occurs while the aggregate is locked. A mismatch denies the request before mutation, audit, history, events, or outbox work is committed.

9. Durable record

One ActionRequest produces one ActionRecord. The record groups command, rule, snapshot, domain-event, evidence, effect, integrity, result, and failure records under one replay identity. Durable scope and stream sequences provide authoritative ordering; client timestamps do not.

Idempotent resume returns a prior completed record rather than repeating the business mutation. Effect idempotency separately prevents repeated downstream delivery.

10. Execution conformance example

Given an action with ConsistencyMode.strict, required evidence, one emitted event, and one WorkflowEffect, a conforming executor MUST satisfy all of the following:

1. planning identifies the lock, snapshot, mutation, ledger, event, evidence, and outbox effects without mutating state;
2. preflight returns a denied record when the required evidence is absent;
3. a stale expectedVersion produces no domain mutation or durable success record;
4. successful execution commits the mutation, history, audit, action record, evidence, event, and workflow outbox row atomically;
5. the external workflow does not start until after database commit; and
6. replay identifies the exact Blueprint revision and command that produced the workflow start.

These requirements are exercised by the protocol, compiler, DDL, and PostgreSQL executor tests in the current packages.