feat(streams)!: the bearer key is an ADR-0031 provisioning need, minted per streams module

[wmadden-electric]

What an app author writes

// module.ts — the deploy root
const store = provision(storage());
const events = provision(streams(), { deps: { store: store.store } });
provision(jobsService, { deps: { events: events.streams } });

// src/jobs/service.ts — the consumer
export default compute({
  name: 'jobs',
  deps: { events: durableStreams() },
  build: node({ module: import.meta.url, entry: '../../dist/jobs/server.mjs' }),
});

// src/jobs/server.ts — the binding hydrates to a ready client
const { events } = service.load(); // StreamsClient

await events.create('jobs');
await events.append('jobs', { kind: 'created' });
const { events: log, nextOffset } = await events.read('jobs');
const next = await events.tail('jobs'); // resolves on the next live event

Nothing anywhere authors the key, a URL, a header, or a protocol detail: no secret slot, no envSecret, no bearer scheme, no offset names, no long-poll dance. Declaring the dependency is the wiring, and hydration hands back a typed client — the RPC parity (rpc() hydrates through makeClient; streams hydrates through createStreamsClient). Previously the root bound one platform variable into the module's apiKey secret slot and into every consumer's own slot, connected only by convention, and the app hand-rolled every request.

Decision

The bearer key is a value the framework mints, which is exactly what ADR-0031 is for: durableStreams()'s apiKey param declares a provisioning need under a streams brand, and the prisma-cloud target registers a provisioner for that brand. It is not an ADR-0029 secret (no external value, nothing to name) and not a producer output (no producer hands it over).

The provisioner is per-provider: it reuses #93's ServiceKey resource with the provider's address as the resource id, so every consumer edge of one streams() module resolves to one resource and one stable value — which is what @prisma/streams-server requires, since it authenticates a single API_KEY. ADR-0031 explicitly leaves cardinality to the provisioner, so this is policy, not a workaround.

Consistency is the reason this shape won. An earlier revision of this PR minted the key with its own BearerKey resource + a streams node descriptor. That worked, but it stood a second, streams-shaped mechanism next to the framework's general one — two ways to audit one concept, and one more thing a maintainer must learn per module. A module should build on the framework's internals rather than invent its own.

What's in the diff

• streams-keys.ts (new, target): the brand STREAMS_API_KEY, the need constructor, the faceted-edge scan, and the reserved env name — mirroring service-keys.ts, with its same no-effect/no-@internal/lowering constraint.
  • Brand-location deviation, on purpose: ADR-0031's discipline is that the declaring package owns the brand and the target imports it (what @internal/rpc does). prisma-cloud's layer order is lowering → extensions → modules, so a target import of @internal/streams would invert the layering. The brand lives in the target and the module imports it downward instead; the writer/reader-share-one-key discipline is unchanged. Documented at both ends.
