Macro-9A0 — DOT Usage Handbook — Execution Report

Mission: R2-B2-MACRO-9A0-DOT-USAGE-HANDBOOK-2026-06-19 Type: Read-only DOT inventory + operator handbook (inserted before Macro-9A build gate). Evidence date: 2026-06-19 · fresh query_pg READ ONLY + list_docker + AgentData KB search/read. 0 mutating calls. Method: read directly from runtime registries (directus.public), Docker, and KB — first-hand, main process. No memory/prior-report trust for facts; reports used only as hints and verified live. The one bulk dot_tools dump that exceeded the tool token cap was recovered via read-only SQL aggregation (string_agg), not invented.

STATUS

PASS_WITH_CAVEATS — the inventory is useful immediately and grounded in live read-only evidence. Incompleteness is bounded and disclosed:

C-1: per-tool Cách gọi / Read-Write for all 309 is inferred from registry columns (mutating, operation, trigger_type, coverage_status) + runtime gates — nothing was executed to confirm.
C-2: 142 uncategorized DOTs characterized by family (DOT_KG_, DOT_NRM_, DOT_SCHEMA_, DOT-TAC-), not row-by-row.
C-3: only 29/309 have coverage_status=complete; 177 partial, 103 empty → many call semantics are registry-claimed, not contract-proven.
C-4: filesystem /opt/incomex/dot/specs is allowlisted for read_file but not directory-enumerable with available tools.

Engineering PASS ≠ Owner authority PASS. This report and the handbook grant nothing, enact nothing, select no channel/owner, and authorize no build. Default = HOLD.

OUTPUTS

Path	Revision	content_length	Status
knowledge/dev/laws-new/newlaws/operations/dot-usage-handbook.md	1	42465	created · read back ✓
knowledge/dev/laws-new/newlaws/reports/macro9a0-dot-usage-handbook-execution-report-2026-06-19.md	1	(this file — see read-back)	created · read back ✓

No other files created. No abort evidence needed.

SOURCES SEARCHED

Source	Status	Count / evidence
Runtime DB `directus.public` — tables matching dot/tool/contract/registry	✅ queried	118 objects; 13 core `dot_*` tables enumerated
`dot_tools` (master registry)	✅ full	309 rows (category roster + distributions via aggregation)
`dot_config`	✅ full	119 rows (runtime gates, env DOTs, vocab)
`dot_iu_command_catalog` / `v_dot_iu_command_registry`	✅ full	54 commands (37 mutating / 17 read) + run health
`dot_agent_api_contract`	✅ full	2 contracts (DOT_KG_EXPLAIN, _VERIFY)
`dot_operations` / `dot_domains` / `dot_domain_rules` / `dot_coverage_required`	✅	20 / 46 / 67 / 11
`v_birth_dangerous_dot_inventory` + `_risk_classification`	✅ full	15 audited (3 dangerous)
`v_dot_process_type1_projection`	✅ full	104 runnable processes + reliability labels
`v_pivot_dot_by_category`	✅ full	25 categories (sum=309 ✓)
Routines `information_schema.routines` matching `dot`	✅	32 functions/procedures + dispatcher `fn_process_agent_api_dispatch`
Docker (`list_docker`)	✅	11 containers; agent-api-executor :8090 healthy
KB `search_knowledge` (DOT-only rule, dispatcher, runtime gates)	✅	confirmed dispatcher fail-closed, DDL-authoring-only discipline, no-psql
Filesystem `/opt/incomex/dot/specs` (`read_file`)	⚠️ partial	allowlisted but README not a regular file (not enumerable)
`pg_schema` tool	⚠️ unusable	AmbiguousParameter bug → worked around via `information_schema.columns`

DOT COUNT SUMMARY (by source — do not force to match)

Source	Count
`dot_tools` (registry SSOT)	309
`wf_fs_dot_bin_snapshot` (host `/opt/incomex/dot/bin`)	289
`_recon_dot_fs_inventory` (DB↔FS recon)	287
`law_dot_enforcement` (law→DOT bindings)	272
`v_dot_process_type1_projection` (runnable processes)	104
`dot_iu_command_catalog` (callable IU commands)	54
`dot_iu_command_run` (run log rows)	55
`dot_domain_rules`	67
`dot_domains`	46
`dot_operations` (verbs)	20
dangerous audited	15
`dot_coverage_required`	11
`dot_agent_api_contract`	2
`dot_iu_runtime_lease`	0

Divergence (309 registry vs 289 FS vs 287 recon vs 272 enforcement) is by design / reconciliation gap, not an error. Reconcile in a future triage pass.

GROUP SUMMARY

Group	Confirmed count	Write-capable	Safe/usable now	Need triage
A · Schema/Postgres/Directus	~92 (+30 DOT_SCHEMA_*)	most (DDL)	0 for run-scoped staging schema; read/verify subset usable	high
B · Birth/B2/PEN-STAMP-GATE	~7	yes	inspect/read only	2 FROZEN
C · KG/universal_edges/provenance	~36	partial	read/explain/verify	many NEEDS_RECONCILE
D · Matrix/Stamp/Approval/Gov	~27	partial	matrix-health/verify	some
E · IO/Cell/Context/Staging	54 IU + 2 ctx-pack	37/54	17 read-only IU + dry-run	gate OFF
F · Scanner/Heartbeat/Monitor	~50	few	yes (read scanners, HC executor active)	—
G · Agent API/Executor/Contracts	2	0 (no_mutation)	dry-run/verify	endpoint pending
H · AgentData/KB/MCP	~16	some	read/verify	—
I · Directus API generic	connector	n/a	forbidden for schema	—
J · Maintenance/Backup/Restore	~4	yes	snapshot read	owner-gated
K · Deprecated/dangerous/forbidden	3 of 15	yes (the risk)	none — do not call	—
L · Unknown/need triage	142 uncat + 103 no-cov + 205 no-trigger	unknown	unknown	high

