Document data

Document data stores rendered documents — the printable result of running a template over table rows — as versioned snapshots. Each saved document keeps its history, so a client can re-open an earlier version and an archive can list the latest version of every document.

Runs and snapshots

Two tables make up the model:

Table	One row represents
document_data_runs	One document: a rendering of some table rows by a template
document_data_snapshots	One saved version of that document

A run is created once when the document is first saved. Every later save adds a snapshot under the same run, with an increasing version_number starting at 1.

A snapshot stores:

• the source records it was built from (each as profile, table, table definition id, and row id);
• the template name, kind, and path;
• the rendered document itself as JSON;
• the change kind: generated when the server produced it, user_adjustment when a user edited it;
• who created and who last updated it;
• the version number and timestamps;
• an optional seal time.

Saving a document

SaveDocument stores a freshly produced document — the rendered JSON plus its template metadata and source records — as a new run with its first snapshot, marked generated. It returns the document id (the run id), the snapshot id, and the version number.

UpdateDocument saves an edited version under an existing run, marked user_adjustment.

The version window

Not every update creates a new version. If the latest snapshot is an unsealed user_adjustment updated within the last 10 minutes, a new user_adjustment updates it in place instead — useful while a user is actively editing, where every keystroke would otherwise mint a version. The save reports whether it created a new version or updated the latest one.

Any other combination creates a new version:

• the latest snapshot is generated (a fresh render starts a new version);
• the latest snapshot is sealed;
• the latest update is older than the 10-minute window;
• the new save is generated rather than an adjustment.

Sealing is a data-layer operation that freezes a version so it can no longer be updated in place.

Reading documents

Call	Returns
GetDocuments	The latest snapshot of every run, optionally filtered by profile and template, newest first
GetDocument	The latest snapshot of one run
GetDocumentVersion	One specific version of one run

GetDocuments defaults to 200 results and accepts up to 1,000.

Permissions

A document is a rendering of table rows, so it inherits their permissions: a caller may touch a document only if it may read every table the document was built from.

• a document with source records requires read access to each source table;
• a document without source records falls back to requiring read on the whole profile;
• listings are filtered rather than refused, so a narrow role still sees its own documents;
• a single document the caller may not read is hidden — the response looks exactly like a document that does not exist.