Skip to content

Graph Serialization Elevation

Every knowledge engineer building on FCC eventually hits the same question: "Is the symbol I'm importing part of the stable public API, or is it an internal detail that might disappear in the next release?" The answer is a moving target. v1.5.0 formalised the answer by introducing the Knowledge Graph Serializer Elevator (KGSE) persona — the owner of the preview → stable promotion lifecycle for non-public FCC symbols being elevated into fcc.api.*.

This page is the knowledge-engineer-facing reference for KGSE. It covers the persona's Zachman cell, the fcc.plugins.v1_N_preview pattern, the SemVer 1.x migration guarantees, the POLARIS and LYRA bridge promotion that shipped in v1.5.0 as the signature worked example, and the interactions with LTAS (archive steward) and DAR (decision archaeologist) that keep the promotion ledger coherent over time.

The KGSE persona, in one paragraph

KGSE sits in the ARCHITECT/HOW cell of the Zachman matrix — the architect row, the HOW column. Where KGSE's name hints at graph serialization, the scope is broader: any non-public FCC symbol that a downstream consumer (ice_ext, constellation vocabulary providers, JV partners) needs to depend on stably is a KGSE candidate. The persona's core output is the per-release promotion ledger — a record of every symbol that landed in fcc.plugins.v1_N_preview.*, its migration guide draft, and the version in which it was elevated to fcc.api.* with a SemVer 1.x backward-compatibility commitment. Preview-path removal follows a deliberate 6-month / one-minor deprecation window.

For the full R.I.S.C.E.A.R. specification, see src/fcc/data/personas/knowledge_graph_serializer_elevator.yaml.

Why does FCC need a promotion lifecycle at all?

A python package that ships to pypi with a public module tree announces a contract to every downstream consumer: "these symbols are stable; they won't move; their signatures are backward-compatible within a major version." FCC honours that contract at fcc.api.*.

But the real graph of FCC types is larger than what fcc.api.* exposes. There are 30+ subpackages (fcc.personas, fcc.workflow, fcc.knowledge, fcc.rag, fcc.federation, fcc.classification, and many more) that collectively export hundreds of symbols. Some of those symbols should be public; some shouldn't. Making the call for each symbol is KGSE's job.

The mechanism is a two-step elevator:

  1. Land in preview — new stable-candidate symbol is added to fcc.plugins.v1_N_preview.<module>. Downstream consumers can import from here at their own risk, typically behind a sentinel guard.
  2. Elevate to stable — in a subsequent minor release, the symbol is re-exported from fcc.api.* and the fcc.api.__all__ list is updated. The preview path is kept for one minor (the deprecation window) with a DeprecationWarning on import.

The 1-minor preview window is the KGSE constraint. No direct private-to- public elevation is allowed. This gives downstream consumers a full release cycle to surface concerns before the symbol becomes a contractual commitment.

The fcc.plugins.v1_N_preview pattern

Every active preview namespace lives under src/fcc/plugins/v1_N_preview/. The canonical file layout is:

src/fcc/plugins/v1_N_preview/
├── __init__.py         # emits DeprecationWarning once all symbols are stable
├── polaris_bridge.py   # previewed in v1.5.0, stable in v1.5.0 -> fcc.archive
├── lyra_bridge.py      # previewed in v1.5.0, stable in v1.5.0 -> fcc.knowledge
└── README.md           # the preview-namespace lifecycle doc

The __init__.py carries the deprecation-window policy. From v1.5.0:

"Symbols in this namespace are preview candidates for elevation to fcc.api.*. Preview paths are kept for one minor release after elevation. If you import from here, the import will emit a DeprecationWarning starting the release after elevation. Migrate to the stable path before the next major."

Downstream consumers who want zero deprecation noise can use the fcc.api.* path directly from the first release it exists. Consumers who cannot yet migrate can keep the preview import through the one-minor window.

The fcc.api.__all__ contract

fcc.api.__all__ is the canonical list of stable symbols. As of v1.5.0 the list includes:

# From src/fcc/api/__init__.py
__all__ = [
    "PersonaSpec", "PersonaRegistry",
    "WorkflowGraph", "WorkflowAction", "ActionEngine",
    "AISimulationEngine", "CollaborationEngine",
    "BenchmarkRunner", "ModelCardGenerator",
    "ComplianceAuditor", "RequirementRegistry",
    "AIActClassifier", "CompliancePipeline",
    "ModelFacade", "EventBus", "Event", "EventType",
    "KnowledgeGraph", "JSONLDSerializer", "RDFSerializer",
    "RAGPipeline", "DocumentChunker",
    "get_polaris_bridge", "get_lyra_bridge",
]

