RS-OP-POSTURE: Operations posture document

View as Markdown

This document defines the operations posture observation that Registry Relay and Registry Notary return from their protected admin surfaces. It gives operators and tooling authors one stable, versioned document for observing build, runtime, configuration, deployment, audit, and component-specific status without treating that observation as an authorization decision or a source of secrets.

The key words in this document are interpreted per RS-DOC Section 2. Defined terms are used per RS-TERMS.

Portable structural validation is defined by the in-tree draft schema; release-tagged source evidence for this revision is pending. This specification defines the operational meaning, semantic producer validation, and evolution rules that JSON Schema alone does not express.

Version history

Version	Date	Status	Change
0.1.0	2026-07-19	draft	Initial posture-document contract for `registry.ops.posture.v1`.
0.1.1	2026-07-19	draft	Added restricted Relay per-resource refresh health before the 1.0 schema freeze.
0.1.2	2026-07-20	draft	Replaced waiver reason text with validated operator references and optional summaries before the 1.0 schema freeze.
0.1.3	2026-07-23	draft	Reserved credential-shaped waiver-reference prefixes before the 1.0 schema freeze.
0.1.4	2026-07-24	draft	Separated portable waiver-schema checks from contextual semantic validation before the 1.0 schema freeze.

1. Scope and surface

This specification covers a point-in-time operations observation returned by GET /admin/v1/posture. Registry Relay and Registry Notary expose that route on their protected admin surfaces, not in the public Registry Relay API document. The product route and authorization details remain with the Registry Relay API reference and the Registry Notary API reference.

This specification does not define deployment configuration, profile-gate policy, audit retention, or a new authorization scope. It also does not make a posture document a health guarantee, a conformance certificate, or proof that an external artifact is safe to trust.

2. Document envelope

The schema identifier is registry.ops.posture.v1. Its canonical JSON Schema identifier is https://id.registrystack.org/schemas/registry-platform/registry.ops.posture.v1.schema.json. The root object and named nested objects use additionalProperties: false, except for two explicitly modeled maps. standards_artifacts accepts producer-selected artifact labels, while each artifact-reference value has the closed shape defined by the schema. notary.signing_keys.readiness accepts signing-key identifiers, while each value is one of the defined readiness states.

REQ-OP-POSTURE-001: A producer MUST emit a JSON object that validates against registry.ops.posture.v1. It MUST include schema, observed_at, component, instance, build, runtime, configuration, standards_artifacts, and posture. observed_at MUST be an RFC 3339 date-time and schema MUST equal registry.ops.posture.v1. A producer MUST NOT add a root or nested property that the schema does not model.

REQ-OP-POSTURE-002: A runtime endpoint producer MUST include tier as either default or restricted, even though the v1 schema permits its omission. Consumers of a runtime endpoint MUST treat an absent tier as invalid for that endpoint rather than silently guessing the disclosure class.

Component rules

component is exactly one of registry-relay and registry-notary. The component selects one, and only one, component section.

`component` value	Required section	Forbidden section
`registry-relay`	`relay`	`notary`
`registry-notary`	`notary`	`relay`

REQ-OP-POSTURE-003: A registry-relay document MUST contain relay and MUST NOT contain notary. A registry-notary document MUST contain notary and MUST NOT contain relay. A consumer MUST reject a document that does not satisfy this pairing, even when the shared envelope itself appears complete.

The shared sections state the following categories of observation:

instance: deployment identity and environment, with optional owner, jurisdiction, and URL.
build: package and version, with optional source revision and enabled features.
runtime: authentication mode, admin enablement, and readiness state.
configuration: configuration source, reload support, the latest applied state, and optional emergency or trusted-root state.
deployment: optional profile, findings, and waivers.
audit: optional assurance characteristics for the configured audit path.
standards_artifacts: observed published-artifact references keyed by artifact label.
posture: warnings, actionable findings, and the observed audit-shipping state.

The relay section reports configured surface counts, metadata-manifest state, adapter state, and restricted per-resource refresh health. The notary section reports claim and credential-profile counts plus state, credential-status, federation, OID4VCI, and optional subject-access observations.

