Skip to content

Commit 78d88e4

Browse files
mogulOpenCode Agent
andauthored
feat(isolation): support backend-supplied provider roots (#522)
## Summary Version the provider-input contract so sandbox backends can supply their proven read-only root without changing the provider-relative layout. ## Issue resolved **#521** - Preserve the released v1 schema and fixed path unchanged. - Add a separate v2 schema with `models/providers/<providerId>`. - Provide an explicit host-validator CLI for staged external bundles. - Define fail-closed backend obligations and authoritative-empty semantics. - Keep runtime mount/consumer implementation in the Quickstart backend layer. ## Before and after **Before this PR:** Provider bundles required one fixed absolute guest root that MSB could provide but current SBX could not. **After merge:** Version 2 preserves a stable provider-relative path beneath a backend-supplied read-only root, while version 1 remains byte-compatible for existing consumers. ## Verification - Provider contract tests: 168 passed - `make validate-provider-input-contract`: passed - `make validate`: passed - `make generate-check`: passed - `make test-kits`: passed - Ruff format/lint and `git diff --check`: passed - Independent adversarial reviews: all blockers resolved ## Security impact The mandatory host validator retains strict JSON, path containment, symlink, executable, credential-binding, URL, duplicate-provider, and cross-field checks. Schema and credential-binding inputs must come from trusted pinned/backend control-plane sources. Rejected candidates fail provisioning rather than becoming an empty provider set. ## Relationships Fixes: #521 Parent epic: #357 Unblocks: GSA-TTS/agentic-coding-quickstart#600, GSA-TTS/agentic-coding-quickstart#606, and #516 ## Rollback Revert both commits in this PR. The released version 1 schema remains unchanged throughout. AI-assisted by OpenCode. Human review required. --------- Co-authored-by: OpenCode Agent <[email protected]>
1 parent d345c5c commit 78d88e4

9 files changed

Lines changed: 534 additions & 60 deletions

File tree

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
{
2-
"schemaVersion": "acq-provider-input-bundle/v1",
2+
"schemaVersion": "acq-provider-input-bundle/v2",
33
"providerId": "usai",
44
"factsPath": "provider-input/facts.json",
55
"normalizerPath": "scripts/normalize-catalog.mjs",
66
"snapshotPath": "files/home/usai-config/model-catalog-snapshot.json",
7-
"projectedPath": "/var/lib/acq/host/models/providers/usai",
7+
"providerPath": "models/providers/usai",
88
"credentialEnvNames": ["USAI_API_KEY"]
99
}

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

Lines changed: 49 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -11,11 +11,9 @@ nist_controls: ["SC-7", "AC-4", "CM-7", "SI-10"]
1111
# ADR 0004 (isolation) — Neutral model-provider discovery: provider facts, a models orchestrator kit, and harness-owned rendering
1212

1313
> Area-scoped ADR for `integrations/isolation/`. Extends the neutral `hybrid/v1`
14-
> kit spec (ADR 0001) and the network egress tiers (ADR 0002). It changes neither
15-
> schema; the mechanism composes from already-shipped primitives
16-
> (`caps.network.allow` union, sequential kit startup) plus the
17-
> host-authoritative read-only config mount defined in quickstart ADR-0035
18-
> (pending — GSA-TTS/agentic-coding-quickstart#504).
14+
> kit spec (ADR 0001) and the network egress tiers (ADR 0002). Provider input
15+
> bundles are versioned independently so the mechanism can preserve a stable
16+
> provider layout while backends supply their proven read-only guest root.
1917
2018
## Context and Problem Statement
2119

@@ -58,27 +56,46 @@ change is required.
5856

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

61-
A provider-role kit declares an `acq-provider-input-bundle/v1` manifest at its
59+
A provider-role kit declares an `acq-provider-input-bundle/v2` manifest at its
6260
kit root. The manifest declares kit-relative paths for a small, static JSON
6361
**facts file**, a **normalizer** entrypoint, and a **vendored fallback snapshot**.
6462
At provision, `acq` reads those static artifacts **on the
6563
host**, validates the facts file host-side (see
6664
[Security model](#security-model)), and materializes all three into a
67-
per-sandbox host directory that it mounts **read-only** into the guest as a
68-
fixed per-provider layout at a well-known path:
65+
per-sandbox host directory that it mounts **read-only** into the guest. Version
66+
2 fixes the provider-relative layout, not the guest root:
6967

7068
```text
71-
/var/lib/acq/host/models/providers/<PROVIDER_ID>/ (read-only mount)
69+
<ACQ_PROVIDER_INPUT_ROOT>/models/providers/<PROVIDER_ID>/ (read-only mount)
7270
├── facts.json # 7-field facts shape (v1), below
7371
├── normalizer # provider's normalizer entrypoint (executable)
7472
└── snapshot.json # provider's vendored fallback snapshot
7573
```
7674

77-
The package manifest fixes both sides of the contract: its paths are relative
78-
to the provider kit and may not traverse outside it, while `projectedPath` MUST
79-
be exactly `/var/lib/acq/host/models/providers/<providerId>`. The host validates
80-
the relationship before it copies any files. The USAi names are one provider's
81-
data, not generic paths or vocabulary.
75+
The package manifest fixes both package and provider-relative paths: its artifact
76+
paths are relative to the provider kit and may not traverse outside it, while
77+
`providerPath` MUST be exactly `models/providers/<providerId>`. The backend
78+
supplies `ACQ_PROVIDER_INPUT_ROOT` as the absolute root of its read-only mount;
79+
consumers compose the path rather than selecting a backend destination. The host
80+
validates the relationship before it copies any files. Provider names are data,
81+
not generic paths or vocabulary.
82+
83+
Version 1 remains accepted during migration. Its `projectedPath` remains exactly
84+
`/var/lib/acq/host/models/providers/<providerId>` and consumers that already
85+
understand version 1 continue to use that fixed path. New provider bundles use
86+
version 2. A future removal of version 1 requires an explicit compatibility
87+
decision after all supported consumers have moved to the supplied-root contract.
88+
89+
The Patterns validator discovers provider bundles only in `acq-kits/*`; it does
90+
not infer duplicate bundle locations from other kit layouts. Every materializer
91+
MUST invoke the Python host validator because JSON Schema cannot prove
92+
cross-field agreement, artifact containment, symlink safety, or executable-file
93+
requirements. The backend materializer owns the supplied-root value, read-only
94+
mount enforcement, symlink rejection in the materialized tree, and the required
95+
directory-name-to-`providerId` cross-check. Backend tests are mandatory
96+
acceptance for this contract; this repository does not ship a substitute
97+
consumer or mount implementation. Implementation belongs to the Quickstart
98+
backend materializer and is outside this repository.
8299

83100
`facts.json` shape (v1):
84101

@@ -132,7 +149,7 @@ not merely as a schema string. The invariant:
132149
of the directory `acq` materializes for it, and the orchestrator MUST derive
133150
each provider's identity from the **directory name it globbed**, cross-checked
134151
against the `providerId` inside that directory's `facts.json`. A mismatch is a
135-
hard failure for that provider, not a warning: it means the two sources of
152+
provisioning failure, not a warning: it means the two sources of
136153
identity disagree, and neither can be trusted to select the right credential.
137154
- **Unique within the materialized set.** Two provider kits MUST NOT resolve to
138155
the same `providerId`. `acq` fails provisioning on a collision rather than
@@ -141,9 +158,8 @@ not merely as a schema string. The invariant:
141158
code and routing for another's while keeping that other's `keyEnv`.
142159

143160
Validation runs host-side, before materialization, in the same pass as the
144-
checks below. A facts file failing it is rejected and that provider is absent
145-
from the mount — which the orchestrator treats as "no provider present"
146-
(Layer 2, step 4), never as a provider with a default identity.
161+
checks below. Any candidate bundle failing validation makes provisioning fail;
162+
it must not be converted into an absent provider or an authoritative empty set.
147163

148164
`keyEnv` names the environment variable that holds the vendor credential. A
149165
provider kit may only name a credential it declares itself: `acq` confirms
@@ -188,7 +204,7 @@ guarantees `zscaler-ca-certificate` runs before kits that need its CA trust
188204
Its `startup` phase:
189205

190206
1. Globs the read-only provider-facts mount
191-
`/var/lib/acq/host/models/providers/*/facts.json` (Layer 1).
207+
`$ACQ_PROVIDER_INPUT_ROOT/models/providers/*/facts.json` (Layer 1).
192208
2. **The helper fetches; the normalizer never does.** The shared,
193209
vendored-into-this-kit bounded-fetch helper — one canonical implementation —
194210
performs the HTTPS request to `modelsUrl` itself, applying the per-provider
@@ -240,16 +256,16 @@ Its `startup` phase:
240256
The provider still contributes entries; they are its last-known-good ones.
241257

242258
**No provider present is a different case and is NOT a snapshot fallback.**
243-
When the glob in step 1 matches nothing — no provider kit enabled, or every
244-
candidate rejected by host-side facts validation — there is no provider
259+
When authoritative discovery succeeds and finds no provider kit enabled,
260+
there is no provider
245261
directory, so there is no `snapshot.json` to read. The orchestrator MUST then
246262
write a **valid, explicitly empty** aggregate (`models: []`) carrying the
247263
provenance that zero providers were discovered, and exit success. It MUST NOT
248264
omit the file, write a partial file, invent a default provider, or fail
249265
sandbox startup: a harness kit reading the catalog must be able to tell *"no
250266
providers are configured"* from *"discovery did not run"*, and an absent file
251-
cannot express the difference. A provider whose facts failed validation is
252-
reported in that provenance as rejected, not silently absent.
267+
cannot express the difference. A candidate rejected during host validation
268+
fails provisioning before the orchestrator runs.
253269
5. Aggregates every provider's neutral output into one **guest-local,
254270
per-sandbox** file, written read-write and never shared with any other
255271
sandbox: `/var/lib/acq/models/catalog.json`. The aggregate carries **only
@@ -301,7 +317,7 @@ same ordering convention), reads:
301317
**model metadata only** (id, context window, pricing, capabilities,
302318
provenance);
303319
- the Layer 1 read-only facts mount,
304-
`/var/lib/acq/host/models/providers/<PROVIDER_ID>/facts.json` — for
320+
`$ACQ_PROVIDER_INPUT_ROOT/models/providers/<PROVIDER_ID>/facts.json` — for
305321
**routing/credential fields** (`apiProtocol`, `host`, `baseUrl`, `keyEnv`) — never from the
306322
catalog, since the catalog is guest-writable and cannot be authoritative for
307323
where a credential is sent (see [Security model](#security-model)); and
@@ -359,11 +375,11 @@ Constraints on the **aggregate** shape (`acq-neutral-model-aggregate/v1`):
359375
would force the no-provider case to either omit the file or write something
360376
invalid, which is exactly the ambiguity step 4 exists to prevent.
361377
- **Discovery provenance is required.** The aggregate records the set of
362-
providers discovered and, for each, the outcome (`live`, `snapshot`, or
363-
`rejected`). A consumer must be able to tell a live catalog from a stale one,
378+
successfully validated providers and, for each, the outcome (`live` or
379+
`snapshot`). A consumer must be able to tell a live catalog from a stale one,
364380
and *"zero providers configured"* from *"discovery did not run"*, by reading
365-
the file alone — and a provider rejected by host-side validation must be
366-
visible as rejected rather than merely absent.
381+
the file alone. Host-side validation rejection fails provisioning before an
382+
aggregate is produced.
367383
- **Each entry names its origin provider.** Entries carry the `providerId` they
368384
came from, so a consumer can attribute a model without re-deriving it. Whether
369385
that entry was live or stale is answered by the per-provider outcome above,
@@ -678,9 +694,12 @@ sequenceDiagram
678694

679695
## References
680696

697+
- `integrations/isolation/docs/provider-input-contract.md` — consumer-facing
698+
version 2 root discovery and version 1 migration rules.
681699
- `integrations/isolation/schemas/acq-provider-input-bundle.schema.json`,
682-
`acq-provider-facts.schema.json`, and `acq-neutral-model-catalog.schema.json`
683-
— formal shapes for the package manifest, provider facts, and neutral catalog.
700+
`acq-provider-input-bundle-v2.schema.json`, `acq-provider-facts.schema.json`,
701+
and `acq-neutral-model-catalog.schema.json` — formal shapes for version 1 and
702+
version 2 package manifests, provider facts, and the neutral catalog.
684703
- Quickstart ADR-0035 (*Host-Authoritative Sandbox Configuration*, pending —
685704
GSA-TTS/agentic-coding-quickstart#504) — the general principle and the
686705
per-sandbox host config dir + read-only mount + trusted-startup-execution
Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
---
2+
title: "Provider Input Bundle Consumer Contract"
3+
description: "Versioned provider bundle paths and the backend-supplied read-only consumer root."
4+
status: canonical
5+
tier: 2
6+
last_updated: "2026-10-21"
7+
---
8+
9+
# Provider Input Bundle Consumer Contract
10+
11+
Provider input bundles let provider kits publish facts, a normalizer, and a
12+
vendored model snapshot without coupling a consumer to a provider or sandbox
13+
backend. The host validates and stages these inputs; the backend materializer
14+
owns the supplied root, read-only mount, and consumer wiring.
15+
16+
## Version 2
17+
18+
New bundles use `schemaVersion: "acq-provider-input-bundle/v2"` and declare:
19+
20+
```json
21+
{
22+
"providerId": "example-provider",
23+
"providerPath": "models/providers/example-provider"
24+
}
25+
```
26+
27+
`providerPath` is a required stable relative path. It is not an absolute guest
28+
path, cannot contain traversal or dot segments, and must exactly agree with the
29+
bundle's `providerId`.
30+
31+
The backend supplies `ACQ_PROVIDER_INPUT_ROOT` as an absolute path to the
32+
read-only provider-input root. A consumer composes the provider directory as:
33+
34+
```text
35+
$ACQ_PROVIDER_INPUT_ROOT/models/providers/<providerId>
36+
```
37+
38+
The backend owns the root value. A provider bundle and a consumer must not infer
39+
or select it from a backend name.
40+
41+
The backend materializer MUST supply the root, enforce the read-only mount,
42+
reject symlinks in the materialized provider tree, and verify that each
43+
materialized directory name equals its validated `providerId`. Its offline and
44+
live backend tests must cover these requirements. This repository deliberately
45+
does not provide a synthetic consumer or mount implementation; see ADR 0004 for
46+
the tracked implementation work.
47+
48+
## Version 1 Migration
49+
50+
`acq-provider-input-bundle/v1` remains accepted. Its `projectedPath` continues
51+
to name the released fixed location
52+
`/var/lib/acq/host/models/providers/<providerId>`. Existing version 1 consumers
53+
therefore continue working unchanged.
54+
55+
New bundles must use version 2. Consumers supporting both versions use the v1
56+
fixed `projectedPath` or compose the v2 `providerPath` under the supplied root.
57+
The validation contract retains the same artifact, symlink, credential, URL,
58+
executable, and strict-JSON checks for both versions.
59+
60+
The released `acq-provider-input-bundle.schema.json` remains the v1 schema with
61+
its original `$id`. Version 2 uses
62+
`acq-provider-input-bundle-v2.schema.json` and `$id`
63+
`acq-provider-input-bundle/v2`. Every host materializer MUST invoke
64+
`scripts/validate_provider_input_contract.py`; JSON Schema alone cannot enforce
65+
cross-field agreement, file containment, symlink rejection, or executable-file
66+
checks.
67+
68+
Materializers validate staged bundles without copying contract logic:
69+
70+
```text
71+
python3 scripts/validate_provider_input_contract.py \
72+
--schema-dir <released-patterns>/integrations/isolation/schemas \
73+
--credential-bindings <released-patterns>/integrations/isolation/schemas/provider-credential-bindings.json \
74+
--bundle <staged-provider-1>/provider-input.json \
75+
--bundle <staged-provider-2>/provider-input.json
76+
```
77+
78+
**CLI invocation rules:**
79+
80+
- **Repeated `--bundle` flags in ONE invocation** perform set-wide duplicate-provider checking across all candidates. Each distinct `--bundle` invocation with a single flag resets the uniqueness set, so pass every candidate as repeated `--bundle` flags in a single command to catch duplicates.
81+
- **Zero `--bundle` flags** select repository discovery and validate the shipped fixture and canonical kit bundles. This is discovery mode, not validation of an empty external provider set; see Consumer Requirements.
82+
83+
`--schema-dir` and `--credential-bindings` are trusted control-plane inputs.
84+
They MUST come from the pinned Patterns release and backend-owned credential
85+
configuration, never from bundle contents or provider-controlled metadata. A
86+
provider controls only the staged manifest path(s) passed with `--bundle`.
87+
88+
## Consumer Requirements
89+
90+
- Treat an absent required `ACQ_PROVIDER_INPUT_ROOT` or provider directory as
91+
**not ready**, never as an empty provider set.
92+
- Treat a present authoritative root with zero provider directories as a valid,
93+
authoritative empty provider set.
94+
- Treat a rejected bundle as a provisioning failure. Build an empty aggregate
95+
only after successful authoritative discovery confirms zero providers.
96+
- Read provider routing and credential-name facts only from the backend's
97+
read-only provider directory.
98+
- Do not place credential values in the bundle, mount, aggregate catalog, or
99+
consumer configuration.
100+
101+
See ADR 0004 for the trust boundary, validation rules, and rationale.

‎integrations/isolation/schemas/acq-provider-facts.schema.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
"$schema": "https://json-schema.org/draft/2020-12/schema",
33
"$id": "acq-provider-facts/v1",
44
"title": "ACQ Provider Facts",
5-
"description": "Host-materialised, read-only self-registration record for a provider kit. Validated by acq host-side before the sandbox is created; the resulting directory is mounted read-only at /var/lib/acq/host/models/providers/<providerId>/. See integrations/isolation/docs/decisions/0004-neutral-model-provider-discovery.md §Layer 1.",
5+
"description": "Host-materialised, read-only self-registration record for a provider kit. With legacy bundle v1, the resulting directory is mounted at /var/lib/acq/host/models/providers/<providerId>/. With bundle v2, it is at the validated provider-relative path models/providers/<providerId> beneath the backend-supplied root. The backend materializer owns root injection, read-only mounting, and materialized-directory identity checks. See integrations/isolation/docs/decisions/0004-neutral-model-provider-discovery.md §Layer 1.",
66
"type": "object",
77
"additionalProperties": false,
88
"required": [
@@ -25,7 +25,7 @@
2525
"minLength": 1,
2626
"maxLength": 32,
2727
"pattern": "^[a-z0-9]([a-z0-9-]{0,30}[a-z0-9])?(?![\\s\\S])",
28-
"description": "Stable, lowercase slug used as a filesystem path segment under /var/lib/acq/host/models/providers/<providerId>/. Allowed: lowercase ASCII alphanumerics and internal hyphens, 1-32 characters total. Disallowed: path separators, dots, underscores, uppercase, non-ASCII, leading/trailing hyphens, whitespace, and control characters. The pattern ends with (?![\\s\\S]) — a zero-width assertion that matches only at the true end of the string — rather than $ because JSON Schema (ECMA regex) and Python re both allow $ to match before a trailing newline, which would permit 'usai\\n' as a path segment. The (?![\\s\\S]) lookahead has no such exception and enforces fullmatch semantics portably."
28+
"description": "Stable, lowercase slug used as the final materialized provider directory. Bundle v1 uses the legacy fixed root; bundle v2 uses a backend-supplied root plus models/providers/<providerId>. The backend materializer enforces that the materialized directory name equals this value. Allowed: lowercase ASCII alphanumerics and internal hyphens, 1-32 characters total. Disallowed: path separators, dots, underscores, uppercase, non-ASCII, leading/trailing hyphens, whitespace, and control characters. The pattern ends with (?![\\s\\S]) — a zero-width assertion that matches only at the true end of the string — rather than $ because JSON Schema (ECMA regex) and Python re both allow $ to match before a trailing newline, which would permit 'usai\\n' as a path segment. The (?![\\s\\S]) lookahead has no such exception and enforces fullmatch semantics portably."
2929
},
3030
"apiProtocol": {
3131
"type": "string",
Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
{
2+
"$schema": "https://json-schema.org/draft/2020-12/schema",
3+
"$id": "acq-provider-input-bundle/v2",
4+
"title": "ACQ Provider Input Bundle v2",
5+
"description": "Host-time manifest for a provider kit. Version 2 fixes the provider-relative layout while the backend supplies the authoritative read-only guest root. Every materializer MUST invoke scripts/validate_provider_input_contract.py; JSON Schema cannot enforce cross-field, file, symlink, or executable invariants.",
6+
"type": "object",
7+
"additionalProperties": false,
8+
"required": ["schemaVersion", "providerId", "factsPath", "normalizerPath", "snapshotPath", "providerPath", "credentialEnvNames"],
9+
"properties": {
10+
"schemaVersion": {"const": "acq-provider-input-bundle/v2"},
11+
"providerId": {"type": "string", "pattern": "^[a-z0-9]([a-z0-9-]{0,30}[a-z0-9])?(?![\\s\\S])"},
12+
"factsPath": {"type": "string", "minLength": 1, "maxLength": 256, "pattern": "^(?!/)(?!.*\\\\)(?!.*(?:^|/)\\.{1,2}(?:/|$))[A-Za-z0-9][A-Za-z0-9._/-]*(?![\\s\\S])"},
13+
"normalizerPath": {"type": "string", "minLength": 1, "maxLength": 256, "pattern": "^(?!/)(?!.*\\\\)(?!.*(?:^|/)\\.{1,2}(?:/|$))[A-Za-z0-9][A-Za-z0-9._/-]*(?![\\s\\S])"},
14+
"snapshotPath": {"type": "string", "minLength": 1, "maxLength": 256, "pattern": "^(?!/)(?!.*\\\\)(?!.*(?:^|/)\\.{1,2}(?:/|$))[A-Za-z0-9][A-Za-z0-9._/-]*(?![\\s\\S])"},
15+
"providerPath": {"type": "string", "pattern": "^models/providers/[a-z0-9]([a-z0-9-]{0,30}[a-z0-9])?(?![\\s\\S])"},
16+
"credentialEnvNames": {"type": "array", "minItems": 1, "uniqueItems": true, "items": {"type": "string", "pattern": "^[A-Z][A-Z0-9_]*(?![\\s\\S])"}}
17+
}
18+
}

0 commit comments

Comments
 (0)