diff --git a/docs/demos/outbox-disposition.log b/docs/demos/outbox-disposition.log new file mode 100644 index 0000000..79c7137 --- /dev/null +++ b/docs/demos/outbox-disposition.log @@ -0,0 +1,7 @@ +Script started on 2026-11-13 14:10:21-05:00 [COMMAND="python3 scripts/demo-outbox-disposition.py" ] +Synthetic fixture: same old firing; deliver_pending at t=10; fresh control at t=20. base +{"mode": "base", "obsolete_attempts": 1, "obsolete_received": true, "sent": ["old-event", "fresh-event"], "fresh_control_received": true} +Synthetic fixture: same old firing; deliver_pending at t=10; fresh control at t=20. expired +{"mode": "expired", "obsolete_attempts": 0, "obsolete_received": false, "sent": ["fresh-event"], "fresh_control_received": true} + +Script done on 2026-11-13 14:10:21-05:00 [COMMAND_EXIT_CODE="0"] diff --git a/docs/demos/outbox-disposition.md b/docs/demos/outbox-disposition.md new file mode 100644 index 0000000..e5fa10c --- /dev/null +++ b/docs/demos/outbox-disposition.md @@ -0,0 +1,28 @@ +# Outbox expiry demonstration + +This terminal recording uses disposable synthetic SQLite state and the real +`deliver_pending` implementation. An obsolete firing delivers on base +`64e484528d1b7f6955dbdff01e9d4e2c2a367464`; after its explicit disposition on +implementation `7650ae4`, it remains undelivered with zero attempts. A fresh event +still delivers on both revisions. No sink network, deployment or private state +participates; the sink is an in-process receipt fixture. + +[Readable transcript](outbox-disposition.log) and +[timing file](outbox-disposition.timing) are retained with this source as a small +review artifact. Replay after downloading both files: + +```sh +scriptreplay --log-out outbox-disposition.log --log-timing outbox-disposition.timing +``` + +Playback was verified with util-linux `scriptreplay`; no inline video embed is +claimed. Reproduce from the implementation checkout, with a separate export of +the exact base: + +```sh +DEMO_BASE_SOURCE=/path/to/base python3 scripts/demo-outbox-disposition.py +``` + +Later commits adding this recording and caption do not change the demonstrated +implementation. This source fixture demonstrates delivery behavior, not installed +acceptance or representative backlog rehearsal. diff --git a/docs/demos/outbox-disposition.timing b/docs/demos/outbox-disposition.timing new file mode 100644 index 0000000..166ac82 --- /dev/null +++ b/docs/demos/outbox-disposition.timing @@ -0,0 +1,4 @@ +0.017207 90 +0.171376 139 +0.018143 93 +0.134688 130 diff --git a/docs/outbox-disposition.md b/docs/outbox-disposition.md new file mode 100644 index 0000000..f618dd8 --- /dev/null +++ b/docs/outbox-disposition.md @@ -0,0 +1,59 @@ +# Expire retained firings without delivery + +`chaski-outbox-disposition` (also `python emitter.py`) supports an explicit, +reviewed, append-only `expired-not-delivered` disposition. Original outbox rows, +payloads, attempts, receiver bindings, delivery timestamps and cursors remain +unchanged. A disposition is not a receiver receipt or acknowledgement. Recoveries +require separate adjudication and cannot use this command. + +Create a private plan from an existing database with `plan --db INBOX --plan PLAN +--emitter LABEL --created-before UNIX_SECONDS --expected-count COUNT --reason +REASON --ruling-ref REFERENCE`. This opens SQLite read-only and holds a consistent +read transaction. The plan records every exact event ID and full-row hash, scope, +cutoff, count, reason, ruling reference and source UTC. It contains no event +payloads, but its identities may still be private. The command writes an exclusive +0600 plan file and prints its SHA256. Review that exact file and hash through the +normal deployment process; a free-text ruling reference does not authenticate or +authorize the caller. + +Only after the consumer is quiesced and the deployment's hold-release admission +is recorded, run `apply --db INBOX --cursor CURSOR --plan PLAN +--expected-plan-sha256 HASH`. This takes the same exclusive cursor/inbox lease as +the consumer and appends in one SQLite transaction. Every selected row must still +be undelivered, never attempted, unbound and not recovery-queued; the exact scoped +population and every full-row hash must match. Changes, duplicates, foreign scope, +recovery payloads and conflicting prior decisions refuse the whole append. +Replaying the identical plan is idempotent. No sink or network call occurs. + +New plans select only work without a prior disposition, so later cohorts can be +expired without selecting the originals retained by an earlier plan. Validation +includes receipts belonging to the exact plan being replayed; receipts from +other plans remain excluded. Both original plans can be replayed without changing +their receipts, while a changed decision for an already-disposed identity still +refuses. Newly eligible rows outside the reviewed population still refuse apply. + +`list --db INBOX` lists retained receipts (up to 10,000; a larger population +refuses). `verify --db INBOX` checks original row hashes and eligibility read-only. +Startup verifies the same contract; missing or changed originals refuse startup. +The runtime fences by event identity even if a row drifts after startup, so a +changed fingerprint never silently releases it. Delivery, receiver setup, +receiver binding, write-budget scheduling, wakeups, renewal and recovery selection +honor this fence. Pending/oldest-pending metrics exclude disposed rows; +`chaski_emitter_outbox_disposed_total` reports them separately. Delivered metrics +continue to count only actual delivery receipts. Supported key migration refuses +to rename an identity with a disposition. + +## Rollback and custody + +An older consumer that does not understand this ledger can send retained rows +again. Neither installing the ledger alone nor restoring such a binary is a safe +rollback. Keep the delivery hold asserted while preparing the ledger and moving +to the expiry-aware consumer. Before releasing the hold, rehearse the same source +revision and name either an expiry-aware rollback target or the explicit operation +that re-asserts the hold before any older consumer starts. The CLI's lease prevents +an overlapping cooperating consumer; it cannot confer this operational admission +or control a legacy process that ignores custody. + +Never erase originals, mark them delivered, reset a cursor, forge a historical +receiver binding, or disable the ledger to manufacture a clean queue. New events +outside the exact plan retain the normal delivery contract. diff --git a/emitter.py b/emitter.py index 416f7b8..76c4f94 100644 --- a/emitter.py +++ b/emitter.py @@ -46,6 +46,7 @@ import hashlib import json import logging +import math import re import sqlite3 import subprocess @@ -66,6 +67,24 @@ DELIVER_PER_TICK = 5 SCHEMA = """ +CREATE TABLE IF NOT EXISTS outbox_dispositions ( + source_table TEXT NOT NULL CHECK(source_table='outbox'), + event_id TEXT NOT NULL, + row_sha256 TEXT NOT NULL, + plan_sha256 TEXT NOT NULL, + disposition TEXT NOT NULL CHECK(disposition='expired-not-delivered'), + reason TEXT NOT NULL, + ruling_ref TEXT NOT NULL, + source_utc TEXT NOT NULL, + recorded_at REAL NOT NULL, + PRIMARY KEY(source_table,event_id) +); +CREATE TRIGGER IF NOT EXISTS outbox_dispositions_no_update + BEFORE UPDATE ON outbox_dispositions BEGIN + SELECT RAISE(ABORT,'disposition ledger is append-only'); END; +CREATE TRIGGER IF NOT EXISTS outbox_dispositions_no_delete + BEFORE DELETE ON outbox_dispositions BEGIN + SELECT RAISE(ABORT,'disposition ledger is append-only'); END; CREATE TABLE IF NOT EXISTS renewal_receipts ( event_id TEXT PRIMARY KEY, last_received REAL, @@ -179,6 +198,11 @@ def connect(path: Path | str) -> sqlite3.Connection: conn.execute("CREATE INDEX IF NOT EXISTS outbox_recovery_candidates ON outbox(emitter,item,created,event_id)" " WHERE recovery_queued=0 AND delivered_at IS NOT NULL") conn.execute("CREATE INDEX IF NOT EXISTS verdict_recovery_candidates ON verdicts(emitter,recovery_at)") + try: + verify_dispositions(conn) + except BaseException: + conn.close() + raise return conn @@ -379,7 +403,7 @@ def queue_recoveries(conn: sqlite3.Connection, emitter: Emitter, limit: int = DE " LEFT JOIN recovery_outbox r ON r.emitter=o.emitter AND r.prior_event=o.event_id" " WHERE o.emitter=? AND o.recovery_queued=0 AND o.delivered_at IS NOT NULL" " AND v.recovery_at IS NOT NULL AND (v.tracked=0 OR v.verdict!=?)" - " AND r.event_id IS NULL ORDER BY o.created,o.event_id LIMIT ?", + " AND " + undisposed("o") + " AND r.event_id IS NULL ORDER BY o.created,o.event_id LIMIT ?", (emitter.label, emitter.to_verdict, limit)).fetchall() queued = [] for prior_id, item, raw, generation, recovered_at, scope in rows: @@ -475,11 +499,18 @@ def sink_setup_allowed(conn, sink, now, emitter, resolve_recovery): allowed = not resolve_recovery first = conn.execute( "SELECT delivery_scope FROM outbox WHERE emitter=? AND delivered_at IS NULL" - " AND next_attempt<=? ORDER BY created LIMIT 1", (emitter, now)).fetchone() + " AND " + undisposed("outbox") + " AND next_attempt<=? ORDER BY created LIMIT 1", (emitter, now)).fetchone() if first is not None: scope_fn = getattr(sink, "delivery_scope", None) scope = scope_fn() if scope_fn is not None else None allowed = first[0] is None or json.loads(first[0]) == scope + if first is None and conn.execute( + "SELECT 1 FROM outbox_dispositions d JOIN outbox o ON o.event_id=d.event_id" + " WHERE o.emitter=? LIMIT 1", (emitter,)).fetchone(): + # Disposed work must not cause a receiver setup/budget write either. + allowed = allowed and bool(conn.execute( + "SELECT 1 FROM outbox WHERE emitter=? AND delivered_at IS NULL AND " + + undisposed("outbox") + " LIMIT 1", (emitter,)).fetchone()) return allowed @@ -511,7 +542,8 @@ def deliver_pending(conn: sqlite3.Connection, sink: Sink, now: float, emitter: s tables = ("outbox", "recovery_outbox") if resolve_recovery else ("outbox",) query = " UNION ALL ".join( f"SELECT event_id,payload,attempts,created,'{table}' AS source_table FROM {table}" - " WHERE emitter=? AND delivered_at IS NULL AND next_attempt<=?" for table in tables) + " WHERE emitter=? AND delivered_at IS NULL AND next_attempt<=? AND " + + (undisposed(table) if table == "outbox" else "1") for table in tables) args = [value for _ in tables for value in (emitter, now)] + [limit] rows = conn.execute(query + " ORDER BY created LIMIT ?", args).fetchall() ok = failed = 0 @@ -591,7 +623,7 @@ def renew_active(conn: sqlite3.Connection, sink: Sink, now: float, definition: E "LEFT JOIN renewal_receipts r ON r.event_id=o.event_id " "WHERE v.emitter=? AND v.tracked=1 AND v.verdict=? " "AND v.item IN (SELECT value FROM json_each(?)) " - "AND o.delivered_at IS NOT NULL AND COALESCE(r.next_attempt,0)<=? " + "AND " + undisposed("o") + " AND o.delivered_at IS NOT NULL AND COALESCE(r.next_attempt,0)<=? " "AND COALESCE(r.last_received,o.delivered_at)<=? " "ORDER BY COALESCE(r.last_received,o.delivered_at) LIMIT ?", (definition.label, definition.to_verdict, json.dumps(sorted(positive)), now, @@ -678,7 +710,8 @@ def delivery_due(self, now): " AND NOT EXISTS (SELECT 1 FROM outbox prior WHERE" f" prior.event_id=json_extract({table}.payload,'$.resolution_of')" " AND prior.delivered_at IS NOT NULL) THEN MAX(next_attempt,?)" - f" ELSE next_attempt END) FROM {table} WHERE emitter=? AND delivered_at IS NULL", + f" ELSE next_attempt END) FROM {table} WHERE emitter=? AND delivered_at IS NULL AND " + + (undisposed(table) if table == "outbox" else "1"), (now + 5, self.emitter.label)).fetchone() if row[0] is not None: values.append(row[0]) @@ -747,7 +780,7 @@ def tick(self, now: float) -> None: def _snapshot_values(self) -> dict: pending, oldest = self.conn.execute( "SELECT COUNT(*), MIN(created) FROM (" - " SELECT created FROM outbox WHERE emitter=? AND delivered_at IS NULL" + " SELECT created FROM outbox WHERE emitter=? AND delivered_at IS NULL AND " + undisposed("outbox") + " UNION ALL SELECT created FROM recovery_outbox WHERE emitter=? AND delivered_at IS NULL)", (self.emitter.label, self.emitter.label)).fetchone() delivered = self.conn.execute( @@ -760,7 +793,10 @@ def _snapshot_values(self) -> dict: "JOIN verdicts v ON v.last_event=o.event_id " "WHERE v.emitter=? AND v.tracked=1 AND v.verdict=?", (self.emitter.label,self.emitter.to_verdict)).fetchone() - return {"renewal_receipts": renewal_pending, "renewal_failures": renewal_failures, + disposed = self.conn.execute( + "SELECT COUNT(*) FROM outbox_dispositions d JOIN outbox o ON o.event_id=d.event_id" + " WHERE o.emitter=?", (self.emitter.label,)).fetchone()[0] + return {"disposed": disposed, "renewal_receipts": renewal_pending, "renewal_failures": renewal_failures, "runs": dict(self.runs), "last_success": self.last_success, "queued_total": self.queued_total, "pending": pending, "oldest_created": oldest, "delivered": delivered} @@ -783,8 +819,244 @@ def metrics(self, esc) -> list[str]: f'chaski_emitter_renewal_failures{{emitter="{label}"}} {s["renewal_failures"]}', f'chaski_emitter_renewal_receipts{{emitter="{label}"}} {s["renewal_receipts"]}', f'chaski_emitter_outbox_pending{{emitter="{label}"}} {s["pending"]}', + f'chaski_emitter_outbox_disposed_total{{emitter="{label}"}} {s["disposed"]}', f'chaski_emitter_outbox_delivered_total{{emitter="{label}"}} {s["delivered"]}', f'chaski_emitter_outbox_oldest_pending_age_seconds{{emitter="{label}"}} ' f'{(time.time() - oldest) if oldest else 0:.0f}', ] return lines + + +DISPOSITION_PLAN = 'chaski-outbox-disposition/v1' + + +def undisposed(alias): + """Fence by immutable event identity, even if a retained row later drifts. + + The row fingerprint is independently verified at startup and apply. Matching + only the fingerprint here could accidentally release a changed row. + """ + if alias not in ('outbox', 'o'): + raise ValueError('invalid outbox alias') + return ("NOT EXISTS (SELECT 1 FROM outbox_dispositions disposition WHERE " + f"disposition.source_table='outbox' AND disposition.event_id={alias}.event_id)") + + +def disposition_digest(value): + return hashlib.sha256(json.dumps(value, sort_keys=True, separators=(',', ':'), + allow_nan=False).encode()).hexdigest() + + +def disposition_row(conn, event_id): + cursor = conn.execute('SELECT * FROM outbox WHERE event_id=?', (event_id,)) + row = cursor.fetchone() + return None if row is None else dict(zip((d[0] for d in cursor.description), row)) + + +def disposition_eligible(row): + if (row is None or row['delivered_at'] is not None or row['attempts'] != 0 + or row['delivery_scope'] is not None or row['recovery_queued'] != 0): + raise ValueError('disposition requires an unbound never-attempted firing') + payload = json.loads(row['payload']) + if not isinstance(payload, dict) or 'prior' in payload or 'resolution_of' in payload: + raise ValueError('recovery dispositions require separate adjudication') + + +def verify_dispositions(conn): + """Never reinterpret a disposition as a delivery receipt.""" + rows = conn.execute('SELECT event_id,row_sha256 FROM outbox_dispositions').fetchall() + for identity, expected in rows: + row = disposition_row(conn, identity) + disposition_eligible(row) + if disposition_digest(row) != expected: + raise ValueError('disposed row changed or disappeared; consumer remains fenced') + return len(rows) + + +def disposition_ledger_present(conn): + return conn.execute( + "SELECT 1 FROM sqlite_master WHERE type='table' AND name='outbox_dispositions'" + ).fetchone() is not None + + +def disposition_population(conn, emitter, cutoff, limit, replay_digest=None): + """New plans exclude receipts; replay includes only this exact plan's receipts. + + A first read-only plan may inspect a legacy database before schema adoption. + Missing ledger is empty only after a successful exact schema read. + """ + join, receipt_filter, receipt_params = '', '', () + if disposition_ledger_present(conn): + join = (" LEFT JOIN outbox_dispositions d ON d.source_table='outbox' " + 'AND d.event_id=o.event_id') + receipt_filter = 'AND (d.event_id IS NULL OR d.plan_sha256=?) ' + receipt_params = (replay_digest,) + return conn.execute( + 'SELECT o.event_id FROM outbox o' + join + + ' WHERE o.emitter=? AND o.created<=? AND o.delivered_at IS NULL ' + 'AND o.attempts=0 AND o.delivery_scope IS NULL AND o.recovery_queued=0 ' + + receipt_filter + 'ORDER BY o.event_id LIMIT ?', + (emitter, cutoff, *receipt_params, limit)).fetchall() + + +def inspect_disposition_plan(conn, plan): + fields = {'schema', 'emitter', 'created_before', 'expected_count', 'reason', + 'ruling_ref', 'source_utc', 'rows'} + if not isinstance(plan, dict) or set(plan) != fields or plan['schema'] != DISPOSITION_PLAN: + raise ValueError('invalid disposition plan') + if (type(plan['expected_count']) is not int or not 1 <= plan['expected_count'] <= 10000 + or not isinstance(plan['rows'], list) or len(plan['rows']) != plan['expected_count']): + raise ValueError('invalid exact population bound') + for field in ('emitter', 'reason', 'ruling_ref', 'source_utc'): + if not isinstance(plan[field], str) or not plan[field].strip() or len(plan[field]) > 4096: + raise ValueError('missing disposition provenance') + if not re.fullmatch(r'\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d+)?Z', plan['source_utc']): + raise ValueError('source UTC must be explicit') + if type(plan['created_before']) not in (int, float) or not math.isfinite(plan['created_before']): + raise ValueError('invalid creation cutoff') + identities = set() + for entry in plan['rows']: + if (not isinstance(entry, dict) or set(entry) != {'event_id', 'row_sha256'} + or not isinstance(entry['event_id'], str) or not entry['event_id'] + or not isinstance(entry['row_sha256'], str) + or not re.fullmatch('[0-9a-f]{64}', entry['row_sha256']) + or entry['event_id'] in identities): + raise ValueError('invalid or duplicate row identity') + identities.add(entry['event_id']) + row = disposition_row(conn, entry['event_id']) + disposition_eligible(row) + if (row['emitter'] != plan['emitter'] or row['created'] > plan['created_before'] + or disposition_digest(row) != entry['row_sha256']): + raise ValueError('exact reviewed row changed or foreign scope') + digest = disposition_digest(plan) + if disposition_ledger_present(conn): + for entry in plan['rows']: + prior = conn.execute( + "SELECT plan_sha256 FROM outbox_dispositions WHERE source_table='outbox' AND event_id=?", + (entry['event_id'],)).fetchone() + if prior is not None and prior[0] != digest: + raise ValueError('conflicting append-only disposition') + population = {row[0] for row in disposition_population( + conn, plan['emitter'], plan['created_before'], plan['expected_count'] + 1, digest)} + if population != identities: + raise ValueError('exact reviewed population changed') + return digest + + +def apply_disposition_plan(conn, plan, expected_sha256): + """Append atomically under the caller's exclusive consumer custody. + + The ruling reference records a caller declaration, not authentication or a + replacement for the deployment's operator admission and quiesced handoff. + """ + if conn.in_transaction: + raise ValueError('disposition requires its own transaction') + conn.execute('BEGIN IMMEDIATE') + try: + digest = inspect_disposition_plan(conn, plan) + if digest != expected_sha256: + raise ValueError('reviewed plan hash mismatch') + verify_dispositions(conn) + recorded = time.time() + for entry in plan['rows']: + receipt = (entry['row_sha256'], digest, 'expired-not-delivered', plan['reason'], + plan['ruling_ref'], plan['source_utc']) + prior = conn.execute( + 'SELECT row_sha256,plan_sha256,disposition,reason,ruling_ref,source_utc ' + "FROM outbox_dispositions WHERE source_table='outbox' AND event_id=?", + (entry['event_id'],)).fetchone() + if prior is not None: + if tuple(prior) != receipt: + raise ValueError('conflicting append-only disposition') + continue + conn.execute('INSERT INTO outbox_dispositions VALUES (?,?,?,?,?,?,?,?,?)', + ('outbox', entry['event_id'], *receipt, recorded)) + conn.commit() + except BaseException: + conn.rollback() + raise + return {'plan_sha256': digest, 'disposed_rows': len(plan['rows']), + 'disposition': 'expired-not-delivered'} + + +def disposition_main(argv=None): + """Supported offline plan/apply/list/verify; never opens a sink or network. + + # arming: agent-invoked — exact reviewed plan and exclusive consumer lease. + """ + import argparse + import datetime + import os + from consumer_lease import ConsumerLease + from chaski_version import add_version_argument + ap = argparse.ArgumentParser(description='Append-only expiry; original rows remain undelivered') + add_version_argument(ap, 'chaski-outbox-disposition') + ap.add_argument('action', choices=('plan', 'apply', 'list', 'verify')) + ap.add_argument('--db', type=Path, required=True) + ap.add_argument('--cursor', type=Path) + ap.add_argument('--plan', type=Path) + ap.add_argument('--expected-plan-sha256') + ap.add_argument('--emitter') + ap.add_argument('--created-before', type=float) + ap.add_argument('--expected-count', type=int) + ap.add_argument('--reason') + ap.add_argument('--ruling-ref') + args = ap.parse_args(argv) + if not args.db.is_file(): + ap.error('existing inbox required; no initialization') + if args.action == 'apply': + if not args.cursor or not args.cursor.is_file() or not args.plan or not args.expected_plan_sha256: + ap.error('apply requires existing cursor custody, reviewed plan and exact hash') + if args.plan.stat().st_size > 4 * 1024 * 1024: + ap.error('plan exceeds 4MiB bound') + plan = json.loads(args.plan.read_text()) + with ConsumerLease(args.cursor, args.db): + conn = connect(args.db) + try: + result = apply_disposition_plan(conn, plan, args.expected_plan_sha256) + finally: + conn.close() + else: + conn = sqlite3.connect(args.db.resolve().as_uri() + '?mode=ro', uri=True) + try: + conn.execute('PRAGMA query_only=ON') + conn.execute('BEGIN') + if args.action == 'plan': + if not all((args.emitter, args.plan, args.reason, args.ruling_ref)) or args.created_before is None: + ap.error('plan requires emitter, cutoff, count, reason, ruling ref and output path') + if type(args.expected_count) is not int or not 1 <= args.expected_count <= 10000: + ap.error('exact count must be 1..10000') + rows = disposition_population( + conn, args.emitter, args.created_before, args.expected_count + 1) + if len(rows) != args.expected_count: + raise ValueError('review population count changed') + plan = {'schema': DISPOSITION_PLAN, 'emitter': args.emitter, + 'created_before': args.created_before, 'expected_count': args.expected_count, + 'reason': args.reason, 'ruling_ref': args.ruling_ref, + 'source_utc': datetime.datetime.now(datetime.timezone.utc).isoformat().replace('+00:00', 'Z'), + 'rows': [{'event_id': row[0], 'row_sha256': disposition_digest(disposition_row(conn, row[0]))} + for row in rows]} + digest = inspect_disposition_plan(conn, plan) + with os.fdopen(os.open(args.plan, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600), 'w') as output: + json.dump(plan, output, indent=2) + result = {'plan_sha256': digest, 'rows': len(rows), 'status': 'dry-run; no inbox mutation'} + else: + count = verify_dispositions(conn) + result = {'verified_dispositions': count} + if args.action == 'list': + result['receipts'] = [dict(zip(('event_id', 'row_sha256', 'plan_sha256', 'disposition', + 'reason', 'ruling_ref', 'source_utc', 'recorded_at'), row)) + for row in conn.execute( + 'SELECT event_id,row_sha256,plan_sha256,disposition,reason,' + 'ruling_ref,source_utc,recorded_at FROM outbox_dispositions ' + 'ORDER BY event_id LIMIT 10001')] + if len(result['receipts']) > 10000: + raise ValueError('list bound exceeded; no complete listing') + finally: + conn.close() + print(json.dumps(result)) + return 0 + + +if __name__ == '__main__': + raise SystemExit(disposition_main()) diff --git a/pyproject.toml b/pyproject.toml index c4e22d6..a10c9a7 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -29,6 +29,7 @@ chaski-event = "external_event:main" chaski-github-routes = "github_routes:main" chaski-github-work = "github_work:main" chaski-once = "once:main" +chaski-outbox-disposition = "emitter:disposition_main" chaski-state-key-migrate = "state_key_migration:main" [tool.setuptools] diff --git a/scripts/demo-outbox-disposition.py b/scripts/demo-outbox-disposition.py new file mode 100644 index 0000000..f7c290a --- /dev/null +++ b/scripts/demo-outbox-disposition.py @@ -0,0 +1,59 @@ +"""Record actual before/after library delivery on synthetic disposable state. + +DEMO_BASE_SOURCE selects a checkout/export of the documented base revision. +No production paths, adapters, credentials, or network are used. +""" +import os +from pathlib import Path +import subprocess +import sys + +PROBE = r''' +import json,sys,tempfile +sys.path.insert(0,sys.argv[1]) +import emitter as em +class Sink: + def __init__(self): self.events=[] + def deliver(self,event): self.events.append(event['event_id']) +with tempfile.TemporaryDirectory() as root: + conn=em.connect(root+'/fixture.db') + definition=em.Emitter(label='fixture',command=[],interval_s=5,owner='fixture') + em.observe(conn,definition,[{'item':'old','verdict':'BLOCKED'}],1) + em.observe(conn,definition,[{'item':'old','verdict':'UNBLOCKED','event_id':'old-event'}],2) + old=conn.execute('SELECT event_id FROM outbox').fetchone()[0] + if sys.argv[2]=='expired': + plan={'schema':em.DISPOSITION_PLAN,'emitter':'fixture','created_before':3, + 'expected_count':1,'reason':'obsolete synthetic backlog','ruling_ref':'fixture-ruling', + 'source_utc':'2026-01-01T00:00:00Z', + 'rows':[{'event_id':old,'row_sha256':em.disposition_digest(em.disposition_row(conn,old))}]} + em.apply_disposition_plan(conn,plan,em.disposition_digest(plan)) + sink=Sink() + em.deliver_pending(conn,sink,10,'fixture') + row=conn.execute('SELECT attempts,delivered_at FROM outbox WHERE event_id=?',(old,)).fetchone() + if sys.argv[2]=='expired': + assert row==(0,None) and sink.events==[] + else: + assert row==(1,10) and sink.events==[old] + em.observe(conn,definition,[{'item':'fresh','verdict':'BLOCKED'}],11,scope=['fresh']) + em.observe(conn,definition,[{'item':'fresh','verdict':'UNBLOCKED','event_id':'fresh-event'}],12,scope=['fresh']) + em.deliver_pending(conn,sink,20,'fixture') + assert 'fresh-event' in sink.events + print(json.dumps({'mode':sys.argv[2],'obsolete_attempts':row[0], + 'obsolete_received':row[1] is not None,'sent':sink.events, + 'fresh_control_received':'fresh-event' in sink.events})) + conn.close() +''' + + +def main(): + candidate = Path(__file__).resolve().parents[1] + base = Path(os.environ['DEMO_BASE_SOURCE']).resolve() + for mode, source in [('base', base), ('expired', candidate)]: + print('Synthetic fixture: same old firing; deliver_pending at t=10; fresh control at t=20. ' + mode, + flush=True) + subprocess.run([sys.executable, '-c', PROBE, str(source), mode], check=True) + return 0 + + +if __name__ == '__main__': + raise SystemExit(main()) diff --git a/state_key_migration.py b/state_key_migration.py index 1959833..30d3a34 100644 --- a/state_key_migration.py +++ b/state_key_migration.py @@ -65,7 +65,14 @@ def inspect(conn, plan): old, new = row(conn, emitter, source), row(conn, emitter, target) state = digest({"from": stable(old), "to": stable(new)}) conflict = None - if state != mapping["expected"]: + ledger = conn.execute("SELECT 1 FROM sqlite_master WHERE type='table' " + "AND name='outbox_dispositions'").fetchone() + disposed = ledger and conn.execute( + "SELECT 1 FROM outbox_dispositions d JOIN outbox o ON o.event_id=d.event_id " + "WHERE o.emitter=? AND o.item IN (?,?) LIMIT 1", (emitter, source, target)).fetchone() + if disposed: + conflict = "append-only disposition freezes this event identity" + elif state != mapping["expected"]: conflict = "logical state changed since reviewed dry-run" elif old is None: if new is None: diff --git a/test_outbox_disposition.py b/test_outbox_disposition.py new file mode 100644 index 0000000..2a5c814 --- /dev/null +++ b/test_outbox_disposition.py @@ -0,0 +1,299 @@ +"""Expiry is retained evidence, never a receiver acknowledgement.""" + +import json +import sqlite3 + +import pytest +import emitter as em + + +@pytest.fixture +def state(tmp_path): + conn = em.connect(tmp_path / "inbox.db") + definition = em.Emitter( + label="source", + command=[], + interval_s=5, + owner="owner", + from_verdict="NO", + to_verdict="YES", + externally_triggered=True, + ) + em.observe(conn, definition, [{"item": "item", "verdict": "NO"}], 1) + em.observe(conn, definition, [{"item": "item", "verdict": "YES", "event_id": "event"}], 2) + yield conn, definition + conn.close() + + +def plan_for(conn): + row = conn.execute("SELECT event_id FROM outbox").fetchone()[0] + return { + "schema": em.DISPOSITION_PLAN, + "emitter": "source", + "created_before": 3, + "expected_count": 1, + "reason": "obsolete backlog", + "ruling_ref": "ruling-1", + "source_utc": "2026-01-01T00:00:00Z", + "rows": [{"event_id": row, "row_sha256": em.disposition_digest(em.disposition_row(conn, row))}], + } + + +def apply(conn, plan=None): + plan = plan or plan_for(conn) + return em.apply_disposition_plan(conn, plan, em.disposition_digest(plan)) + + +class Sink: + def __init__(self): + self.sent = [] + self.setups = 0 + + def delivery_scope(self): + return {"receiver": "control"} + + def setup_pending(self): + return not self.setups + + def setup(self): + self.setups += 1 + + def deliver(self, event): + self.sent.append(event["event_id"]) + + +def test_expiry_fences_delivery_binding_setup_budget_wakeup_and_metrics(state): + conn, definition = state + before = list(conn.execute("SELECT * FROM outbox")) + plan = plan_for(conn) + apply(conn, plan) + apply(conn, plan) # lost answer is idempotent + sink = Sink() + budget = em.WriteBudget(1) + old_budget = budget._last + assert em.deliver_pending(conn, sink, 10, "source", budget) == (0, 0) + runner = em.Runner(definition, conn, sink, budget) + assert runner.delivery_due(10) is None + assert runner.setup_due(10) is None + assert runner.next_wakeup(10) == 15 + assert sink.sent == [] and sink.setups == 0 and budget._last == old_budget + assert list(conn.execute("SELECT * FROM outbox")) == before + assert runner._snapshot["pending"] == 0 and runner._snapshot["delivered"] == 0 + assert runner._snapshot["disposed"] == 1 + assert any("outbox_disposed_total" in line and line.endswith(" 1") for line in runner.metrics(str)) + assert em.verify_dispositions(conn) == 1 + # Undisposed fresh traffic remains deliverable with ordinary binding/receipt. + em.observe(conn, definition, [{"item": "fresh", "verdict": "NO"}], 11) + em.observe(conn, definition, [{"item": "fresh", "verdict": "YES", "event_id": "new"}], 12) + assert em.deliver_pending(conn, sink, 20, "source", budget) == (0, 0) # setup takes its own slot + assert em.deliver_pending(conn, sink, 21, "source", budget) == (1, 0) + assert sink.sent == ["new"] and sink.setups == 1 + assert conn.execute( + "SELECT delivered_at FROM outbox WHERE event_id=?", (plan["rows"][0]["event_id"],) + ).fetchone() == (None,) + + +def test_original_positive_control_delivers_without_ledger(state): + conn, _ = state + sink = Sink() + assert em.deliver_pending(conn, sink, 10, "source") == (1, 0) + assert sink.sent and sink.setups == 1 + assert conn.execute("SELECT attempts,delivery_scope FROM outbox").fetchone() == ( + 1, + json.dumps(sink.delivery_scope(), sort_keys=True), + ) + + +@pytest.mark.parametrize( + "change", + [ + "UPDATE outbox SET attempts=1", + "UPDATE outbox SET delivered_at=3", + "UPDATE outbox SET delivery_scope='{}'", + "UPDATE outbox SET payload='{}'", + "UPDATE outbox SET emitter='foreign'", + "UPDATE outbox SET created=999", + "UPDATE outbox SET recovery_queued=1", + ], +) +def test_changed_or_attempted_rows_refuse_without_partial_disposition(state, change): + conn, _ = state + plan = plan_for(conn) + conn.execute(change) + with pytest.raises(ValueError): + apply(conn, plan) + assert conn.execute("SELECT COUNT(*) FROM outbox_dispositions").fetchone() == (0,) + + +def test_atomic_append_rollback_and_conflicting_replay(state): + conn, _ = state + plan = plan_for(conn) + conn.execute("CREATE TEMP TRIGGER crash AFTER INSERT ON outbox_dispositions BEGIN SELECT RAISE(ABORT,'crash'); END") + with pytest.raises(sqlite3.IntegrityError): + apply(conn, plan) + assert conn.execute("SELECT COUNT(*) FROM outbox_dispositions").fetchone() == (0,) + conn.execute("DROP TRIGGER crash") + apply(conn, plan) + plan["reason"] = "different decision" + with pytest.raises(ValueError, match="conflicting"): + apply(conn, plan) + for sql in ("UPDATE outbox_dispositions SET reason=reason", "DELETE FROM outbox_dispositions"): + with pytest.raises(sqlite3.IntegrityError, match="append-only"): + conn.execute(sql) + + +def test_drift_stays_fenced_and_restart_refuses(state): + conn, _ = state + apply(conn) + conn.execute("UPDATE outbox SET payload='{}'") + assert em.deliver_pending(conn, Sink(), 10, "source") == (0, 0) + with pytest.raises(ValueError, match="changed"): + em.verify_dispositions(conn) + db = conn.execute("PRAGMA database_list").fetchone()[2] + with pytest.raises(ValueError, match="changed"): + em.connect(db) + + +def test_duplicate_foreign_recovery_and_wrong_plan_hash_refuse(state): + conn, _ = state + plan = plan_for(conn) + with pytest.raises(ValueError, match="hash"): + em.apply_disposition_plan(conn, plan, "0" * 64) + plan["rows"] *= 2 + plan["expected_count"] = 2 + with pytest.raises(ValueError, match="duplicate"): + apply(conn, plan) + conn.execute("UPDATE outbox SET payload=?", (json.dumps({"resolution_of": "prior"}),)) + with pytest.raises(ValueError, match="recovery"): + apply(conn) + + +def test_cli_plan_readonly_and_apply_requires_exclusive_custody(state, tmp_path, capsys): + from consumer_lease import ConsumerLease, ConsumerLeaseError + + conn, _ = state + db = tmp_path / "inbox.db" + cursor = tmp_path / "cursor.json" + cursor.write_text("{}") + plan = tmp_path / "plan.json" + assert ( + em.disposition_main( + [ + "plan", + "--db", + str(db), + "--plan", + str(plan), + "--emitter", + "source", + "--created-before", + "3", + "--expected-count", + "1", + "--reason", + "obsolete", + "--ruling-ref", + "ruling-1", + ] + ) + == 0 + ) + digest = json.loads(capsys.readouterr().out)["plan_sha256"] + assert conn.execute("SELECT COUNT(*) FROM outbox_dispositions").fetchone() == (0,) + args = ["apply", "--db", str(db), "--cursor", str(cursor), "--plan", str(plan), "--expected-plan-sha256", digest] + with ConsumerLease(cursor, db): + with pytest.raises(ConsumerLeaseError): + em.disposition_main(args) + assert em.disposition_main(args) == 0 + assert em.disposition_main(["verify", "--db", str(db)]) == 0 + assert conn.execute("SELECT delivered_at,attempts FROM outbox").fetchone() == (None, 0) + + +def test_extra_matching_population_refuses_every_append(state): + conn, definition = state + plan = plan_for(conn) + em.observe(conn, definition, [{"item": "extra", "verdict": "NO"}], 2) + em.observe(conn, definition, [{"item": "extra", "verdict": "YES", "event_id": "extra"}], 2.5) + with pytest.raises(ValueError, match="population"): + apply(conn, plan) + assert conn.execute("SELECT COUNT(*) FROM outbox_dispositions").fetchone() == (0,) + + +def test_successive_cli_plans_exclude_prior_receipts_and_replay_both(state, tmp_path, capsys): + conn, definition = state + first = plan_for(conn) + apply(conn, first) + apply(conn, first) + old_receipts = list(conn.execute("SELECT * FROM outbox_dispositions")) + em.observe(conn, definition, [{"item": "later", "verdict": "NO"}], 4) + em.observe(conn, definition, [{"item": "later", "verdict": "YES", "event_id": "later"}], 5) + originals = list(conn.execute("SELECT * FROM outbox ORDER BY event_id")) + output = tmp_path / "later-plan.json" + assert em.disposition_main([ + "plan", "--db", str(tmp_path / "inbox.db"), "--plan", str(output), + "--emitter", "source", "--created-before", "6", "--expected-count", "1", + "--reason", "later obsolete cohort", "--ruling-ref", "ruling-2", + ]) == 0 + capsys.readouterr() + second = json.loads(output.read_text()) + assert [entry["event_id"] for entry in second["rows"]] == ["later"] + apply(conn, second) + both_receipts = list(conn.execute("SELECT * FROM outbox_dispositions ORDER BY event_id")) + apply(conn, first) + apply(conn, second) + assert list(conn.execute("SELECT * FROM outbox ORDER BY event_id")) == originals + assert list(conn.execute("SELECT * FROM outbox_dispositions ORDER BY event_id")) == both_receipts + assert conn.execute( + "SELECT * FROM outbox_dispositions WHERE event_id=?", (first["rows"][0]["event_id"],) + ).fetchall() == old_receipts + assert em.verify_dispositions(conn) == 2 + conflicting = dict(second, reason="different ruling") + with pytest.raises(ValueError, match="conflicting"): + apply(conn, conflicting) + assert list(conn.execute("SELECT * FROM outbox_dispositions ORDER BY event_id")) == both_receipts + + +def test_readonly_first_plan_does_not_create_ledger_in_legacy_database(state, tmp_path, capsys): + conn, _ = state + conn.execute("DROP TABLE outbox_dispositions") + output = tmp_path / "legacy-plan.json" + assert em.disposition_main([ + "plan", "--db", str(tmp_path / "inbox.db"), "--plan", str(output), + "--emitter", "source", "--created-before", "3", "--expected-count", "1", + "--reason", "obsolete", "--ruling-ref", "ruling-1", + ]) == 0 + capsys.readouterr() + assert len(json.loads(output.read_text())["rows"]) == 1 + assert conn.execute("SELECT name FROM sqlite_master WHERE name='outbox_dispositions'").fetchall() == [] + + +def test_disposed_original_cannot_be_renamed_by_supported_migration(state): + import state_key_migration as migration + + conn, _ = state + apply(conn) + conn.row_factory = sqlite3.Row + old = migration.row(conn, "source", "item") + plan = { + "schema": migration.SCHEMA, + "mappings": [ + { + "emitter": "source", + "from": "item", + "to": "urn:fixture:item", + "expected": migration.digest({"from": migration.stable(old), "to": None}), + } + ], + } + report = migration.inspect(conn, plan) + assert report["conflicts"][0]["reason"] == "append-only disposition freezes this event identity" + assert em.verify_dispositions(conn) == 1 + + +def test_version_exits_before_operational_inputs(capsys): + from importlib.metadata import version + + with pytest.raises(SystemExit) as outcome: + em.disposition_main(["--version"]) + assert outcome.value.code == 0 + assert capsys.readouterr().out == "chaski-outbox-disposition " + version("chaski-reactor") + "\n"