Configuration Compiler v1.0¶

This document defines the strict boundaries and invariants for the Configuration Compiler pipeline (formerly Bootstrap). The Configuration Compiler is an independent architectural layer that compiles source definitions and external state into a deterministic, immutable artifact set. It must pass deterministically before the Operations runtime can begin.

1. Architectural Invariants¶

Configuration Compiler is Runtime-Agnostic. It produces artifacts (lockfiles, environment mappings, manifests). It NEVER calls the Docker runtime or docker compose config. It ends with a PASS/FAIL receipt.
Operations Validation. The Operations layer takes the artifacts produced by the compiler and performs runtime-specific validation (e.g., docker compose config).
Fail Fast. If the secret inventory is incomplete, the compiler halts. There is no partial compilation.
Target-Driven Compilation. Profiles (e.g., observability, production, ci) are deterministic compilation targets.

2. Macro Architecture¶

Internet
   ↓
Connectors
   ↓
Snapshots
   ↓
Evidence
   ↓
Knowledge Graph
   ↓
Decision Engine
   ↓
Reference Architecture
   ↓
Reference Stack
   ↓
Configuration Compiler     <-- (We are here)
   ↓
Operations Runtime
   ↓
Governance Runtime
   ↓
Execution Runtime

3. The 5-Stage Compiler Pipeline¶

0.1 Source Inventory¶

Inputs: docker-compose.yml, .env.template
Action: Ensure the source files exist and are syntactically well-formed.

0.2 Secret Reference Validation¶

Inputs: 1Password Vault, .env.template
Action: Verify every op:// reference points to a valid item via direct 1Password Connect/SDK/CLI lookup. Never generate a .op-env file, and never materialize a .env file containing resolved secret values to disk — per STD-AUTH-001 (.op-env is forbidden), validate references directly and consume secrets only within op run process boundaries.

0.3 Environment Validation (Secret Coverage)¶

Inputs: .env.template, live 1Password reference-validation results (no intermediate file)
Action: Produce a machine-readable Secret Coverage Receipt mapping every requested variable to its validated reference status, source vault, and BCKG Evidence pointer.

0.4 Lockfile Generation¶

Inputs: docker-compose.yml, target profile
Action: Hash the inputs and generate an immutable compose.lock.yaml that includes checksums, compiler version, and build IDs.

0.5 Registry Object Generation¶

Action: Emit a RUN object (e.g., RUN-000021) as a first-class registry artifact for the Bluefly Core Knowledge Graph (BCKG).

4. Schemas¶

4.1 First-Class Registry Object (`RUN-XXXXX`)¶

The compiler generates a RUN node in the Knowledge Graph:

id: RUN-000021
compiler_version: 1.0.0
ontology_version: 1.0
rule_version: 1.0
projection_version: 1.0
inputs:
  - SRC-000012
  - SNAP-000083
outputs:
  - ENV-000031
  - LOCK-000014
status: PASS

4.2 Bootstrap Receipt Schema (`bootstrap_receipt.yaml`)¶

schema: 1.1
phase: Configuration Compiler
build_id: RUN-000021
status: PASS
variables:
  - name: POSTGRES_PASSWORD
    status: resolved
    source: BlueflyAgents
    evidence: EVID-00142
    checksum: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
summary:
  required: 42
  resolved: 42
  missing: 0

4.3 Immutable Lockfile (`compose.lock.yaml`)¶

This file is treated like Cargo.lock or composer.lock. If inputs don't change, this file never changes.

# Generated by Configuration Compiler v1.0.0
# Build ID: RUN-000021
# SHA256: 8a7f0e6c2...

5. BCKG Integration¶

The Configuration compiler connects to the graph: - RUN → generated → ENV - RUN → generated → LOCK - RUN → used → SRC - RUN → validated → PROFILE

6. Compatibility¶

Breaking changes to this interface require: - A schema version increment (e.g., v2.0). - Explicit updates to the CI/CD deployment pipelines.