releaseStreamGrants
releaseStreamGrants(
options,claims,token,now):Promise<{released:number; } | {refused:string; }>
Defined in: packages/server/src/circuits/subscribe.ts:704
Give back the engine claims a token’s grants acquired — the close half of subscribe.
Why this route exists. A native POST /shapes with a definition the engine already holds does
not create a second shape: it JOINS the existing one, under a claim of its own. Live claims are
load-bearing rather than bookkeeping — one live claim blocks both dormancy and eviction, precisely
because native durable-streams reads bypass the engine entirely, so a claim is the only thing that
tells it a reader it cannot see still exists. Without a release, a shape waits out its whole lease
window before it can go dormant, every time.
The token IS the request, exactly as on the re-mint path: its signature proves this control
plane minted these grants, so nothing has to be stored server-side to know what was acquired.
Verified with allowExpired, and that is not a weakening — a session releases at CLOSE, which is
routinely past a 5-minute TTL, and expiry bounds how long a grant keeps working, not what it
proves was issued. A release grants its bearer nothing; the only thing it can do is give away
claims that this token’s own subject holds.
ONE release per GRANT, deliberately not deduplicated by shapeId. Two grants naming one shape
are two joins — the engine deduplicated identical definitions and counted both (ADR-0055 decision
6) — so collapsing them here would return one of two claims and leak the other permanently. Each
grant releases its OWN claim (DELETE /shapes/{id}?subscription=<claim>), which is what makes one
release distinguishable from the other at all.
Idempotent and retry-safe (fork ADR-0008). A claim is named, so releasing it twice is releasing
it once: the second DELETE is a no-op 200 and cannot touch another subscriber’s claim. That is
a change in kind from the anonymous refcount decrement this route was first written against, and it
collapses the old asymmetry — a client, a proxy or an operator may repeat a release freely. A
release that never arrives at all is not a permanent leak either: the claim is a LEASE, renewed on
the token re-mint, so a session that crashed or was unloaded has its claims reclaimed by the engine
within leaseSeconds. What this route buys is promptness, not correctness.
Refusals are refusals, not no-ops: a bad signature or a mismatched subject answers an error rather
than { released: 0 }, because a token presented by anyone but its own subject is not a release,
it is an attempt to drop the victim’s claims.
Parameters
Section titled “Parameters”options
Section titled “options”engine
Section titled “engine”{ createShape(request): Promise<CircuitsShapeHandle>; releaseShape(shapeId, subscription): Promise<void>; replicationState(): Promise<CircuitsReplicationState>; }
engine.createShape
Section titled “engine.createShape”(request) => Promise<CircuitsShapeHandle>
Register a shape and get the stream to follow — and renew that registration.
There is deliberately no renewShape: a renewal IS this call, repeated with the same
request.subscription on the same definition (fork ADR-0008). The engine answers the same
handle, counts nothing extra, and moves the lease forward. That is also why a create whose
response was lost can simply be sent again, and why the control plane’s token re-mint can renew
every live claim without a second route.
Two outcomes a caller must distinguish:
- 409 (CircuitsEngineError.status) — the id names a DIFFERENT shape already. One name, one shape; nothing was taken, and a retry will not change it.
- a different handle — the claim had lapsed or the shape was evicted, so this call re-subscribed rather than renewed. The stream the old grant named is not this one (ADR-0007).
The engine shares by definition: two identical bodies collapse onto one maintained stream and return the same handle. Nothing here has to check for that or cache against it — which is exactly why the shared tier’s predicate must be GENERATED. Two subscribers in one scope produce identical bodies only because neither’s identity reached the predicate; they are still two distinct subscriptions, because each names its own claim.
The answer is VALIDATED, not cast, for the same reason replicationState validates the barrier: an engine that acknowledges a create without saying which subscription it recorded or how long that subscription lives cannot be renewed or released by id at all, and defaulting either field would invent a lease this control plane was never promised.
engine.releaseShape
Section titled “engine.releaseShape”(shapeId, subscription) => Promise<void>
Release ONE named subscription’s claim on a shape (DELETE /shapes/{id}?subscription=…).
Idempotent, and that is the whole point of naming the claim: releasing one that is already
gone is a no-op 200 rather than a decrement that steals another subscriber’s. A caller whose
response was lost may simply send it again.
There is no anonymous form here. The engine still accepts a bare DELETE /shapes/{id} as a
legacy refcount decrement, but it carries no claim identity and is not retry-safe, so this
client never issues one.
The shape itself survives its other subscribers and then follows the engine’s retention lifecycle (idle → dormant → evicted); this is a release, not a delete.
engine.replicationState
Section titled “engine.replicationState”() => Promise<CircuitsReplicationState>
The engine’s convergence barrier (ADR-0056): where replication is, how many computed-but-undelivered subquery flips remain, and how many flip batches the engine gave up on.
The engine answers a sync field beside these and it is deliberately NOT read: it is the
__el_sync sentinel watermark — an i64 the engine’s conformance harness bumps and waits on as
a global quiescence fence — which no pgxsinkit database ever writes, so it is 0 everywhere and
says nothing about convergence.
pendingFlips > 0 means a revocation has been computed and not yet written to any stream,
which no wire-format watermark can see. That is the term the Electric wire could not express
at all, and the reason the barrier is read out of band rather than inferred from a position.
flipFailures > 0 means a batch was abandoned after exhausting its propagation retries:
those membership effects are gone rather than late. The engine keeps the abandoned batch’s
pendingFlips count held — so the waiting terms never falsely read converged — and latches
itself degraded: /ready answers 503, so do its membership-bearing routes, and a reaper
deletes every subquery shape stream. Recovery is an operator restart.
The answer is VALIDATED, not cast. An engine that does not report both counters cannot answer the question this barrier asks, and defaulting a missing term to zero would manufacture a converged reading out of an engine that never claimed one.
CryptoKey
claims
Section titled “claims”{[key: string]: unknown; app_metadata?: {[key: string]: unknown; roles?: string[]; }; sub?: string; } | null
string
number
Returns
Section titled “Returns”Promise<{ released: number; } | { refused: string; }>