Deployment waiver metadata

A deployment waiver names one finding and expiry date. Its reference is a required opaque operator-local approval, incident, or ticket identifier. The optional summary adds short operational context. Neither value grants authority or changes which gate severities can be waived.

REQ-OP-POSTURE-011: A producer that emits a deployment waiver MUST include reference as an already canonical 1 to 128 byte string using only ASCII letters, digits, ., _, :, and -. The reference MUST NOT contain ... It MUST NOT start, case-insensitively, with the credential-shaped prefix Bearer:<value> or Basic:<value>, directly or after Authorization:. OPS-2026-0042 is an accepted ticket-style reference. If the producer emits summary, the summary MUST be an already trimmed 1 to 256 Unicode-character string without control characters, an authorization value, or a private-key begin marker. The producer MUST omit summary when no summary was configured and MUST NOT emit the retired reason property. The JSON Schema enforces the reference syntax and reserved prefixes. It also enforces the summary length, C0 and C1 control-character exclusion, and leading or trailing whitespace exclusion. The schema does not encode context-sensitive authorization-value or private-key marker detection. Before emitting either waiver shape, a producer MUST apply semantic validation equivalent to validate_deployment_waiver_metadata. Schema acceptance alone does not satisfy the contextual exclusions in REQ-OP-POSTURE-011. These metadata rules do not alter expiry behavior: an expired waiver stops suppressing its finding. They also do not alter the hard-gate boundary: startup_fail and readiness_fail findings remain non-waivable.

3. Examples

The schema-valid Registry Relay default example and Registry Notary default example show the default projection for each component. The restricted-tier fixture shows fields that are valid but intentionally absent from the default projection. The checked-in registry-relay.restricted-posture.valid.json fixture shows the Relay refresh-health shape and its last-good serving state.

Examples are observations, not deployment templates. An operator MUST supply actual deployment configuration through the product’s configuration surface, not by copying posture values into configuration.

4. Sensitivity tiers and emit-only filtering

The tier identifies the disclosure class of the document, not the caller’s authorization level. The product endpoint remains responsible for authentication and authorization before it returns either tier. A deployment MUST NOT assume that selecting restricted grants a caller any new permission.

REQ-OP-POSTURE-004: A producer of the default tier MUST create its emitted document from the default JSON-pointer allowlist. It MUST use an emit-only projection, not a blacklist redaction pass over a complete operational object. If a leaf is not allowlisted, the producer MUST omit it rather than mask it, hash it, or preserve it in an opaque nested value.

The default projection includes operational status, counts, selected digests, finding identifiers and severities, and non-secret audit-shipping observations. It excludes values that can reveal topology or operational free text, including instance URLs, build revisions and features, trusted roots, artifact URLs, waiver references and summaries, signing-key details, and Notary federation identities or peers. The checked-in sensitive fixture proves that the projection excludes credentials, private keys, source URLs, subject identifiers, raw rows, claim values, and the restricted topology fields. The default tier also excludes relay.refresh_health, including its dataset and resource identifiers.

REQ-OP-POSTURE-005: A restricted document MAY contain every field modeled by the v1 schema, including fields excluded from the default allowlist. It MUST still conform to the closed schema and MUST NOT contain secret material, raw registry data, claim values, subject identifiers, bearer tokens, or private keys. The restricted tier is not a substitute for a private admin listener, access control, or operator review.

Consumers MUST treat a missing field as unreported, not as false, none, or a failed check. Consumers MUST NOT reconstruct excluded values from a default-tier document or compare a default and restricted observation as though omission proves a configuration change.

5. Schema evolution

The v1 schema is a strict closed contract, not an extensible envelope. Its schema field is a constant and the root and named nested objects reject unknown keys, apart from the explicitly modeled maps in Section 2. This lets consumers validate a complete known shape before making an operational decision.

REQ-OP-POSTURE-006: The identifier registry.ops.posture.v1 MUST continue to name exactly its published v1 shape and meaning. Every post-1.0 shape change, including an additive optional property, a new required property, a removed or renamed property, a changed type or enum, or a changed field meaning, requires a new schema identifier and new JSON Schema document. A producer MUST NOT send a changed shape while retaining registry.ops.posture.v1.

