# Root-grant read contract v0.1

Owner: net-kingdom. Status: approved delivery design, 2026-10-03.
Tracks NK-WP-0045 and accepted [ADR-0017](../adr/ADR-0017-root-grant-custody-and-account-authority.md).
Schema: [custody-record v0.1](../../canon/schemas/custody-record_v0.1.schema.json).
Reference implementation and fixtures: [validator](../../tools/custody-record/README.md).

The founder accepted ADR-0017 and selected the OpenBao design below. Delivery
and identity admission are pending; design acceptance does not assign a
custodian or establish a real root grant. Fixtures are
synthetic and must never seed the authoritative record.

## Read-surface decision (T04)

The founder explicitly accepted ADR-0017 and approved the proposed OpenBao
design. Scoped receipt: `c2cff929-91b9-4018-bfd6-fa04f7da8280`.
T01/T04 are done; bundled D10 `cef97ccd-4ee7-40fe-859e-1df9c9360ecb`
stays open for its separate MFA journey.

Selected delivery owner: **railiance-platform**, RPF-WP-0049. OpenBao KV v2
mount `platform`, API path `/v1/platform/data/custody/net-kingdom/platform-root`,
record ID `nk-custody:platform-root`, owner `net-kingdom-custody`. The complete
schema document is at response `data.data.document`; KV metadata version is
transport concurrency state, not the custody revision.

user-engine reads through an authenticated exact-path read-only identity;
separate attended human custody writes publish whole-document CAS updates.
The actual user-engine runtime identity/auth binding, writer custody binding,
bootstrap provenance and live acceptance are still owner delivery requirements.
The producer packet is `railiance-platform/openbao/root-grant/README.md`.

## Producer requirements (T05)

The selected owner must implement these requirements in its own repository,
link its workplan/task in NK-WP-0045-T05, and return non-secret delivery evidence:

1. Publish a complete schema-valid JSON document as one atomic revision. Bind
   its `record_id` and `owner_system` to the trusted configured source. A schema
   pass alone cannot authenticate its authority.
2. Admit a real reader identity through the existing owner routing procedure;
   deny unauthenticated readers and deny custody writes by reader identities.
   Keep credential material out of the document and delivery receipts.
3. Populate real entries only from human-controlled custody ceremony evidence,
   with exact issuer/subject and actor/time/reason. A directory or JWT projection
   cannot supply the grant. NetKingdom does not create a real entry from fixtures.
4. Validate every candidate document and its transition from the previous
   document before publication. Retain all entries and immutable grant facts;
   new grants, revocations and supersessions use revisions above the previous
   revision. Never reuse a revision for changed content. `updated_at` must not
   move backwards. Preserve revision history through backup/restore.
5. On read failure, incomplete publication or invalid data, report failure
   without returning a last-good document as a newly read authoritative result.
   Suppress raw documents, rejected values and credential errors in logs.
6. Document endpoint/path, authentication, timeouts/size limits, deployment
   revision, revocation procedure, recovery and audit owner. Supply positive and
   denial/outage/restore receipts before declaring the surface live.

## Consumer requirements (T06 / USER-WP-0037-T02)

user-engine owns the adapter and optional `AccountAuthority.root_grant` mapping.
Downstream workloads read that fact through user-engine's authenticated account
authority surface; they do not mint it from claims or configured root subjects.

1. Authenticate the source and bind the expected record ID before validating.
   Read with bounded timeout/size and preserve the actual successful owner read
   time. File mtime, document `updated_at`, HTTP proxy/cache hits, and viewing a
   cached observation do not establish a new authoritative read time.
2. Validate schema and semantics; compare with the last trusted document using
   `successor_errors`. Keep the last trusted revision/content across cache
   replacement and restart. Reject rollback and same-revision mutation; do not
   silently reset that baseline after a source/record change. The runtime owner
   must define the controlled rebootstrap procedure.
3. Call `observe_root_grant` with timezone-aware read/check times and the last
   trusted document (`previous_record`) when present. Match exact issuer and
   subject, without username, email, case folding, or issuer normalization.
   Only tenant `platform` and active `platform-root-custodian` entries qualify.
   Future records/grants, revoked/superseded entries and malformed reads yield
   no grant. An empty valid record also means no grant.
4. Cache read observations no longer than the record's `max_cache_seconds`
   (0–900 seconds). Re-check the owner for every root-grant-dependent write.
   Failed reads, stale data or rollback yield no grant for that action, even if
   a previous read granted it. Never extend expiry by re-reading local cache.
5. Retain only `subject`, fixed `grant`, `source.record_id/revision`,
   `observed_at`, and expiry/revocation time when known. No root grant for other
   tenants, unknown subjects, tenant admins, directory-only or JWT-only roots.
   The fact does not replace flex-auth authorization for the requested action.

## Acceptance receipts

| Receipt | Responsible repo | Unblocks |
| --- | --- | --- |
| ADR acceptance/amendment and surface/owner selection | net-kingdom records the founder's decision | T01, T04 |
| Owner workplan/task, authenticated read location, real ceremony provenance, atomic revision and denial/outage/recovery/audit evidence | Selected delivery repo; railiance-platform for OpenBao option | T05 |
| Adapter commit, exact mapping, retained source/time, and positive/negative integration tests against the delivered surface | user-engine, USER-WP-0037-T02 | T06 |

Integration evidence must cover grant, revocation, supersession, unknown/wrong
issuer, wrong tenant, projection-only input, expired cache, failed read,
rollback, same-revision mutation and no cache renewal on local reads. Local
fixtures establish algorithm behavior; they cannot satisfy live delivery or
real custody provenance. USER-WP-0037-T03's separate Hub credential admission
remains owned by user-engine/state-hub and is not delivery evidence for T05.