Exit Strategy¶
Fgentic's open protocols create replacement seams; they do not make implementation state portable. This document distinguishes a same-implementation relocation from a cross-implementation replacement and records what must move, what must be recreated, and where the repository has no automated migration path. It does not promise a zero-downtime or lossless exit.
Exit rules¶
- Pin the source and target versions, name the protocol and data boundary being preserved, and define the rollback point before changing either side.
- Inventory four kinds of state separately: Git-declared configuration, SOPS-encrypted credentials, durable application data, and external-provider data. Never use a Kubernetes object or volume snapshot as the only inventory.
- Prove the target with the same positive and negative contract checks used by the current layer. Protocol conformance is necessary but does not prove Fgentic's authorization, attribution, privacy, or failure behavior.
- Rehearse backup and restore into an isolated target. Freeze or drain the old writer for the final delta, cut over one boundary at a time, and keep the old side read-only until acceptance passes.
- Rotate credentials, revoke the old endpoint and provider access, and record any retained archive after cutover. A successful request to the replacement is not evidence that old access was removed.
Architecture coverage¶
The exit matrix covers every deployed layer in the README architecture table and every runtime box in the Open Agentic Stack. The diagram's foundation and maintainer boxes are stewardship labels, not deployed components; an operator can replace an implementation at a protocol boundary but cannot replace an upstream standard's steward.
| Architecture box or layer | Exit row |
|---|---|
| Human in a Matrix room; UI + collaboration fabric | Matrix clients; Matrix homeserver and authentication |
| Self-hosted Matrix stack | Matrix homeserver and authentication |
| Fgentic Matrix-A2A bridge | Matrix-A2A bridge |
| A2A contract | Delegation protocol and SDK |
| agentgateway; AI data plane / governance | Agentic data plane |
| kagent Agent; Agents | Agent runtime |
| Selected model backend; optional self-hosted model | Model backend |
| MCP contract; MCP tool server | Tool protocol and servers |
| Optional network interop | External-network bridges |
| Optional reference IdP | Upstream human IdP |
| Shared state | PostgreSQL and grounding data |
| Web ingress + TLS | Ingress and certificates |
| Observability | Metrics, dashboards, and traces |
| Runtime image security | Runtime image scanner |
| Delivery | GitOps, CI, and artifact registry |
| Kubernetes or the optional GKE reference | Kubernetes and cloud |
Layer exit matrix¶
Migration cost is relative to this repository's current automation: low changes configuration while retaining durable state, medium needs a controlled data or policy conversion, and high needs application re-provisioning, downtime, or a newly engineered compatibility path.
| Layer | Exit target and compatibility gate | Data that moves | Data recreated or deliberately left behind | Cost and one-way doors |
|---|---|---|---|---|
| Matrix clients | Replace Element Web/X with a client that passes the required Matrix Client-Server API, MAS/OIDC, room-version, threading, edit, notice, and automation-marker checks. The homeserver and MXIDs stay unchanged. | No server-side room or account migration. Export any client-local preferences that the chosen clients support. | Access tokens, device sessions, notification settings, and client-local caches are recreated. Do not assume Element-specific UX or MSC support exists elsewhere. | Low–medium. The protocol preserves server state, not client feature parity. The current bridge supports plaintext rooms and refuses encrypted events; a later deployment that enables per-room crypto must separately handle device keys and backups under ADR 0026. |
| Mobile notification transport | Replace Element's hosted gateway and APNs/FCM path independently from the Matrix client. Options are to disable background push, choose a client with an acceptable service, or operate a reviewed gateway plus an operator-owned app build. Preserve event_id_only unless the replacement is approved to process room content. |
Matrix room/account state does not move through the push service. Re-register each target client/device against its reviewed gateway after validating the homeserver pusher URL, format, app ID, push key handling, and notification behavior. | Device tokens, notification preferences, gateway state/logs, app signing keys, APNs/FCM credentials, provider accounts, and store-distributed app identity are recreated or revoked. Element-hosted records are not exported by Fgentic. | Medium–high. The stock Element X path is an accepted external operational-metadata dependency under the production notification decision, not sovereign transport. Self-hosting Sygnal removes Element from one hop but not Apple/Google; avoiding APNs/FCM also requires control of the client build and distribution path. |
| Matrix homeserver and authentication | Relocate Synapse by moving its complete PostgreSQL state, media, signing keys, MAS state, and server_name; or replace ESS with a separately qualified Matrix implementation. The documented permissive candidates are Tuwunel and continuwuity, not a shipped drop-in profile. |
A same-Synapse relocation moves databases, media, signing keys, appservice registration, and DNS/delegation. For audit or discovery, Synapse can export user data. | A cross-implementation replacement recreates local accounts, rooms, aliases, memberships, appservice registration, and history. The Synapse user export is an archive, not a supported import path, and it omits media bytes. | High. §10.3 records no cross-implementation account/history migration tooling. Tuwunel and continuwuity use mutually incompatible RocksDB stores, while Synapse/MAS use PostgreSQL; choosing a populated target is another one-way state decision. |
| Matrix-A2A bridge | Replace the Go appservice only with an implementation that preserves the stable Matrix appservice boundary, A2A v1 contract, ghost namespace, durable intake semantics, attribution, rate limits, media policy, and negative security behavior. No off-the-shelf equivalent is claimed. | Keep the Matrix-side ghost accounts and room state by retaining the namespace and server identity. A same-code relocation moves the complete bridge database and reviewed configuration. |
A different implementation recreates its state cache and transaction/task ledger. Drain durable jobs first; do not copy the repository-specific schema into unrelated software or reinvoke acknowledgement-ambiguous tasks. | Medium for relocation; high for replacement. Changing the exclusive ghost namespace strands existing identities. Starting two active appservices with the same namespace or tokens creates competing writers and is not a migration strategy. |
| Delegation protocol and SDK | Replace a2a-go behind the same A2A v1 wire contract only after AgentCard, version negotiation, Signed AgentCard, task polling, cancellation, extension, timeout, and negative authorization tests pass. Replacing A2A itself is a design change requiring an adapter and ADR. |
Protocol-visible AgentCards, messages, artifacts, task semantics, and Fgentic extension schemas move only where the target implements them exactly. | SDK-internal state, task stores, generated types, and implementation-specific errors are recreated. Existing task/context identifiers are not assumed portable across servers. | Medium for an SDK; high for another protocol. Shared JSON shapes do not preserve security or task lifecycle semantics. The bridge's integration fixture proves one plain a2a-go runtime, not arbitrary A2A products. |
| Agentic data plane | Replace agentgateway with a gateway or explicit service routes that reproduce model credential isolation, A2A/MCP/model routing, exact authorization, quotas, token telemetry, trace propagation, and both load-bearing NetworkPolicies. | Translate reviewed routes, backends, policy intent, model inventory, certificate trust, and metric/trace dimensions. Secrets move only through a newly encrypted target-specific credential set. | Controller state, transient rate/quota counters, generated AgentCards, and implementation-specific policy resources are recreated. Historical telemetry remains in the observability system, not the gateway. | High. Direct routing is acceptable only for ordinary debug A2A where ADR 0006 permits it; it is not an exit for model credentials or permission-aware retrieval. A cutover that gives Agents provider keys violates the current security contract. |
| Agent runtime | Replace kagent with an A2A v1 server that passes the bridge's AgentCard, task, attribution, timeout, media, and authorization contract. The repository continuously proves this seam against a standalone SDK-backed server with no kagent resources. | Move agent-owned source, prompts, tool declarations, durable artifacts, and any application data through formats owned by that agent. Keep the Matrix ghost mapping while changing the reviewed A2A endpoint and pinned identity. | kagent CRs, controller state, sessions, and its PostgreSQL rows are recreated unless the replacement explicitly supports them. Start new contexts; do not present a copied contextId as session continuity. |
Medium per stateless agent; high for sessionful agents. A2A compatibility does not migrate framework memory, tools, permissions, or model behavior. Remote targets also cross a new organization and credential boundary. |
| Model backend | Select another implemented profile in Model Provider Profiles, or add a reviewed provider whose endpoint, credential resolver, model identifiers, network policy, token metrics, residency, and paid-provider gate pass the same static and runtime checks. | Move Git-declared provider/model selection and organization-owned evaluation cases. A self-hosted model may move only with its license, immutable weights/revision, serving config, and model cache policy. | Provider-side prompts, responses, fine-tunes, caches, invoices, and account controls remain with that provider unless its own export contract says otherwise. API keys and Workload Identity bindings are recreated and the old grant is revoked. | Low–medium for a supported stateless profile; high for fine-tuned or stateful services. Model names are not quality equivalence. Re-run golden tasks, safety checks, latency/capacity checks, residency review, and budget thresholds before cutover. |
| Tool protocol and servers | Replace an MCP server behind the governed route only when the protocol version, tool names and schemas, credential scope, side effects, rate limits, and allowed/denied call tests match. Replacing MCP itself changes both the Agent and gateway contract. | Move tool-owned source, schemas, policy, and business data using that tool's documented export. Preserve stable names only when semantics and authorization remain identical. | MCP sessions, discovery caches, credentials, and server-specific state are recreated. External systems of record stay in their owning service rather than being copied through MCP. | Medium; high if tool semantics change. Schema-compatible output does not prove equivalent side effects or authority. The current internal MCP route is not a public portability API. |
| External-network bridges | Disable an optional Slack/Telegram appservice or replace it with another reviewed bridge using a distinct registration, provider app, namespace, database role, and acceptance record. | Matrix room history already admitted to local rooms remains in Matrix. Export provider-owned data only through that provider's approved mechanism and contract. | Provider tokens, bridge database/state, remote event mappings, puppets, and sessions are recreated. Revoke the old provider app and complete the offboarding sequence; uninstalling the pod alone is insufficient. | Medium–high. A changed ghost namespace creates new Matrix identities. Provider history, edits, deletions, threads, and identity mappings are not assumed portable or lossless. |
| Upstream human IdP | Keep MAS and replace Keycloak with a conformant OIDC provider using Identity and SSO's fail-closed claim contract. Preserve an administrator-controlled matrix_localpart; test both first login and an existing account. |
Move human identities, required attributes, group policy, and recovery ownership through the IdP's reviewed export/import path. Keep Synapse/MAS account databases when only the upstream IdP changes. | OIDC client secrets, signing trust, sessions, recovery factors, and provider subject identifiers are recreated. Do not assume a new issuer/subject will attach to an existing Matrix account; require an explicit, tested relink procedure. | Medium–high. Mutable email or username mapping can fork or capture an MXID, so on_conflict: fail remains load-bearing. Disabling the old IdP before existing-account acceptance can lock out every administrator. |
| PostgreSQL and grounding data | Move from CloudNativePG to another PostgreSQL 17-compatible operator or service after proving database collation, roles/HBA, TLS, extensions (vector), backup, restore, and failover behavior. Use logical dump/restore or replication for an operator/cloud exit unless physical compatibility is proved. |
Move every tenant database, owner and scoped role, the knowledge schema and vectors, required extensions, and audited grants. Preserve Synapse's C collation. CloudNativePG recovery bootstraps a new CNPG cluster from its physical backup. |
Recreate Kubernetes Secrets, certificates, endpoints, operator CRs, monitoring, and backup credentials. Historical WAL/PITR remains readable only while its exact PostgreSQL, backup-tool, encryption, and object-store contract is retained. | High. Physical storage formats are PostgreSQL-major and backup-tool sensitive. CloudNativePG documents logical dump/restore or replication for blue/green major-version moves; rehearse the same boundary before changing operator or cloud. |
| Ingress and certificates | Replace Traefik with an implementation conformant for the pinned Gateway API version and the route types/features Fgentic uses; replace cert-manager only with an issuer controller that preserves Certificate lifecycle and renewal behavior. | Move standard Gateway, HTTPRoute, ReferenceGrant, DNS names, and issuer intent after comparing the target's version-specific Gateway API conformance. | Controller state, load-balancer addresses, ACME accounts when policy requires, provider annotations, and implementation-specific status are recreated. Prefer reissuing certificates to copying private keys. | Medium–high. Gateway API conformance is version/profile/feature-specific, not universal. DNS TTL and certificate overlap govern downtime; the current Gateway API, Traefik, and agentgateway pins are coupled and cannot be upgraded independently. |
| Metrics, dashboards, and traces | Replace Prometheus/Grafana with a PromQL-compatible metrics backend/UI, and replace the OTel Collector/Jaeger path with an OTLP-compatible backend after privacy, label, alert, query, retention, and access checks pass. | Translate ServiceMonitor/PodMonitor discovery, recording/alert rules, required metric dimensions, OTLP endpoints, and dashboards where the target format permits. Use a supported remote-write/export path if historical metrics are a requirement. | Grafana dashboard JSON, Prometheus TSDB data, alert state, and datasource identities are not generally portable to another product. The reference Jaeger store is memory-only, capped, and deliberately recreated without history. | Medium without history; high with history or a new UI. Preserve the token-burn guard and content-suppression boundary. A green synthetic trace or an empty dashboard is not equivalent operational evidence. |
| Runtime image scanner | Replace Trivy Operator only with a scanner that covers the same namespaces and immutable digests, has least-privilege execution, exposes reviewable findings, and can drive an equivalent high/critical drift signal. | Translate namespace scope, severity policy, immutable image identity, exception ownership, alert routing, and the human triage/runbook contract. | Scanner CRDs, caches, Jobs, reports, and baselines are recreated. Keep any required historical evidence in an approved external record; the in-cluster report set is not the compliance archive. | Medium. Different scanners and feeds produce different identities and counts, so re-baseline explicitly and never present equal counts as equivalent findings. Do not weaken admission, signature, SBOM, or build-time scanning during the transition. |
| GitOps, CI, and artifact registry | Replace Flux, GitHub Actions, or GHCR with systems that preserve pull-based reconciliation, dependency ordering, SOPS/age decryption, immutable digest pins, vulnerability gates, SBOM/signature identity, and clean-tree validation. | Move Git history, plain manifests, Helm charts/values, encrypted secrets, provenance policy, and artifact digests. Translate Flux Kustomization, HelmRelease, source, and verification CRs rather than treating them as portable Kubernetes APIs. |
Controller inventory/status, deploy keys, CI identities, registry tokens, caches, and environment protection are recreated. Re-encrypt secrets for the target trust root; never decrypt them into Git for migration. | Medium–high. Run exactly one reconciler/writer during cutover. Changing registry or CI identity invalidates current cosign subject policy and every pinned image/chart reference until the new supply-chain proof passes. |
| Kubernetes and cloud | Move workloads to another conformant Kubernetes cluster or an on-premises target. infra/terraform/ is a GKE reference, not a portable cluster module; #60 tracks a non-GCP production profile and its own acceptance evidence. |
Move Git-declared workloads and application data through the layer-specific procedures above. Recreate DNS and then restore PostgreSQL/object data into the target before enabling writers. | Nodes, control-plane state, PVCs/snapshots without proven CSI portability, load balancers, Cloud NAT, Workload Identity, GCS buckets, Vertex bindings, Cloud DNS, and Terraform state are provider-specific and recreated or retired. | High. Application-level restore is the default portable boundary; copying cloud disks is not. Prove storage class, topology, NetworkPolicy, Gateway API, DNS/TLS, backup/restore, capacity, and model residency before moving traffic or deleting the source. |
Minimum exit evidence¶
An exit is complete only when its evidence records:
- the source revision and target versions;
- the inventory and checksum or count for every moved durable dataset;
- a successful isolated restore or import plus the layer's positive and negative contract checks;
- the final-writer freeze, delta capture, cutover time, and rollback deadline;
- target health, authorization, attribution, privacy, and failure-path acceptance—not only reachability;
- revoked old credentials, routes, provider apps, DNS, and reconciliation access;
- every intentionally abandoned dataset, its owner, retention period, and deletion evidence.
These records are deployment evidence. The repository supplies boundaries and checks; it does not invent a migration result for an operator that has not run them.