Blueprint Language Specification

This specification defines the Blueprint language implemented by the current Vyuh Blueprint packages. Blueprint is an internal DSL embedded directly in Dart. A Blueprint program is a Dart object graph built from constructors such as Blueprint, Module, Entity, Facet, Field, Action, and Relationship.

The Dart program is the only authoring source. Canonical JSON documents, runtime manifests, SQL, protocol records, and UI models are derived artifacts. They are not alternate authoring languages and are not edited in place.

Normative words MUST, MUST NOT, SHOULD, and MAY describe requirements already enforced or consumed by the implementation.

Language pipeline

Dart Blueprint program
  -> BlueprintValidator
  -> Blueprint.bootstrap() -> EffectiveBlueprint
  -> BlueprintDefinitionDocument.capture()
  -> compiler and runtime artifacts derived from the declaration and effective graph
  -> query and action protocol

The boundaries have different jobs:

Boundary	Meaning	Current owner
Authoring model	Dart constructors, typed field tokens, references, declarations, and validation	vyuh_blueprint
Linked model	Descriptor contributions merged into effective entities with origin information	vyuh_blueprint
Canonical definition	Deterministic, JSON-safe definition snapshot and reference index	vyuh_blueprint
Compilation and execution	Database artifacts, plans, preflight, transactions, history, and outbox	vyuh_blueprint_server
Operation records	Query, action, evidence, event, effect, replay, and simulation envelopes	vyuh_blueprint_protocol
Durable workflow model	Registered workflow versions, runs, commands, tasks, signals, and policy entities	vyuh_workflow_blueprint

Specification documents

• Core language defines the abstract syntax, Dart concrete form, name and reference rules, static validation, diagnostics, canonical serialization, compatibility, and core conformance examples.
• Execution semantics defines actions, requests, transaction boundaries, derived atomic plans, evidence and provenance, durable workflow starts, versioned entities, projections, and execution conformance examples.

The Protocol Contract and Execution Replay Contract remain the normative transport and durable-record companions to this language specification.

Conformance

A conforming Blueprint program:

1. is authored as Dart objects using the exported Blueprint APIs;
2. passes BlueprintValidator.validate without errors;
3. bootstraps to one deterministic EffectiveBlueprint;
4. captures as vyuh.blueprint.definition/v2 without losing semantic references;
5. produces plans and protocol records whose identities remain bound to the effective Blueprint revision; and
6. does not require annotations, generated authoring classes, a build step, or an external configuration document to express the program.

A runtime is conforming when it preserves the declared query, action, transaction, evidence, history, outbox, and replay semantics. A renderer is conforming when it consumes the effective declarations and server-resolved capabilities without creating a second domain model.