Blueprint

Standalone blueprint notes for the vyuh_blueprint repository.

Blueprint is the declarative layer for building regulated, entity-shaped applications in Vyuh. It describes what a manufacturing-grade application is before the DB, API, UI, seed data, or runtime execution surface is generated.

Language And Runtime Invariant

Blueprint is a domain-neutral programming language. A domain Blueprint is a program written in that language, and the common Blueprint runtime is its domain-neutral interpreter. Only the domain program changes between industries and applications. The grammar, protocol, runtime lifecycle, record model, and adapter contracts remain fixed.

The runtime must never branch on industry, application, module, entity, facet, field, relationship, or action names. Domain-specific behavior enters through declarations and versioned registry bindings. See the normative Blueprint Protocol Contract and Execution Replay Contract.

It is designed first for pharma and manufacturing: MES, WMS, LMS, DMS, HRMS, OMS, asset management, cleaning validation, batch manufacturing, quality operations, inventory, transport, and other regulated systems where connected entities, policies, evidence, audit, and impact analysis matter.

Why It Exists

Manufacturing software is not just forms over tables. A change to one master can affect production planning, material planning, cleaning validation, equipment readiness, inventory, protocols, sampling, release decisions, and audit posture.

Blueprint gives Vyuh a common language for that world:

• modules compose applications
• entities represent stable business objects
• descriptors let modules enrich existing entity types
• facets organize state and operational dimensions
• facet actions define transactional behavior
• policies and policy gates govern behavior
• evidence and audit make execution regulated
• projections make facet-owned state usable by DB, API, and UI
• origin graphs explain who contributed what
• compilers produce DB, API, UI, seed, and app surfaces

Core Model

The model is best read as seven vocabulary layers:

Layer	Purpose
Field types	Closed primitive interpretation for codecs, DDL, and validators.
Field tokens	Named typed atoms, semantic field classes, row access, and DB/UI/seed hints.
Structure	Blueprint, module, entity, facet, relationship, lifecycle, projection, descriptors.
Logic brain	FieldPredicate, ActorSet, Condition, Rule, and evaluator refs.
Work and proof	Action, TaskTemplate, Evidence, AuditEnvelope, declared Effect, subscriptions.
Configuration	Policy values, grants, qualifications, bindings, templates, locks, effective resolution.
Runtime effects	Requests, plans, records, database/audit/outbox/realtime/dry-run effects, traces.

Software Surfaces

At the product level, Blue is not just a data model and not just a transaction engine. It is a way to build all operational software surfaces from one declaration, one configuration model, and one execution grammar.

Surface	What it means	Main vocabulary
Master data and model surface	Stable operational objects and the rules for using them. Equipment, materials, areas, documents, users, roles, templates, and other masters are modeled as entities composed from facets. Their lifecycle, declared actions, relationships, workflows, evidence posture, audit posture, and projections define how the master can participate in operations.	Entity, Facet, Field, Relationship, Lifecycle, Action, TaskTemplate, Evidence, AuditEnvelope, Projection
Configuration surface	Scoped choices and witnesses that make the declaration executable in a tenant, site, line, area, product, document type, equipment category, or instance. Some configuration is policy. Some configuration is actual master data that a request depends on.	Policy, PolicyScope, EffectivePolicy, grants, qualifications, templates, bindings, thresholds, locks, source refs, external-system bindings
Transactional surface	Incoming work. A request becomes either a query or a command/action. Commands plan and execute against declared actions, predicates, actor sets, rules, invariants, lifecycle, evidence, and audit, then produce records and effects.	QueryRequest, ActionRequest, ActionCommand, ExecutionPlan, ActionRecord, ActionResult, ActionFailure, Effect
Integration surface	The bridge to instruments, ERP, QMS, DMS, LIMS-adjacent systems, notification channels, file stores, and other external systems. Integrations should enter as requests or leave as effects, not bypass the runtime.	ExternalSystemRef, EvidenceSourceRef, evaluator refs, outbox effects, inbound requests, source bindings, payload mappings
Dashboard, reporting, and analytical surface	Operational visibility built from transactional facts, records, effects, projections, and derived rollups. Dashboards and reports should read the system of record instead of inventing a second truth.	EntityProjection, ActionResult, ActionEffectRecord, audit/evidence records, reports, dashboards, analytics rollups, saved views
Intelligence, readiness, and debug surface	Continuous understanding of whether the system is ready, what a request would do, why a request was denied, what effects were produced, and where agents can safely advise or intervene.	SystemReadinessReport, preflight, simulation, dry-run effects, traces, explain records, subscriptions, realtime signals

