Use an existing R2 bucket

Run these commands from the comms-id/drq checkout after pnpm install. DRQ assigns an existing verified bucket exclusively; it does not create a bucket or ask the consumer to replenish stock.

1. Take the bucket

Choose your application's team, stack, binding and a stable request ID:

pnpm quarantine take --kind r2 --request-id my-app-assets-001 --team my-team --stack my-app --binding ASSETS

The JSON reply contains item.resourceId (the bucket name), item.assignment, item.verifiedEvent and item.lastPassedCheck, and the receipt event: the ledger's number, requestId, recordedAt and logId for your take. Save that assignment and receipt with your application configuration. Reuse the exact command and request ID if the reply is lost; it returns the same assignment. Never use a new request ID to recover an interrupted take.

2. Connect the application

In the application's existing Alchemy Worker declaration, bind the returned bucket name. Do not declare a new R2 bucket resource:

yield* worker.bind`Assets`({
  bindings: [{ type: "r2_bucket", name: "ASSETS", bucketName: assignedBucketName }],
});

In the existing localisation declaration, add the emitted Worker logical ID and binding name:

residency: { "Consumer/ASSETS": { residency: "verified" } }

Replace Consumer with that Worker's logical ID. Deploy through the application's normal reviewed deployment path; the policy reads the current verification for that exact bucket. The application accesses its assigned bucket through env.ASSETS.

Credentials

The CLI knows the Comms.ID ledger URL and reads no file implicitly (issue #394). Supply the consumer credential through the environment: RESIDENCY_CONSUMER_TOKEN for take, list and verification reads, or RESIDENCY_LEDGER_TOKEN, or RESIDENCY_LEDGER_TOKEN_FILE naming a local file. No Cloudflare provisioning credential is needed to take stock. Do not put the credential in application source or print it.

On the operator Mac, load it from the Comms.ID secret store for one command:

RESIDENCY_CONSUMER_TOKEN="$(/Users/MN/bin/comms-id-secret RESIDENCY_CONSUMER_TOKEN)" pnpm quarantine take --kind r2 --request-id my-app-assets-001 --team my-team --stack my-app --binding ASSETS

Another machine supplies the same credential through its approved secret setup.

Application deployment needs its normal deployment credentials plus ledger access for the verification read. A token-file setting alone does not configure the deployment process:

export RESIDENCY_LEDGER_URL=https://residency-ledger.comms-id.workers.dev
export RESIDENCY_LEDGER_TOKEN="$(/Users/MN/bin/comms-id-secret RESIDENCY_CONSUMER_TOKEN)"

The consumer credential permits take, stock listing, verification and object-routing reads, and help. It cannot add, recheck, retire, remove or abandon items, change references, initialise the ledger, export/subscribe to its full history, or run measurement probes. The access control enforces this at both HTTP boundaries. It is a shared consumer role, not a per-team identity; assignment fields still identify the consuming team, stack and binding. Existing operator credentials retain operator access and should not be distributed to consumers.

If allocation is unavailable

An empty pool returns an unavailable-stock error. A recorded fault affecting R2 or unavailable authoritative verification can also prevent allocation. Retry the same request identity after DRQ service is restored; no maintenance operation belongs to the consuming agent.

When a service replaces its taken Durable Object, an operator can release the old one once the new one is taken for the same team, stack and binding and the old one's restock demand is settled: it is retired and unassigned, and its routing is revoked at the next refresh. Storage items are never released (#466).

Replenishment may be stopped without preventing allocation of existing eligible stock. DRQ records replacement demand internally; an operator fills it with take --restock under the take's own identity (#466). D1 maintenance faults do not block R2 allocation; expired canary checks do not trigger maintenance during a take. This does not invent or refresh verification: refused or unverified items remain unavailable.

Inventory reports stale or uncertain canary maintenance separately from admission of your verified storage. An expired instrument check alone does not block consumer promotion. The exact assigned resource must still have authoritative verification; missing identities, recorded control faults and refused storage remain failures. DRQ owns the maintenance result. Under the 22 September recovery decision, the locator-only R2 canary failure with an inconclusive native challenge also leaves previously verified buckets usable. New stock stays blocked; the failed maintenance remains visible.

Owners: allocation, CLI, plan admission, ADR-0033.