@synapsor/runner 1.6.0 → 1.6.1

package/docs/security-boundary.md

@@ -120,6 +120,16 @@ explicit host-level administrative boundary.
 Proposal tools read the current row through the read credential, store evidence
 and an exact before/after diff, and leave the source database unchanged.
 
+For an explicitly freshness-enabled proposal, Runner also captures exact
+version authority for the target and reviewed same-source supporting rows.
+Before each local approval it performs a read-only live check and binds the
+successful proof to that approval. This improves review integrity but does not
+hold a lock through apply. The trusted direct SQL apply path therefore locks
+and rechecks the dependencies again inside the mutation transaction. A stale
+or unverifiable dependency produces no mutation and is never silently
+refreshed. See
+[Proposal And Evidence Freshness](proposal-evidence-freshness.md).
+
 Code-first Safe Actions do not create authority when a file is edited. Runner
 parses the restricted TypeScript object without importing or executing it,
 compiles it into a digest-addressed disabled canonical draft, and keeps the
@@ -153,11 +163,18 @@ outside the model-facing MCP server and verifies:
 - conflict/version guard;
 - idempotency key;
 - operation-specific version or source-unique deduplication guard;
+- declared same-source supporting-version guards, when freshness is required;
 - job expiry;
 - exactly one reviewed row or every member of one bounded frozen set.
 
 If any authority check cannot be verified, the write fails closed.
 
+Strict freshness is intentionally limited to same-database direct SQL
+writeback. Runner rejects app-owned or cross-source strict freshness because it
+cannot claim one atomic transaction around those effects. Cloud can govern an
+approval, but it does not read the source; the local Runner revalidates source
+state before a Cloud-approved job can mutate data.
+
 For direct SQL writeback, the writer connection is the env var named by the
 source `write_url_env` in `synapsor.runner.json`. With `source_db` receipt
 authority, the source mutation and receipt commit atomically; the receipt table

package/docs/store-lifecycle.md

@@ -48,6 +48,7 @@ then proposal id as the tie-breaker. The default view answers:
 - what capability and business object the model requested;
 - which trusted tenant and principal scoped it;
 - approval state and progress;
+- required/live freshness state and the proof digest bound to each approval;
 - whether a writeback job or intent exists;
 - the latest guarded outcome and whether the source changed;
 - replay and Cloud-link status; and
@@ -123,6 +124,7 @@ The existing commands remain useful when you need one record type:
 | Question | Focused command |
 | --- | --- |
 | What did the model propose? | `synapsor-runner proposals show latest --details` |
+| Is the latest proposal still fresh enough to review? | `synapsor-runner proposals check-freshness latest --config ./synapsor.runner.json` |
 | What data supported it? | `synapsor-runner evidence list --proposal <proposal-id>` then `evidence show <evidence-id> --details` |
 | What query was run? | `synapsor-runner query-audit list --proposal <proposal-id>` |
 | Did guarded writeback apply? | `synapsor-runner receipts list --proposal <proposal-id>` |
@@ -135,6 +137,12 @@ The existing commands remain useful when you need one record type:
 it materializes a job and is therefore an operator mutation, not a read-only
 view.
 
+`proposals check-freshness` is source-read-only but is not a ledger-pure
+inspection: it contacts the configured source and records an immutable proof
+event. The `lifecycle` command never does that; it only reports the most recent
+stored proof and approval linkage. See
+[Proposal And Evidence Freshness](proposal-evidence-freshness.md).
+
 ## Server leases
 
 MCP server modes write a small lease file next to the store:

package/docs/troubleshooting-first-run.md

@@ -364,6 +364,82 @@ Fix:
 Use a read-only credential for MCP reads and a separate writer credential only
 for trusted apply.
 
