@awebai/oats 0.69.23 → 0.69.24

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 (74) hide show
  1. package/bin/oats.mjs +56 -17
  2. package/docs/capabilities.md +353 -5
  3. package/docs/capability-manifest.schema.json +36 -0
  4. package/docs/configuration.md +27 -7
  5. package/docs/design/2026-11-19-sandboxes.md +595 -121
  6. package/docs/design/2026-11-20-provider-home-lifecycle.md +320 -0
  7. package/docs/design/README.md +7 -3
  8. package/docs/desktop-cli-api.md +257 -9
  9. package/docs/desktop.md +181 -48
  10. package/docs/execution-targets.md +186 -3
  11. package/docs/first-team.md +11 -0
  12. package/docs/implementation.md +5 -1
  13. package/docs/integrations.md +2 -2
  14. package/docs/knowledge-capability-authoring.md +1 -1
  15. package/docs/knowledge-reference/proposal.md +10 -0
  16. package/docs/knowledge.md +20 -11
  17. package/docs/official-catalog.md +2 -2
  18. package/docs/packages.md +7 -7
  19. package/docs/release-notes/v0.69.24.md +264 -0
  20. package/docs/souls-and-instances.md +45 -0
  21. package/docs/tui.md +21 -1
  22. package/docs/upgrading.md +12 -5
  23. package/docs/workspaces.md +13 -5
  24. package/lib/capability-show.mjs +11 -1
  25. package/lib/command-flags.mjs +2 -2
  26. package/lib/compile-cache.mjs +1 -1
  27. package/lib/core.mjs +1176 -181
  28. package/lib/errors.mjs +4 -1
  29. package/lib/hook-env.mjs +106 -0
  30. package/lib/host-run.mjs +11 -3
  31. package/lib/instance-inspect.mjs +44 -0
  32. package/lib/instance-lifecycle.mjs +15 -3
  33. package/lib/instance-listing.mjs +97 -8
  34. package/lib/kernel-features.mjs +10 -1
  35. package/lib/node-version.mjs +9 -0
  36. package/lib/provider-call-child.mjs +60 -0
  37. package/lib/provider-resume.mjs +83 -0
  38. package/lib/provider-test-seams.mjs +20 -0
  39. package/lib/read-call.mjs +2 -0
  40. package/lib/reserved-launch-env.mjs +8 -1
  41. package/lib/retire-admission.mjs +5 -1
  42. package/lib/schedule.mjs +14 -4
  43. package/lib/servers.mjs +28 -4
  44. package/lib/session-inspect.mjs +104 -13
  45. package/lib/session-providers.mjs +528 -0
  46. package/lib/session-resume.mjs +68 -15
  47. package/lib/stable-node.mjs +3 -0
  48. package/lib/triggers.mjs +3 -1
  49. package/package-catalog.json +2 -2
  50. package/package.json +2 -1
  51. package/packages/client/capability-list.mjs +21 -0
  52. package/packages/client/cli-adapter.mjs +19 -4
  53. package/packages/client/cli-locator.mjs +5 -1
  54. package/packages/client/deployment-data.mjs +23 -1
  55. package/packages/client/deployment-panel.mjs +25 -3
  56. package/packages/client/home-board.mjs +33 -19
  57. package/packages/client/inspect-boundary.mjs +18 -8
  58. package/packages/client/instance-acts.mjs +30 -3
  59. package/packages/client/instance-board.mjs +206 -0
  60. package/packages/client/instance-presentation.mjs +55 -0
  61. package/packages/client/liveness.mjs +15 -4
  62. package/packages/client/own-codes.mjs +5 -1
  63. package/packages/client/remote-roster.mjs +6 -1
  64. package/packages/client/session-backends.mjs +31 -0
  65. package/packages/client/session-start.mjs +18 -6
  66. package/packages/client/spawn-apply-cli.mjs +5 -3
  67. package/packages/client/spawn-apply-contract.mjs +25 -2
  68. package/packages/client/spawn-apply.mjs +5 -1
  69. package/packages/client/spawn-messages.mjs +3 -0
  70. package/packages/client/terminal-contract.mjs +4 -0
  71. package/packages/client/waiting-on-you.mjs +12 -2
  72. package/packages/tui/lib/model.mjs +14 -3
  73. package/packages/tui/lib/store.mjs +12 -3
  74. package/skills/oats-getting-started/SKILL.md +3 -3
@@ -1,5 +1,17 @@
1
1
  # Sandboxes: boundaries declared in the workspace, started by `oats sync`
2
2
 
3
+ **Amended in r5 (2026-11-20), decided by both sides.** Placement no longer follows a
4
+ team. A sandbox lists the souls it may run, admits the capabilities their resolved
5
+ compositions need (with optional exclusions, behind an applied-plan gate), and has no
6
+ team. A soul's team is declared once, in `souls:`, and
7
+ placement never changes it. Messaging between agents is governed by aweb's policy,
8
+ whichever sandboxes they run in. What can an agent do? That's authorized per team or
9
+ per long-lived principal, by the resource's owner. This replaces the rule "a soul runs
10
+ in sandbox S when its resolved default team is S's team" everywhere below, and with it
11
+ C2's team routes. Items changed in r5 are marked "(r5)". The reviewed behaviour that
12
+ never depended on team placement is unchanged: the keyed replay, proof before a seat
13
+ is released (r4d), one owner of each schedule's clock, and explicit local selection.
14
+
3
15
  **Status:** contracts decided, 2026-11-19. The product owner's side and aweb's maintainers agreed
4
16
  C1–C10 and C3b as written at 0849ef12, with aweb's maintainers' four changes, which
5
17
  the product owner's side accepted: the registry setting (C3, C6), a keyed `seat` (C4), the receipt of the host's
@@ -36,32 +48,61 @@ use is scheduled knowledge-base ingestor agents on a cloud machine: they read un
36
48
  content, so they must not reach the engineers' agents, credentials or network.
37
49
 
38
50
  **Done means:** on a Linux machine with Docker, a workspace that declares one sandbox,
39
- and a deployment whose local file lists it, `oats sync` builds and starts the sandbox.
40
- A workspace schedule whose `runsOn` names that machine spawns its soul inside the
41
- sandbox, with an identity minted on the host. The agent can message only its own team,
42
- reach only the declared destinations and read only the declared credentials. Retiring
43
- it removes its identity from the team. Delisting the sandbox stops it and destroys
51
+ and a deployment whose local file lists it, `oats sync` builds and starts the sandbox,
52
+ and one reviewed `oats sync --admission-revision` admits its souls' capabilities (an
53
+ ordinary sync widens nothing, so the first tick needs that first admission). A workspace schedule whose `runsOn` names that machine spawns a soul the sandbox lists
54
+ inside it, with an identity minted on the host. The agent reaches only the declared
55
+ destinations and reads only the declared credentials. It messages only as its team,
56
+ its server and aweb's policy allow. For the ingestors that is a closed topology: their
57
+ own team on their own aweb server, with federation outbound off. That's a policy
58
+ configured for that use, not something placement implies (r5). Retiring the agent
59
+ removes its identity from the team. Delisting the sandbox stops it and destroys
44
60
  nothing. All of this is shown by a live rehearsal and by the tests pinned in each spec.
45
61
 
46
62
  ## Decided with the product owner
47
63
 
48
- - **A team is membership and messaging. A sandbox is the boundary** (its local state,
49
- credentials and egress). In v1 a team has at most one sandbox, so the two coincide by
50
- default. They stay separate primitives: a later layout can split one team across
51
- sandboxes by relaxing validation, with no change to the file format and no identity
52
- remint (decided 2026-11-19, agreeing to aweb's maintainers' requirement of 2026-11-18).
53
- - **Credentials in v1 are read-only files** mounted into the sandbox. Every agent in it
54
- can read them, which is acceptable with one team per sandbox (decided 2026-11-19).
64
+ - **Five separate decisions (r5).** A team is membership and messaging. A sandbox is a
65
+ runtime boundary (its local state, mounts and egress). Placement is which sandbox a
66
+ soul may run in. Identity is who an instance acts as. Authority is what it may do.
67
+ Each is declared and checked on its own (The design, "Five independent decisions").
68
+ This replaces "in v1 a team has at most one sandbox, so the two coincide" (decided
69
+ 2026-11-20 by both sides; the product owner's direction, and aweb's maintainers'
70
+ requirement of 2026-11-18).
71
+ - **The one-team limit is the v1 provider's, not the model's (r5).** The model admits
72
+ several teams in one sandbox, as co-resident trust the operator accepts. v1's
73
+ provider, teamctl, serves one team per sandbox, so in practice v1 still runs one
74
+ team per sandbox. That limit lifts when a provider serves several teams, and C1's
75
+ reference text and the release notes say so plainly (decided 2026-11-20).
76
+ - **`souls:` is the one declaration of a soul's team (r5).** Its `default` is the team
77
+ that soul's instances join, and its `teams` the others they may join. A pattern
78
+ entry sets them for a set of souls. A sandbox places souls and never changes their
79
+ team (decided 2026-11-20). Whether the key itself gets another name is a separate
80
+ question, outside this record.
81
+ - **Capabilities are derived from the souls, per soul (r5).** A sandbox admits each
82
+ listed soul's resolved composition at the lock's versions, less an optional
83
+ `excludeCapabilities`. Admission widens only when the operator applies a plan that
84
+ shows the change (C1, "The applied-plan gate"; decided 2026-11-20 by both sides).
85
+ - **Credential files are a bridge for the whole sandbox (r5).** v1 ships read-only
86
+ credential files mounted into the sandbox, because the first use has no other path
87
+ to its tokens. Every process in the sandbox can read them. Read-only stops writes,
88
+ not disclosure or use. A secret meant for one principal never goes through them
89
+ (Credentials; decided 2026-11-20, replacing "acceptable with one team per sandbox").
55
90
  - **OATS does not create or delete machines in v1.** Sync builds and starts listed
56
91
  sandboxes on a machine that already exists. Creating machines comes later, as a
57
92
  provider capability (decided 2026-11-19).
93
+ - **Kubernetes is a provider option (r5).** C4 is the contract a Kubernetes provider
94
+ implements, as Compose through teamctl does. Its qualification and release scope
95
+ are decided separately (decided 2026-11-20).
58
96
  - **Both broker contracts are designed in this effort**: one for secrets, one for
