Developer Guide

This is the working contract for a developer creating Vyuh blueprints.

Developers author the declaration, bind the configuration, and prove the contract through tests. The common runtime owns query/action endpoints, transaction planning, rule and invariant evaluation, records, audit, outbox, realtime signals, dry runs, and traces.

The blueprint should describe what the system means. The execution plane should interpret that description the same way for masters, transactions, workflows, agents, simulations, dashboards, and operational software.

Responsibility Boundary

Area	Developer owns	Runtime owns
Vocabulary	Names, field tokens, semantic field classes, entity/facet/action names, policy domains, rule ids, refs.	Exhaustive interpretation of field types, row codecs, validators, route catalogs, and generated metadata.
Declaration	Modules, entities, facets, relationships, lifecycle, projections, actions, payloads, predicates, actor sets, rules, invariants, evidence, audit posture, declared effects.	Descriptor merge, origin graph, declaration validation, route exposure, action/query planning, common lifecycle and effect interpretation.
Configuration	Site/tenant policy values, grants, qualifications, template bindings, evidence source bindings, external-system bindings, thresholds, locks.	Effective resolution for a concrete actor/request/scope, readiness reports, explain traces, and configuration drift detection.
Execution	Test scenarios, fixtures, expected denials, expected effects, simulation assertions, business acceptance.	Preflight, execute, transaction envelope, pre-action checks, post-action checks, invariant phases, commit, staged effects, records, audit, outbox, realtime, dry-run traces.
Operations	Monitoring expectations, readiness gates, dashboards, exception paths, rollout playbooks.	Shared DevTools traces, action records, effect records, subscription streams, query endpoints, and runtime telemetry.

Developers should not create private mini API servers for each domain action. They should also avoid hidden DDL, hidden audit writes, UI-only business logic, and ad hoc transaction handlers. If the behavior matters, it belongs in the blueprint or configuration, and the runtime should execute it.

Three-Plane Contract

Plane	Developer question	Primary artifacts
Declaration	What can exist, what can be attempted, and what must always be true?	Field types, field tokens, entities, facets, relationships, lifecycle, actions, predicates, actor sets, rules, invariants, evidence, audit, declared effects.
Configuration	Which scoped values and witnesses make this declaration executable here?	Policy values, grants, qualifications, templates, bindings, source refs, locks, thresholds, external systems.
Execution + intelligence	What happened, why did it happen, and what effects came out?	Query requests, action requests, plans, preflight, execute, simulate, records, database effects, audit effects, outbox effects, realtime effects, traces.

The API server is derived from this contract. It exposes the query and action surfaces, resolves effective configuration, executes transactions, checks invariants, and emits effects. Subscriptions and realtime connections are also effect surfaces: they observe committed records and outbox/realtime effects.

Surfaces To Account For

When building a blueprint, make sure the declaration and tests cover each software surface:

Surface	Developer responsibility
Master data and model	Declare stable entities, facets, fields, relationships, lifecycle, actions, workflow/task templates, evidence, audit, and projections.
Configuration	Bind policy values, grants, qualifications, templates, thresholds, locks, source refs, external-system refs, and required master-data witnesses.
Transactions	Prove that requests become queries or commands, commands produce plans, and plans produce records, failures, results, and effects.
Integrations	Route inbound external data as requests and outbound external work as declared effects or outbox records.
Dashboards and analytics	Build dashboards, reports, saved views, and analytics from projections, records, effects, audit, and transactional facts.
Intelligence and debug	Cover readiness, preflight, simulation, explain traces, realtime subscriptions, and agent-safe interventions.

Build In Seven Layers

Layer	Developer responsibility	Test responsibility
1. Field types	Use the closed primitive interpretation. Add a field type only when codecs, DDL, validators, and UI hints all need a new primitive.	Decode/encode, DDL mapping, nullability, enum collision, numeric precision.
2. Field tokens	Define reusable typed atoms such as code, name, status, identifier, quantity, money, file, related, and reference fields. Keep behavior out of fields.	Row access, default expressions, generated identifiers, companion units/currencies, related-field chains.
3. Structure	Compose modules, entities, facets, relationships, lifecycle, projections, and descriptors.	Descriptor merge, origin graph, relationship closure, lifecycle determinism, projection shape.
4. Logic brain	Compose FieldPredicate, ActorSet, Condition, Rule, Invariant, and evaluator refs. This is where the domain brain lives.	Truth tables, actor eligibility, rule phase/severity, invariant pre/post behavior, evaluator registry failures.
5. Work and proof	Declare actions, payloads, task templates, evidence, audit envelopes, subscriptions, and possible effects.	Action catalog, payload mapping, evidence requirements, task completion path, effect declaration closure.
6. Configuration	Bind policy values, grants, qualifications, templates, evidence sources, external systems, thresholds, and locks at the right scope.	Effective resolution, missing witnesses, override/lock behavior, readiness drift, scope-specific fixtures.
7. Runtime effects	Assert what requests should produce: records, database writes, audit writes, outbox events, realtime signals, dry-run traces, dashboards, and reports.	Plan, preflight, simulate, execute, rollback, idempotency, post-commit effects, subscription delivery.

