@mandateops/cli-linux-arm64 0.0.0-stage → 0.7.1

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 (68) hide show
  1. package/LICENSE +55 -0
  2. package/README.md +175 -2
  3. package/audit-lab/README.md +194 -0
  4. package/audit-lab/bin/mandateops +0 -0
  5. package/audit-lab/contracts/contact-plain-text.vectors.json +85 -0
  6. package/audit-lab/contracts/history-reading.md +185 -0
  7. package/audit-lab/contracts/history-reading.vectors.json +284 -0
  8. package/audit-lab/contracts/profiles.md +161 -0
  9. package/audit-lab/contracts/properties.md +512 -0
  10. package/audit-lab/contracts/sdk-config.md +155 -0
  11. package/audit-lab/contracts/system-under-test.md +385 -0
  12. package/audit-lab/contracts/test-provider.md +350 -0
  13. package/audit-lab/lab/compose.audit.yml +181 -0
  14. package/audit-lab/lab/config/fault-control.json +14 -0
  15. package/audit-lab/lab/examples/agents/Dockerfile +28 -0
  16. package/audit-lab/lab/examples/agents/codeloc.cjs +199 -0
  17. package/audit-lab/lab/examples/agents/load.cjs +9 -0
  18. package/audit-lab/lab/examples/agents/package-lock.json +2840 -0
  19. package/audit-lab/lab/examples/agents/package.json +9 -0
  20. package/audit-lab/lab/examples/agents/python/mandateops_codeloc.py +271 -0
  21. package/audit-lab/lab/examples/agents/python/sitecustomize.py +51 -0
  22. package/audit-lab/lab/examples/agents/requirements-python.txt +522 -0
  23. package/audit-lab/lab/examples/agents/telemetry-router.cjs +272 -0
  24. package/audit-lab/lab/examples/test-provider/.dockerignore +4 -0
  25. package/audit-lab/lab/examples/test-provider/Dockerfile +28 -0
  26. package/audit-lab/lab/examples/test-provider/bun.lock +405 -0
  27. package/audit-lab/lab/examples/test-provider/package.json +42 -0
  28. package/audit-lab/lab/examples/test-provider/src/amount.ts +32 -0
  29. package/audit-lab/lab/examples/test-provider/src/app.ts +538 -0
  30. package/audit-lab/lab/examples/test-provider/src/auth.ts +30 -0
  31. package/audit-lab/lab/examples/test-provider/src/barrier.ts +262 -0
  32. package/audit-lab/lab/examples/test-provider/src/codeloc.ts +27 -0
  33. package/audit-lab/lab/examples/test-provider/src/config.ts +311 -0
  34. package/audit-lab/lab/examples/test-provider/src/connect.ts +204 -0
  35. package/audit-lab/lab/examples/test-provider/src/declaration.ts +270 -0
  36. package/audit-lab/lab/examples/test-provider/src/declared.ts +198 -0
  37. package/audit-lab/lab/examples/test-provider/src/domain.ts +193 -0
  38. package/audit-lab/lab/examples/test-provider/src/egress.ts +396 -0
  39. package/audit-lab/lab/examples/test-provider/src/flow.ts +263 -0
  40. package/audit-lab/lab/examples/test-provider/src/gate.ts +301 -0
  41. package/audit-lab/lab/examples/test-provider/src/main.ts +31 -0
  42. package/audit-lab/lab/examples/test-provider/src/notify.ts +157 -0
  43. package/audit-lab/lab/examples/test-provider/src/owner.ts +60 -0
  44. package/audit-lab/lab/examples/test-provider/src/payment.ts +103 -0
  45. package/audit-lab/lab/examples/test-provider/src/profile.ts +417 -0
  46. package/audit-lab/lab/examples/test-provider/src/request.ts +201 -0
  47. package/audit-lab/lab/examples/test-provider/src/rows.ts +173 -0
  48. package/audit-lab/lab/examples/test-provider/src/schema.ts +114 -0
  49. package/audit-lab/lab/examples/test-provider/src/signature.ts +86 -0
  50. package/audit-lab/lab/examples/test-provider/src/staged.ts +318 -0
  51. package/audit-lab/lab/examples/test-provider/src/store.ts +432 -0
  52. package/audit-lab/lab/examples/test-provider/src/traffic.ts +50 -0
  53. package/audit-lab/lab/examples/test-provider/src/webauthn.d.ts +11 -0
  54. package/audit-lab/lab/examples/test-provider/src/wire.ts +153 -0
  55. package/audit-lab/lab/examples/test-provider/tsconfig.build.json +9 -0
  56. package/audit-lab/lab/examples/test-provider/tsconfig.json +24 -0
  57. package/audit-lab/lab/images/capture/Dockerfile +15 -0
  58. package/audit-lab/lab/images/capture/LICENSE +201 -0
  59. package/audit-lab/lab/images/fault-control/Dockerfile +13 -0
  60. package/audit-lab/lab/images/fault-control/LICENSE +21 -0
  61. package/audit-lab/lab/images/provider-store/Dockerfile +4 -0
  62. package/audit-lab/lab/images/provider-store/LICENSE +23 -0
  63. package/audit-lab/lab/images/telemetry/Dockerfile +14 -0
  64. package/audit-lab/lab/images/telemetry/LICENSE +201 -0
  65. package/audit-lab/lab/scripts/compose-down.sh +143 -0
  66. package/audit-lab/lab/scripts/compose-lib.sh +632 -0
  67. package/audit-lab/lab/scripts/compose-up.sh +240 -0
  68. package/package.json +16 -4
