gnomonlearn
Docs/RFC-0054/Design Q&A

RFC-0054 · Design Q&A

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.

← Read the authored RFC

Q: What is the atomic unit of DDL apply?

Status: Open

Source: RFC-0054 §§3.3, 7.1, 10 invariant 6; RFC-0041 §6.1 Issue: Stage 3 and the invariant require one atomic transaction per module, but §7.1 permits per-file or per-statement transactions and an operator override. A partial module apply would violate the install engine’s rollback guarantee. Recommendation: Keep a single module transaction for transactional DDL and define explicit staged operations for statements that PostgreSQL forbids inside it, with recovery state and readiness gates.

Q: Which installed objects are eligible for automatic DROP?

Status: Open

Source: RFC-0054 §§3.2, 5 Issue: The diff turns any installed object absent from the declared SQL map into a DROP, including possible operator-owned, extension-owned, or other modules’ objects in a live pg_dump. The RFC does not establish ownership boundaries or a protected-object set. Recommendation: Diff only objects with recorded Gnomon ownership and a compatible prior manifest identity; require explicit adoption before managing preexisting objects.

Q: How is a plan bound to the database state it was reviewed against?

Status: Open

Source: RFC-0054 §§3.2–3.3, 8.2 Issue: CI may plan against a snapshot while deploy applies to a live database that changed meanwhile. The RFC does not require an installed-state fingerprint check or reapproval when the live state differs. Recommendation: Bind the plan to source bundle and installed-state digests, revalidate under an apply lock, and fail closed on drift.

Q: Who is allowed to approve a destructive operation?

Status: Open

Source: RFC-0054 §§5.1, 5.4 Issue: A module author can set allow-destructive: true in the same change that emits a DROP, and a broad CLI flag bypasses the default deny. Neither establishes approval for the exact target, data impact, and plan digest; a PR label does not carry through to deployment authorization. Recommendation: Require an operator-approved, exact-plan acknowledgment bound to environment, object identities, and plan digest, with an audit record.

Q: What does the round-trip fingerprint prove about legacy SQL parity?

Status: Open

Source: RFC-0054 §§4.1–4.2, 11.1–11.3 Issue: Matching canonical SQL bytes is neither necessary nor sufficient for schema and behavior equivalence, and the source admits 7.5% imperative legacy statements outside the mapper. It cannot prove the entire legacy schema is faithfully represented while those statements remain manual. Recommendation: Compare catalog state and behavior on fresh databases, inventory every unmapped statement, and gate retirement on a complete executable migration or explicit supported exception.

Q: How are data changes and irreversible effects rolled back without migration files?

Status: Open

Source: RFC-0054 §§5.2–5.3, 8.3 Issue: A schema snapshot records structure, not removed rows or values. Reverse DDL cannot recover data lost by DROP, TRUNCATE, or lossy casts, and manually invoked imperative scripts are not tracked by the declared plan. Recommendation: Distinguish reversible schema changes from data migrations, require backup/restore or forward-repair procedures for irreversible steps, and record operational scripts as versioned artifacts.

Q: What canonical representation is compared between emitted SQL and pg_dump?

Status: Open

Source: RFC-0054 §§3.2, 4.1 Issue: The emitter’s normalized SQL and pg_dump --schema-only do not necessarily use the same statement structure, ordering, or implicit defaults. A text-keyed (category, qualified-name) → canonical-sql diff can report false changes or miss dependencies. Recommendation: Normalize both through a typed PostgreSQL catalog model with versioned comparison rules, then emit SQL from the resulting semantic diff.