qbit-scripting/docs/DURABLE-AFTER-HOOKS.md

# Durable AFTER record hooks

Status: full base verification passed 2026-10-31 against the root-verified core/RDBMS
candidate in a dedicated local repository: 145 tests, no failures/errors/skips,
zero Checkstyle violations, unchanged instruction/branch coverage checks passed.
The 13 native file-H2 AFTER tests use the real transactional Jobs owner/runtime
and a trusted protocol worker. The corrected optional provider gate also passed all 44 tests: 13 file-H2,
14 actual AFTER/MySQL and 17 baseline MySQL. This is not a hostile-worker or
deployment qualification.
No new queue, script registry, database store or generation dependency was added.

## Event semantics

Add distinct AFTER_INSERT, AFTER_UPDATE and AFTER_DELETE phases. Existing PRE and
POST behavior is unchanged: POST observes the backend action before its caller
may commit, and a warning cannot undo that action. AFTER is dispatched from a
Jobs intent enlisted in the exact source transaction and becomes deliverable only
after commit. Enlistment failure refuses the required mutation; delivery failure
cannot roll back its committed source. Preview never enlists or executes AFTER.

INSERT/UPDATE retain only a bounded locator and immutable script pin. The worker
receives a newly authorized, field-projected record at delivery time, explicitly
not the historical mutation snapshot. A deleted/missing/inaccessible current row
refuses execution. DELETE is an event-metadata notification, not an old-record
snapshot: no deleted values or inferred missing-row readability. Current native
table/action/project/run authority is still mandatory. Jobs parameters contain
no source record field snapshot, passwords, BLOBs, hidden fields or credentials.

## Minimal components

- Extend HookEvent and ALLOW-only result validation. AFTER cannot patch or veto;
  the broker remains bounded read-only. SDK event metadata explains delivery
  semantics; authoring discovery/test/binding uses the existing APIs.
- An opt-in host metadata helper installs a required transactional record listener
  for selected AFTER phases, preserving existing Java customizers and refusing
  conflicting required listeners rather than silently replacing them.
- The listener resolves the active immutable binding, publication/build/artifact
  pin, checks current caller authority and bounds the action/locator count. A
  core-owned UUID identifies this exact active native event invocation; per-record request
  keys include that identity, binding ID and ordinal. Repeated callback enlistment
  therefore reuses the same owner key without a consumer registry. Identical later writes
  are different events. Re-delivery of the persisted job preserves its event ID.
- A single fixed Java backend process (stable transactional process revision)
  consumes only a core-verified currently leased enlisted intent. Direct process
  invocation and an ordinary launched Jobs process with forged parameters fail.
  The consumer must not duplicate core grant/lease verification or trust params
  as credentials.
- Delivery checks current restored actor, native table/action and project access,
  enabled exact binding, immutable publication/build/artifact hashes, field
  policy and qualified worker. INSERT/UPDATE use genuine enforced native Get
  with display/heavy enrichment disabled. DELETE rechecks table-level policy
  using a genuine read input and does not fetch or expose deleted values.
- Existing append-only script execution audit records attempts/outcomes with
  event correlation and generic host-owned refusal codes. Worker text and source
  values stay out of shared history. Core Jobs owns admission, restart, attempts,
  lease and completion; no exactly-once script execution claim. A crash between
  external execution and completion can repeat an observational attempt. Terminal
  audit failure after worker execution leaves the job failed and the independently
  committed STARTED entry visible. An authorized operator retry may run the worker
  again with the same event correlation; that ID is not execution deduplication.

## Compatibility and verification

MySQL fresh schema includes the nine phases; `003_durable_after_hooks.sql` upgrades
the original unnamed event check after explicit schema inspection. H2 metadata-derived
fixtures have no event check to migrate. Existing rows
and published source pins retain their meaning. Native authoring lists AFTER only
when the host installs its required listener; patch fields remain empty and dry
runs explicitly do not prove commit or enqueue jobs. No worker runtime change.

Use real native InsertAction/UpdateAction/DeleteAction and qualified JDBC/Jobs
fixtures with a trusted protocol worker: source+intent commit/rollback and caught
admission failures; preview suppression; bounded batch locators; identical later
writes remain distinct; repeated same request dedupes/conflicts correctly;
restart restores current actor and pinned script; revoke project/table/run/binding
before delivery and prove zero worker calls; hidden/credential data never enters
params/context; deleted snapshot never enters worker; direct invocation refused;
ALLOW accepted and PATCH/VETO rejected; audit failure explicit; late source
update produces authorized current-state data. Tests must not substitute a fake
queue for native same-transaction/restart evidence.

Core dependencies are not installed by this task. Root coordinates final shared
artifact handoff, provider gates and consumer compatibility builds.

