# Application navigation v1

`pkg/runtime/applicationnavigationv1` defines the shared vocabulary consumed by
Runtime, Controlplane initialization, and an application service. The capability
is `runtime.application-navigation.v1`. This release adds the semantic contract;
generated wire bindings and transport clients are separately released consumers.

Navigation is current tenant configuration. Its document revision is independent
of Catalog publication, schema generation, and engine generation. Those three
receipt fields must be zero. Runtime owns the stored document and effective
authorization; this package owns neither persistence nor identity resolution.

Read returns the complete administrator-authorized document. Resolve returns
caller-visible projections from the same current authority, omitting unavailable
applications or targets according to effective policy. An explicitly empty list
is a real value; absent lists are invalid. A saved target has exactly one arm:
resource, application-owned page ID, or an HTTP(S) URL without user information.
Labels do not identify resources or permissions. Application IDs, item IDs, page
IDs, resource IDs, and idempotency keys are opaque and case-sensitive: request
deduplication and response correlation both use exact identity. Control and
Unicode format characters are invalid in stored text. Page routes and availability
belong to the serving application release; an unavailable page reference remains
valid for administration and exact replay after an upgrade.

Save replaces the complete ordered item list using an expected revision and
idempotency key. The persistence owner must atomically commit the document and
operation receipt, reject conflicting key reuse, and reauthorize replay with
current permissions. Changed saves advance exactly one revision; no-op saves
preserve it. Exact replay returns the original operation result, even if the
document subsequently changed. Response validation binds application ID, item
content, revision, and change flag to the submitted request. Neither a request
identifier nor an idempotency key grants authority.

Requests and responses have bounded counts and encoded sizes. Response
validation rejects aggregate raw data beyond the response budget before parsing
text or allocating JSON; the final encoded-size check also counts escaping and
syntax. Validation requires
the common request context contract. Wire mapping, public route grammar, server
admission, permission policy, and transactional initialization are deliberately
outside this module. Consumers must not infer navigation from a Catalog snapshot
or regenerate it from permissions or a template after initialization.

Response failures retain their shared Runtime classification across Read, Resolve,
and Save: unsupported protocol/capability receipts are `INCOMPATIBLE` with the
required capability and supported protocol range; malformed or uncorrelated
current-state responses are `INTERNAL`; raw or JSON-encoded response byte
exhaustion is `RESOURCE_EXHAUSTED` with `SEMANTIC_RESPONSE_BYTES` and the maximum.