[Compatibility] Gate any retirement of legacy MCP eras and deprecated features

[mohanagy]

Context

Miftah currently supports the modern MCP 2026-07-28 era and the initialized legacy 2025-11-25 era. Legacy compatibility includes initialized serving, sessionful Streamable HTTP, capability-gated Roots behavior, resource subscriptions/list-changed notifications where supported, and upstream transport: "sse" configuration.

MCP ecosystem deprecation is a signal, not sufficient evidence to remove shipped Miftah behavior. This issue is the mandatory decision gate for any retirement; it does not authorize removal by itself.

Trigger

Start the retirement decision only when concrete usage and compatibility evidence exists. Until then:

• do not remove or silently change a legacy path
• do not make new features depend on deprecated behavior
• keep modern and initialized legacy release gates green
• keep migration guidance accurate

Required evidence before implementation

• Inventory every public protocol, transport, configuration, CLI, library, and runtime behavior proposed for retirement.
• Record usage/compatibility evidence for affected clients and configurations, including exact versions, transport, protocol era, operations tested, and known limitations.
• Define an exact migration for every affected configuration and workflow, including stable diagnostics and operator actions.
• Prove rollback to the last compatible release from packaged artifacts without corrupting configuration, profile state, approvals, OAuth state, or audit data.
• Document security and privacy effects, especially session ownership, Roots-derived routing context, subscriptions, cancellation, and audit behavior.
• Define the release boundary. Any intentional public incompatibility must ship in a new major version under the post-1.0 SemVer policy.
• Create a separate implementation issue with bounded scope, acceptance criteria, tests, documentation, and release gates.
• Obtain explicit maintainer approval on the evidence-backed retirement decision before implementation begins.

Implementation acceptance gates

The later implementation PR must:

• target development
• preserve an actionable compatibility failure and migration path
• update the protocol/client matrix, configuration docs, changelog, and threat/security documentation
• cover source and installed-package behavior across the supported OS/Node matrix
• pass the locked MCP TypeScript client and pinned MCP Inspector gates for every retained path
• include current-head CI and review approval before merge
• be released only through a protected development to main major-version promotion

Out of scope for this gate

• adopting new features on deprecated protocol surfaces
• claiming named-host runtime compatibility from generated configuration alone
• treating a deprecation notice or lack of reported failures as usage evidence
• removing standalone downstream SSE, which Miftah does not implement

Current status

Deferred pending evidence. The compatibility source of truth is docs/mcp-compatibility.md; actual retirement requires a separate implementation issue and major release plan.

[mohanagy]

Stable evidence baseline published

@lubab/miftah@1.1.2 is now the packaged baseline for this decision gate.

• GitHub Release: v1.1.2
• Exact tag/current-main commit: db02f292bcb5f3f1013582f182d4baeb24ed8060
• Protected trusted-publishing run: 31828756232, successful
• npm: @lubab/miftah@1.1.2 is latest
• Registry provenance: SLSA predicate v1
• Fresh consumer: exact install, CLI version, and package import passed; zero known vulnerabilities; 100 registry signatures and 15 attestations verified
• Full release record: [Release] Publish v1.1.2 usability and identity fixes #409

This proves a stable, reproducible source and rollback baseline. It does not prove that any initialized legacy MCP, sessionful Streamable HTTP, Roots-derived routing context, resource subscription/list-change behavior, v1 library host path, or upstream transport: "sse" route is unused or safe to remove.

Evidence work starting now

1. Inventory every public legacy behavior and its source, configuration, documentation, and packaged test owner.
2. Build a client/configuration matrix using exact client and package versions, transport, negotiated protocol era, operations tested, limitations, and evidence strength.
3. Define an exact migration and stable diagnostic for every candidate surface.
4. Rehearse rollback from any future major candidate to the exact v1.1.2 packaged artifact while checking configuration, profile state, approvals, OAuth state, and audit data.
5. Document security/privacy effects for session ownership, Roots context, subscriptions, cancellation, and audit behavior.
6. Return an evidence-backed keep/defer/retire recommendation. Any removal remains blocked on a separate bounded implementation issue and explicit maintainer approval.

[mohanagy]

Evidence ledger merged; decision remains deferred

PR #412 merged to development as b8b1119b2cbc64395c5f095652dfded5ee3cec5d.

• Ledger: docs/legacy-retirement-evidence.md
• Current-head CI: run 31830577273 passed Linux quality, Verify, and Linux/macOS/Windows on Node 20/22/24.
• CodeRabbit: review unavailable because the PR hit its temporary review-rate limit; no CodeRabbit findings or approval are claimed.
• Local evidence: lint, typecheck, build, 159 test files / 1,973 passed / 34 skipped, 58-file package contract, 31 clean-tarball tests, and pinned Inspector 2.1.0 interoperability passed.

Completed gate sections now recorded in the issue checklist:

• public retirement-candidate inventory
• security/privacy effects and required protections
• major-version release boundary

