@mandateops/cli-linux-arm64 0.0.0-stage → 0.7.2
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.
- package/LICENSE +55 -0
- package/README.md +181 -2
- package/audit-lab/README.md +194 -0
- package/audit-lab/bin/mandateops +0 -0
- package/audit-lab/contracts/contact-plain-text.vectors.json +85 -0
- package/audit-lab/contracts/history-reading.md +185 -0
- package/audit-lab/contracts/history-reading.vectors.json +284 -0
- package/audit-lab/contracts/profiles.md +161 -0
- package/audit-lab/contracts/properties.md +512 -0
- package/audit-lab/contracts/sdk-config.md +155 -0
- package/audit-lab/contracts/system-under-test.md +385 -0
- package/audit-lab/contracts/test-provider.md +350 -0
- package/audit-lab/lab/compose.audit.yml +181 -0
- package/audit-lab/lab/config/fault-control.json +14 -0
- package/audit-lab/lab/examples/agents/Dockerfile +28 -0
- package/audit-lab/lab/examples/agents/codeloc.cjs +199 -0
- package/audit-lab/lab/examples/agents/load.cjs +9 -0
- package/audit-lab/lab/examples/agents/package-lock.json +2840 -0
- package/audit-lab/lab/examples/agents/package.json +9 -0
- package/audit-lab/lab/examples/agents/python/mandateops_codeloc.py +271 -0
- package/audit-lab/lab/examples/agents/python/sitecustomize.py +51 -0
- package/audit-lab/lab/examples/agents/requirements-python.txt +522 -0
- package/audit-lab/lab/examples/agents/telemetry-router.cjs +272 -0
- package/audit-lab/lab/examples/test-provider/.dockerignore +4 -0
- package/audit-lab/lab/examples/test-provider/Dockerfile +28 -0
- package/audit-lab/lab/examples/test-provider/bun.lock +405 -0
- package/audit-lab/lab/examples/test-provider/package.json +42 -0
- package/audit-lab/lab/examples/test-provider/src/amount.ts +32 -0
- package/audit-lab/lab/examples/test-provider/src/app.ts +538 -0
- package/audit-lab/lab/examples/test-provider/src/auth.ts +30 -0
- package/audit-lab/lab/examples/test-provider/src/barrier.ts +262 -0
- package/audit-lab/lab/examples/test-provider/src/codeloc.ts +27 -0
- package/audit-lab/lab/examples/test-provider/src/config.ts +311 -0
- package/audit-lab/lab/examples/test-provider/src/connect.ts +204 -0
- package/audit-lab/lab/examples/test-provider/src/declaration.ts +270 -0
- package/audit-lab/lab/examples/test-provider/src/declared.ts +198 -0
- package/audit-lab/lab/examples/test-provider/src/domain.ts +193 -0
- package/audit-lab/lab/examples/test-provider/src/egress.ts +396 -0
- package/audit-lab/lab/examples/test-provider/src/flow.ts +263 -0
- package/audit-lab/lab/examples/test-provider/src/gate.ts +301 -0
- package/audit-lab/lab/examples/test-provider/src/main.ts +31 -0
- package/audit-lab/lab/examples/test-provider/src/notify.ts +157 -0
- package/audit-lab/lab/examples/test-provider/src/owner.ts +60 -0
- package/audit-lab/lab/examples/test-provider/src/payment.ts +103 -0
- package/audit-lab/lab/examples/test-provider/src/profile.ts +417 -0
- package/audit-lab/lab/examples/test-provider/src/request.ts +201 -0
- package/audit-lab/lab/examples/test-provider/src/rows.ts +173 -0
- package/audit-lab/lab/examples/test-provider/src/schema.ts +114 -0
- package/audit-lab/lab/examples/test-provider/src/signature.ts +86 -0
- package/audit-lab/lab/examples/test-provider/src/staged.ts +318 -0
- package/audit-lab/lab/examples/test-provider/src/store.ts +432 -0
- package/audit-lab/lab/examples/test-provider/src/traffic.ts +50 -0
- package/audit-lab/lab/examples/test-provider/src/webauthn.d.ts +11 -0
- package/audit-lab/lab/examples/test-provider/src/wire.ts +153 -0
- package/audit-lab/lab/examples/test-provider/tsconfig.build.json +9 -0
- package/audit-lab/lab/examples/test-provider/tsconfig.json +24 -0
- package/audit-lab/lab/images/capture/Dockerfile +15 -0
- package/audit-lab/lab/images/capture/LICENSE +201 -0
- package/audit-lab/lab/images/fault-control/Dockerfile +13 -0
- package/audit-lab/lab/images/fault-control/LICENSE +21 -0
- package/audit-lab/lab/images/provider-store/Dockerfile +4 -0
- package/audit-lab/lab/images/provider-store/LICENSE +23 -0
- package/audit-lab/lab/images/telemetry/Dockerfile +14 -0
- package/audit-lab/lab/images/telemetry/LICENSE +201 -0
- package/audit-lab/lab/scripts/compose-down.sh +148 -0
- package/audit-lab/lab/scripts/compose-lib.sh +663 -0
- package/audit-lab/lab/scripts/compose-up.sh +240 -0
- 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.
|