# Arena canonical draft coordinator

Implemented source, not deployed or activated. This coordinates one exact
personal approval, one exact studio acceptance, and canonical DRAFT creation.
It introduces no mint, public listing, purchase, wallet transfer, Stripe action
or real-value execution. The browser-facing Arena command and real issuer/studio
acceptance still require completion before activation.

## Private command and authority

`POST /asset-registry/arena-drafts` runs on the operated private Core origin.
It is not an Arena website route, public V2 endpoint or general partner API. It
has its own narrowly scoped authentication exemption; subpaths do not inherit it.
The handler refuses browser Origin, Cookie and Authorization. The ordinary Core
client key is neither required nor accepted as this operation's authorization.
All responses are no-store and private request logging is redacted by the existing
`/asset-registry/` rule.

The caller is the operated Arena backend, which must first enforce the current
session's ownership of the original collectible brief/review. Its dedicated
service credential authenticates the app, not an arbitrary end user. Never expose
that key to browsers, partner agents or other apps. `ARENA_ASSET_APP_ID` is derived
from the operator's registered app configuration; the request cannot choose an
app, profile, vault, collection, metadata or edition. Native issuer authority
comes only from Hybrid-ID's authenticated private consumption receipt.

The exact request has `operation` (`advance`, `read`, or `cancel`), `request_id`
(original lowercase UUID v4), `proposal_digest`, `canonical_request_sha256`,
`revision` (the approved revision), `grant_id` (studio grant UUID v4) and
`grant_sha256`. All three hashes are lowercase SHA-256. Unknown fields are rejected.
Maximum 2 KiB JSON; no query parameters. Contract: `arena-asset-coordinator.openapi.json`.

Headers: `X-Arena-Draft-Time` (10-digit UTC Unix seconds, ±30 seconds),
`X-Arena-Draft-Nonce` (fresh 48 lowercase hex characters), and
`X-Arena-Draft-Signature` (64 lowercase hex HMAC-SHA256). Sign the literal key string
and original body bytes with this newline-separated input, no trailing newline:

```text
HYBRID-ARENA-DRAFT-COORDINATOR-V1
{time}
{nonce}
POST
/asset-registry/arena-drafts
{sha256_of_exact_body_bytes}
```

Nonce replay is denied for 61 seconds in the canonical database, surviving process
restart. Requests must use verified private routing/TLS and must not follow
redirects. The coordinator's outbound clients ignore proxy environment variables,
use fixed Identity loopback and Star Quest HTTPS origins, reject redirects, impose
8-second timeouts and 128-KiB response bounds, and verify exact receipt bindings.
No caller URL is fetched.

## Durable progression and partial results

Before contacting either participant, Core binds the entire intent (including the
configured app) to the original UUID in InnoDB. Changed reuse returns 409. A
connection-owned MySQL advisory lock serializes workers for that request, and the
code rechecks lock ownership before journal writes and creation. Database reads
use the same direct driver connection and never silently reconnect. A concurrent
worker gets a retryable 409; no second intent or asset is created.

`advance` follows this sequence:

1. Recover a source decision, or reserve the exact studio permit. Existing v1
   rights observations are insufficient. The source grant must have a separately
   reviewed acceptance permit binding this selected proposal and canonical body.
2. Recover or consume exact personal approval using Hybrid-ID contract
   `2026-10-08.2`, including server-derived `app_id`. The provider checks the
   originating app **before** consuming approval and before native issuer lookup.
3. Recover or consume exact source rights. Compare original IDs, proposal/body
   hashes, recording/brief/metadata, native issuer/vault/collection, replay,
   permitted use and edition across both receipts. Accepted permission is not an
   existing asset. The source acceptance policy is one exact irreversible draft.
4. Read the exact historical Core creation receipt first. If none exists and new
   creation is enabled, durably mark `creation_started` and call keyed canonical
   creation with the original body and UUID. The existing InnoDB transaction owns
   the receipt, asset, event, proof and outbox. It now locks the collection and
   checks both current native profile/vault bindings and DRAFT/ACTIVE state before
   a **new** keyed creation. Existing legacy unkeyed behavior is unchanged.
5. Validate the immutable creation response, then independently read the actual
   canonical asset. Only matching issuer/collection/metadata/supply/type/decimals
   confirms creation. Until then, `asset_uuid` is null and
   `creation_confirmed:false`, even if a creation receipt was already returned.

The journal records the pending stage before every external mutation. A timeout
means **unknown result**, not failure. Retrying the original UUID and terms first
recovers historical decisions; it never reactivates approval or creates another
edition. Receipt/body and journal hashes detect mismatches and stored corruption.
Stage names explicitly distinguish reservation pending, issuer acceptance pending,
permissions accepted, creation pending, readback pending, cancellation and created.

