RFC-0002 · Reference catalog
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.
Generated reference catalog. This page renders structured Lean data for RFC-0002: defined terms, diagnostics, dependencies, and invariants. It does not establish proof coverage or runtime conformance. The authored narrative lives in
RFC-0002.This page is generated from the
lean/Gnomon/Spec/module for RFC-0002. Edit that source and regenerate this catalog.
Title: Compiled Bundle Format
Status: draft
Owners: Compiler, Runtime Platform
Proof citations in source: 20 / 20. Standalone proof verification is pending.
Definitions
(none defined)
Diagnostics
| Code | Severity | Description |
|---|---|---|
M02100 | Error | Missing required bundle element |
M02101 | Error | Invalid bundle format version declaration |
M02102 | Error | Unresolved required identity export |
M02103 | Error | Gnomon kinds declared but storage manifest absent |
M02150 | Warning | TIMESTAMP_EMBEDDED — reproducibility failure due to embedded timestamp |
M02151 | Warning | TOOLCHAIN_VARIANCE — reproducibility failure due to toolchain variance |
M02152 | Warning | LOCALE_DEPENDENT — reproducibility failure due to locale dependence |
M02153 | Warning | FILESYSTEM_ORDER — reproducibility failure due to filesystem ordering |
M02154 | Warning | OTHER reproducibility/determinism failure category |
M02155 | Warning | STORAGE_DDL_VARIANCE — non-determinism in storage DDL generation |
M02160 | Error | Storage object missing required field (storage_path, object_type, or kind_path) |
M02161 | Error | Storage path does not follow canonical naming pattern |
M02162 | Error | DDL fingerprint mismatch between manifest and installed state at install time |
M02163 | Error | Migration mode drop blocked — live gnomon instances exist |
M02164 | Error | Migration mode alter contains column removal — requires explicit approval |
M02165 | Warning | Migration mode recreate requires explicit authoring intent |
M02166 | Error | Cross-module kind reference in storage manifest not satisfied at install time |
Invariants
- All serialized bundle structures MUST use canonical (lexicographic) ordering before serialization to enable byte-identical output. (enforced by: compile-time)
- Any module declaring gnomon kinds MUST include a storage_manifest in the compiled bundle, else error M02103. (enforced by: compile-time)
- Aspect merge order must be deterministic and explainable across runs. (enforced by: compile-time)
- Bundle format version MUST be explicit. (enforced by: compile-time)
- Bundle schema changes MUST increment format version; readers MUST reject incompatible major versions. (enforced by: compile-time + runtime)
- Compile output for identical inputs (source tree, compiler version, compile configuration) MUST be byte-identical. (enforced by: compile-time)
- Compiled policy envelopes MUST remain tamper-evident through pipeline boundaries. (enforced by: compile-time + install-time)
- Compiler MUST NOT silently drop policy declarations. (enforced by: compile-time)
- Compilers MUST apply the deterministic aspect/facet merge algorithm (selector specificity, lexicographic identity, declared mode semantics, lexicographic key canonicalization) before serialization. (enforced by: compile-time)
- Diagnostics MUST be serialized in canonical order (source path UTF-8, line, column) and duplicates emitted only once. (enforced by: compile-time)
- Every compiled object MUST carry canonical identity metadata. (enforced by: compile-time)
- Every unresolved reference MUST appear as a diagnostic. (enforced by: compile-time)
- Storage manifest DDL is security-sensitive; modifications outside the compile pipeline MUST be detectable via DDL fingerprint comparison at install time. (enforced by: install-time)
- Storage manifest entries MUST be deterministically ordered by table identity path; DDL non-determinism MUST produce STORAGE_DDL_VARIANCE (M02155). (enforced by: compile-time)
- The install pipeline MUST validate that migration operations are consistent with the prior installed storage manifest before executing any DDL. (enforced by: install-time)
- Timestamps, transient identifiers, and non-deterministic sequences MUST be excluded from fingerprint computation. (enforced by: compile-time)
- alter migrations that remove columns MUST be treated as breaking and require explicit human approval in the install plan diff. (enforced by: install-time)
- drop migration mode MUST be blocked by the install pipeline unless no live gnomon instances of the affected kind exist. (enforced by: install-time)
- recreate mode MUST NOT be auto-generated and requires explicit authoring intent, producing warning M02156. (enforced by: compile-time)
- storage_manifest.format_version MUST be incremented independently of the bundle format version. (enforced by: compile-time)
- valid_time and system_time columns are managed exclusively by the gnomon runtime and triggers; application writes MUST be treated as a violation (M07630). (enforced by: DB-trigger + runtime)
Normative Statements
Statements are structured source data. Proof citations, where present, have not passed a standalone Gnomon proof gate.
Compatibility and Migration
- SHOULD — Backward-compat modes SHOULD be time-bounded and explicitly documented.
- MUST — Bundle schema changes MUST increment format version. (proof citation:
rfc0002_schema_change_increments_version; verification pending) - MUST — Readers MUST reject incompatible major versions.
- MUST — Storage manifest format changes MUST increment storage_manifest.format_version independently of the bundle format version.
Diagnostics Contract
- MUST — Bundle diagnostics MUST preserve source mapping to author files.
- MUST — Compilers MUST apply the deterministic aspect/facet merge ordering algorithm before serialization.
- SHOULD — Compilers SHOULD emit both category and mapped code when reporting determinism failure. (proof citation:
rfc0002_diagnostic_category_and_code; verification pending) - SHOULD — Determinism failure diagnostics SHOULD include a reproducibility category.
- MUST — Diagnostics MUST be serialized in canonical order by source path, line, then column.
- MUST — Duplicate diagnostics MUST be emitted only once. (proof citation:
rfc0002_b55_grounded; verification pending) - MUST — Facet declarations MUST serialize deterministically by facet identity path.
Identity Contract
- MUST — Authoring identities MUST be normalized into bundle canonical paths.
- MUST — Bundle identifiers MUST be the source of truth for install-plan target identity derivation.
- MUST — Compiled objects MUST include canonical path, namespace, kind, and stable external identity where applicable. (proof citation:
rfc0002_b2_grounded; verification pending) - MUST — Compilers MUST emit composition-layer exports using the canonical shape when declared. (proof citation:
rfc0002_composition_exports_canonical; verification pending) - MUST — Composition-layer exports MUST appear in exported identifiers when declared. (proof citation:
rfc0002_composition_exports_in_identifiers; verification pending)
Invariants
- MUST — All serialized bundle structures MUST use canonical ordering before serialization.
- MUST — Bundle format version MUST be explicit.
- MUST — Compile output for identical inputs MUST be byte-identical.
- MUST — Every compiled object MUST carry canonical identity metadata. (proof citation:
rfc0002_b18_grounded; verification pending) - MUST — Every unresolved reference MUST appear as a diagnostic. (proof citation:
rfc0002_b30_grounded; verification pending) - MUST — Modules declaring gnomon kinds MUST include a storage_manifest; absence MUST produce M02103. (proof citation:
rfc0002_storage_manifest_required; verification pending) - MUST — Storage manifest entries MUST be deterministically ordered by table identity path.
- MUST — Timestamps and transient identifiers MUST be excluded from fingerprint computation.
Reproducibility Quality Gates
- SHOULD — A baseline reproducibility target of 70 percent or greater SHOULD be treated as a release-readiness quality gate.
- SHOULD — Compiler releases SHOULD report reproducibility results for representative bundle sets.
- SHOULD — Reproducibility reporting SHOULD include success rate plus categorized failure counts.
- MUST — Storage manifest DDL generation MUST be included in reproducibility reporting under category STORAGE_DDL_VARIANCE.
Required Bundle Elements
- MUST — CONDITIONAL sections MUST be present iff corresponding declarations exist in source.
- MUST — Every compiled bundle MUST contain the enumerated required sections. (proof citation:
rfc0002_bundle_required_sections; verification pending)
Security Considerations
- MUST — Authorization propagation artifacts MUST be inspectable. (proof citation:
rfc0002_authorization_artifacts_inspectable; verification pending) - MUST — Compiled policy envelopes MUST remain tamper-evident through pipeline boundaries.
- MUST_NOT — Compiler MUST NOT silently drop policy declarations. (proof citation:
rfc0002_b34_grounded; verification pending) - MUST — Storage manifest DDL MUST be treated as security-sensitive and detectable via DDL fingerprint comparison at install time.
Storage Manifest
- MUST_NOT — Application code MUST NOT write to valid_time or system_time directly. (proof citation:
rfc0002_no_direct_bitemporal_writes; verification pending) - MUST — Direct writes to bitemporal columns outside the gnomon API MUST be treated as M07630 violations. (proof citation:
rfc0002_bitemporal_writes_diagnostic; verification pending) - MUST — Each storage object MUST carry storage_path, object_type, kind_path, ddl_fingerprint, and migration_mode.
- MUST — Modules declaring gnomon kinds MUST include a storage_manifest section in the compiled bundle. (proof citation:
rfc0002_storage_manifest_in_bundle; verification pending) - MUST — Storage paths MUST follow the canonical composition identity shape pattern. (proof citation:
rfc0002_b52_grounded; verification pending) - MUST — The install pipeline MUST validate manifest migrations against the prior installed storage manifest before executing DDL.
- MUST — The storage manifest MUST enumerate base, edge, projection, support tables, views, indexes, and migrations. (proof citation:
rfc0002_storage_manifest_complete; verification pending) - MUST — alter migrations removing columns MUST require explicit human approval in the install plan diff. (proof citation:
rfc0002_b41_grounded; verification pending) - MUST — drop migration mode MUST be blocked unless no live gnomon instances of the affected kind exist. (proof citation:
rfc0002_drop_blocks_with_live_instances; verification pending) - MUST_NOT — recreate mode MUST NOT be generated automatically and MUST produce warning M02156. (proof citation:
rfc0002_recreate_no_auto; verification pending)
Linked References
(no cross-RFC dependencies)