@mandateops/cli-linux-x64 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,155 @@
1
+ # SDK configuration contract
2
+
3
+ What an `@mandateops/audit` config may say, what the host does with each value, and what a result
4
+ claims. The SDK types, the host's validation and the dashboard all follow this document. Session
5
+ protocol 7.
6
+
7
+ ## Principles
8
+
9
+ - Financial inputs are never defaulted: account, destination, amount, currency, tenant, agent,
10
+ delegation, capacity limits and retry assumptions are stated by the customer or the run refuses.
11
+ - Operational bounds may be defaulted. Every resolved value, defaulted or declared, is written to
12
+ the run record and shown with the result.
13
+ - A configuration that cannot establish a required check is refused before any deployment starts.
14
+ - Evidence missing at run time fails the required check it belongs to. The financial verdict is
15
+ reported separately: "no breach found; required evidence missing" is not "breach found".
16
+
17
+ ## Backend timings
18
+
19
+ Three values describe the customer's backend. Each is a non-negative integer of milliseconds, or
20
+ `"unknown"`.
21
+
22
+ | Field | Meaning |
23
+ |---|---|
24
+ | `retryDelayMs` | Longest delay between two attempts of one payout by the backend itself. `0`: it never retries. |
25
+ | `leaseMs` | Longest claim a worker holds on an attempt before another may take it. `0`: no leases. |
26
+ | `quiescenceMs` | After a payout settles, how long anything in the backend may still act on it. |
27
+
28
+ A late attempt can follow a lease expiry and then a retry delay, so the latest declared activity
29
+ after settlement is `retryDelayMs + leaseMs`. The two are added, not compared: a longer
30
+ observation is safe, a shorter one can miss a second payout.
31
+
32
+ - When all three are known, `quiescenceMs` must be greater than `0` and at least
33
+ `retryDelayMs + leaseMs`, or the run is refused with the minimum named.
34
+ - When any is `"unknown"`, the run needs an explicit `drainMs`. The result is then scoped to that
35
+ window: it states that effects after the window are not covered, and checks that need a complete
36
+ observation (`commitment`, `shared-capacity`) are refused before deployment.
37
+
38
+ ## Observation window
39
+
40
+ | Field | Default | Rule |
41
+ |---|---|---|
42
+ | `drainMs` | `quiescenceMs` | At least `quiescenceMs` when known. Required when any backend timing is `"unknown"`. |
43
+ | `drainBoundMs` | `4 × drainMs` | At least `drainMs`. |
44
+
45
+ After the test body, the host observes until no new effect, notification or backend change has
46
+ appeared for `drainMs`. Any such activity restarts that quiet window. If activity is still
47
+ restarting it when `drainBoundMs` is reached, every check that depends on a complete observation is
48
+ inconclusive, never passed.
49
+
50
+ ## Operational bounds
51
+
52
+ | Field | Default |
53
+ |---|---|
54
+ | `system.startupTimeoutS` | 180 |
55
+ | `system.faultDeadlineMs` | 60000, and it includes the time the backend takes to reach the provider |
56
+ | `testBudgetMs` | 120000 |
57
+ | `abortGraceMs` | 1000 |
58
+ | `system.controlTimeoutMs`, `system.processTimeoutMs`, `system.stopTimeoutS`, `system.portReads`, `system.logLimitBytes` | the host's or lab's own |
59
+
60
+ A run that reaches a defaulted or declared bound names the field to raise.
61
+
62
+ ## Checks
63
+
64
+ A check is a question the run must answer. `requiredChecks` lists the ones CI requires; when it is
65
+ absent, the checks the financial profile requires are used.
66
+
67
+ | Check | Question | Needs |
68
+ |---|---|---|
69
+ | `provider-outcome` | Did the provider hold exactly the declared outcome? | any profile |
70
+ | `backend-outcome` | Does the backend's reported outcome agree with the provider? | a status adapter, or a reading adapter |
71
+ | `backend-records` | Do the backend's records agree with each other and name the provider's effect? | a reading adapter (`payout-effects` or `payout-commitment`) |
72
+ | `commitment` | Did the backend hold capacity while the outcome was unknown? | `payout-commitment`, known backend timings |
73
+ | `shared-capacity` | Did competing payments stay within the shared limit? | known backend timings; the competition is declared in the test body, so a run that never races fails this check as required evidence missing |
74
+ | `notifications` | Did the backend act once per paid notification? | `notifyPath` and history readings with `effects` |
75
+
76
+ The host refuses, before deployment (exit 2), a required check its session cannot establish. The SDK
77
+ states the one test fact it needs when opening the session: `--status-adapter` when the test gives a
78
+ status adapter.
79
+
80
+ `capacityLimitMinor` is required when `payout-effects` or `payout-commitment` is selected, and
81
+ refused under `payout-effects-only`, where nothing reads it.
82
+
83
+ ## Providers
84
+
85
+ `system.providers` lists every provider the customer's backend calls. A single provider is a
86
+ one-entry list; there is no other form.
87
+
88
+ | Field | Required | Rule |
89
+ |---|---|---|
90
+ | `name` | yes | 1 to 80 letters, digits, `-` and `_`; unique in the list. Names the provider in the record. |
91
+ | `format` | no | The provider format the test provider speaks; the lab's own format if absent. |
92
+ | `urlEnv` | no | The variable the backend reads this provider's base URL from. The lab replaces its value. |
93
+ | `credentialEnv` | no | The variable the backend reads this provider's credential from. The lab replaces its value. |
94
+
95
+ - The list holds 1 to 8 entries; an empty or longer list is refused before deployment (exit 2).
96
+ - Every variable name follows the reserved-name rules of `credentialEnv`, and a refusal names the
97
+ field as `providers.<index>.urlEnv` or `providers.<index>.credentialEnv`.
98
+ - Every provider runs in the same session, each reached at its own host with the URL its `urlEnv` names.
99
+ Money is counted across all of them: a payout paid on two providers is one payout paid twice, and
100
+ capacity and duplicate checks sum its effects over every provider.
101
+ - A request to a route that provider's format does not declare is reported against that provider, so a
102
+ payout routed to a provider that does not serve it leaves the run inconclusive.
103
+ - Each provider holds its own lab credential, a signing key of its own for a format that signs
104
+ requests; no provider accepts another's.
105
+ - A provider's `urlEnv` or `credentialEnv` may not repeat across providers or name a variable that
106
+ `credentialEnv` or `environment` already names; the refusal names both fields.
107
+ - One key reused across providers for different payouts is reported as a duplicate key.
108
+ - `credentialEnv` at the system level holds the audited service's own roles only: `client`,
109
+ `operator`, `viewer` and `notify`.
110
+
111
+ ## Removed from the public config
112
+
113
+ - `provider`: removed; every run uses the MandateOps test provider, and results say so.
114
+ - `system.defectStimulus` and `system.providerMapping`: lab internals.
115
+ - `system.workerDeadlineMs`: bounds only the lab's own native-worker scenario, not an SDK session.
116
+ - `system.providerUrlEnv`, `system.providerWire` and `system.credentialEnv.provider`: replaced by
117
+ `system.providers`.
118
+
119
+ ## Result
120
+
121
+ The host computes one headline from the sealed record, and the CLI, the SDK and the dashboard show
122
+ the same text. It leads with the verdict and keeps the scope on the same line, then lists what was
123
+ not checked and the resolved run parameters:
124
+
125
+ ```text
126
+ Passed (provider outcome only): backend outcome not checked
127
+ USD 25.00 left once, as declared.
128
+
129
+ Not checked: backend outcome, reservations
130
+ Observation: 45 s quiet window, bound 180 s
131
+ Provider: test environment
132
+ Cleanup: complete
133
+ Record: saved locally, not uploaded
134
+
135
+ Test environment: no real money moves; real provider settlement is not covered.
136
+ ```
137
+
138
+ A statement such as "left once" appears only when the property behind it was judged satisfied.
139
+
140
+ ## Exit codes
141
+
142
+ | Code | Meaning |
143
+ |---|---|
144
+ | 0 | Every required check passed. |
145
+ | 1 | A required check failed or required evidence was missing. |
146
+ | 2 | Configuration refused before deployment. |
147
+ | 3 | Infrastructure or teardown failure. |
148
+ | 130 | Interrupted. |
149
+
150
+ ## Interruption
151
+
152
+ The first interrupt stops the test body, drains and seals the run with the body's `test_status` recorded as `interrupted`, apart from
153
+ `threw`, `timed_out` and `passed`. A
154
+ second interrupt skips the drain, removes the deployment, writes `host-lost.json`, prints the
155
+ `mandateops recover` command when anything is left, and exits 130.
@@ -0,0 +1,385 @@
1
+ # System-under-test adapter contract (V5)
2
+
3
+ V5 renames every lab setting from `AUDIT_*` to `MANDATEOPS_*`, names the run directory's settings file
4
+ `settings.env` and its service identity file `service.json`, and runs every lab container under a MandateOps image name. An old setting name is refused with its new name.
5
+
6
+ How the audit runtime connects to a payout backend it has never seen. A backend keeps its own
7
+ API, storage, workers and retry behaviour. A small reviewed Rust adapter per backend submits
8
+ work through the backend's native API and maps its native records into one neutral record model.
9
+ The runner, scenario profiles, conversion, checker, trace and report depend only on that model,
10
+ on the traits in `crates/audit-adapter/src/sut.rs` and on
11
+ declared capabilities; none of them names a backend. The adapter is selected by name from
12
+ configuration (`MANDATEOPS_BACKEND_ADAPTER` in a deployment file, `--adapter` on the command line) and
13
+ its name and declared capabilities are recorded in `raw-run.json`, with the build that recorded the run.
14
+
15
+ Paths in code spans are relative to the source repository; a package carries only these contracts.
16
+
17
+ `ts-payout` (`crates/audit-adapter/src/backends/ts_payout.rs`) maps
18
+ `examples/ts-payout-backend` under the
19
+ [controlled-payout profile](profiles.md). `queue-payout`
20
+ (`crates/audit-adapter/src/backends/queue_payout.rs`) maps
21
+ `examples/queue-payout-backend` under the
22
+ native-worker profile. `remit-api` (`crates/audit-adapter/src/backends/remit_api.rs`) maps
23
+ `examples/remit-api` under the controlled-payout profile through
24
+ that service's own approval flow, and `settle-service`
25
+ (`crates/audit-adapter/src/backends/settle_service.rs`) maps
26
+ `examples/settle-service` under the native-worker profile.
27
+ Those two services know nothing of this runtime: their Compose files live in `config/sut/`, and a
28
+ seeded defect is a source patch from `fixtures/seeded-defects/`, applied at image build through the
29
+ deployment's `SOURCE_PATCH`.
30
+
31
+ ## Boundary
32
+
33
+ Inside the boundary: the backend's reservations, submissions, attempt outcomes, workers, retries
34
+ and, when declared, its capacity stocks. Outside: the provider's effect records and the fault
35
+ proxy, which are lab infrastructure observed independently of the adapter
36
+ ([provider contract](test-provider.md)). The financial properties are defined in
37
+ [properties.md](properties.md); the profiles in [profiles.md](profiles.md).
38
+
39
+ Backend-specific code may translate API paths, authentication, schemas, statuses, identifiers,
40
+ units and database or queue observations. It must not redefine the oracle, fabricate ordering,
41
+ own a replacement ledger, retry effect-producing calls, or copy scenario orchestration.
42
+
43
+ ## Traits
44
+
45
+ `SystemUnderTest` (`#[async_trait]`, `Send + Sync`) performs I/O. Each method makes a bounded
46
+ number of native requests with bounded timeouts and returns the backend's unmodified JSON body,
47
+ which the runner stores as raw evidence before interpretation. Pagination and several reads are
48
+ legitimate; a hidden effect-producing retry is not.
49
+
50
+ | Method | Obligation |
51
+ |---|---|
52
+ | `ready` | Succeeds only when the backend can serve every other method. |
53
+ | `submit_payout(instruction)` | Submits the exact instruction through the path the agent workload uses, with the agent credential only. Its effect depends on the declared `submission` capability. |
54
+ | `history(payment)` | Reads the payout record and its lifecycle consistently, including per-attempt request terms when the backend records them. A payout the adapter holds no backend identifier for is looked up by the run's unique reference; the mapping's `absence_is_definite` declares whether the backend's 404 then means it never admitted that payment. |
55
+ | `fixture_reset()` | `Some(&dyn FixtureReset)` exactly when `fresh_fixture: reset`. |
56
+ | `attempt_control()` | `Some(&dyn AttemptControl)` exactly when `attempt_control: manual`. |
57
+ | `capacity_snapshot()` | `Some(&dyn CapacitySnapshot)` exactly when a `capacity_snapshot` is declared. |
58
+
59
+ | Optional trait | Method | Obligation |
60
+ |---|---|---|
61
+ | `FixtureReset` | `reset` | Clears every payout and lifecycle record and restores `A = L`, `C = S = 0`. |
62
+ | `AttemptControl` | `attempt(payment)` | Exactly one provider attempt; returns once its outcome is durable; refuses (non-2xx) when no attempt is allowed. |
63
+ | `CapacitySnapshot` | `capacity` | Reads A, C and S with the declared scope and consistency. |
64
+
65
+ `RecordMapping` is pure: `name`, `version`, `capabilities`, and `readiness`, `history`, `capacity`
66
+ and `provider_payment` mappings of stored bodies. The provider side has the same split:
67
+ `ProviderObserver` reads and `ProviderMapping` (`crates/audit-adapter/src/records.rs`) maps a
68
+ provider's bodies into `ProviderRecords`, selected by `MANDATEOPS_PROVIDER_MAPPING` and recorded in
69
+ `raw-run.json`, so a provider of another shape plugs in without touching conversion. It is separate from the I/O trait because `check`, `trace`,
70
+ `report` and `conformance` interpret stored evidence without a running backend.
71
+ `backends::mapping(name)` and `backends::connect(name, ...)` are the only places that know adapter
72
+ names. The CLI refuses (configuration failure) an adapter whose optional traits differ from its
73
+ declared capabilities.
74
+
75
+ ## Capability catalogue
76
+
77
+ | Capability | Values | Used by |
78
+ |---|---|---|
79
+ | `fresh_fixture` | `reset` (in place) or `isolated_deployment` (a new database, namespace, snapshot or deployment per run) | Startup. Destructive reset is one option, never a universal requirement. |
80
+ | `submission` | `reserve_only` or `native_processing` (submission starts the backend's own workers, queues and retries) | Profile negotiation. |
81
+ | `attempt_control` | `manual` or `none` | Profile negotiation; the native-worker profile never uses it. |
82
+ | `reservation_recorded` | bool: the backend records a reservation before submitting | Checker: without one the commitment is held from the first submission. |
83
+ | `capacity_snapshot` | absent, or `{scope: reported_payout_count, isolated_single_payout or shared, consistency: atomic or non_atomic}` | Missing: `capacity_unobserved`. `atomic` means one statement or transaction reads A, C and S; the equal history reads around a reading are its consistency point with the lifecycle. `isolated_single_payout` needs `isolated_deployment`; it is a declaration about the deployment, not a count. |
84
+
85
+ Deployment facilities are recorded separately in `raw-run.json` because they belong to a
86
+ deployment, not an adapter: `provider_barrier` (a provider control can hold, release or disarm a
87
+ committed response and inject notifications) and `process_control` (the runner may kill and
88
+ restart the service named by `MANDATEOPS_PROCESS_SERVICE`) and `reply_loss` (the path to a real
89
+ provider's sandbox can lose a declared reply; see `profiles.md`). Negotiation reads them, and the scenario
90
+ probes each one it needs before any work is submitted.
91
+
92
+ A scenario negotiates its required capabilities (`profile::negotiate`)
93
+ before any request reaches the deployment. A missing required capability refuses the scenario as
94
+ a configuration failure (exit 3) and names the requirements in `refused` in `raw-run.json`; a missing optional capability leaves the affected property
95
+ inconclusive through a named gap. A missing capability is never assumed present, and "not applicable"
96
+ is reserved for properties the reviewed run input deliberately excludes.
97
+
98
+ ## Neutral record model
99
+
100
+ | Concept | Neutral form | Meaning the adapter must establish |
101
+ |---|---|---|
102
+ | Logical payout | `PayoutRecord { instruction, provider_payment, state, committed, attempts, effect_id }` | `instruction` is the stored immutable instruction in the run input's logical identifiers; `provider_payment` is the identifier the backend sends the provider as `payment` (equal to the logical one unless the backend assigns its own); `state` is `reserved`, `executing`, `unknown`, `needs_review`, `failed` or `confirmed`; `committed` says whether its amount is in C now, and is absent unless the backend reports it independently of the lifecycle. |
103
+ | Provider request | `Submitted { attempt, key, terms }` | The idempotency key the backend durably recorded before sending that attempt, and the request terms of that attempt if recorded. A later payout row never stands in for absent terms. |
104
+ | Attempt outcome | `Outcome { attempt, result, ended_by, effect_id }` | `result` is `confirmed`, `rejected` (definitive non-execution under the provider contract) or `unknown`. `ended_by` is `response`, `timeout`, `connection_lost`, `error_status` or `invalid_response`, or absent if not recorded. |
105
+ | External effect identifier | `effect_id`, and the provider's `effectId` | Names one provider effect, compared with independent provider records. |
106
+ | Commitment flows | `Reserved { flow }`, `Consumed { effect_id, flow }`, `Released { flow }` | One record per stock movement, in commit order; `flow` carries the amount, account and stocks when reported. `Reserved` is absent for a backend declaring `reservation_recorded: false`. |
107
+ | Late outcome | `LateOutcome { attempt, effect_id }` | An outcome arriving after the backend stopped waiting; it moves no stock. |
108
+ | Restart with an attempt in flight | `Recovered { attempt }` | The attempt's outcome is unknown. |
109
+ | Capacity | `CapacityReading { limit, available, committed, consumed, payouts_in_scope }` | Read together when declared atomic. |
110
+ | Readiness | `Readiness { ready, provider_timeout_ms, label }` | `provider_timeout_ms` is optional; `label` is untrusted display metadata. |
111
+
112
+ ## Semantic obligations
113
+
114
+ 1. Lifecycle records are append-only and returned in commit order; a later read extends an
115
+ earlier one. The conversion rejects a history that is not an extension of an earlier read.
116
+ 2. Every `Submitted` precedes the request it describes, and its key and terms are those sent.
117
+ 3. A confirmation maps to `Outcome { confirmed }` followed by `Consumed` naming the same effect.
118
+ 4. `Released` is emitted for every movement of the payout's amount from C to A, even if a later
119
+ `Reserved` puts it back.
120
+ 5. Under `attempt_control: manual` with `reserve_only` submission, records change only in
121
+ response to `attempt`. Under `native_processing` the backend may act on its own; the runner
122
+ then brackets readings with history reads and treats a changed bracket as a capture gap.
123
+ 6. Mapping is total over what the backend can return: a body the mapping cannot read is an
124
+ interpretation failure, never a guess, and leaves independent evidence standing with a named gap.
125
+ Unknown members are rejected. A backend that binds some terms only at its first attempt maps
126
+ earlier reads to `RecordError::Unbound`: a wait polls again; a capture records
127
+ `backend_terms_unbound`.
128
+ 7. A read composed of several native requests reports `complete: false` unless it can show no
129
+ record committed between them. A final capture so marked is `truncated_history`; an inspection
130
+ so marked is not used (`inspection_missing`).
131
+
132
+ ## Trust boundary
133
+
134
+ | Fact | Source | Trust |
135
+ |---|---|---|
136
+ | Readiness, provider timeout, label | `ready` | Backend-reported. The label never affects a verdict. |
137
+ | Payout record, lifecycle, keys, per-attempt terms, `ended_by`, provider-facing payment identifier | `history` | Backend-reported; checked against each other. A backend that misreports or omits a record is not detected. Provider terms naming another identifier stay changed terms. |
138
+ | A, C, S, limit, payouts in scope | `capacity` | Backend-reported; checked against the declared `L` and the lifecycle. |
139
+ | External effects, provider account, operation and scope, notifications, refused requests | Provider `GET /_control/effects` | Independently observed; the only source of `E`. |
140
+ | Response loss | Provider barrier and fault-control cut | Caused and recorded by the runner. That the backend saw a lost connection is backend-reported. |
141
+ | Instruction, `L`, provider binding, excluded properties | Run input file (`--input`) | Declared by the reviewed run configuration. |
142
+ | Capabilities | Adapter declaration, recorded in `raw-run.json` | Reviewed code; offline interpretation requires the same declaration and the same build. |
143
+
144
+ ## Conformance
145
+
146
+ `mandateops conformance --adapter NAME --ports PORTS --input INPUT` checks the obligations against
147
+ a fresh deployment, choosing checks by declared capability only: fresh fixture (reset when
148
+ declared), capacity, reservation shape (reserve-only submission), one attempt (triggered under
149
+ manual control, otherwise awaited from the native worker within the declared deadline),
150
+ confirmation shape and recorded terms (with any number of earlier attempts), the provider's
151
+ independent effect under the submitted key, provider account, operation and scope, a refused
152
+ second attempt (manual control), and a final reset (when declared). Capacity follows the
153
+ properties: a reading they would refuse is reported `skipped`, and a declared count that is missing
154
+ fails. It prints `{"conformance":"pass","checks":[...]}` with exit 0, or names the first failed
155
+ check and exits 3. A failure is a configuration failure, never an audit verdict. A deployment
156
+ declaring `isolated_deployment` is consumed by this check.
157
+
158
+ A stored bundle is admitted through one gate, `audit_adapter::bundle::verify_bundle`: this build's
159
+ adapter and provider mapping, version, declarations and a profile that follows from them; raw bytes
160
+ matching the digest; `observations.json` and `outcome.json` reproducing byte for byte. A recorded
161
+ harness failure does not bypass it.
162
+
163
+ ## Testing from a customer's own suite
164
+
165
+ A customer needs no adapter in this workspace and no checkout. `make package` builds
166
+ `dist/audit-lab-<os>-<arch>.tar.gz` (`bin/mandateops` and the `lab/` it runs) and an SDK tarball; neither is
167
+ published. `audit.config.ts` declares the system (`compose`, `service`, `port`, every timing,
168
+ `providerTerms`, `providers`, `providerClients`, `credentialEnv`), and `mandateops session
169
+ --system-file FILE --runs-dir DIR` validates it and renders `runs/<id>/settings.env`, readable only
170
+ by its owner. Declared values never reach a command line or the scripts' environment: lab settings
171
+ come from a fixed list, and every other value goes to an env file only the customer's Compose
172
+ invocation reads. A variable steering Compose, the engine or a process (`DOCKER_*`, `COMPOSE_*`,
173
+ `PATH` and the like) is refused. The service needs a Compose healthcheck.
174
+
175
+ ### Isolation
176
+
177
+ The lab and the customer are two Compose projects; no customer file is merged with the lab's, and
178
+ the customer's is interpolated without any lab token, since Compose interpolates every file of a
179
+ project from one environment and a token there could be written into any service. Each token reaches
180
+ only the services declared to hold it, as a literal value in a file only the owner can read, written
181
+ after the customer's build and removed once Compose has started the project. `mandateops isolate` inspects the resolved
182
+ customer configuration before anything starts against an allow-list: only keys it lists pass, so a
183
+ Compose key it does not know is refused until reviewed. That refuses host networking, privileged or
184
+ extra capabilities, engine sockets, bind mounts outside the project or into the evidence, other
185
+ networks and network identities, and a service holding a lab name in any case, as Docker's resolver
186
+ ignores case. A key people often write that stays refused says why: `container_name` and `links`
187
+ give a container a name outside these checks, `sysctls` retune the network stack, and `security_opt`
188
+ passes only `no-new-privileges`. A logging driver other than `json-file` or `local` would send output
189
+ past the network or leave none for the evidence. A named volume keeps Compose's name, since teardown
190
+ removes it. A bind mount holding the run directory is refused, so `.:/app` needs `runsDirectory`
191
+ outside the project. A service behind a Compose profile is not in the resolved project, as the lab
192
+ activates none. Customer images build first,
193
+ before the lab starts and with no `--build` afterwards. A build keeps normal network access, as it
194
+ runs arbitrary steps outside the internal network, so isolation covers running containers and not
195
+ image builds. A built service's `image:` is replaced by a tag of the run, on any service sharing it
196
+ too, so the build moves no tag the host uses and teardown removes only what the run built. Every
197
+ service then joins the internal
198
+ `customer` network, loses its published ports and `NET_RAW`, and can reach only its siblings and
199
+ the gate. The gate carries two routes and has no control surface. `mandateops-provider` to the fault-control proxy listens
200
+ on the gate's `customer` address and connects only to a `lab` address; the ingress port to the
201
+ declared service listens on its `lab` address and connects only to a `customer` address. Docker's
202
+ resolver answers for every network the gate is on, by service, alias and container name, so a name
203
+ proves nothing: the gate compares the answer with the network the route declares and drops the
204
+ connection otherwise, logging why. A declared service that resolves to a lab container therefore
205
+ gets no ingress, so a run fails when it cannot reach the service. The provider, its database and the fault-control API are
206
+ not on the `customer` network, so a container cannot reach them or the outside. Refusing rather than
207
+ rewriting means a stack with its own Compose networks must drop them to be audited. A sibling
208
+ container in the customer's own project is not "outside": a payment to a fake bank inside the
209
+ stack leaves no evidence and cannot be detected.
210
+
211
+ The provider counts payment requests by route, and those it left no record of. A hosted run needs
212
+ traffic through the proxy, none around it and none unrecorded, or it cannot pass; a rejection the
213
+ backend reports needs the test provider's refusal. A declared `processService` must be a service that
214
+ talks to the provider, and the host probes it before the test starts.
215
+
216
+ A drain lasts until the provider's records have been quiet for the whole declared window, and an
217
+ effect restarts it. No window proves nothing happened later: `ci-result.json` states what the run
218
+ assumes.
219
+
220
+ Teardown removes `settings.env`, and `compose.log` is bounded by `MANDATEOPS_LOG_LIMIT_BYTES`, which
221
+ `system.logLimitBytes` sets. Built images go too unless `system.keepImages` sets
222
+ `MANDATEOPS_KEEP_IMAGES=true`, which keeps them under the run's tags. After
223
+ SIGKILL of the host, `mandateops recover` removes the deployment
224
+ ([integrity and recovery](#integrity-and-recovery)).
225
+
226
+ ### Prebuilt images
227
+
228
+ A service may declare `image: name@sha256:...` with no `build:`; nothing of the customer's then runs
229
+ during startup. Compose uses a local image and otherwise pulls it, and teardown leaves it in place.
230
+ `system.requirePrebuiltImages` makes that the rule: `isolate` refuses any service with a `build` key
231
+ or an image not pinned by a whole lowercase digest, naming the service and what to declare. Without
232
+ it the build path stays the default.
233
+
234
+ `provenance.json` names under `restarted_for_ports` any lab service restarted once at startup because Docker left its requested port mapping empty; this happens before any traffic.
235
+ `provenance.json` records each container's declared reference, image ID and the engine's repository
236
+ digests. The raw record binds them as `service_images`, the report states them, and `recheck` refuses
237
+ a `provenance.json` that differs from the record. Every service is listed, including the lab's. The
238
+ classic Docker image store gives an image a repository digest only when it is pushed, so a local-only
239
+ image cannot be pinned there: push it to a registry, or use the containerd image store, which assigns
240
+ one on build.
241
+
242
+ ### Backend telemetry
243
+
244
+ Every run traces the backend with no change to it. `isolate` writes `compose.telemetry.yml` beside
245
+ the override, and the project starts with both:
246
+
247
+ - **MandateOps telemetry.** `mandateops-recorder` receives spans and writes `telemetry/spans.jsonl` in the run
248
+ directory, rotated at 32 MiB with one backup. `mandateops-recorder-intake` shares its network
249
+ namespace and owns both standard ports, 4317 and 4318. An HTTP/1.1 connection goes to the
250
+ HTTP receiver. HTTP/2 without TLS (h2c) is terminated in the router and routed per
251
+ request: `content-type: application/grpc*` to the gRPC receiver, trailers kept; `POST` to
252
+ `/v1/traces`, `/v1/metrics` or `/v1/logs` with a protobuf or JSON body to the HTTP receiver;
253
+ anything else is answered 404. Both receivers are on loopback, bodies stream with backpressure
254
+ and a request body over 16 MiB is reset. An exporter built for gRPC therefore works against the
255
+ injected HTTP endpoint, and the reverse, as does an HTTP span exporter speaking h2c. A protocol seen on the other protocol's port is noted in `telemetry/protocol.jsonl`, and
256
+ `trace` and the dashboard show a plain note saying so; nothing needs changing in the service.
257
+ - **MandateOps capture.** Each wired service gets `mandateops-observer-<service>`, which shares only that service's process namespace. It sees the service's
258
+ processes and no other container's, and records HTTP, gRPC and SQL calls for any language,
259
+ including Go and Rust. It runs with the kernel tracing capabilities it needs, not `privileged`, and the run
260
+ waits up to 30 seconds for it to attach before submitting work.
261
+ - **Agents.** Every service gets the telemetry address in the standard `OTEL_*` exporter variables
262
+ (unless it sets its own) and, from a read-only volume, the Node agent through `NODE_OPTIONS` and the Java agent
263
+ through `JDK_JAVA_OPTIONS`, and the Python agent through `PYTHONPATH` (only when the service sets
264
+ none), for function-level spans. A service that sets `NODE_OPTIONS` keeps its
265
+ own. Propagation is off, so no `traceparent` header reaches the provider.
266
+
267
+ `mandateops trace` lists the calls in time order and counts database statements. The listing is
268
+ chosen by category, not by arrival, so infrastructure polling cannot crowd out the backend's own
269
+ calls. In priority order the categories are: calls to the provider proxy and the calls they descend
270
+ from (`provider`), failed calls by the declared service and provider clients (`failure`), their
271
+ other calls (`service`), and everything else (`infrastructure`), failed calls of any other service
272
+ included: an infrastructure long-poll that ends in an error is not a failure of the system under
273
+ test. Each has its own limit (200, 200, 120 and 40) within a total of 200. Failures cannot take the
274
+ last 40 places while service calls remain: those are reserved for service calls. Once a provider
275
+ call is cut no lower category is listed; once a failure is cut only the reserved service calls are.
276
+ In the record's spans block each call carries its `category`, and `omitted_by_category`
277
+ counts what was left out per category, beside distinct statements past 100 and unread spans. Only names, peers
278
+ and status are kept; query text and bodies are never read. `mandateops export`, and so `upload`, reduces each database
279
+ statement to its operation (`SELECT`, `INSERT`, `UPDATE` and the like, else `QUERY`) and counts
280
+ statements that then read alike together: span names can carry table and schema names, so none
281
+ leaves the machine, and `db.statement` and `db.query.text` are never read at all. This happens once,
282
+ at the export boundary; the local `trace` keeps the names as recorded. Spans are self-reported and
283
+ unauthenticated, so they explain a verdict and never decide one. Set `MANDATEOPS_TELEMETRY=off` in the
284
+ deployment file to run without any of this, for instance when an image sets `NODE_OPTIONS` in its
285
+ own `ENV`, which the Node agent's variable would replace.
286
+
287
+ ### Integrity and recovery
288
+
289
+ A packaged `mandateops` is stamped with its lab's digest and runs no other tree. The journal is
290
+ bound to the raw record by digest, and `recheck` compares them. These digests are unkeyed and
291
+ detect accident and partial edits, not forgery: anyone able to rewrite a run directory can
292
+ regenerate a consistent one. `recheck` also refuses a file under `evidence/` the record did not
293
+ plan, and a `provenance.json` whose images differ from the record. It does not bind the run's
294
+ operating records beside the bundle, `compose.log`,
295
+ `containers.json`, `ports.env` and `compose.override.yml`, nor extra files in `audit/`. A signature was not added because the key would sit with the same
296
+ local operator it would guard against; a real guarantee needs a signer outside this machine.
297
+
298
+ Session secrets are replaced by value in everything recorded, and in `compose.log`. Other secrets a
299
+ customer's service logs or sends are not known to the lab and are not redacted.
300
+
301
+ Before teardown removes `settings.env`, which can hold credentials, the session copies only the
302
+ system under test's service name (`MANDATEOPS_SUT_SERVICE`) into `service.json` in the run
303
+ directory. `export` reads the name from there, so a forwarding helper's provider calls are still
304
+ told apart from the backend's after teardown. A record that names no service labels its calls
305
+ "Unattributed service", never the backend's.
306
+
307
+ After SIGKILL of the host, `mandateops recover --run-id ID --runs-dir DIR` removes the deployment and
308
+ writes `host-lost.json`. No verdict is reconstructed, and the logs are dropped because the session's
309
+ secrets died with the host and they could not be redacted.
310
+
311
+ Each session generates its own credentials. The test receives the client, operator and viewer ones
312
+ in the `ready` reply and never a provider credential: it drives the customer's own API, so it does hold that API's. Anyone with local Docker access can read container environments. They are not written to the run directory.
313
+
314
+ ## Adding a backend
315
+
316
+ 1. Add `crates/audit-adapter/src/backends/<name>.rs` implementing `SystemUnderTest` (and the
317
+ optional traits it declares) over the backend's own API and `RecordMapping` over its own
318
+ bodies, and register the name in `backends/mod.rs`.
319
+ 2. Add a Compose file for the backend's services whose provider URL is `http://mandateops-provider:8666`,
320
+ and a deployment file under `config/deployments/` with `MANDATEOPS_PROFILE`.
321
+ 3. Add rows to `config/cases.tsv`. `scripts/e2e.sh` runs conformance on every deployment before
322
+ its case. No change to the checker, conversion, profiles or renderers is needed.
323
+
324
+ ## Test sessions
325
+
326
+ A customer's own test can drive the workflow instead of an adapter here:
327
+ customer test, thin SDK (`sdk/typescript`), `mandateops session`,
328
+ evidence bundle, Rust analysis, report. The session speaks JSON lines on stdin and stdout, journals
329
+ every accepted message and host action to `runs/<id>/session/journal.jsonl` with a sync before it
330
+ answers, and seals what it has if its input ends. The host alone reads the test provider's effects and
331
+ applies controls; no message carries an effect. The expected instruction is test-declared
332
+ authorisation: it is what the run is judged against, not proof of a business approval.
333
+
334
+ The optional test adapter sends readings that name their source, units and consistency, mapped by
335
+ `test-session` (`crates/audit-adapter/src/backends/test_session.rs`). They stay backend-reported. It
336
+ reads with a viewer credential the service refuses for writes. Final snapshots alone cannot establish
337
+ historical commitment properties; those need commit-ordered events or readings taken while an attempt
338
+ is unresolved, and otherwise stay inconclusive.
339
+
340
+ A reviewed financial profile (`payout-effects`, `payout-commitment` or `payout-effects-only`) sets the
341
+ required properties. `payout-effects-only` needs no adapter: the test must declare `exactly_one_effect`
342
+ or `no_effect`, the host refuses adapter readings, and the run is judged on the test provider's records alone
343
+ through `external_outcome` ([properties.md](properties.md)). Competing payments under it take no
344
+ capacity reading either: the test declares their shared limit or `no_shared_cap`, and each payment's
345
+ expected outcome, the first one bound being the payout judged. An undeclared cap is refused when the
346
+ competition is declared, before any payment is submitted (`competition_cap_undeclared`); the host never
347
+ reads or makes up a capacity to decide it. V3 admits these competitions; V2 refused every competition
348
+ under `payout-effects-only` (`competition_needs_readings`). A pass there is labelled money out only,
349
+ commitments not checked, in `ci-result.json` (`assurance`), the published `run.json`, the dashboard and the terminal.
350
+ `ci-result.json` records satisfied, violated, inconclusive and not applicable apart. CI passes
351
+ only when the test body passed, nothing is violated, `run.json` was published and every required
352
+ property is satisfied. Nothing tolerates an unresolved required property: there are no waivers, because
353
+ every gap either concerns independent evidence, withdraws a witness or leaves the payout unresolved.
354
+ Profiles live beside the admission gate, which requires a stored policy to equal the named profile
355
+ exactly. Both require `reconciliation_consistency`, which is what shows the payout resolved, so both
356
+ need a capacity reading; a run with no adapter can find a violation but cannot pass. Armed stimuli and a
357
+ seeded defect are recorded as steps and bound at admission, history reads bracket the effects read once
358
+ each, and a failure or death after a reported pass overrides it. These are consistency checks: the raw
359
+ record is not signed. `mandateops recheck` reproduces every field of `ci-result.json`, including whether
360
+ the report exists, and refuses a sealed run without a `teardown.json` for those exact bytes stating
361
+ its deployment was removed, so deleting the addendum or a failed teardown loses the result. Removal
362
+ means the daemon lists no container, network or volume under the run's project labels after `down`,
363
+ not only that `down` succeeded. `history`, `trace` and `export` state the same reading: anything but an addendum chained to
364
+ the seal saying removed is flagged, a hosted record whose seal is lost or unreadable included, and an
365
+ addendum `recover` wrote is tagged: `recheck` then confirms the record's consistency and reports
366
+ `deployment_removal`. `pass_withdrawn` is true where the seal said `ci_passed` and the deployment outlived its own teardown, and `recheck` then exits non-zero; a recovered run whose seal never passed has no pass to withdraw. The `ready` reply carries `recover_command`, the recovery line quoted for a shell, spelt from `--host-program`, the words the caller reached the host by, or this binary without it. An operational failure ends the session with a line carrying no `id`, `{"ok":false,"error":"host_failed_at_<stage>","terminal":true}`. A failed start adds `cause`:
367
+ `{"service":"<name>"|null,"exit_code":<int>|null,"excerpt":[...],"log":"<path>/compose.log"}`, read
368
+ from the `containers.json` and `compose.log` the lab kept as it removed the deployment. The excerpt
369
+ is the failing service's last error lines, at most 8 of at most 200 characters each. Teardown
370
+ redacts `compose.log` exactly first: every lab secret, every value the engine reports in a
371
+ container's environment (resolved Compose values and `env_file` entries included) and every
372
+ customer value of the deployment file, wherever it appears; a value under 8 characters is kept
373
+ unless its variable is a declared credential. Only once that succeeded, for at most 4096 values, does teardown write
374
+ `compose.log.exact`, and without it the excerpt is empty: the cause carries the service, its exit
375
+ code and the log path only. The excerpt is then redacted again by heuristics: credential keys, URL
376
+ user information, long mixed tokens and the rules of gitleaks v8.30.1 (vendored with its licence).
377
+ The CLI prints the same cause on stderr. A declaration whose
378
+ `providers` (`urlEnv`, `credentialEnv`), `credentialEnv` or `environment` names a reserved variable (prefixes `AUDIT_`,
379
+ `DOCKER_`, `COMPOSE_`, `BUILDKIT_`, `LD_`, `DYLD_`, or `PATH`, `HOME`, `SHELL`, `IFS`, `BASH_ENV`) is
380
+ refused before launch by the SDK and again by `session`, naming the field, the rule and a valid
381
+ example. The first `terminal` line answers every later message at once. A line with no `id` and no `terminal` refuses one unreadable message and the channel stays open, so a failed body still seals. The addendum
382
+ is chained, not signed. The drain is declared when the session starts, must
383
+ cover the deployment's declared quiescence, and a deployment declaring none is refused. A hosted test
384
+ scopes no provider record out: its deployment is its own. The journal survives a dying test and a
385
+ SIGTERM or SIGINT to the host; nothing yet rebuilds a run from it after SIGKILL of the host.