Compiled bundle contract decision
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. Owner: Compiler, Runtime Platform, and specification maintainers. The authored RFC, Lean catalog, and bundle schema are unchanged. Two RDF provenance links were corrected from §6 to authored §11 without changing claim IRIs or normative values. Five companion QA answers are preserved as prior answers and reopened because the claimed normative sections do not implement them.
Source conflicts
| Topic | Current authored RFC-0002 | Prior companion QA answer |
|---|---|---|
| Fingerprint | §4 calls source fingerprint SHA-256 of all source files in lexicographic order; §3 excludes volatile data from fingerprint computation. | Semantic AST of each bundle section, insensitive to comments and formatting; cites §5, which specifies identity rather than fingerprinting. |
| Minimal runtime | §4 requires metadata, declarations, dependency_map, and diagnostics in every bundle; it defines no kernel section. | Identity envelope plus kernel section are mandatory; other sections optional. |
| Install-plan-only | The same §4 required sections apply; migration operations live within conditional storage_manifest (§7.1). | Identity envelope, storage manifest, and separate migration-operations section suffice; kernel omitted. |
| DDL packaging | Normative §7.3 embeds ddl: text beside each storage object; §7.2 requires a DDL fingerprint. | Full DDL belongs in a separate storage.sql artifact and the manifest carries a strategy field. |
| Cross-module kind references | §7.1–7.2 enumerate storage objects and fields but no cross_module_ref entry; §11 allocates M02166. | Manifest records cross_module_ref with kind FQN and source-module fingerprint, and install validates it. |
There is also a reproducibility conflict within the authored RFC: §3 requires byte-identical output for identical source and configuration, while §4 requires a timestamp in bundle metadata. If the timestamp is the current wall clock and is serialized into the canonical bundle, both rules cannot hold.
Source-bound RDF review found two §4 projection overstatements. The diagnostics
claim uses defaults-to [] where the source only allows an empty array; the
source-fingerprint claim asserts raw file concatenation although §4 specifies
no byte framing or path encoding. Neither triple should be changed until the
bundle schema and fingerprint algorithm are decided and consumer effects are
measured (PROJECTION_GAPS.md).
The projection review also found eight §6 aspect, diagnostic, facet, and serialization claims supported only by the Lean catalog. Authored §6 does not state those rules. Before publishing them as normative, either add exact authored clauses and implementation tests or withdraw the unsupported claims; do not treat generated catalog text alone as author approval.
In §7, the authored manifest requires ordered migration operations and names
storage.migration paths, but its object_type enum excludes migration and
its normative example has no operation entry. Define a separate typed,
ordered migration_operations field and its path and version rules before
claiming compiler/install interoperability. The §7 RDF bitemporal prohibition
also reverses actor and target in its structured relationship, although its
prose matches the RFC. The triple should be corrected with consumer review.
The remaining §8–10 RDF review found seven more subject mismatches. Compiler
policy handling, authorization artifacts, bundle readers, compatibility modes,
reproducibility reports, release-readiness targets, and DDL generation should
each be modeled as the actor or target named by the authored clause. The
current triples place several of those behaviors on a policy envelope,
BundleFormatVersion, a compiled bundle, or a storage-manifest declaration.
Keep the authored claim text and stable claim IRIs while proposing corrected
relationships, then compare local and external query results before release.
The full RFC-0002 domain projection review found twelve additional source mismatches. The immediate model questions are the Operations-versus-Composition classification of action, claim, and policy envelope sections; an authored Diagnostic field schema; the direct/outside-API qualifier on bitemporal writes; and one permanent recreate warning code. Resolve those in the same versioned contract pass as the claim relationships so generated reference and RDF consumers see one coherent release. The exact eight-claim mapping and 16-query counterfactual are in RFC0002_RDF_MODEL_PROPOSAL.md.
Recommended architecture
- Define one canonical full bundle with an explicit versioned schema. Keep §4’s four required sections until a migration is approved. Define runtime and install-plan views of that bundle as named profiles with required fields and allowed omissions, rather than calling structurally different payloads the same bundle. Do not claim a kernel section or a separate migration-operations section until the schema defines it.
- Distinguish a
source_fingerprintover exact source bytes from asemantic_fingerprintover a canonical semantic AST. Both must name their inputs, ordering, algorithm, and normalization rules. Keep wall-clock build provenance outside the canonical byte-identical payload, or make the timestamp a deterministic explicit compile input. Version any fingerprint whose meaning changes; never reuse one field name for a new algorithm. - Choose exactly one DDL distribution contract. A content-addressed
storage.sqlsidecar can keep the bundle small, but the bundle must carry its digest and artifact identity, and install must verify both before any DDL runs. Until that atomic artifact path is implemented and tested, the existing embeddedddl:form is the only authored normative shape. A migration may support both with an explicit format version and one canonical fingerprint rule. - Add
cross_module_refonly with a typed schema, exact ownership and fingerprint semantics, import reconciliation, and M02166 install behavior. The reference must be included in determinism and compatibility tests.
Acceptance
- Amend RFC-0002 §§3–7, the bundle schema, Lean catalog, diagnostics, QA, and generated reference/RDF artifacts together. Resolve the separate M02156 versus M02165 warning identity before publishing the diagnostic catalog.
- Compile the same inputs twice under different wall-clock times and compare canonical bytes and both fingerprints. Change only whitespace/comments and verify the documented source/semantic fingerprint distinction. Test locale, filesystem order, and toolchain inputs as the RFC requires.
- Validate full, runtime, and install-plan profiles against explicit schemas; test rejection of missing required sections and incompatible major versions.
- If DDL moves to a sidecar, test missing, swapped, and modified artifacts and atomic install behavior. Test cross-module import and kind resolution before DDL execution, including M02166 and persisted bundle compatibility.
- Inventory compiler emitters, install readers, stored bundles, and external consumers before changing public field names or RDF identities. Publish a versioned migration and rollback path.