+## Freshness Check Is Stale
+
+What happened:
+
+```text
+Freshness: stale
+code: FRESHNESS_TARGET_STALE
+```
+
+or:
+
+```text
+code: FRESHNESS_DEPENDENCY_STALE
+```
+
+Why it matters:
+
+The proposal target or one explicitly declared supporting row no longer has
+the exact version captured by the immutable proposal. Runner records no
+approval and never updates the old proposal to match current data.
+
+Fix:
+
+Perform a new reviewed source read and create a new proposal. Do not retry
+approval on the stale proposal or edit its stored JSON.
+
+## Freshness Check Is Unavailable
+
+What happened:
+
+```text
+Freshness: unavailable
+code: FRESHNESS_TEMPORARILY_UNAVAILABLE
+```
+
+Why it matters:
+
+Runner could not prove current source state. Unavailability is not treated as
+fresh, and no approval was recorded.
+
+Fix:
+
+Restore the read connection or resolve the transient database/pool issue, then
+retry:
+
+```bash
+synapsor-runner proposals check-freshness latest \
+  --config ./synapsor.runner.json \
+  --store ./.synapsor/local.db
+```
+
+## Freshness Writer Lock Probe Failed
+
+What happened:
+
+`doctor --check-writeback` reports that the writer cannot lock a declared
+supporting dependency.
+
+Why it matters:
+
+Approval-time reads alone cannot provide the final atomic guarantee. The direct
+SQL adapter must lock and compare every dependency inside the mutation
+transaction.
+
+Fix:
+
+Grant only the narrow table/column privilege required for the writer's
+`SELECT ... FOR UPDATE` locking read, then rerun:
+
+```bash
+synapsor-runner doctor --check-writeback --config ./synapsor.runner.json
+```
+
+Do not replace this with an overprivileged owner/superuser role. See
+[Proposal And Evidence Freshness](proposal-evidence-freshness.md).
+
 ## MCP Client Config Contains A Secret
 
 What happened:

package/docs/writeback-executors.md

@@ -250,3 +250,11 @@ Executor secrets are never exposed over MCP. The model never receives:
 
 `MCP tool call = request/proposal authority. Trusted runner = execution
 authority.`
+
+Optional Runner `proposal_freshness` adds pre-approval and final-transaction
+checks only to same-source direct SQL writeback. It is deliberately rejected
+for HTTP/command handlers and cross-source dependencies: Runner cannot claim an
+atomic source check around an externally owned transaction. Handler authors
+must implement equivalent scope, exact-version, locking, idempotency, and
+receipt semantics themselves. See
+[Proposal And Evidence Freshness](proposal-evidence-freshness.md).

package/fixtures/compatibility/published-1.6.0/manifest.json