59
- connectors (decided 2026-11-18). Credential files remain the way to start.
60
- - **Messaging isolation is by server:** each isolated team gets its own aweb server
61
- with federation outbound off. This needs no aw contract change (decided 2026-11-17).
97
+ connectors (decided 2026-11-18). The connector broker stays designed only, with no
98
+ build and no verb until a real provider exists (decided 2026-11-20).
99
+ - **Messaging isolation is by server, when a workload wants it:** an isolated team gets
100
+ its own aweb server with federation outbound off. This needs no aw contract change
101
+ (decided 2026-11-17). It's a policy chosen for that workload (the ingestors), not a
102
+ consequence of placement (r5).
62
103
  - **Kept as they are:** the word "team"; the schedule file, with `runsOn` naming the
63
- machine and no lease; a sandbox does not list its own souls; there is no workspace
64
- list of shared deployments.
104
+ machine and no lease; there is no workspace list of shared deployments. A sandbox
105
+ now lists its own souls; only the earlier "automatic team" stays rejected (r5).
65
106
 
66
107
  ## What exists today, and what this builds on
67
108
 
@@ -95,6 +136,29 @@ nothing. All of this is shown by a live rehearsal and by the tests pinned in eac
95
136
 
96
137
  ## The design
97
138
 
139
+ ### Five independent decisions (r5)
140
+
141
+ | Question | Who decides, and how |
142
+ | --- | --- |
143
+ | What runs where? | The shared workspace names sandboxes and the souls each may run; the capabilities admitted for each soul are derived from its resolved composition, less any exclusions, and widen only through an applied plan. A machine's local file selects which declared sandboxes it runs, and nothing else. A spawn or a schedule selects a soul; if the soul is placed, it resolves to an eligible sandbox (C2). |
144
+ | What does the runtime isolate? | Each sandbox has its own name, workload, private state, and declared egress and mounts. Several sandboxes may run on one machine. Agents that share readable state, credential files or a process trust boundary are mutually trusted. |
145
+ | Who can communicate? | aweb team membership, service routes, and contact, inbound and federation policy. A sandbox needs egress to a service to reach it. Sharing a sandbox joins no team. Sharing a team neither colocates agents nor gives them each other's local state. |
146
+ | Who is acting? | The identity provider binds each instance to an authenticated principal, from that instance's identity configuration, resolved per instance. Its messaging context, the team it joins, is resolved separately, from `souls:` and the documented fallbacks. Neither comes from its sandbox. |
147
+ | What can the actor do? | The resource's owner grants operations, to a team or to a long-lived principal, and the broker or provider checks them at use. Placement, a capability, membership or an address grants nothing on its own. |
148
+
149
+ One team per sandbox is a useful starting layout, and tooling may generate it as
150
+ explicit placement. The contract admits the same team in several sandboxes, and
151
+ several teams in one sandbox when the operator accepts that they share one trust
152
+ boundary, subject to each sandbox's egress and the owners' grants. v1's provider
153
+ limits this (C8, "One served team"). The ingestors are the case of a separate sandbox
154
+ combined with a separate team, server and federation policy, chosen for that workload.
155
+
156
+ **The case a reader can test (r5).** A reviewer and a deployer are in one team and
157
+ placed in two sandboxes. They exchange the messages aweb allows. Each keeps its own
158
+ state, session material and mounts. The reviewer can't use the deployment
159
+ credential, and revoking the deploy grant stops the next deployment without moving
160
+ either agent. The Acceptance section pins this.
161
+
98
162
  ### Who does what
99
163
 
100
164
  | Piece | Owner | Does |
@@ -106,21 +170,31 @@ nothing. All of this is shown by a live rehearsal and by the tests pinned in eac
106
170
 
107
171
  ### Placement
108
172
 
109
- A soul runs in sandbox S when its resolved default team is S's team. Otherwise it runs
110
- on the host, as today. Placement is derived in v1; explicit placement, if it ever comes,
111
- is declared in the workspace and never in a machine's local file.
112
-
113
- - On a host that lists S and has it started, a spawn of such a soul (by hand, or by a
114
- schedule tick) is routed into S, as a remote spawn through S's server registration.
115
- S1 builds on #1912's floor (lane:juan, held): the task goes on stdin, the apply is
116
- bound to its preview and keyed, and a host below 0.69.15 is refused. This costs
117
- nothing, because the sandbox's kernel must already be the release with `sandboxes`.
118
- S1 may be built now, but does not merge before #1912. If #1912 is withdrawn, S1 itself requires the same
119
- three properties of the sandbox's kernel, rather than relying on today's fallbacks.
120
- - On a host that does not list S, the spawn is refused with `E_SANDBOX_NOT_HERE`, naming
121
- S and the local key that would list it. A sandboxed soul never falls back to the host.
122
- - Inside S, its deployment refuses to spawn any soul not placed in S
123
- (`E_SANDBOX_PLACEMENT`).
173
+ A soul runs in sandbox S when S's `souls` lists it (C1), S is selected for the spawn
174
+ (C2), and this host lists S. Otherwise, a soul that no sandbox lists runs on the host,
175
+ as today, apart from `E_SANDBOX_HOST_AGENT` (C10). Placement never follows a team, and
176
+ a machine's local file never moves a soul: it only chooses which declared sandboxes
177
+ the machine runs (r5, replacing the derived rule "a soul runs in S when its resolved
178
+ default team is S's team").
179
+
180
+ - On a host that lists the selected sandbox S and has it started, a spawn (by hand, or
181
+ by a schedule tick) is routed into S, as a remote spawn through S's server
182
+ registration. S1 builds on #1912's floor (lane:juan; its hold is lifted, and it is not yet merged): the task goes on stdin,
183
+ the apply is bound to its preview and keyed, and a host below 0.69.15 is refused.
184
+ This costs nothing, because the sandbox's kernel must already be the release with
185
+ `sandboxes`. S1 does not merge before #1912. If #1912 is withdrawn, S1 itself
186
+ requires the same three properties of the sandbox's kernel, rather than relying on
187
+ today's fallbacks.
188
+ - On a host that does not list S, the spawn is refused with `E_SANDBOX_NOT_HERE`,
189
+ naming S and the local key that would list it. A placed soul never falls back to
190
+ the host.
191
+ - **After placement, the provider checks it can serve the instance's messaging
192
+ context (r5).** Once the workspace's placement has selected S, the provider checks
193
+ that it can serve the team the instance joins (C6, C8). A context it can't serve
194
+ fails with a remedy. It never routes the spawn to another sandbox, changes the
195
+ agent's team or falls back to the host.
196
+ - Inside S, its deployment refuses a spawn of any soul S does not list, and a routed
197
+ request that names another sandbox (`E_SANDBOX_PLACEMENT`, C3b).
124
198
 
125
199
  ### The clock
126
200
 
@@ -136,9 +210,28 @@ Every instance in a sandbox has its own identity, minted on the host at spawn an
136
210
  removed at retire. The team's controller key and team key stay on the host, under the
137
211
  operator's account, and never enter the container.
138
212
 
213
+ **Whose identity (r5).** The seat binds the instance's own identity kind and messaging
214
+ context, resolved per instance, never from the sandbox's name, a team label or an
215
+ alias. In v1 the one kind a sandbox takes is a local member seat. Its team T is the
216
+ team the instance joins: its soul's resolved default (`souls:`, or the fallbacks
217
+ workspaces.md gives). The kernel resolves T and hands it to the provider in the seat
218
+ plan and the `seat` act (C4). Two kinds stay out of sandboxes in v1, each refused
219
+ before anything is minted, with a remedy:
220
+
221
+ - **Extra teams** (`join-not-seated`): a join mints a per-team identity from that
222
+ team's root, and no root enters a sandbox. So a spawn into a sandbox joins its
223
+ default team only. Seats for extra teams are a later layout.
224
+ - **A resident's grant seat** (`grant-seat-not-sandboxable`): a grant seat calls the
225
+ resident's custody service over a host-local Unix socket while it runs, not only at
226
+ mint (oats-aweb's resident and grant-seat docs). That socket must never enter a
227
+ sandbox, because it serves the resident's root key. A soul whose identity
228
+ configuration makes it a grant seat is refused in a sandbox until a qualified,
229
+ revocable remote delegation exists, which is aweb's to design. There is no
230
+ downgrade from resident to local.
231
+
139
232
  1. Before routing the spawn, the provider mints the instance's identity on the host
140
- from the host's root for the sandbox team (`roots[T]`), into a private staging
141
- directory. Where the sandbox team's registry is private, the host deployment sets
233
+ from the host's root for the instance's team (`roots[T]`), into a private staging
234
+ directory. Where that team's registry is private, the host deployment sets
142
235
  `settings.oats.aweb.registry` for the mint (C3).
143
236
  2. It delivers the identity's authority files (the same list retained seats copy
144
237
  today) and a seat descriptor into the sandbox's state, at
@@ -155,18 +248,34 @@ operator's account, and never enter the container.
155
248
  The exact order of a routed spawn, with the value each step binds (r2, r3):
156
249
 
157
250
  1. The kernel makes the spawn's idempotency key (`spawnKey`) and asks the provider for
158
- a seat plan (`plan`, target `seat`, with `instance: {soul, spawnKey}`). The plan is
159
- read-only and needs no instance name: it answers the seat ID (derived from
160
- `spawnKey`), its path and the `spawnProvider` options. Its `planRevision` fences
161
- only the sandbox's provider state and `spawnKey`.
162
- 2. The kernel runs the remote preview **with those options**. The preview chooses the
251
+ a seat plan (`plan`, target `seat`, with `instance: {soul, spawnKey, team}`, where
252
+ `team` is T, r5). The plan is read-only and needs no instance name: it answers the
253
+ seat ID (derived from `spawnKey`), its path and the `spawnProvider` options, or
254
+ refuses a team it can't serve (C8, `team-not-served`). Its `planRevision` fences the
255
+ sandbox's provider state, `spawnKey` and T.
256
+ 2. The kernel runs the remote preview **with those options**, and with
257
+ `--sandbox <S>`, the same selector as the outer spawn, naming the sandbox the host
258
+ placed it in (r5). The in-sandbox kernel compares it with its `self` (C3b), and a
259
+ different sandbox refuses at the preview with `wrong-sandbox`, before anything is
260
+ kept or minted. The selector is part of the decision, so `D` binds it, and the
261
+ apply carries the same `--sandbox <S>` from the kept request. The preview chooses the
163
262
  instance name when the caller gave none (a schedule passes `--purpose`, not
164
263
  `--name`), and answers `decision.revision`, `D`, the hash of the whole decision
165
264
  that the apply's `--expect-decision` must match, as #1912 requires. The in-sandbox
166
265
  kernel admits a preview that carries a seat option without reading the seat; only
167
266
  an apply needs it.
