fivefold 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (128) hide show
  1. fivefold/__init__.py +4 -0
  2. fivefold/_data/db/bootstrap.sql +26 -0
  3. fivefold/_data/db/migrations/0001_schemas.sql +67 -0
  4. fivefold/_data/db/migrations/0002_gateway.sql +224 -0
  5. fivefold/_data/db/migrations/0003_gateway_record_0010.sql +91 -0
  6. fivefold/_data/db/migrations/0004_harness.sql +141 -0
  7. fivefold/_data/db/migrations/0005_sim.sql +679 -0
  8. fivefold/_data/db/migrations/0006_gateway_reads.sql +66 -0
  9. fivefold/_data/db/migrations/0007_eval.sql +33 -0
  10. fivefold/_data/db/migrations/0008_run_stop.sql +18 -0
  11. fivefold/_data/db/migrations/0009_message_copies.sql +69 -0
  12. fivefold/_data/db/migrations/0010_gateway_g1_check.sql +14 -0
  13. fivefold/_data/db/migrations/0011_model_calls.sql +37 -0
  14. fivefold/_data/db/migrations/0012_recovery_latency.sql +23 -0
  15. fivefold/_data/db/migrations/0013_split_topology.sql +33 -0
  16. fivefold/_data/db/migrations/0014_tool_call_args.sql +20 -0
  17. fivefold/_data/db/registry/0001_registry.sql +31 -0
  18. fivefold/_data/faults/expected.yaml +406 -0
  19. fivefold/_data/scenarios/dev/dev-001-single-po.yaml +45 -0
  20. fivefold/_data/scenarios/dev/dev-002-human-approval.yaml +47 -0
  21. fivefold/agents/__init__.py +7 -0
  22. fivefold/agents/branch.py +187 -0
  23. fivefold/agents/checkpoint.py +77 -0
  24. fivefold/agents/connection.py +153 -0
  25. fivefold/agents/live.py +492 -0
  26. fivefold/agents/policy.py +426 -0
  27. fivefold/agents/remote.py +333 -0
  28. fivefold/agents/replay.py +170 -0
  29. fivefold/agents/scripted.py +122 -0
  30. fivefold/agents/tools.py +229 -0
  31. fivefold/agents/worker.py +164 -0
  32. fivefold/domain/__init__.py +5 -0
  33. fivefold/domain/api.py +517 -0
  34. fivefold/domain/authority.py +149 -0
  35. fivefold/domain/contracts.py +80 -0
  36. fivefold/domain/identity.py +113 -0
  37. fivefold/domain/prices.py +178 -0
  38. fivefold/domain/report.py +92 -0
  39. fivefold/domain/rules.py +346 -0
  40. fivefold/domain/scenario.py +524 -0
  41. fivefold/evaluator/__init__.py +155 -0
  42. fivefold/evaluator/__main__.py +127 -0
  43. fivefold/evaluator/authorization.py +146 -0
  44. fivefold/evaluator/checks.py +331 -0
  45. fivefold/evaluator/evaluate.py +109 -0
  46. fivefold/evaluator/evidence.py +392 -0
  47. fivefold/evaluator/freshness.py +136 -0
  48. fivefold/evaluator/liveness.py +236 -0
  49. fivefold/evaluator/load.py +354 -0
  50. fivefold/evaluator/metrics.py +95 -0
  51. fivefold/evaluator/records.py +452 -0
  52. fivefold/evaluator/recovery.py +209 -0
  53. fivefold/evaluator/report.py +1096 -0
  54. fivefold/evaluator/result.py +344 -0
  55. fivefold/evaluator/store.py +83 -0
  56. fivefold/faults/__init__.py +5 -0
  57. fivefold/faults/catalog.py +278 -0
  58. fivefold/faults/plan.py +538 -0
  59. fivefold/gateway/__init__.py +6 -0
  60. fivefold/gateway/admin.py +179 -0
  61. fivefold/gateway/admin_api.py +398 -0
  62. fivefold/gateway/codec.py +372 -0
  63. fivefold/gateway/destination.py +64 -0
  64. fivefold/gateway/dispatcher.py +379 -0
  65. fivefold/gateway/freshness.py +83 -0
  66. fivefold/gateway/invariants.py +761 -0
  67. fivefold/gateway/memory.py +277 -0
  68. fivefold/gateway/pg_store.py +657 -0
  69. fivefold/gateway/records.py +592 -0
  70. fivefold/gateway/server.py +102 -0
  71. fivefold/gateway/sim_client.py +295 -0
  72. fivefold/gateway/state_machine.py +376 -0
  73. fivefold/gateway/steps.py +897 -0
  74. fivefold/gateway/store.py +635 -0
  75. fivefold/gateway/tools.py +424 -0
  76. fivefold/gateway/twin.py +199 -0
  77. fivefold/gateway/wire.py +138 -0
  78. fivefold/harness/__init__.py +6 -0
  79. fivefold/harness/actors.py +230 -0
  80. fivefold/harness/cells.py +303 -0
  81. fivefold/harness/clock.py +209 -0
  82. fivefold/harness/demo.py +397 -0
  83. fivefold/harness/fault_effects.py +122 -0
  84. fivefold/harness/live_options.py +159 -0
  85. fivefold/harness/log.py +540 -0
  86. fivefold/harness/mcp_link.py +409 -0
  87. fivefold/harness/migrations.py +520 -0
  88. fivefold/harness/models.py +368 -0
  89. fivefold/harness/registry.py +105 -0
  90. fivefold/harness/reports.py +100 -0
  91. fivefold/harness/rng.py +57 -0
  92. fivefold/harness/run.py +881 -0
  93. fivefold/harness/scheduler.py +441 -0
  94. fivefold/harness/sim_points.py +215 -0
  95. fivefold/harness/split/__init__.py +34 -0
  96. fivefold/harness/split/__main__.py +275 -0
  97. fivefold/harness/split/credentials.py +74 -0
  98. fivefold/harness/split/faults.py +75 -0
  99. fivefold/harness/split/gateway.py +769 -0
  100. fivefold/harness/split/hops.py +291 -0
  101. fivefold/harness/split/lifecycle.py +322 -0
  102. fivefold/harness/split/rundir.py +152 -0
  103. fivefold/harness/split/service.py +157 -0
  104. fivefold/harness/split/simulator.py +432 -0
  105. fivefold/harness/study.py +643 -0
  106. fivefold/harness/transport.py +533 -0
  107. fivefold/paths.py +24 -0
  108. fivefold/py.typed +0 -0
  109. fivefold/recorder/__init__.py +18 -0
  110. fivefold/recorder/__main__.py +308 -0
  111. fivefold/recorder/cassette.py +322 -0
  112. fivefold/recorder/playback.py +316 -0
  113. fivefold/recorder/recording.py +133 -0
  114. fivefold/sim/__init__.py +37 -0
  115. fivefold/sim/config.py +52 -0
  116. fivefold/sim/endpoint.py +176 -0
  117. fivefold/sim/ledger.py +583 -0
  118. fivefold/sim/service.py +834 -0
  119. fivefold/viewer/__init__.py +14 -0
  120. fivefold/viewer/__main__.py +75 -0
  121. fivefold/viewer/app.py +122 -0
  122. fivefold/viewer/records.py +108 -0
  123. fivefold/viewer/source.py +196 -0
  124. fivefold/viewer/timeline.py +61 -0
  125. fivefold-0.1.0.dist-info/METADATA +169 -0
  126. fivefold-0.1.0.dist-info/RECORD +128 -0
  127. fivefold-0.1.0.dist-info/WHEEL +4 -0
  128. fivefold-0.1.0.dist-info/licenses/LICENSE +202 -0
