Skip to content

Commit d20f292

Browse files
wz-gsaOpenCode Agent
andcommitted
docs(isolation): restructure ADR 0004 Layer 1 artifact to a per-provider directory
Design amendment, landed separately from the accuracy/citation fixes in the prior commit per the consensus panel's recommendation (7-role higher_order vote, 85.7% approve): several voters flagged this as a schema change to the Layer 1 contract, not a wording fix, and asked that it be independently reviewable/revertable from the citation and claim corrections. The gap: the v1 facts file has no field locating a provider's normalizer or vendored snapshot, yet Layer 2 steps 2 and 4 require the orchestrator to resolve both. Two independent provider-kit authors implementing v1 as written could place those artifacts at different conventions, and the orchestrator would find neither — undermining the ADR's own central interoperability claim ("a third-party provider kit works with no PR into the orchestrator"). Fix: replace the single per-provider JSON file with a fixed per-provider directory (facts.json + normalizer + snapshot.json), materialized read-only as a unit. Updated Layer 2's glob (step 1) and its normalizer/snapshot resolution (steps 2 and 4) to locate both artifacts as siblings of the facts.json just read. Layer 3's read-list (added in the prior commit) is updated to the corrected path. The mermaid trust-boundary diagram is left unchanged: its RO participant description and the one path-like string in the diagram (`providers/evil.json` in the adversary-attempt line) don't cite the specific single-file convention this commit changes, so nothing there needed to move. markdownlint: 0 issues. Content verified against the full draft produced during review (byte-identical diff, confirmed before commit). Co-authored-by: OpenCode Agent <[email protected]>
1 parent 3b565fd commit d20f292

1 file changed

Lines changed: 29 additions & 19 deletions

File tree

‎integrations/isolation/docs/decisions/0004-neutral-model-provider-discovery.md‎

Lines changed: 29 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -58,17 +58,22 @@ change is required.
5858

5959
### Layer 1 — Provider kit self-registration (host-materialized, read-only)
6060

61-
A provider-role kit ships a small, static JSON **facts file** inside its own
62-
(pinned) kit directory. At provision, `acq` reads that static file **on the
63-
host**, validates it host-side (see [Security model](#security-model)), and
64-
materializes it into a per-sandbox host directory that it mounts **read-only**
65-
into the guest at a well-known path:
61+
A provider-role kit ships a small, static JSON **facts file**, a **normalizer**
62+
entrypoint, and a **vendored fallback snapshot**, all inside its own (pinned)
63+
kit directory. At provision, `acq` reads those static artifacts **on the
64+
host**, validates the facts file host-side (see
65+
[Security model](#security-model)), and materializes all three into a
66+
per-sandbox host directory that it mounts **read-only** into the guest as a
67+
fixed per-provider layout at a well-known path:
6668

6769
```text
68-
/var/lib/acq/host/models/providers/<PROVIDER_ID>.json (read-only mount)
70+
/var/lib/acq/host/models/providers/<PROVIDER_ID>/ (read-only mount)
71+
├── facts.json # 6-field facts shape (v1), below
72+
├── normalizer # provider's normalizer entrypoint (executable)
73+
└── snapshot.json # provider's vendored fallback snapshot
6974
```
7075

71-
Facts file shape (v1):
76+
`facts.json` shape (v1):
7277

7378
```json
7479
{
@@ -101,14 +106,16 @@ before that variable is ever read. This check is a mechanical string comparison,
101106
runs host-side as part of facts validation, and prevents a kit from naming an
102107
unrelated credential (e.g. `GITHUB_TOKEN`).
103108

104-
Each provider kit also ships, inside its own kit directory (never centrally):
109+
Each provider kit also ships, inside its own kit directory (never centrally),
110+
as siblings of `facts.json` in the materialized `<PROVIDER_ID>/` directory
111+
above:
105112

106-
- its **normalizer** — code that maps the raw vendor API response to the neutral
113+
- `normalizer` — code that maps the raw vendor API response to the neutral
107114
catalog schema. The vendor's own author knows its API shape best, so no central
108115
kit accumulates per-vendor knowledge that rots; and
109-
- a **vendored fallback snapshot** — a small, committed, last-known-good model
110-
list used when a live refresh fails, so a bad fetch degrades to *that
111-
provider's* last-known-good list.
116+
- `snapshot.json` — a small, committed, last-known-good model list used when a
117+
live refresh fails, so a bad fetch degrades to *that provider's*
118+
last-known-good list.
112119

113120
Keying the credential by provider (not by harness) means a second harness kit
114121
reaching the same vendor reuses the same secret-store service identity,
@@ -123,17 +130,20 @@ guarantees `zscaler-ca-certificate` runs before kits that need its CA trust
123130
Its `startup` phase:
124131

125132
1. Globs the read-only provider-facts mount
126-
`/var/lib/acq/host/models/providers/*.json` (Layer 1).
127-
2. For each discovered provider, invokes that provider's own normalizer through a
128-
shared, vendored-into-this-kit bounded-fetch helper (per-provider timeout +
129-
response-size cap), with one canonical implementation of that helper.
133+
`/var/lib/acq/host/models/providers/*/facts.json` (Layer 1).
134+
2. For each discovered provider, invokes that provider's own normalizer —
135+
`<PROVIDER_ID>/normalizer`, the sibling of the `facts.json` just read —
136+
through a shared, vendored-into-this-kit bounded-fetch helper (per-provider
137+
timeout + response-size cap), with one canonical implementation of that
138+
helper.
130139
3. Validates the normalizer's **output** against the neutral catalog schema
131140
before accepting it — a structurally-valid-but-wrong response is still a
132141
routing hazard, so shape validation runs on every refresh, not only on error
133142
paths.
134143
4. On any failure (timeout, oversized, malformed, validation failure, or no
135-
provider present) falls back to that provider's vendored snapshot, presented
136-
on the same read-only mount.
144+
provider present) falls back to that provider's vendored snapshot —
145+
`<PROVIDER_ID>/snapshot.json`, the sibling of the `facts.json` just read —
146+
presented on the same read-only mount.
137147
5. Aggregates every provider's neutral output into one **guest-local,
138148
per-sandbox** file, written read-write and never shared with any other
139149
sandbox: `/var/lib/acq/models/catalog.json`. The aggregate carries **only
@@ -185,7 +195,7 @@ same ordering convention), reads:
185195
**model metadata only** (id, context window, pricing, capabilities,
186196
provenance);
187197
- the Layer 1 read-only facts mount,
188-
`/var/lib/acq/host/models/providers/<PROVIDER_ID>.json` — for
198+
`/var/lib/acq/host/models/providers/<PROVIDER_ID>/facts.json` — for
189199
**routing/credential fields** (`host`, `baseUrl`, `keyEnv`) — never from the
190200
catalog, since the catalog is guest-writable and cannot be authoritative for
191201
where a credential is sent (see [Security model](#security-model)); and

0 commit comments

Comments
 (0)