The important shape is: master/model surfaces define what exists; configuration decides how it applies in a scope; transactional requests produce records and effects; integrations enter and exit through the same grammar; analytical and intelligence surfaces read those facts.

Planes and flow

Requests enter, logic lights up, effects leave.

Declaration gives the runtime meaning, configuration resolves the scope, and execution turns each request into records and effects.

Software surfaces

One grammar, many surfaces.

Entity constellation

An entity is a center of gravity.

Layer differences

Master, configuration, and transaction are different jobs.

Masters describe stable operational things. Configuration binds scoped decisions and witnesses. Transactions are requests that produce records and effects.

Developer Responsibility

Blueprint developers own the clarity and testability of the declaration. They name the vocabulary, compose fields into facets and entities, declare actions, write the predicates/rules/invariants that make up the domain brain, and bind the scoped configuration needed for a real site or tenant.

They do not reinvent the API server for each action. The common execution plane derives query and action surfaces from the declaration, resolves effective configuration, performs preflight and execution checks, runs invariants, commits records, and emits database, audit, outbox, realtime, and dry-run effects.

Read the Developer Guide for the build and testing workflow, including the equipment/activity walkthrough.

Use the Complete Entity Grammar as the authoritative configuration reference. It inventories every built-in Blueprint, module, entity, facet, field, relationship, lifecycle, action, storage, seed, UI, app-shell, runtime, and extension surface, and distinguishes declared configuration from assembled and runtime-effective values.

Use the Vocabulary Identity and Display Contract when defining protocol metadata or rendering Blueprint vocabulary. It fixes the meaning of schemaType, name, title, and code, and distinguishes semantic identity from projection result shape and collection layout terminology.

Building block	Purpose
Blueprint	Complete application definition.
Module	Package-level boundary for entities, descriptors, policies, DB/UI/seed hints, and exports.
Entity	Stable business type and facet composition boundary such as product, equipment, area, protocol, user, role, or logbook.
EntityDescriptor	Contribution from one module into an entity type owned or exported by another module.
Facet	Operational dimension of an entity. Facets own state, lifecycle, actions, policies, evidence, audit posture, and projection.
FieldType	Sealed primitive interpretation for storage, validation, codec, and DDL generation.
Field	Typed state member with core title/description metadata and DB/UI/seed hints.
FieldPredicate	Boolean algebra over field tokens for payload, state, projection, and rule checks.
ActorSet	Boolean algebra for who may claim, delegate, complete, approve, or execute work.
Relationship	Entity graph connection such as ownership, assignment, containment, usage, or membership. Rich many-to-many membership is modeled as an association entity.
Lifecycle	Facet-owned state machine.
Action	Facet-scoped transaction surface such as create, update, delete, approve, release, sample, calculate, assign, or retire. Standard CRUD actions belong to the identity facet and use the same runtime pipeline as every domain action.
TaskTemplate	Declared workflow work item that always completes through a blueprint action.
Rule	Declared truth checked at availability, beforeCommit, or afterCommit. Shared entity/module/blueprint rules lift onto mutating actions.
Effect	Declared downstream trigger. Runtime lowers work into database, audit, record, outbox, realtime, and dry-run effects.
Actor	Human, system, workflow, simulator, API client, or agent that attempts an action.
RequestContext	Actor, scope, time, reason, device, correlation, and source envelope attached to an action request.
Policy	Configurable governance object at a scope, made of domains, sections, parameters, values, locks, and source.
PolicyScope	Domain-specific address where a policy applies, such as global, tenant, site, module, entity, facet, action, instance, or a richer policy-defined scope.
EffectivePolicy	Runtime-resolved policy for a concrete actor/request/entity scope.
Evidence	Required or captured proof such as signatures, photos, checklists, logs, instrument data, and artifacts.
AuditEnvelope	Regulated audit posture and action history contract.
FacetProjection	Facet-owned projection shape for storage, API, query, and UI use.
EntityProjection	Union of all facet projections for one effective entity.
EntityOriginGraph	Lineage graph for every module contribution and assembled item.