• streamsApiKeyProvisioner registered in the target's provisions map beside serviceKeyProvisioner — same ServiceKey mint, keyed on edge.providerAddress. No new resource kind.
• Provider landing (ADR-0019): compute's serialize writes the minted value to COMPOSER_<addr>_STREAMS_API_KEY; compute's run re-stashes it address-free — the same channel shape RPC's accepted set uses. The streams entrypoint reads it there.
• Zero consumers = no key. The need lives on the consumer's edge, so a streams() nothing depends on never gets a key minted, and the server's only alternative would be serving every endpoint unauthenticated. It refuses to boot with a named error instead. (A deploy-time check isn't cheaply expressible: after the descriptor deletion the streams service is a plain compute(), and nothing in the target can tell it apart without re-adding the streams-shaped surface this PR removes. The deploy-side half — no consumers → no mint, no landing — is pinned by a target test.)
• Deleted (vs. this PR's earlier revision): bearer-key.ts, bearer-key-resource.ts, descriptors/bearer-key.ts, descriptors/streams.ts, streams-compute.ts, their registrations, exports, arch-config entries and tests. streams-service.ts is a plain compute() again; the module provisions no credentials resource.
• createStreamsClient / StreamsClient (@internal/streams, exported via the umbrella): the client the binding hydrates to — create (ensure-style) / append / read / tail, wrapping @durable-streams/client (ElectricSQL's canonical protocol client, Apache-2.0, pinned 0.2.1 — the version @prisma/streams-server 0.1.11's own repo pairs with; pure fetch-based JS inlined by tsdown, so no package grows a runtime dependency). Platform compensations live here with their tickets: tail() long-polls (PRO-218) via the protocol's own offset=now; idempotent operations ride out a cold start with a bounded backoff (PRO-219); appends never retry — the wire client's default retries network errors indefinitely on every method including POST, so the writer handle pins maxRetries: 0 and batching: false (no idempotency key upstream). The factory is exported standalone so local dev wraps the stand-in URL without load().
• examples/streams collapses to app logic: routes, the stream name, error mapping, and calls on the hydrated client — zero protocol knowledge in userspace.
• examples/streams keeps its jobs consumer service (append / read / long-poll tail over the binding), which exercises the key in-deployment and removes the zero-consumer shape from the example.
• The jobs consumer carries no retry, deliberately. It calls the streams service with a plain fetch; a failure surfaces as a 502 naming its cause. Cold-start handling belongs in the platform, not in every consumer — see the Verification section and PRO-219.
• Conformance suite pinned to exact 0.2.3 (reverting dependabot chore(deps-dev)(deps-dev): Bump the dev-deps group across 1 directory with 4 updates #86's 0.3.5 bump): 0.3.x tests fork/TTL/sub-offset features @prisma/streams-server 0.1.11 doesn't ship — 60/332 failed locally on main before this. The suite must track the pinned server version, not float; both harness headers record why.

Verification

Proven live on real Prisma Cloud (stack streams-example, deployed then destroyed — re-run on the client-hydration commits):

• Deploy green — 29 resources (counted from destroy; the deploy log double-reports steps). One streamskey-streams.service mint, landed to the consumer's param and the provider's reserved var.
• The consumer service through its own public URL, all protocol via the hydrated client: POST /jobs → 201 (first request, cold deploy); GET /jobs → 200 with events and a nextOffset; GET /jobs?offset=<mid> → the opaque-cursor resume returns exactly the later events; GET /jobs/tail → the client's long-poll delivered an event appended after it opened. Auth negatives direct to streams: unauthenticated → 401, junk bearer → 401.
• A real integration defect was caught by this live run and fixed: the deployed server's offset=now long-poll answers 204 with no content-type, defeating the wire client's JSON-mode detection (invisible against the stand-in, which sends the header). The client now passes the json: true hint — streams are JSON by this module's contract.
• Deployed conformance: 215/239 — all 24 failures the known "SSE Mode" group (PRO-218); zero protocol failures. Smoke 8/9 (same single SSE item). Harness key read from deploy state (mode-600, deleted after).
• Key stability across a redeploy: [streamskey-streams.service] noop, key byte-identical in state, consumer green with all prior events intact.
• Destroy clean: 29 resources, both URLs 404, the Project reaped by the CLI (ac1e7b1).
• One first-request-after-idle POST returned 502 (the deliberately non-retried append meeting a cold instance) — PRO-217/PRO-219 surfacing exactly as the example intends.

Local:

• @internal/streams 18/18 — including the new client suite against the stand-in (create-ensure semantics, append/read round-trips, opaque-cursor resume, live tail delivery + clean timeout, and a real protocol error surfacing unretried) and the entrypoint integration test end to end.
• @internal/prisma-cloud 188/188 (incl. feat(rpc): auto-provision per-binding RPC service keys (ADR-0030/0031) #93's and docs(rpc): document service keys; deny zero-consumer providers; close the project #100's regression nets and the boot-sweep/landing tests, each checked against a planted defect); local conformance 239/239 (raw-fetch harness — it tests the server, not our client); examples/streams 6/6 (the app driven through the client against the stand-in).
• Entrypoint and testing bundles verified single-file (no external imports beyond bun/node: builtins) with the wire client inlined; build / typecheck / test:types green; repo pnpm lint green; lint:deps clean; cast ratchet delta 0.

Alternatives considered

• Hydrate to the raw { url, apiKey } config and let apps hand-roll the protocol (this PR's earlier revision). Rejected by the operator: Durable Streams protocol logic in a user application is the moral equivalent of RPC users doing their own request encoding. The client library is also the right home for the platform compensations (PRO-218's long-poll default, PRO-219's idempotent-only retry) — in userspace they were boilerplate; in the library they are policy.

• A module-owned BearerKey resource + a streams node descriptor (this PR's earlier revision). Rejected on consistency: it duplicated ADR-0031's job with streams-specific surface. The narrower technical comparison only ever showed it was possible, never that it was right.

• Per-edge keys now. Needs @prisma/streams-server to accept a key set (it authenticates one API_KEY). When upstream grows that, this becomes a provisioner cardinality flip plus an accepted-set landing — no resource to add, no core change, nothing here to delete. Recorded in design-notes.md.

• External (out-of-deployment) key access: the same recorded platform ask as storage's minted SigV4 credentials; test harnesses read deploy state instead.

🤖 Generated with Claude Code

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@prisma/composer@92

npm i https://pkg.pr.new/@prisma/composer-prisma-cloud@92

commit: 0ca79a0

[wmadden]

What is this? Why does a particular node need magic logic in the compute() base?

[wmadden-electric]

Answering the review comment on descriptors/compute.ts — you and I crossed: that comment is anchored to b6d0f7a, and the fix landed in 6f98f16 about 10 minutes later.

You were right, and it was worse than a streams problem. compute imported two brand modules and carried two hardcoded provider-landing blocks — RPC's (from #93) and streams' (ours). Every future provisioned-param brand meant another import and another block in the general descriptor: the accretion ADR-0031 exists to prevent, relocated from core into the target. And ADR-0031 already assigned the fix — "the provisioner owns mint, size, aggregation, stability, and rotation" — so the landing never belonged in compute at all. We inherited the shape from #93 and doubled it.

6f98f16 deletes it rather than relocating it:

• descriptors/compute.ts runs one brand-blind loop — it looks a landing up by the need's brand and never names one. Each brand's landing lives beside its provisioner in control.ts; RPC's aggregation moved there verbatim (same env key, same encoding, its tests untouched as the regression net).
• The two hand-written edge scanners collapsed into one generic provisionedEdges(graph) that returns the brand as data.
• src/compute.ts had the identical accretion, so its re-stash went generic too.
• Core is unchanged (ADR-0031: the physical landing stays the target's); the seam is target-local, passed down as data to avoid a compute → control cycle.
• The acceptance test: a third brand requires editing none of descriptors/compute.ts, src/compute.ts, or the scanner — only registering a provisioner and a landing in control.ts.

Grep on the current head: zero occurrences of RPC_PEER_KEY|STREAMS_API_KEY|service-keys|streams-keys in either compute file.

Now rebasing onto main, which moved under this: #100 made RPC's landing provider-driven (zero consumers → literal "[]" → deny all), while our loop is edge-driven — rebased naively that would silently reopen the fail-open hole #100 just closed, so the seam is going provider-driven (each registered landing invoked per exposing service with possibly-empty refs; the landing decides — RPC emits "[]", streams emits nothing so its server fails closed by refusing to boot). Re-proving live afterwards, since #94/#100/ac1e7b1 all landed since the last live evidence. Will re-request review when it's green.

🤖 Generated with Claude Code

[wmadden]

This doesn't belong in userspace

[wmadden]

What does any of this jargon mean

[wmadden]

Why is the user's application doing this? I would have expected STREAM was a property of the durable-stream connection DI'ed into the service.

And why is await withStream() necessary in applciation code, instead of in the hydrated stream client?

[wmadden]

Is there value in separating this app.ts from server.ts?

[wmadden]

I don't understand, what changed in this file? Just indentation?

[wmadden]

I'm deeply suspicious of this - what is it?

[wmadden]

This looks like a hack.

[wmadden]

What does this mean? What does "restash address free" mean? why would we want this? Why is this permitted in compute code?

[wmadden]

Woah what? why???

[wmadden]

Convert to a class. It's an object with a bunch of methods, stop forcing factory functions in the wrong paradigm