@@ -0,0 +1,76 @@
+{
+  "schema_version": "synapsor.published-compatibility.v1",
+  "published_packages": {
+    "@synapsor/runner": {
+      "version": "1.6.0",
+      "npm_shasum": "3ac934e1742184514c7eca935d7d3c1ca752bb70"
+    },
+    "@synapsor/dsl": {
+      "version": "1.5.0",
+      "npm_shasum": "45832b2e4e754bd68d195e3daf14b1c14edbc27d"
+    },
+    "@synapsor/spec": {
+      "version": "1.5.0",
+      "npm_shasum": "e167ccff21e0a511bbe0758d0a918fdd59b03b4d"
+    }
+  },
+  "contracts": [
+    {
+      "path": "packages/spec/fixtures/valid/basic-read.contract.json",
+      "source_sha256": "5ec499965f639d784603b7942390d18a3e742d79e4d510dbea470e166a743972",
+      "canonical_sha256": "9d3addfde77eb6528aae7b9e81ae0f582b5c002aa77ebb2d7381fe663f5f5b1e"
+    },
+    {
+      "path": "packages/spec/fixtures/conformance/aggregate-read/contract.json",
+      "source_sha256": "830bc208b749bb9ed6a4b4468571d58d68bc8a2b6e1072fc45fb87d1c68697e7",
+      "canonical_sha256": "ccc6ea17f449bfc207d1cea70ef3320d575c450a3904c850dcb631132c6e5602"
+    },
+    {
+      "path": "packages/spec/fixtures/conformance/proposal-capability/contract.json",
+      "source_sha256": "d4c25fb8f79f04c13bdb3daf8c18a44d4f1c61596660a67bf35d46d0f94f4100",
+      "canonical_sha256": "d895081246d41a072892b5dde6929099302492a77a229033fbfa5052cce34b18"
+    },
+    {
+      "path": "packages/spec/fixtures/conformance/bounded-set-threats/contract.json",
+      "source_sha256": "c902d45457789a6d87504ca434c8b299f3e09be779f3bfdf7bbd8684d575a10e",
+      "canonical_sha256": "64c7078ff1687762d95c17873238759b3572dce499f903a8d6f1aaa8faae5f24"
+    },
+    {
+      "path": "packages/spec/fixtures/conformance/reversible-change-sets/contract.json",
+      "source_sha256": "7e4f8da90a4b235097f76e70a7f550153bbf62d219e7ef6f4f2194f6c36fa205",
+      "canonical_sha256": "181f2e93ad3c53b9a1345a4ed6c8b5e24ab0201c00159f38659f0c2a00c037de"
+    },
+    {
+      "path": "packages/spec/fixtures/conformance/principal-row-scope/contract.json",
+      "source_sha256": "00a05c1f4e82cc9c4e5d2d68c9c9201cd9512ac42d63292314bb7b4845026996",
+      "canonical_sha256": "fc96a5327ab0f4b311c90da9b5585348e81349ed66bd3a22e41e5f29804c32a8"
+    },
+    {
+      "path": "packages/spec/fixtures/conformance/approval-quorum/contract.json",
+      "source_sha256": "dde6b328f648ba60d837fa363494d764d7eb0d2d9a8a81ff70a9c077edde410c",
+      "canonical_sha256": "9407a7d0cc4439c773c3caf721aaed6c6e163c403fa67518632829d8c5de33e7"
+    }
+  ],
+  "dsl_sources": [
+    {
+      "path": "packages/dsl/examples/aggregate-read.synapsor.sql",
+      "source_sha256": "bccac4c2eb0ab7b2fc099c7fb3f6fdc25ee2e6e534282aa19b46f0aec8191b8d",
+      "canonical_sha256": "0cc2d892f00a31a3582d773812a26c6c45c0ce343e1d8d09da226a5bbb7c93eb"
+    },
+    {
+      "path": "packages/dsl/examples/billing-late-fee.synapsor.sql",
+      "source_sha256": "f5c462cff7aa0cd01a08543c6096ee1d225ebba449d65b7470815b1aa7ec42cd",
+      "canonical_sha256": "d495df575d64e798a730dad385e097dfc2c2f371a1505865bc45179ad3c479f2"
+    },
+    {
+      "path": "packages/dsl/examples/bounded-set-multi-term.synapsor.sql",
+      "source_sha256": "0ae199034ebba8b25146435c911576118f948b55b54636a5e68f46002cd1c6dd",
+      "canonical_sha256": "5b3e84cf8f5062a8afcd50763bde907e6a141977456e74a81d01f8b3a484e422"
+    },
+    {
+      "path": "packages/dsl/examples/principal-row-scope.synapsor.sql",
+      "source_sha256": "08ccd769d633417ea45d478383d9628991f43262223f12c78bbd776202b10253",
+      "canonical_sha256": "e29f2819c267210e54f783c40d0f550d11d0d1de844dbe1590ed8c3405af3cf7"
+    }
+  ]
+}

package/fixtures/compatibility/published-1.6.0/sources/packages/dsl/examples/aggregate-read.synapsor.sql

@@ -0,0 +1,21 @@
+CREATE AGENT CONTEXT finance_operator
+  BIND tenant_id FROM ENVIRONMENT SYNAPSOR_TENANT_ID REQUIRED
+  BIND principal FROM ENVIRONMENT SYNAPSOR_PRINCIPAL REQUIRED
+  TENANT BINDING tenant_id
+  PRINCIPAL BINDING principal
+END
+
+CREATE CAPABILITY billing.overdue_balance_total
+  DESCRIPTION 'Return one suppressed overdue-balance aggregate for the trusted tenant.'
+  RETURNS HINT 'Returns one scalar or a suppression result; never member rows.'
+  USING CONTEXT finance_operator
+  SOURCE local_postgres
+  ON public.invoices
+  PRIMARY KEY id
+  TENANT KEY tenant_id
+  AGGREGATE READ SUM balance_cents
+  SELECT WHERE status = 'overdue'
+  MIN GROUP SIZE 5
+  KEEP OUT customer_email, private_notes
+  REQUIRE EVIDENCE
+END

