# Replay rights acceptance — canonical coordinator contract

Implemented and tested; not deployed or activated. This extends the reviewed
rights registry with a durable participant for one exact canonical DRAFT request.
It creates no asset, studio license, issuer consent, wallet permission or sale.
The canonical coordinator and joint real-issuer/studio acceptance remain required.

## Permission and the acceptance boundary

Existing v1 grants remain read-only observations. They do **not** authorize this
new acceptance behavior. A studio operator must separately review and record a
`starquest.replay-rights-acceptance-permit.v1`, including its retained agreement
reference and digest. Its explicit policy is
`one_exact_draft_irrevocable_after_acceptance`. Do not record a permit unless the
actual studio agreement authorizes that boundary. Star Quest can approve only its
own rights; neither this permit nor an Arena checkbox supplies player/third-party
rights or transfers copyright.

The permit binds the original issuance UUID, exact immutable grant digest, final
selected Hybrid-ID proposal digest, and exact canonical creation-body digest. The
grant in turn binds the saving owner, replay and committed bytes, Arena brief and
metadata hashes, native issuer/profile/vault/collection, edition, uses and term.
No caller profile, owner, collection, metadata, replacement UUID or supply is
accepted by this service. The coordinator must compare **all** those bindings with
the Hybrid-ID receipt and canonical body before any creation.

Four operations use the same exact intent:

- `reserve`: requires a reviewed permit, active grant, and current committed
  recording bytes. Durably pins the original intent. It does not freeze revocation,
  extend the grant's term, consume issuer consent, or authorize asset creation.
- `consume`: requires an existing reservation. Rechecks permit, active grant and
  actual bytes; then rechecks key, activation, time, permit and revocation under
  one SQLite write transaction. That transaction writes the immutable receipt.
  This commit is the **source acceptance point**. Revocation/cancellation that
  commits first wins. Acceptance that commits first remains historical acceptance
  for exactly this draft even if the studio later revokes the underlying grant.
- `cancel`: before acceptance, writes a permanent tombstone (also when reservation
  is absent). A late reserve/consume cannot overtake it. After acceptance it returns
  409; accepted allocation cannot be silently released, reassigned or reused.
- `read`: returns the last durable state and any exact historical receipt. Unknown
  requests return 404 without creating a reservation or permission.

No lease expiration or automatic reallocation exists. A reservation has no new
rights beyond its grant, and can no longer be consumed after grant expiry. Its
intent remains recorded. The original grant already permits only one issuance
UUID and exact edition; creating a second UUID is not a recovery strategy.

New reserve/consume are separately disabled by default. Exact accepted retries,
reads and cancellation remain available with the current dedicated key when new
acceptance is disabled. Accepted recovery performs no media or permission lookup:
expired/revoked rights and missing bytes cannot change a historical receipt. It
still requires the exact intent, current service authentication, trustworthy
clock, and intact registry. A changed original UUID reuse returns 409.

## Signed private-service operation

`POST https://starquest.live/api/arena/rights/acceptance`

This is a canonical-service channel, not a browser/Arena player connection API.
It rejects Origin, Cookie and Authorization headers. The existing Arena connector
key is explicitly rejected as configuration for this operation. There is no
unsigned, generic administrator, user-token or developer-token fallback. Use HTTPS
with certificate verification and no redirects. The canonical coordinator holds
the dedicated operator-managed key; do not give it to browser apps or partners.

Body is exactly `RightsAcceptanceRequest` in the adjacent OpenAPI document, at
most 4 KiB of valid UTF-8 JSON, with Content-Type `application/json` and no query.
Headers (each exactly once):

- `X-Rights-Time`: 13-digit UTC Unix milliseconds, within 30 seconds.
- `X-Rights-Nonce`: fresh 48 lowercase hex characters.
- `X-Rights-Signature`: 64 lowercase hex HMAC-SHA256.

HMAC key is the literal secret string. Input is newline joined without a trailing
newline, and hashes the **original bytes**, not reserialized JSON:

```text
STARQUEST-RIGHTS-ACCEPTANCE-V1
{time}
{nonce}
POST
/api/arena/rights/acceptance
{sha256_of_body_bytes}
```

A valid nonce is recorded durably for 61 seconds. Reuse returns 409, including after
restart. The greatest observed clock is persisted under the database write lock;
backward time fails 503 until it catches up. Acquiring that lock before observing
time prevents concurrent processes from mistaking lock contention for rollback.
An observed expiry cannot be revived by restart or a clock correction backward.
The dedicated key is reread and rechecked after asynchronous recording I/O.

