Skip to content

ADR-008: POLARIS (ice_ext) Absorption + Stable Bridge Promotion

Date: 2026-04-22 Status: Accepted Decision-makers: FCC core maintainers · KGSE (Knowledge-Graph Serializer Elevator) persona · LTAS (Long-Term Archive Steward) persona Consulted: ice_ext (POLARIS) maintainers · Research Center — Zachman cross-cut alignment Informed: Patent counsel (ice_ext structural-concept IP posture) · All downstream archive consumers

Context and Problem Statement

ice_ext (codename POLARIS) implements a Model Creation and Management Extension based on the structural concepts described in patent US20250272473A1. By early 2026-Q2 it had matured enough to offer FCC five concrete integration asks, documented in its STATUS.md as "Open items for FCC":

  1. Vendor ice_ext's element_mapping.yaml into FCC's objectmodel tree so ice_ext's own CI could SHA-drift check against an upstream copy.
  2. Register ice_ext as a Tier-1-Strict ecosystem partner in FCC's authoritative registries.
  3. Establish reciprocal CI workflows so both sides exercise each other's tests on every commit.
  4. Promote FCC's JSONLDSerializer + RDFSerializer into the stable public fcc.api.knowledge namespace so ice_ext could depend on them without tracking private-API churn.
  5. Absorb four upstream patterns — Zachman 6×6 classification cross-cut, SHA-256 vocabulary-drift sentinel, three-layer documentation convention, and a SAFe ↔ FCC vocabulary reconciliation table — into FCC directly, making FCC the canonical home for each pattern.

Separately, ice_ext had begun asking consumers to depend on a POLARIS archive abstraction that in turn depends on ice_ext's live adapter. The cleanest way to let downstream projects target "POLARIS archive" without coupling to ice_ext's private repo was for FCC to publish a bridge protocol + mock fallback pattern (the same sentinel-guarded approach already used for distiller_bridge).

The decision was whether to absorb ice_ext's five requests in full, or to stay at arm's length and treat POLARIS as an external dependency.

Decision Drivers

  • Ecosystem coherence. If FCC owns the canonical Zachman cross-cut, all 164 personas can carry zachman_cell uniformly.
  • Patent posture. ice_ext implements US20250272473A1 structural concepts privately; FCC's patent-counsel-gated FTO posture must be preserved — FCC carries interface contracts, not the protected implementation.
  • Bridge-pattern consistency. Distiller, LYRA, and POLARIS all deserve the same availability-sentinel bridge treatment; making POLARIS the third such bridge normalises the ecosystem pattern.
  • Manifest discipline. Archive operations have strong manifest requirements (tar-manifest audit trail, archive-id assignment); a dedicated persona (LTAS) needs to own that contract on the FCC side.
  • Back-compat. Consumers that import v1_5_preview.polaris_bridge in v1.4.x must continue to work for at least one minor after promotion.

Considered Options

  1. Stay at arm's length. Leave POLARIS as an external repository FCC knows about but doesn't absorb. Require consumers to depend on ice_ext directly for Zachman + archive semantics.
  2. Absorb ice_ext's five asks in full but do not promote the bridge yet. Keep PolarisBridgeProtocol + PolarisMockBridge under the preview namespace (fcc.plugins.v1_5_preview.polaris_bridge).
  3. Absorb + promote to stable fcc.api.archive. Absorb all five asks in v1.4.1, ship the bridge scaffolding in the preview namespace, then promote the bridge to stable in v1.5.0 with a read-compat re-export from the preview path.
  4. Merge ice_ext into FCC. Full repo consolidation.

Decision

We adopt option 3, in two phases.

