Incomex AI Portal
KB-36F7

B7 Governed Export-Step Contract — tool-kiem-thu (2026-06-10)

10 min read Revision 1
tool-kiem-thub7governed-export-stepnamed-querycontext-pack-readonlycontractarticle-13article-142026-06-10

B7 Governed Export-Step Contract — tool-kiem-thu

Status: B7_EXPORT_STEP_CONTRACT_DESIGN_COMPLETE_REFERENCE_VALIDATED · Date: 2026-06-10 Authoritative source rule: KB-FIRST / PG-FIRST / NATIVE-DRIVEN / LOCAL-LAST. This contract is design authority for the export step only; it grants no new runtime authority and is not a binding governed seal until owner/Codex promotion (see §10). Article 13: PG-first/native — every read is through the native context_pack_readonly gateway. Article 14: every claim below is backed by a live read-only probe run 2026-06-10 (see §3, §9) — no prose-only assertion.

Closes the first of B7's three deferred contracts (rev4 spec §19/§22): the governed export step + its named-query-catalog/driver/network-policy contract. The other two — a path-scoped server-enforced KB writer (D10) and a downstream gate-consumer (D11) — are out of scope here and remain blocked (see checkpoints/action-ready-blocker-after-b7-governed-export-packet-2026-06-10.md).

1. Purpose & boundary

The export step is the single, governed, read-only component that turns existing KB/PG/native read surfaces into a bounded, provenance-stamped packet (designs/b7-governed-packet-schema-2026-06-10.md) that the offline MVP later consumes. It is the only place a live governed read occurs. It is not the inspector and never runs inside the MVP sandbox.

[governed source surfaces] --(named query IDs only)--> [export step / context_pack_readonly gateway]
        --(provenance-stamped packet + manifest hash)--> [local packet file] --(offline)--> [MVP inspector]

The MVP holds no driver, no credential, no network (proven in Phase 2: reports/phase2-offline-mvp-execution-report-2026-06-10.md). All live-read authority lives here, and is itself fenced by the native gateway.

2. Who/what may export

Actor Permitted Basis
Governed export operator (human, OR an agent acting through the query_pg MCP gateway) running named queries only YES This contract. Demonstrated 2026-06-10 (§9).
Automated export service DEFERRED — not built. Until built, packets are produced by the operator above (rev4 spec §12.6: "a human runs the approved reads and assembles the packet"). residual blocker B7-EXP-2
The MVP inspector NEVER rev4 spec §2/§12: MVP is offline, no driver, no network.

3. Source surfaces — allowed vs prohibited (live-verified 2026-06-10)

Connected role verified live: context_pack_readonly — rolsuper=false, rolcreaterole=false, rolcreatedb=false, rolbypassrls=false, rolcanlogin=true, database directus. Gateway contract (from the query_pg tool + live probes): AST-validated, READ ONLY transaction, read-only role, statement_timeout 5s, hard LIMIT 500, no writes/DDL, restricted current_setting(), server-side DB allowlist {directus, incomex_metadata, workflow} (postgres ⇒ DENIED).

Allowed read surfaces (all confirmed to exist in directus.public, read-only, 2026-06-10):

  • DOT registry: dot_tools, meta_catalog (count 309 verified).
  • Reconciliation (canonical): v_dot_reconciliation_reliability (309 rows); diagnostic: v_dot_registry_no_file (41) — must carry precedence=diagnostic, never override canonical (Authority Contract Domain D).
  • FS mirror: wf_fs_dot_bin_snapshot. Orphan/dup result surfaces: wf_orphan_digest_v2, entity_dependencies, universal_edges, v_kg_edges_all (read result tables/views only — never execute a detector, Domain G).
  • Dual corpora: information_unit (219), tac_logical_unit (102) — dual-report only, never joined (Domain H).
  • Context pack: v_context_pack_latest, context_pack_manifest, v_entity_full_classification.
  • Command catalog (read): dot_iu_command_catalog (read-only listing; the 15 mutating=false rows are a candidate set, not an authorized call set — Domain C).
  • Flows (observe): directus_flows. Issues (read): system_issues.
  • KB: document_id + path + revision via the KB read connector's read verbs only.

Prohibited surfaces / actions: postgres DB (DENIED); any write/DML/DDL/CALL; any detector/engine execution (fn_dot_wf_orphan_detector*, fn_iu_op_*, fn_tac_log_checker_issue write sink); any TAC↔IU join; the 186 ∩ command-catalog "safe-call" formula (WITHDRAWN, join=0).

4. Role / permission requirements

The export step must run as a role with rolsuper=false ∧ rolcreaterole=false ∧ rolcreatedb=false ∧ rolbypassrls=false, inside a READ ONLY transaction, through the AST-validating gateway. context_pack_readonly satisfies this and is the designated role. The export step asserts these attributes at start (cheap read-only probe) and fails closed if any is not satisfied.