267
+ **The admission check (r5).** The preview's answer lists the composition the apply
268
+ will materialize: each module with its resolved id and source. `D` binds that
269
+ composition, because the apply's `--expect-decision D` refuses any other
270
+ (`E_DECISION_STALE`). So `D` is the gate's carrier into the sandbox, and the
271
+ in-sandbox kernel needs no new input. Before step 3, the host compares that
272
+ composition with the recorded admission entry for this sandbox and soul (C1, "The
273
+ applied-plan gate"), and with the current `excludeCapabilities`. A capability or a
274
+ source outside the entry refuses (`capability-not-applied`), an excluded one refuses
275
+ (`capability-excluded`), and nothing is kept, minted or applied.
168
276
  3. **Before anything is minted, the kernel keeps the whole routed request** (r3,
169
- contract): server, `spawnKey`, `D`, the exact argv and provider options, and the
277
+ contract): server, `spawnKey`, `D`, the composition `D` binds and the revision of
278
+ the recorded entry it was checked against (r5), the exact argv and provider options, and the
170
279
  task text, in `~/.oats/remote/<server>/pending/<spawnKey>.json` (0600, under the
171
280
  operator account, beside today's remote snapshots). It holds the task text, which
172
281
  #1912 took off argv for a reason, so: it is removed as soon as its seat settles
@@ -175,13 +284,33 @@ The exact order of a routed spawn, with the value each step binds (r2, r3):
175
284
  `sandbox-pending-stale`, naming the spawn key, never the task. S1 pins a test that
176
285
  its content never reaches a receipt, a log or a readiness line.
177
286
  4. The kernel runs `seat` with the plan's revision, `spawnKey` and
178
- `instance: {name, soul, decision: D}`. The name and `D` are inputs to the mint, not
179
- part of the plan's revision. The provider writes the ledger entry (`minting`, with
180
- `spawnKey`, `D`, the alias it will mint and the seat ID) before it mints, mints,
287
+ `instance: {name, soul, spawnKey, team, decision: D, settings}`. `settings` is the preview's
288
+ composed settings for the capability the seat plan named
289
+ (`spawnProvider.capability`), passed through unread, so the provider can refuse a
290
+ seat it must not mint (C6, r5). The name, `D` and `settings` are inputs to the mint,
291
+ not part of the plan's revision. The provider writes the ledger entry (`minting`, with
292
+ `spawnKey`, `D`, T, the alias it will mint and the seat ID) before it mints, mints,
181
293
  records the certificate ID, delivers, and moves the entry to `delivered`.
182
294
  5. The kernel runs the remote apply with `--expect-decision D` and
183
295
  `--idempotency-key spawnKey`, from the kept request, with the same provider options
184
296
  as the preview. No provider input changes between 2 and 5.
297
+ - **The request's in-flight lock (r5).** From step 3 until its seat settles in step 6,
298
+ the spawn holds an exclusive lock on its kept request. A reconcile skips a request
299
+ whose lock is held (`held-in-flight`), and replays or binds nothing for it. A lock
300
+ whose holder is gone is taken over, and its request is replayable again.
301
+ - **The apply-time admission fence (r5).** Under that lock, immediately before it
302
+ sends the apply, the host recomputes the admission inputs: the workspace's commit
303
+ and lock, the exclusions, and the recorded entry for this sandbox and soul. It
304
+ then rechecks the composition `D` binds against them. `D` fingerprints the
305
+ composition, not workspace policy, so this recheck is what catches an exclusion
306
+ committed between the seat and the apply.
307
+ - **When the fence refuses** (`capability-excluded` or `capability-not-applied`),
308
+ the apply is not sent. The kept request records every send durably before it's
309
+ made, so one with no recorded send, refused here under its lock, is proof that no
310
+ apply carrying `spawnKey` was ever sent. `bind` then gets that proof in place of an
311
+ answer (step 6).
312
+ - **Later edits:** an exclusion committed after this check applies to the next
313
+ spawn, as it does to a home already running.
185
314
  6. The kernel passes the apply's own answer to the provider (`bind`, C4), which acts
186
315
  on it by this table (r4, contract):
187
316
 
@@ -189,6 +318,7 @@ The exact order of a routed spawn, with the value each step binds (r2, r3):
189
318
  | --- | --- | --- |
190
319
  | Success, or the keyed replay of one | the home's `capabilityMeta["oats.aweb"].seat`, `{seatApi:1, seatId, certificateId, spawnKey}`, written by oats.aweb's spawn hook once the seat is connected, matching the ledger entry | `active` |
191
320
  | `E_DECISION_STALE` | the kernel's key recovery found no home holding `spawnKey` and refused before placing anything; the descriptor admits only that key (C6), so no home holds the seat | released (`spawn-failed`) |
321
+ | No apply sent: `{sent: false, code}`, from the admission fence, for a request with no recorded send (r5) | the host refused under the request's lock before any apply carrying `spawnKey` was made, and the request is deleted once the seat is released, so no home can hold the seat | released (`spawn-failed`) |
192
322
  | `E_REQUIRED_HOOK_FAILED` or `E_HOOK_ENVIRONMENT_CONTRACT` whose details carry no `unconfirmed: true` (r4d) | the spawn's rollback confirmed its home is gone, so no home holds the seat, whatever the hook did before it failed (oats.aweb's `seat-binding` refusal arrives this way) | released (`spawn-failed`) |
193
323
  | `E_IDEMPOTENCY_CONFLICT` (r4d) | a home already holds `spawnKey` under another decision and may hold the seat | stays `delivered` |
194
324
  | `E_SPAWN_INCOMPLETE`, a hook failure with `unconfirmed: true`, a failed or uncertain seat connect, any other refusal, or no answer | none of these proves that no home holds the seat | stays `delivered` |
@@ -218,7 +348,14 @@ The exact order of a routed spawn, with the value each step binds (r2, r3):
218
348
  `delivered`: a kept request whose entry is `minting` or `mint-uncertain` is never
219
349
  applied or replayed, and one whose seat was released is deleted. Each replay is
220
350
  unchanged, keyed by its `spawnKey`, and its answer goes to `bind` as in 6. A replay of an apply that was
221
- never sent is that apply, with its task, and a stale `D` refuses it terminally. The
351
+ never sent is that apply, with its task, and a stale `D` refuses it terminally.
352
+ Before each replay, the host runs step 5's admission fence under the request's
353
+ lock (r5). The recorded entry only widens or replaces a capability's source, so a source
354
+ replaced since, or an exclusion added since, can refuse the replay. A request with no recorded send that the fence refuses settles as in
355
+ step 6 ("No apply sent"). A replay of a request that was sent before, and fails the
356
+ fence, is not sent. Its request is kept and reported (`held-not-admitted`), and
357
+ its seat stays `delivered` (readiness, `sandbox-seat-unsettled`), because an
358
+ earlier send may have made a home that holds it. The
222
359
  provider never builds or replays a spawn itself. Absence of the instance's name, or
223
360
  an unused seat directory, is never evidence. A `delivered` seat with no kept request
224
361
  stays `delivered`, and readiness reports `sandbox-seat-unsettled`.
@@ -245,7 +382,7 @@ pins a kill after registration and before the receipt.
245
382
  Minting and removing identities need the host's keys, so in v1 the host is the only
246
383
  place a sandboxed instance is spawned from, and the host finishes every retire:
247
384
 
248
- - **Spawn inside the sandbox.** The in-sandbox deployment has no root for the team.
385
+ - **Spawn inside the sandbox.** The in-sandbox deployment has no root for any team.
249
386
  Its kernel accepts a spawn only when it carries a host-delivered seat (the routed
250
387
  spawn's `identity.seat`, C4 and C6). Any other spawn there, by an agent or by hand,
251
388
  is refused with `E_SANDBOX_PLACEMENT`, reason `spawn-from-host`, whose remedy is to
@@ -285,6 +422,38 @@ place a sandboxed instance is spawned from, and the host finishes every retire:
285
422
 
286
423
  ### Credentials (v1)
287
424
 
425
+ **Two routes, with different scopes (r5).**
426
+
427
+ - **The credential files are a bridge whose scope is the whole sandbox.** The
428
+ sandbox's reviewed entry in `oats-workspace.yaml`, `sandboxes.<id>.credentials`
429
+ (C1), is the explicit approval: committing it approves exposing each named file to
430
+ everything in that sandbox. Every process in the sandbox can read the files.
431
+ Read-only stops writes, not disclosure or use. The bridge can never provide a
432
+ per-principal secret, and a secret meant for one principal never goes through it.
433
+ It ships in v1 because the first use, the knowledge ingestors, has no other path to
434
+ its tokens: they reach the okf capability only as file settings today.
435
+ - **A per-principal secret goes through aweb's Secrets,** designed while its provider
436
+ is pending:
437
+ - A per-principal Secrets grant authorizes a defined operation in its verified
438
+ team/installation context.
439
+ - The secret may enter the environment of the designated, isolated runner job for
440
+ that operation. Its value stays out of the agent's ordinary environment, shared
441
+ mounts, persistent runtime metadata and results.
442
+ - A value injected into an agent process is a disclosure to that process, and must
443
+ be treated according to the actual execution boundary.
444
+ - The reviewed workspace credential-file entry approves exposure to the whole
445
+ sandbox trust group, and cannot provide a per-principal secret.
446
+
447
+ The sandbox reaches Secrets through the egress base role `secrets`, which teamctl
448
+ already declares. Egress permits access to the service; it changes neither the
449
+ grants nor the runtime's disclosure boundary. Per-principal enforcement is marked
450
+ designed until the provider exists. When it's built, its acceptance covers
451
+ co-resident agents as well as separate sandboxes (aweb's Secrets design, §4.6 and
452
+ §9; its runner protocol, §4.4).
453
+ - **Per team:** a team's credentials are a sandbox's files in a sandbox whose souls are
454
+ all that team's, or a grant to a Secrets role the team's owner assigns. Neither
455
+ needs a new OATS key. Ordinary membership never grants use.
456
+
288
457
  The workspace names a sandbox's credentials. The host's local file says where each
289
458
  value is. The provider mounts each named file read-only at `/run/oats-credentials/<name>`
290
459
  in that sandbox's agent container only. Nothing else gets a mount, and an undeclared or
@@ -386,7 +555,10 @@ Identities section) (r4d), so a self-retire is completed by the next sync even w
386
555
  (r3). A pinned test: a self-retire, then an otherwise no-op sync, removes the member.
387
556
 
388
557
  A sandbox declared in the workspace but not listed locally is never started. A sandbox
