Blueprint and Runtime Boundary

The entity blueprint is the declarative surface for regulated software. It describes modules, entities, facets, fields, relationships, actions, rules, conditions, evidence requirements, DB posture, API routes, UI hints, seed hints, and app scaffold intent. It should remain portable: pure Dart definitions, JSON-safe configuration, no Flutter dependency, and no direct storage or server runtime dependency.

Entities are composition boundaries. Facets are behavior boundaries. Every ActionDefinition belongs to a facet; actions that appear entity-wide belong to the identity facet and may be surfaced by generated UI wherever appropriate.

The Vyuh runtime is the enforcement substrate. It owns the machinery that turns blueprint intent into safe execution: authenticated actors, action context, effective policies, audit events, evidence envelopes, exception remedies, function registries, localization registries, telemetry, correlation IDs, storage adapters, and server/client execution hooks.

Package Responsibilities

vyuh_entity_blueprint_types

This package defines the vocabulary. It should contain only portable model types and validators:

• Blueprint, Module, Entity, Facet, Field, Relationship
• facet-scoped ActionDefinition, ActionContext, lifecycle transitions, effects
• RuleDefinition and condition vocabulary for access, policy, lifecycle, data, evidence, audit, snapshot, effect, and custom decisions
• audit and evidence declarations
• DB, UI, API, and seed hints
• code references that point to functions without importing their runtimes

It must not evaluate policies, write audit records, mount routes, connect to Postgres, render Flutter widgets, or call application code.

vyuh_entity_blueprint

This package compiles blueprint declarations into concrete artifacts:

• Postgres/Supabase DDL and physical DB plans
• OpenAPI/API route plans
• Entity System UI plans and generated entity configuration source
• seed-generation plans and app scaffold plans
• validation and diagnostics explaining compromises or missing runtime support

Compilers may understand Vyuh/CDX conventions, but generated artifacts should still flow through the runtime packages that own execution.

Vyuh Runtime/Core

The shared regulated runtime primitives should live below both server and client packages. This layer is larger than Entity System and smaller than an application:

• Actor and identity source
• ActionContext with who, when, why, what, where, tenant/site, session, device, IP, correlation ID, and idempotency key
• policy evaluation contracts and effective policy resolution
• audit event and evidence envelope contracts
• exception and remedy registry contracts
• function/reference registry contracts
• localization, icon, category, and semantic registry contracts
• telemetry and compliance event contracts

Both the server and client should share these model contracts. Server code is authoritative for enforcement; client code uses the same contracts to render accurate affordances and capture complete action context.

vyuh_server and Server Plugins

The server runtime composes plugins and executes regulated actions:

• authentication plugins create verified actors
• policy plugins resolve and evaluate effective policy
• storage plugins write through Postgres/Supabase
• entity CRUD and blueprint runtime plugins mount standard routes
• action routes require action context and re-check policies server-side
• audit/evidence plugins persist immutable action history
• OpenAPI plugins expose the transactional surface

The UI is never trusted as the enforcement boundary. Every mutation must be validated on the server against the effective actor, scope, policy, lifecycle state, evidence requirements, and action context.

For the Postgres runtime, a facet action should become one authoritative database transaction: lock the relevant entity/facet rows, resolve grants and effective policy, evaluate declared action rules, capture required snapshots, write facet state changes, persist action transaction/audit/evidence rows, and enqueue outbox effects for downstream actions, workflows, realtime projections, and analytics.

vyuh_entity_system

Entity System is the interaction layer for entity-shaped software:

• entity configuration and metadata
• entity API clients
• routes, actions, forms, tables, layouts, references, drafts, versioning
• authorization provider integration
• local permission checks for navigation, fields, and actions

It should consume generated configuration and shared runtime contracts. It should not become the home for all regulated runtime concepts.

vyuh_entity_system_ui

Entity System UI renders the compiled UI surface:

• navigation visibility
• field visibility and editability
• action availability
• evidence prompts
• signatures and reason-code prompts
• audit/version/detail views
• authorization fallbacks and redaction

It should be the Flutter-specific edge. Blueprint, IAM, and policy contracts must stay Flutter-free.

Execution Flow

Blueprint definition
  -> validation
  -> DB/API/UI/seed/app compiler artifacts
  -> server plugin registration
  -> client entity configuration registration
  -> user invokes a facet action
  -> client captures ActionContext and evidence
  -> server authenticates Actor
  -> server resolves effective policy
  -> server validates lifecycle, payload, evidence, and permissions
  -> server commits data and audit/evidence records
  -> server emits outbox/effects/subscriptions
  -> client refreshes entity projections and UI state

Rule of Thumb

• If it describes what the regulated system is, put it in Blueprint.
• If it evaluates or enforces a decision, put it in the runtime/server.
• If it renders or interacts with entity data, put it in Entity System/UI.
• If it is app/domain vocabulary, put it in a product module such as CVS, ELog, WMS, IPQC, or BRM.
• If behavior appears entity-level, model it on the identity facet or the facet that owns the transaction's intent.

Near-Term Extraction Targets

The next stable runtime layer should extract these primitives before CVS and ELog grow much further:

1. Shared ActionContext model and serializer.
2. Shared PolicyDecision, PolicyEvaluationRequest, and policy-engine adapter contracts.
3. Shared audit/evidence envelope model.
4. Exception/remedy registry interfaces.
5. Function/reference registry model used by policy evaluators, validators, UI annotations, and seed generation.
6. Server-side policy enforcement adapter for blueprint actions.
7. Client-side authorization bridge from shared decisions into Entity System UI.