CipherShift365 -- Architecture Decisions
ADR Index
| ADR | Title | Status |
|---|---|---|
| ADR-001 | Shared Core split: lightweight runtime Core + build-time Analysis Engine | Accepted |
| ADR-002 | Analysis Engine as a shared component (Compass + gate) | Accepted |
| ADR-003 | AOT-compatible provider resolution; AOT scope = runtime only | Accepted |
| ADR-004 | IP-protection depth = moderate | Accepted |
| ADR-005 | Baseline distribution to runtime hosts | Accepted |
| ADR-006 | Runtime KB = classification subset, encrypted | Accepted |
| ADR-007 | CBOM signing-key custody in the build zone | Accepted |
| ADR-008 | Air-gapped deployment variant | Accepted |
ADR-001 -- Shared Core Split
Context: All three modules depend on Core; Vault ships into customers' production applications; the static Analysis Engine (Roslyn) is heavy.
Decision: Split Core into (a) a lightweight runtime Core -- CBOM model, identity, risk model, signing/verification, KB interface, policy -- packaged for runtime and AOT; and (b) the Analysis Engine as a separate build-time-only package. Vault depends only on (a).
Consequences: Production hosts never carry a compiler; clean dependency hygiene; two package families to version.
ADR-002 -- Analysis Engine as Shared Component
Context: Guardian's gate must "reuse the Compass engine."
Decision: The Analysis Engine is a standalone shared library consumed by Compass (CLI + CI task) and Guardian's gate; neither module depends on the other's host package.
Consequences: A single source of analysis truth; gate/listener classification parity is natural.
ADR-003 -- AOT-Compatible Provider Resolution
Context: Vault resolves providers/algorithms from configuration; Native AOT restricts runtime reflection.
Decision: Provider/algorithm resolution uses source generators / explicit registration, never runtime reflection. Native AOT applies to runtime components only; build-time tools remain standard JIT/managed.
Consequences: AOT-safe SDK with runtime footprint benefits; source generation adds some build complexity.
ADR-004 -- IP-Protection Depth = Moderate
Context: The KB is the moat but ships client-side.
Decision: Moderate posture: sign all artifacts; encrypt KB at rest, decrypt in memory; Native AOT + light obfuscation for runtime; do not pursue heavy commercial obfuscation; keep durable moat off-client (curated corpus, update cadence, research, services).
Consequences: Raises extraction cost without a false sense of security.
ADR-005 -- Baseline Distribution to Runtime
Context: The approved baseline is produced in the build zone but consumed by the runtime listener for drift comparison.
Decision: The approved, signed baseline is distributed to runtime hosts -- bundled at deploy time or pulled from a read-only signed baseline store at listener startup; the listener verifies the signature before use.
ADR-006 -- Runtime KB = Classification Subset, Encrypted
Context: The listener needs Core + KB for classification parity; shipping the full KB to every host widens IP exposure.
Decision: Ship only the classification subset of the KB to runtime hosts (what is needed to classify observed crypto -- not the full recommendation/migration corpus), encrypted at rest.
ADR-007 -- CBOM Signing-Key Custody in Build Zone
Context: CBOM signing happens in the build zone; the signing private key is a high-value credential.
Decision: Custody the signing private key in a build-zone HSM or CI secret store, isolated from runtime key-store credentials.
ADR-008 -- Air-Gapped Deployment Variant
Context: Some regulated/government buyers forbid any outbound connection.
Decision: Support a fully air-gapped topology where signed KB updates are sideloaded (manual import), verified fail-closed before apply.
Consequences: Broadens the addressable market to high-assurance buyers.