Response `starquest.replay-rights-acceptance.v1` reports `reserved`, `consumed` or
`canceled`, timestamps in UTC milliseconds, an optional immutable receipt and retry
flag. Receipt terms omit the saving-owner key and private operator/review details.
They include native issuer identifiers and must stay on private service channels.
All responses are no-store. `historical_only:true`, `issuer_consent_verified:false`,
`asset_created:false`, `issuance_enabled:false`, `mint_enabled:false` and
`value_movement:false` distinguish this participant from successful issuance.
Never publish a receipt as a detached cryptographic proof or current ownership.

## Source operator preparation and rollout

1. Deploy this code with all existing runtime paths/keys unchanged, keeping the
   new acceptance key path absent and activation false. Preserve all four live
   room IDs, checkpoints, replay recording and worker health. The new endpoint
   should report 503 not configured; normal signed rights reads stay unchanged.
2. Before any later acceptance setup, take a consistent private SQLite backup,
   including active WAL state. Run the explicit schema upgrade:
   `node --experimental-strip-types scripts/replay-rights.ts upgrade-acceptance /absolute/private/rights.sqlite`.
   This adds four acceptance tables and schema version 2; it does not create any
   grant or permit. Old v1 databases still support existing rights reads. The
   consumer refuses to initialize or upgrade a database automatically.
3. Keep the registry in its private 0700 directory with a 0600 regular file.
   Record actual studio-approved permits through a 0600 JSON file containing only
   `permit` and `reviewed_by`:
   `node --experimental-strip-types scripts/replay-rights.ts authorize-acceptance /absolute/private/rights.sqlite /absolute/private/permit.json`.
   This records explicit reviewed permission; reserve/consume perform the fresh
   replay-byte checks. Exact retries recover the original permit. Changed terms,
   canceled requests and inactive grants cannot create a new permit.
4. Only after coordinator acceptance, configure
   `STARQUEST_REPLAY_RIGHTS_ACCEPTANCE_FILE` as an absolute 0600 regular JSON file
   with exactly `secret` (43 base64url characters, independently generated from
   32 random bytes). It must differ from the existing Arena connection secret.
   Keep `STARQUEST_REPLAY_RIGHTS_ACCEPTANCE_ENABLED` absent/false until activation
   is explicitly selected. `STARQUEST_REPLAY_RIGHTS_FILE` and the actual replay
   root must already be configured. No default path, key or fixture is installed.
5. Consumer writes are limited by the application to acceptance, nonce and clock
   tables; studio grant/permit/revocation methods require operator mode. The SQLite
   file remains protected operator infrastructure, not a sandbox for untrusted
   code. Existing game rights reads still use a separate read-only connection.

Keep backups and immutable decisions indefinitely. Never restore older state over
newer revocations, cancellations or acceptance receipts. Disabling new acceptance
keeps recovery available; removing the key disables the whole channel. After a
v2 schema upgrade, rollback code must understand v2: do not restore a v1 database
as a rollback shortcut. Partial source failure must not interrupt gameplay.

## Canonical coordinator obligations and recovery

Durably save the original complete issuance intent before any participant call.
Do not claim a distributed atomic transaction across Star Quest, Hybrid-ID and
Core. Reserve source rights, obtain/consume exact personal approval through the
separate Hybrid-ID private channel, consume source rights, and only then submit
the matching canonical body with its original creation UUID. Revalidate the body
and both receipts. The keyed Core creation transaction must enforce its own issuer
and collection authority. Confirm actual DRAFT creation through immutable receipt
and canonical readback before showing an asset in Arena.

A timeout is an unknown result, not failure. Recover `read` or exact retries using
the same UUID and terms. A request may be permanently accepted by one participant
without an asset existing; surface that state honestly and retain its audit. If a
pre-acceptance request is definitively abandoned, persist that coordinator decision
before canceling its source reservation. Never cancel/reallocate while canonical
creation is uncertain. After source acceptance, cancellation is rejected; continue
recovery of the same draft or retain accepted-without-creation history. Publication,
minting, transfer, sale and funding require their own future permissions.

Required joint acceptance: actual studio permit and personal issuer consent;
wrong terms/owner/collection/edition; concurrent revoke/cancel versus consume;
response loss and restart between every participant and Core creation; expiry and
clock rollback; key/activation changes during I/O; exact historical recovery after
revocation; one DRAFT only; actual canonical readback. Automated synthetic tests
are implementation evidence, not a real studio license or production activation.
