Blueprint Server

vyuh_blueprint_server hosts and executes Blueprints through vyuh_server.

It provides:

• entityFeature(...) for registering a blueprint module as a server feature
• BlueprintProtocolsConfig for configuring protocol identity, the active blueprint list, base path, persistence schemas, policy evaluators, protected paths, and standard Vyuh plugin dependencies
• BlueprintServerRuntime for accessing the composed blueprint, trigger executor, outbox dispatcher, protocol route module, and entity facade route module
• RuntimeArtifactInstaller for installing compiled app/runtime artifacts into the runtime schema in one database transaction
• BlueprintProtocolDbExecutor for executing protocol query/action requests against the database while writing a durable protocol ledger
• BlueprintProtocolRouteModule for exposing the server-side runtime protocol through vyuh_server
• BlueprintEntityFacadeRouteModule for exposing entity-shaped query/action routes and blueprint-derived OpenAPI
• BlueprintExplorerRouteModule for developer exploration of modules, entities, prominence counts, descriptor sources, projections, origin graphs, and ordered action plans
• server adapter wiring for database, query, policy, auth, telemetry, and route integration

This package is integration glue. The executable runtime contracts live in vyuh_blueprint_server.

Protocol Configuration

The protocols are configured as data first, then mounted as a Vyuh feature:

final config = BlueprintProtocolsConfig(
  blueprints: [blueprint],
  name: 'elog.blueprint.protocol',
  basePath: '/elog',
  persistence: const BlueprintPersistenceConfig(
    runtimeSchema: 'elog_app_runtime',
    outboxSchema: 'elog_app_runtime',
  ),
  protectedPaths: const ['/elog/actions'],
);

final runtime = await VyuhServer.bootstrap(
  name: config.name,
  plugins: [dbPlugin],
  features: [blueprintProtocolsFeature(config)],
);

blueprintProtocolsFeature(config) creates the BlueprintProtocolDbExecutor from vyuh.db, uses the configured runtime schema for the protocol ledger, uses the configured outbox schema for entity effects, and mounts both protocol entity facade routes, and developer explorer routes at the same base path.

The server is generic across blueprint sets. Supabase is the ELog sample's local Postgres host, not a special runtime dependency. Any host can provide the same persistence surface through the standard vyuh_server database plugin and DbAdapter.

Runtime Artifact Boundary

The app compiler emits runtime artifacts: blueprint revisions, manifests, entity projections, action capabilities, app surfaces, and policy artifacts. The server installer does not reinterpret those artifacts. It emits the compiler-owned install SQL and applies every statement in one DbAdapter transaction against the runtime schema, defaulting to vyuh_runtime.

This keeps schema evolution incremental: the compiler can generate a new artifact set for a blueprint revision, while the server owns the operational installation boundary.

Protocol Routes

BlueprintProtocolRouteModule mounts the API vocabulary used by UI surfaces, agents, simulators, and workflows through vyuh_server.RouteModule. Its default base path is /api; hosts can choose another base path such as /elog for local previews.

Route	Purpose
GET /api/manifest	Return the installed effective blueprint manifest.
POST /api/capabilities	Return actor/context-aware capabilities and effective policies.
POST /api/query	Execute a BlueprintQueryRequest for a named projection and return a durable QueryRecord.
POST /api/actions/plan	Resolve an ActionRequest into an ExecutionPlan.
POST /api/actions/preflight	Evaluate the request without committing.
POST /api/actions/execute	Execute the request and return an ActionRecord.
GET /api/actions/records/:id/explain	Return the stored execution explanation for an action record.

The route module is transport-thin. Runtime decisions stay inside BlueprintRuntime; database, auth, policy, telemetry, and outbox adapters stay owned by the server layer and are mounted through the Vyuh server lifecycle.

Entity Facade Routes

BlueprintEntityFacadeRouteModule is the entity-friendly view of the same protocol. It accepts route context in the URL, translates the request into BlueprintQueryRequest or ActionRequest, and delegates to the same runtime executor. It does not introduce separate business logic.

Route	Purpose
POST /api/:module/:entity/query/:projection	Execute a named entity projection query.
POST /api/:module/:entity/:id/:facet/:action/plan	Plan one entity action.
POST /api/:module/:entity/:id/:facet/:action/preflight	Evaluate one entity action without committing.
POST /api/:module/:entity/:id/:facet/:action/execute	Execute one entity action.
GET /api/openapi.json	Return the generated OpenAPI contract for protocol and entity facade routes.

blueprintFeature(...) mounts the protocol route module, entity facade route module, and developer explorer route module by default.

Developer Explorer Routes

BlueprintExplorerRouteModule is the read-only developer view of the effective blueprint. It is meant for local tooling, OpenAPI exploration, entity-system debugging, and origin-graph inspection before execution-readiness checks become stricter.

Route	Purpose
GET /api/explorer	Explore modules, entities, prominence counts, action counts, and the full origin graph.
GET /api/explorer/origin-graph	Return the blueprint origin graph as nodes and edges.
GET /api/explorer/actions	Return actions, declared effects, and ordered action plans for action-thread exploration.
GET /api/explorer/entities/:entityType	Inspect one effective entity summary.
GET /api/explorer/entities/:entityType/explosion	Explode one entity into facets, fields, relationships, actions, projections, descriptor sources, and origin graph.

GET /api/openapi.json includes these explorer endpoints alongside the protocol and entity facade routes so tooling can discover the whole server surface from one document.

Action Plans

The effective blueprint is the source of truth for the developer catalog. Entities own facets, facets own actions, and actions own payload fields, rules, capture requirements, emitted records, and follow-up effects. The explorer flattens that declaration into three collections:

• actions: qualified action names, owning entity/facet, rules, payload fields, consistency, capture contract, and effect counts
• effects: source action, target entity/facet/trigger, payload mapping, optional target id path, and consistency override
• action_plans: ordered execution plans whose steps reference catalog actions, whose dependencies reference catalog effects, and whose atomicity declares that one failed step fails the whole plan

The catalog is reference data. The plan is the execution unit. This keeps ordering and failure semantics in one place instead of spreading dependency meaning across individual actions.

Developers add application behavior by implementing action/effect handlers, policy evaluators, and integration adapters against the shared runtime contracts. The protocol routes, entity facade, OpenAPI document, runtime ledger, and explorer stay common for every blueprint-backed application.

Protocol DB Execution

BlueprintProtocolDbExecutor is the server-side database executor for the runtime protocol. It consumes BlueprintQueryRequest, ActionRequest, and ActionCommand values. Queries are executed through DbAdapter.from(...).applyQuery(...).read() so the shared cdx_query expression remains the protocol query grammar. Actions delegate planning and rule evaluation to the configured BlueprintRuntime, apply executable database locks/writes, and record each execution into the runtime schema:

• query_records: incoming query request, actor context, named projection, serialized Vyuh Query expression, and typed ProjectionResult
• action_requests: incoming ActionRequest, actor context, lineage, limits, command list, and request idempotency key
• action_commands: command-level module/entity/facet/action, payload, entity id, status, and command idempotency key
• execution_plans: resolved ExecutionPlan
• action_records: durable ActionRecord
• action_failures: typed failures
• action_results: factual outputs that can feed projections, dashboards, reports, documents, and UI refreshes
• action_effects: outbox/workflow/realtime effects that can produce bounded follow-up action requests

The executor stores the protocol ledger in one DB transaction. If a resume request supplies an idempotency key, it looks for an existing completed action record and returns it instead of executing the action again.

The dry-run path consumes the same query/request/command stream and produces the same plan and record shapes with effects marked as non-applying.