qbit-scripting/rdbms

Scripting persistence adapter

The base Scripting QBit depends only on QQQ core. Persistence is disabled unless a trusted host supplies ScriptingTransactionPolicy. This optional module supplies RdbmsScriptingTransactionPolicy; it inspects the exact opened transaction before authoring changes or independently committed execution history can proceed.

runtime.withTransactionPolicy(new RdbmsScriptingTransactionPolicy());

The base service preserves the authenticated caller's native credential and client-channel limits before switching to its least-authority storage session. Named scripting grants still authorize each lifecycle action; the adapter does not grant permissions or introduce a second source registry.

Qualified connection requirements

Every transaction rechecks the actual connection and all nine core/source and scripting-owned tables. There is no cached database qualification, reflective connection probing, mutation of pooled session settings, or fallback to a no-op transaction.

• MySQL: native mysql, actual MySQL 8.4, configured single target/catalog, non-autocommit writable connection, all tables InnoDB with utf8mb4_0900_bin text comparisons, exact source/owner unique keys, innodb_flush_log_at_trx_commit=1, and sync_binlog=1 when binary logging is enabled. The server must use recovery-capable innodb_doublewrite (ON or DETECT_AND_RECOVER), and the session must not be read-only. The actual session must be UTC and have a lock timeout of 1–5 seconds. The JDBC driver's ordinary timestamp conversion must preserve the server's exact instant.
• File H2: native h2, exact jdbc:h2:file: target, real writable transaction, live WRITE_DELAY=0, and the required identity indexes. In-memory H2 is not a production qualification.
• Aurora MySQL, MariaDB, PostgreSQL and other engines/versions are refused. No provider equivalence is inferred.

Configure MySQL driver time handling using connectionTimeZone=UTC&forceConnectionTimeZoneToSession=true. Configure the bounded session timeout through the host pool/JDBC session variables or a dedicated database default. Keep host credentials and TLS configuration outside this module; the production adapter never disables TLS. Test-only loopback fixtures use disposable credentials and explicitly disabled TLS.

Required core indexes are (scriptId, sequenceNo) on the actual core revision table and (scriptRevisionId, fileName) on the actual core revision-file table. Hosts apply them using their native physical column mappings. The adapter checks them even if metadata omitted the uniqueness declaration. Required owner indexes match the shipped db/mysql/001_scripting.sql: artifact build/version, publication version, binding active slot and import revision. It never modifies core schemas itself.

The actual mapped scripting_execution.operation_id column must be VARCHAR with capacity at least64 and NOT NULL. This is checked on the same transaction connection before audited work. Fresh001 provides64; existing original001 deployments apply inspected003 to widen36 and enable AFTER phases. No runtime DDL or truncation fallback is used.

Migration and deployment authority

Apply the shipped MySQL migration with a separate migration identity. The application identity receives DML privileges only, without ALTER, DROP or TRIGGER. The migration's append-only history and binding-identity triggers must be checked by that deployment identity, and application DML denial must be tested before release.

Runtime cannot inspect trigger definitions under a least-privilege DML account: MySQL requires the TRIGGER privilege to expose that metadata. Granting it merely for inspection would let the application remove the same protections. The adapter therefore checks runtime connection/engine/settings/identity constraints, while the exact trigger migration and DML-denial proof remain deployment requirements. Privileged DDL changes are trusted host actions and require requalification.

Synchronous settings follow MySQL's documented commit durability requirements. Disk flush behavior, backups, restore, replication/failover and host/container death are separate deployment proofs. This adapter is not a claim that every configured host is production-ready.

Tests and current evidence

The base's explicit memory/in-memory-JDBC test policy is intentionally volatile and belongs only to its test classifier. It is not shipped in the production artifact and does not attest durable storage. The real provider subclasses here replace it with the production adapter.

Build the base main/test artifacts first, then run the module through the repository wrapper:

.\mvnw.cmd verify install
.\mvnw.cmd -f rdbms/pom.xml verify install

The MySQL suite creates a disposable loopback-only container from mysql@sha256:a0225d1ea6631c8bc2385dc4c2faba17bbf1834ecf369e1659a9a382bd8d5dd7, with random synthetic migration/application credentials, per-test schemas and a DML-only application identity. Docker wire logs are suppressed. A restart refreshes the actual dynamic port before reconnecting. The H2 suite uses temporary file databases and closes their native providers before cleanup.

The inherited suites cover native transaction rollback, separate committed history, publication/binding concurrency and native record-hook behavior. New cases cover unsafe core engines and commit settings, missing source uniqueness/case folding, concurrent draft saves, committed publication after an actual server restart, file-H2 delayed-flush refusal and no-op transaction refusal.

Current evidence: base full 124 tests and quality gates passed after caller-ceiling/default-deny changes. The optional adapter passed all 29 real-provider tests (17 MySQL and 12 file H2), with zero failures/errors, and was packaged/installed after that unchanged verified snapshot. This includes actual database restart, rollback/concurrency, DML-only migration guards, live durability refusal, doublewrite/read-only rejection and source-key qualification. The first H2 unsafe-setting test exposed a fixture URL that reset WRITE_DELAY; it now changes the actual native connection URL and proves refusal. Neither the protocol-level fake worker nor these database tests qualify hostile script execution.

AFTER and audit-schema compatibility — 2026-10-31

Current corrected evidence supersedes the historical29-test snapshot above: base145 passed all quality gates; this optional module passed44 tests (13 file-H2,14 actual AFTER/MySQL,17 baseline MySQL), zero failures/errors/skips, with Checkstyle. See after-hooks-operation64-provider-verification.log and the base AFTER report for exact hashes, schema upgrade proof and preserved earlier failures. Existing36 and nullable-column refusals are covered; historical audit rows and immutable triggers survive actual003 migration. The optional POM's BOM imports now use dependencyManagement and its duplicate RDBMS dependency is removed; retained dependency versions/scopes are unchanged. No shared artifact install or host deployment follows from this verification.