Skip to content

WO20: API-plane status audit + code-only completion (engine fix, wrangler types, package guards) - #30

Merged
ronaldtse merged 3 commits into
mainfrom
wo20-api-status
Nov 16, 2026
Merged

ronaldtse merged 3 commits into
mainfrom
wo20-api-status

Conversation

@ronaldtse

@ronaldtse ronaldtse commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

API-plane status audit + code-only completion (WO20, issue #238)

The issue names interscript/interscript-api — that repo is the legacy Ruby GraphQL Lambda (AWS), kept as the production rollback plane. The agreed architecture (code-only npm package, maps as deployment artifacts, no-regex engine, bundled maps surface, ml surface) lives in the Cloudflare plane: interscript/api (worker software, this PR) + interscript/api.interscript.org (deployment repo). This PR targets the software repo; the table audits the whole plane.

Status table (audit vs the agreed architecture)

Surface Status Notes
No-regex engine directive was broken → fixed here Engine = interscript-ts native async interpreter, no regex compilation. But CI on main has been red since the WO15 merge (2026-10-07), for two stacked reasons: the pinned engine ^4.0.0 has no plane module for src/ml.ts's createPlaneModel import, and vitest.config.ts aliased interscript/ml to a sibling ../interscript-ts checkout that does not exist on CI runners (tests could only ever pass on machines with the full monorepo sibling layout). Bumped to ^5.14.0 — the published package now ships interscript/ml — and removed the sibling alias, so CI resolves the real published engine. Parity suite stays byte-identical, 48/48 green.
Code-only npm package done (+ guards) Corpus never enters the tarball (existing guard); this PR adds a phantom-entry guard, a shipped-.d.ts import-closure guard, and a manifest entry-point guard. unpackedSize < 1 MB holds.
Maps as deployment artifacts done ASSETS-binding loader; deployment repos fetch a pinned, sha256-verified interscript/maps release artifact; maps/ in this repo is for tests/build-time metadata only and the guards keep it out of npm.
Bundled maps surface done GraphQL systemCodes, /v1/maps, /v1/maps/{code}; 297 asset files validated by the (now strict) wrangler deploy --dry-run smoke.
ML surface done; snapshot refresh owner-held /v1/models + /v1/infer (Modal proxy) + in-worker plane execution with the 100 MB workerd budget (WO15). The src/generated/models.json snapshot (index v5, 23 models) refresh against the current models.yaml is a release-round action — not done here.
Worker code done GraphQL (production camelCase schema, legacy raw-GraphQL-body compatibility), REST v1 + OpenAPI 3.1 + docs page, limits/errors, e2e script (49 checks), parity fixtures recorded from the production Ruby API with zero-diff CI gate.
Wrangler config with generated types missing → completed here The software repo had no wrangler config at all. Added the canonical self-deploy wrangler.jsonc (no routes, no secrets) and the generated worker-configuration.d.ts (committed, npm run gen:types, CI freshness gate via git diff --exit-code). @cloudflare/workers-types is superseded by the generated runtime types.
package.json exports/files hygiene completed here ./package.json export added; guards now fail CI on any manifest/tarball drift, and a new guard asserts the published bundle never absorbs the node ONNX backend's native binaries. CI also builds before vitest (the package guards need dist/), and the bundle smoke no longer swallows failures (|| true removed). Bundle-smoke fix (commit 3): once onnxruntime-node entered devDependencies, wrangler's esbuild resolved the engine's dynamic backend probe and choked on the five platform onnxruntime_binding.node binaries — wrangler.jsonc now carries an alias (esbuild's alias, wrangler's canonical knob) redirecting onnxruntime-node to stubs/onnxruntime-node.js, which throws on evaluation; the plane session's backend probe catches it and selects a worker-compatible backend (the node backend is unreachable in workerd by construction). The npm build marks it explicitly --external, and the README documents the remedy for self-hosters.
Deployment (routes, secrets, DNS, wrangler deploy) owner-held — not run Commands recorded below. Nothing was deployed.

Deploy commands (recorded, NOT run)

# staging — CI does this on push to main of interscript/api.interscript.org:
#   npm run deploy:staging   (wrangler --config wrangler.staging.jsonc, workers.dev preview)
# production — CI does this on a v* tag there (environment: production):
#   npm run deploy
# manual equivalents, from a checkout of interscript/api.interscript.org:
npm install
npx wrangler deploy --config wrangler.staging.jsonc   # staging
npx wrangler deploy                                    # production
npx wrangler secret put ML_TOKEN                       # if (re)setting the inference key
# verify after any deploy:
E2E_BASE_URL=https://interscript-api-staging.interscript.workers.dev node scripts/e2e.mjs
node scripts/e2e.mjs                                   # production

Secrets (CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID) are already installed as deployment-repo secrets; the deployment repo pins this package — after this PR merges, bump that pin to pick up the engine fix.

Legacy plane

interscript/interscript-api (Ruby Lambda): unchanged, still the documented rollback path; no code changes required for this round.

Verification

  • npm run typecheck, npm run lint, npm run format:check — clean
  • npx vitest run — 48/48 against the published 5.14.0 engine with no sibling checkouts involved (commit 2: drops the vitest.config.ts alias to ../interscript-ts and adds onnxruntime-node as a devDependency for the plane decode tests — the exact condition CI runs under)
  • npm run build + strict npx wrangler deploy --dry-run — green (162 KB bundle, 297 assets)

…es, package guards

CI on main has been red since the WO15 merge: src/ml.ts imports
createPlaneModel from "interscript/ml", but the pinned engine (^4.0.0)
has no plane module. Bump the engine to ^5.14.0 — the parity suite
still gates byte-identical behavior, 48/48 green.

Also the code-only plane-completion round:

- wrangler.jsonc: canonical self-deploy config in-repo (no routes, no
  secrets), and the generated worker-configuration.d.ts committed with
  a CI freshness gate (npm run gen:types + git diff --exit-code);
  @cloudflare/workers-types superseded by the generated runtime types
- ci.yml: build before vitest (package.test guards the packed
  tarball), generated-types check, and the wrangler dry-run smoke is
  strict (no more `|| true`)
- test/package.test.ts: phantom-file guard (every files entry ships),
  shipped-.d.ts import-closure guard, manifest entry-point guard
- package.json: ./package.json in exports
- prettier: src/ml.ts, src/rest.ts, test/ml.test.ts (drift since WO15)
- dist/: regenerated from current src (the committed tree had drifted)
…ngine

The vitest config aliased interscript/ml to a sibling ../interscript-ts
checkout, so the ml suite could only pass on machines with the full
monorepo layout - CI has been unable to resolve the import since the
WO15 merge (the committed engine pin had no plane module either; fixed
in the parent commit by the ^5.14.0 bump).

With the published 5.14.0 shipping interscript/ml, tests now resolve
the real package. The plane session's node backend needs
onnxruntime-node in the test environment - added as a devDependency
(the Worker bundle never selects the node backend; build + dry-run
remain green). 48/48 locally against the published engine, no sibling
checkouts involved.
…erses the native binary

CI's bundle smoke (wrangler deploy --dry-run) fails with 'No loader is
configured for .node files': once onnxruntime-node entered devDependencies,
it became resolvable, and wrangler's esbuild expands interscript's dynamic
backend probe across all five platform onnxruntime_binding.node binaries.

Fix: wrangler.jsonc 'alias' (esbuild's alias) redirects the specifier to
stubs/onnxruntime-node.js, which throws on evaluation — the plane session's
backend probe catches it and selects a worker-compatible backend (the node
backend is unreachable in workerd by construction). The npm build also
marks onnxruntime-node explicitly external, the package ships the stub, a
package guard asserts the bundle never contains the native binary
references, and the README documents the remedy for self-hosters.
@ronaldtse
ronaldtse merged commit 5b077ae into main Nov 16, 2026
7 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.

1 participant