@@ -0,0 +1,679 @@
1
+ -- The simulator's ground truth (decision records 0002, 0004, 0005, 0009).
2
+ --
3
+ -- The simulator connects as ff_sim and is the only writer here; ff_harness, ff_eval and
4
+ -- ff_viewer read; ff_gw and ff_agent have no access (0008). The service in
5
+ -- src/fivefold/sim/ decides every change and writes it in one transaction. This schema
6
+ -- also enforces, on its own, the rules a database can enforce:
7
+ --
8
+ -- - One gap-free sequence orders every simulator event. Each event takes the next
9
+ -- number from the run's counter row, and virtual time never goes back.
10
+ -- - Ground truth is never deleted: no role can DELETE or TRUNCATE a sim table, and the
11
+ -- logs (events, fact versions, reads, effects, approval events) are append-only.
12
+ -- - Fact versions run 1, 2, 3 per key, each from a later event. A version caused by an
13
+ -- effect is exactly that effect's consequence, and every effect has its consequence.
14
+ -- - An effect repeats the write it commits, commits by the write's deadline unless a
15
+ -- fault waived it, and stores the idempotency key exactly when the destination
16
+ -- honours keys. A key the destination honours commits at most once and is in flight
17
+ -- at most once.
18
+ -- - At C3, an effect cites an approval that is approved, unrevoked, unexpired and not
19
+ -- yet backing another effect. Scope and basis are checked by the service only.
20
+ -- - Writes and approvals only move forward, and what identifies them never changes.
21
+ --
22
+ -- The default privileges in 0001_schemas.sql give ff_sim SELECT, INSERT, UPDATE and
23
+ -- DELETE on every table here, and ff_harness, ff_eval and ff_viewer SELECT, as record
24
+ -- 0008's table says. Triggers, not privileges, keep ground truth from being deleted or
25
+ -- rewritten, and they apply to every role.
26
+
27
+ -- Helpers ---------------------------------------------------------------------------------
28
+
29
+ -- Whether a jsonb value is an integer.
30
+ CREATE FUNCTION sim.is_integer(value jsonb) RETURNS boolean
31
+ LANGUAGE sql IMMUTABLE AS $$
32
+ SELECT coalesce(jsonb_typeof(value) = 'number' AND (value #>> '{}') ~ '^-?[0-9]+$', false)
33
+ $$;
34
+
35
+ -- Whether a fact value has the fields of its key's kind (src/fivefold/domain/rules.py).
36
+ CREATE FUNCTION sim.fact_value_ok(key text, value jsonb) RETURNS boolean
37
+ LANGUAGE sql IMMUTABLE AS $$
38
+ SELECT coalesce(jsonb_typeof(value) = 'object' AND CASE split_part(key, '/', 1)
39
+ WHEN 'quote' THEN
40
+ sim.is_integer(value -> 'unit_price_minor')
41
+ AND jsonb_typeof(value -> 'currency') = 'string'
42
+ AND sim.is_integer(value -> 'min_quantity')
43
+ AND sim.is_integer(value -> 'lead_time_days')
44
+ AND jsonb_typeof(value -> 'status') = 'string'
45
+ WHEN 'budget' THEN
46
+ sim.is_integer(value -> 'limit_minor') AND sim.is_integer(value -> 'committed_minor')
47
+ WHEN 'inventory' THEN
48
+ sim.is_integer(value -> 'available')
49
+ WHEN 'suppliers' THEN
50
+ jsonb_typeof(value -> 'suppliers') = 'array'
51
+ ELSE false
52
+ END, false)
53
+ $$;
54
+
55
+ -- The fact a committed write changes (rules.consequence_key).
56
+ CREATE FUNCTION sim.consequence_key(operation text, args jsonb) RETURNS text
57
+ LANGUAGE sql IMMUTABLE AS $$
58
+ SELECT CASE operation
59
+ WHEN 'submit_purchase_order' THEN 'budget/' || (args ->> 'cost_center')
60
+ WHEN 'reserve_inventory' THEN
61
+ 'inventory/' || (args ->> 'warehouse_id') || '/' || (args ->> 'sku')
62
+ END
63
+ $$;
64
+
65
+ -- The new value of that fact (rules.consequence): an order adds its amount to the
66
+ -- budget's committed amount; a reservation takes its quantity from available stock.
67
+ CREATE FUNCTION sim.consequence_value(operation text, args jsonb, current jsonb) RETURNS jsonb
68
+ LANGUAGE sql IMMUTABLE AS $$
69
+ SELECT CASE operation
70
+ WHEN 'submit_purchase_order' THEN current || jsonb_build_object('committed_minor',
71
+ (current ->> 'committed_minor')::numeric
72
+ + (args ->> 'quantity')::numeric * (args ->> 'unit_price_minor')::numeric)
73
+ WHEN 'reserve_inventory' THEN current || jsonb_build_object('available',
74
+ (current ->> 'available')::numeric - (args ->> 'quantity')::numeric)
75
+ END
76
+ $$;
77
+
78
+ CREATE FUNCTION sim.reject_change() RETURNS trigger LANGUAGE plpgsql AS $$
79
+ BEGIN
80
+ RAISE EXCEPTION 'sim.% is ground truth: % refused', TG_TABLE_NAME, TG_OP;
81
+ END
82
+ $$;
83
+
84
+ -- The run ---------------------------------------------------------------------------------
85
+
86
+ -- One row per run database: the destination's configuration, set once at setup, and the
87
+ -- counters that number events and ids. Every simulator transaction locks this row
88
+ -- first, so the simulator handles one request at a time (0004).
89
+ CREATE TABLE sim.run (
90
+ singleton boolean PRIMARY KEY DEFAULT true CHECK (singleton),
91
+ scenario_id text NOT NULL,
92
+ task_id text NOT NULL,
93
+ capabilities text[] NOT NULL
94
+ CHECK (capabilities <@ ARRAY['status', 'idempotency_key', 'conditional_write']),
95
+ max_hop_latency_ms bigint NOT NULL CHECK (max_hop_latency_ms > 0),
96
+ commit_deadline_ms bigint NOT NULL CHECK (commit_deadline_ms > 0),
97
+ status_lag_ms bigint NOT NULL CHECK (status_lag_ms >= 0),
98
+ credentials text[] NOT NULL CHECK (cardinality(credentials) >= 1),
99
+ authority jsonb NOT NULL CHECK (sim.is_integer(authority -> 'approval_ttl_ms')),
100
+ last_seq bigint NOT NULL DEFAULT 0 CHECK (last_seq >= 0),
101
+ last_vt bigint NOT NULL DEFAULT 0 CHECK (last_vt >= 0),
102
+ last_po_no bigint NOT NULL DEFAULT 0 CHECK (last_po_no >= 0),
103
+ last_rs_no bigint NOT NULL DEFAULT 0 CHECK (last_rs_no >= 0),
104
+ last_apr_no bigint NOT NULL DEFAULT 0 CHECK (last_apr_no >= 0)
105
+ );
106
+
107
+ -- The configuration never changes, counters never go back, and only a new event (whose
108
+ -- trigger runs one level down) moves the sequence and the clock.
109
+ CREATE FUNCTION sim.keep_run() RETURNS trigger LANGUAGE plpgsql AS $$
110
+ BEGIN
111
+ IF (NEW.singleton, NEW.scenario_id, NEW.task_id, NEW.capabilities,
112
+ NEW.max_hop_latency_ms, NEW.commit_deadline_ms, NEW.status_lag_ms, NEW.credentials,
113
+ NEW.authority)
114
+ IS DISTINCT FROM
115
+ (OLD.singleton, OLD.scenario_id, OLD.task_id, OLD.capabilities,
116
+ OLD.max_hop_latency_ms, OLD.commit_deadline_ms, OLD.status_lag_ms, OLD.credentials,
117
+ OLD.authority)
118
+ THEN
119
+ RAISE EXCEPTION 'the run''s configuration never changes';
120
+ END IF;
121
+ IF NEW.last_po_no < OLD.last_po_no OR NEW.last_rs_no < OLD.last_rs_no
122
+ OR NEW.last_apr_no < OLD.last_apr_no
123
+ THEN
124
+ RAISE EXCEPTION 'the run''s id counters never go back';
125
+ END IF;
126
+ IF (NEW.last_seq, NEW.last_vt) IS DISTINCT FROM (OLD.last_seq, OLD.last_vt)
127
+ AND pg_trigger_depth() < 2
128
+ THEN
129
+ RAISE EXCEPTION 'only a new event moves the sequence and the clock';
130
+ END IF;
131
+ RETURN NEW;
132
+ END
133
+ $$;
134
+
135
+ CREATE TRIGGER run_keeps_its_configuration BEFORE UPDATE ON sim.run
136
+ FOR EACH ROW EXECUTE FUNCTION sim.keep_run();
137
+
138
+ -- Events ----------------------------------------------------------------------------------
139
+
140
+ -- Every simulator event, in the order the gap-free sequence gives (0004). A row's seq is
141
+ -- assigned here: the run's last seq plus one. Other tables refer to these rows.
142
+ CREATE TABLE sim.event (
143
+ seq bigint PRIMARY KEY CHECK (seq >= 1),
144
+ vt bigint NOT NULL CHECK (vt >= 0),
145
+ kind text NOT NULL CHECK (kind IN (
146
+ 'setup', 'read', 'fact_changed',
147
+ 'write_received', 'write_committed', 'write_replayed', 'write_in_progress',
148
+ 'write_rejected', 'write_aborted',
149
+ 'approval_requested', 'approval_repeated', 'approval_approved', 'approval_denied',
150
+ 'approval_revoked', 'approval_status', 'status'
151
+ )),
152
+ actor text NOT NULL,
153
+ ref text,
154
+ -- Wall-clock time, for metrics only; never used for decisions (0009).
155
+ wall_at timestamptz NOT NULL DEFAULT now()
156
+ );
157
+
158
+ CREATE FUNCTION sim.next_event() RETURNS trigger LANGUAGE plpgsql AS $$
159
+ DECLARE
160
+ run sim.run;
161
+ BEGIN
162
+ SELECT * INTO run FROM sim.run FOR UPDATE;
163
+ IF NOT FOUND THEN
164
+ RAISE EXCEPTION 'the run is not set up';
165
+ END IF;
166
+ IF NEW.seq IS NOT NULL AND NEW.seq <> run.last_seq + 1 THEN
167
+ RAISE EXCEPTION 'event % would leave a gap after %', NEW.seq, run.last_seq;
168
+ END IF;
169
+ IF NEW.vt < run.last_vt THEN
170
+ RAISE EXCEPTION 'virtual time went back from % to %', run.last_vt, NEW.vt;
171
+ END IF;
172
+ NEW.seq := run.last_seq + 1;
173
+ UPDATE sim.run SET last_seq = NEW.seq, last_vt = NEW.vt;
174
+ RETURN NEW;
175
+ END
176
+ $$;
177
+
178
+ CREATE TRIGGER event_takes_the_next_seq BEFORE INSERT ON sim.event
179
+ FOR EACH ROW EXECUTE FUNCTION sim.next_event();
180
+
181
+ -- Raise unless event `seq` exists with this kind and virtual time (and actor, if given).
182
+ CREATE FUNCTION sim.require_event(seq bigint, kinds text[], vt bigint, actor text)
183
+ RETURNS void LANGUAGE plpgsql AS $$
184
+ DECLARE
185
+ hit sim.event;
186
+ BEGIN
187
+ SELECT * INTO hit FROM sim.event WHERE event.seq = require_event.seq;
188
+ IF NOT FOUND OR NOT hit.kind = ANY(require_event.kinds)
189
+ OR hit.vt IS DISTINCT FROM require_event.vt
190
+ OR (require_event.actor IS NOT NULL AND hit.actor IS DISTINCT FROM require_event.actor)
191
+ THEN
192
+ RAISE EXCEPTION 'event % is not a % event at % by %', require_event.seq,
193
+ require_event.kinds, require_event.vt, require_event.actor;
194
+ END IF;
195
+ END
196
+ $$;
197
+
198
+ -- Facts -----------------------------------------------------------------------------------
199
+
200
+ -- The full history of quotes, budgets, stock and the supplier directory (0004). Every
201
+ -- fact starts at version 1 from the scenario; every change appends a version with its
202
+ -- cause: a committed effect, or a change through the control interface (faults F7).
203
+ CREATE TABLE sim.fact_version (
204
+ key text NOT NULL CHECK (key ~ (
205
+ '^(quote/[A-Za-z0-9][A-Za-z0-9._-]{0,63}/[A-Za-z0-9][A-Za-z0-9._-]{0,63}'
206
+ '|budget/[A-Za-z0-9][A-Za-z0-9._-]{0,63}'
207
+ '|inventory/[A-Za-z0-9][A-Za-z0-9._-]{0,63}/[A-Za-z0-9][A-Za-z0-9._-]{0,63}'
208
+ '|suppliers)$'
209
+ )),
210
+ version bigint NOT NULL CHECK (version >= 1),
211
+ value jsonb NOT NULL,
212
+ valid_from_seq bigint NOT NULL REFERENCES sim.event (seq),
213
+ valid_from_vt bigint NOT NULL,
214
+ cause text NOT NULL CHECK (cause IN ('initial', 'effect', 'control')),
215
+ cause_effect_id text,
216
+ cause_actor text,
217
+ PRIMARY KEY (key, version),
218
+ CONSTRAINT fact_value_fits_its_kind CHECK (sim.fact_value_ok(key, value)),
219
+ CONSTRAINT fact_versions_start_from_the_scenario CHECK ((cause = 'initial') = (version = 1)),
220
+ CONSTRAINT fact_cause_is_named CHECK (
221
+ (cause = 'effect') = (cause_effect_id IS NOT NULL)
222
+ AND (cause = 'control') = (cause_actor IS NOT NULL)
223
+ )
224
+ );
225
+
226
+ -- Every read served: the fact's version at that moment, and who asked (0004).
227
+ CREATE TABLE sim.read_log (
228
+ seq bigint PRIMARY KEY REFERENCES sim.event (seq),
229
+ key text NOT NULL,
230
+ version bigint NOT NULL,
231
+ caller text NOT NULL,
232
+ vt bigint NOT NULL,
233
+ FOREIGN KEY (key, version) REFERENCES sim.fact_version (key, version)
234
+ );
235
+
236
+ -- A read serves the latest version.
237
+ CREATE FUNCTION sim.check_read() RETURNS trigger LANGUAGE plpgsql AS $$
238
+ BEGIN
239
+ PERFORM sim.require_event(NEW.seq, ARRAY['read'], NEW.vt, NEW.caller);
240
+ IF NEW.version IS DISTINCT FROM
241
+ (SELECT max(version) FROM sim.fact_version WHERE key = NEW.key)
242
+ THEN
243
+ RAISE EXCEPTION 'a read of % must serve its latest version', NEW.key;
244
+ END IF;
245
+ RETURN NEW;
246
+ END
247
+ $$;
248
+
249
+ CREATE TRIGGER read_serves_the_latest_version BEFORE INSERT ON sim.read_log
250
+ FOR EACH ROW EXECUTE FUNCTION sim.check_read();
251
+
252
+ -- Writes ----------------------------------------------------------------------------------
253
+
254
+ -- Every write request that reached the destination, and its outcome. A write in state
255
+ -- `received` is in flight: it commits only by its deadline, its arrival plus D, unless a
256
+ -- fault waived the deadline (F5 beyond the deadline, a contract violation). Otherwise it
257
+ -- is aborted and never commits (0005). `key_honoured` says whether the destination stores
258
+ -- and enforces the write's idempotency key.
259
+ CREATE TABLE sim.write (
260
+ received_seq bigint PRIMARY KEY REFERENCES sim.event (seq),
261
+ received_vt bigint NOT NULL,
262
+ caller text NOT NULL,
263
+ operation text NOT NULL CHECK (operation IN ('submit_purchase_order', 'reserve_inventory')),
264
+ intent_id text NOT NULL,
265
+ approval_id text NOT NULL,
266
+ args jsonb NOT NULL CHECK (jsonb_typeof(args) = 'object'),
267
+ basis jsonb NOT NULL CHECK (jsonb_typeof(basis) = 'object'),
268
+ idempotency_key text,
269
+ key_honoured boolean NOT NULL,
270
+ client_ref text,
271
+ deadline_vt bigint NOT NULL,
272
+ deadline_waived boolean NOT NULL,
273
+ state text NOT NULL CHECK (state IN (
274
+ 'received', 'committed', 'replayed', 'in_progress', 'rejected', 'aborted'
275
+ )),
276
+ outcome_seq bigint UNIQUE REFERENCES sim.event (seq),
277
+ outcome_vt bigint,
278
+ effect_id text,
279
+ rejection jsonb,
280
+ CONSTRAINT write_outcome_recorded CHECK (
281
+ (state = 'received') = (outcome_seq IS NULL)
282
+ AND (outcome_seq IS NULL) = (outcome_vt IS NULL)
283
+ ),
284
+ CONSTRAINT write_outcome_after_receipt CHECK (outcome_seq > received_seq),
285
+ CONSTRAINT write_effect_when_committed
286
+ CHECK ((state IN ('committed', 'replayed')) = (effect_id IS NOT NULL)),
287
+ CONSTRAINT write_rejection_when_rejected CHECK ((state = 'rejected') = (rejection IS NOT NULL)),
288
+ CONSTRAINT write_key_honoured_needs_a_key
289
+ CHECK (NOT key_honoured OR idempotency_key IS NOT NULL)
290
+ );
291
+
292
+ -- A key the destination honours is in flight at most once (0005).
293
+ CREATE UNIQUE INDEX write_key_in_flight_once ON sim.write (idempotency_key)
294
+ WHERE key_honoured AND state = 'received';
295
+
296
+ CREATE INDEX write_in_flight_by_deadline ON sim.write (deadline_vt) WHERE state = 'received';
297
+
298
+ -- Every committed write: the effects ledger (0004). One committed write is one effect.
299
+ CREATE TABLE sim.effect (
300
+ effect_id text PRIMARY KEY,
301
+ intent_id text NOT NULL,
302
+ operation text NOT NULL CHECK (operation IN ('submit_purchase_order', 'reserve_inventory')),
303
+ args jsonb NOT NULL,
304
+ approval_id text NOT NULL,
305
+ basis jsonb NOT NULL,
306
+ idempotency_key text UNIQUE,
307
+ client_ref text,
308
+ received_seq bigint NOT NULL UNIQUE REFERENCES sim.write (received_seq),
309
+ commit_seq bigint NOT NULL UNIQUE REFERENCES sim.event (seq),
310
+ committed_vt bigint NOT NULL,
311
+ CONSTRAINT effect_id_names_its_operation CHECK (
312
+ (operation = 'submit_purchase_order' AND effect_id ~ '^PO-[0-9]{4,}$')
313
+ OR (operation = 'reserve_inventory' AND effect_id ~ '^RS-[0-9]{4,}$')
314
+ ),
315
+ CONSTRAINT effect_commits_after_receipt CHECK (commit_seq > received_seq)
316
+ );
317
+
318
+ CREATE INDEX effect_by_intent ON sim.effect (intent_id, operation, commit_seq);
319
+ CREATE INDEX effect_by_approval ON sim.effect (approval_id);
320
+
321
+ ALTER TABLE sim.write ADD CONSTRAINT write_effect_exists
322
+ FOREIGN KEY (effect_id) REFERENCES sim.effect (effect_id);
323
+ ALTER TABLE sim.fact_version ADD CONSTRAINT fact_version_cause_exists
324
+ FOREIGN KEY (cause_effect_id) REFERENCES sim.effect (effect_id);
325
+ CREATE INDEX fact_version_by_effect ON sim.fact_version (cause_effect_id)
326
+ WHERE cause_effect_id IS NOT NULL;
327
+
328
+ -- Approvals -------------------------------------------------------------------------------
329
+
330
+ -- The authority record (0002). `status` is stored as pending, approved, denied or
331
+ -- revoked; an approved approval is expired from `expires_at` on, which needs no row
332
+ -- change. `effect_id` is the effect the approval backs: the first to cite it (rule 10).
333
+ CREATE TABLE sim.approval (
334
+ approval_id text PRIMARY KEY CHECK (approval_id ~ '^APR-[0-9]{4,}$'),
335
+ intent_id text NOT NULL,
336
+ operation text NOT NULL CHECK (operation IN ('submit_purchase_order', 'reserve_inventory')),
337
+ scope jsonb NOT NULL CHECK (jsonb_typeof(scope) = 'object'),
338
+ client_request_key text UNIQUE,
339
+ requester text NOT NULL,
340
+ requested_seq bigint NOT NULL UNIQUE REFERENCES sim.event (seq),
341
+ requested_vt bigint NOT NULL,
342
+ status text NOT NULL CHECK (status IN ('pending', 'approved', 'denied', 'revoked')),
343
+ decided_seq bigint UNIQUE REFERENCES sim.event (seq),
344
+ decided_vt bigint,
345
+ decided_by text,
346
+ expires_at bigint,
347
+ revoked_seq bigint UNIQUE REFERENCES sim.event (seq),
348
+ revoked_vt bigint,
349
+ revoked_by text,
350
+ effect_id text UNIQUE REFERENCES sim.effect (effect_id),
351
+ CONSTRAINT approval_decision_recorded CHECK (
352
+ (status = 'pending') = (decided_seq IS NULL)
353
+ AND (decided_seq IS NULL) = (decided_vt IS NULL)
354
+ AND (decided_seq IS NULL) = (decided_by IS NULL)
355
+ ),
356
+ CONSTRAINT approval_expiry_when_approved
357
+ CHECK ((status IN ('approved', 'revoked')) = (expires_at IS NOT NULL)),
358
+ CONSTRAINT approval_revocation_recorded CHECK (
359
+ (status = 'revoked') = (revoked_seq IS NOT NULL)
360
+ AND (revoked_seq IS NULL) = (revoked_vt IS NULL)
361
+ AND (revoked_seq IS NULL) = (revoked_by IS NULL)
362
+ )
363
+ );
364
+
365
+ -- Every change to an approval: requested, approved, denied, revoked (0002, rule 9).
366
+ CREATE TABLE sim.approval_event (
367
+ seq bigint PRIMARY KEY REFERENCES sim.event (seq),
368
+ approval_id text NOT NULL REFERENCES sim.approval (approval_id),
369
+ kind text NOT NULL CHECK (kind IN ('requested', 'approved', 'denied', 'revoked')),
370
+ actor text NOT NULL,
371
+ vt bigint NOT NULL
372
+ );
373
+
374
+ CREATE FUNCTION sim.check_approval_event() RETURNS trigger LANGUAGE plpgsql AS $$
375
+ BEGIN
376
+ PERFORM sim.require_event(NEW.seq, ARRAY['approval_' || NEW.kind], NEW.vt, NEW.actor);
377
+ RETURN NEW;
378
+ END
379
+ $$;
380
+
381
+ CREATE TRIGGER approval_event_matches_its_event BEFORE INSERT ON sim.approval_event
382
+ FOR EACH ROW EXECUTE FUNCTION sim.check_approval_event();
383
+
384
+ -- An approval is filed pending. It then moves only from pending to approved or denied,
385
+ -- and from approved to revoked, each move recorded by its approval event; an approval
386
+ -- expires `approval_ttl_ms` after its decision. Its request never changes, and it backs
387
+ -- at most one effect, which must cite it.
388
+ CREATE FUNCTION sim.keep_approval() RETURNS trigger LANGUAGE plpgsql AS $$
389
+ DECLARE
390
+ ttl bigint;
391
+ BEGIN
392
+ IF TG_OP = 'INSERT' THEN
393
+ IF NEW.status <> 'pending' OR NEW.effect_id IS NOT NULL THEN
394
+ RAISE EXCEPTION 'approval % must be filed pending', NEW.approval_id;
395
+ END IF;
396
+ PERFORM sim.require_event(NEW.requested_seq, ARRAY['approval_requested'],
397
+ NEW.requested_vt, NEW.requester);
398
+ RETURN NEW;
399
+ END IF;
400
+ IF (NEW.approval_id, NEW.intent_id, NEW.operation, NEW.scope, NEW.client_request_key,
401
+ NEW.requester, NEW.requested_seq, NEW.requested_vt)
402
+ IS DISTINCT FROM
403
+ (OLD.approval_id, OLD.intent_id, OLD.operation, OLD.scope, OLD.client_request_key,
404
+ OLD.requester, OLD.requested_seq, OLD.requested_vt)
405
+ THEN
406
+ RAISE EXCEPTION 'the request of approval % never changes', OLD.approval_id;
407
+ END IF;
408
+ IF NEW.status IS DISTINCT FROM OLD.status
409
+ AND NOT (OLD.status = 'pending' AND NEW.status IN ('approved', 'denied'))
410
+ AND NOT (OLD.status = 'approved' AND NEW.status = 'revoked')
411
+ THEN
412
+ RAISE EXCEPTION 'approval % cannot move from % to %',
413
+ OLD.approval_id, OLD.status, NEW.status;
414
+ END IF;
415
+ IF OLD.decided_seq IS NOT NULL
416
+ AND (NEW.decided_seq, NEW.decided_vt, NEW.decided_by, NEW.expires_at)
417
+ IS DISTINCT FROM (OLD.decided_seq, OLD.decided_vt, OLD.decided_by, OLD.expires_at)
418
+ THEN
419
+ RAISE EXCEPTION 'the decision on approval % never changes', OLD.approval_id;
420
+ END IF;
421
+ IF OLD.decided_seq IS NULL AND NEW.decided_seq IS NOT NULL THEN
422
+ IF NOT EXISTS (
423
+ SELECT 1 FROM sim.approval_event
424
+ WHERE seq = NEW.decided_seq AND approval_id = NEW.approval_id
425
+ AND kind = CASE NEW.status WHEN 'denied' THEN 'denied' ELSE 'approved' END
426
+ AND vt = NEW.decided_vt AND actor = NEW.decided_by
427
+ ) THEN
428
+ RAISE EXCEPTION 'the decision on approval % has no matching event', NEW.approval_id;
429
+ END IF;
430
+ SELECT (authority ->> 'approval_ttl_ms')::bigint INTO ttl FROM sim.run;
431
+ IF NEW.status = 'approved' AND NEW.expires_at IS DISTINCT FROM NEW.decided_vt + ttl THEN
432
+ RAISE EXCEPTION 'approval % must expire % ms after its decision',
433
+ NEW.approval_id, ttl;
434
+ END IF;
435
+ END IF;
436
+ IF OLD.revoked_seq IS NOT NULL
437
+ AND (NEW.revoked_seq, NEW.revoked_vt, NEW.revoked_by)
438
+ IS DISTINCT FROM (OLD.revoked_seq, OLD.revoked_vt, OLD.revoked_by)
439
+ THEN
440
+ RAISE EXCEPTION 'the revocation of approval % never changes', OLD.approval_id;
441
+ END IF;
442
+ IF OLD.revoked_seq IS NULL AND NEW.revoked_seq IS NOT NULL AND NOT EXISTS (
443
+ SELECT 1 FROM sim.approval_event
444
+ WHERE seq = NEW.revoked_seq AND approval_id = NEW.approval_id AND kind = 'revoked'
445
+ AND vt = NEW.revoked_vt AND actor = NEW.revoked_by
446
+ ) THEN
447
+ RAISE EXCEPTION 'the revocation of approval % has no matching event', NEW.approval_id;
448
+ END IF;
449
+ IF NEW.effect_id IS DISTINCT FROM OLD.effect_id THEN
450
+ IF OLD.effect_id IS NOT NULL OR NOT EXISTS (
451
+ SELECT 1 FROM sim.effect
452
+ WHERE effect_id = NEW.effect_id AND approval_id = NEW.approval_id
453
+ ) THEN
454
+ RAISE EXCEPTION 'approval % backs its first citing effect, once', NEW.approval_id;
455
+ END IF;
456
+ END IF;
457
+ RETURN NEW;
458
+ END
459
+ $$;
460
+
461
+ CREATE TRIGGER approval_moves_forward BEFORE INSERT OR UPDATE ON sim.approval
462
+ FOR EACH ROW EXECUTE FUNCTION sim.keep_approval();
463
+
464
+ -- Fact version rules ----------------------------------------------------------------------
465
+
466
+ CREATE FUNCTION sim.check_fact_version() RETURNS trigger LANGUAGE plpgsql AS $$
467
+ DECLARE
468
+ previous sim.fact_version;
469
+ source sim.effect;
470
+ BEGIN
471
+ PERFORM sim.require_event(NEW.valid_from_seq,
472
+ CASE NEW.cause
473
+ WHEN 'initial' THEN ARRAY['setup']
474
+ WHEN 'effect' THEN ARRAY['write_committed']
475
+ ELSE ARRAY['fact_changed']
476
+ END,
477
+ NEW.valid_from_vt, NEW.cause_actor);
478
+ SELECT * INTO previous FROM sim.fact_version
479
+ WHERE key = NEW.key ORDER BY version DESC LIMIT 1;
480
+ IF FOUND THEN
481
+ IF NEW.version <> previous.version + 1 OR NEW.valid_from_seq <= previous.valid_from_seq
482
+ THEN
483
+ RAISE EXCEPTION 'version % of % must follow version % from a later event',
484
+ NEW.version, NEW.key, previous.version;
485
+ END IF;
486
+ ELSIF NEW.version <> 1 THEN
487
+ RAISE EXCEPTION 'the first version of % must be 1', NEW.key;
488
+ END IF;
489
+ IF NEW.cause = 'effect' THEN
490
+ SELECT * INTO source FROM sim.effect WHERE effect_id = NEW.cause_effect_id;
491
+ IF NOT FOUND OR previous IS NULL
492
+ OR NEW.valid_from_seq <> source.commit_seq
493
+ OR NEW.key IS DISTINCT FROM sim.consequence_key(source.operation, source.args)
494
+ OR NEW.value IS DISTINCT FROM
495
+ sim.consequence_value(source.operation, source.args, previous.value)
496
+ THEN
497
+ RAISE EXCEPTION 'version % of % is not the consequence of effect %',
498
+ NEW.version, NEW.key, NEW.cause_effect_id;
499
+ END IF;
500
+ END IF;
501
+ RETURN NEW;
502
+ END
503
+ $$;
504
+
505
+ CREATE TRIGGER fact_version_follows_history BEFORE INSERT ON sim.fact_version
506
+ FOR EACH ROW EXECUTE FUNCTION sim.check_fact_version();
507
+
508
+ -- Write and effect rules ------------------------------------------------------------------
509
+
510
+ -- A write is received in flight, or decided at once (replayed, in progress, rejected).
511
+ -- It then moves only from `received` to an outcome, recorded by an event of that kind,
512
+ -- and what it asked for never changes. Its deadline is its arrival plus D, and it keeps
513
+ -- its idempotency key exactly when the destination has the idempotency_key capability.
514
+ CREATE FUNCTION sim.keep_write() RETURNS trigger LANGUAGE plpgsql AS $$
515
+ DECLARE
516
+ run sim.run;
517
+ BEGIN
518
+ IF TG_OP = 'INSERT' THEN
519
+ SELECT * INTO run FROM sim.run;
520
+ PERFORM sim.require_event(NEW.received_seq, ARRAY['write_received'],
521
+ NEW.received_vt, NEW.caller);
522
+ IF NEW.deadline_vt <> NEW.received_vt + run.commit_deadline_ms
523
+ OR NEW.key_honoured IS DISTINCT FROM
524
+ ('idempotency_key' = ANY(run.capabilities) AND NEW.idempotency_key IS NOT NULL)
525
+ THEN
526
+ RAISE EXCEPTION 'write % breaks the destination''s deadline or key rules',
527
+ NEW.received_seq;
528
+ END IF;
529
+ IF NEW.state = 'committed' OR NEW.state = 'aborted' THEN
530
+ RAISE EXCEPTION 'write % must be received before it commits or aborts',
531
+ NEW.received_seq;
532
+ END IF;
533
+ ELSE
534
+ IF (NEW.received_seq, NEW.received_vt, NEW.caller, NEW.operation, NEW.intent_id,
535
+ NEW.approval_id, NEW.args, NEW.basis, NEW.idempotency_key, NEW.key_honoured,
536
+ NEW.client_ref, NEW.deadline_vt, NEW.deadline_waived)
537
+ IS DISTINCT FROM
538
+ (OLD.received_seq, OLD.received_vt, OLD.caller, OLD.operation, OLD.intent_id,
539
+ OLD.approval_id, OLD.args, OLD.basis, OLD.idempotency_key, OLD.key_honoured,
540
+ OLD.client_ref, OLD.deadline_vt, OLD.deadline_waived)
541
+ THEN
542
+ RAISE EXCEPTION 'write % never changes what it asked for', OLD.received_seq;
543
+ END IF;
544
+ IF OLD.state <> 'received' OR NEW.state = 'received' THEN
545
+ RAISE EXCEPTION 'write % has its outcome already', OLD.received_seq;
546
+ END IF;
547
+ END IF;
548
+ IF NEW.state = 'received' THEN
549
+ RETURN NEW;
550
+ END IF;
551
+ PERFORM sim.require_event(NEW.outcome_seq, ARRAY['write_' || NEW.state], NEW.outcome_vt,
552
+ NULL);
553
+ IF NEW.state = 'committed' AND NOT EXISTS (
554
+ SELECT 1 FROM sim.effect
555
+ WHERE effect_id = NEW.effect_id AND received_seq = NEW.received_seq
556
+ AND commit_seq = NEW.outcome_seq
557
+ ) THEN
558
+ RAISE EXCEPTION 'write % commits as its own effect', NEW.received_seq;
559
+ END IF;
560
+ IF NEW.state = 'replayed' AND NOT (NEW.key_honoured AND EXISTS (
561
+ SELECT 1 FROM sim.effect
562
+ WHERE effect_id = NEW.effect_id AND idempotency_key = NEW.idempotency_key
563
+ )) THEN
564
+ RAISE EXCEPTION 'write % replays only the effect of its own key', NEW.received_seq;
565
+ END IF;
566
+ IF NEW.state = 'in_progress' AND NOT (NEW.key_honoured AND EXISTS (
567
+ SELECT 1 FROM sim.write
568
+ WHERE idempotency_key = NEW.idempotency_key AND key_honoured AND state = 'received'
569
+ AND received_seq <> NEW.received_seq
570
+ )) THEN
571
+ RAISE EXCEPTION 'write % is in progress only while its key is in flight',
572
+ NEW.received_seq;
573
+ END IF;
574
+ IF NEW.state = 'aborted' AND (NEW.deadline_waived OR NEW.outcome_vt <= NEW.deadline_vt)
575
+ THEN
576
+ RAISE EXCEPTION 'write % aborts only after its deadline', NEW.received_seq;
577
+ END IF;
578
+ RETURN NEW;
579
+ END
580
+ $$;
581
+
582
+ CREATE TRIGGER write_moves_forward BEFORE INSERT OR UPDATE ON sim.write
583
+ FOR EACH ROW EXECUTE FUNCTION sim.keep_write();
584
+
585
+ -- An effect repeats its write, which is in flight, and commits by the write's deadline
586
+ -- unless a fault waived it. It keeps the write's key exactly when the destination honours
587
+ -- it. At C3 its approval is approved, unrevoked, unexpired and backs no effect yet.
588
+ CREATE FUNCTION sim.check_effect() RETURNS trigger LANGUAGE plpgsql AS $$
589
+ DECLARE
590
+ request sim.write;
591
+ run sim.run;
592
+ cited sim.approval;
593
+ BEGIN
594
+ SELECT * INTO run FROM sim.run;
595
+ SELECT * INTO request FROM sim.write WHERE received_seq = NEW.received_seq;
596
+ IF NOT FOUND OR request.state <> 'received'
597
+ OR (NEW.intent_id, NEW.operation, NEW.args, NEW.approval_id, NEW.basis, NEW.client_ref)
598
+ IS DISTINCT FROM
599
+ (request.intent_id, request.operation, request.args, request.approval_id,
600
+ request.basis, request.client_ref)
601
+ OR NEW.idempotency_key IS DISTINCT FROM
602
+ (CASE WHEN request.key_honoured THEN request.idempotency_key END)
603
+ THEN
604
+ RAISE EXCEPTION 'effect % does not repeat the write it commits', NEW.effect_id;
605
+ END IF;
606
+ PERFORM sim.require_event(NEW.commit_seq, ARRAY['write_committed'], NEW.committed_vt, NULL);
607
+ IF NEW.committed_vt > request.deadline_vt AND NOT request.deadline_waived THEN
608
+ RAISE EXCEPTION 'effect % commits after its deadline', NEW.effect_id;
609
+ END IF;
610
+ IF 'conditional_write' = ANY(run.capabilities) THEN
611
+ SELECT * INTO cited FROM sim.approval WHERE approval_id = NEW.approval_id;
612
+ IF NOT FOUND OR cited.status <> 'approved' OR cited.expires_at <= NEW.committed_vt
613
+ OR cited.effect_id IS NOT NULL
614
+ THEN
615
+ RAISE EXCEPTION 'at C3, effect % needs a valid unused approval', NEW.effect_id;
616
+ END IF;
617
+ END IF;
618
+ RETURN NEW;
619
+ END
620
+ $$;
621
+
622
+ CREATE TRIGGER effect_repeats_its_write BEFORE INSERT ON sim.effect
623
+ FOR EACH ROW EXECUTE FUNCTION sim.check_effect();
624
+
625
+ -- By the end of its transaction, an effect has its consequence and its write is committed.
626
+ CREATE FUNCTION sim.effect_is_complete() RETURNS trigger LANGUAGE plpgsql AS $$
627
+ BEGIN
628
+ IF NOT EXISTS (SELECT 1 FROM sim.fact_version WHERE cause_effect_id = NEW.effect_id)
629
+ OR NOT EXISTS (
630
+ SELECT 1 FROM sim.write
631
+ WHERE received_seq = NEW.received_seq AND state = 'committed'
632
+ AND effect_id = NEW.effect_id
633
+ )
634
+ THEN
635
+ RAISE EXCEPTION 'effect % needs its consequence and its committed write', NEW.effect_id;
636
+ END IF;
637
+ RETURN NULL;
638
+ END
639
+ $$;
640
+
641
+ CREATE CONSTRAINT TRIGGER effect_is_complete AFTER INSERT ON sim.effect
642
+ DEFERRABLE INITIALLY DEFERRED
643
+ FOR EACH ROW EXECUTE FUNCTION sim.effect_is_complete();
644
+
645
+ -- Ground truth is never deleted -----------------------------------------------------------
646
+
647
+ CREATE TRIGGER event_is_append_only BEFORE UPDATE OR DELETE ON sim.event
648
+ FOR EACH ROW EXECUTE FUNCTION sim.reject_change();
649
+ CREATE TRIGGER fact_version_is_append_only BEFORE UPDATE OR DELETE ON sim.fact_version
650
+ FOR EACH ROW EXECUTE FUNCTION sim.reject_change();
651
+ CREATE TRIGGER read_log_is_append_only BEFORE UPDATE OR DELETE ON sim.read_log
652
+ FOR EACH ROW EXECUTE FUNCTION sim.reject_change();
653
+ CREATE TRIGGER effect_is_append_only BEFORE UPDATE OR DELETE ON sim.effect
654
+ FOR EACH ROW EXECUTE FUNCTION sim.reject_change();
655
+ CREATE TRIGGER approval_event_is_append_only BEFORE UPDATE OR DELETE ON sim.approval_event
656
+ FOR EACH ROW EXECUTE FUNCTION sim.reject_change();
657
+ CREATE TRIGGER run_is_never_deleted BEFORE DELETE ON sim.run
658
+ FOR EACH ROW EXECUTE FUNCTION sim.reject_change();
659
+ CREATE TRIGGER write_is_never_deleted BEFORE DELETE ON sim.write
660
+ FOR EACH ROW EXECUTE FUNCTION sim.reject_change();
661
+ CREATE TRIGGER approval_is_never_deleted BEFORE DELETE ON sim.approval
662
+ FOR EACH ROW EXECUTE FUNCTION sim.reject_change();
663
+
664
+ CREATE TRIGGER run_is_never_truncated BEFORE TRUNCATE ON sim.run
665
+ FOR EACH STATEMENT EXECUTE FUNCTION sim.reject_change();
666
+ CREATE TRIGGER event_is_never_truncated BEFORE TRUNCATE ON sim.event
667
+ FOR EACH STATEMENT EXECUTE FUNCTION sim.reject_change();
668
+ CREATE TRIGGER fact_version_is_never_truncated BEFORE TRUNCATE ON sim.fact_version
669
+ FOR EACH STATEMENT EXECUTE FUNCTION sim.reject_change();
670
+ CREATE TRIGGER read_log_is_never_truncated BEFORE TRUNCATE ON sim.read_log
671
+ FOR EACH STATEMENT EXECUTE FUNCTION sim.reject_change();
672
+ CREATE TRIGGER write_is_never_truncated BEFORE TRUNCATE ON sim.write
673
+ FOR EACH STATEMENT EXECUTE FUNCTION sim.reject_change();
674
+ CREATE TRIGGER effect_is_never_truncated BEFORE TRUNCATE ON sim.effect
675
+ FOR EACH STATEMENT EXECUTE FUNCTION sim.reject_change();
676
+ CREATE TRIGGER approval_is_never_truncated BEFORE TRUNCATE ON sim.approval
677
+ FOR EACH STATEMENT EXECUTE FUNCTION sim.reject_change();
678
+ CREATE TRIGGER approval_event_is_never_truncated BEFORE TRUNCATE ON sim.approval_event
679
+ FOR EACH STATEMENT EXECUTE FUNCTION sim.reject_change();