KB-5353
Macro-9A0 DOT Usage Handbook — Execution Report (2026-06-19)
11 min read Revision 1
macro-9a0dotexecution-reportdot-manageread-only2026-06-19
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-Writefor 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/specsis allowlisted forread_filebut 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 … CASCADEon a run-scoped schema name only) · reject prodpublic· 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.