110000x · 01 — Short Operator Contract

Mission: Operator/user issues short commands; no macro-length prompt per file.

1. Five short forms (the operator surface)

MARK file <source_ref> theo quy trình <workflow_ref>, lưu vào <destination_ref>
VERIFY MARK staging_id <id>
CUT staging_id <id>, output <destination>, verify reconstruct + Axis A/B/C
VERIFY CUT run_id <id>
CLEANUP STAGING dry-run older_than 15d

Optional combined (still enforces ordering, no bypass):

MARK_AND_CUT file <source_ref> theo quy trình <workflow_ref>, output <destination>

The combined form internally runs MARK → VERIFY-MARK → APPROVE → CUT → VERIFY-CUT in sequence; it never skips any stage.

2. Two-layer architecture

Layer	Who calls it	Purpose
Agent-side parser	Claude / Codex / operator chat agent	Reads the short form; resolves source_ref, workflow_ref, destination_ref; calls the SQL alias
SQL alias layer	psql -U workflow_admin -d directus	Five fn_iu_op_* wrappers that call the live pipeline (fn_iu_mark_create_manifest, fn_iu_verify_mark, fn_iu_cut_from_manifest, fn_iu_verify_cut_result, fn_iu_staging_cleanup)

Both layers are required for the "short command" feel: the agent does intent parsing + reference resolution, the SQL layer does deterministic execution + atomicity.

3. Resolver protocol

source_ref

Form	Resolution
KB document path knowledge/...	Agent calls mcp__claude_ai_Incomex_KB__get_document_for_rewrite(path) → .content; passes verbatim as p_source_text
URL https://...	Agent calls WebFetch(url) → markdown body → p_source_text
Local file (operator-owned path)	Agent calls Read(path) → text → p_source_text
Inline text	Operator passes text directly; agent forwards

source_ref itself (the human-readable label) is stored in iu_staging_record.source_ref. For KB paths the convention is the path string itself (e.g. knowledge/dev/laws/dieu37-governance-organization-law.md). For URLs use the URL. For local files use the path.

workflow_ref

Form	Resolution
operational-cut-workflow	Resolves to knowledge/dev/laws/dieu44-trien-khai/v0.6-iu-core-operational-cut-workflow-mark-review-cut-verify/ (the 80000x doctrine package). Agent reads piece-cutting rules from this package.

Other workflow_refs are reserved for future packages. Agent must refuse unknown workflow_ref.

destination_ref

Form	Resolution
No-Vector Staging Zone	iu_core.iu_staging_record + iu_core.iu_staging_payload (Q5 vector_excluded=true; structural NVSZ)
IU corpus	public.information_unit (live IU rows) — only valid as CUT output

The MARK alias only writes to NVSZ. The CUT alias only writes to IU corpus (and audit/staging-lifecycle columns). No alias may use any other destination.

4. Five fn_iu_op_* contracts (signatures)

fn_iu_op_mark_file(
  p_source_text       text,        -- resolved by agent
  p_source_ref        text,        -- KB path / URL / file / 'inline'
  p_pieces            jsonb,       -- array, per cut_manifest schema (M1-M16)
  p_actor             text,
  p_source_kind       text DEFAULT 'user',           -- {agent,user,system,import}
  p_idempotency_key   text DEFAULT NULL,             -- auto-derived if NULL
  p_mark_report_md    text DEFAULT NULL,             -- auto-stub if NULL
  p_workflow_ref      text DEFAULT 'operational-cut-workflow'
) RETURNS jsonb  -- {alias, staging_record_id, manifest_digest, source_hash, source_bytes, lifecycle_status, destination, inner_result}

fn_iu_op_verify_mark(
  p_staging_record_id uuid,
  p_approve           boolean DEFAULT false,
  p_approval_doc_id   text DEFAULT NULL,
  p_approver          text DEFAULT NULL,
  p_actor             text DEFAULT NULL
) RETURNS jsonb  -- {alias, staging_record_id, approve, verdict, inner_result}

fn_iu_op_cut(
  p_staging_record_id uuid,
  p_apply             boolean,
  p_actor             text,
  p_open_composer     boolean DEFAULT false   -- if true, in-TX UPDATE dot_config composer_enabled=true
) RETURNS jsonb  -- {alias, staging_record_id, apply, source_hash_resolved, composer_pre, composer_opened_by_alias, applied, pieces_created_count, run_id, refusal_code, inner_result}

fn_iu_op_verify_cut(
  p_run_id            uuid,
  p_actor             text DEFAULT 'operator'
) RETURNS jsonb  -- {alias, run_id, verdict, inner_result}

fn_iu_op_cleanup_dry_run(
  p_older_than_days   integer DEFAULT 15,
  p_actor             text DEFAULT 'operator'
) RETURNS jsonb  -- {alias, apply:false, older_than_days, eligible_count, actions[]}

5. Non-bypass invariants

1. fn_iu_op_cut always delegates to fn_iu_cut_from_manifest, which enforces G1-G7 (not_found, wrong_kind, not_approved, incomplete_approval, digest_changed, source_changed, composer_gate_closed). The alias adds zero bypass paths.
2. fn_iu_op_cut reads p_source_hash from the staging record's cut_manifest payload, then passes it to fn_iu_cut_from_manifest — this preserves G6 source-hash semantics (operator must have approved the same source).
3. p_open_composer=true performs an in-TX UPDATE dot_config SET value='true' WHERE key='iu_core.composer_enabled'; the gate flips closed on rollback. Operator must UPDATE … false after a real cut (not the alias's job).
4. fn_iu_op_cleanup_dry_run calls fn_iu_staging_cleanup(false, …) — never (true, …). There is no fn_iu_op_cleanup_apply alias. Apply-mode cleanup remains operator-direct call.
5. The combined MARK_AND_CUT agent flow is a scripted sequence, not a single SQL function: agent runs MARK → VERIFY (apply=true with approval_doc_id) → CUT (with p_open_composer=true) → VERIFY-CUT. If any stage refuses, the script halts.

6. Determinism

fn_iu_op_mark_file computes:

• source_hash = md5(p_source_text)
• source_bytes = octet_length(p_source_text)
• manifest_digest = md5(source_hash || '|' || source_bytes || '|' || p_pieces::text) (32-hex)
• idempotency_key (when NULL) = 'op-mark-' || source_hash || '-' || manifest_digest

This guarantees: same (source_text, pieces) → identical staging_record_id (via idempotency_key), identical manifest_digest. Required for Điều 30 regression equivalence (alias-vs-direct same-input-same-output).

7. Reference

• See report 02 for the full SQL implementation (migration 042R).
• See report 03 for the Điều 30 regression suite.
• See report 04 for the Điều 31 integrity / refusal suite.
• See report 09 for the short runbook with worked examples (KB path, URL, local file, inline).