## Host registration and authoring

```java
ScriptAfterHooks.install(instance, sourceTable,
   HookEvent.AFTER_INSERT, HookEvent.AFTER_UPDATE, HookEvent.AFTER_DELETE);
```

Configure the existing native Jobs provider on the same supported transaction
resource as the source table, enable transactional admission, and provide the
operator-owned namespace/grant key and identity restoration. The scripting QBit
does not provision or weaken those controls. Bind a tested immutable publication
through normal authorized hook administration. The source editor advertises
AFTER only for installed source phases. Dry runs use a current selected record
for authorization, produce `dryRun: true`, never enlist, and cannot attest commit.
Setting an event string in a direct request never supplies the native dispatch
marker: the fixed delivery entry point always calls the core verifier itself.

The generated editor SDK and bundled compiler SDK declare `HookEvent` (nine
phases) and `CommittedEvent`, whose `CURRENT` variant has a projected `record`
and whose `DELETED_METADATA` variant has no record. These are type assistance,
not authority. Core lease/grant/session checks run on entry, at the actual worker
boundary after history/artifact host callbacks, and after delivery.

Trusted SDK verification: worker/after-sdk-tests.log (18 passed),
worker/after-sdk-lint.log; frontend scripting-after-ui-tests.log (15 passed) and
scripting-after-ui-lint.log. Compiler SDK source SHA256
579ad147e7e0d4f2e025e4513fa8d6ad0436870872b64cb4ce4907ad9eec986a;
worker test source bda2208680b50d81132affb845746ce75d4445aa21b0f594b1cc7ea16f2be5cd.
Root subsequently built and sealed the separate 0447 SDK image candidate;
sealed 0240 image evidence remains unchanged. Runtime qualification remains separate.

## Historical initial native evidence and compatibility boundary

`after-hooks-full-verification.log` is the successful full base gate. The earlier
focused 19-test run found two wrong exception-class assertions; actual native
required listeners throw RequiredListenerException. The corrected 20-test gate
passed before the final full run. Tests preserve source rollback and failed
commit assertions. Existing PRE/POST tests explicitly select their six phases;
AFTER has separate host registration.

The native tests prove source/intent shared commit and rollback, preview refusal,
required-listener admission poisoning even when caught, bounded batches, distinct
identical later mutations, restart with pinned publication and current-state
projection, metadata-only deletion, run/project/source/binding revocation, direct
non-enlisted process refusal, pre-worker scope changes refused after STARTED, and
post-worker scope changes refusing job completion. STARTED audit failure prevents
the worker; outcome audit failure can follow a real execution, and explicit
authorized retry executes again with the same event correlation.

Verified main JAR SHA256:
`d56cae9d674856b3b8eca68e499896d78f59970b73eee50ef88228d17c207cba`;
tests JAR `2209b33413512d7029c6564ddb7215c0f815732915e341048d5848ff8ef30cd7`.
Exact source manifest: `target/after-hooks-verified-source.json`. The core/RDBMS
prerequisite full gates are 3203/417 tests with 16 existing skips; subsequent
29-test native statement-cleanup gate and exact artifact handoff are parent-owned.

H2 evidence does not establish a combined AFTER consumer/MySQL execution test.
Core transactional Jobs has its own actual MySQL provider gate; the optional
scripting RDBMS provider compatibility suite remains a distinct gate. Production
identity restoration, operational namespace/key rotation, actual isolated worker
qualification, and deployment recovery policy remain host responsibilities.

## Historical provider and editor follow-up before the corrected gate

Test-only provider seams preserve all 13 AFTER scenarios and their assertions;
they pass again on actual file-H2 (`after-hooks-provider-seams-verification.log`).
The production main JAR is byte-identical to the full145 gate. Regenerated test
JAR SHA256 is `ec304ab4e191c4a7e4ffca30fe48bb73ee8511e84a6224471589cad57ed842f7`.
Only the base AFTER fixture changed relative to the original source manifest.

The optional MySQL subclass uses the existing pinned provider factory, DML-only
application identity, real scripting policy, native Jobs qualification and shipped
scripting migration/triggers. Jobs adds mandatory READ_COMMITTED and bounded DDL
lock wait. Its restart scenario restarts the actual server and refreshes the
inspected dynamic port before recovering the queued intent. There is no weaker
provider/schema substitute. Full42-provider execution is pending.

The previous optional29 gate had one MySQL communications failure (the generic
qualification refusal intentionally carries no SQL/credentials). A separate
unchanged-deadline retry of that exact method passed with running=true,
oomKilled=false, restarts=0. It does not establish the original failure's cause
or justify calling it transient. Bounded test-only exception class/SQLState and
policy-method diagnostics remain enabled for the combined gate; they never log
SQL, messages, connection properties or credentials.

