RFC-0002 · Compiled Bundle Format
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.
| Status | Draft corpus. Reference catalogs and RDF projections have generation drift checks; Gnomon proofs and projection semantics remain unverified for release. |
|---|
View the generated reference catalog →
Read design questions and decisions →
Status: Draft Owners: Compiler, Runtime Platform
1. Scope
Defines the deterministic compiled output that bridges authoring declarations to install/runtime consumption.
2. Goals
- Deterministic output from same source + config
- Explicit representation of resolved identities and dependencies
- Stable interface for install plan generation and runtime lookup
Linked References
The cross-RFC dependency graph is rendered in reference catalog § Linked References. Out-of-KG pointers to legacy code or external resources, when present, remain in this document under “Source-tree references” below.
3. Invariants
- Compile output for identical inputs (source tree, compiler version, and compile configuration) MUST be byte-identical.
- Every compiled object MUST carry canonical identity metadata.
- Every unresolved reference MUST appear as a diagnostic.
- Bundle format version MUST be explicit.
- All serialized structures in the bundle (objects, diagnostics, import lists, policy envelopes, storage manifest) MUST use canonical ordering (lexicographic by key name or element identity) before serialization to enable byte-identical output.
- Any timestamp, transient identifier (process ID, hostname), or non-deterministic sequence MUST be explicitly excluded from fingerprint computation.
- Any module declaring gnomon kinds MUST include a
storage_manifestin the compiled bundle. Absence of a storage manifest when gnomon kinds are declared MUST produce error M02103. - Storage manifest entries MUST be deterministically ordered by table identity path (lexicographic). Any non-determinism in DDL generation MUST produce a reproducibility diagnostic in category STORAGE_DDL_VARIANCE (M02155).
4. Required Bundle Elements
Every compiled bundle MUST contain the following sections. Sections marked REQUIRED must be present even if empty; sections marked CONDITIONAL must be present if and only if the corresponding declarations exist in source.
| Section | Presence | Contents |
|---|---|---|
metadata | REQUIRED | format version, compiler version, timestamp, source fingerprint (SHA256 of all source files in lexicographic order), determinism flag |
declarations | REQUIRED | resolved object graph: entities, types, facets, flows, policies, agents — all with canonical paths and kind tags |
dependency_map | REQUIRED | resolved versions of all imported modules (see RFC-0014) |
diagnostics | REQUIRED | compiler diagnostic collection; REQUIRED: value MAY be an empty array []; see §6 |
policy_envelopes | CONDITIONAL | one envelope per policy declaration, carrying actor, precondition, and effect bindings |
action_envelopes | CONDITIONAL | one envelope per action declaration, carrying input/output types, preconditions, and effects |
claim_envelopes | CONDITIONAL | one envelope per claim declaration, carrying Claim<T> type, evidence requirements, and allowed status flow reference |
model_declarations | CONDITIONAL | verbatim copy of each model declaration from source (RFC-0008 §6.20): provider, name, digest/version, roles. No model weights or runtime state — authoring-time metadata only |
compiled_rules | CONDITIONAL | for each rule "..." statement that has been compiled: the compiledExpr constraint expression string, the rule text, the rule hash, the model digest, and the template version. Format mirrors the //compiled: structured comment (RFC-0008 §11.3) |
runtime_prompts | CONDITIONAL | for each prompt "..." statement: the verbatim prompt template string and the bound model reference. Runtime evaluates these against the live model at execution time |
composition_envelopes | CONDITIONAL | compiled route/page/layout/widget elements; see §5 |
storage_manifest | CONDITIONAL | REQUIRED when any gnomon kind is declared; see §7 |
5. Identity Contract
Compiled objects MUST include:
- canonical path
- namespace
- kind
- stable external identity where applicable
Identity convergence expectations:
- Authoring identities MUST be normalized into bundle canonical paths.
- Composition-layer exports (route, page, layout, widget) MUST appear in exported identifiers when declared.
- Bundle identifiers MUST be the source of truth for install-plan target identity derivation.
Canonical composition identity shape (required):
<module-namespace>.ui.route.<id><module-namespace>.ui.page.<id><module-namespace>.ui.layout.<id><module-namespace>.ui.widget.<id>
Compilers MUST emit composition-layer exports using the canonical shape above whenever those layers are declared.
Diagnostics
The diagnostic catalog for this RFC is authored in the structured Lean module and
rendered in reference catalog § Diagnostics. Inline mentions in
the prose above (e.g., “rejected with MNNxxx”) cross-link to the catalog
at render time.
7. Storage Manifest
Any module that declares gnomon kinds (RFC-0006 §4.1) MUST include a storage_manifest section in the compiled bundle. The storage manifest is the authoritative specification for all storage objects the install pipeline (RFC-0005) must create, migrate, or drop.
7.1 Storage Manifest Contents
The storage manifest MUST enumerate:
- Base table declarations — the universal gnomon base table schema for this module’s kinds
- Edge table declarations — the gnomon edge table schema for this module’s declared relations (RFC-0007 §6.2)
- Projection table declarations — typed projection tables generated from kind field declarations (RFC-0007 §6.3)
- Support table declarations — embedding, lineage, and observation tables for kinds that declare vector or derivation projections (RFC-0007 §6.4)
- Generated view declarations — SQL view definitions for declared read projections and traversal paths
- Index declarations — indexes required by declared query paths and operator classes
- Migration operations — ordered list of DDL operations required to transition from the prior installed storage state to the current manifest
7.2 Storage Identity Contract
Each storage object in the manifest MUST carry:
storage_path: canonical identity of the form<module-namespace>.storage.<object_type>.<name>object_type: one ofbase_table,edge_table,projection_table,support_table,view,indexkind_path: the gnomon kind or relation that this object serves (resolvable to RFC-0006 declarations)ddl_fingerprint:sha256:<hex>— SHA-256 of the DDL content after stripping comments and normalizing whitespace (collapse runs of whitespace to a single space; trim leading/trailing). Thesha256:prefix is literal. This fingerprint is the tamper-detection mechanism used by the kernel at runtime (RFC-0010 §5.2)migration_mode: one ofcreate,alter,drop,recreate,no_op
Storage paths MUST follow the canonical composition identity shape pattern:
<namespace>.storage.base.<kind_name><namespace>.storage.edge.<relation_name><namespace>.storage.projection.<kind_name><namespace>.storage.support.<kind_name>._support.<name><namespace>.storage.view.<view_name><namespace>.storage.index.<index_name><namespace>.storage.migration.<kind_name>._migrations.<name>
7.3 Storage Manifest Schema (Normative)
storage_manifest:
format_version: "1"
kind_count: 3
objects:
- storage_path: "benefits.storage.base.Employee"
object_type: base_table
kind_path: "benefits.entities.Employee"
ddl_fingerprint: "<hash>"
migration_mode: create
ddl: |
CREATE TABLE benefits_employee (
id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
kind text NOT NULL DEFAULT 'Employee',
identity jsonb,
payload jsonb,
status text NOT NULL,
confidence numeric,
valid_time tstzrange,
system_time tstzrange,
created_at timestamptz NOT NULL DEFAULT now(),
updated_at timestamptz
);
- storage_path: "benefits.storage.projection.Employee"
object_type: projection_table
kind_path: "benefits.entities.Employee"
ddl_fingerprint: "<hash>"
migration_mode: create
ddl: |
CREATE TABLE benefits_employee_projection (
id uuid PRIMARY KEY,
employee_id text NOT NULL,
full_name text NOT NULL,
email text,
employer_id uuid,
hire_date date
);
- storage_path: "benefits.storage.view.EmployeeWithEnrollments"
object_type: view
kind_path: "benefits.entities.Employee"
ddl_fingerprint: "<hash>"
migration_mode: create
ddl: |
CREATE VIEW benefits_employee_with_enrollments AS
SELECT e.*, json_agg(en.*) AS enrollments
FROM benefits_employee_projection e
LEFT JOIN benefits_enrollment_projection en ON en.employee_id = e.id
GROUP BY e.id;
Bitemporal column semantics (normative): The valid_time tstzrange and system_time tstzrange columns that appear in base table DDL carry distinct semantics:
valid_time: tracks when the data is considered true in the real world (business time). Authors setvalid_timewhen writing a value. Insert and update operations setvalid_time.lowerto the transaction timestamp unless an explicit value is provided.system_time: tracks when the row existed in the database (transaction time, append-only).system_time.loweris set by a database trigger at row insertion; it is never set by application code.
Both columns are managed exclusively by the gnomon runtime and its database triggers. Application code MUST NOT write to valid_time or system_time directly. Direct writes to these columns outside the gnomon API MUST be treated as a violation equivalent to a hand-authored projection table write (M07630).
7.4 Migration Safety
dropmigration mode MUST be blocked by the install pipeline unless no live gnomon instances of the affected kind exist (RFC-0005).altermigrations that remove columns MUST be treated as breaking changes and MUST appear in the install plan diff with explicit human approval required.recreatemode (drop + create) MUST NOT be generated automatically; it MUST require explicit authoring intent and produce warning M02156.- The install pipeline MUST validate that migration operations in the manifest are consistent with the prior installed storage manifest before executing any DDL.
8. Security Considerations
- Compiled policy envelopes MUST remain tamper-evident through pipeline boundaries.
- Compiler MUST NOT silently drop policy declarations.
- Authorization propagation artifacts MUST be inspectable.
- Storage manifest DDL MUST be treated as a security-sensitive artifact; modifications outside the compile pipeline MUST be detectable via DDL fingerprint comparison at install time.
9. Compatibility and Migration
- Bundle schema changes MUST increment format version.
- Readers MUST reject incompatible major versions.
- Backward-compat modes SHOULD be time-bounded and explicitly documented.
- Storage manifest format changes MUST increment
storage_manifest.format_versionindependently of the bundle format version.
10. Reproducibility Quality Gates
- Compiler releases SHOULD report reproducibility results for representative bundle sets.
- Reproducibility reporting SHOULD include success rate plus categorized failure counts.
- A baseline reproducibility target of 70 percent or greater SHOULD be treated as a quality gate for release-readiness discussions.
- Storage manifest DDL generation MUST be included in reproducibility reporting; DDL variance MUST be tracked as category STORAGE_DDL_VARIANCE (M02155).
11. Diagnostic Codes (RFC-0002 Allocation)
M020x: Identity and bundle structure
- M02100: Missing required bundle element
- M02101: Invalid bundle format version declaration
- M02102: Unresolved required identity export
- M02103: Gnomon kinds declared but storage manifest absent
M015x: Reproducibility and determinism
- M02150: TIMESTAMP_EMBEDDED
- M02151: TOOLCHAIN_VARIANCE
- M02152: LOCALE_DEPENDENT
- M02153: FILESYSTEM_ORDER
- M02154: OTHER
- M02155: STORAGE_DDL_VARIANCE
M016x: Storage manifest
- M02160: Storage object missing required field (
storage_path,object_type, orkind_path) - M02161: Storage path does not follow canonical naming pattern
- M02162: DDL fingerprint mismatch between manifest and installed state at install time
- M02163: Migration mode
dropblocked — live gnomon instances exist - M02164: Migration mode
altercontains column removal — requires explicit approval - M02165: Migration mode
recreaterequires explicit authoring intent (warning) - M02166: Cross-module kind reference in storage manifest not satisfied at install time — referenced module not installed or kind not found
Appendix A: Optional and Deferred Items (Non-Normative)
Optional follow-on work (not required for RFC-0002 closure):
- Independent rebuilder/verifier interface metadata for distribution pipelines.
- Supply-chain-oriented distribution attestations tied to bundle fingerprints.
Deferred research:
- Determinism boundary analysis for semantic-AST canonicalization versus full source normalization.
- Automated security signal extraction from reproducibility divergence patterns.