Participants and Runtime Loop

Blueprint has two vocabularies that must stay aligned:

Layer	Concept	Meaning
Declarative	Entity	Core business object and facet composition boundary.
Declarative	Facet	State, lifecycle, rule, evidence, audit, projection, and action owner.
Declarative	Action	What can be attempted on a facet and which rules govern it.
Declarative	Policy	Scoped configurable guardrail made from domains, sections, parameters, values, locks, and source.
Declarative	PolicyScope	Address vocabulary used by policies and resolvers to decide which policies participate in a request.
Declarative	Rule / Condition	Composable truth vocabulary for access, policy, lifecycle, data, evidence, audit, snapshot, effect, and custom checks.
Runtime	Actor	Verified participant initiating work: user, system, workflow, simulator, API client, or agent.
Runtime	EffectivePolicy	Nearest-scope-resolved policy config and trace used by action planning and policy rules.
Runtime	ActionRequest	Incoming intent from an actor. One request can carry or derive many commands.
Runtime	ActionCommand	One executable unit against one entity facet action.
Runtime	ExecutionPlan	Resolved command plan: rules, locks, snapshots, writes, effects, and integrity checks.
Runtime	ActionRecord	Durable truth for the whole request.
Runtime	ActionCommandRecord	Durable truth for one command attempt.
Runtime	ActionFailure	First-class typed failure attached to the action record, command record, rule, condition, or integrity check.
Runtime	ActionResult	Factual output produced by the action record: changed entity state, projection material, evidence, audit facts, reports, dashboards, or domain derivatives.

Whole-System Interaction Map

Some entities can also be actors. For example, iam.user, iam.service_account, or a workflow instance can be represented as entities in the blueprint and can also act as runtime participants. The distinction is the role they are playing in a specific moment: entity is the modeled thing; actor is the verified participant attempting an action.

Policy as First-Class Configuration

Policy is its own vocabulary, not a detail hidden inside rules.

A policy defines configurable guardrails:

• domains: broad governance areas such as usage, cleaning, calibration, release, approval, retention, or training
• sections: named groups inside a domain, such as capacity, approval, evidence, review, timeout, escalation, or lock state
• parameters: typed values that can be configured, such as multi_use, max_concurrent_usages, qa_required, min_reviewers, or expiry_window_days
• scope ladder: an ordered collection of policy scopes; position defines broad-to-specific precedence
• policy scope: a named and titled scope that references an owning entity and one of its fields with typed references; the global scope has neither
• values: the scoped parameter values contributed by that policy
• locks: domain, section, or parameter locks that prevent nearer scopes from overriding protected decisions
• trace: provenance from each contributing policy record, including its id, title, metadata, selected scope, values, locks, and resolution result

Runtime turns matching Policy objects into an EffectivePolicy for the current request scope. The resolver accepts multiple policies with the same id at different PolicyScopes and cascades them in the order declared by that policy's ladder. Nearer scopes override farther scopes unless a broader domain, section, or parameter has been locked. A policy rule such as PolicyAllowsCondition consumes the effective policy decision; it does not define the policy world itself.

Put another way: PolicyScope scopes the whole policy contribution, including its values and locks. The effective-policy trace records each contribution as policy + scope + values + locks + result.

The policy resolver does not decide whether an action is allowed. It only produces EffectivePolicy. Action/rule evaluation consumes that effective policy with the ActionRequest, actor, payload, entity state, and evidence. If custom runtime logic is needed, it belongs to a rule/condition evaluator, not to the policy object itself.

Coverage Lens

This model is intended to be broad enough for operational systems across manufacturing, quality, inventory, documents, training, maintenance, logistics, and other regulated domains because it separates the enduring concerns:

• Entity definition: modules and descriptors assemble core entities from facets, relationships, lifecycle, actions, rules, evidence, audit posture, and projection.
• Policy configuration: policies define configurable guardrails as domains, sections, parameters, scopes, values, locks, and sources.
• Actor participation: actor-capable entities can still be modeled as entities, while runtime requests treat them as verified participants.
• Transactional behavior: actions are the primary executable surface, and requests can expand into one or many commands.
• Decision logic: rules and conditions cover access, policy, lifecycle, data, evidence, audit, snapshot, effect, and custom domain checks.
• Failure and stability: typed failures, integrity records, lineage, and execution limits make failure paths and feedback loops visible instead of hidden in exceptions.
• System of record: action records hold results, failures, audit, evidence, and effects; those facts feed projections, reports, dashboards, documents, PDFs, and downstream derivative work.

