Incomex AI Portal
KB-1EEE rev 2

DOT_R2_B2_STAGING_SCHEMA_SHELL — DOT Path Contract (Macro-9B / 9B2 rev2)

13 min read Revision 2
dot-managemacro9bmacro9b2dot-contractr2-b2staging-schemaspecremediation2026-06-20

DOT_R2_B2_STAGING_SCHEMA_SHELL — DOT Path Contract

Artifact type: DOT path specification (engineering contract). Macro-9B deliverable C3, Macro-9B2 remediation. Status: AUTHORED — NOT REGISTERED, NOT WIRED, NOT RUN. REGISTRATION_HOLD + HOLD_FOR_OWNER_REAL_RUN. Date: 2026-06-19. Macro-9B2 remediation (2026-06-20): this contract + the validator (rev2) were updated to close the 7 Codex HOLD findings (required channel+actor, strict full-string/control-char validation, strict-boolean gate, Guard 3 enforced before any real-run write, Guard 4 separability). Engineering evidence is now dot-r2-b2-validator-test-run-v2.txt (64/64 PASS, 0 fail-open), which supersedes the rev1 37/37 run. Companion: dot-schema-write-guards.contract.md (the 4 guards), dot-r2-b2-staging-schema-shell.validator.py (reference fail-closed logic, rev2, proven locally), dot-r2-b2-bad-input-matrix.md (v2, 64 cases). Authorizes nothing. Engineering PASS ≠ Owner authority PASS. Default = HOLD.

Direct answer to DOT handbook §15 NO-GO / §18 row 1 and Collections §16/§19 (Macro-8 SB-4): there is no authorized DOT that builds one run-scoped, disposable, delete-fast R2-B2 staging schema. This contract specifies that missing DOT path so it can later be registered and (separately, Owner-gated) run.

0. Identity & boundary

Field Value
dot_code DOT_R2_B2_STAGING_SCHEMA_SHELL
Purpose Create/verify/drop exactly one run-scoped disposable staging schema r2_b2_wb_<run_id> inside the directus DB, zero production data, prod-untouched, delete-fast (DROP SCHEMA … CASCADE), abort-on-drift.
Design Option B — one primary DOT + 4 separately-inspectable guard components (see guards contract). Composed only through an explicit dict contract: input → verdict → {reject_codes, plan/writes, audit}. No shared mutable state, no registry, no graph, no orchestration engine. Guard 1 and Guard 4 share a pure _validate_target helper; neither guard calls the other.
Separability Each guard is independently generated, testable, replaceable, and rollbackable. Replacing one guard does not require editing the others or the router.
Channel A governed channel only (process_dot_runner or agent_api_executor, DOT §2.4). Manual SQL / psql / docker exec psql / Directus generic create are forbidden lanes (DOT §3/§13), rejected by guard 1.
Write capability today NONE. Execute substrate is dry-run-gated (process_dot_runtime.real_run_enabled=false, dispatcher refuses REAL_RUN, iu_core.operator_runtime_enabled=false). This contract does not change that.

1. Inputs (every invocation must carry — DOT §18 principle 5)

Field Required Rule Reject if violated
dot_code yes must equal DOT_R2_B2_STAGING_SCHEMA_SHELL WRONG_DOT_CODE
mode yes one of the 6 modes (§2) UNKNOWN_MODE
run_id yes non-empty; strict full-string [0-9]{8}T[0-9]{6}Z via re.fullmatch; no whitespace/control chars MISSING_RUN_ID / BAD_RUN_ID
owner_authorization_ref yes (all modes) non-empty; a real Owner real-run grant required for the two real-run modes MISSING_OWNER_AUTH
target_schema yes strict full-string allowlist r2_b2_wb_[a-z0-9]+(_[a-z0-9]+)* via re.fullmatch and embeds run_id; no whitespace/control chars; never a protected schema MISSING_TARGET_SCHEMA / MALFORMED_SCHEMA_CHARS / NON_ALLOWLIST_SCHEMA / SCHEMA_RUNID_MISMATCH / PROTECTED_SCHEMA_TARGET
channel yes non-empty, governed channel only MISSING_CHANNEL / FORBIDDEN_MANUAL_CHANNEL / UNKNOWN_CHANNEL
actor yes non-empty identity for audit MISSING_ACTOR
copy_production_data must be false/absent any truthy ⇒ reject PROD_DATA_COPY_FORBIDDEN
use_directus_generic_create must be false/absent any truthy ⇒ reject DIRECTUS_GENERIC_FORBIDDEN
production_untouched_evidence required for verify and the two real-run modes {before:{...}, after:{...}} over the protected surfaces; consumed by Guard 3 PROD_UNTOUCHED_UNKNOWN (missing/incomplete) / PROD_UNTOUCHED_FAIL (drift)

