# Secret-use evidence engine contract

Status: **shipped** as `secrets-engine secret-use snapshot`. Observation-input
admission remains **proposed** until kings-guard consumes it. `layer.yaml`
`owner_status` stays `proposed` until that admission. Completeness is not
claimed.

Standard: NetKingdom Security Layer Model v0.7 §9.6. Companion:
`net-kingdom/SECURITY-COMPANION.md` §6.

## What this is

A read-only Lifecycle engine surface of **non-secret** lease, revocation,
mount, rotation, and delivery-session metadata, so kings-guard can evaluate
secret-abuse posture without a vault client.

`secrets-engine route` and `secrets-engine audit` are operator summaries over
local JSONL. They are not this surface. The shipped command is
`secrets-engine secret-use snapshot [--catalog-id ID] [--json]`. It reads the
catalog and local evidence only. It never contacts OpenBao.

## Bound (normative)

The archive proves the records it holds were not altered or truncated after
arrival. It does **not** prove a record was sent. Absence of a record is **not**
evidence of non-occurrence. Completeness is not claimed.

This surface cannot close adversarial omission at a compromised source. Cadence
for load-bearing classes is a heartbeat (`secrets-engine evidence heartbeat`),
not rate monitoring.

## Fields (non-secret)

| Field | Meaning | Freshness |
| --- | --- | --- |
| `as_of` | UTC timestamp of the snapshot | Snapshot time |
| `catalog_id` | Lane id | Catalog load |
| `stage` | `build` \| `test` \| `prod` | Catalog load |
| `kind` | `kv` \| `auth-capability` | Catalog load |
| `mount` | OpenBao mount name | Catalog load |
| `path` | KV path or allowlisted auth path, never a value | Catalog load |
| `field_names` | Declared field names, never values | Catalog load |
| `ready` | All declared fields present (boolean) | Last route/verify |
| `session_handle` | Accessor fingerprint only | Last exec/verify |
| `revocation_attempted` | Boolean | Last session |
| `revocation_succeeded` | Boolean | Last session |
| `lifecycle_operation` | `suspend` \| `deactivate` \| `destroy` \| `revoke` if one ran | Last lifecycle |
| `decision_id` | Present only where a decision was rendered | Last privileged action |
| `stance_stage` / `stance_failure_mode` | Named PEP residue | Last privileged action |
| `evidence_kind` | `load-bearing` \| `attributive` \| `heartbeat` | Per record |

Forbidden in this surface: secret values, tokens, passwords, AppRole
`secret_id`, raw accessors, certificate private keys, subprocess argv, and
exception prose.

## Freshness

Every row carries `as_of`. There is no cached authorization verdict. A consumer
must not treat a stale snapshot as a standing allow. Cadence for load-bearing
classes is the heartbeat declared in `evidence-classification.yaml`:

```text
form: heartbeat
interval: 1d
command: secrets-engine evidence heartbeat
```

The snapshot envelope repeats that cadence. Evidence-derived fields (`ready`,
session, stance, decision id) appear only when a local record exists. Omission
is not non-occurrence.

## Destination

Intended owner of custody is `audit-core`. Today the engine queues load-bearing
records in `evidence_dir/outbox/` and writes attributive records to local
JSONL. Drain to `audit-core` is best-effort and is never on the mutation path.

kings-guard reads this engine surface, not OpenBao.

## Non-responsibilities

This surface does not decide whether an action is permitted, does not expose an
approval-validity query, does not prove omission at source, and does not
observe production events kings-guard has not received. Companion §10 still
holds: nothing is observed in production until kings-guard reports otherwise.

## Assent

A coordination message to kings-guard records this contract. Assent or contest
belongs in kings-guard's own voice.

**2026-09-01:** kings-guard assented, in its own voice (State Hub message
`75ebd2cc-a166-4676-94aa-deef2791c0c9`), to this document as a proposed
Engine / Lifecycle read-only non-secret surface. Assent covers: no secret
values; destination audit-core; completeness not claimed; heartbeat rather
than rate monitoring for load-bearing classes; kings-guard reads this engine
surface, never OpenBao. kings-guard will not consume it as an observation
input until the surface ships and publishes its cadence declaration.
`layer.yaml` `owner_status` remains `proposed` until that surface exists.