Firecall Classic to Firecall v2 migration contract
Date: 2026-08-25
Status: Accepted supporting contract for ADR-0012
Applies to: Development Firecall only
1. Purpose
This contract moves Firecall from the live GitHub-dispatched SSH system to the v2 browser workspace without losing a cleanup path.
It defines ownership, capacity, gates, evidence, rollback, and retirement. Section 38 of the implementation plan is the normative detailed sequence. A conflict stops migration until the source documents are amended together.
No delivery-program milestone or approval-card process applies. ADR-0013 still requires approval for trust, secrets, live deletion, and new spend.
2. Product names
| Name | Meaning during migration |
|---|---|
| Firecall Classic | Live serialized workflow, three state slots, and up to three SSH sessions |
| Firecall v1 draft | Unlanded design evidence; no runtime authority |
| Firecall v2 | New portal, workspace, control repository, and per-session runtime |
Do not call Classic v2. Do not use the v1 draft as an operating runbook.
3. Migration invariants
- Classic and v2 never manage the same Azure resource.
- Classic and v2 never use the same Terraform state key.
- Classic and v2 never use the same Azure session identity.
- Classic keeps close and sweep until its final zero proof passes.
- V2 keeps close, sweep, expiry, and break glass during every rollback.
- The combined coexistence ceiling is three sessions.
- Classic supports three sessions before coexistence admission starts.
- Protected Classic source reduces new-open admission to one before v2 creation starts.
- Classic close and sweep continue to inspect all three Classic state keys.
- V2 uses a limit of two only after live proof shows at most one Classic session.
- V2 reaches three only after Classic open trust and resources reach zero.
- A failed or unproved cleanup consumes its v2 slot.
- Unreadable state, status, proof, trust, or workflow facts block advancement.
- The historical Classic open credential never returns after removal.
- Classic resource deletion needs explicit owner approval.
- A source merge is not proof of live state.
- Every gate needs signed evidence and repeated live readback.
4. Ownership boundary
| Property | Firecall Classic | Firecall v2 |
|---|---|---|
| Source repository | OpenMined/infrastructure |
Infrastructure plus OpenMined/firecall-control |
| Entry workflow | .github/workflows/firecall.yml |
Protected control workflows |
| Driver | scripts/ci/firecall.sh |
Control repository typed tools and workflows |
| State | tfstate container; exact keys azure/firecall/dev.tfstate, azure/firecall/dev-slot2.tfstate, and azure/firecall/dev-slot3.tfstate |
firecall-sessions container, key azure/firecall/dev/sessions/<session_id>.tfstate |
| Resource group | One active group per new session, named rg-firecall-dev-<session_id>-eastus; legacy sessions can retain rg-firecall-dev-eastus |
rg-firecall-sessions-dev-eastus |
| Capacity | Three before coexistence; protected admission limit one during the two-session v2 canary | One leased ledger; two during coexistence; three after cutover |
| Primary access | SSH | Browser workspace; optional restricted SSH |
| Session route | Public VM SSH | Cloudflare Access to private mutual-TLS box route |
| Session identity | One managed identity for each active Classic session | One managed identity for each v2 session |
| Cleanup | Per-slot apply, close, and sweep | Per-session destroy, expiry, zero proof, break glass |
The Classic handover contains the complete source and behavior inventory.
5. Data and state treatment
There is no Terraform state migration.
There is no session migration. A Classic session must finish through Classic. A v2 session must finish through v2.
There is no request, terminal, shell, file, audit, or status import from Classic into v2.
V2 can reuse reviewed product intent from Classic profiles. It must publish the profile through the v2 schema and digest process. It cannot read Classic state as a source of profile authority.
The capacity reconciler can read only the three exact Classic state keys for admission and cutover proof. It cannot write those keys.
Keep all three final zero-resource Classic state Blobs through approved audit and rollback retention. Do not delete them during capacity cutover.
6. Migration phases
M0 Architecture and contracts
M1 V2 implementation without Azure or workload authority
M2 Dark trust, edge, cluster, and runtime activation
M3 Reduce Classic admission to one, then run the two-slot owner canary
M4 Reject Classic opens and reduce Classic trust
M5 Prove Classic zero and raise v2 capacity to three
M6 Run depleted-credit three-session qualification
M7 Observe for seven days
M8 Retire Classic after separate deletion approval
Advancement is one-way unless the rollback section gives an exact reverse operation. Never skip a phase because a later check appears green.
M0 — architecture and contracts
Land:
- Accepted ADR-0012.
- The reviewed v2 implementation plan.
- This migration contract.
- The v2 threat model.
- Exact request, profile, status, agent, evidence, and exception contracts.
- The machine-readable source inventory.
- Generic-workflow exclusions and credentialless validation routing.
- Removal of unused pull-request OIDC from the platform image workflow.
- Separation of Talks pull-request validation from its main-only OIDC publisher.
- The bounded authenticated-owner bootstrap exception in
CLAUDE.md.
M0 creates no live cloud resource. It removes pull-request entry into the generic Terraform Azure OIDC workflow. It removes every current mixed pull-request and OIDC workflow. The legacy PR-trusted identity remains live until E1 removes it.
Exit gate
- Group A validation passes.
- Every planned path has one primary merge group and rollback owner.
- Group A's truth-reconciliation exception changes no runtime value.
- Group A publishes one canonical fixture set for Groups B, C, and D.
M1 — implement v2 without Azure or workload authority
Groups B, C, and D can proceed in parallel after M0.
- Group B first performs the exact owner-approved empty control-repository bootstrap. Its consumed authority row and sanitized readback must merge before control product work starts.
- Group B builds the isolated control engine with mocks and emulators.
- Group C builds runtime services, the agent, image source, and supply chain.
- Group D builds the portal and browser workspace.
Each later group must prove compatibility with the canonical Group A fixtures before that group merges.
The repository bootstrap is the only live mutation in M1. Do not create a live OIDC credential, Cloudflare route, Azure resource, secret, node pool, or paid capacity.
Exit gate
- Every group passes contract, unit, integration, parser, browser, and policy tests applicable without credentials.
- Every artifact input has an exact pin and license record.
- No placeholder digest or version remains.
- The repository-bootstrap operation is permanently consumed with verified completion and readback evidence.
M2 — dark activation
Group E performs five ordered integrations.
- Create standing declarations, exact trust, owner bootstrap, policies, and budgets through approved paths.
- Acquire and publish immutable tools, runtime images, VM image, scanners, and signed evidence.
- Add inactive GitOps, admission, the tainted Firecall pool, and private peering. Runtime Deployments stay at zero.
- Add internal runtime, fixed secret delivery, tunnel, Access application, DNS, and cache-policy source.
- Complete the exact dark activation, identity canaries, certificate canaries, connector proofs, drift verdicts, and negative preflight.
M2 ends with:
profile.enabled = false
creation_enabled = false
capacity_limit = 2
live v2 sessions = 0
The dark preflight creates no session, VM, session identity, public IP, disk, NIC, or per-session state. It cannot supply a positive terminal, Kubernetes, preview, close, expiry, or cleanup claim.
Exit gate
- Both Cloudflare zones and Universal SSL checks pass.
- Cloudflare email one-time PIN, GitHub App, OIDC, Key Vault, storage, Policy, node, scanner, certificate, notification, and drift verdicts pass.
- No Entra, Conditional Access, PIM, or human session approval gates development activation or use.
- Two independent connectors and every internal origin are healthy.
- The signed dark preflight passes with creation still disabled.
- No live session resource exists.
M3 — two-slot owner canary
Use protected configuration merges for every gate change.
- Enable only the reviewed profile.
- Keep
creation_enabled=falseuntil the enabled profile passes live readback. - Merge protected Classic source that reduces new-open admission from three sessions to one.
- Keep Classic close and sweep enumeration over all three exact state keys.
- Use two repeated state reads to prove the admission limit and no more than one active Classic session.
- Merge
creation_enabled=truewithcapacity_limit=2. - Reconcile the protected configuration into the leased capacity ledger.
- Verify the permanent bootstrap marker, configuration digest, profile digest, and ledger through live reads.
- Open one platform-owner session through the normal user path.
The first owner canary can establish the first real private network-path marker. That exception applies only when:
- The actor is a current platform owner.
- No v2 session exists before reservation.
- The capacity limit is two.
- Protected Classic admission is one.
- Live Classic state readback reports no more than one active session.
- One reviewed profile is enabled.
- No marker exists for the current protected network-path generation.
- Static VNet, peering, subnet, NSG, DNS, route, and certificate checks pass.
The runner publishes ready only after it proves the real mutual-TLS route to
the box at 10.240.0.0/27:8443. It writes immutable signed evidence and the
generation marker. Later opens require that exact marker and unchanged facts.
The owner canary must prove:
- Portal identity, request, build timeline, and workspace entry.
- Read as the default for each selected service.
- Optional write for only the selected services that request it.
- Write precedence for selected services that share one namespace.
- Reader denial for Secrets, roles, role bindings, and mutations.
- Writer access only in the effective write namespaces.
- Shared terminal and
tmuxreconnect. k9s, workloads, current logs, previous logs, events, and exact namespace access.- Period-form SigNoz links.
- One selected HTTP or WebSocket preview on the separate preview domain.
- Optional SSH behavior if the release claims it.
- Second-human join, scope acknowledgement, invitation revocation, and owner revocation.
- Early close and independent expiry.
- Zero-resource cleanup and capacity release.
Then:
- Open two v2 sessions at the same time.
- Require a third v2 open to fail with capacity full.
- Run failed-open, failed-destroy, signature, digest-admission, and rollback tests.
Exit gate
- Every positive claim has signed live evidence.
- Both successful sessions close with zero proof.
- Any induced cleanup failure remains
rollback_failedand occupied until its reduction test completes. - Classic open works only within its protected admission limit of one.
- Classic close and sweep still inspect all three exact state keys.
- The combined live-session count never exceeds three.
M4 — reject Classic opens and reduce Classic trust
Do not start M4 before all M3 tests pass.
- Merge a Classic change that rejects every new
openand shows the v2 portal URL. - Activate a new SHA-bound Classic reduction identity.
- Permit that identity to close, sweep, and produce zero proof only.
- Remove the historical combined-workflow federated credential.
- Wait for every token issued through the historical credential to expire.
- Prove a new Classic open request is rejected.
- Rerun one completed pre-rejection Classic open and require Azure authentication denial.
One owner-approved, no-Azure cutover job can cancel only bounded non-terminal Classic open runs. It receives no OIDC credential.
After cancellation, run two live GitHub API reads five minutes apart. Both must show no queued, waiting, pending, requested, or in-progress Classic open run.
Keep Classic close and sweep available for every existing Classic session.
Exit gate
- The merged rejection source and protected workflow identities match.
- Historical Classic open authentication fails.
- Only the exact two reduction FICs remain.
- No non-terminal Classic open run remains.
- Every evidence item binds repository, workflow, commit, run, attempt, and authenticated query time.
M5 — Classic zero proof and v2 capacity three
Wait until every Classic session drains through close or sweep.
Classic zero proof requires:
- Zero resources in
rg-firecall-dev-eastusand every state-derived group matchingrg-firecall-dev-<session_id>-eastus. - Zero bound Classic Cluster User or namespace Writer assignments.
- No active lease on any of the three Classic state Blobs.
- Only the expected null session outputs in all three Classic states.
- No historical combined-workflow federated credential.
- Exact current Classic rejection and reduction source.
- No non-terminal Classic open run in repeated live queries.
- One signed
firecall-classic-zero-proofartifact bound to the merged rejection commit.
If the final close did not publish the artifact, dispatch the protected Classic
zero-proof operation.
Then merge only the protected v2 limit change from two to three. The capacity reconciler repeats every Classic source, workflow, credential, resource, role, state, and proof check before it updates the leased ledger.
Exit gate
- Protected configuration and the leased ledger both report three.
- The ledger update binds the exact Classic zero evidence digest.
- Classic open remains disabled.
- All three final Classic state Blobs remain retained.
M6 — depleted-credit three-session qualification
Qualification uses real Firecall paths. It creates no disposable session or node path outside normal control.
- Merge
qualification_mode=truefor current platform owners only. - Use a 12-hour qualification epoch and three-hour session limits.
- Start the exact qualification Pod in node-credit drain mode before a session exists.
- Wait for authenticated node CPU credits below 15 for 15 minutes.
- Stop if the node drain exceeds eight hours.
- Replace the drain Pod with the exact sustain contract.
- Verify node credits remain below 15.
- Open three normal owner sessions.
- Require a fourth session to fail with capacity full.
- Start fixed CPU qualification on all three boxes.
- Require each VM credit balance below 15 for 15 minutes.
- Hold the node and three VMs below 15 through a complete one-hour suite.
- Test terminal, Kubernetes proxy, preview, latency, local revocation, close, expiry, cleanup, and capacity during that hour.
- Delete the load Pod through its exact path.
- Close every qualification session.
- Require zero-resource proof and zero occupied slots.
- Merge
qualification_mode=false.
If any target fails, also merge creation_enabled=false.
Exit gate
- Signed node, VM, latency, expiry, cleanup, and credit evidence passes.
- No load Pod, qualification session, role, state, public IP, disk, or capacity entry remains.
- Qualification mode is false.
M7 — seven-day observation
Observe normal v2 creation, reconnect, access, close, expiry, storage, scanner, certificate, trust, node, cost, and alert behavior for seven complete days.
Do not describe the migration as complete during this period.
Exit gate
- No unresolved
rollback_failedsession exists. - Every scheduled close, sweep, security, trust, certificate, and retention job has current evidence.
- Alert delivery and budget telemetry remain healthy.
- The owner accepts any documented residual before retirement.
M8 — retire Classic
Classic retirement is a separate deletion operation.
It requires explicit owner approval because it deletes live declarations, trust, or retained resources.
Retirement can remove Classic workflow entry points and deterministic live resources only after the approved retention and rollback decision. Preserve the required zero state, signed evidence, source history, and handover record.
Do not delete any final Classic state Blob as an incidental cleanup action.
7. Gate state summary
| Phase | Classic open admission | Classic reduction | V2 profile | V2 create | V2 limit |
|---|---|---|---|---|---|
| M0-M1 | Enabled, limit 3 | Enabled | Not live | Disabled | Not live |
| M2 | Enabled, limit 3 | Enabled | Disabled | Disabled | 2 |
| M3 | Enabled, limit 1 | Enabled for all three state keys | Enabled | Enabled | 2 |
| M4 | Disabled | Enabled | Enabled | Enabled | 2 |
| M5 | Disabled | Zero-proof only | Enabled | Enabled | 3 |
| M6 | Disabled | Zero-proof only | Enabled | Qualification gate | 3 |
| M7 | Disabled | Retained reduction | Enabled | Enabled | 3 |
| M8 | Removed after approval | Removed after approval | Enabled | Enabled | 3 |
8. Rollback contract
8.1 Before Classic open rejection
Merge creation_enabled=false for v2. Keep the capacity limit at two. Close or
expire all v2 sessions through normal control. Classic remains available with
its admission limit of one.
After signed proof shows zero v2 sessions, a protected rollback can restore Classic admission from one to three. Close and sweep retain all three state keys throughout the rollback.
Do not delete v2 status, state, audit, trust, or standing resources during this rollback.
8.2 After Classic open rejection
Merge creation_enabled=false and capacity_limit=2 together. The capacity
reconciler writes both values atomically under the ledger lease.
Do not restore the historical Classic federated credential.
Restoring Classic open requires:
- A new owner-approved credential bound to current protected Classic source.
- Exact binding to the current reusable-workflow commit.
- A successful current open authentication canary.
- Authentication denial for the historical open rerun.
- Continued reduction access for both systems.
8.3 When three v2 sessions exist
Disable v2 creation and lower the configured limit to two atomically.
If three sessions remain, keep Classic open disabled. Select one v2 session for normal close or expiry. Prove at most two v2 sessions before any Classic-open recovery.
8.4 Cleanup or control failure
Keep access denied for a closing, expired, failed, or revoked session. Do not release its slot without zero proof.
Use normal close, then sweep, then the exact two-person reduction-only break glass path. Never use a generic Terraform destroy or delete an unknown resource.
8.5 Trust, edge, or runtime compromise
Disable creation first. Revoke only the affected credential or route. Preserve close and reduction identities where safe. Follow the incident actions in the threat model.
9. Required migration evidence
Each evidence record binds its schema, protected source commit, workflow path, workflow commit, repository and owner IDs, run ID, attempt, actor, authenticated time, live object IDs, ETags, canonical digests, signer, and result.
The migration needs these evidence classes:
- Group A source and contract validation.
- Dark identity, trust, policy, storage, network, node, certificate, edge, and notification proofs.
- Owner canary terminal, Kubernetes, log, event, SigNoz, preview, join, revocation, close, expiry, and zero-resource proofs.
- Two-session capacity and third-session denial.
- Classic source rejection and historical authentication denial.
- Repeated Classic workflow-run absence queries.
- Classic resource, role, state, lease, credential, and zero-proof artifact.
- Capacity two-to-three reconciliation.
- Depleted-credit node and three-VM qualification.
- Seven-day scheduled-operation and alert observation.
Never include a token, private key, state content, terminal content, Kubernetes log, Secret value, request reason, raw join capability, or unredacted address in migration evidence.
10. Stop conditions
Stop advancement when any of these conditions occurs:
- A required approval is absent.
- An authoritative read is unavailable or ambiguous.
- A schema, signature, digest, source, workflow, role, or object ID differs.
- A credential has an unsupported claim lookup, wrong supported claim, issuer, audience, workflow, or scope.
- An event-specific workflow accepts the wrong event, rerun, caller, or source commit.
- The generic
sp-infra-ci-planapplication, pull-request FIC, repository variable, output, input wiring, role assignment, or issued token remains before v2 activation. - A temporary role or token remains active past its required wait.
- A profile, security, node, access, certificate, or notification verdict is missing, stale, or blocked.
- A Classic open can still authenticate after M4.
- A non-terminal Classic open run remains.
- Classic resources, assignments, or state lease remain before capacity three.
- A v2 cleanup is unproved.
- Qualification mode, the load Pod, or a qualification session remains after M6.
- A live fact differs from merged evidence.
A stop does not authorize deletion. Keep the safest reduction path and report the exact failed gate.
11. Responsibility
| Responsibility | Owner |
|---|---|
| Architecture and contracts | Group A maintainer and platform owner |
| Control engine and capacity ledger | Firecall control maintainers |
| Runtime, agent, image, and supply chain | Infrastructure runtime maintainers |
| Portal and workspace | Firecall web maintainers |
| Ordered live integration | One Group E integrator |
| Trust, secret, spend, and deletion approval | Platform owner or named administrator |
| Classic rejection and reduction | Classic cutover maintainer |
| Live evidence and qualification | Group F integrator |
| Independent trust and assignment verification | Protected observer identities |
| Rollback decision | Platform owner with current live evidence |
The machine-readable source inventory assigns each source path to one group, activation gate, and rollback owner.