@@ -0,0 +1,185 @@
1
+ # History and capacity readings
2
+
3
+ What a customer's test adapter returns to the audit host under `payout-commitment` and
4
+ `payout-effects`. An adapter reads the backend through its own API with the viewer credential and
5
+ returns these two shapes. The SDK exports them as `HistoryReading` and `CapacityReading`, and checks
6
+ every reading with `parseHistoryReading` and `parseCapacityReading` before it reaches the host.
7
+ `contracts/history-reading.vectors.json` holds a complete example and the accepted and refused
8
+ variations; the SDK and the host's mapping both run it.
9
+
10
+ ## Who can use these profiles
11
+
12
+ Both profiles model a backend that holds the payout's amount before it sends anything, and that can
13
+ report what it holds:
14
+
15
+ | The backend | `payout-commitment` | `payout-effects` | `payout-effects-only` |
16
+ |---|---|---|---|
17
+ | Records a commitment before sending, and reports capacity | Yes | Yes | Yes |
18
+ | Sends with no prior commitment | No | No | Yes |
19
+ | Reports no capacity | No | No | Yes |
20
+
21
+ A backend without reservations cannot use the first two. A host session always declares a
22
+ reservation, so a first `submitted` with no `reserved` before it would read as a breach the backend
23
+ never promised to keep. The SDK refuses such a reading instead, naming this table's conclusion, and
24
+ a config with no adapter is refused before anything starts. `payout-effects-only` takes no lifecycle
25
+ or capacity adapter and judges provider records alone; it may take a status adapter (below), whose
26
+ reading only `reported_outcome` judges.
27
+
28
+ A status that already holds capacity counts as a reservation. A row inserted as `queued`, whose
29
+ amount the capacity reading reports as committed from that moment, maps to `reserved`.
30
+
31
+ ## Rules for every value
32
+
33
+ - Amounts are canonical decimal strings of integer minor units: `"10000"`, never `10000`, `"010"`
34
+ or `"100.00"`. An instruction's `amount` is at least `"1"`; other amounts may be `"0"`.
35
+ - Any member not listed here is refused, at every level. Do not pass native fields through.
36
+ - "Optional" means absent or `null`, and both mean the backend did not record it.
37
+ - `attempt` is a string, such as `"1"`, and must match between an attempt's events.
38
+
39
+ ## History reading
40
+
41
+ | Field | Type | Meaning |
42
+ |---|---|---|
43
+ | `source` | `"adapter"` | |
44
+ | `units` | `"minor"` | |
45
+ | `consistency` | `"commit_order"` | `events` are in the order the backend committed them. A backend that can state only `logging_order` is refused. |
46
+ | `complete` | boolean | `false` when the read took several requests and cannot show that nothing committed between them. |
47
+ | `payout` | object | See below. |
48
+ | `events` | array, at most 200 | Append-only: a later read extends an earlier one. |
49
+ | `effects` | array, at most 200, optional | Every economic action provider notifications caused for this payout, in commit order. Absent or `null`: the backend does not report them. `[]`: it took none. |
50
+
51
+ `payout`:
52
+
53
+ | Field | Type | Meaning |
54
+ |---|---|---|
55
+ | `instruction` | instruction | The stored terms, with `payment` equal to the reference given to `expectPayment`. |
56
+ | `providerPayment` | string | What the backend sends the provider as `payment`. Equal to the reference unless the backend assigns its own. |
57
+ | `state` | `reserved`, `executing`, `unknown`, `needs_review`, `failed`, `confirmed` | `unknown`: an attempt's outcome is not known and the backend may still act. `needs_review`: parked for a person. `failed`: the backend gave up, which is not proof nothing happened. |
58
+ | `committed` | boolean, optional | Whether the amount is held now. Omit it unless the backend reports this apart from the lifecycle: a value derived from `state` could not disagree with it. |
59
+ | `attempts` | integer | Attempts started. |
60
+ | `effectId` | string, optional | The provider's identifier of the effect. |
61
+
62
+ An instruction has the strings `payment`, `tenant`, `agent`, `delegation`, `account`, `destination`,
63
+ `currency`, `asset` and `network`, and `amount`.
64
+
65
+ `events`, each with a `kind`, one record per thing that happened:
66
+
67
+ | `kind` | Other members | Meaning |
68
+ |---|---|---|
69
+ | `reserved` | `flow` | The amount was held. |
70
+ | `submitted` | `key`; optional `attempt`, `terms` | Recorded before the request was sent. `key` and `terms` are those sent, with `terms.payment` as sent. Without `terms`, `instruction_binding` stays inconclusive. |
71
+ | `outcome` | `result`; optional `attempt`, `endedBy`, `effectId` | How one attempt ended. |
72
+ | `consumed` | `flow`; optional `effectId` | The held amount was spent on this effect. Follows a `confirmed` outcome. |
73
+ | `released` | `flow` | The held amount went back. Every such movement is recorded. |
74
+ | `recovered` | optional `attempt` | The backend restarted with this attempt in flight, so its outcome is unknown. |
75
+ | `late_outcome` | optional `attempt`, `effectId` | An outcome that arrived after the backend stopped waiting. It moves nothing. |
76
+
77
+ `flow` is `{ "amount": "10000", "account": "payer-1" }`, both required.
78
+
79
+ `result` is `confirmed` (the provider returned a receipt), `rejected` (the provider refused, so
80
+ nothing executed) or `unknown` (anything else). `endedBy` is `response`, `timeout`,
81
+ `connection_lost`, `error_status` or `invalid_response`.
82
+
83
+ Omit `endedBy` when the backend did not record the cause: a fault is then shown by the provider's
84
+ records and the host's own step. A recorded cause that differs from the fault leaves the stimulus
85
+ not exercised.
86
+
87
+ A backend that stores statuses rather than events maps each status change to the events above. An
88
+ attempt that will be retried ended `unknown`, even when the row merely returned to a queue.
89
+
90
+ `effects`, each one action the backend took because of a provider notification:
91
+
92
+ | Field | Type | Meaning |
93
+ |---|---|---|
94
+ | `effectId` | identifier | The backend's own identifier of the action. One identifier listed twice is one action. |
95
+ | `kind` | `credit`, `fulfilment`, `payout` | A wallet or ledger credit, an order or obligation marked fulfilled, or a further payout sent. |
96
+ | `amount` | amount, at least `"1"` | Integer minor units of `asset`. |
97
+ | `asset` | identifier | |
98
+ | `notification` | identifier | The delivery that caused it: the `deliveryId` of the notification the test provider sent. |
99
+ | `providerEffect` | identifier | The provider effect that delivery was about: its `effectId`. |
100
+
101
+ An identifier is 1 to 80 letters, digits, `_` or `-`. Report an action when the backend commits it,
102
+ whatever later happens to it. A reading without `effects` leaves `event_effect_idempotency`
103
+ inconclusive whenever notifications reached the backend.
104
+
105
+ ## Capacity reading
106
+
107
+ | Field | Type | Meaning |
108
+ |---|---|---|
109
+ | `source` | `"adapter"` | |
110
+ | `units` | `"minor"` | |
111
+ | `consistency` | `"atomic"` | One statement or transaction read every balance. `non_atomic` is refused. |
112
+ | `payoutsInScope` | integer | Payouts the balances cover. Anything but 1 leaves the reading unused. |
113
+ | `balances` | list | Every balance the backend holds the scope's money in, at least one. |
114
+
115
+ Each balance:
116
+
117
+ | Field | Type | Meaning |
118
+ |---|---|---|
119
+ | `balance` | identifier | The funding balance, as the backend names it. |
120
+ | `currency`, `asset` | identifier | The balance's explicit currency and asset. |
121
+ | `available`, `committed`, `consumed` | amount | Minor units of that currency and asset. For the payout's balance these add up to the config's `capacityLimitMinor`. |
122
+ | `source` | `"observed"` or `"declared"` | Whether the backend reported the balance or the test states it. |
123
+
124
+ The payout's balance is the one `observed` balance in its currency and asset; a reading with none,
125
+ or with several, leaves capacity unobserved. Amounts in different currencies or assets are never
126
+ added together, and a `declared` balance is shown but never stands in for a reading. A reading
127
+ with the three stocks at the top level instead of under `balances` is refused.
128
+
129
+ ## Status reading
130
+
131
+ A backend without reservations cannot report a lifecycle or capacity, but it can report what it
132
+ concluded about the payout. Under `payout-effects-only` a test may give a status adapter, read once
133
+ after the provider's records, which `reported_outcome` (P7) judges against them:
134
+
135
+ | Field | Type | Meaning |
136
+ |---|---|---|
137
+ | `source` | `"adapter"` | |
138
+ | `payment` | string | The reference given to `expectPayment`: the payout the status is about. |
139
+ | `state` | `reserved`, `executing`, `unknown`, `needs_review`, `failed`, `confirmed` | What the backend reports now, as for a history reading's `payout.state`. |
140
+
141
+ Any other member is refused. The SDK checks a status reading's shape and sends a refused or failed
142
+ reading as failed. A reading of the contract's shape that names another payment is sent as read and
143
+ reported to the test as a reading problem; the host never judges it, the trace says only
144
+ `payment=other` on its `capture_status` step and never the reference it named, and both leave P7
145
+ inconclusive (`backend_status_unavailable`). `parseStatusReading` still refuses a reading of another
146
+ payment for callers that check one themselves. A status adapter reads by the provider payment, so it
147
+ needs `bindProviderPayment`; without one the reading is reported as failed, never skipped. A
148
+ lifecycle and capacity adapter is refused under `payout-effects-only`, and a status adapter under
149
+ the other two profiles. `contracts/history-reading.vectors.json` holds the status and the refused
150
+ variations; the SDK and the host both run them.
151
+
152
+ ## Binding and when readings are taken
153
+
154
+ `Authorised.bindProviderPayment(payment)` names the identifier adapters read by, and arrives as
155
+ `context.providerPayment`. Under these profiles it is required before `inspect` and before the test
156
+ body ends; without it the run fails with `AuditUsageError`. Under `payout-effects-only` it is
157
+ optional.
158
+
159
+ The SDK reads history and capacity after the drain, and history again after the provider's records.
160
+ `inspect()` reads them while an attempt is unresolved, and a test that loses a response must call it
161
+ then, after the history shows the ambiguous record, or `commitment_retention` stays inconclusive. A
162
+ crashed worker's `recovered` record appears only when a new attempt starts, which may leave no such
163
+ moment, so use `cut_connection` to judge retention of a backend that records nothing at restart.
164
+
165
+ ## When a reading is refused
166
+
167
+ A refused reading never reaches the record as evidence: the host records that the reading failed,
168
+ and the run is inconclusive for what needed it. `result.reading_problems` lists each one by slot, and
169
+ `auditTest` prints them:
170
+
171
+ ```text
172
+ capture_history: ReadingError: events[1].attempt: expected a string, null or nothing, found a number
173
+ ```
174
+
175
+ The message gives the field's path and what belongs there, and describes the value found by type
176
+ only, because a reading may hold customer data. A stored run shows the gap
177
+ (`backend_history_unavailable`), not the field.
178
+
179
+ ## What stays backend-reported
180
+
181
+ Every reading is the backend's word. Its keys are checked against each other, and `retry_identity`
182
+ then checks them against the keys on the provider's own records. A backend that reports one key and
183
+ sends another violates that property, and any second effect also violates
184
+ `effect_within_authorisation`. A key on a request that never reached the provider's store leaves no
185
+ record, so it stays unjudged.
@@ -0,0 +1,284 @@
1
+ {
2
+ "history": {
3
+ "source": "adapter",
4
+ "units": "minor",
5
+ "consistency": "commit_order",
6
+ "complete": true,
7
+ "payout": {
8
+ "instruction": {
9
+ "payment": "order-1",
10
+ "tenant": "tenant-1",
11
+ "agent": "agent-1",
12
+ "delegation": "delegation-1",
13
+ "account": "payer-1",
14
+ "destination": "supplier-1",
15
+ "currency": "USD",
16
+ "asset": "usd",
17
+ "network": "bank-rail",
18
+ "amount": "10000"
19
+ },
20
+ "providerPayment": "po_1",
21
+ "state": "confirmed",
22
+ "committed": false,
23
+ "attempts": 1,
24
+ "effectId": "effect-1"
25
+ },
26
+ "events": [
27
+ {
28
+ "kind": "reserved",
29
+ "flow": { "amount": "10000", "account": "payer-1" }
30
+ },
31
+ {
32
+ "kind": "submitted",
33
+ "attempt": "1",
34
+ "key": "key-1",
35
+ "terms": {
36
+ "payment": "po_1",
37
+ "tenant": "tenant-1",
38
+ "agent": "agent-1",
39
+ "delegation": "delegation-1",
40
+ "account": "payer-1",
41
+ "destination": "supplier-1",
42
+ "currency": "USD",
43
+ "asset": "usd",
44
+ "network": "bank-rail",
45
+ "amount": "10000"
46
+ }
47
+ },
48
+ {
49
+ "kind": "outcome",
50
+ "attempt": "1",
51
+ "result": "confirmed",
52
+ "endedBy": "response",
53
+ "effectId": "effect-1"
54
+ },
55
+ {
56
+ "kind": "consumed",
57
+ "effectId": "effect-1",
58
+ "flow": { "amount": "10000", "account": "payer-1" }
59
+ }
60
+ ]
61
+ },
62
+ "capacity": {
63
+ "source": "adapter",
64
+ "units": "minor",
65
+ "consistency": "atomic",
66
+ "payoutsInScope": 1,
67
+ "balances": [
68
+ {
69
+ "balance": "payer-1",
70
+ "currency": "USD",
71
+ "asset": "usd",
72
+ "available": "90000",
73
+ "committed": "0",
74
+ "consumed": "10000",
75
+ "source": "observed"
76
+ }
77
+ ]
78
+ },
79
+ "accepted_history_changes": [
80
+ { "name": "committed absent", "remove": "/payout/committed" },
81
+ {
82
+ "name": "effect not known",
83
+ "pointer": "/payout/effectId",
84
+ "value": null
85
+ },
86
+ { "name": "attempt not recorded", "remove": "/events/1/attempt" },
87
+ { "name": "terms not recorded", "remove": "/events/1/terms" },
88
+ {
89
+ "name": "end not recorded",
90
+ "pointer": "/events/2/endedBy",
91
+ "value": null
92
+ },
93
+ {
94
+ "name": "restart with an attempt in flight",
95
+ "pointer": "/events/2",
96
+ "value": { "kind": "recovered", "attempt": "1" }
97
+ },
98
+ {
99
+ "name": "late outcome",
100
+ "pointer": "/events/2",
101
+ "value": {
102
+ "kind": "late_outcome",
103
+ "attempt": "1",
104
+ "effectId": "effect-1"
105
+ }
106
+ },
107
+ {
108
+ "name": "release",
109
+ "pointer": "/events/3",
110
+ "value": {
111
+ "kind": "released",
112
+ "flow": { "amount": "10000", "account": "payer-1" }
113
+ }
114
+ },
115
+ {
116
+ "name": "notification effects reported",
117
+ "pointer": "/effects",
118
+ "value": [
119
+ {
120
+ "effectId": "credit-1",
121
+ "kind": "credit",
122
+ "amount": "10000",
123
+ "asset": "usd",
124
+ "notification": "delivery-1",
125
+ "providerEffect": "effect-1"
126
+ }
127
+ ]
128
+ },
129
+ { "name": "no notification effects", "pointer": "/effects", "value": [] },
130
+ {
131
+ "name": "notification effects not reported",
132
+ "pointer": "/effects",
133
+ "value": null
134
+ }
135
+ ],
136
+ "refused_history_changes": [
137
+ { "field": "source", "remove": "/source" },
138
+ { "field": "units", "pointer": "/units", "value": "major" },
139
+ {
140
+ "field": "consistency",
141
+ "pointer": "/consistency",
142
+ "value": "logging_order"
143
+ },
144
+ { "field": "complete", "pointer": "/complete", "value": "yes" },
145
+ { "field": "sequence", "pointer": "/sequence", "value": 1 },
146
+ { "field": "payout", "remove": "/payout" },
147
+ {
148
+ "field": "payout.instruction.amount",
149
+ "pointer": "/payout/instruction/amount",
150
+ "value": 10000
151
+ },
152
+ {
153
+ "field": "payout.instruction.amount",
154
+ "pointer": "/payout/instruction/amount",
155
+ "value": "0"
156
+ },
157
+ {
158
+ "field": "payout.instruction.tenant",
159
+ "remove": "/payout/instruction/tenant"
160
+ },
161
+ { "field": "payout.providerPayment", "remove": "/payout/providerPayment" },
162
+ { "field": "payout.state", "pointer": "/payout/state", "value": "queued" },
163
+ {
164
+ "field": "payout.committed",
165
+ "pointer": "/payout/committed",
166
+ "value": "0"
167
+ },
168
+ { "field": "payout.attempts", "pointer": "/payout/attempts", "value": [] },
169
+ { "field": "payout.attempts", "pointer": "/payout/attempts", "value": -1 },
170
+ { "field": "events", "pointer": "/events", "value": {} },
171
+ { "field": "events[0].kind", "pointer": "/events/0/kind", "value": "held" },
172
+ {
173
+ "field": "events[0].amount",
174
+ "pointer": "/events/0",
175
+ "value": { "kind": "reserved", "amount": "10000" }
176
+ },
177
+ { "field": "events[0].flow.account", "remove": "/events/0/flow/account" },
178
+ {
179
+ "field": "events[0].flow.amount",
180
+ "pointer": "/events/0/flow/amount",
181
+ "value": "010"
182
+ },
183
+ {
184
+ "field": "events[1].attempt",
185
+ "pointer": "/events/1/attempt",
186
+ "value": 1
187
+ },
188
+ { "field": "events[1].key", "remove": "/events/1/key" },
189
+ {
190
+ "field": "events[1].sequence",
191
+ "pointer": "/events/1/sequence",
192
+ "value": 2
193
+ },
194
+ {
195
+ "field": "events[2].result",
196
+ "pointer": "/events/2/result",
197
+ "value": "effect"
198
+ },
199
+ {
200
+ "field": "events[2].endedBy",
201
+ "pointer": "/events/2/endedBy",
202
+ "value": "provider"
203
+ },
204
+ { "field": "effects", "pointer": "/effects", "value": "none" },
205
+ {
206
+ "field": "effects[0].kind",
207
+ "pointer": "/effects",
208
+ "value": [
209
+ {
210
+ "effectId": "credit-1",
211
+ "kind": "refund",
212
+ "amount": "10000",
213
+ "asset": "usd",
214
+ "notification": "delivery-1",
215
+ "providerEffect": "effect-1"
216
+ }
217
+ ]
218
+ },
219
+ {
220
+ "field": "effects[0].amount",
221
+ "pointer": "/effects",
222
+ "value": [
223
+ {
224
+ "effectId": "credit-1",
225
+ "kind": "credit",
226
+ "amount": "0",
227
+ "asset": "usd",
228
+ "notification": "delivery-1",
229
+ "providerEffect": "effect-1"
230
+ }
231
+ ]
232
+ },
233
+ {
234
+ "field": "effects[0].notification",
235
+ "pointer": "/effects",
236
+ "value": [
237
+ {
238
+ "effectId": "credit-1",
239
+ "kind": "credit",
240
+ "amount": "10000",
241
+ "asset": "usd",
242
+ "notification": "delivery 1",
243
+ "providerEffect": "effect-1"
244
+ }
245
+ ]
246
+ }
247
+ ],
248
+ "refused_capacity_changes": [
249
+ {
250
+ "field": "consistency",
251
+ "pointer": "/consistency",
252
+ "value": "non_atomic"
253
+ },
254
+ { "field": "payoutsInScope", "remove": "/payoutsInScope" },
255
+ { "field": "balances", "pointer": "/balances", "value": [] },
256
+ { "field": "available", "pointer": "/available", "value": "90000" },
257
+ {
258
+ "field": "balances[0].available",
259
+ "pointer": "/balances/0/available",
260
+ "value": 90000
261
+ },
262
+ {
263
+ "field": "balances[0].committed",
264
+ "pointer": "/balances/0/committed",
265
+ "value": "-1"
266
+ },
267
+ { "field": "balances[0].currency", "remove": "/balances/0/currency" },
268
+ { "field": "balances[0].asset", "remove": "/balances/0/asset" },
269
+ {
270
+ "field": "balances[0].source",
271
+ "pointer": "/balances/0/source",
272
+ "value": "inferred"
273
+ }
274
+ ],
275
+ "status": { "source": "adapter", "payment": "order-1", "state": "failed" },
276
+ "refused_status_changes": [
277
+ { "field": "source", "pointer": "/source", "value": "backend" },
278
+ { "field": "payment", "remove": "/payment" },
279
+ { "field": "payment", "pointer": "/payment", "value": "order-2" },
280
+ { "field": "state", "pointer": "/state", "value": "settled" },
281
+ { "field": "state", "pointer": "/state", "value": 7 },
282
+ { "field": "extra", "pointer": "/extra", "value": true }
283
+ ]
284
+ }
@@ -0,0 +1,161 @@
1
+ # Scenario profiles
2
+
3
+ A profile says how a scenario's stimulus reaches a backend and what the runner may control. It
4
+ is chosen per deployment (`MANDATEOPS_PROFILE`, `--profile`), recorded in `raw-run.json`, and
5
+ negotiated against the adapter's declared capabilities before any work is submitted
6
+ ([adapter contract](system-under-test.md)). Profiles never branch on backend names. Both
7
+ profiles feed the same conversion, the same [property contracts](properties.md), the same trace
8
+ and the same report.
9
+
10
+ | | controlled-payout | native-worker |
11
+ |---|---|---|
12
+ | Required | `submission: reserve_only`, `attempt_control: manual` | `submission: native_processing` |
13
+ | Who attempts | The runner, once per scenario step | The backend's own workers |
14
+ | Who retries | The runner (lost-response retry) | The backend; the runner never retries or drives an attempt |
15
+ | Submission count | Exactly what the scenario names | At least what the scenario names |
16
+ | Fault timing | Arm provider hold, submit, trigger attempt | Arm provider hold, then submit (submission starts processing) |
17
+ | Fresh fixture | `reset` or `isolated_deployment` | `reset` or `isolated_deployment` |
18
+
19
+ Scenarios that lose a response or inject notifications additionally require the deployment's
20
+ `provider_barrier`; `crash-after-effect` also requires its `process_control`. Each is probed before
21
+ any work is submitted; a scenario with no fault touches neither the barrier nor the proxy. A response is lost by a proxy cut
22
+ (`lost-response`, `incomplete-capture`), by the backend's own provider timeout
23
+ (`held-past-timeout`) or by killing the declared service (`crash-after-effect`), and the first
24
+ ambiguous record must match that stimulus or the run records `loss_cause_unproven`. Each
25
+ backend's defect is exercised by the stimulus that reaches it: the shared unsafe-release objective
26
+ uses `held-past-timeout` on both.
27
+
28
+ Against a real provider's sandbox there is no barrier, so every scenario above that needs one
29
+ refuses with `provider_barrier` and a plain reason. `lost-reply` needs the deployment's
30
+ `reply_loss` instead: the backend keeps its real HTTPS URL, which on the customer network names
31
+ the gate; the gate passes TLS only for the one allowed host whose SNI it reads, through that
32
+ host's fault-control proxy (`config/fault-control.json`), whose host is pinned at start to the
33
+ public IPv4 addresses it then resolved to. The runner holds the first attempt's provider replies
34
+ one at a time (a reply is the provider's first data after the backend sent some, counted by TLS
35
+ record) and reads the provider's own records while each is held. A reply held before the effect
36
+ exists is let go; once the records hold the payout's effect the connection is cut, so the reply
37
+ reporting it is lost, and one retry follows. Which call a reply answers is never assumed, so call
38
+ order does not matter, and the cut's `after_commit` is the provider's own observation.
39
+ `held-past-timeout` runs there too: the effect's reply is held, not cut, until the backend's own
40
+ provider timeout ends the attempt, then let go to the connection it abandoned. The deployment
41
+ declares how many replies may be held (`MANDATEOPS_REPLY_HOLD_LIMIT`) and how long each may take
42
+ to be held (`MANDATEOPS_REPLY_HOLD_MS`); reaching the limit is recorded and refused in plain words.
43
+ Because the held or cut reply must answer the backend's own creation or funding call, `lost-reply`
44
+ and `held-past-timeout` need a sandbox credential that funds through the API. Without one, the
45
+ other paid sandbox cases adopt a transfer funded by hand from the lab's funded-transfer pool: one
46
+ transfer per funded run input, verified read-only and recorded as used before the run, and the
47
+ case skips with "refill the funded-transfer pool in the sandbox dashboard" when none is left. The
48
+ reader reads such a transfer by id and records that balance-update notifications are not covered,
49
+ since its funding moved the balance before the run. The notification cases move the funded
50
+ transfer through `processing`, `funds_converted` and `outgoing_payment_sent` in the provider's
51
+ order, at least five seconds apart, and refuse a transfer that is not funded; the sent delivery is
52
+ the one they repeat. Refilling the pool and the number a release round spends are described in
53
+ `examples/transfer-payouts/README.md`.
54
+ A host with IPv6 addresses only is refused, as the lab's networks carry IPv4. Each sandbox run
55
+ re-resolves the host under the same public-only rule before the fault and before the retry; when
56
+ none of the pinned addresses remains, the egress proxy moves to a new one and the move is
57
+ recorded (`repin_egress`).
58
+
59
+ Every run records which stimuli its scenario required and which the evidence shows
60
+ (`stimuli` in `observations.json` and `outcome.json`). A required stimulus not shown is
61
+ `stimulus_not_exercised`. A deployment with a seeded defect declares the stimulus that reaches it
62
+ (`MANDATEOPS_DEFECT_STIMULUS`); a run that does not apply it is `defect_path_not_reached`, so it can
63
+ never read like a healthy run.
64
+
65
+ Waits a deployment's behaviour decides are declared by the deployment: `MANDATEOPS_WORKER_DEADLINE_MS`
66
+ covers its retry schedule and `MANDATEOPS_QUIESCENCE_MS` the window after settlement, which has no default and must cover the declared `MANDATEOPS_RETRY_DELAY_MS` and `MANDATEOPS_WORKER_LEASE_MS`. The native-worker
67
+ capture rests on one stated assumption: every effect commits within the quiescence window
68
+ ([properties](properties.md)).
69
+
70
+ The systems view below is our own reading of the payout lab: what is stored, what moves it,
71
+ who knows what and when, and where an intervention acts. Feedback loops marked *hypothesis* are
72
+ expected behaviour, not measured dynamics.
73
+
74
+ ## Controlled-payout profile
75
+
76
+ **Purpose and boundary.** Protect one delegated capacity scope from losing track of money that
77
+ may already have left. Observable: the backend's lifecycle, payout row and capacity stocks, and
78
+ independently the provider's effect records. External: the provider's internal processing and
79
+ the network between backend and provider. Decisions: the agent workload submits; the runner
80
+ decides when each attempt happens; the backend decides reservation, retry key and release.
81
+
82
+ **Stocks, units and scope.** `A`, `C`, `S` in integer minor units of one asset, partitioning the
83
+ fixed limit `L` of one scope that contains one payout. `E`: amount of unique provider effects for
84
+ the payout, same units, observed at the provider. Knowledge stock: the set of submitted attempts
85
+ whose outcome the backend does not yet know.
86
+
87
+ **Flows and rules.** Reserve moves the amount from `A` to `C`. Confirmation moves it from `C` to
88
+ `S`. Release moves it from `C` to `A` only when nothing was submitted or every submitted attempt
89
+ is definitively known not to have executed. Each provider request adds to `E` once per
90
+ idempotency key in the provider's declared scope. A timeout or lost response moves nothing; it
91
+ only adds to the unknown set.
92
+
93
+ **Information channels and delays.** The provider's response is the backend's only near-term
94
+ channel to the economic state; it can be delayed or lost after the effect is committed, so the
95
+ backend's knowledge lags the economic state. The runner's reads of backend history, capacity and
96
+ provider records are taken at different instants; the final capture brackets them with two
97
+ history reads, and the pre-retry capacity reading is bracketed the same way. Effects are placed
98
+ in the trace at their earliest causally possible position, after the submission that named their
99
+ key.
100
+
101
+ **Feedback.** Intended balancing loop: an unknown outcome keeps `C` held and leads to a retry
102
+ with the same key, whose answer resolves the unknown without adding to `E`. *Hypothesis*
103
+ reinforcing failure loops: a retry with a new key adds a second effect, which the backend then
104
+ cannot reconcile (changed-key defect); releasing `C` on a timeout frees capacity that is spent
105
+ again while the first effect is still in flight (unsafe-release defect). The audit itself is a
106
+ separate, slower loop: findings change code and tests, never live financial authority.
107
+
108
+ **Intervention points.** The retry key rule and the release rule change outcomes far more than the
109
+ timeout value: a longer timeout only delays the same decision. Adding a definitive outcome query
110
+ to the information path shortens the unknown period without changing the flows.
111
+
112
+ **Invariants and properties.** `A + C + S = L` and "C holds the amount while unresolved" become
113
+ `reconciliation_consistency` and `commitment_retention`; "one key per payout" becomes
114
+ `retry_identity`; "`E` does not exceed the authorised amount" becomes
115
+ `effect_within_authorisation`, judged from provider records alone; exact terms become
116
+ `instruction_binding`. The bookkeeping equation can hold while `E` is doubled, which is why `E` is
117
+ compared independently.
118
+
119
+ ## Native-worker profile
120
+
121
+ **Purpose and boundary.** The same financial protection for a backend whose submission starts
122
+ its own processing. The workers, queue and retry policy are inside the boundary and are what is
123
+ being assessed; the adapter must not replace or disable them.
124
+
125
+ **Stocks, units and scope.** As above, when the adapter declares a capacity snapshot of an isolated
126
+ single-payout scope or a reported count of one. Additional stocks the backend may expose (queued jobs, in-flight attempts) are
127
+ observations, not terms of `A + C + S`. Without a capacity snapshot the capacity stocks are
128
+ unobserved and only the properties that do not need them can be established.
129
+
130
+ **Flows and rules.** Submission reserves and enqueues. Workers attempt, record outcomes and may
131
+ retry on their own schedule. The release rule and the key rule are the backend's; the profile
132
+ only observes whether they hold.
133
+
134
+ **Information channels and delays.** In addition to the provider response, there is a delay
135
+ between the backend committing a record and a worker acting on it, and between the worker's
136
+ action and the runner's next read. Readings can therefore straddle a worker step; every reading
137
+ used against the lifecycle is bracketed by equal history reads, retried a bounded number of times,
138
+ and a changed bracket drops the reading with a named gap. After settlement the runner waits the
139
+ declared quiescence window and reads effects once more after capture. Submission counts are lower bounds, since a worker may retry while the
140
+ runner is not looking.
141
+
142
+ **Feedback.** Intended balancing loop: the worker's own retry with the same key resolves an
143
+ unknown outcome. *Hypothesis*: autonomous retries during a provider outage multiply submissions;
144
+ with a stable key they add no effects, with a changing key each one can add to `E`. A worker that
145
+ treats repeated notifications as new confirmations would inflate `S` without changing `E`.
146
+
147
+ **Intervention points.** Worker retry key derivation, the condition under which a worker releases
148
+ or abandons a commitment, and whether the worker queries the provider before retrying. Retry
149
+ counts and backoff change how fast the loop runs, not whether it is safe.
150
+
151
+ **Invariants and properties.** The same five property contracts apply unchanged; only the
152
+ stimulus and the submission-count expectation differ. Order-dependent claims use the same causal
153
+ placement and admissibility rules, so a worker acting between two reads can make a property
154
+ inconclusive but cannot manufacture a violation.
155
+
156
+ ## Status
157
+
158
+ The controlled-payout profile is exercised end to end against `examples/ts-payout-backend`, and
159
+ the native-worker profile against `examples/queue-payout-backend`, including a real worker crash
160
+ recovered by lease. Both backends are lab software. No profile claims competing concurrent
161
+ reservations, so no scenario covers them. Neither backend consumes provider notifications.