package/fixtures/compatibility/published-1.6.0/sources/packages/dsl/examples/billing-late-fee.synapsor.sql

@@ -0,0 +1,56 @@
+CREATE AGENT CONTEXT local_operator
+  BIND tenant_id FROM ENVIRONMENT SYNAPSOR_TENANT_ID REQUIRED
+  BIND principal FROM ENVIRONMENT SYNAPSOR_PRINCIPAL REQUIRED
+  TENANT BINDING tenant_id
+  PRINCIPAL BINDING principal
+END
+
+CREATE CAPABILITY billing.inspect_invoice
+  DESCRIPTION 'Inspect one invoice in the trusted tenant before proposing a waiver.'
+  RETURNS HINT 'Returns reviewed invoice fields plus evidence/query-audit handles.'
+  USING CONTEXT local_operator
+  SOURCE local_postgres
+  ON public.invoices
+  PRIMARY KEY id
+  TENANT KEY tenant_id
+  CONFLICT GUARD updated_at
+  LOOKUP invoice_id BY id
+  ARG invoice_id STRING REQUIRED MAX LENGTH 128 DESCRIPTION 'Invoice id such as INV-3001.'
+  ALLOW READ id, tenant_id, customer_id, status, late_fee_cents, waiver_reason, updated_at
+  KEEP OUT card_token, internal_risk_score
+  REQUIRE EVIDENCE
+  MAX ROWS 1
+END
+
+CREATE CAPABILITY billing.propose_late_fee_waiver
+  DESCRIPTION 'Propose waiving one invoice late fee after inspecting invoice and policy evidence.'
+  RETURNS HINT 'Returns a review-required proposal id, exact diff, evidence handle, and source_database_changed:false.'
+  USING CONTEXT local_operator
+  SOURCE local_postgres
+  ON public.invoices
+  PRIMARY KEY id
+  TENANT KEY tenant_id
+  CONFLICT GUARD updated_at
+  LOOKUP invoice_id BY id
+  ARG invoice_id STRING REQUIRED MAX LENGTH 128 DESCRIPTION 'Invoice id such as INV-3001.'
+  ARG waiver_reason TEXT REQUIRED MAX LENGTH 500 DESCRIPTION 'Business reason for the proposed waiver.'
+  ALLOW READ id, tenant_id, customer_id, status, late_fee_cents, waiver_reason, updated_at
+  KEEP OUT card_token, internal_risk_score
+  REQUIRE EVIDENCE
+  MAX ROWS 1
+  PROPOSE ACTION billing.waive_late_fee
+  ALLOW WRITE late_fee_cents, waiver_reason
+  PATCH late_fee_cents = 0
+  PATCH waiver_reason = ARG waiver_reason
+  APPROVAL ROLE billing_lead
+  WRITEBACK DIRECT SQL
+END
+
+CREATE AGENT WORKFLOW billing.late_fee_review
+  USING CONTEXT local_operator
+  ALLOW CAPABILITY billing.inspect_invoice
+  ALLOW CAPABILITY billing.propose_late_fee_waiver
+  REQUIRE EVIDENCE
+  APPROVAL REQUIRED ROLE billing_lead
+  CHECKPOINT PROPOSAL ONLY
+END

package/fixtures/compatibility/published-1.6.0/sources/packages/dsl/examples/bounded-set-multi-term.synapsor.sql

