gnomonlearn
Docs/RFC-0002/Design Q&A

RFC-0002 · 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

Five earlier answers are retained below as prior decisions but reopened for source reconciliation. The exact contract differences and acceptance tests are in BUNDLE_CONTRACT_PROPOSAL.md.

Q: Should bundle fingerprint include normalized whitespace or semantic AST only?

Status: Open Prior answer: Semantic AST only; whitespace and comment differences would not affect the fingerprint. Issue: RFC-0002 §4 defines a source fingerprint over source files, while §5 is the identity contract and does not define semantic-AST fingerprinting. The prior answer changes a published field’s meaning. Recommendation: Define separate source and semantic fingerprints with versioned inputs and normalization rules; reconcile the timestamp/byte-identity conflict in §§3–4.

Q: Which sections are mandatory for minimal runtime mode?

Status: Open Prior answer: An identity envelope and kernel section are mandatory for all runtime modes, with conditional storage and composition sections. Issue: RFC-0002 §4 requires metadata, declarations, dependency_map, and diagnostics in every bundle and does not define a kernel section. The cited §3 is the invariants section. Recommendation: Keep the canonical full-bundle schema explicit and define a separately versioned runtime view if smaller payloads are needed.

Q: What subset is required for install-plan-only workflows?

Status: Open Prior answer: Identity envelope, storage manifest, and a separate migration-operations section suffice; kernel is omitted. Issue: RFC-0002 §4’s four required sections still apply, and §7.1 places migration operations inside storage_manifest rather than a separate section. Recommendation: Define an install-plan view with a typed minimum schema and versioned extraction from the canonical bundle.

Q: Should the storage manifest include the full DDL text, or only a normalized fingerprint with the DDL emitted as a separate artifact?

Status: Open Prior answer: The manifest carries a DDL fingerprint and strategy, while full DDL is emitted as a separate storage.sql artifact. Issue: RFC-0002 §7.3’s normative schema embeds ddl text in each storage object; §7.2 defines a fingerprint but no strategy field. Section 6 is not the storage-manifest section. Recommendation: Keep the embedded form until a content-addressed sidecar, atomic distribution, and install-time digest validation are specified and tested.

Q: Which warning identifies a recreate migration that requires explicit authoring intent?

Status: Open Issue: §7.4 and its extracted normative statement name M02156, while §11, the Lean diagnostic catalog, and the generated reference catalog name M02165 for the same condition. Both identities are present in generated RDF claims. The local consumer search found no executable emitter for either identity, but it does not cover stored or external diagnostics. The owner must select one permanent identity after that consumer review, amend the authored clause and structured catalog together, and regenerate the RDF and reference projections. Do not register both codes as independent warnings for the same condition.

Where normative: §7.4 and §11 of RFC-0002; lean/Gnomon/Spec/Foundation/Rfc0002.lean diagnostic catalog

Q: How are migration operations represented in the storage manifest?

Status: Open Issue: §7.1 requires an ordered migration-operation list and §7.2 assigns storage.migration paths, but the six-value object_type enum excludes migration and §7.3 shows only storage objects. A compiler and installer cannot validate the same manifest shape until the operation schema and its relation to objects are specified. Recommendation: Define a typed ordered migration_operations field separate from the six physical object types, with stable path identity, prior-manifest checks, and explicit handling of create, alter, drop, recreate, and no_op. Version the schema and test compiler/installer round trips before publishing it as normative.

Where normative: §7.1–7.4 of RFC-0002

Q: How should the storage manifest handle cross-module kind references (a kind in module A referenced as a relation target in module B)?

Status: Open Prior answer: A cross_module_ref entry carries the foreign kind FQN and source-module fingerprint; install verifies the referenced module and kind before DDL, using M02166 on failure. Issue: RFC-0002 §7.1–7.2 has no cross_module_ref schema or fingerprint rule, although §11 allocates M02166. The cited §6 is not the storage-manifest section. Recommendation: Define the typed entry and install check alongside import resolution before treating the prior answer as normative.