audit-core/SCOPE.md

# SCOPE

Boundary contract for `audit-core`, aligned to NetKingdom Security Layer Model
v0.7 (accepted) and its working companion. `INTENT.md` says what Audit Core is
for; this file says what it does and does not do, and is the file to check
before adding a surface.

## One-liner

The estate's Evidence engine: durable, tenant-aware custody of audit events,
with an honest and bounded integrity claim.

## Layer and role

**Engine / Evidence** (statute §3.3, §4). Deterministic API over one modeled
concept — the audit event. Declared in `INTENT.md` frontmatter and `layer.yaml`.

Audit Core is **not** a PDP, not a PIP, and not PEP-shaped. It renders no
decision, supplies no claim a decision consumes, and causes no protected side
effect of its own.

## In Scope

**Custody and integrity**

- Event ingestion, validation, normalization to the Audit Core envelope,
  redaction, and append-only operational custody.
- Sender registration and binding; tenant and scope attribution.
- Hash-chain integrity: link, verify, chain-head attestation, and the
  `GET /v1/integrity` operator surface.
- The honest custody claim — `custody_class`, `immutable`, `tamper_evidence`,
  `recoverable_days` — stated at no more than `docs/integrity.md` delivers.
- Retention profiles, search and export entitlements, dead-letter and
  secret-finding surfaces.

**Evidence-role obligations under v0.7 §9.6** *(largely not yet built — see
`workplans/AUDIT-WP-0009-evidence-role-conformance.md`)*

- Recording, per source, whether its evidence is **load-bearing** or
  **attributive**, because the obligations differ.
- Accepting and storing a source's declared **emission cadence**, and raising a
  finding when the stream falls below it — the stream observed, not only its
  contents.
- **Heartbeat** ingestion and missing-heartbeat findings for low-volume
  load-bearing classes, where rate monitoring cannot work.
- A **reconciliation** surface: per-source, per-class event counts a source can
  compare against its own state transitions.
- Registering `approval-engine` as a distinct source carrying issuance, use,
  supersession, and revocation (§9.4, `AUDIT-IN-0001`).

**Conformance**

- Machine-readable layer declaration (`layer.yaml`) and a conformance test.
- A total list of infrastructure contacts, catalogued or not, so the §5 check
  is total rather than vacuous.

## Out of Scope

**Boundaries fixed by the statute — these are permanent, not "not yet"**

- **Any authorization decision.** `access-engine` is the only decision point
  (§6). Audit Core renders and caches none.
- **An approval-validity query.** Records, yes; a verdict on whether an approval
  is still valid, never (§9.4). A consumer branching on such an answer would
  route an authorization decision through the audit fabric.
- **Operative approval state** — the durable object, atomic supersession, single
  consumption, revocation. That is `approval-engine`'s (§9.4).
- **Emission atomicity at the source.** Completeness at the boundary is the
  emitter's obligation; an archive cannot retrofit it (§9.6).
- **Any claim that the archive proves an event occurred, or that absence proves
  it did not** (§9.6).
- **Policy decision making**, per `INTENT.md`.

**Not owned here**

- Procuring or operating S3 / Barman / WAL; the `platform:audit-storage` booked
  cost or a second usage stream.
- WORM, object lock, or ITC-CAP `data.archive`. Ruled a different store with a
  different owner (statute §16); the stronger-custody gap is withdrawn, not
  pending.
- A `rapp.yaml` in this repo (schema requires `rapp-*`).
- Public ingest.
- Unrelated adjacent systems; irreversible operational decisions without human
  approval.

## Current State

- Status: production. Receiver on railiance01 (`namespace audit-core`), Postgres
  operational custody on `platform-pg`, sender `user-engine`.
- Recovery is the platform `data.backup` window (30 days). `/readyz` reports
  `custody_class=operational`, `recoverable_days=30`.
- Hash chain verified on 30 live events
  (`docs/evidence/chain-head-20260816.json`).
- ITC-CAP case: `data/capability/audit-core-operational.json` at D4.
- Tenancy posture: `tenancy.yaml` — declared `I1 A2 E1 P1 R1`, target `E3`/`R2`.

**Known conformance gaps** (assessed 2026-08-29,
`history/2026-08-29-v0.7-alignment-and-scope-assessment.md`):

- ~~`tamper_evidence=True` returned unconditionally by the Postgres backend~~
  **Closed 2026-09-06 (`AUDIT-WP-0009-T01`).** The flag is now derived per
  read from live chain and attestation state against a declared 168h
  freshness window. Until `AUDIT-WP-0009-T02` schedules attestation, the
  honest answer in production is `false` — the overclaim is gone, the
  precondition is not yet met.
- No cadence, heartbeat, or reconciliation surface exists. The §9.6 detection
  obligations Audit Core argued for are not yet supportable by Audit Core, so
  a suppressed load-bearing event still produces silence
  (`AUDIT-WP-0009-T04`/`T05`/`T06`).
- Load-bearing classification **does** now exist: `evidence_kind` on
  `SenderIdentity` and the registration schema, defaulting to `attributive`
  (`AUDIT-WP-0009-T03`, closed 2026-09-06).
- `approval-engine` registration inputs are prepared and inert pending its
  token, a confirmed tenant scope, and an operator apply —
  `docs/approval-engine-source-registration.md` (`AUDIT-WP-0009-T09`).
- ~~No negative test asserts the absence of an approval-validity surface.~~
  **Closed 2026-09-06 (`AUDIT-WP-0009-T08`)**,
  `tests/test_approval_validity_prohibition.py`.

## Getting Oriented

- Start with: `INTENT.md`, then `net-kingdom/SECURITY-COMPANION.md`
- Bound on what may be claimed: `docs/integrity.md`
- Agent instructions: `AGENTS.md`
- Workplans: `workplans/`