Authority gate (NOT a request field): owner_real_run_gate_open is a separate explicit argument supplied by the authority boundary, never read from the (untrusted) request dict. It must be exactly boolean True to permit a real-run write-intent; any non-boolean value ("true", "false", 1, None, …) rejects with INVALID_GATE_TYPE (no truthiness).

Allowlist (guard 1): r2_b2_wb_[a-z0-9]+(_[a-z0-9]+)* matched with re.fullmatch (full-string; re.match(...$) is not used because Python $ accepts a trailing newline), lower-case only, run-scoped, must embed run_id; any whitespace/control character is rejected first as MALFORMED_SCHEMA_CHARS. Hard-reject targets: public, iu_core, cutter_governance, sandbox_tac, information_schema, pg_catalog, pg_toast, pg_temp, and any non-allowlist / shared / production schema.

2. Modes — contract (Mode | Input | Output | Rejects | Writes?)

Mode Input Output Rejects (any ⇒ fail-closed) Writes?
validate_only full input {inputs_valid} verdict + audit all input/guard rejects No
dry_run_plan full input DDL plan: CREATE SCHEMA + 7 CREATE TABLE (preview strings) + audit all input/guard rejects No (plan only)
verify full input + Guard 3 evidence Guard 3 verdict PASS/FAIL/UNKNOWN over before/after evidence + audit all input/guard rejects No (read-only)
teardown_plan full input DROP SCHEMA … CASCADE plan (allowlist re-checked via shared helper) + audit all input/guard rejects (delete-fast guard) No
real_run full input + gate exactly boolean True + Guard 3 evidence on gate True and Guard 3 verdict=PASS: write-intent for schema + 7 tables, audit (before/after) all input/guard rejects + INVALID_GATE_TYPE (non-bool gate) + REAL_RUN_GATE_CLOSED (gate False) + PROD_UNTOUCHED_FAIL/PROD_UNTOUCHED_UNKNOWN (Guard 3 not PASS) Gated — HOLD_FOR_OWNER_REAL_RUN
teardown_real_run full input + gate exactly boolean True + Guard 3 evidence on gate True and Guard 3 verdict=PASS: DROP SCHEMA … CASCADE write-intent, audit all input/guard rejects + INVALID_GATE_TYPE / REAL_RUN_GATE_CLOSED / PROD_UNTOUCHED_FAIL/PROD_UNTOUCHED_UNKNOWN Gated — HOLD_FOR_OWNER_REAL_RUN

In this macro the Owner real-run gate is CLOSED: real_run and teardown_real_run reject with REAL_RUN_GATE_CLOSED (and any non-boolean gate value rejects with INVALID_GATE_TYPE — truthiness is NOT used). Even with the gate forced to boolean True in a local simulation, write-intent is emitted only when Guard 3 (DOT_PRODUCTION_UNTOUCHED_VERIFY) returns PASS over explicit before/after evidence; otherwise it rejects with PROD_UNTOUCHED_FAIL/PROD_UNTOUCHED_UNKNOWN. The four no-write modes return plans/verdicts only and were proven to issue zero writes (validator rev2, 64/64 PASS, 0 fail-open — dot-r2-b2-validator-test-run-v2.txt, superseding the rev1 37/37). The simulated real-run rows emit write-INTENT strings, never a DB call; execution remains a separate Owner-gated runtime step.

3. The seven empty shell tables (DOT §18 row 1)

Created only inside r2_b2_wb_<run_id> on a future authorized real_run. Empty / synthetic only — zero production data, no production copy.

  1. wb_manifest — run_id, owner_authorization_ref, created_at
  2. wb_object — scratch candidate objects (empty)
  3. wb_object_state — scratch state (empty)
  4. wb_edge — scratch edges (NOT the production KG; empty)
  5. wb_audit — local audit-proof rows for this run
  6. wb_drift_check — before/after production-untouched snapshots
  7. wb_teardown_log — delete-fast teardown record

