@awebai/oats 0.69.23 → 0.70.0
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/bin/oats.mjs +112 -20
- package/docs/capabilities.md +697 -11
- package/docs/capability-manifest.schema.json +66 -0
- package/docs/configuration.md +27 -7
- package/docs/design/2026-11-19-sandboxes.md +595 -121
- package/docs/design/2026-11-20-provider-home-lifecycle.md +322 -0
- package/docs/design/README.md +7 -3
- package/docs/desktop-cli-api.md +330 -9
- package/docs/desktop.md +181 -48
- package/docs/execution-targets.md +210 -4
- package/docs/first-team.md +11 -0
- package/docs/implementation.md +24 -3
- package/docs/integrations.md +2 -2
- package/docs/knowledge-capability-authoring.md +1 -1
- package/docs/knowledge-reference/proposal.md +10 -0
- package/docs/knowledge.md +20 -11
- package/docs/official-catalog.md +2 -2
- package/docs/packages.md +7 -7
- package/docs/release-notes/v0.69.24.md +264 -0
- package/docs/release-notes/v0.70.0.md +155 -0
- package/docs/souls-and-instances.md +57 -0
- package/docs/trust-model.md +8 -1
- package/docs/tui.md +21 -1
- package/docs/upgrading.md +19 -5
- package/docs/workspaces.md +13 -5
- package/lib/automation-scope.mjs +1 -1
- package/lib/capability-show.mjs +20 -1
- package/lib/command-flags.mjs +2 -2
- package/lib/compile-cache.mjs +1 -1
- package/lib/core.mjs +1455 -203
- package/lib/errors.mjs +4 -1
- package/lib/home-integrity.mjs +329 -0
- package/lib/hook-env.mjs +107 -0
- package/lib/host-run.mjs +11 -3
- package/lib/instance-events.mjs +32 -5
- package/lib/instance-git.mjs +9 -0
- package/lib/instance-inspect.mjs +107 -9
- package/lib/instance-lifecycle.mjs +15 -3
- package/lib/instance-listing.mjs +101 -8
- package/lib/instance-resolution.mjs +85 -2
- package/lib/instance-upgrade.mjs +170 -14
- package/lib/kernel-features.mjs +10 -1
- package/lib/node-version.mjs +9 -0
- package/lib/provider-call-child.mjs +60 -0
- package/lib/provider-resume.mjs +83 -0
- package/lib/provider-test-seams.mjs +20 -0
- package/lib/read-call.mjs +2 -0
- package/lib/remote.mjs +33 -1
- package/lib/reserved-launch-env.mjs +8 -1
- package/lib/retire-admission.mjs +12 -1
- package/lib/sandbox-allowances.mjs +329 -0
- package/lib/schedule.mjs +14 -4
- package/lib/servers.mjs +38 -5
- package/lib/session-inspect.mjs +123 -87
- package/lib/session-providers.mjs +575 -0
- package/lib/session-receipt.mjs +93 -0
- package/lib/session-resume.mjs +68 -15
- package/lib/stable-node.mjs +3 -0
- package/lib/triggers.mjs +3 -1
- package/lib/upgrade-state.mjs +6 -1
- package/lib/worktree-hooks.mjs +18 -2
- package/lib/worktree.mjs +21 -7
- package/package-catalog.json +2 -2
- package/package.json +2 -1
- package/packages/client/capability-list.mjs +21 -0
- package/packages/client/cli-adapter.mjs +19 -4
- package/packages/client/cli-locator.mjs +5 -1
- package/packages/client/deployment-data.mjs +23 -1
- package/packages/client/deployment-panel.mjs +25 -3
- package/packages/client/home-board.mjs +33 -19
- package/packages/client/inspect-boundary.mjs +18 -8
- package/packages/client/instance-acts.mjs +30 -3
- package/packages/client/instance-board.mjs +206 -0
- package/packages/client/instance-presentation.mjs +55 -0
- package/packages/client/liveness.mjs +15 -4
- package/packages/client/own-codes.mjs +5 -1
- package/packages/client/remote-roster.mjs +6 -1
- package/packages/client/session-backends.mjs +31 -0
- package/packages/client/session-start.mjs +18 -6
- package/packages/client/spawn-apply-cli.mjs +5 -3
- package/packages/client/spawn-apply-contract.mjs +25 -2
- package/packages/client/spawn-apply.mjs +5 -1
- package/packages/client/spawn-messages.mjs +3 -0
- package/packages/client/terminal-contract.mjs +4 -0
- package/packages/client/waiting-on-you.mjs +12 -2
- package/packages/tui/lib/model.mjs +14 -3
- package/packages/tui/lib/store.mjs +12 -3
- 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
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
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
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
-
|
|
54
|
-
|
|
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).
|
|
60
|
-
|
|
61
|
-
|
|
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;
|
|
64
|
-
|
|
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
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
S1
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
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
|
|
141
|
-
directory. Where
|
|
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}
|
|
159
|
-
read-only and needs no instance name: it answers the
|
|
160
|
-
`spawnKey`), its path and the `spawnProvider` options
|
|
161
|
-
|
|
162
|
-
|
|
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
|
|
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}`.
|
|
179
|
-
|
|
180
|
-
`
|
|
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.
|
|
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
|
|
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
|
|
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
|
-
|
|
415
|
-
|
|
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
|
-
|
|
419
|
-
|
|
420
|
-
|
|
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
|
|
425
|
-
|
|
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
|
-
|
|
430
|
-
- `credentials` names match `^[a-z0-9][a-z0-9-]{0,62}$`, and are distinct.
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
`
|
|
439
|
-
`
|
|
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.
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
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
|
|
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
|
|
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
|
-
"
|
|
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}
|
|
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,
|
|
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`)
|
|
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 `
|
|
646
|
-
|
|
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)
|
|
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
|
|
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
|
|
816
|
-
| A soul
|
|
817
|
-
|
|
818
|
-
|
|
819
|
-
|
|
820
|
-
|
|
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
|
|
829
|
-
|
|
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
|
|
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
|
-
|
|
|
859
|
-
|
|
|
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
|
-
-
|
|
867
|
-
|
|
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
|
|
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.
|