Adding an artifact label inside standards_artifacts does not change the v1 shape because that map is the explicitly modeled extension point. The new entry’s value MUST remain a v1 artifact_reference object.

REQ-OP-POSTURE-007: A consumer MUST dispatch on schema before interpreting the document. It MUST validate the complete document against the corresponding schema, reject an unknown schema identifier, and reject unknown properties in a v1 document. A consumer that supports a later schema identifier MUST retain an explicit validation path for v1 until its own compatibility policy retires v1.

6. Producer and consumer expectations

REQ-OP-POSTURE-008: A producer MUST observe the current runtime state, set observed_at at the time of that observation, select the component section that matches the runtime, and emit a result that conforms to the selected schema and tier. It MUST select posture fields through typed, explicit construction and apply the selected tier’s emit-only projection. This construction MUST prevent secret-bearing configuration and production data from being copied into the output.

REQ-OP-POSTURE-009: A consumer MUST use posture as an observation for operations and troubleshooting only. It MUST evaluate readiness, findings, audit status, and artifact observations according to its own policy and MUST NOT treat any of them as an authorization grant, an external conformance claim, or proof of remote receipt or retention.

Relay refresh health

REQ-OP-POSTURE-010: A restricted Registry Relay producer MUST include one relay.refresh_health entry for every resource with a valid last-good table. Each entry MUST carry the configured dataset_id and resource_id, the RFC 3339 last_successful_refresh_at data-load time, a saturating consecutive_refresh_failures count, and serving_last_good. serving_last_good MUST be true exactly when the resource remains ready and the consecutive failure count is greater than zero. A failed refresh or metadata poll MUST increment the count without advancing the last successful data-load time or making a valid last-good resource unready. A successful data load MUST reset the count and advance the time. A successful unchanged metadata poll MUST reset the count without advancing the time.

Refresh health describes Relay’s ability to observe and load the configured source. It MUST NOT be interpreted as semantic or domain freshness of the source records. An operator SHOULD alert at three consecutive failures and MAY use a lower threshold when a freshness service-level objective requires it.

Conformance

A producer conforms to this specification when it emits a schema-valid, component-consistent, tier-labeled observation; uses the emit-only allowlist for default output; keeps restricted output within the same secret and source-data boundary; assigns a new schema identifier for every post-1.0 shape change; reports Relay refresh health when applicable; and emits only validated deployment waiver metadata (REQ-OP-POSTURE-001 through REQ-OP-POSTURE-006, REQ-OP-POSTURE-008, REQ-OP-POSTURE-010, and REQ-OP-POSTURE-011).

A consumer conforms when it validates and dispatches by schema, enforces component pairing, handles omissions as unreported, and does not elevate posture observations into proof or authority (REQ-OP-POSTURE-002, REQ-OP-POSTURE-003, REQ-OP-POSTURE-007, and REQ-OP-POSTURE-009).

Evidence

This specification is verified: its document shape, examples, component pairing, and tier filter are shipped in Registry Platform and exercised by contract tests.

Release-tagged source evidence for the v1 JSON Schema’s waiver definitions and shared portable metadata constraints is pending. The source pack will be linked after those changes merge.
The posture contract tests validate both examples, the default allowlist projection, the sensitive fixture, and exclusion of restricted fields from default output (Sections 3, 4, and 6).
The checked-in restricted Relay posture fixture and Registry Relay admin tests validate per-resource last-good state, tier filtering, and the live producer shape (Sections 4 and 6).
The Registry Relay admin handler and Registry Notary admin handler select the requested tier and return the shared posture document (Sections 1, 4, and 6).

Harden a production deployment explains how an operator uses posture findings while preparing a deployment.
Registry Relay protocol defines the Relay admin-surface boundary.
Registry Notary protocol defines Registry Notary’s protected service surface.
RS-SEC-G defines the security model and the operator boundary this observation helps inspect.