The list is not a facade of re-imports — each symbol is re-exported from its canonical module home. A knowledge engineer depending on a stable symbol can import from either the fcc.api.* aggregate or the module home; KGSE guarantees both paths remain stable.

The module-level stable homes for v1.5.0 bridge symbols:

Symbol Module home Aggregate
PolarisBridge fcc.archive.polaris_bridge fcc.api.archive
LyraBridge fcc.knowledge.lyra_bridge fcc.api.knowledge

This is the signature KGSE deliverable from v1.5.0 — the POLARIS and LYRA bridges moved from preview to stable, and the fcc.api.__all__ list was updated in lockstep.

Worked example — POLARIS + LYRA in v1.5.0

The v1.5.0 promotion is worth walking in detail because every future KGSE promotion will follow the same shape.

v1.4.1: Preview landing. fcc.plugins.v1_5_preview.polaris_bridge and fcc.plugins.v1_5_preview.lyra_bridge land as preview namespaces. Each exposes a *BridgeProtocol, a *MockBridge fallback, and a get_*_bridge() factory. Downstream consumers (ice_ext, lyra) import via the preview path.

v1.4.2–v1.4.4: Preview stabilisation. No API changes. KGSE opens the promotion ledger entry and drafts the migration guide at docs/migrations/v1.5.0-api-additions.md. The discernment discipline is active — every promotion cites the STATUS.md §n ask that triggered it. POLARIS promotion cites ice_ext STATUS.md §4; LYRA promotion cites the v1.4.4 CHANGELOG Generated section.

v1.5.0: Elevation. Three changes land together:

  1. fcc.archive.polaris_bridge and fcc.knowledge.lyra_bridge are created as the stable module homes.
  2. fcc.api.__all__ gains get_polaris_bridge and get_lyra_bridge.
  3. fcc.plugins.v1_5_preview.__init__ starts emitting DeprecationWarning on import.

The migration guide at docs/migrations/v1.5.0-api-additions.md is published. The ledger row for each promotion is updated with the stable module home, the release date, and the elevation commit SHA.

v1.6.0 (planned): Preview-path removal. The preview namespace is removed. The one-minor deprecation window has elapsed; downstream consumers had v1.5.0 to migrate. KGSE files the post-mortem if any consumer is still on the preview path at removal time.

An auditor or downstream consumer can walk this four-release arc end to end by reading the CHANGELOG entries for v1.4.1 through v1.5.0 and the promotion ledger. That is the KGSE pattern made observable.

The promotion ledger

The ledger is a single YAML file at docs/governance/promotion-ledger.yaml. Every entry carries:

- symbol: get_polaris_bridge
  preview_path: fcc.plugins.v1_5_preview.polaris_bridge
  stable_path: fcc.archive.polaris_bridge
  api_aggregate: fcc.api.get_polaris_bridge
  preview_landed: v1.4.1
  stable_landed: v1.5.0
  preview_removed: v1.6.0 (planned)
  status: stable
  ask_ref: "ice_ext STATUS.md §4"
  migration_guide: docs/migrations/v1.5.0-api-additions.md

Every field is required. A partial entry is a KGSE finding and blocks release. The ledger is the single source of truth; CI contract tests cross-check fcc.api.__all__ against ledger entries with status: stable.

SemVer 1.x commitments

When a symbol lands in fcc.api.__all__ with status: stable, the SemVer 1.x commitment kicks in:

  1. The symbol's identifier (module path + name) is stable for the remainder of the 1.x line.
  2. The symbol's signature — argument names, argument order, return types — is backward-compatible. New arguments may be added with defaults; existing arguments cannot be removed or renamed.
  3. The symbol's semantic contract — what it does when called with a given input — is stable. Bug fixes are allowed; behaviour changes that break an existing caller are not.

KGSE is the persona that enforces these three commitments across releases. The forensic auditor (FA) and the governance compliance auditor (GCA) receive KGSE findings when a commitment is broken.

A knowledge engineer building a vocabulary provider plugin against fcc.api.* can rely on the three commitments through v1.9.x without further concern. That is the reason fcc.api.* exists as a separate surface from the module tree — to carry the contract visibly.

The DeprecationWarning cycle

Python's warnings.warn(..., DeprecationWarning) is the chosen mechanism. The cycle is:

  1. Stable landing release (e.g. v1.5.0): preview path works silently. Stable path is authoritative.
  2. One release after stable landing (e.g. v1.5.1): preview path emits DeprecationWarning on every import.
  3. Preview removal release (e.g. v1.6.0): preview path raises ImportError. Consumers must be on the stable path.