The offline editor fallback SDK also now matches the generated/server and bundled
compiler SDK. Actual language-service tests cover completion of all nine hook
phases plus CONTEXT, invalid event diagnostics and deleted-record narrowing.
Combined frontend API/panel/language-service22 tests and scoped ESLint pass in
`scripting-after-sdk-ui-tests.log` and `scripting-after-sdk-ui-lint.log`. No package
or lockfile changes accompany these declarations.

## Corrected audit schema and final provider gate — 2026-10-31 05:26

The first combined42 gate (`rdbms/after-hooks-combined-provider-verification.log`)
failed five AFTER/MySQL assertions and one baseline MySQL setup. The five AFTER
failures exposed a real schema defect: UUID plus ordinal correlation needs at
least 38 characters, while the old physical audit column allowed 36. Producer
metadata and fresh001 now use VARCHAR(64); actual003 widens existing history
before enabling nine-phase bindings. Event identity and retry assertions were
not shortened or weakened. The upgrade test preserves every column of two real
pre-upgrade audit rows and verifies their UPDATE/DELETE guards after migration,
then records STARTED/OK with the exact long event correlation.

The optional policy now checks the exact current transaction's mapped execution
column: VARCHAR, capacity at least64 and NOT NULL, using a bounded metadata SELECT.
Unmigrated36 and nullable columns refuse before worker execution or new audited
work. There is no qualification cache, second connection or runtime DDL.

`after-hooks-correlation-full.log`: full145 base tests, zero failures/errors/skips,
Checkstyle and unchanged coverage gates passed. `rdbms/after-hooks-capacity-h2-verification.log`
passed13 file-H2 tests. Root's `rdbms/after-hooks-operation64-provider-verification.log`
passed44 tests at05:26:08:13 file-H2,14 actual AFTER/MySQL and17 baseline MySQL,
zero failures/errors/skips and Checkstyle clean. The actual AFTER scenarios use
native Jobs admission/delivery, DML-only application identity, shipped migrations,
restart, rollback, current-authority refusal and audit-failure retry.

Exact corrected artifacts (SHA256):

- Base main: `9d205a77b155cb59360b24f3e5b38d139df24f9548398e62d3ed789c042d0c1d`.
- Base tests: `b6a9db73a761014a322a2551a169fb6eb036b343bd7ee58e342c94d5a0bc11c2`.
- Base POM: `987b2e5456a22b07ce1601c57ea6f50e4d44b21491de53ff6c5048feaa2ff1bd`.
- Optional RDBMS JAR: `2ff374cb881be26b331e9db9ec8fc20a8ea694ee49017b3ba81c5341217cd989`.
- Optional POM: `6be71c8fe8d727f0047c0ce5c2edf50b2e2785d2fa746db6589256770a9c547c`.

Base source manifest: `target/after-hooks-operation64-source.json`; combined
source/artifact manifest: `target/after-hooks-operation64-provider-source.json`.
Only the dedicated local Maven repository received base artifacts; no shared
installation or deployment occurred. Optional middleware/GitHub compatibility
is recorded separately after its own gates.

The earlier12954 qualification/transport failure and6946 baseline08S01 failure
remain preserved. A single-method diagnostic retry and this full corrected gate
passed unchanged deadlines, with healthy fixture observations; they do not
establish those original transport failures' cause or justify calling them
transient. Only the separately reproduced audit-width defect is diagnosed and
corrected here. Production storage/recovery, identity restoration and hostile
worker qualification remain deployment gates.

### Optional consumer compatibility

After the corrected145/44 snapshot, serial offline wrapper verification in the
same dedicated repository passed middleware7 (including6 actual native HTTP
tests) at05:27:44 and GitHub importer7 at05:28:37, with Checkstyle and no installs.
Logs: `middleware/after-hooks-operation64-compatibility.log` and
`github/after-hooks-operation64-compatibility.log`. GitHub tests use trusted
HTTP fixtures; no private repository was sent externally.

Middleware JAR SHA256 `4094e2d7b74906fda6dd98ff6e879fa38aec7cd8489ae8681b1c196fb21fe936`;
GitHub JAR SHA256 `63b2ed1a8ecae02fc2d37754ab552a5133525a20087865120b0c4bc7fbc1c300`.
Their exact source, POM and artifact hashes are appended to
`target/after-hooks-operation64-provider-source.json`. No production source changed
during these compatibility gates. These existing HTTP tests establish regression
compatibility; native durable AFTER delivery is exercised by the separate13/14
H2/MySQL fixtures, not by an invented HTTP commit assertion.