gnomonlearn
Docs/RFC-0041 install atomicity and audit conformance

RFC-0041 install atomicity and audit conformance

Versioned draft snapshot

RFCs, reference catalogs, and evidence reflect Spec 3b2e3e7a114fb826b1445d39a48756b8fff629cd. Counts and pending/status notes belong to that snapshot. Read the dated project update for later progress.

Source repositories are private during staging. Links marked “repository access required” need access to the linked repository.

This is a trace and gap record from the pinned draft specification. It does not establish proof or implementation conformance.

Current status — October 17, 2026

Gnomon commit e5c2abea9b4b8d12fa25b717f48b17d4a617fd16 closes the tested §8 object-failure diagnostic subcheck: M41020 identifies manifest namespace/version, object name and kind, preserves the original cause/code, and rejects with either continueOnError setting before later objects and materialization. The ordinary Roma engine Node target passed 28 Vitest files and 217 tests on Node v20.19.0 / Darwin arm64, including all seven transaction-test-file cases. See the archived actual evidence (Gnomon source: gnomon/tools/roma/evidence/rfc0041-m41020-20261017/README.md; public archive link pending).

The separate focused ordinary Roma target //runtime/tests/completeness:test_pg_transaction_boundary at Gnomon 091f1f0060fff18cf7168e23a77a88a0f5682beb passed one Vitest file and all five tests against fresh local PostgreSQL 16.15. Its five sentinel-table API/backend SQL cases check owned commit visibility, callback rollback, failed savepoint isolation with caller commit authority, caller rollback of successful nested writes, and deferred-foreign-key COMMIT failure with reuse of the same writer/backend. A distinct pinned observer checks persisted visibility. See the actual scoped evidence (Gnomon source: gnomon/tools/roma/evidence/rfc0041-real-pg-20261017/README.md; public archive link pending) and Root 4328dc/session10051 → c9f827/0, Roma child 55899, and independent acceptance c51d53/0 plus dbe597/0.

These SQL cases do not execute a module install plan or write Graph module resources, registry records, install-level audits or agent activation state. Separately, Gnomon 713420af34abb299ef7105ec81bce294356ff527 passed the ordinary Roma engine target with 29 Vitest files and 231 tests. Its two filesystem no-savepoint cases use the real engine, registry, object installer and template executor. Fresh observers verify persisted module, manifest and resource-type rows: two successful modules commit before the third module’s real object failure, its staged object rolls back, and a fourth module runs only with continueOnError=true. See the archived actual evidence (Gnomon source: gnomon/tools/roma/evidence/rfc0041-filesystem-persistence-20261017/README.md; public archive link pending).

The follow-up at Gnomon 9d2b93386890a98d667c92b903d30bad50ee3f54 passed 29 files and 233 tests, including four filesystem cases in 199 ms (full Vitest duration 4.39 seconds). With either continuation choice, the caller catches the no-savepoint capability-check rejection inside its own transaction and commits both its prior and later writes. Fresh observers find no module, manifest or resource-type artifacts, and no template or content input is invoked. The caller-refusal evidence (Gnomon source: gnomon/tools/roma/evidence/rfc0041-filesystem-caller-rejection-20261017/README.md; public archive link pending) binds Root 6de9c8/session10076 → c0d20d/0, Roma child 91202, independent acceptance 39ec98/0, and 6,373 unchanged product rows. This verifies refusal. Full installer rollback within a supported-savepoint caller transaction remains open.

PostgreSQL module-resource/install-plan/registry persistence, caller-owned module rollback on real backends, install-level audit persistence/readback, agent activation and concurrency remain open. Normalized manifest hash/version storage, object ordering and registration, and executable linker/provider behavior also remain open in the engine conformance record. The October 4 audit and its earlier 214/216-test results retain their original scope; no full RFC-0041 or deployment acceptance is claimed.

Historical audit — October 4, 2026

Status: implementation audit, 2026-10-04. Owner: Module Platform, Graph Runtime, and Spec. No Gnomon system is deployed.

Observed gap

RFC-0041 §3 and §6 require one atomic transaction per module. Section 10 states that a hook failure rolls back the entire module, with no partial success or warn-and-continue behavior. Its continueOnError option belongs to the install plan: after a failed module, the plan may attempt later modules. The extracted graph/packages/graph-module-engine/install/install-module.ts previously caught per-object, materialization, reconciliation, and post-install hook failures and suppressed the throw when options.continueOnError was true. A module could then return success: false from a transaction callback that committed. This violated per-module atomicity and hook failure semantics. Framework commit 279bbaf76 fixed audit suppression; commit 65d300610 now throws on all four failure paths regardless of the plan-level continuation flag. The graph-module-engine Bazel target passed 28 Vitest files and 216 tests, including new object and post-install hook failure cases with continuation enabled. Batch installation uses an outer transaction with savepoints when supported. The no-savepoint branch calls the installer directly in the outer transaction, so it cannot isolate one failed module while continuing later modules.

RFC-0041 §11.3 also requires one structured audit entry per install, including namespace/version, strategy, installer, tenant, object count, hook statuses, manifest hash, and duration. The engine constructs required graph statements and a core.module Resource, but its shown module-materialization template writes only name and version into that Resource. A source search found no explicit RFC-0041 install audit entry writer in the extracted engine. Database write audit triggers may produce lower-level records, but those do not by themselves prove the required install-level entry and fields. The PostgreSQL batch path also previously ran SET LOCAL audit.enabled = 'off'. Framework commit 279bbaf76 removed that override. Its graph-module-engine Bazel target passed 28 Vitest files and 214 tests, including a transaction test that exercises the PostgreSQL-compatible execute seam and confirms no audit-disabling command is issued.

  1. Keep the new throw behavior for any object, materialization, statement reconciliation, or hook error. Let the outer plan decide whether to attempt the next module. Keep per-module status/error reporting outside the rolled-back transaction so a failed status is observable.
  2. Use a per-module transaction or working savepoint for continuation. If a backend has neither, reject continueOnError before writes or run modules as separate transactions. Test prior successful modules, the failing module, and later modules independently.
  3. Emit an install-level audit record with every §11.3 field, including failure and no-op outcomes. Define its schema in the existing audit contract and verify persistence/readback on each backend. Ensure neither module content nor install options can suppress it.
  4. Reconcile the core.module record’s §11.1 fields with the actual stored shape, manifest hash and lifecycle policy. This is a first-release contract decision if the implementation cannot support the authored fields.

Acceptance

  • Inject a failure at each install phase, especially postInstall, with continueOnError both false and true. No writes from the failed module survive in either case; later modules run only when continuation is true.
  • Run those cases on PostgreSQL and one no-savepoint backend. Query the graph and install audit store after commit/rollback rather than trusting only returned status.
  • Verify the full core.module and audit entry shapes, tenant/principal attribution, hook statuses, and no-op behavior against RFC-0041 and RFC-0047 before claiming conformance.