Still open and merge-blocking for any retirement implementation:

• named-host packaged runtime transcripts and real usage/configuration evidence
• an exact tested migration for every observed workflow
• rollback rehearsal against a future incompatible candidate using exact v1.1.2
• a separate bounded implementation issue
• explicit maintainer approval

Current recommendation: keep and collect; do not retire.

[mohanagy]

Reopened: PR #412 merged the evidence ledger but did not satisfy the remaining usage, exact migration, rollback-rehearsal, separate implementation issue, or explicit maintainer-approval gates. GitHub auto-closed this issue because the PR body used the literal phrase close #388 inside a sentence saying the PR did not do that; the closing keyword has been removed from the merged PR record.

[mohanagy]

Packaged-runtime evidence is now merged to development via #414 at 420971c56e1bea03a4ebb2737029e2f01461c1a4.

Current-head gates:

• CI run: https://github.com/mohanagy/miftah/actions/runs/31834343864 — all Linux/macOS/Windows Node 20/22/24 jobs and Verify passed
• CodeRabbit required check passed; all four review findings were marked addressed

Exact published @lubab/miftah@1.1.2 evidence now proves initialized 2025-11-25 Roots initialization/refresh, resource subscribe/update/unsubscribe, routed upstream cleanup, and empty stderr. It also records the remaining boundary accurately: all three advertised list-change notifications are dropped and downstream cancellation never reaches the selected upstream. Those defects are tracked in #413.

This advances the evidence ledger but does not authorize retirement; #388 remains open for the named-host transcripts, real configuration/usage samples, exact migration runbooks, rollback evidence, and approval.

[mohanagy]

Correction after #415 merged to development as e75fb6663e67adb42564d5fc63ebc68bd277861a:

The list-change and cancellation limitations in the preceding comment were evidence-harness errors, not v1.1.2 runtime defects. The corrected exact-package fixture (SHA-256 fe99b4aefc50101a174a905b00ab8c1f4e38f998fc1e59d57d8153bcfdb09fd2) proves all three advertised active-profile list changes, exactly one upstream cancellation, and one terminal cancelled / REQUEST_CANCELLED audit event while preserving Roots, subscription/update/unsubscribe, cleanup, and empty stderr.

Current-head CI: https://github.com/mohanagy/miftah/actions/runs/31836244902 passed Linux quality, Verify, and Linux/macOS/Windows Node 20/22/24. CodeRabbit was explicitly review-rate-limited; its required context passed and no review findings were produced. #413 is closed as an evidence correction.

#388 remains open for named-host and real usage/configuration evidence, exact migration runbooks, candidate rollback proof, and maintainer approval.

[mohanagy]

Exact initialized Streamable HTTP evidence completed

Issue #416 is complete via PR #417, merged to development as 2d9aea7e4ae3a37ad61b514c9bcce6d4dca6aedc.

Current-head CI run 31839258621 is green across Linux quality, Verify, and Ubuntu/macOS/Windows on Node 20, 22, and 24:
https://github.com/mohanagy/miftah/actions/runs/31839258621

CodeRabbit's initial review found three harness gaps. All were addressed and confirmed in-thread: explicit server-side session termination with a retained-ID 404 probe, bounded/unrefed shutdown timeout handling, and surfaced spawn errors. The new-head CodeRabbit check passed with Review rate limited, so no second full review was available.

Exact published-package record:

• package: @lubab/miftah@1.1.2
• integrity: sha512-irvuGcic5EzsZc3cLEiw8+31Vnua5qjdU3l1gztl6q8I9RJQyCNLopVyolxRmmtoqHAoe+3803AvNy8V0ihvmw==
• fixture: tests/fixtures/legacy-http-artifact-consumer.mjs
• fixture SHA-256: 0354ae23f54a2eec27e9e7ab4a6741c5e10086ea16188e3aadcc1064ecbfd4c8
• environment: macOS 26.3 arm64, Node 22.9.0, npm 11.12.1
• client: official @modelcontextprotocol/client@2.0.0
• upstream: deterministic fake STDIO server 1.0.0

{"protocol":"2025-11-25","session":{"mcpSessionIdAssigned":true,"terminationProbeStatus":404,"closed":true},"approval":{"elicitationCount":1,"actions":["requested","approved","consumed"],"toolExecutions":1,"terminalAuditStatus":"success","terminalAuditErrorCode":null,"sensitiveArgumentRedacted":true},"cancellation":{"downstreamRejected":true,"upstreamNotifications":1,"terminalAuditEvents":1,"lastAuditStatus":"cancelled","lastAuditErrorCode":"REQUEST_CANCELLED"},"cleanup":{"work":true},"stderrEmpty":true}

This closes the executable exact-reference-client HTTP gap only. It is not named-host runtime evidence, usage attestation, migration proof, rollback rehearsal, provider evidence, or retirement approval. The gate remains keep and collect / retirement deferred until those external and future-candidate requirements are met.