qbit-document-generation/bridges/scripting/README.md

# Optional scripting bridge

This separate artifact depends on both QBits' public APIs. Neither QBit depends on the other or owns the other's tables.

Wire `DocumentGenerationQBitConfig.withContextExecution(new PublishedScriptContextAdapter(scriptingService))`. Trusted programmatic callers may obtain `PublishedScriptContextAdapter.reference(scriptingService.selectPublishedContext(actor, publicationId).pin())`; the reference includes publication ID, artifact ID and SHA-256. A malformed reference, missing exact-build context-test success, changed hash, missing permission, inaccessible source record, unavailable worker or failed execution blocks generation.

For native user authoring, create one adapter and install both `.withContextExecution(adapter)` and `.withContextSelection(adapter)`. The template's **Select or clear published context script** action searches current-authorized isolated projects and selects a publication tested successfully as CONTEXT on its exact build. The server obtains the immutable artifact/hash reference; users never construct it. Clearing is explicit. Discovery is bounded to20 matching projects/100 publication candidates and50 results; narrow by project name. Older exact selection lookup remains authorized independently. Publishing a newer script never moves an existing template pin. The direct `reference(...)` helper remains compatible for trusted programmatic integration.

Eligibility is checked for direct raw-reference publication and execution as well as the chooser. An older document pin that was published using only a hook test now fails closed until that exact build has successful context-test evidence. The adapter never substitutes another build or silently republishes a template. Generic Scripting context execution retains its existing API semantics; this stricter document contract belongs to the optional adapter.

The adapter fetches the actual source under current QQQ permissions. Scripts receive `context.payload.context.record` and `context.payload.context.source` through the worker's `main(context, qqq)` entrypoint. The return value is a bounded JSON object; Document Generation reserves its original record context. Published signed declarations are the maximum read grants; hosts may supply a narrower grant selector. QQQ table, record and field permissions still apply to every broker read.

Build from the Document Generation repository using its wrapper: `./mvnw -f bridges/scripting/pom.xml verify`, after installing the matching Scripting QBit and this repository foundation (`./mvnw -pl foundation install`). This bridge does not supply or qualify an execution worker.

Test fixtures explicitly allow volatile storage through the scripting test base; production hosts must configure the scripting owner's qualified transaction policy and isolated worker.

## Cold maintenance for document context publications

Configure the optional owner-neutral SPI with
`ScriptingRuntime.withWarmPublicationSource(new GenerationWarmPublicationSource(definitions))`.
The native scripting lifecycle calls it under its fresh declared service principal. Give that
principal `scripting.warm`, `scripting.view`, `document-generation.view` and
`document-generation.warm`, the required metadata read ceilings and access to required script
projects. Do not add `scripting.execute`. The generation inventory requires a freshly minted,
currently declared native service identity; an ordinary user carrying the same role strings is
not sufficient. No source record, template body or executable bundle enters this supplier.
The declared warm target-table set intersects the generation host's configured source tables.

The inventory includes current draft pins (preview), active published revision pins, revisions
of QUEUED/RUNNING queue items and incomplete synchronous batches. Completed request/revision
history and historical PREVIEW snapshots do not reserve capacity. Every queue pin must match its
immutable revision. Complete `publication:id:artifact:sha256` tuples remain intact; Scripting
independently verifies project visibility, artifact/HMAC and exact-build CONTEXT test evidence.
Warming grants no execution or broker authority. No hot path prepares a missing artifact.

Apply the additive `20261031-warm-batch-completion-{h2,mysql}.sql` migration once before adopting
this version on an existing database. Fresh schemas include nullable `document_generation_batch.completed`.
NULL legacy batches remain required: completion is never inferred from a partial request history.
Only successful replay of the same pinned batch selection marks completion; failures, changed
selections and partial results cannot release its pin. Queue reconciliation and retained-original
reprint do not execute historical scripts. Unknown generation uses the current publication.

The inventory projects code metadata only: at most 1000 templates, 1000 required revisions,
1000 incomplete batches, 1000 required queue headers and 10016 pending queue items, each with a
lookahead row. This is a bounded supported capacity, not a performance claim. Required metadata
loss, overflow, hidden fields, mismatched native/owner reads or combined scripting pin/byte limits
fail readiness rather than truncate. The explicit maintenance projection bypasses only this owner's
known actor/parent POST_QUERY_RECORD filter on work tables. Ordinary caller queries are unchanged;
custom host filters and row locks are refused. Native table/field, credential/channel and current
service declaration checks still apply. No source records or initiating actors are projected.

Historical first restart-tranche evidence: the initial five native-memory inventory tests and existing three context adapter tests passed;
four new translation tests exposed an invalid empty native test instance before reaching assertions.
The fixture now uses normal native backend/table/auth metadata, and a sixth inventory regression
covers draft-only pins and draft changes. This corrected snapshot and final restart qualification
remain root-owned and pending. These tests do not qualify a worker or database.

The earlier conservative retained-history policy is superseded by the active/in-flight
inventory and cold idle-session reclamation described above. Parent Generation67 (34 service/22 JDBC/11 inventory) and full Scripting227 gates passed with
zero failures/errors/skips and Checkstyle0; scripting coverage also passed. The actual H2 migration
case passed; the inherited MySQL migration case remains a separate gate. Earlier65/5 and67/2
Generation failures remain preserved with their corrections in the source handoff. Required
active code can still exceed configured capacity. Reserve headroom for authoring: bounded use
leases protect newly prepared code through test dispatch/publication or binding commit, so a
periodic pass cannot discard it between preparation and use. Busy/protected sessions may defer
reclamation; readiness stays down until the complete current inventory is prepared.