design(executable-suites): published suites on Cloudflare Worker Loaders - #6
Conversation
Design doc for the founder ruling that api.qa MUST execute service-published vitest-style suites via the dynamic Worker Loader binding: the A.8.5 amendment (axp-exec@1 runner dialect, npm integrity pinning, the replay/attestation basis that replaces the "never code" prohibition), the sandbox security model (brokered egress re-applying the existing gates), and a phased S/M implementation scope. No production code changes. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
… jest/vitest compat Refine the axp-exec@1 harness layer so the test API (describe/it/test/expect and the four hooks) is injected as GLOBALS by default (vitest globals:true / Jest default), with `import ... from 'vitest'` still resolving to the same api.qa-owned implementation for the import style. Goal: "publish the tests you already have" — an existing Jest or vitest suite ports with zero/near-zero changes. - §2/§3: globals-by-default decision + opt-out (`export const globals = false`, read from the pinned bytes before evaluation); example uses the globals form, import form noted as identical. - §3: new Jest/vitest compatibility subsection documenting the in-scope surface (structure/hooks, expect core matchers with .not, resolves/rejects, feasible expect.* asymmetric helpers) vs out-of-scope (no snapshots, no vi/jest module mocking, no fake timers, no expect.extend) — enforced by a fail-with-symbol stub, never a silent pass. - §5.3: confirm the globals path routes through the same parent-computed verdict — globals and the import export are one instance, both emit typed assertion events to REPORTER; no globals-only escape hatch returns a verdict. - §4/§9: entry installs globals before importing the suite; Phase 1 scope updated. Migration section: adoption win — a property's existing vitest suite becomes the published executable suite with little/no change and still runs under real vitest locally. Runner dialect, integrity pinning, replay/attestation, and sandbox-security sections unchanged — ergonomics refinement to the harness layer only. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a18d84ced6
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| resolve artifact (inline / stored / npm / same-origin URL) | ||
| │ verify integrity + digest — refuse before anything executes | ||
| ▼ | ||
| env.SUITE_LOADER.get(`exec:${suiteDigest}:${HARNESS_VERSION}`, () => ({ |
There was a problem hiding this comment.
When the same suite digest runs more than once, get() reuses the worker keyed only by the suite and harness versions, but the cached WorkerCode embeds run-specific reporter and gateway stubs containing runId, origin, methods, and budget. The loader callback will not rebuild those bindings on a cache hit, so later runs can report into the first run and use its egress policy; the module-scoped suite state is also retained because ESM evaluation is not repeated. Use one-shot load(), make the identity cover the complete configuration, or pass run-specific state through a stable dispatcher rather than cached bindings.
Useful? React with 👍 / 👎.
| | Publicly-routable target | `isPubliclyRoutableSameOrigin` | same function, same refusal set (private ranges, metadata IPs, etc.) | | ||
| | Target-origin pinning | resolved URLs re-gated same-origin | every brokered request must be same-origin with the card; off-origin → gateway throws, run fails with the URL named | |
There was a problem hiding this comment.
When an allowed same-origin endpoint returns a redirect to an off-origin or private address, the gateway's own native fetch will follow it without another child request passing through globalOutbound, so checking only each request delivered to the gateway does not enforce this origin guarantee. The existing observer explicitly uses redirect: 'manual' and validates every hop in src/http.ts; the executable gateway needs the same behavior and a redirect-specific integration test, otherwise a publisher-controlled 302 can bypass the SSRF boundary.
Useful? React with 👍 / 👎.
| **Phase 4 — the card path (M).** `discovery.ts` `TestSuiteClaim` learns | ||
| `runner`/`npm`/`methods`; `test-suite.ts` gate widens: `gateTestSuiteCard` | ||
| accepts the new runner (Form A same-origin URL reuses the existing | ||
| fetch+digest gates byte-for-byte), a new `gateExecSuiteModule` replaces | ||
| `gateTestSuiteDocument` for the exec branch; `checks.ts` | ||
| `published-test-suite` runs the exec path and judges from the recorded |
There was a problem hiding this comment.
When a property follows the recommended dual-publication posture and puts the executable declaration in interfaces.testSuite.suites, this phase only teaches TestSuiteClaim about runner, npm, and methods and retains a singular card dispatch. Consequently the current verifier described here would continue to run only the top-level declarative suite, contradicting the promise that it runs every nested entry. Add suites parsing, gating, execution, and tests to the card-path phase.
Useful? React with 👍 / 👎.
1 participant
Design memo: executable published test suites on Cloudflare Worker Loaders; harness defaults to injected globals with jest/vitest compat.
Single new file:
docs/2026-08-08-executable-suites-worker-loader.md. Docs-only.🤖 Generated with Claude Code