389
- listed earlier and now delisted is stopped, never destroyed. The provider keeps the
558
+ listed earlier and now delisted is stopped, never destroyed: its state and its
559
+ identities are kept. A later schedule tick whose spawn selects it is refused
560
+ (`E_SANDBOX_NOT_HERE`), and no provider receipt implies a retire or the removal of
561
+ compute (r5). The provider keeps the
390
562
  last declaration it started each sandbox with in its own state, so a sandbox whose
391
563
  workspace entry was removed together with its local listing is still stopped, from
392
564
  that record (r1). `oats sync --plan` shows
@@ -406,37 +578,152 @@ then, not here.
406
578
 
407
579
  ## The contracts (decided)
408
580
 
409
- ### C1. Workspace `sandboxes:` (new root key)
581
+ ### C1. Workspace `sandboxes:` (new root key; r5)
410
582
 
411
583
  ```yaml
412
584
  teams:
585
+ eng: { team: "eng:example.org" }
413
586
  ingest-team: { team: "ingest:example.org" }
414
- souls:
415
- knowledge/knowledge-ingestor: { default: ingest-team }
587
+ defaultTeam: eng
588
+ souls: # the one declaration of each soul's team
589
+ "*": { default: eng } # default: the team this soul's instances join
590
+ knowledge/*: { default: ingest-team } # a pattern sets it for a set of souls
591
+ knowledge/knowledge-reviewer: { default: eng, teams: [ingest-team] } # a deliberate bridge
416
592
  sandboxes:
417
593
  ingest:
418
- team: ingest-team # one sandbox per team in v1
419
- egress: [model, source, forge] # closed set, added to the base routes
420
- credentials: [sources-read, knowledge-propose] # names only
594
+ souls: [knowledge/knowledge-ingestor] # who may run here; never their team
595
+ excludeCapabilities: [acme-deploy] # optional: never admitted here
596
+ egress: [model, source, forge] # closed set, added to the base routes
597
+ credentials: [sources-read, knowledge-propose] # names only: a whole-sandbox bridge
421
598
  description: Knowledge ingestors # optional
422
599
  ```
423
600
 
