sdg: IP 0001 — foundational machine surfaces for an external spec UI

.github/workflows/ci.yml

@@ -27,8 +27,16 @@ name: CI
 
 on:
   pull_request:
+  # GitHub creates no pull_request-event runs while a PR is unmergeable.
+  # PR #7 (patch 0001, branch claude/xspec-ui-apis-4df8fa, standing in for
+  # patch/external-ui-apis) is conflicted with main (specs/PHILOSOPHY.md), so
+  # its CI signal comes from push-event runs on the branch head instead —
+  # same workflow, same tree; checks attach to the head commit and surface on
+  # the PR. Drop that branch from this list once its PR is mergeable again or
+  # the patch completes. (Same channel sdg/initial-build used, kept for
+  # history.)
   push:
-    branches: [main, sdg/initial-build]
+    branches: [main, sdg/initial-build, claude/xspec-ui-apis-4df8fa]
   workflow_dispatch:
 
 concurrency:

AGENTS.md

@@ -5,15 +5,15 @@ Build, test, and run instructions for this repository (nothing else belongs in t
 - Requires Node.js >= 22 and npm. Install dependencies: `npm ci`.
 - One npm package (`xspec`) holding two distinct programs: the product under `src/` and the test harness under `test/`. The harness never imports product code; it drives the built `xspec` executable as a subprocess.
 - Build the product: `npm run build` — compiles `src/` (TypeScript ESM, `src/tsconfig.json`) to `dist/`; the `xspec` bin is `dist/cli/bin.js`. Run it: `node dist/cli/bin.js`.
-- The built product enables Node's on-disk V8 compile cache (`node:module` `enableCompileCache`; default directory under the OS temp dir, e.g. `/tmp/node-compile-cache`). The first invocations after `npm run build` repopulate it, so one-off CLI timings are slower than steady state; the cache affects timing only, never output.
+- The built product enables Node's on-disk V8 compile cache (`node:module` `enableCompileCache`; default directory under the OS temp dir, e.g. `/tmp/node-compile-cache`). The first invocations after `npm run build` repopulate it, so one-off CLI timings are slower than steady state; the cache affects timing only, never output. Steady-state per-invocation cost is ~0.26s for any command that parses the configuration (the TypeScript compiler module is loaded through `createRequire` in `src/core/ts-module.ts` — importing that CJS file through the ESM loader instead costs ~0.2s more per invocation in format sniffing and named-export lexing; keep any new `typescript` use routed through that module) and ~0.12s for the store-backed fast paths (`query` and `at` on a workspace whose `.xspec/graph.json` verifies against the current bytes) — the numbers that matter when a test sweeping many CLI invocations nears its timeout.
 - Typecheck both programs: `npm run typecheck` (`src/tsconfig.json`, then `test/tsconfig.json`; the harness is not typechecked by Vitest at run time). `test/fixtures/` is excluded from the harness typecheck: fixture projects are data compiled or executed at test run time and may contain deliberate type errors (e.g. the S-4 fixture).
 - Consumer fixture programs are compiled through the harness's TypeScript tooling driver (`test/helpers/tooling.ts`), which resolves `@types/node` from this repository's own `node_modules` — `npm ci` (dev dependencies included) must have run for consumer compilation to work.
 - Full test suite (TEST-SPEC sections 1–17, certification included; the Linux CI leg): `npm test`. Build the product first — tests invoke the built executable.
 - Run a subset of a test project by appending file paths, e.g. `npx vitest run --config test/vitest.config.ts --project suite test/suite/section-1.1-1.2.test.ts` — the way to observe new product-facing tests failing-as-diagnosed against the stub product (Phase 9 red-green).
 - Running tests also requires the system `git` executable on PATH: harness fixtures script local git repositories (`test/helpers/workspace.ts`). No git configuration is needed — the builder isolates all ambient git config and identity.
 - Harness self-tests and certification only (TEST-SPEC 17): `npm run test:self`.
 - Certification fixture products (CERTIFICATIONS.md, e.g. `test/fixtures/conf-core/`) are plain Node ESM programs with no build step and no dependencies: the certification runner (and manual debugging) invokes `node test/fixtures/<fixture>/bin.mjs <command> …` with a staged workspace as the working directory. Violator executables sit beside the conformer's entry as `bin-<deviation>.mjs` (e.g. `bin-nolock.mjs`) and run the same way. `test/fixtures/` is excluded from the harness typecheck; Prettier still formats it.
-- Windows-leg subset (TEST-SPEC E-6; run by the Windows CI job): `npm run test:windows`. Build the product first. Its byte-identity test compares this leg's representative-fixture outputs against the Linux leg's, read from the directory named by `XSPEC_E6_EXCHANGE_DIR`; the Linux outputs are written by the suite project's E-6 writer test (`test/suite/e6-exchange-writer.test.ts`) whenever that variable is set during `npm test`, and CI exchanges them as the `e6-linux-outputs` artifact (`.github/workflows/ci.yml`). Against the stub product the whole subset is red (diagnosed failures) before any exchange is consulted; once the product conforms, run the Linux suite with the variable set, then the Windows subset with the same variable — with the variable unset or the directory absent, the byte-identity test fails loudly by design (never skips).
+- Windows-leg subset (TEST-SPEC E-6; run by the Windows CI job): `npm run test:windows`. Build the product first. Its byte-identity test compares this leg's representative-fixture outputs against the Linux leg's, read from the directory named by `XSPEC_E6_EXCHANGE_DIR`; the Linux outputs are written by the suite project's E-6 writer test (`test/suite/e6-exchange-writer.test.ts`) whenever that variable is set during `npm test`, and CI exchanges them as the `e6-linux-outputs` artifact (`.github/workflows/ci.yml`). Against the stub product the whole subset is red (diagnosed failures) before any exchange is consulted; once the product conforms, run the Linux suite with the variable set, then the Windows subset with the same variable — with the variable unset or the directory absent, the byte-identity test fails loudly by design (never skips). The T11.6-1 drive-mismatch test (`test/windows/e6-drive-mismatch.test.ts`) additionally stages a substituted drive mapping (`subst`), which exists only on Windows: on any other platform it fails loudly after its same-drive premise arm (never skips), so a fully green `npm run test:windows` needs an actual Windows machine.
 - Local-only suite (TEST-SPEC E-2; separately invocable, never run in CI, currently empty): `npm run test:local`.
 - Property tests (TEST-SPEC 16; machinery in `test/helpers/property.ts`) run a fixed seed set by default — the CI mode, fully deterministic. To rerun with a specific seed: `XSPEC_PROPERTY_SEED=<uint32 from the failure message>`. Optional randomized local mode: `XSPEC_PROPERTY_SEED=random` (each property reports its seed for replay). Never set the variable in CI. Vitest intercepts the seed reports (`console.info`); add `--disable-console-intercept` to the vitest invocation to see them — but place any test-file filter argument *before* that flag (a file path following `--disable-console-intercept` is not treated as a filter and the whole project runs).
 - Format code (Prettier, default config, `src/` and `test/` only): `npm run format`; verify: `npm run format:check`.