dot-iu-cutter v0.4 — LedgerWriter Schema-Binding Code-Review Evidence

Date: 2026-05-17 · Evidence package for the PROVISIONAL_PASS code cycle (commit 84c52c5). Read-only verification only — no code change, no commit, no dry-run, no production connection, no secret read, no deploy, no CUT/VERIFY. All command outputs below were captured live read-only from the VPS code SSOT /opt/incomex/dot.

1. Git evidence

branch              : main
head commit         : 84c52c57aa296de921998910d85b0d4a85ad0746
parent commit       : 56d3732cb74d07546c938242180a434ed1067a9a   (accepted FINAL CODE PASS)

git show --stat --oneline -1 HEAD:
  84c52c5 feat(iu-cutter): v0.4 LedgerWriter schema-binding code (rebind 9 writers + schema_binding.py + phases lineage/idempotency/sweep + contract tests)
   iu-cutter/cutter_agent/ledger.py                | 153 ++++++++++----
   iu-cutter/cutter_agent/phases.py                | 122 +++++++++----
   iu-cutter/cutter_agent/schema_binding.py        | 156 +++++++++++++++++
   iu-cutter/tests/_schema_contract_fixture.py     | 145 ++++++++++++++++
   iu-cutter/tests/test_phase_contracts.py         |  10 +-
   iu-cutter/tests/test_schema_binding_contract.py | 219 ++++++++++++++++++++++++
   6 files changed, 730 insertions(+), 75 deletions(-)

git diff-tree --no-commit-id --name-status -r HEAD:
  M  iu-cutter/cutter_agent/ledger.py
  M  iu-cutter/cutter_agent/phases.py
  A  iu-cutter/cutter_agent/schema_binding.py
  A  iu-cutter/tests/_schema_contract_fixture.py
  M  iu-cutter/tests/test_phase_contracts.py
  A  iu-cutter/tests/test_schema_binding_contract.py

git status --short -- iu-cutter : (empty — clean)