424
- - The name matches `^[a-z0-9]$|^[a-z0-9][a-z0-9-]{0,30}[a-z0-9]$`. `team` must be a label in
425
- this file's `teams:`, and no other sandbox may name it (v1).
601
+ - **The key** is the sandbox ID, matching `^[a-z0-9]$|^[a-z0-9][a-z0-9-]{0,30}[a-z0-9]$`.
602
+ Its storage, status, server registration and lifecycle are keyed by that ID and the
603
+ deployment, never by a team label, a team ID or an agent alias.
604
+ - **`souls`** (required, non-empty) is the workspace's placement allowlist, and the one
605
+ place it is declared. Each entry is an exact soul reference as `souls:` keys spell a
606
+ single soul (`<member>/<soul>` or `<package>/<soul>`), never a pattern. Entries are
607
+ distinct (`duplicate-entry`). It makes a soul eligible to run here, and spawns
608
+ nothing: spawns and schedules still decide which instances run. A soul may be listed
609
+ by several sandboxes; C2 says how a spawn chooses. A reference no member or package
610
+ offers is reported by readiness (`sandbox-soul-unknown`), and a spawn of it is
611
+ refused (`E_SANDBOX_PLACEMENT`, `soul-unknown`).
612
+ - **Capabilities are derived, per soul (r5).** For each soul a sandbox lists, the
613
+ admitted capabilities are that soul's fully resolved composition (workspace defaults,
614
+ the soul's own layer and required dependencies) at the lock's versions. Each one is
615
+ identified by its resolved id and its authorized source, a canonical member or a
616
+ package. Admission is per (sandbox, canonical soul): one soul never rides on a
617
+ capability admitted for another, and the sandbox-wide union is for display only.
618
+ Package integrity and member trust are unchanged, and the gate adds no per-commit
619
+ consent for member code.
620
+ - **`excludeCapabilities`** (optional) names capabilities never admitted in this
621
+ sandbox. A soul whose composition needs one is refused (`E_SANDBOX_PLACEMENT`,
622
+ `capability-excluded`, naming the capability and the soul), never trimmed. The remedy
623
+ is a workspace soul, or a variant of one, whose composition doesn't need it, or a
624
+ reviewed change to the exclusion. The image's contents and the egress are separate
625
+ limits, and choosing software grants nothing.
626
+ - **The sandbox provider is composed like any default (r5).** A capability in the
627
+ workspace's `defaults`, the sandbox provider included (C4), is part of every listed
628
+ soul's resolved composition, and it's admitted by the same rule as the rest. Nothing
629
+ removes it. Inside a sandbox its `sandbox` hook is simply never called: a deployment
630
+ with `sandbox: {self}` runs no sandboxes (C3b). A sandbox that wants to keep it out
631
+ excludes it, and a soul that needs it is then refused, never trimmed.
632
+ - **The applied-plan gate.** Before minting a seat or starting a session through spawn
633
+ or a schedule tick, the kernel compares the actual resolved composition to the last
634
+ successfully applied plan entry for this sandbox and soul. Missing admission, a new
635
+ capability or a changed capability source refuses with `E_SANDBOX_PLACEMENT`,
636
+ reason `capability-not-applied`, naming the soul, the sandbox, the applicable
637
+ capability and source, and how to review and apply the updated plan (`oats sync
638
+ --plan`, then `oats sync --admission-revision <revision>`). The routed apply rechecks
639
+ the recorded entry for this sandbox and soul against what it will materialize: the host checks the
640
+ composition `D` binds, after the remote preview and before anything is kept or
641
+ minted, and again before each replay (Identities, steps 2 and 7). An explicitly excluded capability refuses as
642
+ `capability-excluded`. Never strip a capability to make a spawn pass. Narrowing
643
+ within the approved set needs no additional apply, and does not edit the recorded
644
+ plan.
645
+ - Only a successful, operator-authorized apply of the plan revision that shows the
646
+ change widens admission. A plan-only run, a failed sync, a schedule tick or a
647
+ recovery never does.
648
+ - Sync's plan, and readiness, show each soul's additions and source changes before
649
+ they're applied. Sandbox status and readiness show the recorded set and the
650
+ current derived set.
651
+ - **The admission revision and its commit (r5).** `oats sync --plan` answers one
652
+ admission revision for the whole sync, with the per-soul changes it would admit,
653
+ grouped by sandbox (C5). The revision is one hash over the entire admission plan:
654
+ the workspace's commit and the lock sync would install (the plan's lock) and, for
655
+ every listed sandbox and soul, its derived
656
+ set (ids and sources), the exclusions and the currently recorded entry.
657
+ - **Widening:** only `oats sync --admission-revision <revision>` widens admission,
658
+ and only when its revision equals the one the current inputs give, checked
659
+ after sync's own lock step. An upstream
660
+ change anywhere in the plan after it was reviewed changes the revision, so the
661
+ apply refuses all admission for that sync (`E_PLAN_STALE`, with the fresh
662
+ `admissionRevision` and changes in its detail) and records nothing. The refusal
663
+ is reported once in the answer's top-level `problems`, the rest of the sync
664
+ goes on, and sync exits nonzero.
665
+ - **First admission.** A listed soul with no recorded entry is a change of its
666
+ own (`first: true`), whatever its derived set, the empty set included. A missing
667
+ entry and a recorded empty entry are different states: the first refuses every
668
+ spawn (`capability-not-applied`), and the second admits a composition with no
669
+ capabilities. The first reviewed apply writes the entry.
670
+ - **The commit point:** a sync that applies an admission revision writes, in one
671
+ atomic write under sync's own lock, only the entries whose changes are
672
+ non-empty: a first admission, an added capability or a changed source. Each such entry records its
673
+ recorded set plus the additions, with the source changes applied, and the
674
+ revision. A capability the soul no longer derives stays recorded, so if the
675
+ soul derives it again from the same source it is admitted without a new apply,
676
+ because it was reviewed once already; from another source it is a
677
+ `sourceChanged` and needs one. An entry with
678
+ no additions or source changes keeps its recorded set and revision, so
679
+ narrowing never edits the recorded plan. The write happens only when the whole
680
+ sync has succeeded, with no problem in any sandbox. A sync that fails
681
+ anywhere writes none. Its infrastructure changes stand, as they always have,
682
+ and a later sync with a fresh revision applies the admission. So when sandbox A
683
+ succeeds and sandbox B fails, A's admission isn't widened either.
684
+ - **The commit fence.** The rows written are the ones captured from the exact
685
+ plan whose revision matched, and they are never re-resolved for writing. Under
686
+ sync's lock, immediately before the write, the kernel recomputes the hashed
687
+ inputs and compares them with the plan's inputs as sync applied them. Sync's
688
+ own lock and package steps are not a change; an edit from outside sync is. If
689
+ any input changed that way while the sync ran (a member's composition, the
690
+ lock, an exclusion or this host's listing), the whole admission is refused as
691
+ `E_PLAN_STALE` and nothing is written. No newer or partly recomputed plan is ever
692
+ written under the earlier revision.
693
+ - **Where they live:** in the host deployment's own state, per sandbox and soul.
694
+ The in-sandbox kernel never reads them: the host checks them against what `D`
695
+ binds (Identities, step 2).
696
+ - **Sync without the flag** applies everything else and widens nothing. It reports
697
+ each pending change as a warning (readiness, `sandbox-admission-pending`).
698
+ Narrowing writes nothing.
699
+ - An unattended sync that applies its own plan would admit changes without review,
700
+ weakening the gate to "since the last apply". A deployment that wants the gate
701
+ keeps the apply operator-authorized.
702
+ - **No team (r5).** A sandbox has no `team` field. `souls:` is the one declaration of
703
+ each soul's team (Decided with the product owner), and placing a soul never changes
704
+ it. The `team` field of the earlier, unreleased shape is refused when the file is
705
+ read (`E_WORKSPACE_SCHEMA`, reason `sandbox-team-field`). The remedy names the
706
+ migration: the souls whose default team it was go in `souls`, under the same sandbox
707
+ ID. There's no silent inference from a team.
708
+ - **One served team, in v1 (r5).** The model admits several teams in one sandbox. v1's
709
+ provider, teamctl, serves one team per sandbox (C8), so in practice v1 runs one team
710
+ per sandbox. That's the provider's limit, not the model's, and it lifts when a
711
+ provider serves several teams. C1's reference text and the release notes say so.
426
712
  - `egress` is a subset of `{model, source, forge}` (`forge` behind feature
427
713
  `sandbox-egress-forge`), because those are the external roles the egress component
428
- supports. Adding another destination is a change to the egress
429
- component, not a free-form list.
430
- - `credentials` names match `^[a-z0-9][a-z0-9-]{0,62}$`, and are distinct.
431
- - **A team not yet created (r2).** A shared team may omit its provider id (declared,
432
- not created). A sandbox may name such a team: the workspace stays valid, so other
433
- hosts are not refused. Its start refuses (`E_SANDBOX_TEAM`, reason
434
- `team-not-created`), and so does a routed spawn, with the existing remedy: its owner
435
- runs `oats aweb setup`, then commits the id. The id is never inferred from the label
436
- or an active team. Until it is set, C2's checks compare the label.
437
- - `team` is required. `egress` and `credentials` are optional and default to `[]`;
438
- `egress` entries are distinct. A duplicate in either list is refused (reason
439
- `duplicate-entry`) (r1).
714
+ supports. Adding another destination is a change to the egress component, not a
715
+ free-form list.
716
+ - `credentials` names match `^[a-z0-9][a-z0-9-]{0,62}$`, and are distinct. Committing
717
+ them approves exposing each file to the whole sandbox (Credentials).
718
+ - `egress`, `credentials`, `excludeCapabilities` and `description` are optional; the
719
+ lists default to `[]`. A duplicate in any list is refused (reason `duplicate-entry`)
720
+ (r1).
721
+ - **A team not yet created (r2, r5).** A shared team may omit its provider id
722
+ (declared, not created). A soul whose team has none stays valid, so other hosts are
723
+ not refused. A routed spawn of it refuses (`E_SANDBOX_TEAM`, reason
724
+ `team-not-created`), and so does a start whose provider would serve that team (C8),
725
+ with the existing remedy: its owner runs `oats aweb setup`, then commits the id. The
726
+ id is never inferred from the label or an active team.
440
727
  - It is closed (`additionalProperties: false`), like every workspace block. An older
441
728
  kernel refuses the file with `E_WORKSPACE_SCHEMA` and its existing "upgrade OATS"
442
729
  hint, which is the error that tells existing deployments what to do.
@@ -450,27 +737,40 @@ sandboxes:
450
737
  `oats version --json` on each host lists `sandboxes`.
451
738
  - Feature `sandboxes` in `oats version --json`.
452
739
 
453
- ### C2. The three ways round a sandbox are refused (aweb's maintainers' edge cases)
454
-
455
- All are refused when the workspace file is read, with `E_WORKSPACE_SCHEMA` and a reason
456
- code:
457
-
458
- 1. **A sandboxed team as a soul's extra team** (`teams: [ingest-team]`): refused, reason
459
- `sandboxed-team-not-default`. The `"any"` value means every shared team without a
460
- sandbox. An explicitly declared bridge is not in v1.
461
- 2. **A sandboxed team reached through a wildcard or the default:** a `"*"` or
462
- `<member>/*` entry whose `default` is a sandboxed team, and a workspace `defaultTeam`
463
- that is one, are refused (reason `sandboxed-team-by-wildcard`). A sandboxed team is
464
- reached only through a named soul (`<member>/<soul>`).
465
- 3. **A local override:** an `oats-local.yaml` cannot move a sandboxed soul. Local files
466
- have no soul-to-team mapping today, and a local `defaultTeam` already loses to a
467
- soul's `souls:` default. A local team may not reuse a sandboxed team's label or
468
- provider id (reason `sandboxed-team-local`).
469
- 4. **A shared alias (r1):** two shared labels may today name one provider id. A
470
- sandboxed team's provider id must be named by exactly one shared label; another
471
- shared label with that id is refused (reason `sandboxed-team-alias`). Every check
472
- above, and placement, compare provider ids, never labels alone, so two sandboxes
473
- cannot name one team through two labels either (reason `sandbox-team-taken`).
740
+ ### C2. Choosing a sandbox (r5: replaces the team routes)
741
+
742
+ A soul's **eligible sandboxes** are the workspace's sandboxes whose `souls` lists it.
743
+ The choice is made from the shared workspace, at the spawn or the schedule, before
744
+ anything happens:
745
+
746
+ - **None:** the soul is a host soul. It runs on the host as today, apart from
747
+ `E_SANDBOX_HOST_AGENT` (C10).
748
+ - **Exactly one:** it's inferred.
749
+ - **More than one:** the spawn names its target. That's `oats spawn <soul> --sandbox
750
+ <id>`, and a `run: spawn` schedule's `sandbox: <id>` field, both new contracts (the
751
+ CLI, and the schedule file). A spawn without one is refused (`E_SANDBOX_PLACEMENT`,
752
+ reason `sandbox-ambiguous`, naming the candidates and the flag or field). It's
753
+ refused even when this host lists only one of the candidates: a local file never
754
+ chooses a placement.
755
+ - **A named target** that the workspace doesn't declare (`sandbox-unknown`), or that
756
+ doesn't list the soul (`sandbox-not-eligible`), is refused with
757
+ `E_SANDBOX_PLACEMENT`. Both remedies list the soul's eligible sandboxes and say to
758
+ name one of them. `sandbox-not-eligible` also says the soul can be added to that
759
+ sandbox's `souls` in the workspace, by a reviewed change. A target this host doesn't list is refused with
760
+ `E_SANDBOX_NOT_HERE`. Each refusal comes before any effect, and none falls back to
761
+ the host.
762
+ - `runsOn` still names the one machine that owns a schedule's clock. `sandbox:` names
763
+ only where its spawn runs.
764
+
765
+ **Withdrawn (r5).** C2's team routes go: `sandboxed-team-not-default`,
766
+ `sandboxed-team-by-wildcard`, `sandboxed-team-local`, `sandboxed-team-alias` and
767
+ `sandbox-team-taken`. So does the rule that `"any"` excludes sandboxed teams. They
768
+ existed only because placement followed the default team. Now a team reached through
769
+ a wildcard, an extra team or a local default places nothing, and an eligible extra
770
+ membership is never a way to a placement or a grant. Operators who want a narrower
771
+ communication policy configure it on the messaging service and in egress. Messages
772
+ aweb allows can carry data between sandboxes, so separate storage promises no data
773
+ isolation across a permitted conversation.
474
774
 
475
775
  ### C3. `oats-local.yaml`: `sandboxes` and `credentials` (new root keys)
476
776
 
@@ -494,12 +794,14 @@ settings:
494
794
  - `sandboxes` lists distinct names that the workspace declares. An unknown name is
495
795
  refused (`E_WORKSPACE_SCHEMA`, reason `sandbox-unknown`), a duplicate likewise
496
796
  (`duplicate-entry`), and so is a listed sandbox with no `host.name` (reason
497
- `sandbox-host-name-required`) (r1).
797
+ `sandbox-host-name-required`) (r1). The list selects which sandboxes this machine
798
+ runs, and nothing else: it holds sandbox IDs and infrastructure facts only, and it
799
+ can't place, move or choose between souls (C2, r5).
498
800
  - `credentials` uses the kernel's existing `fromFile` form. A listed sandbox whose
499
801
  declared credential has no source here refuses its start, naming the credential.
500
802
  - The teamctl file holds infrastructure only (images, network, ports, state directory,
501
803
  limits). The provider refuses a file that sets a boundary field the workspace owns
502
- (`team.id`, the role booleans `egress.external.source`, `.model` and `.forge`,
804
+ (`team.id`, which v1's provider derives from the souls the sandbox lists (C8, r5); the role booleans `egress.external.source`, `.model` and `.forge`,
503
805
  `aweb.federationOutbound`): boundaries are declared once. The refusal is
504
806
  `E_SANDBOX_DEPLOYMENT`, reason `boundary-field`, naming the field (r1). The
505
807
  resolvers the external roles need, `egress.external.resolvers`, are host
@@ -509,7 +811,7 @@ settings:
509
811
  the workspace. Example: `egress: { external: { resolvers: [1.1.1.1, 9.9.9.9] } }`
510
812
  in the teamctl file, with C1's `egress: [model, source, forge]`.
511
813
  - **A private registry.** oats.aweb refuses an ambient `AWID_REGISTRY_URL`
512
- (awebai/oats-aweb#284), so where the sandbox team's registry is private the setting
814
+ (awebai/oats-aweb#284), so where the instance's team's registry is private the setting
513
815
  is written twice: `settings.oats.aweb.registry` on the host deployment, for the mint
514
816
  and for `remove-member` (C6), and the same key in the sandbox's `settings`, which the
515
817
  provider writes into the in-sandbox local file. Without the in-sandbox one, the
@@ -521,7 +823,23 @@ The provider writes it into the in-sandbox deployment's local file. It is a cont
521
823
  its own because a kernel reads it:
522
824
 
523
825
  - `self` must name a sandbox the workspace declares. That deployment then spawns only
524
- souls placed in that sandbox, and refuses others with `E_SANDBOX_PLACEMENT`.
826
+ souls that sandbox's `souls` lists, with the capabilities admitted for them, and refuses
827
+ others with `E_SANDBOX_PLACEMENT`, reason `not-placed-here` (r5), whose remedy says
828
+ to spawn it from the host into a sandbox that lists it. A routed request must name
829
+ the sandbox, soul and composition its preview showed, and its sandbox must equal
830
+ `self`. The sandbox reaches the in-sandbox kernel as `--sandbox <S>` on both the
831
+ remote preview and the apply (Identities, step 2); a request carrying a seat option (a
832
+ routed request) without `--sandbox` is refused with `E_SANDBOX_PLACEMENT`,
833
+ `wrong-sandbox`, and `D` binds the selector. An ordinary local spawn without a host-delivered
834
+ seat is not subject to the routed selector check. It remains subject to the placement
835
+ check and to the host-delivered-seat requirement (Lifecycle calls made inside a
836
+ sandbox, `spawn-from-host`). One that names another sandbox is refused with `E_SANDBOX_PLACEMENT`,
837
+ reason `wrong-sandbox`, even when the soul is eligible in both. Its remedy says the
838
+ host routed it to the wrong registration, and to check the host's `sandbox-<name>`
839
+ server entry (C7). Nothing is spawned. `D`
840
+ already binds the composition, and the `self` check refuses a request that names
841
+ another sandbox. A request through the sandbox's own deployment can never place a
842
+ soul on the host or in another sandbox.
525
843
  - It may not be combined with `sandboxes:` (a sandbox runs no sandboxes),
526
844
  `credentials:` (credentials reach it as mounts only), local `teams:` or local
527
845
  `defaultTeam`. Each combination is refused with `E_WORKSPACE_SCHEMA`, reason
@@ -554,21 +872,28 @@ hook that exits nonzero, times out or prints anything but one valid answer is re
554
872
 
555
873
  ```json
556
874
  {"sandboxApi":1,"act":"start","sandbox":"ingest","host":"cloud-1",
557
- "team":{"label":"ingest-team","id":"ingest:example.org"},
875
+ "souls":[{"soul":"knowledge/knowledge-ingestor",
876
+ "team":{"label":"ingest-team","id":"ingest:example.org"}}],
877
+ "excludeCapabilities":["acme-deploy"],
558
878
  "egress":["model","source"],
559
879
  "credentials":[{"name":"sources-read","path":"/srv/…"}],
560
880
  "workspace":{"url":"…","commit":"…","lock":"<sha256>"}}
561
881
  ```
562
882
 
883
+ There's no sandbox-wide `team` (r5). `souls` carries each listed soul with the team
884
+ its instances join, as the kernel resolved it from `souls:`, so a provider that serves
885
+ one team (C8) can check what it would serve. The kernel never derives an identity
886
+ from the sandbox's name, a team label or an alias.
887
+
563
888
  and by act:
564
889
 
565
890
  | Act | Extra request fields | Answer fields beyond the envelope |
566
891
  | --- | --- | --- |
567
- | `plan` | `target`: `start`, `stop`, `reconcile`, `seat`, `bind` or `release`; for target `seat`, `instance: {soul, spawnKey}`; for `bind` and `release`, the `instance` fields of that act | `planRevision`, `actions: [{step, detail}]`; for target `seat` also `seat: {id, path}` and `spawnProvider: {capability, options: {<key>: <value>}}` |
892
+ | `plan` | `target`: `start`, `stop`, `reconcile`, `seat`, `bind` or `release`; for target `seat`, `instance: {soul, spawnKey, team}` (r5); for `bind` and `release`, the `instance` fields of that act | `planRevision`, `actions: [{step, detail}]`; for target `seat` also `seat: {id, path}` and `spawnProvider: {capability, options: {<key>: <value>}}` |
568
893
  | `start`, `stop`, `reconcile` | `planRevision`, `idempotencyKey` | `server`; for `reconcile`, `seats` as in `status` |
569
- | `status` | none | `server`, `seats: [{seatId, instance, alias, certificateId, state}]` |
570
- | `seat` | `planRevision`, `idempotencyKey`, `instance: {name, soul, spawnKey, decision}` (`decision` is `D`, the remote preview's `decision.revision`) | `seat: {id, path, alias, certificateId, team}` |
571
- | `bind` | `planRevision`, `idempotencyKey`, `instance: {name, spawnKey}`, `apply`: the routed apply's answer as the kernel received it | `seat: {id, certificateId, state}` |
894
+ | `status` | none | `server`, `seats: [{seatId, instance, alias, certificateId, team, state}]` |
895
+ | `seat` | `planRevision`, `idempotencyKey`, `instance: {name, soul, spawnKey, team, decision, settings}` (`decision` is `D`, the remote preview's `decision.revision`; `team` is the team the instance joins; `settings` is the preview's composed settings for the seat's capability, passed unread; r5) | `seat: {id, path, alias, certificateId, team}` |
896
+ | `bind` | `planRevision`, `idempotencyKey`, `instance: {name, spawnKey}`, `apply`: the routed apply's answer as the kernel received it, or `{sent: false, code}` when the admission fence refused a request with no recorded send (r5) | `seat: {id, certificateId, state}` |
572
897
  | `release` | `planRevision`, `idempotencyKey`, `instance: {name, seatId}`, `reason`: `retired` or `spawn-failed` | `seat: {id, certificateId, state}` |
573
898
 
574
899
  **The envelope** of every answer:
@@ -608,13 +933,33 @@ and by act:
608
933
 
609
934
  - `oats sandbox status [--json]`, `oats sandbox start|stop <name> (--plan | --plan-revision <r> --idempotency-key <k>)`.
610
935
  - `oats sandbox status --json` answers
611
- `{sandboxApi:1, host, sandboxes:[{name, team:{label,id}, listedHere, state, server, egress, credentials:[{name, source:"present"|"missing"}], problems}]}`.
936
+ `{sandboxApi:1, host, sandboxes:[{name, souls, excludeCapabilities, admission:[{soul, recorded:[{id, source}], current:[{id, source}]}], listedHere, state, server, egress, credentials:[{name, source:"present"|"missing"}], problems}]}`.
937
+ `admission` shows, per soul, the set the last applied plan recorded and the set
938
+ derived now. The sandbox-wide union is the client's to display.
939
+ A sandbox has no `team` (r5): what the sandbox allows (`souls`, `excludeCapabilities`, `admission`) is
940
+ shown apart from the team each instance actually joined, which is on its seat
941
+ (`seats[].team`). The answer's readers change with it (below).
942
+ - `oats spawn <soul> --sandbox <id>` selects among a soul's eligible sandboxes, and a
943
+ `run: spawn` schedule's `sandbox: <id>` does the same (C2, r5). Both are new
944
+ contracts. Inside a sandbox, the host's routed preview and apply carry the same
945
+ `--sandbox <S>`, which must equal `self` (C3b). `--sandbox` is refused together with `--server`, which names a target of
946
+ its own (`E_BAD_ARGS`). That refusal applies to the caller's argv; the routed
947
+ preview and apply run inside S with `--sandbox` and no `--server`.
612
948
  - `oats sandbox start|stop <name> --plan --json` answers
613
949
  `{sandboxApi:1, sandbox, act, planRevision, actions}`; the apply answers
614
950
  `{sandboxApi:1, sandbox, act, state, server, receipts, problems}`, and a stale
615
951
  revision refuses `E_PLAN_STALE` with the fresh plan in its detail (r1).
616
952
  - `oats sync --json` gains `sandboxes` with the same entries plus `action`
617
- (`build|start|stop|none`). The field is additive, so `syncApi` stays 1.
953
+ (`build|start|stop|none`), and, in a plan, the admission it would apply: each
954
+ sandbox entry carries `admissionChanges: [{soul, first, added:[{id, source}], sourceChanged:[{id, from, to}]}]`
955
+ (`first: true` for a soul with no recorded entry, whose `added` is its whole derived
956
+ set, excluded capabilities omitted since they refuse at spawn regardless, possibly
957
+ empty),
958
+ and the answer carries one top-level `admissionRevision`, the hash of the whole
959
+ admission plan (C1) (r5). `oats sync --admission-revision <revision>` takes that one value and
960
+ applies all of it or none (C1, "The applied-plan gate"), and a sync without the
961
+ flag widens nothing. The fields are additive, so
962
+ `syncApi` stays 1; the flag is new.
618
963
  - `oats status --json` gains `placement: {sandbox, seatId}` on each instance placed in
619
964
  one; `seatId` is the seat its home took (r2).
620
965
  - `oats sandbox status --json`'s entries also carry `seats` (as C4's `status`), and
@@ -630,7 +975,10 @@ and by act:
630
975
  lists every reader it finds, with file and line, and pins one test per reader feeding
631
976
  it an answer with the new fields. If a reader refuses unknown fields, the change is
632
977
  not additive: that answer's API version goes up, and the reader changes first, in its
633
- own PR.
978
+ own PR. The sandbox status answer had no released shape, so dropping `team` breaks
979
+ no release. The two client readers already merged for this effort (#2016, sync's
980
+ exit; #2021, a spawn refusal's words) read no `team`. S1 checks both against r5's
981
+ shape, including the new `E_SANDBOX_PLACEMENT` reasons (r5).
634
982
 
635
983
  ### C6. oats.aweb settings and behaviour
636
984
 
@@ -642,8 +990,10 @@ and by act:
642
990
  - **The seat descriptor (r2).** The retained route reads its service from the
643
991
  source's `workspace.yaml`, which is not an authority file. A delivered seat instead
644
992
  carries `seat.json`, written by the host at mint:
645
- `{seatApi:1, seatId, spawnKey, service, team, alias, certificateId}`, where `service`
646
- is the aweb origin of the sandbox's own server (the egress `aweb` role's origin).
993
+ `{seatApi:1, seatId, spawnKey, service, team, alias, certificateId}`, where `team` is
994
+ the team the instance joins and `service` is that team's aweb origin. That origin is
995
+ one the sandbox's egress `aweb` role admits, and in v1 it's the sandbox's own server
996
+ (C8, r5).
647
997
  The spawn reads its service from that descriptor only, never from `OATS_AWEB_URL` or
648
998
  a copied coordination workspace, and checks it: `team` equals the team the spawn
649
999
  resolved, `alias` equals the instance name, `spawnKey` equals the apply's key, and
@@ -655,6 +1005,18 @@ and by act:
655
1005
  the descriptor it validates. A missing, malformed or contradictory descriptor
656
1006
  refuses the spawn (reason `seat-binding`, naming the field). The host's registry pin
657
1007
  is a separate setting (C3), never the service.
1008
+ - **Seats a sandbox doesn't take in v1 (r5),** refused by `seat` before anything is
1009
+ minted, from the `settings` it's handed (step 4):
1010
+ - A spawn into a sandbox that asks to join a team beyond its default (`join=`):
1011
+ `E_SANDBOX_PLACEMENT`, reason `join-not-seated`. The remedy says that extra-team
1012
+ seats are a later layout, and that the soul's other teams stay eligible on the host.
1013
+ - A soul whose identity settings make it a resident's grant seat:
1014
+ `E_SANDBOX_PLACEMENT`, reason `grant-seat-not-sandboxable`. The remedy says to run
1015
+ it on the host, or to remove it from the sandbox's `souls`, until a qualified
1016
+ remote delegation exists. There's no downgrade from resident to local.
1017
+ The provider removes only a membership it minted for a disposable seat and can prove
1018
+ it owns. Stop, restart and removing a sandbox never retire a resident or revoke its
1019
+ other memberships.
658
1020
  - Retire, for an identity minted by the host for a sandbox: the host runs
659
1021
  `aw id team remove-member` with the controller key it holds, and reports it, from
660
1022
  the routed retire or from reconcile (the Lifecycle section). It
@@ -734,9 +1096,49 @@ existing Docker-context SSH relay from container.md.
734
1096
  - teamctl's changes are these three inputs: `agents.credentials`,
735
1097
  `agents.protectedSourcesFile` and `egress.external.forge`. OATS reads its exit codes
736
1098
  as they are.
1099
+ - **One served team (r5): v1's provider limit, not the model's.** teamctl runs one
1100
+ team's bundle: its aweb server, egress and agent container. So `oats.aweb-sandbox`
1101
+ takes the bundle's team from the souls the sandbox lists (C4's request carries each
1102
+ one's team). It writes it as teamctl's `team.id`, which no host file may set (C3).
1103
+ - **What it refuses:** `oats sandbox start`, sync's start, the seat plan and `seat`
1104
+ refuse, before any seat, a sandbox whose souls join more than one team, or a team
1105
+ whose service isn't the bundle's: `E_SANDBOX_TEAM`, reason `team-not-served`. Each
1106
+ case has its own remedy, and neither changes a team or moves a spawn:
1107
+ - **Several teams:** the remedy names the teams found, and says to list the other
1108
+ team's souls in a sandbox of their own.
1109
+ - **Another service:** the remedy names the team's service and the bundle's
1110
+ server. It says to place that team's souls in a sandbox whose bundle serves that
1111
+ service, or to point this sandbox's bundle at it.
1112
+ - **What the limit covers:** only the combinations of membership inside one sandbox.
1113
+ Messaging between agents of one team in separately placed sandboxes stays
1114
+ governed by aweb's policy.
1115
+ - **A separate question:** whether teamctl can run two sandboxes for one team (two
1116
+ bundles, one team's server) is aweb's maintainers' to say. Until they do, the
1117
+ Acceptance case "same team, separate sandboxes" is pending for v1's provider.
1118
+ - A start never mints a team. The provider reaches only the service origins its plan
1119
+ names, with no ambient URL fallback. A runtime that can build only a team bundle
1120
+ reports that limit before it admits a seat, and never claims independent placement
1121
+ it can't deliver.
737
1122
 
738
1123
  ### C9. Broker contracts (designed now, built against the first real provider)
739
1124
 
1125
+ **Authority (r5).** Both brokers check the verified actor, its acting team or
1126
+ installation context, the operation and resource it is authorized for, and its current
1127
+ grant or session scope, plus any approval required. They check at admission and again
1128
+ at dispatch, fail closed on missing, ambiguous, expired or revoked authority, and
1129
+ record the decision without returning a secret value.
1130
+ - **Scope:** team scope is a policy the owner authorizes within that team's
1131
+ installation. Identity scope is a grant to one stable principal, with any required
1132
+ team context still verified. A grant in one team can't be spent in another because
1133
+ the DID matches.
1134
+ - **Delegation:** asking a more privileged agent over messaging doesn't authorize it to
1135
+ act for the caller; an explicit delegation must cover the operation.
1136
+ - **Revocation and replacement:** revocation denies new dispatches at the applicable
1137
+ fence, though effects already dispatched may complete. Replacing a resident's
1138
+ runtime session keeps its principal without widening its authority.
1139
+ - **No fallback:** a missing broker or an unsupported provider is reported as
1140
+ unavailable, never replaced by a shared mounted file.
1141
+
740
1142
  Both follow aweb's three rules. An agent never reads or exports a value. Approval is a
741
1143
  state with a reference, and the same request is resubmitted under the same request ID.
742
1144
  Authority, custody, approval, where execution happens, audit and withholding all stay
@@ -783,13 +1185,20 @@ egress routes only.
783
1185
  ID (r4d: one whose delivered copy could not be confirmed deleted stays here); a
784
1186
  `delivered` seat with no kept request, including one whose release waits on a copy
785
1187
  deletion that could not be confirmed; or a `delivered` seat whose last replay
786
- answered `E_IDEMPOTENCY_CONFLICT` or `E_SPAWN_INCOMPLETE` (r2, r3, r4d). A pinned
1188
+ answered `E_IDEMPOTENCY_CONFLICT` or `E_SPAWN_INCOMPLETE` (r2, r3, r4d); or a
1189
+ `delivered` seat whose kept request was sent before and is now `held-not-admitted`
1190
+ (r5). A pinned
787
1191
  negative: a known certificate ID whose copy deletion fails gives no replay, no home,
788
1192
  and this item;
789
1193
  - `sandbox-state-orphaned`: provider state under another deployment key for a
790
1194
  sandbox this deployment lists (r2);
791
1195
  - `sandbox-pending-stale`: a kept routed request older than 24 hours, named by its
792
- spawn key, never its task (r3).
1196
+ spawn key, never its task (r3);
1197
+ - `sandbox-soul-unknown`: a sandbox's `souls` names a soul no member or package
1198
+ offers (r5);
1199
+ - `sandbox-admission-pending`: a listed soul with no recorded entry yet, or one whose
1200
+ current derived capabilities add a capability, or change one's source, beyond the
1201
+ last applied plan, with the first admission, additions and changes listed (r5).
793
1202
 
794
1203
  The refusals belong to the acts:
795
1204
 
@@ -809,29 +1218,62 @@ The refusals belong to the acts:
809
1218
  | An unkeyed apply carrying `identity.seat` (r3) | the in-sandbox apply | `seat-binding` (oats.aweb), field `spawnKey` |
810
1219
  | `sandbox-<name>` registered by someone else (r1) | `oats sandbox start`, sync's start | `E_SANDBOX_SERVER`, `server-taken` |
811
1220
  | `sandbox-<name>` owned by another deployment (r2) | `oats sandbox start`, sync's start | `E_SANDBOX_SERVER`, `server-owned-elsewhere` |
812
- | The sandbox's team has no provider id yet (r2) | `oats sandbox start`, sync's start, a routed spawn | `E_SANDBOX_TEAM`, `team-not-created` |
1221
+ | The team an instance joins, or the team a start would serve, has no provider id yet (r2, r5) | `oats sandbox start`, sync's start, a routed spawn | `E_SANDBOX_TEAM`, `team-not-created` |
1222
+ | The sandbox's souls join more than one team, or a team whose service isn't the bundle's: v1's provider limit (r5) | `oats sandbox start`, sync's start, the seat plan, `seat` | `E_SANDBOX_TEAM`, `team-not-served` |
813
1223
  | A delivered seat with a missing or contradictory descriptor (r2) | the in-sandbox apply | `seat-binding` (oats.aweb) |
814
1224
  | No provider, or more than one (r1) | every sandbox act | `E_SANDBOX_PROVIDER`, `none` or `ambiguous` |
815
- | A sandboxed soul on a host that does not list or run its sandbox | `oats spawn`, a schedule's spawn | `E_SANDBOX_NOT_HERE` |
816
- | A soul not placed in this sandbox, inside it | the in-sandbox `oats spawn` | `E_SANDBOX_PLACEMENT` |
817
-
818
- **Why `E_SANDBOX_HOST_AGENT`.** The controller key and the credential sources sit under
819
- the account that runs the deployment, because that account mints the seats. A host-side
820
- agent of the same deployment would run as that account and could read them. So in v1, a
1225
+ | A placed soul whose selected sandbox this host does not list or run | `oats spawn`, a schedule's spawn | `E_SANDBOX_NOT_HERE` |
1226
+ | A soul this sandbox doesn't list, inside it (r5) | the in-sandbox `oats spawn` | `E_SANDBOX_PLACEMENT`, `not-placed-here` |
1227
+ | A routed request naming another sandbox, or none, inside it (r5) | the in-sandbox remote preview and apply; on the normal host route the preview detects it, before any mint | `E_SANDBOX_PLACEMENT`, `wrong-sandbox` |
1228
+ | Several eligible sandboxes and no `--sandbox` or schedule `sandbox:` (r5) | `oats spawn`, a schedule's spawn | `E_SANDBOX_PLACEMENT`, `sandbox-ambiguous` |
1229
+ | A named target that isn't declared, or doesn't list the soul (r5) | `oats spawn`, a schedule's spawn | `E_SANDBOX_PLACEMENT`, `sandbox-unknown` or `sandbox-not-eligible` |
1230
+ | A soul reference no member or package offers (r5) | `oats spawn`, a schedule's spawn | `E_SANDBOX_PLACEMENT`, `soul-unknown` |
1231
+ | A composition that needs an excluded capability (r5) | the routed spawn, after the remote preview and before anything is kept or minted; a replay's recheck (`held-not-admitted`) | `E_SANDBOX_PLACEMENT`, `capability-excluded` |
1232
+ | A composition with a capability, or a capability source, the last applied plan didn't admit for this soul (r5) | the routed spawn (by hand or a tick), after the remote preview and before anything is kept or minted; a replay's recheck (`held-not-admitted`) | `E_SANDBOX_PLACEMENT`, `capability-not-applied` |
1233
+ | `oats sync --admission-revision` whose revision no longer matches the current inputs (r5) | `oats sync`, for all of that sync's admission; its other steps go on | `E_PLAN_STALE`, with the fresh plan |
1234
+ | `--sandbox` together with `--server` (r5) | `oats spawn` | `E_BAD_ARGS`; the remedy says to choose one target, `--sandbox` for a placed soul or `--server` for a registered server |
1235
+ | A join beyond the default team, into a sandbox (r5) | `seat`, before the mint | `E_SANDBOX_PLACEMENT`, `join-not-seated` |
1236
+ | A resident's grant seat, into a sandbox (r5) | `seat`, before the mint | `E_SANDBOX_PLACEMENT`, `grant-seat-not-sandboxable` |
1237
+ | A sandbox entry with a `team` field (the unreleased shape) (r5) | reading the workspace file | `E_WORKSPACE_SCHEMA`, `sandbox-team-field` |
1238
+ | A local `sandboxes` entry the workspace doesn't declare, a duplicate, or a listed sandbox with no `host.name` (C3) | reading the local file | `E_WORKSPACE_SCHEMA`, `sandbox-unknown`, `duplicate-entry` or `sandbox-host-name-required` |
1239
+ | `sandbox: {self}` combined with `sandboxes`, `credentials`, local `teams` or a local `defaultTeam` (C3b) | reading the in-sandbox local file | `E_WORKSPACE_SCHEMA`, `sandbox-self-conflict` |
1240
+ | A new `oats server add` or `connect` with the reserved `sandbox-` prefix (C7) | `oats server add`, `oats server connect` | `E_SERVER_INVALID`, `reserved-prefix` |
1241
+ | A private registry with no in-sandbox `settings.oats.aweb.registry` (C3) | the in-sandbox spawn | oats.aweb's reason `registry-setting-required`, carried by the kernel's refusal of a required hook's failure |
1242
+
1243
+ Reasons in the table that a provider gives, such as `seat-binding` and
1244
+ `registry-setting-required`, reach the caller inside the kernel's own refusal for a
1245
+ failed required hook. The kernel's codes stay the kernel's; the provider adds only the
1246
+ reason and its remedy (r5).
1247
+
1248
+ **Why `E_SANDBOX_HOST_AGENT`.** The controller key, the team roots, the credential
1249
+ sources and any resident's custody service sit under the account that runs the
1250
+ deployment, because that account mints the seats and serves the residents. A
1251
+ host-side agent of the same deployment would run as that account and could read them,
1252
+ or call the custody socket (r5). So in v1, a
821
1253
  deployment that lists a sandbox runs every agent in a sandbox. Agents that belong on the
822
1254
  host run from another deployment, under another OS user. This replaces checking file
823
1255
  modes against users, which cannot be proved from inside one account.
824
1256
 
825
1257
  ## Left out of v1
826
1258
 
1259
+ Each restriction sits beside the feature it qualifies (the section named), and goes in
1260
+ the release notes when that feature ships (r5).
1261
+
827
1262
  - Creating or deleting machines.
828
- - Several sandboxes for one team, and explicit placement.
829
- - A bridge soul between a sandboxed team and another team.
1263
+ - **Several teams in one sandbox, with teamctl:** the model admits it, but v1's provider
1264
+ serves one team per sandbox (C8, `team-not-served`).
1265
+ - **Seats for extra teams** in a sandbox (Identities, `join-not-seated`).
1266
+ - **A resident's grant seat** in a sandbox, until a qualified, revocable remote
1267
+ delegation exists (Identities, `grant-seat-not-sandboxable`).
1268
+ - **Kubernetes qualification.** C4 is the contract a Kubernetes provider implements,
1269
+ and v1's provider is Compose through teamctl. A Kubernetes provider is claimed only
1270
+ after the Acceptance section's Kubernetes case passes on an existing cluster, and its
1271
+ release scope is decided separately.
1272
+ - **Secrets and connector capabilities:** designed only (C9). Per-principal secrets
1273
+ are enforced once the provider exists (Credentials).
830
1274
  - Human IDs by default and `oats sandbox adopt`. These wait on aweb's maintainers' decision
831
1275
  on reversing "strictly opt-in" (#1665). Adoption is specified once
832
1276
  those are settled.
833
- - Kubernetes. The provider contract (C4) is platform-neutral, and v1's provider is
834
- Compose through teamctl.
835
1277
  - Publishing the image, and its digest in the lock.
836
1278
 
837
1279
  ## Alternatives rejected
@@ -841,7 +1283,23 @@ modes against users, which cannot be proved from inside one account.
841
1283
  or show.
842
1284
  - **`hostedBy: everyone` for containers:** Docker could start on a laptop that never
843
1285
  asked for it.
844
- - **A sandbox that lists its own souls and gets an automatic team:** rejected by the product owner.
1286
+ - **A sandbox that gets an automatic team:** rejected by the product owner. A sandbox
1287
+ listing its own souls was rejected with it at first, then adopted in r5, without the
1288
+ team.
1289
+ - **Placement derived from the default team (r1–r4d):** it tied messaging to the
1290
+ runtime boundary, so one team could never span sandboxes, and one sandbox could
1291
+ never hold two teams without changing the model. Replaced in r5 by explicit
1292
+ placement.
1293
+ - **The local file choosing between eligible sandboxes (r5 draft):** it let a machine's
1294
+ file decide a placement, which only the shared workspace decides. Replaced by the
1295
+ explicit selector (C2).
1296
+ - **A declared `capabilities` list per sandbox (r5 drafts):** first optional, meaning
1297
+ "everything", then a required ceiling where `[]` permitted none. Both made every
1298
+ sandbox repeat the workspace's common capabilities. A `defaults` shorthand was
1299
+ considered and dropped too. Replaced by admission derived per soul, optional
1300
+ exclusions and the applied-plan gate (decided 2026-11-20).
1301
+ - **A `team:` alias for a `souls:` entry's `default`:** two spellings of one key in a
1302
+ closed schema. Left out of this amendment by both sides.
845
1303
  - **Docker in the kernel:** the kernel stays runtime-neutral; the provider owns
846
1304
  containers.
847
1305
  - **The container's own clock beside the host's:** two owners of one schedule.
@@ -851,20 +1309,33 @@ modes against users, which cannot be proved from inside one account.
851
1309
  only, by its own contract.
852
1310
  - **A lease service for schedules:** none exists, and `runsOn` already names one host.
853
1311
 
1312
+ ## Acceptance (r5)
1313
+
1314
+ | Case | What it shows |
1315
+ | --- | --- |
1316
+ | Same team, separate sandboxes | A reviewer and a deployer in one team, in two sandboxes, exchange the messages aweb allows. Their state, session material and mounts stay separate, and the reviewer can't use the deployment credential. The same holds with cross-team messaging allowed, and with it denied, by aweb's policy. Pending for v1's provider until aweb's maintainers say whether teamctl runs two sandboxes for one team (C8). |
1317
+ | Teams independent of the runtime | Changing a soul's default team, or a label's alias, moves no soul. Two teams in one sandbox, accepted as co-resident trust, run on a provider that serves several teams; v1's provider refuses it with `team-not-served`. One team in two sandboxes introduces no second team. |
1318
+ | Placement and capability refusals | An ambiguous target, a wrong host, a wrong sandbox, an excluded capability, a capability not yet applied, a forged seat binding and an unavailable provider route each fail with the responsible decision and a remedy, before any placement succeeds or usable authority leaks. A route meant for sandbox A that resolves to sandbox B's registration, for a soul eligible in both, refuses at the remote preview with `wrong-sandbox`, and no seat is minted. |
1319
+ | The admission fence and its commit | An exclusion committed between the seat and the apply: the apply is not sent, the seat is released with no home made, and the request is gone. The same exclusion before a replay of an apply that was sent: the replay isn't sent and the seat stays delivered (`held-not-admitted`). Sandbox A's sync step succeeds and B's fails under `--admission-revision`: neither's admission is recorded. Both succeed under the plan's one revision: both sandboxes' widened entries are recorded in one write. A's entry had narrowed while B's widens: A keeps its recorded set. An upstream change in B after the plan: `--admission-revision` refuses `E_PLAN_STALE` in the top-level `problems`, neither A's nor B's admission is recorded, both sandboxes' infrastructure steps still run, and sync exits nonzero. A member's composition, or this host's listing, changes while sandbox B starts, after the plan matched: the commit fence refuses the whole admission with `E_PLAN_STALE` and writes nothing. A soul with no recorded entry is refused until the first reviewed apply, which records it, an empty derived set included (`first: true`); a recorded empty entry admits it. |
1320
+ | Capabilities widen only through an applied plan | One sandbox lists review (capability `read`) and deploy (`read` and `deploy`). Upstream adds `deploy` to review, with no new applied plan. A manual spawn of review and its tick both refuse before minting (`capability-not-applied`), and deploy still works. After the revised plan is approved and applied, review may load the capability, which still grants it no credential or operation. |
1321
+ | Identity apart from the route | Designed while grant seats stay on the host. A grant-backed agent restarts with the same stable DID and a new valid session; one without public inbound reach stays usable as the same principal; an alias match, a wrong team or a stale session can't spend its grant; revocation stops the next dispatch with both sandboxes left in place. |
1322
+ | Target and policy | With Compose: start, authorized work, stop, resume and delist, with separate state and one clock. The same contract against an existing Kubernetes cluster, including storage across a workload replacement and a check of the network policy, before that provider is claimed. |
1323
+
854
1324
  ## Delivery
855
1325
 
856
1326
  | Spec | Surface | Lane | Builds first |
857
1327
  | --- | --- | --- | --- |
858
- | S1 Kernel: C1, C2, C3, C4's caller, C5, C10, placement and routing | `lib/`, `bin/`, schemas, `docs/` | lane:product | first; built now, merged after #1912's hold lifts |
859
- | S2 Provider: `oats.aweb-sandbox`, C4's hook, C6, C7, the registry setting (C3) | the oats-aweb package | lane:setup, aweb's maintainers read first | after S1's contract is merged |
1328
+ | S1a Kernel, the part placement doesn't touch: C1's shape (validated when read), C3, C3b, C4's caller and runner, C5's lifecycle and sync, C7, the kept-request custody and replay fence, readiness | `lib/`, `bin/`, schemas, `docs/` | lane:product | first; reuses the reviewed work of #2025 that no team placement touches, merged after #1912 |
1329
+ | S1b Kernel, placement: C2's selection, derived admission and the applied-plan gate (C1), the seat's team and settings (C4), C3b's checks, the r5 refusals (C10), the status answer without `team` | `lib/`, `bin/`, schemas, `docs/` | lane:product | after S1a |
1330
+ | S2 Provider: `oats.aweb-sandbox`, C4's hook, C6, C7, C8's one served team, the registry setting (C3) | the oats-aweb package | lane:setup, aweb's maintainers read first | after S1b's contract is merged |
860
1331
  | S3 Credential mount and the `forge` role: C8, the egress component, teamctl's inputs | `container/agent`, and teamctl on aweb's maintainers' side | lane:juan | in parallel with S1 |
861
1332
  | S4 Broker contracts: C9 docs, then the client verbs | `docs/`, `lib/` | lane:product | after the first real provider |
862
1333
 
863
1334
  Each spec carries its own reference pages and a release-notes entry of its own under
864
1335
  `docs/release-notes/next/` (r1):
865
1336
 
866
- - S1: [workspaces.md](../workspaces.md) (`sandboxes:`, the rollout rule, C2's
867
- refusals), [configuration.md](../configuration.md) (C3, C3b), [capabilities.md](../capabilities.md)
1337
+ - S1a and S1b: [workspaces.md](../workspaces.md) (`sandboxes:`, the rollout rule,
1338
+ C2's selection, and the one-served-team limit stated plainly), [configuration.md](../configuration.md) (C3, C3b), [capabilities.md](../capabilities.md)
868
1339
  and the manifest schema (the `sandbox` hook, C4), the CLI and JSON pages (C5),
869
1340
  [servers.md](../servers.md) (the reserved prefix, C7), and readiness (C10).
870
1341
  - S2: the oats-aweb package's own docs (`identity.seat`, the registry setting,
@@ -873,6 +1344,9 @@ Each spec carries its own reference pages and a release-notes entry of its own u
873
1344
  teamctl's docs on aweb's maintainers' side.
874
1345
  - S4: the broker contracts' reference page, when it is built.
875
1346
 
1347
+ Who builds each slice is decided apart from this record, and reviewing the record
1348
+ commits no side to building one (r5).
1349
+
876
1350
  The live rehearsal runs on a disposable Linux Docker host, never on a person's machine.
877
- It covers every "done means" line, with the egress and boundary probes' receipts kept as
878
- evidence.
1351
+ It covers every "done means" line and the Acceptance cases v1's provider can run,
1352
+ with the egress and boundary probes' receipts kept as evidence.