refactor(layout): move sdk/ and surface/ under packages/

[kjgbot]

Consolidates onto the layout relay and relayfile use, so all three publishable packages sit together:

packages/sdk
packages/surface
packages/runtime-linux-x64

Scope was much smaller than it looked

The headline is 138 files and ~1557 references. Only 19 needed changing. The rest live in ops/reviews/*, ops/DRIVE-LOG.md, ops/AUTODRIVE_BRIEF*.md, ops/BACKLOG.md and past run reports — records of what was true when they were written. Rewriting those would falsify history to match a layout that did not exist yet, so they still say sdk/.

One consequence worth knowing: ops/BACKLOG.md is read by a live test (packages/sdk/tests/backlog-picker.test.ts). The fix there is the path in the test, not the document.

The subtle half: path arithmetic

Inside the moved trees, tests reached the repo root with two levels of .., which now lands at packages/. Every repo-root climb is now three levels. Package-relative single-.. uses are unchanged and must stay that way — RELAYFLOWS_SDK_DIST, join(__dirname,'..','dist').

I got this wrong twice while doing it, and the suite caught both:

• The first sweep fixed only testdata climbs and missed ops/.
• A more general second sweep then over-corrected testdata to four levels — a regex that matched its own previous output.

Hashed fixtures, deliberately reverted

testdata/tick-heartbeat.* and hello-ladder.* are pinned by a sha256 shared across the SDK/kernel spec-parity boundary. Rewriting a comment inside them broke spec parity: hashes tick-heartbeat to the pinned spec_hash. They are reverted, so their prose still names the old paths. Correcting that means regenerating the pinned hash on both sides — a separate change, not a drive-by.

Verification

Both suites, run in the moved layout:

kernel:  cargo test --workspace       165 passed, 0 failed
sdk:     vitest run                   662 passed | 3 skipped | 0 failed

The sdk run includes the real-analyzer gate-2 case and the daemon-kill resume case, both of which exercise repo-root paths — which is what makes them worth having here rather than a typecheck.

Status

Khaliq asked for codex to implement this. Codex was handed the branch with a brief covering the four traps above, and hit a usage limit before starting (try again at Sep 7th 4:39 AM). This PR exists so the verified work is reviewable rather than stranded on a branch; the release pipeline that was the second half of that brief is not in here and remains open.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FtQSAcGDta5VH9xiZFT4sR

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Team

Run ID: 2fd5a037-1d32-46a4-a07d-3cdde3391028

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cubic-dev-ai]

3 issues found across 123 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name=".github/workflows/cloud-runtime-artifact.yml">

<violation number="1" location=".github/workflows/cloud-runtime-artifact.yml:147">
P1: The layout move to packages/ leaves this workflow broken: the steps still set `working-directory: sdk` and `working-directory: surface` (and `npm ci --prefix sdk`), but those directories no longer exist at the repo root after sdk/ and surface/ moved under packages/, so GitHub Actions fails those steps and the whole job aborts before producing the artifact. Update them to `working-directory: packages/sdk`, `working-directory: packages/surface`, `npm ci --prefix packages/sdk`, and change the preflight guard's `../testdata/preflight` to `../../testdata/preflight`.</violation>
</file>

<file name="packages/sdk/tests/live-kernel.test.ts">

<violation number="1" location="packages/sdk/tests/live-kernel.test.ts:28">
P3: The move of the SDK to packages/sdk makes the build hint at line 70 stale. `requireExecutable(BUILT_CLI, ..., '(cd sdk && npm run build)')` now tells the user to cd into a directory that no longer exists, so following the hint fails. Update it to '(cd packages/sdk && npm run build)'.</violation>
</file>

<file name="workflows/drive.yaml">

<violation number="1" location="workflows/drive.yaml:394">
P1: After the package test builds `packages/sdk/dist/index.js`, NEXT validation still requires the removed `./sdk/dist/index.js`. The load failure is swallowed, so invalid or unevidenced `ops/NEXT.md` content can pass verification; require the moved path and preserve module-load failures.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P1: After the package test builds packages/sdk/dist/index.js, NEXT validation still requires the removed ./sdk/dist/index.js. The load failure is swallowed, so invalid or unevidenced ops/NEXT.md content can pass verification; require the moved path and preserve module-load failures.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At workflows/drive.yaml, line 394:

<comment>After the package test builds `packages/sdk/dist/index.js`, NEXT validation still requires the removed `./sdk/dist/index.js`. The load failure is swallowed, so invalid or unevidenced `ops/NEXT.md` content can pass verification; require the moved path and preserve module-load failures.</comment>

<file context>
@@ -390,8 +390,8 @@ workflows:
-          # Runs BEFORE the node_modules cleanup below, which needs sdk/dist.
-          if [ -f ops/NEXT.md ] && [ -f sdk/dist/index.js ]; then
+          # Runs BEFORE the node_modules cleanup below, which needs packages/sdk/dist.
+          if [ -f ops/NEXT.md ] && [ -f packages/sdk/dist/index.js ]; then
             nextout=$(node -e '
               const fs = require("node:fs");
</file context>

[cubic-dev-ai]

P1: The layout move to packages/ leaves this workflow broken: the steps still set working-directory: sdk and working-directory: surface (and npm ci --prefix sdk), but those directories no longer exist at the repo root after sdk/ and surface/ moved under packages/, so GitHub Actions fails those steps and the whole job aborts before producing the artifact. Update them to working-directory: packages/sdk, working-directory: packages/surface, npm ci --prefix packages/sdk, and change the preflight guard's ../testdata/preflight to ../../testdata/preflight.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At .github/workflows/cloud-runtime-artifact.yml, line 147:

<comment>The layout move to packages/ leaves this workflow broken: the steps still set `working-directory: sdk` and `working-directory: surface` (and `npm ci --prefix sdk`), but those directories no longer exist at the repo root after sdk/ and surface/ moved under packages/, so GitHub Actions fails those steps and the whole job aborts before producing the artifact. Update them to `working-directory: packages/sdk`, `working-directory: packages/surface`, `npm ci --prefix packages/sdk`, and change the preflight guard's `../testdata/preflight` to `../../testdata/preflight`.</comment>

<file context>
@@ -144,7 +144,7 @@ jobs:
         run: |
           mkdir -p dist/cloud-artifact-input
-          bun build sdk/src/cli-executable.ts \
+          bun build packages/sdk/src/cli-executable.ts \
             --compile \
             --target=bun-linux-x64 \
</file context>

[cubic-dev-ai]

P3: The move of the SDK to packages/sdk makes the build hint at line 70 stale. requireExecutable(BUILT_CLI, ..., '(cd sdk && npm run build)') now tells the user to cd into a directory that no longer exists, so following the hint fails. Update it to '(cd packages/sdk && npm run build)'.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/sdk/tests/live-kernel.test.ts, line 28:

<comment>The move of the SDK to packages/sdk makes the build hint at line 70 stale. `requireExecutable(BUILT_CLI, ..., '(cd sdk && npm run build)')` now tells the user to cd into a directory that no longer exists, so following the hint fails. Update it to '(cd packages/sdk && npm run build)'.</comment>

<file context>
@@ -24,8 +24,8 @@ import { AgentWorker } from '../src/worker.js';
-const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
-const SDK = join(ROOT, 'sdk');
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+const SDK = join(ROOT, 'packages', 'sdk');
 const BUILT_CLI = join(SDK, 'dist', 'cli.js');
 const TESTDATA = join(ROOT, 'testdata');
</file context>

[cubic-dev-ai]

3 issues found across 9 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="workflows/drive.yaml">

<violation number="1" location="workflows/drive.yaml:355">
P0: The layout move left the materialization gate stale. Line 52 still requires a root-level `sdk` directory in the `for required in ... kernel sdk` check, but this PR moved it to `packages/sdk`, so `[ -e sdk ]` fails and the workflow exits 78 (SYNC_FAIL_NOT_MATERIALIZED) on every run — before any of the updated `packages/sdk` paths execute. Update the entry to `packages/sdk` so the check matches the new layout.</violation>
</file>

<file name="examples/research/tsconfig.json">

<violation number="1" location="examples/research/tsconfig.json:14">
P3: The `//` comment in this file still says to run from `cd sdk`, but this PR moved the SDK to `packages/sdk/`, so that command no longer works. Update the comment to `cd packages/sdk` so the documented typecheck invocation matches the new layout (it is the same stale-reference class the rest of this PR fixes).</violation>
</file>

<file name="scripts/surface-package-gate.sh">

<violation number="1" location="scripts/surface-package-gate.sh:9">
P2: The `cd "$repo_root/packages/surface"` breaks the gate's `bun run typecheck:regressions` step. That script runs `tsc -p ../regressions/tsconfig.json` (surface package.json `typecheck:regressions`), and `../regressions` is now resolved relative to `packages/surface`, i.e. `packages/regressions/tsconfig.json`, which does not exist. The tsconfig lives at `$repo_root/regressions/tsconfig.json`. Previously the cd was into `$repo_root/surface` so `../regressions` resolved correctly. Fix the typecheck:regressions path (e.g. `tsc -p ../../regressions/tsconfig.json` in packages/surface/package.json, or invoke tsc with `$repo_root/regressions/tsconfig.json` here) or the package gate fails at this step.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P0: The layout move left the materialization gate stale. Line 52 still requires a root-level sdk directory in the for required in ... kernel sdk check, but this PR moved it to packages/sdk, so [ -e sdk ] fails and the workflow exits 78 (SYNC_FAIL_NOT_MATERIALIZED) on every run — before any of the updated packages/sdk paths execute. Update the entry to packages/sdk so the check matches the new layout.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At workflows/drive.yaml, line 355:

<comment>The layout move left the materialization gate stale. Line 52 still requires a root-level `sdk` directory in the `for required in ... kernel sdk` check, but this PR moved it to `packages/sdk`, so `[ -e sdk ]` fails and the workflow exits 78 (SYNC_FAIL_NOT_MATERIALIZED) on every run — before any of the updated `packages/sdk` paths execute. Update the entry to `packages/sdk` so the check matches the new layout.</comment>

<file context>
@@ -352,7 +352,7 @@ workflows:
             if [ ! -d packages/sdk/node_modules ]; then
               echo "VERIFY_INSTALL: packages/sdk/node_modules absent — installing"
-              out=$(cd sdk && run_bounded "npm ci" npm ci 2>&1); rc=$?
+              out=$(cd packages/sdk && run_bounded "npm ci" npm ci 2>&1); rc=$?
               if [ $rc -ne 0 ]; then
                 echo "$out" | tail -12
</file context>

[cubic-dev-ai]

P2: The cd "$repo_root/packages/surface" breaks the gate's bun run typecheck:regressions step. That script runs tsc -p ../regressions/tsconfig.json (surface package.json typecheck:regressions), and ../regressions is now resolved relative to packages/surface, i.e. packages/regressions/tsconfig.json, which does not exist. The tsconfig lives at $repo_root/regressions/tsconfig.json. Previously the cd was into $repo_root/surface so ../regressions resolved correctly. Fix the typecheck:regressions path (e.g. tsc -p ../../regressions/tsconfig.json in packages/surface/package.json, or invoke tsc with $repo_root/regressions/tsconfig.json here) or the package gate fails at this step.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At scripts/surface-package-gate.sh, line 9:

<comment>The `cd "$repo_root/packages/surface"` breaks the gate's `bun run typecheck:regressions` step. That script runs `tsc -p ../regressions/tsconfig.json` (surface package.json `typecheck:regressions`), and `../regressions` is now resolved relative to `packages/surface`, i.e. `packages/regressions/tsconfig.json`, which does not exist. The tsconfig lives at `$repo_root/regressions/tsconfig.json`. Previously the cd was into `$repo_root/surface` so `../regressions` resolved correctly. Fix the typecheck:regressions path (e.g. `tsc -p ../../regressions/tsconfig.json` in packages/surface/package.json, or invoke tsc with `$repo_root/regressions/tsconfig.json` here) or the package gate fails at this step.</comment>

<file context>
@@ -6,15 +6,15 @@ pack_dir="$(mktemp -d /tmp/relayflows-surface-pack.XXXXXX)"
 trap 'rm -rf "$pack_dir" "$consumer_dir"' EXIT
 
-cd "$repo_root/surface"
+cd "$repo_root/packages/surface"
 bun install --frozen-lockfile --ignore-scripts
 bun run build
</file context>

[cubic-dev-ai]

P3: The // comment in this file still says to run from cd sdk, but this PR moved the SDK to packages/sdk/, so that command no longer works. Update the comment to cd packages/sdk so the documented typecheck invocation matches the new layout (it is the same stale-reference class the rest of this PR fixes).

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At examples/research/tsconfig.json, line 14:

<comment>The `//` comment in this file still says to run from `cd sdk`, but this PR moved the SDK to `packages/sdk/`, so that command no longer works. Update the comment to `cd packages/sdk` so the documented typecheck invocation matches the new layout (it is the same stale-reference class the rest of this PR fixes).</comment>

<file context>
@@ -11,7 +11,7 @@
     "skipLibCheck": true,
     "forceConsistentCasingInFileNames": true,
-    "typeRoots": ["../../sdk/node_modules/@types"],
+    "typeRoots": ["../../packages/sdk/node_modules/@types"],
     "types": ["node"]
   },
</file context>

[cubic-dev-ai]

1 existing issue remains and 2 new issues found across 3 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="testdata/backlog-picker.flow.yaml">

<violation number="1" location="testdata/backlog-picker.flow.yaml:13">
P1: After this change, `build-sdk` produces the SDK at `packages/sdk/dist`, but the `select-entry` and `emit-package` steps still resolve it by walking ancestors for `sdk/dist/backlog-picker.js`, which no longer exists. `RELAYFLOWS_SDK_DIST` is only set by the unit tests, so in real gate runs `select-entry`/`emit-package` throw `SDK_DIST_NOT_FOUND` even though the build succeeded. Update the resolution fallback in both steps to look for `packages/sdk/dist/backlog-picker.js` (and mirror the change in the canonical spec).</violation>

<violation number="2" location="testdata/backlog-picker.flow.yaml:13">
P1: This yaml change to `cd packages/sdk` diverges from the canonical spec. `testdata/backlog-picker.spec.canonical.json` still has `cd sdk && npm ci...` for `build-sdk`, and the `stays in sync with the flow yaml` test in `backlog-picker-flow.test.ts` asserts every canonical command equals the yaml command, so this change fails that test. Because the kernel executes the canonical spec, the real gate still runs `cd sdk`, which does not exist in the new layout and fails. Regenerate the canonical spec to match the yaml.</violation>
</file>

<sub>Requires human review: Auto-approval blocked because this review re-detected 1 unresolved issue already reported by Cubic.
Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

P1: After this change, build-sdk produces the SDK at packages/sdk/dist, but the select-entry and emit-package steps still resolve it by walking ancestors for sdk/dist/backlog-picker.js, which no longer exists. RELAYFLOWS_SDK_DIST is only set by the unit tests, so in real gate runs select-entry/emit-package throw SDK_DIST_NOT_FOUND even though the build succeeded. Update the resolution fallback in both steps to look for packages/sdk/dist/backlog-picker.js (and mirror the change in the canonical spec).

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At testdata/backlog-picker.flow.yaml, line 13:

<comment>After this change, `build-sdk` produces the SDK at `packages/sdk/dist`, but the `select-entry` and `emit-package` steps still resolve it by walking ancestors for `sdk/dist/backlog-picker.js`, which no longer exists. `RELAYFLOWS_SDK_DIST` is only set by the unit tests, so in real gate runs `select-entry`/`emit-package` throw `SDK_DIST_NOT_FOUND` even though the build succeeded. Update the resolution fallback in both steps to look for `packages/sdk/dist/backlog-picker.js` (and mirror the change in the canonical spec).</comment>

<file context>
@@ -10,7 +10,7 @@ steps:
     type: deterministic
     dependsOn: [read-backlog]
-    command: "cd sdk && npm ci --silent --no-audit --no-fund && npm run build --silent"
+    command: "cd packages/sdk && npm ci --silent --no-audit --no-fund && npm run build --silent"
   - id: select-entry
     type: deterministic
</file context>

[cubic-dev-ai]

P1: This yaml change to cd packages/sdk diverges from the canonical spec. testdata/backlog-picker.spec.canonical.json still has cd sdk && npm ci... for build-sdk, and the stays in sync with the flow yaml test in backlog-picker-flow.test.ts asserts every canonical command equals the yaml command, so this change fails that test. Because the kernel executes the canonical spec, the real gate still runs cd sdk, which does not exist in the new layout and fails. Regenerate the canonical spec to match the yaml.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At testdata/backlog-picker.flow.yaml, line 13:

<comment>This yaml change to `cd packages/sdk` diverges from the canonical spec. `testdata/backlog-picker.spec.canonical.json` still has `cd sdk && npm ci...` for `build-sdk`, and the `stays in sync with the flow yaml` test in `backlog-picker-flow.test.ts` asserts every canonical command equals the yaml command, so this change fails that test. Because the kernel executes the canonical spec, the real gate still runs `cd sdk`, which does not exist in the new layout and fails. Regenerate the canonical spec to match the yaml.</comment>

<file context>
@@ -10,7 +10,7 @@ steps:
     type: deterministic
     dependsOn: [read-backlog]
-    command: "cd sdk && npm ci --silent --no-audit --no-fund && npm run build --silent"
+    command: "cd packages/sdk && npm ci --silent --no-audit --no-fund && npm run build --silent"
   - id: select-entry
     type: deterministic
</file context>