Entity Blueprint

Standalone blueprint notes for the vyuh_blueprint repository.

Entity 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.

It is designed for domains such as CVS, ELog, WMS, IPQC, BRM, 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.

Entity 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

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.
Field	Typed state member with core title/description metadata and DB/UI/seed hints.
Relationship	Entity graph connection such as ownership, assignment, containment, usage, or many-to-many membership.
Lifecycle	Facet-owned state machine.
ActionDefinition	Facet-scoped invokable transaction such as approve, release, sample, calculate, assign, or retire.
ActionContext	Who, when, why, what, and where envelope captured for every action.
Policy	Configurable strategy that governs behavior.
PolicyGate	Named decision computed from policy, state, actor, scope, and context.
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 state shape for storage, API, query, and UI use.
EntityStateProjection	Union of all facet projections for one effective entity.
EntityOriginGraph	Lineage graph for every module contribution and assembled item.

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 State 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
  physical_profile.surface_area_cm2
  cleaning_status.current_state
  tenancy.site_id

entity state 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.

Compiler Surfaces

Entity Blueprint is consumed by compilers:

Compiler	Generates
DB compiler	Supabase/Postgres schemas, tables, facet tables, join tables, RLS, indexes, triggers, views, audit/evidence tables, outbox plans.
API compiler	ActionDefinition endpoints, CRUD routes, payload schemas, OpenAPI, policy checkpoints, error contracts.
UI compiler	Entity System configuration, route builders, forms, tables, actions, evidence prompts, signatures, reason prompts, access fallbacks.
Seed compiler	Smoke, demo, validation, and load seed plans for SQL, JSON, API fixtures, or AI-generated data.
App compiler	Vyuh app scaffold with feature registration, plugins, routes, auth, entity browsing, workflow views, and audit views.

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

ELog as the Hardening Track

ELog is the first full proving application for Entity 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.

Open the ELog rebuild map

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
• facet action execution
• 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. Entity System UI uses generated hints to render accurate affordances, but every mutation is checked again on the server against actor, scope, policy, lifecycle, evidence, and action context.

Regulated Execution

Every facet action should answer:

• who performed it
• when it happened
• why it happened
• what changed
• where and under which scope it happened

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, lock the target entity/facet rows, evaluate action rules, capture snapshots, apply lifecycle/data changes, insert action transaction/audit/evidence rows, and enqueue outbox effects inside one database transaction.

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.