@awebai/oats 0.69.22 → 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.
- package/bin/oats.mjs +185 -38
- package/docs/capabilities.md +365 -7
- package/docs/capability-manifest.schema.json +37 -1
- package/docs/configuration.md +27 -7
- package/docs/container.md +206 -228
- package/docs/design/2026-11-19-sandboxes.md +1352 -0
- package/docs/design/2026-11-20-provider-home-lifecycle.md +320 -0
- package/docs/design/README.md +7 -0
- package/docs/desktop-cli-api.md +673 -81
- package/docs/desktop.md +241 -65
- package/docs/execution-targets.md +186 -3
- package/docs/first-team.md +11 -0
- package/docs/implementation.md +6 -2
- package/docs/integrations.md +3 -3
- package/docs/knowledge-capability-authoring.md +10 -7
- package/docs/knowledge-reference/acceptance.md +21 -19
- package/docs/knowledge-reference/adoption.md +18 -4
- package/docs/knowledge-reference/model.md +11 -9
- package/docs/knowledge-reference/package-craft.md +2 -2
- package/docs/knowledge-reference/proposal.md +127 -0
- package/docs/knowledge-reference/provider-mapping.md +10 -10
- package/docs/knowledge-reference/reader-capture.md +26 -22
- package/docs/knowledge-theory.md +1 -1
- package/docs/knowledge.md +25 -16
- package/docs/official-catalog.md +4 -4
- package/docs/packages.md +13 -13
- package/docs/release-notes/v0.69.23.md +231 -0
- package/docs/release-notes/v0.69.24.md +264 -0
- package/docs/servers.md +10 -6
- package/docs/souls-and-instances.md +96 -22
- package/docs/tui.md +25 -4
- package/docs/upgrading.md +19 -5
- package/docs/workspaces.md +14 -6
- package/lib/argv.mjs +6 -2
- package/lib/capability-contract.mjs +2 -2
- package/lib/capability-show.mjs +11 -1
- package/lib/command-flags.mjs +40 -3
- package/lib/compile-cache.mjs +1 -1
- package/lib/core.mjs +1201 -195
- package/lib/errors.mjs +4 -1
- package/lib/hook-env.mjs +106 -0
- package/lib/host-run.mjs +11 -3
- package/lib/instance-board.mjs +337 -0
- package/lib/instance-events.mjs +48 -10
- package/lib/instance-inspect.mjs +44 -0
- package/lib/instance-lifecycle.mjs +34 -18
- package/lib/instance-listing.mjs +113 -16
- package/lib/instance-related-work.mjs +143 -0
- package/lib/kernel-features.mjs +13 -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/reserved-launch-env.mjs +8 -1
- package/lib/retire-admission.mjs +5 -1
- package/lib/schedule.mjs +14 -4
- package/lib/servers.mjs +151 -17
- package/lib/session-inspect.mjs +104 -13
- package/lib/session-providers.mjs +528 -0
- package/lib/session-resume.mjs +68 -15
- package/lib/stable-node.mjs +3 -0
- package/lib/triggers.mjs +3 -1
- package/package-catalog.json +3 -3
- 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 +27 -3
- package/packages/client/deployment-panel.mjs +27 -4
- 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/instance-tree.mjs +34 -4
- package/packages/client/keymap.mjs +5 -0
- package/packages/client/liveness.mjs +15 -4
- package/packages/client/mail-contract.mjs +130 -0
- package/packages/client/own-codes.mjs +5 -1
- package/packages/client/panel-views.mjs +7 -7
- package/packages/client/related-work.mjs +84 -0
- package/packages/client/remote-roster.mjs +9 -3
- 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/client/workspace-cli.mjs +13 -2
- package/packages/tui/lib/model.mjs +14 -3
- package/packages/tui/lib/store.mjs +12 -3
- package/skills/oats-getting-started/SKILL.md +11 -8
- package/docs/knowledge-reference/harvester.md +0 -109
- package/lib/instance-same-work.mjs +0 -67
- package/packages/client/same-work.mjs +0 -49
|
@@ -0,0 +1,1352 @@
|
|
|
1
|
+
# Sandboxes: boundaries declared in the workspace, started by `oats sync`
|
|
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
|
+
|
|
15
|
+
**Status:** contracts decided, 2026-11-19. The product owner's side and aweb's maintainers agreed
|
|
16
|
+
C1–C10 and C3b as written at 0849ef12, with aweb's maintainers' four changes, which
|
|
17
|
+
the product owner's side accepted: the registry setting (C3, C6), a keyed `seat` (C4), the receipt of the host's
|
|
18
|
+
`remove-member` (C6) and the credential-mount probe (C8). The connector half of C9
|
|
19
|
+
stays designed only. Nothing is built yet. **Revised after review round 1** (marked
|
|
20
|
+
"(r1)" below): existing host homes, lifecycle calls made inside a sandbox, C4's
|
|
21
|
+
per-act wire shapes and provider selection, shared team aliases, mount overlap, the
|
|
22
|
+
first use's GitHub API route, managed server registrations, and the missing refusal
|
|
23
|
+
codes. Both sides decided those, with two precisions from aweb's maintainers, and decided the
|
|
24
|
+
`forge` egress role for the GitHub API. **Revised again after review round 2** (marked
|
|
25
|
+
"(r2)"): every real agent bind is checked, `status` mutates nothing, the routed
|
|
26
|
+
spawn's exact sequence and seat binding, the seat's service descriptor, provider state
|
|
27
|
+
scoped per deployment, a team not yet created, and the seat option's key. Both sides
|
|
28
|
+
decided the r2 additions, with `sandbox-state-orphaned`. **Revised after review round
|
|
29
|
+
3** (marked "(r3)"): the apply is bound to the preview's `decision.revision`; the seat
|
|
30
|
+
plan needs only the spawn key; the spawn hook learns the apply's key; the kernel keeps
|
|
31
|
+
the full routed request for replay; mint recovery; hardlinked credentials; the
|
|
32
|
+
resolvers are host infrastructure; the protected-sources input shape; and the `forge`
|
|
33
|
+
role's Host guarantee corrected to what a TLS pass-through can enforce. Both sides
|
|
34
|
+
decided the r3 contracts, with the domain-fronting risk statement and the pending
|
|
35
|
+
request's custody. **Revised after review round 4** (marked "(r4)"): the apply
|
|
36
|
+
evidence `bind` acts on, and the fence that keeps a replay away from an interrupted
|
|
37
|
+
delivery. **Revised after the round-4 delta read** (marked "(r4d)"): a seat is
|
|
38
|
+
released only on proof that no home can hold it, and the readiness and ordering text
|
|
39
|
+
that follows from that. A later change to a contract goes back to
|
|
40
|
+
both sides (the lane map's "Contract changes" line). When this record and a reference
|
|
41
|
+
page disagree after it is built, the reference page wins.
|
|
42
|
+
|
|
43
|
+
## The goal
|
|
44
|
+
|
|
45
|
+
One machine runs `oats sync` on a deployment, and the sandboxes that deployment lists
|
|
46
|
+
are built and started, with their boundaries declared once in the workspace. The first
|
|
47
|
+
use is scheduled knowledge-base ingestor agents on a cloud machine: they read untrusted
|
|
48
|
+
content, so they must not reach the engineers' agents, credentials or network.
|
|
49
|
+
|
|
50
|
+
**Done means:** on a Linux machine with Docker, a workspace that declares one sandbox,
|
|
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
|
|
60
|
+
nothing. All of this is shown by a live rehearsal and by the tests pinned in each spec.
|
|
61
|
+
|
|
62
|
+
## Decided with the product owner
|
|
63
|
+
|
|
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").
|
|
90
|
+
- **OATS does not create or delete machines in v1.** Sync builds and starts listed
|
|
91
|
+
sandboxes on a machine that already exists. Creating machines comes later, as a
|
|
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).
|
|
96
|
+
- **Both broker contracts are designed in this effort**: one for secrets, one for
|
|
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).
|
|
103
|
+
- **Kept as they are:** the word "team"; the schedule file, with `runsOn` naming the
|
|
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).
|
|
106
|
+
|
|
107
|
+
## What exists today, and what this builds on
|
|
108
|
+
|
|
109
|
+
- `container/agent` is one team's container. It runs every agent, sshd, the wake
|
|
110
|
+
broker and `oats host run` as one user, with its own OATS deployment at
|
|
111
|
+
`/state/deploy`, reached from the host as an OATS server over SSH
|
|
112
|
+
([container.md](../container.md)).
|
|
113
|
+
- Its egress component has five base roles (aweb, registry, secrets, logs, signer), of
|
|
114
|
+
which a policy may declare a subset (#1955); teamctl's profile declares four of them
|
|
115
|
+
(all but signer). It adds two optional external roles, `source` (`https://github.com`)
|
|
116
|
+
and `model` (`https://api.anthropic.com`). It does not take arbitrary origins
|
|
117
|
+
([egress README](../../container/agent/egress/README.md)). The Compose boundary probe
|
|
118
|
+
takes a `namePrefix` and reports `--json` receipts (#1958).
|
|
119
|
+
- aweb's team bundle, `deploy/team` (`teamctl`, aweb's maintainers), renders one
|
|
120
|
+
`deployment.yaml` into an aweb server, the egress proxy and the agent container. It
|
|
121
|
+
sets `AWEB_FEDERATION_OUTBOUND` to `off` by default. `teamctl start` probes the
|
|
122
|
+
boundary, brings up the agent, and exits 3 on purpose with the agents held: it admits
|
|
123
|
+
no seat.
|
|
124
|
+
- Seats: today a container agent takes a retained seat (`identity.source`) that the
|
|
125
|
+
operator provisioned. oats.aweb mints an instance's identity with
|
|
126
|
+
`aw init --join-from <root> --join-team <team>`, which works only where the team key
|
|
127
|
+
is, and at retire it prints `aw id team remove-member` rather than running it.
|
|
128
|
+
- The kernel has no Docker code, and must not gain any: provider behaviour belongs in a
|
|
129
|
+
capability.
|
|
130
|
+
- `oats-workspace.yaml` and `oats-local.yaml` are closed schemas. An older kernel
|
|
131
|
+
refuses a new root key with `E_WORKSPACE_SCHEMA` and, for the workspace file, an
|
|
132
|
+
"upgrade OATS" hint.
|
|
133
|
+
- A `run: spawn` schedule spawns on the host its `runsOn` matches (`host.name`). A
|
|
134
|
+
remote spawn (`--server`) runs preview and apply on the server's kernel, and the home
|
|
135
|
+
lives there.
|
|
136
|
+
|
|
137
|
+
## The design
|
|
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
|
+
|
|
162
|
+
### Who does what
|
|
163
|
+
|
|
164
|
+
| Piece | Owner | Does |
|
|
165
|
+
| --- | --- | --- |
|
|
166
|
+
| Declaration, validation, placement, CLI verbs, sync | the kernel (lane:product) | Reads `sandboxes:`, refuses the ways round the boundary, decides where a soul runs, calls the sandbox provider, and reports. No Docker. |
|
|
167
|
+
| Sandbox provider | a new capability, `oats.aweb-sandbox`, in the oats-aweb package | Turns a sandbox into teamctl input, runs teamctl, registers the sandbox as a server, prepares the in-sandbox deployment, mints and delivers seats, removes members at retire. |
|
|
168
|
+
| The team bundle | teamctl, aweb `deploy/team` (aweb's maintainers) | Three new inputs: the credential mount, the protected-sources file and the `forge` role (C8). |
|
|
169
|
+
| The agent image and Compose | `container/agent` (lane:juan) | A read-only credential mount fragment (C8). |
|
|
170
|
+
|
|
171
|
+
### Placement
|
|
172
|
+
|
|
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).
|
|
198
|
+
|
|
199
|
+
### The clock
|
|
200
|
+
|
|
201
|
+
There is one clock per machine, and it is the host's. A schedule runs on the host its
|
|
202
|
+
`runsOn` names, and its spawn is routed into the sandbox. The in-sandbox deployment
|
|
203
|
+
registers no deployment for ticking, so its `oats host run` keeps only the resume sweep
|
|
204
|
+
and the ordered stop, and ticks nothing. This replaces the container's clock; it does
|
|
205
|
+
not add a second one.
|
|
206
|
+
|
|
207
|
+
### Identities
|
|
208
|
+
|
|
209
|
+
Every instance in a sandbox has its own identity, minted on the host at spawn and
|
|
210
|
+
removed at retire. The team's controller key and team key stay on the host, under the
|
|
211
|
+
operator's account, and never enter the container.
|
|
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
|
+
|
|
232
|
+
1. Before routing the spawn, the provider mints the instance's identity on the host
|
|
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
|
|
235
|
+
`settings.oats.aweb.registry` for the mint (C3).
|
|
236
|
+
2. It delivers the identity's authority files (the same list retained seats copy
|
|
237
|
+
today) and a seat descriptor into the sandbox's state, at
|
|
238
|
+
`/state/seats/<seat-id>/`, and deletes the staging copy. The seat ID is derived from
|
|
239
|
+
the routed spawn's idempotency key, so a seat directory names one spawn, never an
|
|
240
|
+
instance name that can be reused (r2).
|
|
241
|
+
3. The remote spawn takes that seat as a one-use seat (C6). The agent's own private key
|
|
242
|
+
is then inside the container, which is what aweb's answer requires: there is no
|
|
243
|
+
alternative short of a grant home, and that route is untested.
|
|
244
|
+
4. At retire, the routed retire removes the home and releases the seat. The provider
|
|
245
|
+
then runs `aw id team remove-member` on the host, where the controller key is,
|
|
246
|
+
instead of printing it.
|
|
247
|
+
|
|
248
|
+
The exact order of a routed spawn, with the value each step binds (r2, r3):
|
|
249
|
+
|
|
250
|
+
1. The kernel makes the spawn's idempotency key (`spawnKey`) and asks the provider for
|
|
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
|
|
262
|
+
instance name when the caller gave none (a schedule passes `--purpose`, not
|
|
263
|
+
`--name`), and answers `decision.revision`, `D`, the hash of the whole decision
|
|
264
|
+
that the apply's `--expect-decision` must match, as #1912 requires. The in-sandbox
|
|
265
|
+
kernel admits a preview that carries a seat option without reading the seat; only
|
|
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.
|
|
276
|
+
3. **Before anything is minted, the kernel keeps the whole routed request** (r3,
|
|
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
|
|
279
|
+
task text, in `~/.oats/remote/<server>/pending/<spawnKey>.json` (0600, under the
|
|
280
|
+
operator account, beside today's remote snapshots). It holds the task text, which
|
|
281
|
+
#1912 took off argv for a reason, so: it is removed as soon as its seat settles
|
|
282
|
+
(bound, released, or refused terminally); it is never copied into a receipt, a log
|
|
283
|
+
or the ledger; and readiness reports one older than 24 hours as
|
|
284
|
+
`sandbox-pending-stale`, naming the spawn key, never the task. S1 pins a test that
|
|
285
|
+
its content never reaches a receipt, a log or a readiness line.
|
|
286
|
+
4. The kernel runs `seat` with the plan's revision, `spawnKey` and
|
|
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,
|
|
293
|
+
records the certificate ID, delivers, and moves the entry to `delivered`.
|
|
294
|
+
5. The kernel runs the remote apply with `--expect-decision D` and
|
|
295
|
+
`--idempotency-key spawnKey`, from the kept request, with the same provider options
|
|
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.
|
|
314
|
+
6. The kernel passes the apply's own answer to the provider (`bind`, C4), which acts
|
|
315
|
+
on it by this table (r4, contract):
|
|
316
|
+
|
|
317
|
+
| The apply's answer | Evidence | The seat |
|
|
318
|
+
| --- | --- | --- |
|
|
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` |
|
|
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`) |
|
|
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`) |
|
|
323
|
+
| `E_IDEMPOTENCY_CONFLICT` (r4d) | a home already holds `spawnKey` under another decision and may hold the seat | stays `delivered` |
|
|
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` |
|
|
325
|
+
|
|
326
|
+
A seat is released only on proof that no home can hold it (r4d): releasing revokes
|
|
327
|
+
the member, which is right for a seat that no home holds, used or not, and wrong
|
|
328
|
+
for one a live home holds. Before such a release the provider deletes any copy at
|
|
329
|
+
`/state/seats/<seat-id>/` through the server route. If that deletion cannot be
|
|
330
|
+
confirmed, the entry stays `delivered`, the kept request is deleted (its refusal
|
|
331
|
+
was terminal), and readiness reports `sandbox-seat-unsettled`. The server route's
|
|
332
|
+
"copy deleted" answer comes from the sandbox, so it is untrusted input: it can
|
|
333
|
+
release only a seat of that sandbox's own ledger, and a false "deleted" can at
|
|
334
|
+
worst revoke that sandbox's own member, never another's (r4d). `ok: false` alone is
|
|
335
|
+
never evidence, and the provider reads no field of a refusal beyond its code and
|
|
336
|
+
`unconfirmed`. S1 pins that the routed apply's answer, and its keyed replay, carry
|
|
337
|
+
the new home's `capabilityMeta`; that the routed answer carries the host's refusal
|
|
338
|
+
code and its `unconfirmed` detail unchanged; that `E_DECISION_STALE` is raised
|
|
339
|
+
only when no home holds the key, before any placement or hook; and that a required
|
|
340
|
+
hook's failure carries `unconfirmed: true` whenever the rollback could not confirm
|
|
341
|
+
the home gone. S2 pins the meta oats.aweb writes and a `bind` test per row,
|
|
342
|
+
including a prior home holding the key under another decision
|
|
343
|
+
(`E_IDEMPOTENCY_CONFLICT`: the member is kept) and a failed copy deletion.
|
|
344
|
+
7. **The kernel settles a `delivered` seat** (r3, r4): `oats sandbox reconcile`, and
|
|
345
|
+
so sync, first runs the provider's `reconcile` act, which settles interrupted mints
|
|
346
|
+
and deliveries (below) and answers the ledger's seats. Only then does it replay a
|
|
347
|
+
kept request, and only one whose ledger entry that answer shows durably
|
|
348
|
+
`delivered`: a kept request whose entry is `minting` or `mint-uncertain` is never
|
|
349
|
+
applied or replayed, and one whose seat was released is deleted. Each replay is
|
|
350
|
+
unchanged, keyed by its `spawnKey`, and its answer goes to `bind` as in 6. A replay of an apply that was
|
|
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
|
|
359
|
+
provider never builds or replays a spawn itself. Absence of the instance's name, or
|
|
360
|
+
an unused seat directory, is never evidence. A `delivered` seat with no kept request
|
|
361
|
+
stays `delivered`, and readiness reports `sandbox-seat-unsettled`.
|
|
362
|
+
|
|
363
|
+
**A mint whose outcome is uncertain (r3, contract).** An entry found in `minting` was
|
|
364
|
+
interrupted, and the registry may hold an identity whose result was never recorded, or
|
|
365
|
+
a seat copy may already have landed in the sandbox before the `delivered` write (r4).
|
|
366
|
+
The next mutating act reads the certificate ID from the staging copy, if one is there,
|
|
367
|
+
into the entry before it deletes that copy, and moves the entry to `mint-uncertain`.
|
|
368
|
+
With a certificate ID, it first deletes any copy at `/state/seats/<seat-id>/` through
|
|
369
|
+
the server route, then releases the seat (reason `spawn-failed`): no apply was sent
|
|
370
|
+
for it, because the apply follows the `delivered` write and its kept request is
|
|
371
|
+
fenced (step 7). If that copy cannot be confirmed deleted, the entry stays
|
|
372
|
+
`mint-uncertain` and is reported as unsettled. A pinned test kills the provider
|
|
373
|
+
between the copy landing and the `delivered` write, then runs reconcile and an
|
|
374
|
+
otherwise no-op sync: no home is created, the copy is gone and the member is
|
|
375
|
+
removed. Without one, the entry stays `mint-uncertain`, readiness
|
|
376
|
+
reports `sandbox-seat-unsettled` naming the alias, and the operator checks the team's
|
|
377
|
+
members. A replay of that `seat` key answers `unknown` and never mints again. A test
|
|
378
|
+
pins a kill after registration and before the receipt.
|
|
379
|
+
|
|
380
|
+
### Lifecycle calls made inside a sandbox (r1)
|
|
381
|
+
|
|
382
|
+
Minting and removing identities need the host's keys, so in v1 the host is the only
|
|
383
|
+
place a sandboxed instance is spawned from, and the host finishes every retire:
|
|
384
|
+
|
|
385
|
+
- **Spawn inside the sandbox.** The in-sandbox deployment has no root for any team.
|
|
386
|
+
Its kernel accepts a spawn only when it carries a host-delivered seat (the routed
|
|
387
|
+
spawn's `identity.seat`, C4 and C6). Any other spawn there, by an agent or by hand,
|
|
388
|
+
is refused with `E_SANDBOX_PLACEMENT`, reason `spawn-from-host`, whose remedy is to
|
|
389
|
+
spawn from the host. A sandboxed agent that needs a helper asks for one; it cannot
|
|
390
|
+
start one.
|
|
391
|
+
- **Retire inside the sandbox** (`oats retire --self`, or a retire run there by hand)
|
|
392
|
+
works as today: the home goes, and oats.aweb prints the `remove-member` command it
|
|
393
|
+
cannot run. The host completes it through the provider's `reconcile` act (C4), which
|
|
394
|
+
`oats sandbox start` and sync run for each listed sandbox, under the sandbox's lock.
|
|
395
|
+
`status` only observes (r2).
|
|
396
|
+
- **The sandbox's report is untrusted input.** Reconcile reads the sandbox's instances
|
|
397
|
+
through the server route, and that report comes from inside the boundary. So it can
|
|
398
|
+
only move seats of that sandbox's own ledger toward `released`, and it triggers no
|
|
399
|
+
other act. A seat is released by reconcile only when all of these hold: its entry is
|
|
400
|
+
`active` (never `minting`, `delivered` or `removal-uncertain`), the report lists no
|
|
401
|
+
home holding its seat ID, and its seat directory is gone. The release's receipt
|
|
402
|
+
records that the sandbox's report drove it (reason `reconcile`), so it can be told
|
|
403
|
+
from a retire's removal. A test pins that a report naming a seat of another
|
|
404
|
+
sandbox, or an unknown certificate, changes nothing.
|
|
405
|
+
- **Retire from the host** (`oats retire <name> --server sandbox-<name>`, or the
|
|
406
|
+
kernel routing a retire of a sandboxed instance) runs the remote retire, then the
|
|
407
|
+
provider's `release` act (C4) for that seat at once (reason `retired`).
|
|
408
|
+
- **The ledger** lives in the provider's state on the host, scoped to the deployment
|
|
409
|
+
(C7): `~/.oats/sandboxes/<deployment-key>/<sandbox>/seats.json`, one entry per seat:
|
|
410
|
+
seat ID, `spawnKey`, `D`, instance, alias, certificate ID, team, state (`minting`,
|
|
411
|
+
`mint-uncertain`, `delivered`, `active`, `removing`, `released`,
|
|
412
|
+
`removal-uncertain`), and the receipt
|
|
413
|
+
of each step. It outlives the remote home, and is the only evidence
|
|
414
|
+
`remove-member` acts on.
|
|
415
|
+
- **Removal is written before it runs (r2).** The provider moves an entry to
|
|
416
|
+
`removing`, durably, before it calls `remove-member`, then to `released` or
|
|
417
|
+
`removal-uncertain` with the receipt. An entry found in `removing` was interrupted:
|
|
418
|
+
it becomes `removal-uncertain`, and is never removed again automatically (C6).
|
|
419
|
+
- **Compensation.** If the mint succeeds but delivery fails, the provider releases
|
|
420
|
+
the seat at once (reason `spawn-failed`) and deletes any delivered copy. After
|
|
421
|
+
delivery, only step 6 or 7 above settles the seat.
|
|
422
|
+
|
|
423
|
+
### Credentials (v1)
|
|
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
|
+
|
|
457
|
+
The workspace names a sandbox's credentials. The host's local file says where each
|
|
458
|
+
value is. The provider mounts each named file read-only at `/run/oats-credentials/<name>`
|
|
459
|
+
in that sandbox's agent container only. Nothing else gets a mount, and an undeclared or
|
|
460
|
+
missing credential refuses the start. A capability inside the sandbox reads a credential
|
|
461
|
+
through its own file setting (for example `settings.oats.okf.github-token-file`), which
|
|
462
|
+
the provider writes into the in-sandbox local file from the host's settings for that
|
|
463
|
+
sandbox.
|
|
464
|
+
|
|
465
|
+
**No other mount may expose them (r1, r2).** A credential source is a regular file,
|
|
466
|
+
read through its real path; a symlink is resolved, and one that leads to anything but
|
|
467
|
+
a regular file is refused (`E_SANDBOX_CREDENTIAL`, reason `not-a-file`). The bind
|
|
468
|
+
source is the resolved path. A credential source with more than one hard link is
|
|
469
|
+
refused too (reason `hardlinked`, r3, contract): a second link could sit inside another
|
|
470
|
+
sandbox's work directory, where no path check sees it. This applies to every source in
|
|
471
|
+
the host's `credentials`, used or not, at every sandbox's start; the container's own
|
|
472
|
+
acceptance already refuses a public CA with more than one link. A pinned test puts a
|
|
473
|
+
hard link of one sandbox's credential in another sandbox's work directory.
|
|
474
|
+
|
|
475
|
+
The provider derives a protected inventory, in two parts:
|
|
476
|
+
|
|
477
|
+
- **Hard-denied:** the host's team roots (`roots`), the seat staging directory, the
|
|
478
|
+
provider's own state (`~/.oats/sandboxes`) and the host deployment directory. No
|
|
479
|
+
bind may equal, contain or lie inside one of these, a declared credential included:
|
|
480
|
+
a credential source inside a team root is refused.
|
|
481
|
+
- **Credential sources:** every source in the host's `credentials`, whether a listed
|
|
482
|
+
sandbox declares it or not (an unused one, or one of a delisted sandbox, included),
|
|
483
|
+
and every other sandbox's state, work and mirror directories. Only the exact
|
|
484
|
+
read-only bind of a credential this sandbox declares, at
|
|
485
|
+
`/run/oats-credentials/<name>`, is excepted.
|
|
486
|
+
|
|
487
|
+
The check runs on **every bind of the real agent container**, before any agent runs
|
|
488
|
+
(r2): the provider renders the teamctl deployment and checks each agent bind source in
|
|
489
|
+
the rendered configuration (the state, work and mirror directories, the harness login
|
|
490
|
+
directory from `agents.secrets`, the authorized-keys file, and the credential binds),
|
|
491
|
+
then the container's own mount acceptance checks the started agent's actual mounts
|
|
492
|
+
against the same inventory before any seat is admitted (C8). Today's boundary probe
|
|
493
|
+
substitutes an empty login directory, so it cannot stand in for this check. The
|
|
494
|
+
started-agent check reads the agent container by its exact identity (the container ID
|
|
495
|
+
teamctl's start returned, or an ownership label as in #1958), never by name alone: a
|
|
496
|
+
same-named container that is not this sandbox's refuses admission (a pinned negative
|
|
497
|
+
in S2 and S3). A failing
|
|
498
|
+
bind refuses the start (`E_SANDBOX_MOUNT`, reason `overlap`, naming both paths), and so
|
|
499
|
+
do two sandboxes sharing any such directory. Pinned negative tests: a work or mirror
|
|
500
|
+
directory containing an unused credential; one containing a delisted sandbox's
|
|
501
|
+
credential; a harness login directory pointing at a team root.
|
|
502
|
+
|
|
503
|
+
**The first use's GitHub API route: the `forge` role (decided).** `source` admits
|
|
504
|
+
`https://github.com` only, and a knowledge proposer also calls `https://api.github.com`
|
|
505
|
+
(OKF's own setup check requires both). Both sides decided a third external role for
|
|
506
|
+
it:
|
|
507
|
+
|
|
508
|
+
- `forge` selects exactly `https://api.github.com`, defaults to false and, like the
|
|
509
|
+
other external roles, needs `egress.external.resolvers`. Its wrapper input is
|
|
510
|
+
`egress.external.forge` (teamctl's schema), its policy entry
|
|
511
|
+
`externalTargets.forge.origin`, and the component checks the exact origin again.
|
|
512
|
+
- **What it guarantees (r3, contract: corrects a decided item).** External roles are
|
|
513
|
+
TLS pass-through: the proxy routes on the SNI and never sees the encrypted
|
|
514
|
+
Host/`:authority` (egress README, "Optional external source and model roles").
|
|
515
|
+
So `forge`'s guarantee is the external roles' own: exact SNI `api.github.com` and a
|
|
516
|
+
validated public destination. The probe tests what the proxy enforces: an
|
|
517
|
+
unlisted SNI is refused, and `api.github.com` resolves only to the proxy. **The
|
|
518
|
+
risk that remains:** with SNI `api.github.com` admitted, the connection reaches
|
|
519
|
+
whatever GitHub's front end for that name serves to a Host it accepts; domain
|
|
520
|
+
fronting is not refused here. So the one-repository credential is the control that
|
|
521
|
+
matters. A Host
|
|
522
|
+
that differs from the SNI inside the encrypted stream, on a `forge` or another
|
|
523
|
+
admitted connection, is not refused by this component; whether GitHub serves it is
|
|
524
|
+
GitHub's. Refusing it would need TLS interception, which this record does not
|
|
525
|
+
propose. This statement replaced the earlier "SNI/Host mismatch" item; both sides
|
|
526
|
+
decided it in r3, with the risk statement above.
|
|
527
|
+
- The external-egress image test and the boundary probe name the hosts that stay
|
|
528
|
+
refused: `uploads.github.com`, `codeload.github.com`, `raw.githubusercontent.com`,
|
|
529
|
+
`objects.githubusercontent.com` and `gist.github.com`.
|
|
530
|
+
- **The credential is scoped to one repository, as a requirement.** With a token the
|
|
531
|
+
API can write, and the boundary limits services, not accounts. So the sandbox's
|
|
532
|
+
proposal credential (`knowledge-propose` in C1's example) must be scoped to the one
|
|
533
|
+
knowledge-base repository, as a push credential is today. The egress README's role
|
|
534
|
+
section, this section and the first use's setup steps all say so.
|
|
535
|
+
- C1's `egress` set becomes `{model, source, forge}`. `forge` has its own feature,
|
|
536
|
+
`sandbox-egress-forge`, because a kernel that already has `sandboxes` refuses the new
|
|
537
|
+
value through C1's closed set: a workspace uses `forge` only once every one of its
|
|
538
|
+
hosts lists that feature.
|
|
539
|
+
- Order: the egress component and teamctl first, on lane:juan (aweb's maintainers launch
|
|
540
|
+
that developer once this record is final); then C1's value, on the kernel side.
|
|
541
|
+
|
|
542
|
+
### What sync does
|
|
543
|
+
|
|
544
|
+
After its current steps (the lock, package souls, the automation snapshot), `oats sync`
|
|
545
|
+
reconciles each sandbox the local file lists:
|
|
546
|
+
|
|
547
|
+
- not built, or built from other inputs: build and start it;
|
|
548
|
+
- stopped: start it;
|
|
549
|
+
- running with the same inputs: no infrastructure change (`action: "none"`).
|
|
550
|
+
|
|
551
|
+
Whatever the action, sync then reconciles each listed, running sandbox's seats
|
|
552
|
+
(`oats sandbox reconcile`'s work: the provider's `reconcile` act, then the replay of
|
|
553
|
+
each kept request whose entry it answers durably `delivered`, as in step 7 of the
|
|
554
|
+
Identities section) (r4d), so a self-retire is completed by the next sync even when nothing else changed
|
|
555
|
+
(r3). A pinned test: a self-retire, then an otherwise no-op sync, removes the member.
|
|
556
|
+
|
|
557
|
+
A sandbox declared in the workspace but not listed locally is never started. A sandbox
|
|
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
|
|
562
|
+
last declaration it started each sandbox with in its own state, so a sandbox whose
|
|
563
|
+
workspace entry was removed together with its local listing is still stopped, from
|
|
564
|
+
that record (r1). `oats sync --plan` shows
|
|
565
|
+
these actions and performs none. A failed sandbox does not undo the lock. It is reported
|
|
566
|
+
in `problems`, and sync exits nonzero.
|
|
567
|
+
|
|
568
|
+
teamctl's exit 3 ("agents held") is the expected end of a start. The provider reports
|
|
569
|
+
it as `ready`: in this design seats are admitted per spawn, never at start.
|
|
570
|
+
|
|
571
|
+
### Images
|
|
572
|
+
|
|
573
|
+
In v1 the agent and egress image digests are host facts in the teamctl deployment file.
|
|
574
|
+
teamctl already requires the digest form. The image is not yet published: the release
|
|
575
|
+
job is disabled pending the registry decision. Once the release lane publishes it, the
|
|
576
|
+
digest moves into the lock with the release. That is a lock format change, proposed
|
|
577
|
+
then, not here.
|
|
578
|
+
|
|
579
|
+
## The contracts (decided)
|
|
580
|
+
|
|
581
|
+
### C1. Workspace `sandboxes:` (new root key; r5)
|
|
582
|
+
|
|
583
|
+
```yaml
|
|
584
|
+
teams:
|
|
585
|
+
eng: { team: "eng:example.org" }
|
|
586
|
+
ingest-team: { team: "ingest:example.org" }
|
|
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
|
|
592
|
+
sandboxes:
|
|
593
|
+
ingest:
|
|
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
|
|
598
|
+
description: Knowledge ingestors # optional
|
|
599
|
+
```
|
|
600
|
+
|
|
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.
|
|
712
|
+
- `egress` is a subset of `{model, source, forge}` (`forge` behind feature
|
|
713
|
+
`sandbox-egress-forge`), because those are the external roles the egress component
|
|
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.
|
|
727
|
+
- It is closed (`additionalProperties: false`), like every workspace block. An older
|
|
728
|
+
kernel refuses the file with `E_WORKSPACE_SCHEMA` and its existing "upgrade OATS"
|
|
729
|
+
hint, which is the error that tells existing deployments what to do.
|
|
730
|
+
- **Adding it breaks every older host of the workspace, not only the sandbox host.**
|
|
731
|
+
Every host reads the shared file, so the first commit that adds `sandboxes:` makes
|
|
732
|
+
each host on an older kernel refuse the whole workspace. A workspace adds the block
|
|
733
|
+
only once every one of its hosts runs the release that has feature `sandboxes`. The
|
|
734
|
+
person who commits it checks that first: the kernel cannot see another person's host.
|
|
735
|
+
The release notes' Upgrade section and the reference page that owns the workspace
|
|
736
|
+
file ([workspaces.md](../workspaces.md)) both say this, and give the check:
|
|
737
|
+
`oats version --json` on each host lists `sandboxes`.
|
|
738
|
+
- Feature `sandboxes` in `oats version --json`.
|
|
739
|
+
|
|
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.
|
|
774
|
+
|
|
775
|
+
### C3. `oats-local.yaml`: `sandboxes` and `credentials` (new root keys)
|
|
776
|
+
|
|
777
|
+
```yaml
|
|
778
|
+
host: { name: cloud-1 }
|
|
779
|
+
sandboxes: [ingest] # the sandboxes this machine runs
|
|
780
|
+
credentials:
|
|
781
|
+
sources-read: { fromFile: /srv/oats-operator/credentials/sources-read }
|
|
782
|
+
knowledge-propose: { fromFile: /srv/oats-operator/credentials/knowledge-propose }
|
|
783
|
+
settings:
|
|
784
|
+
oats.aweb-sandbox:
|
|
785
|
+
sandboxes:
|
|
786
|
+
ingest:
|
|
787
|
+
deployment: /srv/oats-operator/ingest/deployment.yaml # teamctl host facts
|
|
788
|
+
settings:
|
|
789
|
+
oats.aweb: { registry: https://registry.example.org } # private registry only
|
|
790
|
+
oats.okf: { github-token-file: /run/oats-credentials/knowledge-propose }
|
|
791
|
+
oats.aweb: { registry: https://registry.example.org } # the host-side mint (C6)
|
|
792
|
+
```
|
|
793
|
+
|
|
794
|
+
- `sandboxes` lists distinct names that the workspace declares. An unknown name is
|
|
795
|
+
refused (`E_WORKSPACE_SCHEMA`, reason `sandbox-unknown`), a duplicate likewise
|
|
796
|
+
(`duplicate-entry`), and so is a listed sandbox with no `host.name` (reason
|
|
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).
|
|
800
|
+
- `credentials` uses the kernel's existing `fromFile` form. A listed sandbox whose
|
|
801
|
+
declared credential has no source here refuses its start, naming the credential.
|
|
802
|
+
- The teamctl file holds infrastructure only (images, network, ports, state directory,
|
|
803
|
+
limits). The provider refuses a file that sets a boundary field the workspace owns
|
|
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`,
|
|
805
|
+
`aweb.federationOutbound`): boundaries are declared once. The refusal is
|
|
806
|
+
`E_SANDBOX_DEPLOYMENT`, reason `boundary-field`, naming the field (r1). The
|
|
807
|
+
resolvers the external roles need, `egress.external.resolvers`, are host
|
|
808
|
+
infrastructure and stay in the teamctl file; a sandbox whose workspace egress names
|
|
809
|
+
an external role and whose file gives no resolvers refuses its start (reason
|
|
810
|
+
`resolvers-required`) (r3, contract). The provider writes the role booleans from
|
|
811
|
+
the workspace. Example: `egress: { external: { resolvers: [1.1.1.1, 9.9.9.9] } }`
|
|
812
|
+
in the teamctl file, with C1's `egress: [model, source, forge]`.
|
|
813
|
+
- **A private registry.** oats.aweb refuses an ambient `AWID_REGISTRY_URL`
|
|
814
|
+
(awebai/oats-aweb#284), so where the instance's team's registry is private the setting
|
|
815
|
+
is written twice: `settings.oats.aweb.registry` on the host deployment, for the mint
|
|
816
|
+
and for `remove-member` (C6), and the same key in the sandbox's `settings`, which the
|
|
817
|
+
provider writes into the in-sandbox local file. Without the in-sandbox one, the
|
|
818
|
+
in-sandbox spawn refuses with `registry-setting-required`.
|
|
819
|
+
|
|
820
|
+
### C3b. `oats-local.yaml` inside a sandbox: `sandbox: { self: <name> }` (new root key)
|
|
821
|
+
|
|
822
|
+
The provider writes it into the in-sandbox deployment's local file. It is a contract of
|
|
823
|
+
its own because a kernel reads it:
|
|
824
|
+
|
|
825
|
+
- `self` must name a sandbox the workspace declares. That deployment then spawns only
|
|
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.
|
|
843
|
+
- It may not be combined with `sandboxes:` (a sandbox runs no sandboxes),
|
|
844
|
+
`credentials:` (credentials reach it as mounts only), local `teams:` or local
|
|
845
|
+
`defaultTeam`. Each combination is refused with `E_WORKSPACE_SCHEMA`, reason
|
|
846
|
+
`sandbox-self-conflict`.
|
|
847
|
+
- An older kernel refuses the key as unknown. That is why the agent image's kernel is
|
|
848
|
+
the release that has feature `sandboxes`.
|
|
849
|
+
|
|
850
|
+
### C4. The kernel–provider hook: `sandbox`
|
|
851
|
+
|
|
852
|
+
A new capability hook event, `sandbox`.
|
|
853
|
+
|
|
854
|
+
**Which capability provides it (r1).** Sandbox acts run at deployment level, with no
|
|
855
|
+
soul. The candidates are the capabilities the workspace's `defaults` compose (the
|
|
856
|
+
same resolution a spawn uses, without a soul's layer) whose manifest declares the
|
|
857
|
+
`sandbox` hook. Exactly one must exist: none refuses any sandbox act with
|
|
858
|
+
`E_SANDBOX_PROVIDER`, reason `none`; two or more, reason `ambiguous`, naming them. Its
|
|
859
|
+
settings are its manifest defaults, then the workspace defaults, then the host's
|
|
860
|
+
`settings.<capability>` in `oats-local.yaml`, merged as for a spawn.
|
|
861
|
+
|
|
862
|
+
**The call.** The kernel runs the hook with `OATS_SANDBOX_ACT` set to `plan`, `start`,
|
|
863
|
+
`stop`, `status`, `reconcile`, `seat`, `bind` or `release`, one JSON request on stdin, and reads one JSON
|
|
864
|
+
answer on stdout. The kernel holds a per-sandbox lock around every act but `plan` and
|
|
865
|
+
`status`, so two mutating acts on one sandbox never run at once (a second gets
|
|
866
|
+
`E_LIFECYCLE_BUSY`). The lock, the plan revisions and the idempotency keys are all
|
|
867
|
+
scoped to the deployment and the sandbox (C7's deployment key) (r2). A
|
|
868
|
+
hook that exits nonzero, times out or prints anything but one valid answer is read as
|
|
869
|
+
`state: "unknown"` with problem `E_SANDBOX_PROVIDER`, reason `hook-failed`.
|
|
870
|
+
|
|
871
|
+
**Every request** carries:
|
|
872
|
+
|
|
873
|
+
```json
|
|
874
|
+
{"sandboxApi":1,"act":"start","sandbox":"ingest","host":"cloud-1",
|
|
875
|
+
"souls":[{"soul":"knowledge/knowledge-ingestor",
|
|
876
|
+
"team":{"label":"ingest-team","id":"ingest:example.org"}}],
|
|
877
|
+
"excludeCapabilities":["acme-deploy"],
|
|
878
|
+
"egress":["model","source"],
|
|
879
|
+
"credentials":[{"name":"sources-read","path":"/srv/…"}],
|
|
880
|
+
"workspace":{"url":"…","commit":"…","lock":"<sha256>"}}
|
|
881
|
+
```
|
|
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
|
+
|
|
888
|
+
and by act:
|
|
889
|
+
|
|
890
|
+
| Act | Extra request fields | Answer fields beyond the envelope |
|
|
891
|
+
| --- | --- | --- |
|
|
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>}}` |
|
|
893
|
+
| `start`, `stop`, `reconcile` | `planRevision`, `idempotencyKey` | `server`; for `reconcile`, `seats` as in `status` |
|
|
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}` |
|
|
897
|
+
| `release` | `planRevision`, `idempotencyKey`, `instance: {name, seatId}`, `reason`: `retired` or `spawn-failed` | `seat: {id, certificateId, state}` |
|
|
898
|
+
|
|
899
|
+
**The envelope** of every answer:
|
|
900
|
+
|
|
901
|
+
```json
|
|
902
|
+
{"sandboxApi":1,"act":"…","state":"ready|stopped|absent|failed|unknown|stale",
|
|
903
|
+
"receipts":[{"step":"render|probe|start|register|deploy|mint|deliver|remove","ok":true,"detail":"…"}],
|
|
904
|
+
"problem":{"code":"…","reason":"…","message":"…","remedy":"…"}}
|
|
905
|
+
```
|
|
906
|
+
|
|
907
|
+
- `plan` and `status` are read-only: they change no state, delete no staging and remove
|
|
908
|
+
no member (r2). Every other act mutates, and runs under the lock.
|
|
909
|
+
- `plan` is read-only. Its `planRevision` binds the request's inputs and the
|
|
910
|
+
provider's own state for that sandbox (and, for `seat` and `release`, that
|
|
911
|
+
instance's ledger entry).
|
|
912
|
+
- **The provider owns revisions and receipts.** It checks `planRevision` on every
|
|
913
|
+
act that carries one, and answers `state: "stale"` with a fresh plan in `plan`; the
|
|
914
|
+
kernel reports that as `E_PLAN_STALE` with the fresh plan, on the pattern of `oats
|
|
915
|
+
instance stop`. It keeps each `idempotencyKey`'s receipt in its state on the host,
|
|
916
|
+
and the same key replays that receipt and changes nothing.
|
|
917
|
+
- `seat` mints and delivers one instance's seat, in the order the Identities section
|
|
918
|
+
gives. A replay of its key returns the same seat, or `unknown`, and never mints a
|
|
919
|
+
second identity. The kernel passes the seat plan's `spawnProvider` to the final
|
|
920
|
+
preview and to the apply alike, as `--provider <capability> <key>=<value>`, one per
|
|
921
|
+
option, so the kernel names no messaging provider. Dotted keys nest, so oats.aweb
|
|
922
|
+
answers `{capability: "oats.aweb", options: {"identity.seat": "<path>"}}`, which sets
|
|
923
|
+
its `identity.seat` (C6) (r2).
|
|
924
|
+
- `bind` and `reconcile` settle seats as the Identities and Lifecycle sections say:
|
|
925
|
+
`bind` from the routed apply's answer or the kernel's keyed replay of it (for
|
|
926
|
+
`delivered` seats), `reconcile` from the sandbox's untrusted report (for `active`
|
|
927
|
+
seats) and the interrupted-mint rule. The provider runs no spawn. The
|
|
928
|
+
staging sweep for a killed hook runs in the mutating acts only: under the lock no
|
|
929
|
+
`seat` can be running, so any staging copy found is a leftover.
|
|
930
|
+
- An act whose outcome is uncertain answers `unknown`, never `ready`.
|
|
931
|
+
|
|
932
|
+
### C5. CLI and JSON
|
|
933
|
+
|
|
934
|
+
- `oats sandbox status [--json]`, `oats sandbox start|stop <name> (--plan | --plan-revision <r> --idempotency-key <k>)`.
|
|
935
|
+
- `oats sandbox status --json` answers
|
|
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`.
|
|
948
|
+
- `oats sandbox start|stop <name> --plan --json` answers
|
|
949
|
+
`{sandboxApi:1, sandbox, act, planRevision, actions}`; the apply answers
|
|
950
|
+
`{sandboxApi:1, sandbox, act, state, server, receipts, problems}`, and a stale
|
|
951
|
+
revision refuses `E_PLAN_STALE` with the fresh plan in its detail (r1).
|
|
952
|
+
- `oats sync --json` gains `sandboxes` with the same entries plus `action`
|
|
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.
|
|
963
|
+
- `oats status --json` gains `placement: {sandbox, seatId}` on each instance placed in
|
|
964
|
+
one; `seatId` is the seat its home took (r2).
|
|
965
|
+
- `oats sandbox status --json`'s entries also carry `seats` (as C4's `status`), and
|
|
966
|
+
`oats sandbox reconcile <name> (--plan | --plan-revision <r> --idempotency-key <k>)`
|
|
967
|
+
runs on its own what sync runs for each sandbox: the `reconcile` act, then the
|
|
968
|
+
replays of the kept requests whose entries it answers durably `delivered` (r2, r3,
|
|
969
|
+
r4d).
|
|
970
|
+
- **That these are additive must be shown, not assumed.** The readers of sync's answer
|
|
971
|
+
are `packages/desktop/server/workspace-sync.mjs`,
|
|
972
|
+
`packages/desktop/renderer/workspace-sync-view.mjs`,
|
|
973
|
+
`packages/client/deployment-data.mjs` and `packages/client/workspace-cli.mjs`. The
|
|
974
|
+
readers of the status answer are the client's roster readers and the warm reader. S1
|
|
975
|
+
lists every reader it finds, with file and line, and pins one test per reader feeding
|
|
976
|
+
it an answer with the new fields. If a reader refuses unknown fields, the change is
|
|
977
|
+
not additive: that answer's API version goes up, and the reader changes first, in its
|
|
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).
|
|
982
|
+
|
|
983
|
+
### C6. oats.aweb settings and behaviour
|
|
984
|
+
|
|
985
|
+
- `identity.seat` (new): an absolute path to a one-use seat delivered by the host. The
|
|
986
|
+
spawn copies it the way it copies `identity.source`, takes no retained-seat lock, and
|
|
987
|
+
deletes the delivered copy after connecting. It is refused together with
|
|
988
|
+
`identity.source` and with global mode. A preview reads nothing from it; an apply
|
|
989
|
+
needs it.
|
|
990
|
+
- **The seat descriptor (r2).** The retained route reads its service from the
|
|
991
|
+
source's `workspace.yaml`, which is not an authority file. A delivered seat instead
|
|
992
|
+
carries `seat.json`, written by the host at mint:
|
|
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).
|
|
997
|
+
The spawn reads its service from that descriptor only, never from `OATS_AWEB_URL` or
|
|
998
|
+
a copied coordination workspace, and checks it: `team` equals the team the spawn
|
|
999
|
+
resolved, `alias` equals the instance name, `spawnKey` equals the apply's key, and
|
|
1000
|
+
`service` is a plain https origin. The apply's key reaches the spawn hook through a
|
|
1001
|
+
new, generic hook variable, `OATS_SPAWN_IDEMPOTENCY_KEY`, set by the kernel on a
|
|
1002
|
+
keyed apply and absent otherwise (r3, contract: the hook environment; S1 sets it and
|
|
1003
|
+
pins it, S2 consumes it). An unkeyed apply with `identity.seat` is refused (reason
|
|
1004
|
+
`seat-binding`, field `spawnKey`); the provider never takes the expected key from
|
|
1005
|
+
the descriptor it validates. A missing, malformed or contradictory descriptor
|
|
1006
|
+
refuses the spawn (reason `seat-binding`, naming the field). The host's registry pin
|
|
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.
|
|
1020
|
+
- Retire, for an identity minted by the host for a sandbox: the host runs
|
|
1021
|
+
`aw id team remove-member` with the controller key it holds, and reports it, from
|
|
1022
|
+
the routed retire or from reconcile (the Lifecycle section). It
|
|
1023
|
+
removes by the certificate ID that the mint recorded, never by alias. It removes only
|
|
1024
|
+
an identity listed in the provider's ledger of seats this host minted for this
|
|
1025
|
+
sandbox. An identity it did not mint is never removed, and is reported instead. It
|
|
1026
|
+
uses the host's configured registry pin (`settings.oats.aweb.registry`, C3), and
|
|
1027
|
+
records its receipt in the retire's meta. A failure, or an outcome it cannot be sure
|
|
1028
|
+
of, keeps today's recorded command and warning, and is never retried automatically.
|
|
1029
|
+
- Between mint and delivery, the instance's private key sits in the host's staging
|
|
1030
|
+
directory (0700, under the operator account). `seat` deletes the staging copy on
|
|
1031
|
+
every path: success, a failed mint, a failed delivery, a timeout and an interrupted
|
|
1032
|
+
hook. The next mutating act (C4) finds and removes a copy left by a killed hook, and
|
|
1033
|
+
reports it; `status` only reports it (r2). One test per path pins this.
|
|
1034
|
+
- `oats.aweb-sandbox` (new capability, same package): its settings are
|
|
1035
|
+
`sandboxes.<name>.deployment` and `sandboxes.<name>.settings` (C3).
|
|
1036
|
+
|
|
1037
|
+
### C7. The sandbox's server registration
|
|
1038
|
+
|
|
1039
|
+
The provider registers each started sandbox as server `sandbox-<name>`, using the
|
|
1040
|
+
existing Docker-context SSH relay from container.md.
|
|
1041
|
+
|
|
1042
|
+
- It uses only the fields `servers.json` accepts today (`sshHost`, `workspace`,
|
|
1043
|
+
`oatsPath`, `path`), so an older kernel still reads the file. Anything else the
|
|
1044
|
+
provider keeps goes in its own state, never in `servers.json`.
|
|
1045
|
+
- The `sshHost` alias lives in an OpenSSH file the provider owns,
|
|
1046
|
+
`~/.oats/sandboxes/ssh_config`, which holds the relay, the per-sandbox operator key
|
|
1047
|
+
it generates and the known-hosts file it provisions from the sandbox's host key. The
|
|
1048
|
+
operator adds one `Include` of that file to their own SSH configuration once. Readiness
|
|
1049
|
+
reports `sandbox-ssh-include-missing` until they have.
|
|
1050
|
+
- The `sandbox-` prefix is reserved. A new `oats server add|connect` with that prefix is
|
|
1051
|
+
refused (`E_SERVER_INVALID`, reason `reserved-prefix`). A `sandbox-*` server that is
|
|
1052
|
+
already registered is reported by `oats sandbox status`, not refused: refusing
|
|
1053
|
+
configuration that was accepted before would itself be a contract change. The provider
|
|
1054
|
+
will not adopt or overwrite it, and that sandbox's start refuses, naming the server
|
|
1055
|
+
(`E_SANDBOX_SERVER`, reason `server-taken`).
|
|
1056
|
+
- **Its own registration is not "already registered" (r1).** The provider records
|
|
1057
|
+
each registration it made in its state, with the `servers.json` entry it wrote. A
|
|
1058
|
+
`sandbox-<name>` server that matches its record is its own: a restart reuses it, and
|
|
1059
|
+
stop and delisting keep it and the record, so the sandbox can start again. Only a
|
|
1060
|
+
`sandbox-*` server with no matching record counts as taken.
|
|
1061
|
+
- **Scoped to the deployment (r2).** `servers.json`, the SSH file and the provider's
|
|
1062
|
+
state are per OS user, and two deployments of that user may each declare a sandbox
|
|
1063
|
+
of the same name. So the provider's state lives under a deployment key, the first 16
|
|
1064
|
+
hex digits of the SHA-256 of the host deployment directory's real path:
|
|
1065
|
+
`~/.oats/sandboxes/<deployment-key>/<sandbox>/`. The registration record names its
|
|
1066
|
+
deployment key. A `sandbox-<name>` server recorded for another deployment key is
|
|
1067
|
+
never reused, stopped or overwritten: this deployment's start refuses
|
|
1068
|
+
(`E_SANDBOX_SERVER`, reason `server-owned-elsewhere`, naming the other deployment
|
|
1069
|
+
directory). The public name stays `sandbox-<name>`.
|
|
1070
|
+
- **A moved deployment.** Moving or renaming the deployment directory changes its key
|
|
1071
|
+
and orphans its sandboxes' ledger, lock and receipts. Readiness reports
|
|
1072
|
+
`sandbox-state-orphaned` when provider state under another key holds a sandbox this
|
|
1073
|
+
deployment lists, naming the old key. It is never adopted automatically; the remedy
|
|
1074
|
+
names moving the directory back, or the manual adoption step S2 specifies.
|
|
1075
|
+
|
|
1076
|
+
### C8. teamctl and the container (aweb's maintainers)
|
|
1077
|
+
|
|
1078
|
+
- **Credential mount:** a new teamctl input, `agents.credentials`, a map from name to a
|
|
1079
|
+
host file. It is rendered as read-only binds at `/run/oats-credentials/<name>` through a
|
|
1080
|
+
new `container/agent/compose.agent.credentials.yaml` fragment. teamctl's
|
|
1081
|
+
`agents.secrets` stays the harness login only.
|
|
1082
|
+
- **Probe:** the boundary probe asserts that each credential mount is read-only, that
|
|
1083
|
+
it lies only under `/run/oats-credentials`, and that no undeclared credential path is
|
|
1084
|
+
mounted. Its receipt joins the probe's `--json` receipts (#1958).
|
|
1085
|
+
- **Protected sources (r1, r2, r3):** the provider writes one JSON file per start,
|
|
1086
|
+
`{"protectedSourcesApi":1, "hardDenied":[<path>], "credentialSources":[<path>],
|
|
1087
|
+
"declaredBinds":[{"source":<path>,"target":"/run/oats-credentials/<name>"}]}`, with
|
|
1088
|
+
real paths, and gives it to teamctl as a new input, `agents.protectedSourcesFile`
|
|
1089
|
+
(contract: teamctl's schema, aweb's maintainers). teamctl passes it to the container's
|
|
1090
|
+
mount acceptance, which takes those three parts and, on the started
|
|
1091
|
+
agent's actual mounts, asserts that no bind equals, contains or lies inside a
|
|
1092
|
+
protected path, the declared credential binds being the only exception to the
|
|
1093
|
+
credential-source part. It runs before any seat is admitted.
|
|
1094
|
+
- **Optional, later:** a slimmer profile without Secrets and Logs. v1 runs with
|
|
1095
|
+
teamctl's four base routes.
|
|
1096
|
+
- teamctl's changes are these three inputs: `agents.credentials`,
|
|
1097
|
+
`agents.protectedSourcesFile` and `egress.external.forge`. OATS reads its exit codes
|
|
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.
|
|
1122
|
+
|
|
1123
|
+
### C9. Broker contracts (designed now, built against the first real provider)
|
|
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
|
+
|
|
1142
|
+
Both follow aweb's three rules. An agent never reads or exports a value. Approval is a
|
|
1143
|
+
state with a reference, and the same request is resubmitted under the same request ID.
|
|
1144
|
+
Authority, custody, approval, where execution happens, audit and withholding all stay
|
|
1145
|
+
with the provider. Inside a sandbox, an agent reaches a broker through the sandbox's
|
|
1146
|
+
egress routes only.
|
|
1147
|
+
|
|
1148
|
+
- **Secrets:** `oats credential list [--json]` shows only the names the caller is
|
|
1149
|
+
granted. `oats credential use <name> --action <action> --request-id <id> [--input-file <f>] --json`
|
|
1150
|
+
answers `{requestId, state: "done"|"awaiting-approval"|"refused"|"unknown"|"withheld", approvalRef?, result?}`.
|
|
1151
|
+
There is no verb that returns a value. A capability implements the contract through a
|
|
1152
|
+
`credential-broker` hook with the same request and answer.
|
|
1153
|
+
- **Connectors:** a sandbox may list `connectors: [<name>]` in C1, a later optional
|
|
1154
|
+
key. `oats connector call <name> <operation> --request-id <id> [--input-file <f>] --json`
|
|
1155
|
+
takes the same outcome states, through a `connector-broker` hook. aweb has no
|
|
1156
|
+
connectors broker built or filed, and whether one is planned is for aweb's maintainers to say. The
|
|
1157
|
+
shape is offered so that a provider-neutral gateway can implement it. It stays
|
|
1158
|
+
designed only, and is not built, until aweb's maintainers say whether aweb plans a connectors
|
|
1159
|
+
broker and a provider exists.
|
|
1160
|
+
- **Order:** both contracts are agreed in this record. Each is built when its first real
|
|
1161
|
+
provider ships, and checked against that provider's interface before it is released.
|
|
1162
|
+
This keeps the product owner's decision to design both now, and aweb's maintainers' point that a public
|
|
1163
|
+
contract must not take its shape from one unshipped product.
|
|
1164
|
+
- **What S4's spec settles before it is built (r1),** each a contract both sides
|
|
1165
|
+
agree: the `credential list` JSON and its hook request; how the broker capability
|
|
1166
|
+
is selected, and the no-provider refusal; how the caller and its grant are bound
|
|
1167
|
+
to a request; the scope of a request ID, and what a resubmission with the same ID
|
|
1168
|
+
but a different payload gets; and how `result` is kept free of secret values.
|
|
1169
|
+
Agreement on this outline is not permission for a provider to choose those.
|
|
1170
|
+
- **A change the provider forces is a contract decision.** If checking against the
|
|
1171
|
+
first real provider shows the agreed shape must change, the change goes back to both
|
|
1172
|
+
sides as a contract decision before it is built. It is never a doc edit.
|
|
1173
|
+
|
|
1174
|
+
### C10. Readiness reports; the acts refuse
|
|
1175
|
+
|
|
1176
|
+
`oats readiness` reports, and refuses nothing. Its new items are:
|
|
1177
|
+
|
|
1178
|
+
- `sandbox-listed-not-running`;
|
|
1179
|
+
- `sandbox-credential-missing`;
|
|
1180
|
+
- `sandbox-host-agents`: a deployment that lists a sandbox has host-placed instances,
|
|
1181
|
+
running or stopped;
|
|
1182
|
+
- `sandbox-provider-missing`;
|
|
1183
|
+
- `sandbox-ssh-include-missing`;
|
|
1184
|
+
- `sandbox-seat-unsettled`: a `mint-uncertain` seat, with or without a certificate
|
|
1185
|
+
ID (r4d: one whose delivered copy could not be confirmed deleted stays here); a
|
|
1186
|
+
`delivered` seat with no kept request, including one whose release waits on a copy
|
|
1187
|
+
deletion that could not be confirmed; or a `delivered` seat whose last replay
|
|
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
|
|
1191
|
+
negative: a known certificate ID whose copy deletion fails gives no replay, no home,
|
|
1192
|
+
and this item;
|
|
1193
|
+
- `sandbox-state-orphaned`: provider state under another deployment key for a
|
|
1194
|
+
sandbox this deployment lists (r2);
|
|
1195
|
+
- `sandbox-pending-stale`: a kept routed request older than 24 hours, named by its
|
|
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).
|
|
1202
|
+
|
|
1203
|
+
The refusals belong to the acts:
|
|
1204
|
+
|
|
1205
|
+
| Condition | Refused by | Code |
|
|
1206
|
+
| --- | --- | --- |
|
|
1207
|
+
| Listed sandbox, no provider | `oats sandbox start`, sync's start, a routed spawn | `E_SANDBOX_PROVIDER` |
|
|
1208
|
+
| A declared credential with no source, or a missing source file | `oats sandbox start`, sync's start | `E_SANDBOX_CREDENTIAL` |
|
|
1209
|
+
| A host-placed spawn in a deployment that lists a sandbox | `oats spawn`, a schedule's spawn | `E_SANDBOX_HOST_AGENT` |
|
|
1210
|
+
| Starting, restarting or resuming a host-placed home there (r1) | `oats session start`, the resume sweep | `E_SANDBOX_HOST_AGENT` |
|
|
1211
|
+
| A running or unreadable host-placed home when a sandbox starts (r1) | `oats sandbox start`, sync's start | `E_SANDBOX_HOST_AGENT` |
|
|
1212
|
+
| A spawn inside a sandbox without a host-delivered seat (r1) | the in-sandbox `oats spawn` | `E_SANDBOX_PLACEMENT`, `spawn-from-host` |
|
|
1213
|
+
| A teamctl file that sets a boundary field (r1) | `oats sandbox start`, sync's start | `E_SANDBOX_DEPLOYMENT`, `boundary-field` |
|
|
1214
|
+
| A mount that overlaps a protected path, or shared sandbox state (r1) | `oats sandbox start`, sync's start | `E_SANDBOX_MOUNT`, `overlap` |
|
|
1215
|
+
| A credential source that is not a regular file (r1) | `oats sandbox start`, sync's start | `E_SANDBOX_CREDENTIAL`, `not-a-file` |
|
|
1216
|
+
| A credential source with more than one hard link (r3) | `oats sandbox start`, sync's start | `E_SANDBOX_CREDENTIAL`, `hardlinked` |
|
|
1217
|
+
| An external egress role with no resolvers in the teamctl file (r3) | `oats sandbox start`, sync's start | `E_SANDBOX_DEPLOYMENT`, `resolvers-required` |
|
|
1218
|
+
| An unkeyed apply carrying `identity.seat` (r3) | the in-sandbox apply | `seat-binding` (oats.aweb), field `spawnKey` |
|
|
1219
|
+
| `sandbox-<name>` registered by someone else (r1) | `oats sandbox start`, sync's start | `E_SANDBOX_SERVER`, `server-taken` |
|
|
1220
|
+
| `sandbox-<name>` owned by another deployment (r2) | `oats sandbox start`, sync's start | `E_SANDBOX_SERVER`, `server-owned-elsewhere` |
|
|
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` |
|
|
1223
|
+
| A delivered seat with a missing or contradictory descriptor (r2) | the in-sandbox apply | `seat-binding` (oats.aweb) |
|
|
1224
|
+
| No provider, or more than one (r1) | every sandbox act | `E_SANDBOX_PROVIDER`, `none` or `ambiguous` |
|
|
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
|
|
1253
|
+
deployment that lists a sandbox runs every agent in a sandbox. Agents that belong on the
|
|
1254
|
+
host run from another deployment, under another OS user. This replaces checking file
|
|
1255
|
+
modes against users, which cannot be proved from inside one account.
|
|
1256
|
+
|
|
1257
|
+
## Left out of v1
|
|
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
|
+
|
|
1262
|
+
- Creating or deleting machines.
|
|
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).
|
|
1274
|
+
- Human IDs by default and `oats sandbox adopt`. These wait on aweb's maintainers' decision
|
|
1275
|
+
on reversing "strictly opt-in" (#1665). Adoption is specified once
|
|
1276
|
+
those are settled.
|
|
1277
|
+
- Publishing the image, and its digest in the lock.
|
|
1278
|
+
|
|
1279
|
+
## Alternatives rejected
|
|
1280
|
+
|
|
1281
|
+
- **A groups block with its own soul list:** it writes the soul-to-team mapping twice.
|
|
1282
|
+
- **Sandbox fields inside team entries:** no named container would remain to list, build
|
|
1283
|
+
or show.
|
|
1284
|
+
- **`hostedBy: everyone` for containers:** Docker could start on a laptop that never
|
|
1285
|
+
asked for it.
|
|
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.
|
|
1303
|
+
- **Docker in the kernel:** the kernel stays runtime-neutral; the provider owns
|
|
1304
|
+
containers.
|
|
1305
|
+
- **The container's own clock beside the host's:** two owners of one schedule.
|
|
1306
|
+
- **Free-form egress origins:** the egress component's guarantee rests on a closed set
|
|
1307
|
+
of roles.
|
|
1308
|
+
- **Credentials through teamctl's `agents.secrets`:** that mount is the harness login
|
|
1309
|
+
only, by its own contract.
|
|
1310
|
+
- **A lease service for schedules:** none exists, and `runsOn` already names one host.
|
|
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
|
+
|
|
1324
|
+
## Delivery
|
|
1325
|
+
|
|
1326
|
+
| Spec | Surface | Lane | Builds first |
|
|
1327
|
+
| --- | --- | --- | --- |
|
|
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 |
|
|
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 |
|
|
1332
|
+
| S4 Broker contracts: C9 docs, then the client verbs | `docs/`, `lib/` | lane:product | after the first real provider |
|
|
1333
|
+
|
|
1334
|
+
Each spec carries its own reference pages and a release-notes entry of its own under
|
|
1335
|
+
`docs/release-notes/next/` (r1):
|
|
1336
|
+
|
|
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)
|
|
1339
|
+
and the manifest schema (the `sandbox` hook, C4), the CLI and JSON pages (C5),
|
|
1340
|
+
[servers.md](../servers.md) (the reserved prefix, C7), and readiness (C10).
|
|
1341
|
+
- S2: the oats-aweb package's own docs (`identity.seat`, the registry setting,
|
|
1342
|
+
`oats.aweb-sandbox`'s settings, the ledger and reconcile).
|
|
1343
|
+
- S3: [container.md](../container.md) (the credential fragment and its probe) and
|
|
1344
|
+
teamctl's docs on aweb's maintainers' side.
|
|
1345
|
+
- S4: the broker contracts' reference page, when it is built.
|
|
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
|
+
|
|
1350
|
+
The live rehearsal runs on a disposable Linux Docker host, never on a person's machine.
|
|
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.
|