5. Named-query-ID requirement (no raw SQL)

The export step accepts named query IDs only, resolved against the sealed catalog (designs/b7-named-query-catalog-spec-2026-06-10.md). It accepts no raw SQL, no dynamically generated query text, no multi-statement, no CALL, no DML/DDL from any caller. Function calls are permitted only via an explicit read-only allowlist that is empty today ⇒ no function is called.

Why a named catalog and not "any SELECT" (live-proven 2026-06-10): the gateway is SELECT-only at the statement level, but a SELECT can still execute a function — SELECT pg_backend_pid() returned 514845. Therefore AST-SELECT-only does not prevent side-effect functions (rev4 ledger blocker 5, matrix #32→D9). Side-effect-function safety is enforced here by restricting to pre-approved, side-effect-free named queries whose function-allowlist is empty — not by trusting the gateway's SELECT filter alone.

6. Read-only verification (gateway, live-proven 2026-06-10, no mutation)

Probe Result Proves
INSERT INTO __b7_probe_nonexistent_tbl … [DENIED] only SELECT queries allowed, got Insert no DML
CREATE TEMP TABLE __b7_probe_ddl … [DENIED] only SELECT queries allowed, got Create no DDL
SELECT 1; SELECT 2 [DENIED] exactly one statement required, got 2 no multi-statement
current_setting('transaction_read_only') [DENIED] current_setting() only allowed for a safe parameter list restricted function surface
SELECT pg_backend_pid() 514845 (executed) functions DO run in SELECT ⇒ allowlist required (see §5)

These are real, repeatable, non-mutating probes. The write/DDL/multi-statement attempts were rejected before execution; nothing was created or changed.

7. Query logging / hash / purpose

For every exported item the export step records: named_query_id, governed_surface, observation_ts, source_revision, content_hash (sha256 over the canonical serialization of {named_query_id, governed_surface, sql, payload}), and authority_status (binding|review-ready|draft|evidence-only|superseded|diagnostic) + precedence. The packet manifest_hash is sha256 over the sorted named_query_id:content_hash pairs. Every count carries surface + denominator + query + observation timestamp + match key + population + confidence (Authority Contract §3 denominator discipline) — a single collapsed DOT number is treated as a disguised hardcode and rejected.

8. Packet output

The export step emits exactly the packet defined in designs/b7-governed-packet-schema-2026-06-10.md (source_mode=PACKET_DERIVED, freshness=AS_OF_EXPORT, decision_effect=NONE, may_gate=false, mandatory non-global-denial disclaimer). It writes a local file (and may be uploaded to KB by a separate human governed action — the export step is not a KB writer; D10 remains deferred). The packet is evidence input, not authority (Article 13: no shadow SSOT).

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

Acting as the §2 governed export operator through the gateway, six named queries were executed read-only and assembled into a real packet PKT-B7-REF-2026-06-10-001, manifest sha256:bba872b9a1f449e538b3db98fa26be71d6bb532ed604add66d91cbc4e56e6097, 6 items (dot_tools=309, IU=219, TAC=102, recon_rows=309, registry_no_file=41[diagnostic], system_issues=224019). It validated 10/10 positive + 7/7 negative (reports/b7-governed-export-packet-validation-report-2026-06-10.md). Fresh counts confirm the prior baseline (309/219/102/41) — no reconciliation conflict.

10. Failure modes

  • Role attribute check fails → BLOCKED_BY_UNSAFE_ACCESS, emit nothing.
  • Unknown / non-catalog query ID → reject, no execution.
  • Raw SQL / dynamic / multi-statement / DML/DDL/CALL submitted → reject (gateway + catalog), no execution.
  • LIMIT 500 truncation or statement_timeout hit → item marked TRUNCATED/UNVERIFIED, never silently completed.
  • Source returns no governed provenance → item degrades to NOT_EVIDENCED_IN_ALLOWED_SURFACES, never trusted because local.

11. Article 13 / 14 requirements (binding on every export)

  • 13: native gateway only; no local-first; packet is evidence not authority; no new authority created.
  • 14: no prose-only provenance — every item carries a real content_hash over real read output; no fake-green; truncation/timeout/empty disclosed; absence is scoped (NOT_EVIDENCED_IN_ALLOWED_SURFACES), never global.

12. Promotion requirements (why this is not yet a binding governed seal)

This contract is design-complete and reference-validated, but to become a binding governed authority it needs: (a) owner/Codex seal of the named-query catalog as authoritative (B7-EXP-1); (b) an automated, audited export service if/when batch export is needed (B7-EXP-2). Until then, operator-run export under this contract is the sanctioned interim path. No Codex consulted in this macro (per scope); promotion review is the owner's disposition.