Readiness is not a second brain. It is a continuous monitor over layers 1 to 6 for a concrete scope. It answers: "Can the declared system execute here, now, with the available policy, grants, templates, sources, actors, and bindings?"

Blueprint Build Workflow

1. Name the domain in operational language.
2. Define or reuse field tokens before inventing new structures.
3. Compose modules, entities, facets, relationships, lifecycle, and projections.
4. Declare actions and their payloads.
5. Compose the logic brain with predicates, actor sets, rules, and invariants.
6. Declare work and proof: task templates, evidence, audit posture, effects, and subscriptions.
7. Bind configuration for a target scope: policies, grants, qualifications, templates, source bindings, external systems, thresholds, and locks.
8. Run static declaration validation and inspect the origin graph.
9. Run scope readiness for at least one real site/tenant fixture.
10. Run plan, preflight, simulate, execute, and subscription/effect tests.

The workflow should feel boring in a good way: declare, configure, validate, simulate, execute, observe.

Equipment And Activity Walkthrough

The equipment/activity example is the reference shape for a complex master plus a transactional entity.

Equipment Master

Equipment is a stable, versioned master. The developer declares identity, tenancy, governance, physical profile, relationships to area/line/room, document links, lifecycle, actions such as activate/retire/update profile, and invariants such as "active equipment must have a valid area and profile".

The runtime does not need a special equipment server. It receives an action request, resolves policy and actor eligibility, checks rules and invariants, stages writes, commits, and emits records/effects.

Activity Transaction

Activity is performed work against equipment. The developer declares the activity entity, relationship to equipment, lifecycle, actions such as create, start, complete, review, reject, and void, payload fields, evidence, actor sets, predicates, rules, invariants, and effects.

The activity may produce a business row, an ActionRecord, audit rows, evidence records, outbox events, realtime signals, projection updates, dashboards, and analytics. In dry run, the same plan emits would-apply effects instead of committing writes.

Testing Responsibilities

Test layer	What to prove
Static declaration tests	BlueprintValidator.validate reports no closure errors, bad refs, invalid lifecycle transitions, invalid related fields, invalid identifier masks, or effect payload mismatches.
Vocabulary tests	Field codecs, row access, enum identities, generated identifiers, measured field companions, related fields, file shapes, semantic token defaults.
Logic tests	FieldPredicate truth tables, ActorSet eligibility, Condition composition, rule phase/severity, pre-action invariants, post-action invariants, evaluator registry errors.
Configuration tests	Policy resolution, grant and qualification availability, template refs, evidence source refs, external system refs, locks, source-specific overrides.
Readiness tests	Missing configuration is reported before execution, with scope, dependency, severity, and suggested remediation.
Runtime plan tests	Preflight explains allow/deny, required evidence, planned writes, planned effects, locks, snapshots, and integrity checks.
Simulation tests	Dry run produces the same plan and ordered would-apply effects without database commit.
Execution tests	Successful actions commit records and effects; failing actions return typed failures and do not leak partial writes.
Realtime/effect tests	Database, audit, outbox, realtime, analytics, dashboard, and report effects are emitted from the common effect pipeline.
Replay conformance tests	Records pin declaration and effective configuration, required evidence/events commit atomically, ordering is deterministic, reconstruction matches projection hashes, and isolated replay performs no external I/O.
UI/docs tests	Generated catalogs, route manifests, example pages, screenshots, and docs stay aligned with vocabulary changes.

Invariant Phases

Use invariants at the phase where they protect the system best:

Phase	Purpose
Before action planning	Reject impossible requests early, before expensive resolution.
Before commit	Check the candidate transaction against current state, actor, payload, policy, and staged writes.
After commit	Watch committed facts, derived projections, external effects, and deferred consistency.
Async watcher	Detect drift, late external failures, SLA misses, and cross-entity inconsistencies.

Post-action invariants should usually run before commit against the candidate state. After-commit watchers are for facts that only exist after the transaction is durable or after an external effect returns.

What Not To Do

• Do not build one-off API endpoints for domain actions when the declaration can expose an action.
• Do not put access rules, evidence rules, or lifecycle rules only in UI code.
• Do not bypass ActionRecord, audit, outbox, or realtime effect records.
• Do not make fields carry domain behavior. Fields are atoms; predicates and rules compose behavior.
• Do not call external systems directly from ad hoc handlers. Declare the external system and lower it through effects.
• Do not treat readiness as authorization. Readiness proves the scope can run; rules decide whether a request may run.

Before You Ship

• Vocabulary changes are reflected in the vocabulary reference.
• Equipment/activity examples still map cleanly to the seven layers.
• New refs are declared, validated, and included in readiness output.
• Preflight, simulation, and execution tests cover both allow and deny paths.
• Database, audit, outbox, realtime, dry-run, and trace effects are asserted.
• Developer docs describe what the blueprint author must own.
• Runtime docs describe what the common execution plane owns.
• The action satisfies the Execution Replay Contract for its declared replay horizon.