The operating loop is:

Actor
  -> ActionRequest
  -> EffectivePolicy resolution
  -> ActionCommand[]
  -> ExecutionPlan
  -> ActionRecord
       -> ActionFailure[]
       -> ActionResult[]
       -> ActionEffectRecord[]
  -> system of record
  -> EntityProjection / reports / dashboards / UI / derivatives

There is usually one successful path and many failure paths. The runtime should record both. A denied request, a failed rule, a constraint violation, a network fault, or a domain exception is still part of the factual history of the attempt. A committed or partially committed action can also produce results, effects, evidence, audit rows, projections, and downstream action requests.

Eventual ActionEffect and WorkflowEffect variants may create new action requests for the same or different entities. Those requests carry causal lineage and execution limits so recursive loops can be denied before they destabilize the system.

Composition Model

The base manufacturing module defines shared entities:

manufacturing.product
manufacturing.equipment
manufacturing.area
manufacturing.material
manufacturing.method

Solution modules contribute descriptors to those same stable types:

cvs -> manufacturing.product
  cleaning profile
  MACO participation
  protocol impact

elog -> manufacturing.equipment
  usage history
  logbook applicability
  execution evidence

After blueprint.bootstrap(), compilers and runtime adapters see one effective entity graph:

manufacturing.equipment
  identity
  tenancy
  governance
  physical profile
  cleaning status
  sampling locations
  usage history
  logbook applicability

Bootstrap is the assembly boundary. Application code should not manually merge descriptors. It should define modules, call bootstrap, and consume the effective graph.

Facets and Entity Projection

Facets own state. They also own projection.

Facets also own behavior. There are no entity-level actions in the blueprint model. Actions that feel global to an entity, such as create, publish, archive, restore, or purge, belong to the identity facet and can still be presented by generated UI in an entity header, toolbar, or command palette.

A facet projection describes:

• field paths exposed by the facet
• storage placement
• read/write behavior
• query behavior for filtering, sorting, search, grouping, and aggregation
• UI behavior for visibility, editability, and generated surfaces

The entity projection is the union of all facet projections. That gives Vyuh a simple client/API state shape while keeping Supabase/Postgres storage normalized and indexable.

Facet state should be one-to-one with the entity instance. A user's profile, authentication metadata, tenancy defaults, governance state, or latest geo snapshot can be facets. A repeatable assignment such as user-group membership, role assignment, or user-site membership should be its own entity when the link has scope, validity, approval, revocation, audit, or lifecycle.

When a relationship stores a foreign key, declare the FK as a ReferenceIdField on the same facet and bind the relationship to that field. The field owns storage; the relationship owns graph semantics.

facet state
  physical_profile.surface_area_cm2
  cleaning_status.current_state
  tenancy.site_id

entity projection
  surface_area_cm2
  current_cleaning_state
  site_id

The UI can still render by facet, section, action, or workflow. The API can also expose a flat shape for search, filtering, sorting, grouping, dashboards, and analytics.

Application Surface

The same Blueprint is the installed product definition. Its application section makes the domain model usable through:

• selected entity modules and descriptors
• workspace navigation
• routes and protocol endpoints
• entity list/detail/editor surfaces
• action placement and confirmation behavior
• inboxes, dashboards, reports, search, settings, demos, and integrations

The Blueprint answers both “what exists and how does it evolve?” and “where do users or agents encounter those capabilities?” There is no second application root object.

For ELog, the proving Blueprint includes IAM users, manufacturing equipment, activities, workflow tasks, operations navigation, inbox surfaces, dashboard surfaces, and facet-owned actions such as execution.start, execution.submit, and task.complete.

Runtime Surfaces

Blueprint has one generated target and two interpreted targets:

Surface	Behavior
Database generation	Produces Postgres schemas, tables, facet tables, association entities, indexes, views, audit/evidence tables, outbox infrastructure, and the runtime schema. RLS, grants, and migration planning remain the next DB-generation layer.
Fixed server runtime	Protocol, entity facade, explorer, and OpenAPI surfaces derive their behavior from the assembled Blueprint at runtime.
Assembled application	BlueprintAssembler derives product surfaces into the same Blueprint; vyuh_blueprint_ui maps them into vyuh_studio_ui, with typed custom bindings where needed.

