Deprecation & Sunset Policy

Phosra ships changes additively. A stable v1 surface — an endpoint, a response field, an SDK export — never disappears or changes shape under you without a named deprecation, an advance-notice window, and a machine-readable signal on the wire. This page is that contract: what "deprecated" means, how long you get, what you will see, and how to migrate.

The one guarantee

We do not make silent, breaking, immediate changes to a stable v1 surface. Every breaking change is announced first, carries a machine-readable deprecation signal, and honors a minimum notice window before the old behavior can be removed.

Everything below is the mechanism behind that sentence.

Lifecycle stages

Every stable surface moves through four stages, in order. It can sit in a stage indefinitely, but it can never skip one.

Advance-notice windows

The minimum notice you are guaranteed depends on the blast radius of the change. These are floors, not targets — most changes get more.

On the wire: Deprecation and Sunset headers

Phosra follows the two IETF standards for signalling this in HTTP, so a generic client or gateway can detect a deprecation without reading these docs:

• Deprecation — RFC 9745. A Structured-Field Date (@ + Unix seconds) marking when the resource became (or will become) deprecated. It may be a future date.
• Sunset — RFC 8594. An HTTP-date marking the moment the resource stops responding.
• Link — a pointer to the human migration guide, related by rel="deprecation" and/or rel="sunset".

A response from an endpoint that has entered a sunset window looks like this:

HTTP/2 200
content-type: application/json
deprecation: @1788220800
sunset: Tue, 01 Dec 2026 00:00:00 GMT
link: <https://docs.phosra.com/deprecation>; rel="deprecation",
      <https://docs.phosra.com/changelog>; rel="sunset"
 
{ ...unchanged response body... }

Read it as: "this became deprecated on 2026-09-01 (@1788220800), it stops responding after 2026-12-01, and the migration guide is at the linked URL." The 200 and the body are exactly what you got before — the headers are the only difference.

What you see today

No v1 endpoint has entered a sunset window yet, so you will not see a Sunset header on a live response today — and we would rather you verify that than take our word for it:

BASE=https://phosra-api-sandbox-production.up.railway.app
curl -s -D - -o /dev/null "$BASE/api/v1/platforms" \
  | tr -d '\r' | grep -iE '^(deprecation|sunset|link):' \
  || echo "no deprecation / sunset / link headers — nothing in a sunset window"
# → no deprecation / sunset / link headers — nothing in a sunset window

The block above is the exact shape you will parse when a surface does enter its window. Wiring the check now means your integration lights up the day one appears, instead of the day it breaks.

The one deprecation live today

There is exactly one deprecated route on the current census: the legacy advisor self-registration shim.

It still works — it forwards by the did discriminator and returns the same result the replacement would:

BASE=https://phosra-api-sandbox-production.up.railway.app
# A 32-byte-key validation error proves the request reached the handler and forwarded —
# the route is live, not 404. (Send a real key to get a 200 provisional registration.)
curl -s -X POST "$BASE/api/v1/advisors/register" \
  -H "Content-Type: application/json" \
  -d '{"did":"did:ocss:example","public_key_b64url":"AAAA","roles":["editor"]}'
# → {"error":"Bad Request","message":"invalid_public_key_b64url: must decode to 32 bytes, got 3","code":400}

Migration is a one-line URL change — the request and response shapes are identical:

bash
curl -s -X POST "$BASE/api/v1/advisors/register" \
  -H "Content-Type: application/json" \
  -d '{"did":"...","public_key_b64url":"...","roles":["editor"]}'

The published @phosra/cli already calls self-register, so phosra register needs no change — only hand-rolled callers of the old path do. See the CLI reference and self-serve registration.

How a deprecation reaches you

We announce on every channel a developer actually watches — no single point of failure:

Detect deprecations programmatically

Fail loud in CI or a health check the moment any endpoint you depend on starts advertising a sunset. This runs today (and prints nothing, correctly):

bash
BASE=https://phosra-api-sandbox-production.up.railway.app
for path in /api/v1/platforms /.well-known/ocss/trust-list; do
  hdr=$(curl -s -D - -o /dev/null "$BASE$path" \
    | tr -d '\r' | grep -iE '^(deprecation|sunset):')
  if [ -n "$hdr" ]; then
    echo "DEPRECATION NOTICE on $path:"; echo "$hdr"
  fi
done
echo "checked — no sunset windows open"

What we will never do

Migration expectations

When you receive a deprecation notice, the contract you can count on:

1. A named replacement exists before the notice ships. We never deprecate a path without a place to go.
2. The old and new surfaces overlap for at least the notice window — you can run both, cut over, and verify without a flag-day.
3. The migration is documented at the Link: rel="deprecation" URL, with a before/after example like the one above.
4. Idempotent, replay-safe cutover. Re-issuing the same write against the new path is safe — see Idempotency.

Next steps