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
fivefold/__init__.py ADDED
@@ -0,0 +1,4 @@
1
+ """FiveFold: a test suite and reference gateway for agent side effects under failure.
2
+
3
+ The contracts are in docs/spec.md, and the decision records behind them in docs/adr/.
4
+ """
@@ -0,0 +1,26 @@
1
+ -- Component roles (decision record 0008), and ff_registry, which writes the run registry
2
+ -- (0012, db/registry/). It has no privilege on the schemas of a run database.
3
+ --
4
+ -- Roles belong to the whole PostgreSQL server, so this script runs once per server, as a
5
+ -- superuser, before any migration. It is safe to run again.
6
+ --
7
+ -- The roles can log in but have no password. Where the server uses password
8
+ -- authentication, set passwords outside this repository.
9
+
10
+ DO $$
11
+ DECLARE
12
+ role_name text;
13
+ BEGIN
14
+ FOREACH role_name IN ARRAY ARRAY[
15
+ 'ff_sim', 'ff_gw', 'ff_harness', 'ff_agent', 'ff_eval', 'ff_viewer', 'ff_registry'
16
+ ]
17
+ LOOP
18
+ IF NOT EXISTS (SELECT FROM pg_catalog.pg_roles WHERE rolname = role_name) THEN
19
+ EXECUTE format('CREATE ROLE %I LOGIN', role_name);
20
+ END IF;
21
+ END LOOP;
22
+ END
23
+ $$;
24
+
25
+ -- LangGraph's checkpointer keeps its tables in schema agent (0008).
26
+ ALTER ROLE ff_agent SET search_path = agent;
@@ -0,0 +1,67 @@
1
+ -- Schemas and privileges for the components (decision record 0008).
2
+ --
3
+ -- Tables arrive in later migrations. The default privileges below apply to every table and
4
+ -- sequence that the migrating role creates later in each schema, so each new table gets
5
+ -- the privileges in 0008's table without repeating them. "Writes" means SELECT, INSERT,
6
+ -- UPDATE and DELETE.
7
+ --
8
+ -- role sim gw harness agent eval
9
+ -- ff_sim writes none none none none
10
+ -- ff_gw none writes none none none
11
+ -- ff_harness select none writes none none
12
+ -- ff_agent none none none writes none
13
+ -- ff_eval select select select none writes
14
+ -- ff_viewer select select select none select
15
+ --
16
+ -- The gateway's append-only action_event table revokes UPDATE and DELETE from ff_gw in the
17
+ -- migration that creates it (0003, I6).
18
+
19
+ CREATE SCHEMA sim;
20
+ CREATE SCHEMA gw;
21
+ CREATE SCHEMA harness;
22
+ CREATE SCHEMA agent;
23
+ CREATE SCHEMA eval;
24
+
25
+ -- sim: ground truth. The simulator writes; the harness, evaluator and viewer read.
26
+ GRANT USAGE ON SCHEMA sim TO ff_sim, ff_harness, ff_eval, ff_viewer;
27
+ ALTER DEFAULT PRIVILEGES IN SCHEMA sim
28
+ GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO ff_sim;
29
+ ALTER DEFAULT PRIVILEGES IN SCHEMA sim
30
+ GRANT USAGE, SELECT, UPDATE ON SEQUENCES TO ff_sim;
31
+ ALTER DEFAULT PRIVILEGES IN SCHEMA sim
32
+ GRANT SELECT ON TABLES TO ff_harness, ff_eval, ff_viewer;
33
+
34
+ -- gw: the action store. The gateway writes; the evaluator and viewer read.
35
+ GRANT USAGE ON SCHEMA gw TO ff_gw, ff_eval, ff_viewer;
36
+ ALTER DEFAULT PRIVILEGES IN SCHEMA gw
37
+ GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO ff_gw;
38
+ ALTER DEFAULT PRIVILEGES IN SCHEMA gw
39
+ GRANT USAGE, SELECT, UPDATE ON SEQUENCES TO ff_gw;
40
+ ALTER DEFAULT PRIVILEGES IN SCHEMA gw
41
+ GRANT SELECT ON TABLES TO ff_eval, ff_viewer;
42
+
43
+ -- harness: message, fault and actor logs, and final reports. The harness writes; the
44
+ -- evaluator and viewer read.
45
+ GRANT USAGE ON SCHEMA harness TO ff_harness, ff_eval, ff_viewer;
46
+ ALTER DEFAULT PRIVILEGES IN SCHEMA harness
47
+ GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO ff_harness;
48
+ ALTER DEFAULT PRIVILEGES IN SCHEMA harness
49
+ GRANT USAGE, SELECT, UPDATE ON SEQUENCES TO ff_harness;
50
+ ALTER DEFAULT PRIVILEGES IN SCHEMA harness
51
+ GRANT SELECT ON TABLES TO ff_eval, ff_viewer;
52
+
53
+ -- agent: LangGraph checkpoints. Only the agent runner, which creates its own tables.
54
+ GRANT USAGE, CREATE ON SCHEMA agent TO ff_agent;
55
+ ALTER DEFAULT PRIVILEGES IN SCHEMA agent
56
+ GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO ff_agent;
57
+ ALTER DEFAULT PRIVILEGES IN SCHEMA agent
58
+ GRANT USAGE, SELECT, UPDATE ON SEQUENCES TO ff_agent;
59
+
60
+ -- eval: results. The evaluator writes; the viewer reads.
61
+ GRANT USAGE ON SCHEMA eval TO ff_eval, ff_viewer;
62
+ ALTER DEFAULT PRIVILEGES IN SCHEMA eval
63
+ GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO ff_eval;
64
+ ALTER DEFAULT PRIVILEGES IN SCHEMA eval
65
+ GRANT USAGE, SELECT, UPDATE ON SEQUENCES TO ff_eval;
66
+ ALTER DEFAULT PRIVILEGES IN SCHEMA eval
67
+ GRANT SELECT ON TABLES TO ff_viewer;
@@ -0,0 +1,224 @@
1
+ -- The gateway's action store (decision records 0001, 0002, 0003).
2
+ --
3
+ -- The step functions in src/fivefold/gateway/steps.py decide every change, and the store
4
+ -- in src/fivefold/gateway/pg_store.py writes it in one transaction. This schema holds the
5
+ -- records and enforces, on its own, the invariants a database can enforce:
6
+ --
7
+ -- I1 a trigger rejects any change to an effect id once it is set, and an effect id
8
+ -- exists exactly when the action is Confirmed;
9
+ -- I2 one grant per action and one per approval; a grant never moves to another action
10
+ -- or approval; every attempt uses its action's grant;
11
+ -- I4 every attempt carries its action's idempotency key;
12
+ -- I6 action_event is append-only: ff_gw has no UPDATE, DELETE or TRUNCATE privilege on
13
+ -- it, and triggers reject all three for every role;
14
+ -- I7 a partial unique index allows one live or Confirmed action per intent, for rows
15
+ -- with identity on (G1's rows have it off and are exempt); identity never changes.
16
+ --
17
+ -- What identifies an action, a grant or an attempt never changes after it is written.
18
+ --
19
+ -- The default privileges in 0001_schemas.sql give ff_gw SELECT, INSERT, UPDATE and DELETE
20
+ -- on every table here, and ff_eval and ff_viewer SELECT.
21
+
22
+ -- One row per run database: whether the run is closed (0003), and the counters that give
23
+ -- actions, events and tool calls their gap-free numbers. A transaction takes this row's
24
+ -- lock last: after the intent's row and the action rows it changes.
25
+ CREATE TABLE gw.run_state (
26
+ singleton boolean PRIMARY KEY DEFAULT true CHECK (singleton),
27
+ run_closed boolean NOT NULL DEFAULT false,
28
+ last_action_no bigint NOT NULL DEFAULT 0,
29
+ last_seq bigint NOT NULL DEFAULT 0,
30
+ last_call_no bigint NOT NULL DEFAULT 0
31
+ );
32
+ INSERT INTO gw.run_state DEFAULT VALUES;
33
+
34
+ -- One row per task intent, created at run start; the lock anchor for the matching rule
35
+ -- (0001, item 10).
36
+ CREATE TABLE gw.intent (
37
+ intent_id text PRIMARY KEY,
38
+ operation text NOT NULL
39
+ );
40
+
41
+ CREATE TABLE gw.action (
42
+ action_id text PRIMARY KEY,
43
+ task_id text NOT NULL,
44
+ intent_id text NOT NULL REFERENCES gw.intent (intent_id),
45
+ operation text NOT NULL,
46
+ target text NOT NULL,
47
+ args jsonb NOT NULL,
48
+ action_key text NOT NULL,
49
+ identity boolean NOT NULL,
50
+ contract text NOT NULL CHECK (contract IN ('C0', 'C1', 'C2', 'C3')),
51
+ basis jsonb NOT NULL,
52
+ state text NOT NULL CHECK (state IN (
53
+ 'proposed', 'pending_approval', 'authorized', 'dispatched', 'outcome_unknown',
54
+ 'confirmed', 'rejected', 'failed'
55
+ )),
56
+ grant_id text UNIQUE,
57
+ idempotency_key text NOT NULL UNIQUE,
58
+ effect_id text,
59
+ created_vt bigint NOT NULL,
60
+ updated_vt bigint NOT NULL,
61
+ UNIQUE (action_id, idempotency_key),
62
+ UNIQUE (action_id, grant_id),
63
+ CONSTRAINT action_effect_id_only_when_confirmed
64
+ CHECK ((state = 'confirmed') = (effect_id IS NOT NULL))
65
+ );
66
+
67
+ CREATE UNIQUE INDEX action_one_holder_per_intent ON gw.action (intent_id)
68
+ WHERE identity AND state IN (
69
+ 'proposed', 'pending_approval', 'authorized', 'dispatched', 'outcome_unknown',
70
+ 'confirmed'
71
+ );
72
+
73
+ CREATE FUNCTION gw.keep_effect_id() RETURNS trigger LANGUAGE plpgsql AS $$
74
+ BEGIN
75
+ IF OLD.effect_id IS NOT NULL AND NEW.effect_id IS DISTINCT FROM OLD.effect_id THEN
76
+ RAISE EXCEPTION 'I1: the effect id of % is set and cannot change', OLD.action_id;
77
+ END IF;
78
+ RETURN NEW;
79
+ END
80
+ $$;
81
+
82
+ CREATE TRIGGER action_keeps_effect_id BEFORE UPDATE OF effect_id ON gw.action
83
+ FOR EACH ROW EXECUTE FUNCTION gw.keep_effect_id();
84
+
85
+ -- Only basis (before the first send, 0001 item 16), state, grant_id, effect_id and
86
+ -- updated_vt may change.
87
+ CREATE FUNCTION gw.keep_action_identity() RETURNS trigger LANGUAGE plpgsql AS $$
88
+ BEGIN
89
+ IF (NEW.action_id, NEW.task_id, NEW.intent_id, NEW.operation, NEW.target, NEW.args,
90
+ NEW.action_key, NEW.identity, NEW.contract, NEW.idempotency_key, NEW.created_vt)
91
+ IS DISTINCT FROM
92
+ (OLD.action_id, OLD.task_id, OLD.intent_id, OLD.operation, OLD.target, OLD.args,
93
+ OLD.action_key, OLD.identity, OLD.contract, OLD.idempotency_key, OLD.created_vt)
94
+ THEN
95
+ RAISE EXCEPTION 'what identifies action % cannot change', OLD.action_id;
96
+ END IF;
97
+ RETURN NEW;
98
+ END
99
+ $$;
100
+
101
+ CREATE TRIGGER action_keeps_identity BEFORE UPDATE ON gw.action
102
+ FOR EACH ROW EXECUTE FUNCTION gw.keep_action_identity();
103
+
104
+ -- "grant" is a reserved word in SQL, so the table name is always quoted.
105
+ CREATE TABLE gw."grant" (
106
+ grant_id text PRIMARY KEY,
107
+ action_id text NOT NULL UNIQUE REFERENCES gw.action (action_id),
108
+ approval_id text NOT NULL UNIQUE,
109
+ state text NOT NULL CHECK (state IN (
110
+ 'pending', 'active', 'consumed', 'denied', 'timed_out', 'released', 'revoked',
111
+ 'expired'
112
+ )),
113
+ requested_vt bigint NOT NULL,
114
+ consumed_vt bigint,
115
+ UNIQUE (action_id, grant_id)
116
+ );
117
+
118
+ -- Only state and consumed_vt may change: a grant never moves (I2).
119
+ CREATE FUNCTION gw.keep_grant_binding() RETURNS trigger LANGUAGE plpgsql AS $$
120
+ BEGIN
121
+ IF (NEW.grant_id, NEW.action_id, NEW.approval_id, NEW.requested_vt)
122
+ IS DISTINCT FROM (OLD.grant_id, OLD.action_id, OLD.approval_id, OLD.requested_vt)
123
+ THEN
124
+ RAISE EXCEPTION 'I2: grant % cannot move to another action or approval', OLD.grant_id;
125
+ END IF;
126
+ RETURN NEW;
127
+ END
128
+ $$;
129
+
130
+ CREATE TRIGGER grant_keeps_binding BEFORE UPDATE ON gw."grant"
131
+ FOR EACH ROW EXECUTE FUNCTION gw.keep_grant_binding();
132
+
133
+ -- An action's grant must be a grant of that action. Deferred, because the action row and
134
+ -- its grant are written in the same transaction.
135
+ ALTER TABLE gw.action ADD CONSTRAINT action_grant_is_its_own
136
+ FOREIGN KEY (action_id, grant_id) REFERENCES gw."grant" (action_id, grant_id)
137
+ DEFERRABLE INITIALLY DEFERRED;
138
+
139
+ CREATE TABLE gw.attempt (
140
+ attempt_id text PRIMARY KEY,
141
+ action_id text NOT NULL REFERENCES gw.action (action_id),
142
+ attempt_no integer NOT NULL CHECK (attempt_no >= 1),
143
+ idempotency_key text NOT NULL,
144
+ grant_id text NOT NULL,
145
+ check_kind text NOT NULL CHECK (check_kind IN ('full', 'exact_only', 'exempt')),
146
+ check_approval text,
147
+ check_basis jsonb,
148
+ check_seen_seq bigint NOT NULL,
149
+ check_vt bigint NOT NULL,
150
+ sent_vt bigint NOT NULL,
151
+ answer_class text CHECK (answer_class IN ('committed', 'rejected', 'in_progress', 'unknown')),
152
+ answer_ref text,
153
+ answered_vt bigint,
154
+ UNIQUE (action_id, attempt_no),
155
+ FOREIGN KEY (action_id, grant_id) REFERENCES gw."grant" (action_id, grant_id),
156
+ FOREIGN KEY (action_id, grant_id) REFERENCES gw.action (action_id, grant_id),
157
+ FOREIGN KEY (action_id, idempotency_key) REFERENCES gw.action (action_id, idempotency_key)
158
+ );
159
+
160
+ -- Only the answer may change: the check and the send are history (I3).
161
+ CREATE FUNCTION gw.keep_attempt_history() RETURNS trigger LANGUAGE plpgsql AS $$
162
+ BEGIN
163
+ IF (NEW.attempt_id, NEW.action_id, NEW.attempt_no, NEW.idempotency_key, NEW.grant_id,
164
+ NEW.check_kind, NEW.check_approval, NEW.check_basis, NEW.check_seen_seq,
165
+ NEW.check_vt, NEW.sent_vt)
166
+ IS DISTINCT FROM
167
+ (OLD.attempt_id, OLD.action_id, OLD.attempt_no, OLD.idempotency_key, OLD.grant_id,
168
+ OLD.check_kind, OLD.check_approval, OLD.check_basis, OLD.check_seen_seq,
169
+ OLD.check_vt, OLD.sent_vt)
170
+ THEN
171
+ RAISE EXCEPTION 'attempt % is history; only its answer can be recorded', OLD.attempt_id;
172
+ END IF;
173
+ RETURN NEW;
174
+ END
175
+ $$;
176
+
177
+ CREATE TRIGGER attempt_keeps_history BEFORE UPDATE ON gw.attempt
178
+ FOR EACH ROW EXECUTE FUNCTION gw.keep_attempt_history();
179
+
180
+ CREATE TABLE gw.action_event (
181
+ seq bigint PRIMARY KEY CHECK (seq >= 1),
182
+ action_id text NOT NULL REFERENCES gw.action (action_id),
183
+ kind text NOT NULL CHECK (kind IN ('transition', 'note')),
184
+ from_state text,
185
+ to_state text NOT NULL,
186
+ reason text NOT NULL,
187
+ details jsonb NOT NULL,
188
+ vt bigint NOT NULL,
189
+ wall_at timestamptz NOT NULL DEFAULT now()
190
+ );
191
+
192
+ REVOKE UPDATE, DELETE ON gw.action_event FROM ff_gw;
193
+
194
+ CREATE FUNCTION gw.reject_change() RETURNS trigger LANGUAGE plpgsql AS $$
195
+ BEGIN
196
+ RAISE EXCEPTION 'I6: % is append-only; % refused', TG_TABLE_NAME, TG_OP;
197
+ END
198
+ $$;
199
+
200
+ CREATE TRIGGER action_event_is_append_only BEFORE UPDATE OR DELETE ON gw.action_event
201
+ FOR EACH ROW EXECUTE FUNCTION gw.reject_change();
202
+
203
+ CREATE TRIGGER action_event_is_never_truncated BEFORE TRUNCATE ON gw.action_event
204
+ FOR EACH STATEMENT EXECUTE FUNCTION gw.reject_change();
205
+
206
+ CREATE TABLE gw.escalation (
207
+ escalation_id text PRIMARY KEY,
208
+ action_id text NOT NULL UNIQUE REFERENCES gw.action (action_id),
209
+ opened_vt bigint NOT NULL,
210
+ resolved_vt bigint,
211
+ resolution text CHECK (resolution IN ('committed', 'not_committed')),
212
+ effect_id text,
213
+ actor text
214
+ );
215
+
216
+ -- Every agent-facing response, for I5. `as_of_seq` is the event seq it reflects.
217
+ CREATE TABLE gw.tool_call (
218
+ call_no bigint PRIMARY KEY CHECK (call_no >= 1),
219
+ tool text NOT NULL,
220
+ action_id text REFERENCES gw.action (action_id),
221
+ result jsonb NOT NULL,
222
+ as_of_seq bigint NOT NULL,
223
+ vt bigint NOT NULL
224
+ );
@@ -0,0 +1,91 @@
1
+ -- Record 0010's changes to the gateway's records.
2
+ --
3
+ -- 1. A send's check keeps the approval's expiry. An approval that expires before a send
4
+ -- could commit counts as expired (0010, change 4; 0002, rule 17), so the check that
5
+ -- allowed a send must show when its approval expires. The expiry is kept exactly
6
+ -- when the check found the approval approved.
7
+ -- 2. An accepted `not_done` claim closes its intent, and the run closes in the
8
+ -- transaction that accepts the last report it expects (0010, item 6). `closed` marks
9
+ -- a closed intent; `gw.report` holds each agent worker's first accepted report.
10
+
11
+ ALTER TABLE gw.attempt ADD COLUMN check_approval_expires_at bigint;
12
+
13
+ ALTER TABLE gw.attempt ADD CONSTRAINT attempt_expiry_exactly_when_approved
14
+ CHECK ((check_approval IS NOT DISTINCT FROM 'approved')
15
+ = (check_approval_expires_at IS NOT NULL));
16
+
17
+ -- The expiry is part of the check, which is history (I3): only the answer may change.
18
+ CREATE OR REPLACE FUNCTION gw.keep_attempt_history() RETURNS trigger LANGUAGE plpgsql AS $$
19
+ BEGIN
20
+ IF (NEW.attempt_id, NEW.action_id, NEW.attempt_no, NEW.idempotency_key, NEW.grant_id,
21
+ NEW.check_kind, NEW.check_approval, NEW.check_basis, NEW.check_seen_seq,
22
+ NEW.check_vt, NEW.check_approval_expires_at, NEW.sent_vt)
23
+ IS DISTINCT FROM
24
+ (OLD.attempt_id, OLD.action_id, OLD.attempt_no, OLD.idempotency_key, OLD.grant_id,
25
+ OLD.check_kind, OLD.check_approval, OLD.check_basis, OLD.check_seen_seq,
26
+ OLD.check_vt, OLD.check_approval_expires_at, OLD.sent_vt)
27
+ THEN
28
+ RAISE EXCEPTION 'attempt % is history; only its answer can be recorded', OLD.attempt_id;
29
+ END IF;
30
+ RETURN NEW;
31
+ END
32
+ $$;
33
+
34
+ ALTER TABLE gw.intent ADD COLUMN closed boolean NOT NULL DEFAULT false;
35
+
36
+ -- An intent's id and operation never change, and a closed intent never reopens. An
37
+ -- intent is never deleted either, or deleting and re-adding it would reopen it.
38
+ CREATE FUNCTION gw.keep_intent() RETURNS trigger LANGUAGE plpgsql AS $$
39
+ BEGIN
40
+ IF (NEW.intent_id, NEW.operation) IS DISTINCT FROM (OLD.intent_id, OLD.operation)
41
+ OR (OLD.closed AND NOT NEW.closed)
42
+ THEN
43
+ RAISE EXCEPTION 'intent % cannot change or reopen', OLD.intent_id;
44
+ END IF;
45
+ RETURN NEW;
46
+ END
47
+ $$;
48
+
49
+ CREATE TRIGGER intent_keeps_identity BEFORE UPDATE ON gw.intent
50
+ FOR EACH ROW EXECUTE FUNCTION gw.keep_intent();
51
+
52
+ CREATE FUNCTION gw.reject_row_change() RETURNS trigger LANGUAGE plpgsql AS $$
53
+ BEGIN
54
+ RAISE EXCEPTION 'gw.% rows are history; % refused', TG_TABLE_NAME, TG_OP;
55
+ END
56
+ $$;
57
+
58
+ CREATE TRIGGER intent_is_never_deleted BEFORE DELETE ON gw.intent
59
+ FOR EACH ROW EXECUTE FUNCTION gw.reject_row_change();
60
+
61
+ -- A closed run stays closed, and its counters never go back.
62
+ CREATE FUNCTION gw.keep_run_state() RETURNS trigger LANGUAGE plpgsql AS $$
63
+ BEGIN
64
+ IF (OLD.run_closed AND NOT NEW.run_closed)
65
+ OR NEW.last_action_no < OLD.last_action_no
66
+ OR NEW.last_seq < OLD.last_seq
67
+ OR NEW.last_call_no < OLD.last_call_no
68
+ THEN
69
+ RAISE EXCEPTION 'the run cannot reopen and its counters cannot go back';
70
+ END IF;
71
+ RETURN NEW;
72
+ END
73
+ $$;
74
+
75
+ CREATE TRIGGER run_state_moves_forward BEFORE UPDATE ON gw.run_state
76
+ FOR EACH ROW EXECUTE FUNCTION gw.keep_run_state();
77
+
78
+ CREATE TRIGGER run_state_is_never_deleted BEFORE DELETE ON gw.run_state
79
+ FOR EACH ROW EXECUTE FUNCTION gw.reject_row_change();
80
+
81
+ -- One row per agent worker whose final report was accepted, naming the response that
82
+ -- first accepted it. The gateway only ever adds rows here.
83
+ CREATE TABLE gw.report (
84
+ worker text PRIMARY KEY,
85
+ call_no bigint NOT NULL UNIQUE REFERENCES gw.tool_call (call_no)
86
+ );
87
+
88
+ REVOKE UPDATE, DELETE ON gw.report FROM ff_gw;
89
+
90
+ CREATE TRIGGER report_is_append_only BEFORE UPDATE OR DELETE ON gw.report
91
+ FOR EACH ROW EXECUTE FUNCTION gw.reject_row_change();
@@ -0,0 +1,141 @@
1
+ -- The harness's records of a run (decision records 0004, 0006 and 0009).
2
+ --
3
+ -- The evaluator scores from these records and the simulator's (0004). One counter, kept by
4
+ -- the harness, numbers every harness event in order: a message's send, its delivery, a
5
+ -- fault firing, an action of a scripted human and a submitted report. A message's `seq`
6
+ -- is the number of its send, and `delivered_seq` the number of its delivery, so "this
7
+ -- message was delivered before that report" compares two numbers.
8
+ --
9
+ -- The records are history. A message's fate is set once; faults, actor actions and
10
+ -- reports are never changed. ff_harness has no DELETE on any of these tables and no
11
+ -- UPDATE except on the message log, and triggers hold every role to the same rules.
12
+ --
13
+ -- The default privileges in 0001_schemas.sql give ff_harness SELECT, INSERT, UPDATE and
14
+ -- DELETE on every table here, and ff_eval and ff_viewer SELECT.
15
+
16
+ -- One row per run database: what the run is (0009).
17
+ CREATE TABLE harness.run (
18
+ run_id text PRIMARY KEY,
19
+ scenario_id text NOT NULL,
20
+ scenario_digest text NOT NULL,
21
+ config text NOT NULL CHECK (config IN ('B0', 'G1', 'G2')),
22
+ contract text NOT NULL CHECK (contract IN ('C0', 'C1', 'C2', 'C3')),
23
+ seed bigint NOT NULL,
24
+ topology text NOT NULL CHECK (topology IN ('inproc', 'split')),
25
+ model_adapter text NOT NULL CHECK (model_adapter IN ('scripted', 'live', 'replay')),
26
+ model text NOT NULL,
27
+ cassette_digest text,
28
+ parent_run_id text,
29
+ branch_point bigint,
30
+ params jsonb NOT NULL,
31
+ started_wall_at timestamptz NOT NULL DEFAULT now(),
32
+ CHECK ((parent_run_id IS NULL) = (branch_point IS NULL))
33
+ );
34
+
35
+ CREATE UNIQUE INDEX run_is_one_row ON harness.run ((true));
36
+
37
+ -- Every message on every hop and its fate (0004, 0006).
38
+ CREATE TABLE harness.message_log (
39
+ seq bigint PRIMARY KEY CHECK (seq >= 1),
40
+ hop text NOT NULL CHECK (hop IN ('agent_gw', 'gw_sim', 'agent_sim')),
41
+ kind text NOT NULL CHECK (kind IN ('request', 'answer', 'notification')),
42
+ sender text NOT NULL,
43
+ receiver text NOT NULL,
44
+ api text,
45
+ correlation bigint REFERENCES harness.message_log (seq),
46
+ intent_id text,
47
+ idempotency_key text,
48
+ answer_class text,
49
+ body jsonb NOT NULL,
50
+ sent_vt bigint NOT NULL CHECK (sent_vt >= 0),
51
+ fate text CHECK (fate IN ('delivered', 'dropped')),
52
+ drop_reason text CHECK (drop_reason IN (
53
+ 'fault', 'receiver_down', 'caller_timed_out', 'caller_crashed'
54
+ )),
55
+ delivered_seq bigint UNIQUE CHECK (delivered_seq > seq),
56
+ delivered_vt bigint CHECK (delivered_vt >= sent_vt),
57
+ wall_at timestamptz NOT NULL DEFAULT now(),
58
+ CHECK ((kind = 'answer') = (correlation IS NOT NULL)),
59
+ CHECK ((fate = 'delivered') = (delivered_seq IS NOT NULL AND delivered_vt IS NOT NULL)),
60
+ CHECK ((fate = 'dropped') = (drop_reason IS NOT NULL))
61
+ );
62
+
63
+ -- A message is written once when sent; its fate is set once, later.
64
+ CREATE FUNCTION harness.keep_message_history() RETURNS trigger LANGUAGE plpgsql AS $$
65
+ BEGIN
66
+ IF OLD.fate IS NOT NULL
67
+ OR (NEW.seq, NEW.hop, NEW.kind, NEW.sender, NEW.receiver, NEW.api, NEW.correlation,
68
+ NEW.intent_id, NEW.idempotency_key, NEW.answer_class, NEW.body, NEW.sent_vt)
69
+ IS DISTINCT FROM
70
+ (OLD.seq, OLD.hop, OLD.kind, OLD.sender, OLD.receiver, OLD.api, OLD.correlation,
71
+ OLD.intent_id, OLD.idempotency_key, OLD.answer_class, OLD.body, OLD.sent_vt)
72
+ THEN
73
+ RAISE EXCEPTION 'message % is history; only its fate can be set, once', OLD.seq;
74
+ END IF;
75
+ RETURN NEW;
76
+ END
77
+ $$;
78
+
79
+ CREATE TRIGGER message_log_keeps_history BEFORE UPDATE ON harness.message_log
80
+ FOR EACH ROW EXECUTE FUNCTION harness.keep_message_history();
81
+
82
+ -- Every fault fired, with the deliveries it voided (0006).
83
+ CREATE TABLE harness.fault_log (
84
+ seq bigint PRIMARY KEY CHECK (seq >= 1),
85
+ fault text NOT NULL CHECK (fault ~ '^F([1-9]|1[0-2])$'),
86
+ variant text,
87
+ point text NOT NULL,
88
+ occurrence integer NOT NULL CHECK (occurrence >= 1),
89
+ action text NOT NULL,
90
+ target_seq bigint REFERENCES harness.message_log (seq),
91
+ component text,
92
+ voided bigint[] NOT NULL DEFAULT '{}',
93
+ params jsonb NOT NULL,
94
+ vt bigint NOT NULL CHECK (vt >= 0),
95
+ wall_at timestamptz NOT NULL DEFAULT now()
96
+ );
97
+
98
+ -- Actions of the scripted approver and resolver (0002, 0009).
99
+ CREATE TABLE harness.actor_log (
100
+ seq bigint PRIMARY KEY CHECK (seq >= 1),
101
+ actor text NOT NULL CHECK (actor IN ('approver', 'resolver')),
102
+ action text NOT NULL,
103
+ subject text NOT NULL,
104
+ details jsonb NOT NULL,
105
+ vt bigint NOT NULL CHECK (vt >= 0),
106
+ wall_at timestamptz NOT NULL DEFAULT now()
107
+ );
108
+
109
+ -- Every final report the stack submitted, with its validation (0004, 0008). `message_seq`
110
+ -- is the message that carried the report to the component that accepted it: the gateway
111
+ -- in G modes, the report sink in baselines.
112
+ CREATE TABLE harness.final_report (
113
+ seq bigint PRIMARY KEY CHECK (seq >= 1),
114
+ worker text NOT NULL,
115
+ report jsonb NOT NULL,
116
+ valid boolean NOT NULL,
117
+ errors jsonb NOT NULL,
118
+ accepted_by text NOT NULL CHECK (accepted_by IN ('gateway', 'sink')),
119
+ message_seq bigint REFERENCES harness.message_log (seq),
120
+ vt bigint NOT NULL CHECK (vt >= 0),
121
+ wall_at timestamptz NOT NULL DEFAULT now()
122
+ );
123
+
124
+ CREATE FUNCTION harness.reject_change() RETURNS trigger LANGUAGE plpgsql AS $$
125
+ BEGIN
126
+ RAISE EXCEPTION '%.% is history; % refused', TG_TABLE_SCHEMA, TG_TABLE_NAME, TG_OP;
127
+ END
128
+ $$;
129
+
130
+ CREATE TRIGGER message_log_is_never_deleted BEFORE DELETE ON harness.message_log
131
+ FOR EACH ROW EXECUTE FUNCTION harness.reject_change();
132
+ CREATE TRIGGER fault_log_is_append_only BEFORE UPDATE OR DELETE ON harness.fault_log
133
+ FOR EACH ROW EXECUTE FUNCTION harness.reject_change();
134
+ CREATE TRIGGER actor_log_is_append_only BEFORE UPDATE OR DELETE ON harness.actor_log
135
+ FOR EACH ROW EXECUTE FUNCTION harness.reject_change();
136
+ CREATE TRIGGER final_report_is_append_only BEFORE UPDATE OR DELETE ON harness.final_report
137
+ FOR EACH ROW EXECUTE FUNCTION harness.reject_change();
138
+
139
+ REVOKE DELETE ON harness.message_log FROM ff_harness;
140
+ REVOKE UPDATE, DELETE ON harness.fault_log, harness.actor_log, harness.final_report
141
+ FROM ff_harness;