@@ -0,0 +1,30 @@
+CREATE AGENT CONTEXT local_operator
+  BIND tenant_id FROM ENVIRONMENT SYNAPSOR_TENANT_ID REQUIRED
+  BIND principal FROM ENVIRONMENT SYNAPSOR_PRINCIPAL REQUIRED
+  TENANT BINDING tenant_id
+  PRINCIPAL BINDING principal
+END
+
+CREATE CAPABILITY cases.close_high_risk
+  DESCRIPTION 'Close active high-risk support cases within reviewed row and value caps.'
+  RETURNS HINT 'Returns a proposal for the exact reviewed set; source rows remain unchanged.'
+  USING CONTEXT local_operator
+  SOURCE support_db
+  ON public.support_cases
+  PRIMARY KEY id
+  TENANT KEY tenant_id
+  CONFLICT GUARD version
+  LOOKUP reason BY id
+  ARG reason STRING REQUIRED MAX LENGTH 100
+  ALLOW READ id, tenant_id, risk_level, case_status, exposure_cents, version
+  REQUIRE EVIDENCE
+  PROPOSE ACTION close_high_risk UPDATE SET
+  SELECT WHERE risk_level = 'high' AND case_status = 'active'
+  MAX ROWS 10
+  MAX TOTAL exposure_cents BEFORE 50000
+  ALLOW WRITE case_status
+  PATCH case_status = 'closed'
+  ADVANCE VERSION version USING INTEGER INCREMENT
+  APPROVAL ROLE support_manager
+  WRITEBACK DIRECT SQL
+END

package/fixtures/compatibility/published-1.6.0/sources/packages/dsl/examples/principal-row-scope.synapsor.sql

@@ -0,0 +1,23 @@
+CREATE AGENT CONTEXT care_session
+  BIND hospital_id FROM HTTP_CLAIM hospital_id REQUIRED
+  BIND principal FROM HTTP_CLAIM sub REQUIRED
+  TENANT BINDING hospital_id
+  PRINCIPAL BINDING principal
+END
+
+CREATE CAPABILITY care.inspect_assigned_patient
+  DESCRIPTION 'Inspect one patient assigned to the authenticated case manager within the trusted hospital.'
+  RETURNS HINT 'Returns reviewed patient fields and evidence only when both tenant and assignee locks match.'
+  USING CONTEXT care_session
+  SOURCE local_postgres
+  ON public.patients
+  PRIMARY KEY id
+  TENANT KEY hospital_id
+  PRINCIPAL SCOPE KEY assigned_to
+  LOOKUP patient_id BY id
+  ARG patient_id STRING REQUIRED MAX LENGTH 128 DESCRIPTION 'Reviewed patient identifier.'
+  ALLOW READ id, hospital_id, display_name, care_status, updated_at
+  KEEP OUT assigned_to, diagnosis_notes, insurance_member_id
+  REQUIRE EVIDENCE
+  MAX ROWS 1
+END

package/fixtures/compatibility/published-1.6.0/sources/packages/spec/fixtures/conformance/aggregate-read/contract.json

@@ -0,0 +1,119 @@
+{
+  "spec_version": "0.1",
+  "kind": "SynapsorContract",
+  "metadata": {
+    "name": "aggregate read and enum conformance",
+    "version": "1.0.0"
+  },
+  "resources": [
+    {
+      "name": "billing_invoices",
+      "engine": "postgres",
+      "schema": "public",
+      "table": "invoices",
+      "primary_key": "id",
+      "tenant_key": "tenant_id"
+    }
+  ],
+  "contexts": [
+    {
+      "name": "billing_context",
+      "bindings": [
+        {
+          "name": "tenant_id",
+          "source": "environment",
+          "key": "SYNAPSOR_TENANT_ID"
+        },
+        {
+          "name": "principal",
+          "source": "environment",
+          "key": "SYNAPSOR_PRINCIPAL"
+        }
+      ],
+      "tenant_binding": "tenant_id",
+      "principal_binding": "principal"
+    }
+  ],
+  "capabilities": [
+    {
+      "name": "billing.sum_overdue_balance",
+      "description": "Return one privacy-suppressed aggregate for the trusted tenant.",
+      "returns_hint": "Returns one scalar or a suppression result; never member rows.",
+      "kind": "aggregate_read",
+      "context": "billing_context",
+      "source": "local_postgres",
+      "subject": {
+        "resource": "billing_invoices"
+      },
+      "args": {},
+      "visible_fields": [],
+      "kept_out_fields": [
+        "customer_email",
+        "private_notes"
+      ],
+      "evidence": {
+        "required": true,
+        "query_audit": true
+      },
+      "aggregate": {
+        "function": "sum",
+        "column": "balance_cents",
+        "selection": {
+          "all": [
+            {
+              "column": "status",
+              "operator": "eq",
+              "value": "overdue"
+            }
+          ]
+        },
+        "minimum_group_size": 5
+      }
+    },
+    {
+      "name": "billing.inspect_invoice",
+      "description": "Inspect one tenant-scoped invoice using a reviewed risk enum.",
+      "kind": "read",
+      "context": "billing_context",
+      "source": "local_postgres",
+      "subject": {
+        "resource": "billing_invoices"
+      },
+      "args": {
+        "invoice_id": {
+          "type": "string",
+          "required": true,
+          "max_length": 128
+        },
+        "risk_level": {
+          "type": "string",
+          "required": true,
+          "enum": [
+            "low",
+            "medium",
+            "high"
+          ]
+        }
+      },
+      "lookup": {
+        "id_from_arg": "invoice_id"
+      },
+      "visible_fields": [
+        "id",
+        "tenant_id",
+        "status",
+        "balance_cents"
+      ],
+      "kept_out_fields": [
+        "customer_email",
+        "private_notes"
+      ],
+      "evidence": {
+        "required": true,
+        "query_audit": true
+      },
+      "max_rows": 1
+    }
+  ]
+}
+

