POLARIS Bridge¶

The POLARIS bridge is FCC's seam to the long-term model archive provided by ice_ext.plugin.bridge.ICEFacadeAdapter. v1.5.0 promoted the preview surface at fcc.plugins.v1_5_preview.polaris_bridge to a stable public import path at src/fcc/archive/polaris_bridge.py, which re-exports from the preview module so in-flight callers migrate on their own schedule. From v1.5.0 onward these symbols carry the same 1.x SemVer guarantee as every other fcc.api.* surface — ADR-008 captures the decision to absorb the POLARIS interaction pattern into FCC.

The diagram below details the protocol, the mock implementation, the no-op fallback, and the accessor that chooses between live and fallback paths.

classDiagram
    class PolarisBridgeProtocol {
        <<Protocol>>
        +push_archive(manifest_path: Path) str
        +pull_archive(archive_id: str) Path
        +query_models(**filters) list~dict~
    }

    class PolarisMockBridge {
        -_store : dict[str, dict]
        +push_archive(manifest_path) str
        +pull_archive(archive_id) Path
        +query_models(**filters) list~dict~
        -_compute_archive_id(path) str
    }

    class NoOpPolarisBridge {
        -_UNAVAILABLE_MSG : str
        +push_archive(manifest_path) str
        +pull_archive(archive_id) Path
        +query_models(**filters) list~dict~
    }

    class ICEFacadeAdapter {
        <<external : ice_ext.plugin.bridge>>
        +push_archive(manifest_path) str
        +pull_archive(archive_id) Path
        +query_models(**filters) list~dict~
    }

    class ArchiveDescriptor {
        <<mock in-memory record>>
        +manifest_path : Path
        +created_at : str (ISO-8601)
        +size_bytes : int
        +zachman_cell : str
        +metadata : dict
    }

    class polaris_available {
        <<module-level fn>>
        +polaris_available() bool
        -_POLARIS_AVAILABLE : bool | None
    }

    class get_polaris_bridge {
        <<factory>>
        +get_polaris_bridge() PolarisBridgeProtocol
    }

    class FccApi {
        <<re-export : fcc.api>>
        +get_polaris_bridge
        +PolarisMockBridge
        +PolarisBridgeProtocol
    }

    PolarisMockBridge ..|> PolarisBridgeProtocol : implements
    NoOpPolarisBridge ..|> PolarisBridgeProtocol : implements
    ICEFacadeAdapter ..|> PolarisBridgeProtocol : implements (external)
    PolarisMockBridge "1" *-- "0..*" ArchiveDescriptor : _store values
    get_polaris_bridge ..> polaris_available : probes
    get_polaris_bridge ..> ICEFacadeAdapter : returns when available
    get_polaris_bridge ..> PolarisMockBridge : returns otherwise
    FccApi ..> get_polaris_bridge : re-exports
    FccApi ..> PolarisMockBridge : re-exports
    FccApi ..> PolarisBridgeProtocol : re-exports

Three notes on the stable promotion. First, src/fcc/archive/polaris_bridge.py is a pure re-export module — all real logic stays in the preview path until v1.6.0 removes it; this keeps both import styles green during the migration window. Second, the _POLARIS_AVAILABLE sentinel is cached module-globally and reset only via _reset_polaris_sentinel() (test-only), so polaris_available() is cheap to call from hot paths. Third, the mock's _store is a plain in-process dict — it does not materialize tarballs, so archive IDs are stable SHA-256 digests of the manifest bytes.

Reach for the bridge whenever the framework needs to hand a model artifact to POLARIS for long-term retention or pull a previously archived artifact back. The preview path fcc.plugins.v1_5_preview.polaris_bridge continues to work throughout v1.5.x but emits a DeprecationWarning on import; migrate to from fcc.archive.polaris_bridge import get_polaris_bridge or preferably from fcc.api import get_polaris_bridge before v1.6.0.

Key contracts¶

PolarisBridgeProtocol — three-method structural protocol; callers code against this, never against a concrete class.
push_archive(manifest_path) — persists a manifest descriptor, returns an archive id string. Raises ValueError if the manifest file does not exist.
pull_archive(archive_id) — returns the manifest path previously pushed. Raises KeyError for unknown ids.
query_models(**filters) — permissive filter dict; supported keys are zachman_cell, created_after, size_min, size_max. Unknown keys are ignored.
PolarisMockBridge — default fallback; in-memory dict store keyed by synthetic archive id (first 16 hex chars of sha256(manifest_bytes)).
NoOpPolarisBridge — returns empty values and emits a UserWarning; kept for tests that need a silent-no-op stand-in.
ICEFacadeAdapter — the external live adapter at ice_ext.plugin.bridge.ICEFacadeAdapter. FCC never imports this directly — get_polaris_bridge probes the module and instantiates it inside a try/except.
polaris_available() — module-level sentinel that caches the result of the ice_ext.plugin.bridge import. Reset via _reset_polaris_sentinel() in tests.
get_polaris_bridge() — factory that returns the live adapter when polaris_available() is True, otherwise PolarisMockBridge().

POLARIS Bridge¶

Key contracts¶

See also¶