kings-guard/docs/SecretUseSnapshotAdmission.md
tegwick 31e9963933 Admit source evidence snapshots and harden stream completeness
Assistant: codex
Assistant-Model: gpt-6-astra
Assistant-Session: 01a06e89-93a2-7aa2-82b3-ce5ccd2682e6
2026-09-05 00:42:19 +02:00

2.7 KiB

Secret-use snapshot admission

adapters.secrets_engine.snapshot_from_engine consumes the non-secret envelope returned by secrets-engine secret-use snapshot --json. It opens no client and reads no Engine evidence directory. The caller obtains the Engine response and supplies an explicit catalog_id -> (tenant_id, subject_id) binding; unbound or duplicate lanes are rejected. Catalog identifiers alone do not establish scope.

Source field Consumer meaning
surface, completeness_claimed Require secret-use-evidence and explicit false.
Envelope and lane as_of Snapshot creation time; lane times must match. Not the times of underlying events.
catalog_id, stage, kind Scoped catalog metadata.
ready, revocation_attempted, revocation_succeeded Optional historical booleans. Absence stays unknown; false stays false.
lifecycle_operation, evidence_kind Source-reported metadata, not a new event or inferred evidence classification.
cadence.form, cadence.interval Require heartbeat form and a positive interval; translate 1d to 86400 seconds.
Decision IDs, session handles, paths, mounts, field names, extra fields Not retained in the normalized observation.

The result is a separate SecretUseSnapshot, because ImmuneObservation requires an event actor, event time, and outcome this surface cannot provide. Readiness never becomes allow/deny. A snapshot older than the declared interval receives snapshot:stale; a future snapshot receives snapshot:future_timestamp. Even a fresh snapshot has unknown completeness. Its cadence declaration is not a received heartbeat. It supplies neither heartbeat assertions nor reconciliation counts, so generic stream evaluation is not invoked.

Each lane merges independently selected historical evidence. A newly created snapshot may contain old readiness or revocation information. No content posture or response proposal is generated from these untimed fields. KG-IN-0005 tracks source event timestamps/provenance, evidence-class bindings, scoped heartbeat and reconciliation evidence, and an authorized deployment capture before that lane can support posture. Snapshot parsing is locally admitted; secret-abuse posture remains pending.

Cadence examples for Qonto now follow InfoTechCanon standard/emission-cadence 0.1. extensions.net-kingdom holds source evidence classification and rate-monitoring metadata; extensions.kings-guard holds provenance. The old handover spec is historical. Tests validate both fixtures against the external owner schema when its checkout is available, without a copied generic schema. NetKingdom profile adoption remains with NK-WP-0035.