`read` is a local historical observation with no upstream call or new intent.
It returns only request ID, stage, accepted-permission booleans, whether creation
started, confirmed asset UUID/time, and false mint/publish/purchase/value flags.
Native profile, vault, selected body, service credentials and private receipts do
not leave this endpoint. The observation is not current token ownership or chain
finality. Browser BFF ownership checks remain mandatory even though the returned
fields are reduced.

New advance work requires `ARENA_ASSET_COORDINATOR_ENABLED=true`; actual new keyed
creation also requires `ASSET_CREATION_RECEIPTS_ENABLED=true`. Before any new
participant permission is consumed, the coordinator checks that creation flag,
the existing proof signer, and the receipt table on its direct connection. Historical reads and
recovery of already accepted/created work remain possible with new creation off.
Core's new private `read_creation_receipt` has no creation side effect and remains
usable with creation disabled. It still requires exact UUID/body hash/native
issuer binding from the retained approved request. It has no public route.

`cancel` is deliberately limited: before a source-consumption attempt or canonical
creation starts, it records cancellation intent and asks Star Quest to tombstone
the original source request. A lost cancellation reply is recovered as cancellation,
including if the worker is restarted through `advance`. It cannot turn back into
creation. Once source acceptance may have happened or creation has started,
cancellation is rejected: recover the original result first. There is no automatic
lease release, rollback of accepted user permission, or reallocation of uncertain
rights. Canceled request IDs remain retained. One participant may have accepted
permission while the other has not; that is a retained partial state, not a
successful asset or a distributed atomic transaction.

## Configuration and rollout

No runtime values, database migration, permission, grant, key or asset is installed
by this source change. Required operator-managed settings, all absent/off by default:

- `ARENA_ASSET_COORDINATOR_SECRET`: independent backend caller secret, at least32
  characters. It must differ from the two participant secrets.
- `ARENA_ASSET_APP_ID`: the exact registered Arena OIDC client ID, not a display name.
- `ARENA_ASSET_COORDINATOR_ENABLED`: keep absent/false until joint acceptance.
- `ARENA_ASSET_ID_CONSUMER_SECRET`: independently configured provider consumption
  key for loopback `http://127.0.0.1:3152/hybrid/assets/consumption`.
- `ARENA_ASSET_SOURCE_CONSUMER_SECRET`: separate Star Quest canonical rights key;
  **not** its ordinary Arena connector key. Follow the source's key format.
- Existing `ASSET_PROOF_SIGNING_SECRET` and `ASSET_CREATION_RECEIPTS_ENABLED` for
  actual canonical creation. Do not create a replacement proof-signing identity.

Apply additive `20261008_arena_asset_coordinator.sql` only after reviewing and
backing up the actual target database. Existing creation-receipt and issuer-read
migrations and participant runtime rollouts are separate prerequisites. The normal
asset migration tool now includes this file; no migration runs on import or request.
A missing schema fails closed and never falls back to unkeyed creation.

Back up the coordinator journal, creation receipts, assets/events/proofs/outbox
consistently. Never restore only an older journal or prune original IDs. Participant
backups must retain their own acceptance/revocation/cancellation histories. No
automatic cleanup or grants are synthesized to unblock a request. Keep new work
off during recovery; reconcile exact participant/Core receipts before resuming.

The real rollout must verify protected routing, key separation and no credential
logging, state/backups, actual studio permit and consenting issuer, wrong-owner
and app rejection, failure/restart between each step, revocation/expiry ordering,
one canonical draft and actual readback. It must also implement and exercise the
owned Arena browser initiation/history path. Funding, Stripe, publishing, minting
and value movement remain separately paused.

## Reproducible validation

`python scripts/test-asset-creation-receipts.py` starts fresh network-disabled MySQL
under a private temporary directory and runs the asset, issuer and coordinator
suite. It never reads production database configuration. Synthetic participant
fault cases cover lost remote/Core replies, concurrent workers, cancellation,
current collection ownership changes, mismatched receipts, corrupted journal,
readback outages, disabled creation recovery and actual Flask HMAC/nonce routing.

For joint local transport/contract acceptance, supply checked local source roots:

```sh
ARENA_TEST_ID_SOURCE=/absolute/hybrid-id-checkout \
ARENA_TEST_STARQUEST_SOURCE=/absolute/starquest-checkout \
python scripts/test-asset-creation-receipts.py
```

The fixture imports actual Hybrid-ID consumption and Star Quest rights modules,
uses their signed HTTP handlers on dynamic loopback ports, creates a temporary
recorded replay and synthetic explicit approvals, then creates one actual DRAFT in
the isolated MySQL. No production endpoints, studio rights, real user sessions or
asset records are used. Without those explicit source roots the joint case skips;
report that separately from the native canonical suite. Required source revisions
are Hybrid-ID PR5 (app binding) and Star Quest PR11 (acceptance participant), or
compatible descendants whose contracts have been checked.
