B7 Named-Query Catalog Spec — tool-kiem-thu

Status: B7_NAMED_QUERY_CATALOG_PROVISIONAL_NON_AUTHORITY · Date: 2026-06-10 Authority class: PROVISIONAL NON-AUTHORITY. No governed "named query catalog" surface exists yet (verified 2026-06-10: directus.public has domain-specific packet/manifest views and dot_iu_command_catalog, but no generic named-query registry). This spec defines a catalog model and its promotion requirements; it does not claim a governed catalog exists. Article 13/14: native-driven; every existence claim is a live read; no fake-green.

Part of the B7 export-step contract (contracts/b7-governed-export-step-contract-2026-06-10.md). The catalog is what makes "named query IDs only, no raw SQL" enforceable.

---

1. Reuse-first: adapt the proven native catalog shape (Article 13)

The native layer already has a governed catalog with exactly the columns this needs — dot_iu_command_catalog (verified 2026-06-10): command_name (text), category (text), mutating (boolean), reversible (boolean), target_functions (ARRAY), registered_at (timestamptz). The named-query catalog adapts this shape rather than inventing a new authority:

dot_iu_command_catalog column	named-query-catalog field	meaning
command_name	named_query_id	stable ID
category	category	source family (registry/recon/iu/tac/graph/issues/context-pack)
mutating	side_effect_free = NOT mutating	must be true for export use
target_functions	function_allowlist	empty today ⇒ no function called
registered_at	registered_at + version	versioning / change control

This is a precedent to mirror, not a surface to fork or write to (Domain C/H: no new authority, no mutation).

2. Query-ID format

NQ-<DOMAIN>-<NOUN>[-<QUALIFIER>]-V<major> — uppercase kebab, ends in an explicit version token. Examples (all used in the 2026-06-10 reference packet): NQ-DOT-REGISTRY-COUNT-V1, NQ-IU-INVENTORY-COUNT-V1, NQ-TAC-INVENTORY-COUNT-V1, NQ-DOT-RECON-CANONICAL-ROWS-V1, NQ-DOT-REGISTRY-NO-FILE-COUNT-V1, NQ-SYSTEM-ISSUES-COUNT-V1.

3. Per-entry fields (catalog row)

Field	Required	Notes
named_query_id	yes	§2 format; unique
version	yes	bump on any SQL/semantics change; old version retained (deprecation, §8)
owner / authority_status	yes	PROVISIONAL_NON_AUTHORITY until promoted (§9)
category	yes	source family
approved_source	yes	the single governed surface (table/view) it reads; must be on the §3 allowlist of the export-step contract
sql_text	yes	the exact read-only SELECT; stored in the catalog, never accepted from a caller
expected_output_schema	yes	column names + types of the result
side_effect_free	yes	must be true; entry rejected otherwise
function_allowlist	yes	list of read-only functions the SQL may call; empty by default
read_only_role_required	yes	context_pack_readonly (or equal attributes)
dynamic_sql	yes=false	no dynamic/parameter-built text
multi_statement	yes=false	single statement only
evidence_required_for_approval	yes	see §10
registered_at / deprecated_at	yes/optional	change control

4. Hard invariants (every entry)

• No raw SQL from callers — the export step resolves an ID to catalog sql_text; it never executes caller-supplied text.
• No dynamic SQL, no multi-statement, no CALL, no DML/DDL — enforced by the catalog (dynamic_sql=false, multi_statement=false, statement is a literal SELECT) and structurally by the gateway (live-proven: INSERT/CREATE/multi-statement all [DENIED]).
• No side-effect SELECT functions unless an function_allowlist entry exists and that function is itself proven side-effect-free under a separate authority contract — none today, so the allowlist is empty and no function is called. (This is the D9 / matrix #32 boundary; rationale live-proven: a SELECT can call a function, §1 of the export-step contract.)
• Side-effect-free = true required for export eligibility.

5. Initial provisional catalog (6 entries, all reference-validated 2026-06-10)

All six are side_effect_free=true, function_allowlist=[], dynamic_sql=false, multi_statement=false, read-only role required, single literal SELECT, approved_source on the allowlist. Result counts: 309 / 219 / 102 / 309 / 41 / 224019. NQ-DOT-REGISTRY-NO-FILE-COUNT-V1 is authority_status=diagnostic (reads v_dot_registry_no_file; must carry precedence=diagnostic, Domain D). Full SQL text is embedded in b7_validate.py / the validation report.

6. What is NOT in the catalog (deliberate)

• Any query that joins tac_logical_unit and information_unit (Domain H — dual-report only).
• Any detector/engine call (Domain G), any command run (Domain B/C — no call set), any write/sink (fn_tac_log_checker_issue).
• Any "collapsed canonical DOT number" query (denominator discipline).

7. Versioning & change control

ID embeds -V<n>. A semantic/SQL change ⇒ new version ID; the prior version is marked deprecated_at and retained for reproducibility of old packets. A packet pins the exact version ID per item, so re-validation is deterministic.

8. Deprecation

deprecated_at set; export step refuses to emit new items from a deprecated ID but can still verify an old packet that cites it. Removal requires owner approval.

9. Authority status & promotion requirements

Current: PROVISIONAL_NON_AUTHORITY. To promote to a binding governed catalog (B7-EXP-1):

1. Owner/Codex review and seal of the catalog model + the initial entry set as authoritative.
2. A governed home for the catalog (either a new sealed named_query_catalog table or an extension of the dot_iu_command_catalog pattern) — an owner decision, since it creates a new authority surface.
3. A content-hash/version seal so the catalog cannot be mutated post-approval without detection (embodies feedback_self_audit_before_external_review_mutable_authority). Until promoted, the catalog is a design artifact; operator-run exports cite it as reference, and emitted packets are evidence-only.

10. Evidence required to approve a new entry

• The exact SELECT, run read-only through the gateway, returning a result (proves it executes and is SELECT-only).
• expected_output_schema matches the live result columns/types.
• A statement that the SQL calls no function (or only function_allowlist functions), with the gateway rejection probes (§6 of export-step contract) as the enforcement backstop.
• approved_source is on the export-step allowlist and is read-only (table/view, not a function).