14. Governed Revisions and Database Inspection

An operational lifecycle and a document-style revision lifecycle answer different questions:

• an entity facet lifecycle asks whether the record is active, retired, approved, or otherwise operational;
• entity versioning asks which immutable save or governed revision represents the record at a point in time.

Blueprint keeps both declarations on the entity without inventing a separate master-control object.

Entity declarations come from vyuh_blueprint; DbCompiler and DatabaseInspection come from package:vyuh_blueprint_server/vyuh_blueprint_server.dart.

Choose one history posture

const noHistory = EntityVersioning.none;
const saveHistory = EntityVersioning.versions;

const governed = EntityVersioning.revisions(
  initialStatus: RevisionStatus.draft,
  requireReview: true,
  allowParallelDrafts: false,
  ownedRelationshipRefs: ['documents.attachments'],
  createAudit: AuditEnvelope(
    requireSignature: true,
    requireReasonCode: true,
  ),
  updateAudit: AuditEnvelope(requireReasonCode: true),
);

none keeps current state plus normal audit. versions records an immutable snapshot after every successful save. revisions(...) records those save snapshots and adds governed business revisions.

Put revision policy on the entity

final controlledProcedure = Entity(
  name: 'procedure',
  schemaType: 'docs.procedure',
  schema: 'docs',
  tableName: 'procedures',
  versioning: governed,
  facets: [
    IdentityFacet(
      fields: const [
        CodeField(),
        NameField('title'),
      ],
    ),
  ],
);

The default revision actions are:

Action	Meaning
RevisionAction.newRevision	create a working draft from the effective revision
RevisionAction.submitRevision	freeze and submit the draft for review
RevisionAction.publishRevision	make the reviewed revision effective and supersede the prior one
RevisionAction.abandonRevision	abandon the draft without changing the effective revision

They live under the reserved $revision facet and use the same action, authorization, audit, signature, idempotency, and record pipeline as declared facet actions.

Understand the generated tables

For a host table docs.procedures, the compiler emits:

• docs.procedures for the current aggregate;
• docs.procedures_versions for immutable save snapshots;
• docs.procedures_revisions for governed revision state and lineage.

The host row carries revision identity, number, status, parent revision, and effective revision columns. The revision table preserves review/effective state without creating a second competing save-version counter.

Inspect emitted structure, not a UI guess

final compilation = DbCompiler.compile(blueprint);
final inspection = DatabaseInspection.from(
  blueprint: blueprint,
  ddl: compilation.ddl,
  runtimeDdl: compilation.runtimeDdl,
);

final json = inspection.json;
print(json['summary']);
print((json['sql'] as Map)['complete_script']);

DatabaseInspection parses the emitted DDL and runtime DDL. Its manifest contains:

• schemas, entities, tables, columns, and constraints;
• indexes and relationships;
• lifecycle and infrastructure triggers;
• views and their SQL;
• the complete installation script.

Because the manifest comes from emitted SQL, the Studio database inspector and migrations describe the same physical plan.

Verify lifecycle enforcement too

Facet lifecycles lower to PostgreSQL guards. For declared edges such as draft -> approved and approved -> retired, the emitted trigger rejects any other update of the state column with a constraint error.

This gives two independent controls:

• the action runtime authorizes and records the requested transition;
• PostgreSQL rejects an undeclared state edge even if a writer bypasses the normal action UI.

Checkpoint

Create a revisioned SOP entity and prove:

1. the host, versions, and revisions tables appear in DatabaseInspection;
2. a save increments immutable history;
3. publish_revision changes the effective revision through the action path;
4. an undeclared operational lifecycle edge is rejected by PostgreSQL;
5. revision actions carry the configured reason/signature requirements.

Next: Authentication, IAM, and electronic signatures.

References: Complete Entity Grammar · Server Runtime.