@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.
- package/LICENSE +55 -0
- package/README.md +175 -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 +143 -0
- package/audit-lab/lab/scripts/compose-lib.sh +632 -0
- package/audit-lab/lab/scripts/compose-up.sh +240 -0
- 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.
|