package/fixtures/compatibility/published-1.6.0/sources/packages/spec/fixtures/conformance/approval-quorum/contract.json

@@ -0,0 +1,44 @@
+{
+  "spec_version": "0.1",
+  "kind": "SynapsorContract",
+  "contexts": [
+    {
+      "name": "local_operator",
+      "bindings": [
+        { "name": "tenant_id", "source": "environment", "key": "SYNAPSOR_TENANT_ID" },
+        { "name": "principal", "source": "environment", "key": "SYNAPSOR_PRINCIPAL" }
+      ],
+      "tenant_binding": "tenant_id",
+      "principal_binding": "principal"
+    }
+  ],
+  "capabilities": [
+    {
+      "name": "billing.propose_late_fee_waiver",
+      "kind": "proposal",
+      "context": "local_operator",
+      "subject": {
+        "schema": "public",
+        "table": "invoices",
+        "primary_key": "id",
+        "tenant_key": "tenant_id",
+        "conflict_key": "updated_at"
+      },
+      "args": { "invoice_id": { "type": "string" } },
+      "lookup": { "id_from_arg": "invoice_id" },
+      "visible_fields": ["id", "tenant_id", "late_fee_cents", "updated_at"],
+      "proposal": {
+        "action": "billing.waive_late_fee",
+        "allowed_fields": ["late_fee_cents"],
+        "patch": { "late_fee_cents": { "fixed": 0 } },
+        "conflict_guard": { "column": "updated_at" },
+        "approval": {
+          "mode": "human",
+          "required_role": "billing_lead",
+          "required_approvals": 2
+        },
+        "writeback": { "mode": "direct_sql" }
+      }
+    }
+  ]
+}

package/fixtures/compatibility/published-1.6.0/sources/packages/spec/fixtures/conformance/bounded-set-threats/contract.json

