Document Generations Schema

Phase scope: [app]. This page describes generated output runs under the unified documents / documentVersions model.

Purpose

• Stores generation lifecycle state.
• Captures the assembled text or output file reference.
• Anchors each generation to the exact documentVersions snapshot used for assembly.
• Preserves enough render metadata to explain which committed content and runtime data produced the output.

Relationships

• Many generation runs can belong to one documents row over time.
• Each generation run points at one documentVersions row through documentVersionKey.
• Generation reads the named documentVersions row and its pinned moduleVersions rows. Party facts, if any, are data on a pinned data_pool module version, not partyData / partyDataVersions.
• A generation run may also record documentKey as a convenience pointer for listing and support workflows, but documentVersionKey is the audit anchor.

Fields

Example document

{
  "documentGenerationId": "gen_01HV8XQZK4J9R9W3M6T4M2RGN1",
  "documentKey": "doc_01HV8XQZK4J9R9W3M6T4M2R8E1",
  "documentVersionKey": "docv_01HV8XQZK4J9R9W3M6T4M2RH09",
  "status": "completed",
  "generatedAt": "2026-04-18T14:22:00Z",
  "assembledText": "I, Jane Smith, being of sound mind...",
  "fileReference": "storage/docs/DOCD-00123/v1.pdf",
  "renderMetadata": {
    "format": "pdf",
    "rendererVersion": "2026-04-18",
    "moduleCount": 6,
    "visibleBlockCount": 24
  }
}

Render Boundary

A generation run is deterministic for a given documentVersionKey:

1. Read the documentVersions row.
2. Read all moduleVersions rows pinned to it by moduleVersions.documentVersionKey.
3. Evaluate module and block flow conditions against the runtime data in those version rows.
4. Render embedded blocks[].
5. Store generated output metadata on documentGenerations.

No generation step reads partyData, partyDataVersions, documentInstances, or moduleInstances. Historical party values are preserved because the relevant data_pool module version is pinned to the document version being generated.

Indexes

Foreign Keys

• documentGenerations.documentKey → documents.key (optional convenience pointer).
• documentGenerations.documentVersionKey → documentVersions.key (required audit anchor).

Timestamp Rule

• Use generatedAt as the meaningful business timestamp for when a document generation run produced its output.
• Convex _creationTime already captures when the row itself was inserted.