gnomonlearn
Docs/RFC-0052 bootstrap contract proposal

RFC-0052 bootstrap contract proposal

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.

Status: proposed, awaiting owner decision. Owners: Module Platform, Compiler. No normative source or generated facts changed.

Evidence

RFC-0052 §§3.1, 3.4, and 4.1 declare the cycle db.pg → core → db.graph → db.pg, while §6 requires a DAG and assigns db.pg rank 1 and core rank 7. RFC-0054 §6.1 already includes core bootstrap kind-definitions among bootstrap.sql inputs, alongside db.pg, db.ids, db.audit, and db.graph. RFC-0051 §12.3 and RFC-0052 §9 omit db.pg and core from their generation lists.

RFC-0051 §12.1 promises no change from the first db.graph install, while RFC-0052 §§3.4 and 6.1 explicitly add its non-bootstrap functions and indexes on that install. RFC-0052 §10.4 additionally claims Phase 2 can converge from an empty database, despite requiring Phase-1 storage and principal records.

Use a generated Phase-1 core vocabulary seed owned by the core module, as already anticipated by RFC-0054. Preserve a single authoritative declaration for each seeded kind; neither the kernel nor db.pg gets a duplicate definition.

  1. Offline compilation collects the explicitly tagged bootstrap declarations from db.pg, db.ids, db.audit, db.graph, and core. Resolve their declaration references without requiring an installed database. Reject missing seed prerequisites; do not silently treat an arbitrary runtime dependency cycle as a bootstrap dependency.
  2. Phase 1 executes the resulting format-versioned bootstrap.sql. It creates the minimum storage, roles, functions, policies, principal records, and core kind-definition seed needed for the normal installer. Seed rows carry their owning module identities and deterministic source provenance.
  3. db.pg’s kind-definition prerequisite is explicitly satisfied by the versioned core seed, rather than by a normal Phase-2 dependency on the full core module. Remove that full-module edge from its Phase-2 manifest DAG. Define and validate the seed prerequisite in the canonical manifest contract; it is not an untyped planner exception.
  4. Phase 2 installs the remaining declarations in dependency order, including completion of core at its normal position. It recognizes seeded declarations by their canonical identities and verifies agreement before adding the remainder. A mismatching seed fails; it must not be overwritten silently.
  5. Ranks are ordered groups. Within a group, dependencies determine execution order; only independent members may run concurrently. Thus core.kind precedes core.composition even when both belong to group 8. Use stable module identity ordering to break ties among otherwise independent nodes.
  6. A supported fresh install always runs Phase 1 followed by Phase 2. The fixed-point guarantee is an empty plan on a second Phase-2 install with unchanged inputs. Separately require agreement between Phase-1 output and the overlapping declarations in the complete module plan. Remove the unsupported Phase-2-only empty-database equivalence.

The first Phase-2 install may add non-bootstrap db.graph functions and indexes; only the bootstrap subset must already agree. RFC-0051’s first-install no_change statement must be narrowed accordingly.

Source changes after approval

OwnerExact change
RFC-0051 §12.1, §12.3Narrow no-change to the bootstrap subset; list all five input owners.
RFC-0052 §2, §3.1, §6, §9, §10.4Include core/db.pg bootstrap contributions; separate the seed prerequisite from full-module dependency; define rank groups and repeat-install idempotency; align generation inputs.
RFC-0054 §6Retain five input owners; specify offline seed resolution, provenance, and subset agreement checks.
RFC-0040 manifest contractAdd a typed, versioned bootstrap prerequisite with validation and ownership rules.
Lean, reference catalogs, RDFPropagate each approved statement and refresh source-bound reviews.

Schema naming and protected-template exceptions remain separate decisions. This proposal does not claim an existing compiler implements this sequence.

Acceptance

  • The normal platform manifest graph is acyclic after removing only the bootstrap-satisfied edge; ordinary cycles still fail with M41001.
  • Missing, incompatible, or incomplete core seed prerequisites fail before Phase-2 mutations. Test a same-name seed with differing content.
  • A fresh database can execute the generated Phase-1 artifact and then the complete Phase-2 plan without duplicate declaration identities.
  • Seeded rows and SQL objects agree with the corresponding full-module output.
  • The first Phase-2 install adds intended non-bootstrap artifacts; the second unchanged install has an empty plan.
  • Reordering input manifests leaves the dependency schedule deterministic; core.composition never runs before its core.kind dependency.
  • Bootstrap generation, format-version checks, Lean/reference drift checks, RDF projection checks, and artifact-fed consumer tests all pass.

Alternative: move the full core module into Phase 1 and redesign the remaining install order around it. This expands the bootstrap surface and still requires an offline compilation boundary. The smaller owned seed fits the existing RFC-0054 design and keeps normal module installation responsible for the rest.