net-kingdom/docs/contracts/root-grant-read-contract_v0.1.md

Root-grant read contract v0.1

Owner: net-kingdom. Status: proposed implementation contract, 2026-10-03. Tracks NK-WP-0045 and proposed ADR-0017. Schema: custody-record v0.1. Reference implementation and fixtures: validator.

This contract prepares delivery; it does not accept the ADR, choose a live endpoint, 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's open decision cef97ccd-4ee7-40fe-859e-1df9c9360ecb must accept/amend ADR-0017 and select one delivery surface and accountable repo. user-engine has already confirmed the exact subject and envelope mapping (message 60acf176, recorded in USER-WP-0037-T02).

Option	Delivering repo	Requirements and tradeoff
OpenBao-held non-secret document	railiance-platform	Governed exact-path workload read, separate custody write lane, atomic revision updates; uses existing custody infrastructure but needs consumer identity admission. Recommended for review, subject to owner confirmation.
Private platform service	Named platform runtime owner	Authenticated bounded read, atomic document, custody write/audit lane, availability and recovery; adds a runtime to operate. NetKingdom supplies canon, not a new runtime by default.
Repository artifact delivered to workloads	Named artifact/distribution owner	Authenticated provenance, atomic publication, revision rollback protection and a refresh route for sensitive writes; an indefinitely cached checkout is insufficient.

Decision receipt must name the surface, delivering repo, trusted record ID, consumer identity mechanism, writer/custody approval lane and bootstrap provenance. No endpoint, OpenBao path or access grant is invented here. If the ADR changes, schema, validator and this contract must be reconciled before use.

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.