The runtime schema stores the install and execution spine:

• blueprint_revisions and blueprint_manifests
• entity projections, action capabilities, and app surfaces
• policy artifacts
• query records for projection reads through the protocol
• action requests, commands, execution plans, records, failures, results, and effects

The database generator and runtime surfaces consume effective entities, not raw module definitions. This is what makes CVS, ELog, IAM, and manufacturing descriptors all participate in the same generated surfaces.

Incremental Evolution

The manifest is a compiled runtime contract, not the thing authors edit. Authors change the direct Dart Blueprint program and the Dart declarations it references. Database generation and runtime artifact installation turn that single source into a desired runtime revision.

The local/dev loop should be:

source definitions
  -> compile desired revision
  -> compare with installed revision in vyuh_runtime
  -> produce schema and artifact migration plan
  -> apply safe changes
  -> reload runtime manifest and capabilities

That makes evolution explicit. Adding a projection or action can become an artifact upsert. Adding a field can become a DB migration plus projection updates. Removing or changing a field type becomes a destructive migration that must be reported and approved. The runtime should never blindly regenerate the world; it should install a revision and then diff the next revision against it.

ELog as the Hardening Track

ELog is the first full proving application for Blueprint. It has enough real complexity to stress the vocabulary and compilers:

• IAM, roles, groups, permissions, grants, and scoped assignments
• area/equipment/product/batch masters
• checklist templates and checklist execution
• log templates, log usages, log events, and reports
• resource policies, resource usages, problems, flags, and operational status
• activity lifecycle, assignment, scheduling, submission, review, and evidence
• workflow instances, user tasks, inbox, and audit history
• dashboards, saved views, notifications, search, events, realtime, and analytics rollups

The ELog rebuild is documented as the concrete migration map from the existing application into blueprint modules, entities, facets, actions, policies, DB generation, API generation, UI generation, and runtime execution.

The implementation now lives in the separate Vyrun Pharma Ops repository; Blueprint retains the reusable language, compilers, runtime, server, Studio, and UI adapter packages.

Runtime Boundary

Blueprint describes the regulated system. Runtime enforces it.

The Vyuh runtime and server plugins own:

• authenticated actors
• IAM principals, roles, groups, permissions, grants, assignments, and scopes
• effective policy resolution
• action request planning, preflight, execution, and explanation
• action commands, records, failures, results, and effects
• lifecycle validation
• evidence capture
• audit writes
• exception and remedy handling
• Supabase/Postgres persistence
• realtime events and subscriptions
• telemetry, correlation, and idempotency

The UI is never the enforcement boundary. Blueprint UI interprets declared hints to render accurate affordances, but every mutation is checked again on the server against actor, scope, policy, lifecycle, evidence, and request context.

Regulated Execution

Every action record should answer:

• who attempted it
• when it happened
• why it happened
• what changed
• where and under which scope it happened
• which rules passed or failed
• which failures were produced
• which results became facts in the system of record

This is how Blueprint supports GMP and ALCOA+ expectations: attributable, legible, contemporaneous, original, accurate, complete, consistent, enduring, and available records.

Postgres Execution Direction

Blueprint declarations should compile toward a Postgres-backed execution contract. The runtime should authenticate the actor, resolve effective policy, translate an ActionRequest into one or more ActionCommand values, lock the target entity/facet rows, evaluate action rules, capture snapshots, apply lifecycle/data changes, insert action records, audit/evidence rows, result facts, and enqueue outbox effects inside one database transaction where possible.

Postgres gives the runtime useful enforcement tools: row locks, constraints, foreign keys, generated columns, RLS, security-definer or security-invoker functions, immutable audit tables, materialized projections, outbox tables, and idempotency keys. Blueprint describes the contract; runtime and compiler packages turn it into those database surfaces.

Documentation

The package reference lives in:

• docs/packages/vyuh_entity_blueprint_types/entity-blueprint.md
• docs/packages/vyuh_entity_blueprint_types/entity-descriptors.md
• docs/packages/vyuh_entity_blueprint/blueprint-runtime-boundary.md

Those files go deeper into the full object model, descriptor assembly, origin graph, storage projection, and runtime boundary.