Phase 1 (v1.4.1) — absorption. All five ice_ext STATUS.md items close:

  1. src/fcc/data/objectmodel/ice_ext_element_mapping.yaml vendored with SHA-drift test.
  2. ice_ext registered as Tier-1-Strict in the ecosystem-projects overlay with role "Model Creation and Management extension — implements US20250272473A1 structural concepts with Zachman classification cross-cut".
  3. .github/workflows/ice-ext-integration.yml (advisory in v1.4.1.x)
  4. make ice-ext-integration target.
  5. JSONLDSerializer + RDFSerializer promoted into fcc.api.knowledge — public SemVer 1.x symbols, migration guide at docs/migrations/v1.4.1-api-additions.md.
  6. Four upstream patterns absorbed:
  7. Zachman 6×6 classification cross-cut — src/fcc/classification/ (322-LoC zachman.py + 78-LoC loader + 132-LoC taxonomy YAML). FCC becomes the canonical classifier; ice_ext re-imports from fcc.classification in its next release. fcc audit zachman CLI added.
  8. SHA-256 Vocabulary Drift Sentinel — src/fcc/validation/vocabulary_drift.py generalises ice_ext's verify_upstream_sha256 across all 13+ VocabularyProviders.
  9. Three-layer doc convention explicit: ROADMAP → Emergent Design (Layer 1), STRATEGIC_ARCHITECTURE_REVIEW → Intentional Architecture (Layer 2), AGENTS.md → Protocol Architecture (Layer 3).
  10. SAFe ↔ FCC vocabulary reconciliation table at docs/safe/safe-fcc-vocabulary.md (canonical).

Phase 2 (v1.5.0) — stable bridge promotion. PolarisBridgeProtocol, PolarisMockBridge, and get_polaris_bridge() graduate from fcc.plugins.v1_5_preview.polaris_bridge to src/fcc/archive/polaris_bridge.py. Re-exports from the preview path are preserved for one minor (v1.5.x) as read-compat. The new LTAS (Long-Term Archive Steward) persona owns the manifest- discipline contract on the FCC side; the new KGSE (Knowledge-Graph Serializer Elevator) persona coordinates the elevation into fcc.api.* and guards against similar future promotions.

Per v1.5.0, fcc.api.archive exposes PolarisBridgeProtocol, PolarisMockBridge, and get_polaris_bridge. PolarisMockBridge is an in-memory dict keyed by archive-<sha256[:16]> covering the full push/pull/query protocol — consumers get full functional behaviour even when the live ice_ext.plugin.bridge.ICEFacadeAdapter is not importable.

Consequences

Positive

  • Canonical home for Zachman cross-cut. All 164 personas can (and must) carry zachman_cell; ice_ext re-imports from FCC cleanly.
  • Patent-posture preserved. FCC ships interface contracts + mocks; the protected US20250272473A1 implementation stays in ice_ext.
  • Bridge pattern normalised. Distiller + POLARIS + LYRA all use the same sentinel-guarded import + mock-fallback pattern.
  • Consumer clarity. fcc.api.archive is a stable SemVer 1.x import; consumers don't track preview-namespace churn.
  • Closed coordination debt. All 5 STATUS.md open items closed in one release (v1.4.1).

Negative

  • Coupling to private-repo cadence. ice_ext is a private repository with owner-approval-gated pushes; some follow-on work (FTO counsel, cross-repo re-import) remains gated.
  • Dual-write period. v1_5_preview.polaris_bridge continues to resolve during v1.5.x; the preview namespace isn't removed until v1.6.0.
  • Coordination cost. ice_ext's STATUS.md §n asks are tracked by KGSE, which adds a named role to the governance surface.

Confirmation

  • tests/test_v1_5_preview_polaris.py (v1.4.4, +21 tests with LYRA) — 100% line + branch coverage on the mock bridge.
  • v1.5.0 promotion landed with full re-export compatibility test suite.
  • make ice-ext-integration runs the sibling pytest locally; skips gracefully when ice_ext is not checked out.
  • fcc audit zachman CLI exercises the canonical classifier against all 164 personas; zero findings on v1.5.0 main.

References

  • src/fcc/classification/zachman.py — canonical classifier
  • src/fcc/validation/vocabulary_drift.py — SHA-256 drift sentinel
  • src/fcc/archive/polaris_bridge.py — stable bridge (v1.5.0)
  • src/fcc/plugins/v1_5_preview/polaris_bridge.py — preview (v1.4.1)
  • src/fcc/data/objectmodel/ice_ext_element_mapping.yaml — vendored
  • src/fcc/data/ecosystem/ecosystem_projects_overlay.yaml — ice_ext Tier-1-Strict registration
  • .github/workflows/ice-ext-integration.yml — reciprocal CI
  • docs/migrations/v1.5.0-api-additions.md — bridge-promotion migration guide
  • CHANGELOG [1.4.1] §ice_ext/POLARIS coevolution + [1.5.0] §POLARIS + LYRA stable bridge promotion
  • New personas: LTAS, KGSE
  • US20250272473A1 — ice_ext structural-concept patent (external authority)