Exactly 6 in-scope files (3 cutter_agent/* allowed + tests/*). No db_adapter.py/state_machine.py/idempotency.py/signing.py/signal.py/cli.py change. No unrelated WIP.

2. Blob integrity (working tree == committed blob)

git diff HEAD -- iu-cutter → empty (working tree byte-identical to commit 84c52c5). Per-file sha256(working file) vs sha256(git show HEAD:<path>):

MATCH | 2b748c4adbf30c64a2b6a66d543083a82bcaef8128deaf4cd5f5d54d9ea5ea53 | iu-cutter/cutter_agent/schema_binding.py
MATCH | 0bf4d61fbb4fc198907f9446074596fde4a22a62292e77a2da139c147a993974 | iu-cutter/cutter_agent/ledger.py
MATCH | e9337b7c5e38ca97d09ad3047558697d04b654c29ce57968b6661ae3ed89dffb | iu-cutter/cutter_agent/phases.py
MATCH | f7ef37defb41eef4df36e4fbe745d0742096e58b3dc603eec9cfcf8170adabdc | iu-cutter/tests/_schema_contract_fixture.py
MATCH | 2df28b486cd55cb892b9281c86b9ddd1e072b08d6475468f11dd673cd72c6849 | iu-cutter/tests/test_schema_binding_contract.py
MATCH | 4b4a37acf755a19fe2f637626681842cf99c962344718ea36d7c1d9d88998a7c | iu-cutter/tests/test_phase_contracts.py

All 6 = MATCH ⇒ reviewed source == committed source == deployed source.

3. Source evidence snippets (verbatim from commit 84c52c5)

3.1 schema_binding constants + vocabulary registry (centralised, no scattered literals)

REVIEW_GOVERNANCE_EVENT_KIND = "review_decision"
REVIEW_SCOPE_MANIFEST = "manifest"
REVIEW_STATUS_DECIDED = "decided"
REVIEWER_CLASS = "automated_agent"
RISK_CLASS_STANDARD = "standard"
SWEEP_TRIGGER_KIND = "agent_logged_pass"
VERIFIER_TOOL_REVISION_PENDING = "pending"   # SB-DEC-3 (verifier not yet run)
AFFECTED_TARGET_TABLE_SENTINEL = "cutter_governance/none"  # SB-DEC-4
AFFECTED_OPERATION_KIND = "apply"
VERIFY_STATE_COMPLETE = "complete"
_SIGNATURE_KIND_BY_LANE = {DOT_EXECUTOR_LANE: "executor",
                           DOT_VERIFIER_LANE: "verifier"}
# SCHEMA_BINDING_VOCABULARY maps "<table>.<field>" -> frozenset(allowed):
  "review_decision.verdict": frozenset(_REVIEW_VERDICTS),
  "decision_backlog_sweep_log.trigger_kind": frozenset({SWEEP_TRIGGER_KIND}),
  "cut_change_set.verifier_tool_revision_sentinel":
      frozenset({VERIFIER_TOOL_REVISION_PENDING}),
  "cut_change_set_affected_row.target_table":
      frozenset({AFFECTED_TARGET_TABLE_SENTINEL}),
  "verify_result.verdict": frozenset(_VERIFY_VERDICTS),
  "verify_result.state": frozenset({VERIFY_STATE_COMPLETE}),
  "dot_pair_signature.signature_kind": frozenset(_SIGNATURE_KIND_BY_LANE.values())
def signature_kind_for_lane(lane): ... raise ValueError on unknown lane

3.2 deterministic entry_id uuid5 builder (scale-safe idempotency identity)

# Fixed protocol namespace (NOT a secret, NOT an external id). uuid5 over
# the idempotency key makes a MARK replay resolve to the SAME entry_id, so
# dedup is a primary-key lookup (server-side + indexed at any scale) with
# zero schema change.
ENTRY_ID_NAMESPACE = uuid.uuid5(uuid.NAMESPACE_DNS,
                                "dot-iu-cutter.v0.4.schema-binding")
def deterministic_entry_id(idempotency_key: str) -> str:
    return str(uuid.uuid5(ENTRY_ID_NAMESPACE, idempotency_key))
def rollback_key(entry_id, change_set_id): return f"rbk:{entry_id}:{change_set_id}"

3.3 server-side MARK lookup call shape (primary key, not full scan)

def mark(self, signal):
    payload = embed_idempotency_key({}, signal.signal_source_id,
                                    signal.iu_ref, signal.proposed_cut_spec)
    key = payload_idempotency_key(payload)
    entry_id = sb.deterministic_entry_id(key)
    # idempotent MARK: replay -> same deterministic entry_id -> a
    # server-side primary-key lookup (indexed at any scale; no full-table
    # scan, no schema change).
    existing = self.exec_adapter.find("decision_backlog_entry",
                                      entry_id=entry_id)
    if existing:
        return existing[0]
    ... append_entry(..., entry_id=entry_id) ; append_history(...)

adapter.find("decision_backlog_entry", entry_id=…) → SELECT * FROM cutter_governance.decision_backlog_entry WHERE entry_id = %s — equality on the primary key (always uniquely indexed). No fetch-all + Python filter.

3.4 sweep batch config + clamp (no fixed batch size)

SWEEP_BATCH_ENV_KEY = "DOT_CUTTER_SWEEP_BATCH"
_SWEEP_BATCH_DEFAULT = 100 ; _SWEEP_BATCH_LO = 1 ; _SWEEP_BATCH_HI = 10000
def _clamped_int(env, key, default, lo, hi): ...   # fail-safe parse + clamp
def sweep_batch_size(env=None):
    e = env if env is not None else os.environ
    return _clamped_int(e, SWEEP_BATCH_ENV_KEY, _SWEEP_BATCH_DEFAULT,
                        _SWEEP_BATCH_LO, _SWEEP_BATCH_HI)

3.5 keyset sweep cursor logic

def sweep(self, *, env=None):
    led = LedgerWriter(self.exec_adapter)
    batch = sb.sweep_batch_size(env if env is not None else os.environ)
    candidates = []
    for st in (sm.S_MARKED, sm.S_REVIEWED_DEFERRED):
        candidates.extend(self.exec_adapter.find(
            "decision_backlog_entry", status=st))     # server-side WHERE status=%s
    candidates.sort(key=lambda r: (r.get("emitted_at") or "",
                                   r.get("entry_id") or ""))  # stable keyset
    promotable = candidates[:batch]                   # bounded by config

3.6 representative rebound row-builder — append_history (the S4 fatal write, now bound)

row = {
  "history_id": _id(), "entry_id": entry_id,
  "entry_version_before": from_state,          # nullable (BIRTH=None)
  "entry_version_after": to_state,
  "change_kind": reason,
  "change_diff": {"from": from_state, "to": to_state},
  "changed_by": actor, "changed_at": at, "rationale": reason }
return self.adapter.insert("decision_backlog_history", row)

3.7 representative rebound row-builder — write_cut_change_set

row = {
  "change_set_id": change_set_id,
  "rollback_key": sb.rollback_key(entry_id, change_set_id),
  "manifest_id": manifest_id, "manifest_version": manifest_version,
  "review_decision_id": review_decision_id,
  "executor_tool_revision": sb.TOOL_REV,
  "verifier_tool_revision": sb.VERIFIER_TOOL_REVISION_PENDING,
  "executor_signature_id": executor_signature_id,
  "verifier_signature_id": None,                       # OD-6
  "decision_backlog_entry_id": entry_id,
  "idempotency_key": sb.cut_idempotency_key(entry_id, content_hash),
  "payload_summary": {"content_hash": content_hash},
  "emitted_by": sb.ACTOR_EXEC }
return self.adapter.insert("cut_change_set", row)

3.8 representative rebound row-builder — write_verify_result

row = {
  "verify_result_id": _id(), "change_set_id": change_set_id,
  "manifest_id": manifest_id, "manifest_version": manifest_version,
  "review_decision_id": review_decision_id,
  "executor_tool_revision": sb.TOOL_REV,
  "verifier_tool_revision": sb.TOOL_REV,
  "verdict": sb.verify_verdict(outcome),               # "pass"/"fail"
  "state": sb.VERIFY_STATE_COMPLETE,
  "rollback_triggered": (outcome == "fail"),
  "executor_signature_id": executor_signature_id,
  "verifier_signature_id": verifier_signature_id,      # OD-6
  "escalation_ref": escalation_ref,
  "rollback_change_set_id_triggered": rollback_change_set_id,
  "prior_verify_result_id": prior_verify_result_id }
return self.adapter.insert("verify_result", row)

3.9 no forbidden runtime SQL surface

All writers call only self.adapter.insert(...) / cas_status / stamp_superseded (the pre-existing sanctioned ops in the untouched db_adapter.py). The 3 scope source files contain no DELETE/TRUNCATE/DROP/ALTER/GRANT/CREATE TABLE/COPY (grep §5). The append-only/refusal surface lives only in the untouched db_adapter.py.

4. Tests

• Exact command: python3 -m unittest discover -s tests (VPS /opt/incomex/dot/iu-cutter, py3.12).
• Output summary: Ran 101 tests in 0.032s → OK → 101/101 PASS (92 prior accepted + 9 new). No failures, no errors, no skips reported.
• New test files: tests/_schema_contract_fixture.py (static 12-table deployed contract; committed test data), tests/test_schema_binding_contract.py (python3 -m unittest tests.test_schema_binding_contract → Ran 9 tests … OK).
• Schema-contract tests summary: capture every LedgerWriter INSERT across canonical + force_fail + re-review flows; assert (set-equality, not DDL string compare) emitted columns ⊆ deployed columns AND deployed NOT-NULL-no-default ⊆ emitted; assert all 10 canonical tables exercised; vocabulary values ∈ registry.
• No-hardcode tests summary: test_no_hardcoded_connection_literal_in_schema_binding scans schema_binding.py for postgres://,PGPASSWORD,password=,5432,38.242.240.89 (none); test_sweep_batch_is_config_driven_and_clamped proves default/override/clamp/fail-safe; test_deterministic_keys proves stable uuid5 + key builders; plus the retained test_security_boundaries.test_source_has_no_hardcoded_dsn_or_secret scans all non-test source.

5. Static boundary grep (scope files: schema_binding.py, ledger.py, phases.py)

grep -nE 'postgres://|PGPASSWORD|password=|38.242.240.89|incomex-[a-z]+|qdrant|collection_name|<ipv4>' → NONE_FOUND
grep -nE '\b(DELETE|TRUNCATE|DROP|ALTER|GRANT|CREATE TABLE|COPY)\b'                                   → NONE_FOUND

• No fixed IP / container id (38.242.240.89, incomex-* absent).
• No DSN / password literal (postgres://, PGPASSWORD, password= absent).
• No vector collection literal (qdrant, collection_name absent — no vector integration this cycle).
• No DELETE/TRUNCATE/DDL/GRANT/COPY runtime surface in scope files; the only such surface (refusal guards) remains in the untouched db_adapter.py.
• Scoped git add confirmed: git diff-tree shows exactly the 6 intended paths; git status --short -- iu-cutter clean; completion report states explicit-path add, no git add -A, no unrelated WIP — consistent with the git evidence in §1.

6. Scale safety

• MARK is not a full-table scan: dedup key → deterministic_entry_id (uuid5) → find("decision_backlog_entry", entry_id=…) = equality on the primary key (uniquely indexed by definition). The prior O(N) find()-all + Python filter is gone (§3.3). Indexed at 100k/1M+ with zero schema change.
• Sweep batch is config-driven: DOT_CUTTER_SWEEP_BATCH env, clamped [1,10000], fail-safe default 100; never a hardcoded number in the loop (§3.4/3.5); candidate read is server-side WHERE status=%s.
• Table/column assumptions are test-backed: every runtime table/column the writers emit is asserted against the static _schema_contract_fixture.py by test_schema_binding_contract.py (set-equality), so a deployed-schema drift fails CI deterministically rather than at runtime.
• Future index is performance-only, not correctness: the canonical single-IU PG-backed dry-run needs no index/migration to be correct (PK lookup already indexed; counts r3-invariant). The pre-scale additive index list (FK/lookup indexes) is purely throughput at 100k/1M — it does not change behaviour or counts and is a separate later GPT-gated index-only DDL cycle.
• Count-invariance: InMemory probe of MARK→SWEEP→REVIEW→CUT→VERIFY produced exactly the r3 baseline (entry1 history5 dependency0 sweep_log1 envelope1 unit_block1 review1 dot_pair2 ccs1 affected1 verify1 alias0, total 15, status verified_complete).

7. Limitations (explicit)

• No PG-backed dry-run executed — remains blocked pending GPT review of this evidence package; correctness shown only via the stdlib InMemory probe + 101/101 unit suite (no live DB, by mandate).
• No index DDL authored/applied (pre-scale, separate GPT-gated index-only cycle).
• No JSONB normalization (idempotency-key graduation deferred to a later GPT-gated cycle; not required for the single-IU dry-run).
• No production connection / secret / CUT / VERIFY / deploy / migration / vector integration in this cycle.

8. Verdict

Commit 84c52c5 is internally verifiable: git-clean, blob-faithful (6× sha256 MATCH), 101/101 tests, r3 count-invariant, scope-compliant (only the 3 allowed cutter_agent files + tests; db_adapter.py et al. untouched), no hardcoded connection/secret/SQL surface, MARK scale-safe by PK, sweep config-driven. Next gate: GPT review of this evidence package; on PASS the PG-backed dry-run resumes with command-review r1 + verification-plan r3 unchanged. No self-advance — no dry-run/provisioning/production performed or implied here.