Skip to content

Tooling for gated plugins: catalog requires, certify v3, plugin-routes feature builds and lanes (#134) - #169

Merged
michielbdejong merged 10 commits into
mainfrom
claude/issue-134-gated-tooling
Sep 25, 2026
Merged

michielbdejong merged 10 commits into
mainfrom
claude/issue-134-gated-tooling

Conversation

@michielbdejong

Copy link
Copy Markdown
Contributor

Closes #134.

  • Manifest v3 http rules: a JS port (integrations/tooling/manifest-http.mjs), validated against atomic-server #1732's shared fixtures, which are copied byte for byte with their source SHA.

  • Catalog requires: a new ontology property. catalog-requires.mjs check|write derives each package's list from its manifest.

  • certify:

    • refuses a gated package whose entry is missing requires or has a wrong one;
    • records schemaVersion/requires;
    • builds the sandbox tests of gated packages with plugin-routes.

    Evidence for gated plugins stays "declared" until a report records a runtime level.

  • Lanes: lanes.json can declare pluginRoutes (one or more levels). server-build.mjs provides a <sha>-plugin-routes binary: ATOMIC_SERVER_ROUTES_BINARY in CI, otherwise a Docker image variant, otherwise a local build under a lock. serve.mjs starts it with --plugin-routes <level> --routes-origin …, and run-lane.mjs runs the live and e2e tiers once per level.

  • CI: a build-server-plugin-routes job runs only when a selected lane needs it. It pulls ghcr.io/ontola/atomic-server-e2e:<sha>-plugin-routes (a new variant in the image workflow and Dockerfile, using CARGO_FEATURES), and falls back to a source build.

  • The plugin-routes lane, with its own narrow path filter. The e2e with a gated fixture plugin checks:

    • at read-only: catalog requires/hostFeatures, pinning works, install through the review dialog, GET /_routes/<slug>/hello returns 200 with the handler's body, and other slugs or paths return 404;
    • at off: pinning is refused with 409 host-feature-unavailable, the review shows the refusal with Install disabled, and the earlier installation is degraded.

Tested: the lane passed at atomic-server candidates 2, 5 and 9 (74ae9931f). Lint and format are clean, and the tooling tests pass.

Known host gap: at off, /_routes/… falls through to the data-browser HTML (200) instead of 404, as design §0.4 expects. The spec accepts either, with a TODO.

Overlap with #158 (Codex CI node lanes): a trial merge has only two-sided additions to the tooling test list in ci.yml and the end of lanes.test.mjs, resolved by keeping both. There's no competing tier. serve.mjs loads server-build.mjs lazily, so #158's runner test keeps working.

🤖 Generated with Claude Code

Michiel de Jong and others added 10 commits September 25, 2026 08:49
…xtures

integrations/tooling/manifest-http.mjs is a JS port of atomic-server's
browser/lib/src/plugin-manifest-http.ts (ontola/atomic-server#1732): http
block validation, the plugin-routes gate, the derived `requires`, and the
host-feature-unavailable refusal and its message. Ported rather than
imported, because the tooling must run against pins older than #1732.

fixtures/plugin-manifest/ holds byte-for-byte copies of the host's
http-index.json, http-refusals.json and the manifests they name, from
bcf8199927 (source.json), excluded from oxfmt so a refresh stays a copy.
All 52 fixture cases pass.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ated plugins

- catalog.json's ontology gets `requires` (JSON array), the list the host
  derives from a manifest and puts on /plugin-catalog entries
  (atomic-server#1732), e.g. ["persistent-host", "plugin-routes:read-only",
  "public-origin", "wasm-sandbox"].
- catalog-requires.mjs reads the manifest each integrations/*/plugin.js
  exports and checks (or `write`s) that entry: a version-3 or gated
  package's entry must carry exactly the derived list; any other entry that
  carries one must match too. No package here is v3 yet, so no entry
  changes.
- certify.mjs refuses a gated package without it, records `schemaVersion`
  and `requires` per report item, and runs a gated package's sandbox tests
  with `light,wasm-plugins,plugin-routes`, recording the feature.
- evidence.mjs gives a gated item no evidence unless the report records a
  plugin-routes build running at the level its manifest needs. certify
  records no level (cargo tests are not a running server), so a gated
  plugin's capabilities stay "declared" until a live runner records one.
- fixtures/gated-plugin/plugin.js: the smallest gated plugin (v3, one
  anonymous GET route), used by these tests and the e2e lane that follows.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ime level

lanes.json gains two optional lane fields:

- `pluginRoutes`: a `--plugin-routes` level, or a list of them. The lane's
  live and e2e tiers then run on atomic-server built with
  `--features wasm-plugins,plugin-routes`, once per level on a fresh
  server started with `--plugin-routes <level> --routes-origin
  http://routes.localhost:<port>` (a *.localhost origin, which
  atomic-server#1726 accepts next to a localhost API). Tests get
  PLUGIN_ROUTES_LEVEL and PLUGIN_ROUTES_ORIGIN. Lanes without it are
  unchanged.
- `dir`: a tooling lane owns integrations/tooling (or a directory under
  it) instead of integrations/<id>.

server-build.mjs finds that build: ATOMIC_SERVER_ROUTES_BINARY (CI), else
~/.cache/atomic-plugins/atomic-server/<sha>-plugin-routes, built there on
first use from ~/gh/ontola/atomic-server under a `<dir>.lock` mkdir lock
(pid + host, stale locks removed). There was no build-lock convention
before; this defines one. serve.mjs never runs the published image for
such a lane (it is the default build) and strips inherited
ATOMIC_PLUGIN_ROUTES / ATOMIC_ROUTES_ORIGIN / ATOMIC_PLUGIN_LISTENERS /
ATOMIC_PLUGIN_SIDECARS, which a default build refuses to start with.

ci.yml: `changes` reports whether the matrix has such a lane; a new
build-server-plugin-routes job builds the feature binary only then (from
source; the e2e image stays the default build), and those lane jobs
download it. build-server itself is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… plugin

Lane `plugin-routes` (index 8, dir integrations/tooling, no mock proxy)
runs integrations/tooling/e2e/plugin-routes.spec.ts at `--plugin-routes
off` and `read-only` on the plugin-routes feature build. The spec
publishes fixtures/gated-plugin (v3, one anonymous GET route) and checks:

- publishing to the node's marketplace is not gated;
- /plugin-catalog's hostFeatures.pluginRoutes (compiled, level, routes
  origin) and the entry's derived `requires`;
- /plugin-release-pin answers 409 host-feature-unavailable with the
  design 0.4 message at `off`, and pins the release at `read-only`.

It requests no route (no host serves them yet, AS-04/AS-05), and it does
not drive an Installation commit or the install review UI. Needs a pin
with atomic-server#1726 and #1732.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…uild

integrations/README.md: the derived `requires` on catalog cards and the
catalog-requires.mjs commands; what certification does for a gated
package, and why its capabilities stay "declared" until live evidence at
the needed level exists. PARALLEL_LANES.md: the `pluginRoutes` and `dir`
lane fields. AGENTS.md: where the plugin-routes feature build lives and
its build lock.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A tooling lane (`dir`) must now list its `paths`, and those are its whole
filter: files under integrations/tooling/, .atomic-server-ref and shared
packages. The `shared` filter no longer selects it, so an unrelated
tooling edit doesn't pay for the plugin-routes feature build. The
`plugin-routes` lane names its spec, fixtures, manifest-http.mjs,
catalog-requires.mjs, server-build.mjs, serve.mjs, run-lane.mjs and the
pin. Merge-queue and manual runs pass `all` besides `shared`, which still
selects every lane. The lane's node tests stay in shared-checks.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The Dockerfile takes CARGO_FEATURES (default `wasm-plugins`, so :<sha> is
unchanged) and records it in the dev.atomicdata.atomic-server.features
label. atomic-server-e2e-image.yml builds a second variant,
ghcr.io/ontola/atomic-server-e2e:<sha>-plugin-routes, with
`wasm-plugins,plugin-routes`, for any SHA whose server/Cargo.toml has the
feature (atomic-server#1726 on). Each variant is decided, built and tagged
on its own; :latest-pin still names the default one.

build-server-plugin-routes now pulls that image first, checks its sha and
features labels and that the binary runs, and falls back to the source
build otherwise, like build-server. workflow.test.mjs checks both the
variant's recipe and the pull-before-build order.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… fallback

For a lane that declares `pluginRoutes`, serve.mjs now runs
ghcr.io/ontola/atomic-server-e2e:<sha>-plugin-routes in Docker whenever
ATOMIC_SERVER_IMAGE is set (its tag's variant; `latest-pin` maps to the
pinned SHA's), or ATOMIC_SERVER_ROUTES_IMAGE names one. `--plugin-routes`
and `--routes-origin` go to the container as arguments to atomic-server.
If the image can't be pulled, or its features label lacks plugin-routes,
it warns and falls back to the local <sha>-plugin-routes source build.
ATOMIC_SERVER_ROUTES_BINARY (CI) still wins over both. So a Mac running
the lanes from the published images needs no ~10 GB feature build.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…s route

Against the route registry and execution (atomic-server#1749, #1751):

- fixtures/gated-plugin mounts its `GET /hello` on drive-prefix and
  answers "Hello from the gated fixture" from `handle`, shaped like the
  host's testdata/plugin-routes/hello-route.
- The lane runs read-only first, then off, over the same store. At
  read-only the spec pins, installs through the store's review dialog and
  gets the body from /_routes/<slug>/hello (slug: blake3 of the
  Installation subject, via @tomic/lib's @noble/hashes); another slug or
  an undeclared path is a 404. At off: pin refused (typed problem), the
  review shows the refusal with Install disabled, and the read-only run's
  installation, now degraded, no longer runs its handler.
- At off the host doesn't mount /_routes/ at all, so that URL falls
  through to the data browser (200, HTML) rather than the 404 design 0.4
  describes; the spec accepts either and says so.
- The fixture's source gets a per-run comment: the same release id,
  published by an earlier run's agent on a reused store, can't be read by
  the new agent and the install commit fails with a 401.
- serve.mjs loads server-build.mjs only for a plugin-routes lane, so
  copying serve.mjs without it (as #158's runner test does) still works.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
integrations/README.md no longer says #1726/#1732 are unpinned, and names
what the pinned build has. The spec's per-run release note says the 401 it
avoids is from pins before atomic-server#1755.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@michielbdejong
michielbdejong merged commit 1ffd7f0 into main Sep 25, 2026
26 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Tooling for gated plugins: catalog requires, certification, plugin-routes e2e build

1 participant