@@ -0,0 +1,115 @@
+{
+  "spec_version": "0.1",
+  "kind": "SynapsorContract",
+  "metadata": { "name": "bounded-set-threats", "version": "1.0.0" },
+  "contexts": [
+    {
+      "name": "trusted_operator",
+      "bindings": [
+        { "name": "tenant_id", "source": "environment", "key": "SYNAPSOR_TENANT_ID", "required": true },
+        { "name": "principal", "source": "environment", "key": "SYNAPSOR_PRINCIPAL", "required": true }
+      ],
+      "tenant_binding": "tenant_id",
+      "principal_binding": "principal"
+    }
+  ],
+  "capabilities": [
+    {
+      "name": "billing.close_overdue_invoices",
+      "kind": "proposal",
+      "context": "trusted_operator",
+      "source": "local_postgres",
+      "subject": { "schema": "public", "table": "invoices", "primary_key": "id", "tenant_key": "tenant_id", "conflict_key": "version" },
+      "args": { "reason": { "type": "string", "required": true, "max_length": 500 } },
+      "visible_fields": ["id", "tenant_id", "status", "balance_cents", "version"],
+      "kept_out_fields": ["internal_risk_score"],
+      "evidence": { "required": true, "query_audit": true },
+      "proposal": {
+        "action": "close_overdue",
+        "operation": {
+          "kind": "update",
+          "cardinality": "set",
+          "selection": { "all": [{ "column": "status", "operator": "eq", "value": "overdue" }] },
+          "max_rows": 10,
+          "aggregate_bounds": [{ "column": "balance_cents", "measure": "before", "maximum": 50000 }],
+          "version_advance": { "column": "version", "strategy": "integer_increment" }
+        },
+        "allowed_fields": ["status", "close_reason"],
+        "patch": { "status": { "fixed": "closed" }, "close_reason": { "from_arg": "reason" } },
+        "conflict_guard": { "column": "version" },
+        "approval": { "mode": "human", "required_role": "billing_reviewer" },
+        "writeback": { "mode": "direct_sql" }
+      }
+    },
+    {
+      "name": "billing.delete_expired_drafts",
+      "kind": "proposal",
+      "context": "trusted_operator",
+      "source": "local_postgres",
+      "subject": { "schema": "public", "table": "invoice_drafts", "primary_key": "id", "tenant_key": "tenant_id", "conflict_key": "version" },
+      "args": { "reason": { "type": "string", "required": true, "max_length": 500 } },
+      "visible_fields": ["id", "tenant_id", "status", "estimated_cents", "version"],
+      "evidence": { "required": true, "query_audit": true },
+      "proposal": {
+        "action": "delete_expired_drafts",
+        "operation": {
+          "kind": "delete",
+          "cardinality": "set",
+          "selection": { "all": [{ "column": "status", "operator": "eq", "value": "expired" }] },
+          "max_rows": 5,
+          "aggregate_bounds": [{ "column": "estimated_cents", "measure": "before", "maximum": 10000 }]
+        },
+        "allowed_fields": [],
+        "patch": {},
+        "conflict_guard": { "column": "version" },
+        "approval": { "mode": "human", "required_role": "billing_reviewer", "required_approvals": 2 },
+        "writeback": { "mode": "direct_sql" }
+      }
+    },
+    {
+      "name": "billing.create_credits",
+      "kind": "proposal",
+      "context": "trusted_operator",
+      "source": "local_postgres",
+      "subject": { "schema": "public", "table": "account_credits", "primary_key": "id", "tenant_key": "tenant_id" },
+      "args": {
+        "items": {
+          "type": "object_array",
+          "required": true,
+          "max_items": 10,
+          "fields": {
+            "id": { "type": "string", "required": true, "max_length": 128 },
+            "external_id": { "type": "string", "required": true, "max_length": 128 },
+            "amount_cents": { "type": "number", "required": true, "minimum": 1, "maximum": 2500 },
+            "reason": { "type": "string", "required": true, "max_length": 500 }
+          }
+        }
+      },
+      "visible_fields": ["id", "tenant_id", "external_id", "amount_cents", "reason", "version"],
+      "kept_out_fields": ["internal_note"],
+      "evidence": { "required": true, "query_audit": true },
+      "proposal": {
+        "action": "create_credits",
+        "operation": {
+          "kind": "insert",
+          "cardinality": "set",
+          "batch": { "items_from_arg": "items" },
+          "max_rows": 10,
+          "aggregate_bounds": [{ "column": "amount_cents", "measure": "after", "maximum": 25000 }],
+          "deduplication": {
+            "components": [
+              { "column": "tenant_id", "source": "trusted_tenant" },
+              { "column": "id", "source": "item_field", "item_field": "id" },
+              { "column": "external_id", "source": "item_field", "item_field": "external_id" }
+            ]
+          }
+        },
+        "allowed_fields": ["amount_cents", "reason"],
+        "patch": { "amount_cents": { "from_item": "amount_cents" }, "reason": { "from_item": "reason" } },
+        "numeric_bounds": { "amount_cents": { "minimum": 1, "maximum": 2500 } },
+        "approval": { "mode": "human", "required_role": "billing_reviewer" },
+        "writeback": { "mode": "direct_sql" }
+      }
+    }
+  ]
+}