# Export Console Bundle Contract (Draft) — PREP-EXPORT-CONSOLE-23-001

Status: Draft (2025-11-20)
Owners: Policy Guild · Scheduler Guild · Observability Guild
Scope: Define the evidence bundle exported by Policy Engine for Console replay/verification and the scheduler job contract that produces it.

## 1) Manifest format
- Container: tar.gz (deterministic ordering, UTC mtime `1970-01-01T00:00:00Z`), content-addressed by SHA-256 of archive bytes.
- Root manifest: `bundle.manifest.json` (unsigned) and `bundle.manifest.dsse` (signed, optional until Rekor/Authority hookup).
- `bundle.manifest.json` fields:
  - `bundle_id` (string, required): GUID/ULID assigned by Policy Engine.
  - `policy_run_id` (string, required): ID of originating policy run.
  - `tenant_id` (string, required): tenant scope.
  - `policy_version` (string, required): semantic version or commit hash of the policy set evaluated.
  - `inputs_hash` (hex): SHA-256 of normalized inputs (SBOM, advisories, VEX) used for the run.
  - `generated_at` (string, RFC3339 UTC): timestamp of bundle creation.
  - `schema_version` (string): `policy.export.console.v1`.
  - `artifacts`: array of artefact descriptors with `{path, media_type, sha256, purpose}`; expected purposes: `policy-run-summary`, `effective-findings`, `inputs`, `logs`, `metrics`.
  - `signatures`: optional array referencing DSSE statement(s) with signer identity and key hint.

## 2) Artefact layout
- `summary/policy-run.json`: minimal run summary (status, duration, rule counts, decision stats).
- `findings/effective.ndjson`: deterministic NDJSON list of effective findings emitted by the run (sorted by `finding_id`).
- `inputs/sbom/*.json`: normalized SBOM slices (content-addressed references pointing back to source digests).
- `inputs/advisories/*.json`: advisories snapshot used during evaluation.
- `inputs/vex/*.json`: VEX statements snapshot.
- `telemetry/logs.ndjson`: structured logs with correlation IDs and runner metadata (no secrets, scrub file paths).
- `telemetry/metrics.json`: counters/histograms for run (p50/p95 latency, evaluated rules, facts ingested).

## 3) Scheduler job contract
- Job type: `policy.export.console`.
- Inputs:
  - `policy_run_id` (required)
  - `tenant_id` (required)
  - `priority` (enum: background|interactive; default background)
  - `include_logs` (bool, default true)
- Outputs:
  - `bundle_pointer` (URI/path) to stored bundle in Evidence Locker/Export Center bucket.
  - `bundle_id`, `sha256`.
- Events:
  - Progress events to Observability stream `{job_id, state, percent, bundle_id?, error?}`.
  - Completion emits `policy.export.console.completed` with bundle metadata for Console ingestion.

## 4) Determinism & security
- All NDJSON/JSON sorted by stable keys; floats avoided; timestamps UTC RFC3339.
- No inline PII; tenant-scoped file paths must be redacted or normalized.
- Offline-friendly: no external references; all URIs either `bundle://` or content hashes.

## 5) Open items / decisions needed
- Signer identity and DSSE profile (Rekor optional) — awaiting Authority/Attestor alignment.
- Exact location for bundle storage (Evidence Locker vs Export Center) — propose Evidence Locker namespace `policy-console/` with retention 30d.
- Metrics schema: align with Observability guild’s latest counters/histogram names.

## 6) Handoff
Cite this file in sprint trackers for PREP-EXPORT-CONSOLE-23-001. When upstream decisions land, update schema_version and finalize DSSE profile.