16. System Readiness and Production Patterns

A valid Blueprint is necessary but not sufficient. The database artifacts must compile, required tables and subscriptions must be installed, delivery must be attached, and every declared client extension must have the expected binding.

The current platform exposes each of those checks rather than hiding them behind a generic “healthy” flag.

The readiness, compiler, database inspection, and Explorer APIs are exported by package:vyuh_blueprint_server/vyuh_blueprint_server.dart.

Evaluate whole-system readiness

final report = await SystemReadinessReport.evaluate(
  blueprint: blueprint,
  database: database,
  deliveryWorkerConfigured: true,
);

print(report.status);   // ready, degraded, or blocked
print(report.checks);
for (final finding in report.findings) {
  print('${finding.area}: ${finding.message}');
  print(finding.remedy);
}

The report performs the supported checks in one call:

1. BlueprintValidator.validate for declaration errors;
2. DbCompiler.compile for database diagnostics;
3. declared subscription count versus generated installation rows;
4. generated table inventory through DatabaseInspection;
5. installed-table probes with to_regclass when a DbAdapter is supplied;
6. delivery-worker attachment.

A blocking finding produces blocked. Non-blocking findings produce degraded. No findings produces ready.

Expose the same facts through the Explorer

final explorer = BlueprintExplorerRouteModule(
  blueprint: blueprint,
  database: database,
  deliveryWorkerConfigured: true,
  protectedPaths: const ['/explorer'],
);

GET /api/explorer returns:

• the effective Blueprint and module/entity summaries;
• the origin graph;
• exact generated database inspection JSON;
• system_readiness checks and findings.

Entity, explosion, action-catalog, and origin-graph routes use the same effective Blueprint. Protect developer routes in deployed environments using the host authentication module.

Render database inspection through the owning layers

The ownership chain is deliberate:

DatabaseInspection JSON
  -> BlueprintDatabaseInspector adapter
  -> DatabaseSchemaManifest
  -> vyuh_studio_ui DatabaseSchemaView
  -> CDX controls and tokens

Blueprint UI translates Blueprint/server JSON. Studio owns the generic schema browser. CDX owns visual mechanics. A product app does not create its own table, trigger, or SQL inspector.

Audit client extension bindings

ClientUIBindings is resolved by both kind and ref. DevTools classifies the result:

Classification	Meaning
Bound	the declaration and same-kind implementation both exist
Violation (Unbound)	a declared ref has no implementation
Drift	a binding exists without the matching declaration or under another kind

Unbound render sites show a deterministic placeholder. The diagnostic report keeps forms, detail tabs, routes, dashboard widgets, and field editors separate, so one ref cannot accidentally satisfy the wrong extension kind.

Inspect effective policy instead of client guesses

The effective-policy surface presents the value selected at the active scope and the contributing policy chain. Action availability, collection visibility, editor writability, and server execution all consume server-resolved access and policy results. Client hints select hide, disable, redact, placeholder, or read-only presentation; they are never the authorization authority.

Use a layered verification gate

Gate	Supported proof
Declaration	validator returns no errors
Assembly	descriptor refs resolve and origin graph is deterministic
Build	DB compiler produces DDL/runtime DDL and database inspection
Installed DB	generated tables exist and migrations/policies pass focused integration tests
Protocol	manifest, query, plan, preflight, execute, and explain use typed records
Authentication	provider discovery, session policy, actor resolution, and protected routes fail closed
Authorization	qualified product actions evaluate with effective scope on the server
Client	Studio renders generated and bound surfaces; binding drift is empty
Delivery	subscription installation matches declarations and the outbox worker is attached
Evidence	required evidence/signature checks block commit and persist their records

Production pattern: one vertical slice

For each important capability, prove one dependency-aware vertical slice:

1. declare the field, entity, action, access, audit, and UI intent;
2. compile and inspect the physical artifacts;
3. install the generated schema and policies;
4. authenticate and resolve the product actor;
5. create, query, update/action, and reread through the protocol;
6. inspect action, evidence, event, audit, and effect records;
7. verify the Studio collection/editor/detail surfaces;
8. clean up in reverse dependency order;
9. require a non-blocked SystemReadinessReport for that environment.

This is the advanced Blueprint pattern: one declaration remains traceable through storage, protocol, policy, UI, execution records, and operations.

Final checkpoint

The tutorial system is complete when you can answer with evidence:

• What is declared, and which package owns each interpreter?
• What exact SQL and runtime tables are generated?
• Which tables, subscriptions, and delivery workers are installed?
• Which provider authenticated the identity, and which product principal acted?
• Which effective grants and policy values enabled or denied the action?
• Which revision, snapshots, evidence, events, and effects were recorded?
• Which client refs are bound, unbound, or drifting?
• Can the same action be explained from its durable record without consulting transient UI state?

Return to the tutorial index or use the coverage matrix as a retrieval map.

References: Three Planes · Server Runtime · Blueprint UI.