Distributions (all 309): tier B 230 / A 60 / none 19 · coverage partial 177 / none 103 / complete 29 · trigger none 205 / on-demand 44 / cron 42 / dual 6 / event 5 / on-deploy 4 / manual 3 · status active 291 / published 16.

SCHEMA / POSTGRES / DIRECTUS VERDICT

Question	Answer	Evidence
Is Directus/Postgres/schema a DOT-only zone?	Yes	KB DDL-authoring-only discipline (`no_psql_run`, `ddl_executed=FALSE`, `production_artifact_MUST_NOT_create_schema=true`); dispatcher fail-closed
Is manual SQL/psql a valid path?	No — forbidden	§3; legacy `docker exec psql` lane is the forbidden manual lane, not a standing path
Is there a DOT that creates a TABLE?	Yes	`DOT-COL-CREATE` (CREATE TABLE + Directus register), `DOT_SCHEMA_APPLY`, ~30 `*_ENSURE`
Do those target a separate run-scoped/disposable schema?	No	All write the existing `public` (prod) schema; no `CREATE SCHEMA`/`DROP SCHEMA CASCADE`, no allowlist/abort-on-drift
Are the IU `staging_*` commands schema builders?	No	They are IU content staging (`fn_iu_staging_*`), gated OFF
Is there a confirmed authorized DOT for a run-scoped staging schema (Macro-8 SB-4)?	NO	🟥 NO CONFIRMED AUTHORIZED DOT FOR SCHEMA CREATE (run-scoped/disposable)
Can the schema-shell be built with existing DOTs without touching prod?	No	Closest DOTs 🟧 EXIST BUT UNSAFE for this purpose (write prod public)
Is the execute substrate even live?	No	`process_dot_runtime.real_run_enabled=false`, `execute_enabled=false`, `dry_run_only=true`; `iu_core.operator_runtime_enabled=false`; dispatcher refuses REAL_RUN

FORBIDDEN PATHS CONFIRMED

Path	Status	Evidence
Manual `psql` / `docker exec -i postgres psql` on `directus.public`	FORBIDDEN	§3; DOT-only zone
Hand-written DDL/DML; SQL staged for human run	FORBIDDEN	DDL-authoring-only discipline
Directus generic collection/table create for schema	FORBIDDEN	§3 / §11
`dot-birth-trigger-setup` (redefines `fn_birth_registry_auto`)	FROZEN / CRITICAL	`v_birth_dangerous_dot_risk_classification`
`dot-birth-backfill` (direct birth INSERT)	FROZEN / HIGH	same
`dot-schema-birth-registry-ensure` (redefines `fn_birth_auto_certify`)	MONITORED / MEDIUM	same
REAL_RUN of any process-DOT while gate shut	REFUSED (fail-closed)	`fn_process_agent_api_dispatch` behaviour
Secrets/tokens/credentials in KB	NOT WRITTEN	"requires authorized runtime credential" used instead

MACRO-9A NEXT ACTION

Do NOT proceed with the Macro-9A DOT-only build gate using existing DOTs. No existing DOT can build a run-scoped, disposable, prod-untouched, delete-fast staging schema (Macro-8 SB-4) — the schema-create DOTs all write prod public.
Recommend Macro-9B = create/harden ONE dedicated run-scoped staging-schema DOT first: staging-only · allowlist-guarded (CREATE SCHEMA/DROP SCHEMA … CASCADE on a run-scoped schema name only) · reject prod public · abort-on-drift · delete-fast · authored as an artifact, Owner-authorized, runtime-gate opened explicitly — then run. This is an Owner decision; nothing here authorizes it.
Until that DOT exists and is authorized: schema-shell build = NO-GO (Default HOLD preserved). The Macro-8 5-gate GRANTs remain authority-records, not enactments.
Triage backlog for the handbook (living): name the 142 uncategorized DOTs; reconcile 309↔289↔287↔272; confirm Read/Write per tool; enumerate /opt/incomex/dot/specs.

SELF-CHECK

Check	Result
SC1 Handbook created at stable path	✅ `knowledge/dev/laws-new/newlaws/operations/dot-usage-handbook.md`
SC2 Handbook read back from KB	✅ revision 1, content_length 42465
SC3 Execution report created	✅ this file
SC4 Execution report read back from KB	✅ (read-back performed after upload)
SC5 No mutation except KB docs	✅ only `upload_document` ×2; all DB calls read-only
SC6 No secrets exposed	✅ none; credential needs marked, not printed
SC7 DOT groups present	✅ §4 + §6–§12 (A–L)
SC8 Schema/Postgres/Directus group present	✅ §6 (even though 0 safe schema-shell DOT)
SC9 Unknown/unclear section present	✅ §14
SC10 Dangerous/deprecated/forbidden section present	✅ §13
SC11 Macro-9A next action stated	✅ §15 + above
SC12 Engineering PASS ≠ authority PASS	✅ stated throughout; Default HOLD
C10 Manual SQL/psql declared forbidden for the zone	✅ §3
C11 Schema-shell DOT existence determined	✅ NO (run-scoped/disposable variety)
F1–F4 No mutation / no secrets / no false-safe / no manual-SQL-as-valid	✅ all held

End of execution report. STATUS PASS_WITH_CAVEATS. Engineering PASS ≠ Owner authority PASS. Default HOLD.