Blueprint Protocol Contract

This specification defines the stable instruction set between a domain Blueprint and every Blueprint runtime implementation. The grammar, protocol, and runtime are domain-neutral. Only the domain program changes between industries, applications, and customers.

Normative words MUST, MUST NOT, SHOULD, and MAY have their usual specification meanings.

Architectural Invariant

Blueprint grammar (language)
  -> domain Blueprint (program)
  -> EffectiveBlueprint (linked program)
  -> Blueprint protocol (instruction set)
  -> Blueprint runtime (interpreter)
  -> storage, workflow, evidence, event, notification, and UI adapters

The grammar and runtime MUST NOT branch on industry, application, module, entity, facet, field, relationship, or action names. Domain behavior enters through declarations and versioned registry bindings. A new industry MUST be deployable by supplying a different Blueprint program without modifying the protocol or runtime packages.

Stable Protocol Surface

The protocol has two executable operation families:

1. BlueprintQueryRequest reads a named projection with the shared query AST and produces a QueryRecord.
2. ActionRequest carries one or more ordinary facet actions and produces an ActionRecord.

All transports MUST preserve these operation and record semantics. HTTP, in-process execution, workflow integration, simulation, agents, and other message transports are adapters over the same protocol rather than separate business APIs.

The fixed HTTP control surface is:

GET  /manifest
GET  /health
POST /capabilities
POST /query
POST /actions/plan
POST /actions/preflight
POST /actions/execute
GET  /actions/records/:recordId/explain

Entity-friendly facade routes MAY provide shorter paths, but they MUST lower to the same query and action requests and MUST produce the same records.

Discovery And Capabilities

manifest publishes the effective Blueprint revision, modules, entities, projections, query capabilities, and action catalog. capabilities resolves the subset available for one verified actor and scope. Clients MUST discover the domain through these contracts and MUST NOT hard-code domain types in the shared runtime or UI engines.

Query Contract

A query MUST identify an effective entity, a named projection, request context, and a typed shared query AST. Before lowering the AST to storage, the runtime MUST verify that every selected, searched, filtered, grouped, and sorted field is exposed by the projection and has a valid storage or derived binding. Unknown or non-queryable fields MUST be rejected before adapter SQL is executed.

Query results MUST preserve projection field labels, types, semantic hints, reference targets, enum choices, formatting metadata, pagination, and total count information needed by generic clients.

Action Contract

Every mutation is an ordinary Action owned by a facet. create, update, and delete are standard actions owned by the entity's identity facet. They MUST use the same payload validation, authorization, policy, evidence, invariant, plan, transaction, result, error, audit, and replay contracts as domain actions. An entity-level alias MAY be accepted at a transport edge, but the runtime MUST normalize it to the actual identity facet before capability resolution, planning, execution, or recording.

Facet-centric actions remain owned by their declaring facet. The effective action catalog is the union of standard identity actions and actions contributed by every effective facet.

An ActionRequest carries source, actor and scope context, causal lineage, idempotency/resume policy, execution budgets, and one or more commands. A command identifies module.entity.facet.action, an optional entity id, and a typed payload.

Plan, Preflight, Execute, Explain

The runtime MUST expose one common lifecycle:

1. Plan resolves effective declarations and configuration into commands, policies, rules, locks, snapshots, invariants, writes, evidence, events, workflow work, effects, and cache invalidations without mutation.
2. Preflight validates payloads, references, access, policy, lifecycle, evidence readiness, invariants, conflicts, and adapter capabilities without committing domain writes.
3. Execute revalidates transaction-sensitive decisions, acquires declared locks, captures snapshots, applies writes, records versions and evidence, emits domain events and outbox work, persists the action journal, and commits atomically where declared.
4. Explain reconstructs why a plan or record was allowed, denied, failed, partially committed, or committed.

Clients MUST NOT bypass this lifecycle with entity-specific CRUD endpoints or direct writes.

Results, Evidence, Events, And Effects

ActionResult records facts produced by execution. ActionEvidenceRecord records proof captured for declared evidence requirements. ActionDomainEventRecord records domain facts without requiring the runtime to import domain classes. ActionEffectRecord records downstream delivery work and its attempts.

Database writes, versions, the action journal, required evidence manifests, domain events, and transactional outbox rows MUST obey the atomicity declared by the action plan. External I/O MUST occur through idempotent post-commit dispatch and MUST be traceable back to the originating request and command.

The complete post-hoc requirements are defined by the Execution Replay Contract.

Errors And Remedies

Protocol failures MUST be machine-readable. A failure envelope carries a stable code, kind, severity or HTTP status, safe message, retryability, recoverability, contextual details, metadata, and zero or more typed remedies. The common taxonomy includes validation, access, policy, conflict, constraint, integrity, not-found, evidence, network, timeout, adapter, system, and domain failures.

Adapters MUST translate native errors into this vocabulary and MUST NOT leak raw SQL, credentials, stack traces, or infrastructure internals to clients. Field and action validation failures SHOULD identify the failing declaration token so a generic client can focus the correct control and present a remedy.

The declaration source of truth is the module error/remedy catalog described in Errors and Remedies. Servers MUST log the original exception and stack trace with an error_id; clients receive the safe structured error, details, remedies, and correlation identifiers. Raw stack traces MUST remain server-side in production.

Relationships, Caching, And Invalidation

The Effective Blueprint relationship graph is compiled once into a dependency and invalidation index. An entity action announces only its own committed mutation. The cache layer derives affected entity projections, references, collections, counts, and cross-module dependants from that index. Domain actions MUST NOT hard-code lists of caches to clear.

Effect Integration

Effects are the single structural boundary for work that follows an action's committed facts. Every effect uses the same protocol shape: a stable effect kind or adapter reference, target, payload, delivery semantics, idempotency key, causation and correlation identifiers, execution status, attempts, and result or failure. The runtime MUST plan, record, dispatch, retry, and reconcile effects without adding branches for particular domains or technologies.

Workflow commands, notifications, object-storage operations, realtime publication, external integrations, cache signals, and downstream actions are examples of effect adapters. None is a privileged runtime primitive. A workflow adapter may interpret an effect as start, signal, complete, or cancel, but the Blueprint action runtime only sees an effect declaration and its durable outcome. Any work returning from an adapter enters through the same ordinary action protocol.

Adapter Conformance

Storage, policy, identity, evidence, and effect implementations are adapters. Specialized effect handlers such as workflow, notification, realtime, and object storage remain adapters behind that same boundary. An adapter MUST publish its capabilities and pass the shared protocol conformance suite. Unsupported capabilities MUST fail during validation, readiness, or preflight rather than silently degrading execution semantics.

The definitive portability test is to replace the domain Blueprint with an unrelated industry program and run the same discovery, query, action, error, replay, caching, and adapter tests without changing the runtime.