4. Guard composition order (fail-closed; all reject codes collected, no short-circuit)

  1. identity → WRONG_DOT_CODE
  2. mode → UNKNOWN_MODE
  3. channel (required, governed) → MISSING_CHANNEL / DIRECTUS_GENERIC_FORBIDDEN / FORBIDDEN_MANUAL_CHANNEL / UNKNOWN_CHANNEL
  4. actor (required) → MISSING_ACTOR
  5. run_id (strict full-string, no control chars) → MISSING_RUN_ID / BAD_RUN_ID
  6. prod-data-copy → PROD_DATA_COPY_FORBIDDEN
  7. owner-auth → MISSING_OWNER_AUTH
  8. DOT_SCHEMA_WRITE_ALLOWLIST_GUARD (create) / DOT_STAGING_SCHEMA_DELETE_FAST allowlist (teardown) — both route through the shared pure _validate_target helper (Guard 4 does not call Guard 1) → MISSING_TARGET_SCHEMA / MALFORMED_SCHEMA_CHARS / PROTECTED_SCHEMA_TARGET / NON_ALLOWLIST_SCHEMA / SCHEMA_RUNID_MISMATCH
  9. real-run gate (real-run modes only) → INVALID_GATE_TYPE (gate not exactly boolean True) / REAL_RUN_GATE_CLOSED (gate boolean False)
  10. DOT_PRODUCTION_UNTOUCHED_VERIFY (guard 3, real-run modes only, after gate True) → PROD_UNTOUCHED_FAIL (drift) / PROD_UNTOUCHED_UNKNOWN (missing/incomplete evidence); a real-run write-intent is emitted only on Guard 3 verdict=PASS
  11. Accept iff zero reject codes. DOT_SCHEMA_WRITE_AUDIT_PROOF (guard 2) emits an audit envelope for every decision (accept or reject), now including production_untouched_verdict.

5. Reject-code dictionary

WRONG_DOT_CODE · UNKNOWN_MODE · MISSING_CHANNEL · FORBIDDEN_MANUAL_CHANNEL · UNKNOWN_CHANNEL · DIRECTUS_GENERIC_FORBIDDEN · MISSING_ACTOR · MISSING_RUN_ID · BAD_RUN_ID · PROD_DATA_COPY_FORBIDDEN · MISSING_OWNER_AUTH · MISSING_TARGET_SCHEMA · MALFORMED_SCHEMA_CHARS · PROTECTED_SCHEMA_TARGET · NON_ALLOWLIST_SCHEMA · SCHEMA_RUNID_MISMATCH · INVALID_GATE_TYPE · REAL_RUN_GATE_CLOSED · PROD_UNTOUCHED_FAIL · PROD_UNTOUCHED_UNKNOWN.

Every reject ⇒ accepted=false, writes=[], plan=null, plus an audit envelope. Fail-closed by construction (default deny; accept only on empty reject set).

6. Audit evidence shape (DOT_SCHEMA_WRITE_AUDIT_PROOF, guard 2)

{ dot_code, actor, run_id, mode, target_schema, owner_authorization_ref, channel, decided_at, reject_codes[], write_intent[], production_untouched_verdict, before_snapshot_ref, after_snapshot_ref } — produced for every decision. No write-enabled mode may run without leaving this proof (production_untouched_verdict is the Guard 3 verdict; before/after_snapshot_ref populated only for write modes).

7. Stop states (do not pass)

  • REGISTRATION_HOLD — registering this DOT in dot_tools / wiring an agent-api contract / opening a runtime gate is a DB write. This macro performs none. Registration requires an authorized DOT-registration path or Owner-approved runtime gate. dot_tools is NOT written by hand.
  • HOLD_FOR_OWNER_REAL_RUN — the first real_run or teardown_real_run would issue CREATE SCHEMA / DROP SCHEMA … CASCADE. Blocked until: explicit Owner real-run authorization + a freshly-opened runtime execute gate + a fresh read-only preflight + SB-4 no-prod-touch & delete-fast proof. The strict-boolean gate + Guard 3 PASS requirement are validator-level preconditions, not a substitute for Owner authority.

8. Manual-block hardening hooks (recorded; see guards contract §Hardening)

This DOT is the only sanctioned write path for r2_b2_wb_*. It is enforceable only if the 10 DOT §18 hardening principles hold (read-only default roles; write isolated to a dedicated DOT-executor role; no generic role/Directus path may create schema; allowlist; prod-reject; audit-log; abort-on-drift; DOT-only teardown). This macro implements none of them (no role/grant/gate change). They are preconditions for any future registration/real-run.

End of contract. Authored as an artifact, Owner-authorized later, runtime gate opened explicitly; only then run. Default HOLD.