B7 Governed Packet Schema — tool-kiem-thu

Status: B7_GOVERNED_PACKET_SCHEMA_DESIGN_COMPLETE_REFERENCE_VALIDATED · Date: 2026-06-10 Schema id: b7-governed-packet/v1. Reference instance PKT-B7-REF-2026-06-10-001 validated 10/10 + 7/7 (reports/b7-governed-export-packet-validation-report-2026-06-10.md). Article 13/14: native-driven provenance; tamper-evident; no fake-green; absence is scoped, never global.

The serialization the export step emits and the offline MVP consumes. Pins rev4 spec §9/§10/§16.1 into a single schema, reusing the proven native context_pack_manifest / v_iu_collection_manifest provenance shape.

---

1. Reuse-first basis (Article 13)

Native precedents verified 2026-06-10:

• context_pack_manifest: generated_at, git_commit, logical_checksum_sha256, file_checksum_sha256, publish_status, kb_mirror_status, …counts… → proves the generated_at + dual-checksum + publish-status manifest pattern. manifest_hash here = the analogue of logical_checksum_sha256.
• v_iu_collection_manifest / v_iu_collection_export_status: collection_key, manifest_digest, digest_present, canonical_address, last_exported_at, lifecycle_status → proves the per-item digest + canonical_address (provenance) + export-status + lifecycle pattern.

The schema adapts these; it does not invent a third unrelated manifest authority (the generic package_manifest schema remains a deferred true gap, Codex-review-mandatory — reuse map #8.3).

2. Packet-level fields

Field	Req	Value / rule
schema	yes	"b7-governed-packet/v1"
packet_id	yes	stable ID, e.g. PKT-B7-REF-2026-06-10-001
packet_as_of	yes	export timestamp (from SELECT now() through the gateway)
source_mode	yes	"PACKET_DERIVED" (rev4 §2)
freshness	yes	"AS_OF_EXPORT" — the consumer's staleness gate keys on packet_as_of
export_operator	yes	{role, database, gateway} — role MUST be read-only (rolsuper/createrole/createdb/bypassrls all false)
manifest_hash	yes	sha256: over the sorted named_query_id:content_hash pairs
decision_effect	yes	"NONE" (non-gating, rev4 §4.0)
may_gate	yes	false
non_global_denial_disclaimer	yes	verbatim; scopes all derived verdicts to enumerated surfaces as-of packet_as_of; absence ⇒ NOT_EVIDENCED_IN_ALLOWED_SURFACES, never global
items	yes	array of §3 items

3. Per-item fields

{
  "named_query_id": "NQ-…-V1",
  "payload": { … literal result rows/aggregate … },
  "source_metadata": {
    "governed_surface": "directus.public.<table_or_view>",   # never a local path
    "surface_kind": "BASE TABLE" | "VIEW",
    "named_query_id_or_kb_path": "NQ-…-V1" | "knowledge/…",
    "observation_ts": "<packet_as_of or per-query ts>",
    "source_revision": "<rev token | as-of-export | stale-YYYY-MM-DD>",
    "content_hash": "sha256:<hex over canon({named_query_id,governed_surface,sql,payload})>",
    "authority_status": "binding|review-ready|draft|evidence-only|superseded|diagnostic",
    "precedence": "canonical|diagnostic"
  }
}

4. Provenance & authority rules (rev4 §16.1 — location is not authority)

• Every item MUST carry full source_metadata; a missing field ⇒ the consumer marks the item NOT_EVIDENCED_IN_ALLOWED_SURFACES (validator V05).
• governed_surface MUST be a native surface; a local-file surrogate ⇒ FLAG_LOCAL_FIRST_AUTHORITY/CONFLICT, prefer KB/PG (validator V06).
• A KB path alone never makes a source authoritative; authority_status of review-ready/draft treated as binding ⇒ FLAG_AUTHORITY_VIOLATION.
• A diagnostic source (e.g. v_dot_registry_no_file) MUST be precedence=diagnostic and MUST NOT override a canonical reconciliation surface (validator V09; Domain D).

5. Integrity / tamper-evidence

• content_hash is sha256 over the canonical (sort_keys, UTF-8, compact) serialization of {named_query_id, governed_surface, sql, payload}. Any payload edit changes the hash (validator V08 / negative N1).
• manifest_hash reproduces from the item hashes; tampering either is caught (V07 / negative N4).
• The emitted packet exposes no raw SQL to the consumer — only named_query_id (validator V10 / negative N6). SQL lives in the catalog, not the packet.

6. Staleness / TTL

No absolute TTL field; freshness is AS_OF_EXPORT + packet_as_of. The consumer decides acceptable age and degrades an over-age item to BLOCKED_BY_UNVERIFIED_SOURCE (consumption contract §4). A source_revision of stale-<date> marks a known-stale diagnostic.

7. Scope / allowed consumer / limitations

• scope = the enumerated items[].governed_surface set, as of packet_as_of.
• allowed_consumer = the offline MVP inspector (read-only). The packet is evidence input, not authority and non-gating (decision_effect=NONE).
• Limitations: counts are denominator-scoped (never collapsed to one canonical DOT number); TAC/IU never joined; no execution/run evidence (that is the deferred Call Contract).

8. Checksum/signature placeholder

manifest_hash provides tamper-evidence today. A cryptographic signature (operator key) is a future field (manifest_signature) — deferred with the automated export service (B7-EXP-2); absence is disclosed, not faked.

9. Reference instance (real, 2026-06-10)

PKT-B7-REF-2026-06-10-001, packet_as_of=2026-06-10T02:40:06.819600+00:00, operator context_pack_readonly/directus, manifest_hash=sha256:bba872b9a1f449e538b3db98fa26be71d6bb532ed604add66d91cbc4e56e6097, 6 items. Per-item hashes and full payloads in the validation report. Schema conformance: V01–V10 PASS.