The two-release cycle is long enough for downstream consumers to migrate calmly but short enough to keep the preview namespace from accreting forever. KGSE's role_adoption_checklist requires every promotion to confirm the cycle is wired correctly at landing time.

For consumers: pin your warnings filter appropriately in your tests, or migrate to the stable path ahead of the v1.5.1 deprecation window.

Interaction with LTAS

LTAS (Long-Term Archive Steward) is KGSE's natural peer. When a promoted symbol depends on archive semantics — the POLARIS bridge is the canonical example — LTAS reviews the SemVer-1.x commitment against the archive-integrity guarantees. The review protocol is:

  1. KGSE drafts the migration guide.
  2. LTAS reviews the archive-manifest implications.
  3. If LTAS identifies a retention-class concern, the promotion is blocked until addressed.
  4. If LTAS approves, KGSE finalises the ledger entry.

The interaction is symmetric on the other side — LTAS promotions of new archive retention classes are reviewed by KGSE for SemVer compatibility.

See the companion Long-Term Archive Stewardship page for the LTAS side of this protocol.

Interaction with DAR

DAR (Decision Archaeologist) supplies the rationale for borderline promotion decisions. When KGSE is choosing between "promote now" and "wait one more release," DAR reconstructs the rationale for earlier similar decisions to inform the call.

The reconstruction pattern is standard DAR — triangulation against ADR + event stream + commit history — but narrowed to previous promotions. The effect is that KGSE's decisions compound over releases; each promotion is informed by the corpus of prior promotions.

For DAR's side of the protocol, see Decision Archaeology.

KGSE maturity model (for consumer teams)

A consumer team's relationship with KGSE matures across four stages.

Stage Signal KGSE interaction
Observer Imports only from fcc.api.*; no preview-path usage Receives release notes; no active interaction
Ask author Files STATUS.md §n asks for new promotions Direct coordination on preview landing date
Preview consumer Imports from fcc.plugins.v1_N_preview.* Receives early warnings on API shape changes
Promotion partner Co-drafts migration guides Joint ownership of the ledger entry

Most consumer teams stabilise at Observer or Ask author. Preview consumer and Promotion partner are active collaborations reserved for ecosystem-tier projects (ice_ext, AOME, CONSTEL, the constellation verticals).

KGSE does NOT own

  • KGSE does NOT decide what a symbol does. That is the owning subsystem's persona.
  • KGSE does NOT resolve SemVer disputes unilaterally. Those escalate to GCA + FA.
  • KGSE does NOT maintain the archive. LTAS owns the archive.
  • KGSE does NOT write the migration consumer guide for a specific downstream project. That is a PHV (Pattern-Harvester) deliverable in coordination with the consumer team.

Keeping these lanes clean avoids the most common promotion-ledger disputes.

Persona Direction Interaction
LTAS peer POLARIS bridge promotion + archive-steward SemVer review
DAR upstream Supplies ADR rationale for borderline promotion decisions
IHL upstream Receives downstream ask signals during innovation handoffs
PHV peer Aligns promotion ledger with cross-sibling-repo pattern harvest
FA downstream Surfaces promotion compliance findings during forensic audits

Next steps

  • Read the Long-Term Archive Stewardship page — LTAS is KGSE's closest peer.
  • Read the Decision Archaeology page — DAR supplies rationale for promotion decisions.
  • Consult docs/migrations/v1.5.0-api-additions.md for the authoritative v1.5.0 migration guide.
  • Read ADR-008 — POLARIS absorption and ADR-010 — Six pillars architecture for the framework-level rationale KGSE cites during promotion reviews.
  • Consult the Codename Decoder for POLARIS and LYRA origin reasoning.
  • Open the KGSE persona YAML at src/fcc/data/personas/knowledge_graph_serializer_elevator.yaml for the authoritative R.I.S.C.E.A.R. spec.
  • Review docs/personas/evolution/kgse.md for the KGSE evolution guide (career milestones, first 90 days, escalation points).
  • Browse docs/tutorials/sample-prompts/persona-kgse-prompts.md for ready-to-run promotion-ledger prompts.
  • Walk docs/tutorials/advanced-capabilities/polaris-archive-integration.md and docs/tutorials/advanced-capabilities/lyra-knowledge-graph-integration.md (Pool B) for the two bridge integrations KGSE owns.
  • Follow the Vocabulary Provider Pattern for the downstream consumer view — vocabulary providers are one of the three major KGSE constituencies.