qbit-document-generation/bridges/scripting

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.