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

.github/workflows/cloud-runtime-artifact.yml

@@ -20,7 +20,7 @@ on:
     paths:
       - ".github/workflows/cloud-runtime-artifact.yml"
       - "kernel/**"
-      - "sdk/**"
+      - "packages/sdk/**"
       - "scripts/cloud-artifact.mjs"
       - "scripts/cloud-artifact.test.mjs"
       - "testdata/**"
@@ -81,7 +81,7 @@ jobs:
         run: cargo test --workspace
 
       - name: Build authoring surface
-        working-directory: surface
+        working-directory: packages/surface
         run: |
           bun install --frozen-lockfile --ignore-scripts
           bun run build
@@ -90,10 +90,10 @@ jobs:
       # npm runs the file: dependency's prepare before its own devDependencies
       # exist. The SDK's own build is the next step, so nothing is skipped.
       - name: Install SDK dependencies
-        run: npm ci --prefix sdk --ignore-scripts
+        run: npm ci --prefix packages/sdk --ignore-scripts
 
       - name: Test SDK and type-level authoring contracts
-        working-directory: sdk
+        working-directory: packages/sdk
         env:
           # `live-kernel.test.ts` runs one case against the REAL Claude analyzer
           # and fails by default when it cannot, deliberately: an unavailable
@@ -128,7 +128,7 @@ jobs:
           # second, debug copy through a wrapper that cannot run here.
           #
           # The build is still required: several test files fail at collection
-          # without sdk/dist, which is why a bare `vitest run` is not enough.
+          # without packages/sdk/dist, which is why a bare `vitest run` is not enough.
           # test:prep's other half, kept: it re-asserts the executable bit on the
           # preflight CLI fixtures. They are committed 100755 so actions/checkout
           # already restores them, but the guard is one line and the failure it
@@ -144,7 +144,7 @@ jobs:
       - name: Build standalone flows CLI
         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 \
             --outfile=dist/cloud-artifact-input/flows

.github/workflows/surface-package.yml

@@ -6,18 +6,18 @@ on:
     paths:
       - ".github/workflows/surface-package.yml"
       - "scripts/surface-package-gate.sh"
-      - "surface/**"
+      - "packages/surface/**"
       - "regressions/**"
-      - "sdk/**"
+      - "packages/sdk/**"
   push:
     branches:
       - main
     paths:
       - ".github/workflows/surface-package.yml"
       - "scripts/surface-package-gate.sh"
-      - "surface/**"
+      - "packages/surface/**"
       - "regressions/**"
-      - "sdk/**"
+      - "packages/sdk/**"
 
 permissions:
   contents: read

README.md

@@ -16,8 +16,8 @@ Nothing in this repo may contradict it; changing it is a human decision.
 
 ```
 kernel/     relayflowd — Rust. Journal, scheduler, leases, timers, streams. One binary.
-sdk/        TypeScript-first authoring SDK. Compiles specs; speaks the journal protocol.
-surface/    @relayflows/surface — the TypeScript flow-authoring contract.
+packages/sdk/        TypeScript-first authoring SDK. Compiles specs; speaks the journal protocol.
+packages/surface/    @relayflows/surface — the TypeScript flow-authoring contract.
 workflows/  The gates. Each gate is a relayflow; the build is orchestrated by relayflows.
 docs/       RFC-0001 and design docs.
 charter/    The Relayflow Lead.

docs/SURFACE.md

@@ -385,7 +385,7 @@ cycle` error — before a journal exists and before the step's command runs.
 Cycles that pass through a child applicator (`properties`, `items`,
 `prefixItems`, ...) consume one level of the instance per step, so ordinary
 recursive schemas stay legal. `kernel/relayflowd-core/src/schema.rs` and
-`sdk/src/json-schema-bound.ts` implement the same rule and are pinned to the
+`packages/sdk/src/json-schema-bound.ts` implement the same rule and are pinned to the
 shared corpus in `testdata/json-schema-bound-cases.json`, so the kernel and the
 SDK agree on which schemas are legal by construction. `verify` compiles through
 the same gate, so a journal written before the bound existed fails its gate with

docs/bootstrap-report.md

@@ -5,7 +5,7 @@ Honest state only: what exists, what passed, what is missing.
 
 ## What was built
 
-All of the following is **uncommitted** on `main` (untracked `kernel/`, `sdk/`,
+All of the following is **uncommitted** on `main` (untracked `kernel/`, `packages/sdk/`,
 `testdata/`; `workflows/bootstrap-gate1.yaml` modified mid-run to swap the
 adversary agent's CLI from `grok` to `claude`). A human decides branch/commit/PR.
 
@@ -35,7 +35,7 @@ v0 (12 verbs, JSON over unix socket).
 - Largest file 397 lines; `cargo clippy -D warnings` and `cargo fmt --check`
   passed at build time (per kernel-dev's step report).
 
-### sdk/ — @relayflows/sdk, TypeScript (sdk-dev)
+### packages/sdk/ — @relayflows/sdk, TypeScript (sdk-dev)
 - `spec.ts` — spec types mirroring RFC §1's ladder (`deterministic | llm |
   agent`), verification gates, recovery modes, agent surfaces, budgets;
   zero-agent flows legal by construction.
@@ -50,7 +50,7 @@ v0 (12 verbs, JSON over unix socket).
 
 ### testdata/ — shared parity fixture
 `hello-ladder.flow.yaml` → `hello-ladder.spec.canonical.json` + sha256, pinned
-bit-for-bit on **both** sides (`sdk/tests/spec-parity.test.ts`,
+bit-for-bit on **both** sides (`packages/sdk/tests/spec-parity.test.ts`,
 `kernel/relayflowd-core/tests/spec_parity.rs`), so the SDK-compiled spec and
 the kernel-parsed spec provably hash identically.
 
@@ -112,7 +112,7 @@ test tests::append_is_durable_and_monotonic_after_reopen ... ok
 test result: ok. 5 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out
 ```
 
-### `npm test` (sdk/: `tsc --noEmit && vitest run`) — 41 passed, 0 failed
+### `npm test` (packages/sdk/: `tsc --noEmit && vitest run`) — 41 passed, 0 failed
 
 ```
  ✓ tests/journal-client.test.ts (7 tests) 17ms
@@ -143,7 +143,7 @@ Minor observations carried forward from the review (not violations):
 2. `next_actions` returns only `ArmTimer` for the first backing-off step in
    spec order — wall-clock inefficiency for future parallel DAGs, irrelevant
    to the sequential gate-1 ladder.
-3. `sdk/dist/` build artifacts are checked in; fresh today, but they can drift.
+3. `packages/sdk/dist/` build artifacts are checked in; fresh today, but they can drift.
 
 ## What gate 1 still needs
 

examples/research/shims/agent-cli.ts

@@ -1,6 +1,6 @@
 // REPLACE-WHEN: gate-1 agent dispatch accepts a run-time instruction and the
 // kernel starts independent steps concurrently. Then `f.agent` is the SDK's
-// AgentWorker (sdk/src/worker.ts) and this file is deleted.
+// AgentWorker (packages/sdk/src/worker.ts) and this file is deleted.
 //
 // What this shim provides today: the `agent` verb of research.flow.ts's
 // context, executed by spawning the lane's declared CLI through its headless
@@ -159,7 +159,7 @@ export const runAgentWithCli: AgentRunner = async (options) => {
   }
   const { argv, stdin } = headlessInvocation(cli, { model, promptFile, cwd: options.cwd, binaries: options.binaries });
   const env: NodeJS.ProcessEnv = { ...process.env };
-  // Same rule as sdk/src/worker.ts: unset first, then set only when declared,
+  // Same rule as packages/sdk/src/worker.ts: unset first, then set only when declared,
   // so a CLI can tell "no model chosen" from an inherited pin.
   delete env[MODEL_ENV];
   if (model !== undefined) env[MODEL_ENV] = model;

examples/research/tsconfig.json

@@ -11,7 +11,7 @@
     "allowImportingTsExtensions": true,
     "skipLibCheck": true,
     "forceConsistentCasingInFileNames": true,
-    "typeRoots": ["../../sdk/node_modules/@types"],
+    "typeRoots": ["../../packages/sdk/node_modules/@types"],
     "types": ["node"]
   },
   "include": ["**/*.ts"]

kernel/relayflowd-core/src/schema.rs

@@ -17,7 +17,7 @@
 //! recursive schemas: each step consumes one level of the instance, so they
 //! terminate, and they stay legal.
 //!
-//! `sdk/src/json-schema-bound.ts` implements the same rule, and
+//! `packages/sdk/src/json-schema-bound.ts` implements the same rule, and
 //! `testdata/json-schema-bound-cases.json` is the corpus both sides are pinned
 //! to, so kernel and SDK agree on which schemas are legal by construction
 //! rather than by coincidence of two engines' overflow behaviour.

kernel/relayflowd-core/tests/spec_parity.rs

@@ -1,7 +1,7 @@
 //! The kernel half of the cross-boundary spec-parity gate.
 //!
 //! `testdata/hello-ladder.spec.canonical.json` is emitted by the SDK compiler
-//! (see `sdk/tests/spec-parity.test.ts`). This test proves the kernel parses
+//! (see `packages/sdk/tests/spec-parity.test.ts`). This test proves the kernel parses
 //! that exact artifact fail-closed, and that re-serializing it — precisely what
 //! the engine hashes when it stamps `spec_hash` in `run.spawned` — reproduces
 //! the same canonical bytes and the same sha256 the SDK computed. Together the

ops/FORBIDDEN_PATHS

@@ -15,7 +15,7 @@
 
 # Review rejected an in-kernel HTTP adapter (PR #16, P1): a durable-execution
 # kernel must not own provider-specific product logic or network I/O. The
-# Hacker News adapter lives at sdk/src/hn-poller.ts, outside the kernel.
+# Hacker News adapter lives at packages/sdk/src/hn-poller.ts, outside the kernel.
 kernel/relayflowd/src/engine/hn_poller.rs
 kernel/relayflowd/tests/hn_poller.rs
 

ops/cargo.sh

@@ -40,7 +40,7 @@ export RUSTUP_HOME="$toolchain_home/rustup"
 # whole of the problem.
 #
 # Anything that hardcodes kernel/target/debug must read RELAYFLOWD_BIN instead;
-# sdk/tests/live-kernel.test.ts already does.
+# packages/sdk/tests/live-kernel.test.ts already does.
 # Keyed per worktree. Review caught that a single shared target dir would be
 # used by every worktree under the same HOME (PR #38): cargo locks it, so the
 # builds are safe, but two different source trees sharing one target thrash

ops/probes/pr134-repair-0903/gate-cost.mjs

@@ -5,8 +5,8 @@ import { fileURLToPath } from 'node:url';
 const REPO = resolve(dirname(fileURLToPath(import.meta.url)), '../../..');
 const DIST = process.argv[2] ?? 'dist';
 const N = Number(process.argv[3] ?? 30000);
-const { AuthoredFlowOperation, verifyAuthoredOperations } = await import(`${REPO}/sdk/${DIST}/authored-flow-operation.js`);
-const { AuthoredFlowLifecycle } = await import(`${REPO}/sdk/${DIST}/authored-flow-lifecycle.js`);
+const { AuthoredFlowOperation, verifyAuthoredOperations } = await import(`${REPO}/packages/sdk/${DIST}/authored-flow-operation.js`);
+const { AuthoredFlowLifecycle } = await import(`${REPO}/packages/sdk/${DIST}/authored-flow-lifecycle.js`);
 
 const lc = new AuthoredFlowLifecycle();
 const ops = [];

ops/probes/pr134-repair-0903/harness.mjs

@@ -1,7 +1,7 @@
 // Shared probe harness for the PR #134 authored-lifecycle repair.
 //
 // Drives the real `executeAuthoredFlow` against a loopback journal faithful to
-// `sdk/tests/journal-client-loopback.ts`, and reports which journal runs were
+// `packages/sdk/tests/journal-client-loopback.ts`, and reports which journal runs were
 // started — so "did the flow lower its terminal complete-* run" is observed,
 // not inferred. Run any probe in this directory with plain `node`.
 import { randomUUID } from 'node:crypto';
@@ -12,9 +12,9 @@ import { fileURLToPath } from 'node:url';
 import { rmSync } from 'node:fs';
 
 const REPO = resolve(dirname(fileURLToPath(import.meta.url)), '../../..');
-export const { executeAuthoredFlow } = await import(`${REPO}/sdk/dist/authored-flow-executor.js`);
-export const { JournalClient } = await import(`${REPO}/sdk/dist/journal-client.js`);
-export const { flow } = await import(`${REPO}/surface/dist/index.js`);
+export const { executeAuthoredFlow } = await import(`${REPO}/packages/sdk/dist/authored-flow-executor.js`);
+export const { JournalClient } = await import(`${REPO}/packages/sdk/dist/journal-client.js`);
+export const { flow } = await import(`${REPO}/packages/surface/dist/index.js`);
 
 function sockPath() { return join(tmpdir(), `rf-${randomUUID().slice(0, 8)}.sock`); }
 

ops/probes/pr134-repair-0903/promise-all-semantics.mjs

@@ -5,7 +5,7 @@ import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 const REPO = resolve(dirname(fileURLToPath(import.meta.url)), '../../..');
 const DIST = process.argv[2] ?? 'dist';
-const { AuthoredFlowLifecycle } = await import(`${REPO}/sdk/${DIST}/authored-flow-lifecycle.js`);
+const { AuthoredFlowLifecycle } = await import(`${REPO}/packages/sdk/${DIST}/authored-flow-lifecycle.js`);
 
 const nativeAll = Promise.all;
 const lc = new AuthoredFlowLifecycle();

ops/probes/pr134-repair-0903/verb-output-fields.mjs

@@ -5,8 +5,8 @@ import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { mkdirSync, writeFileSync } from 'node:fs';
 const REPO = resolve(dirname(fileURLToPath(import.meta.url)), '../../..');
-const { validateSpec } = await import(`${REPO}/sdk/dist/validate.js`);
-const { compileYaml, toKernelSpec } = await import(`${REPO}/sdk/dist/compile.js`);
+const { validateSpec } = await import(`${REPO}/packages/sdk/dist/validate.js`);
+const { compileYaml, toKernelSpec } = await import(`${REPO}/packages/sdk/dist/compile.js`);
 
 // Documented shape (docs/SURFACE.md): the JSON Schema sits directly under `output`.
 const OUTPUT = { type: 'object', properties: { verdict: { type: 'string' } }, required: ['verdict'] };
@@ -66,4 +66,4 @@ for (const [name, body] of Object.entries(bodies)) {
   }
   console.log(`  ${name.padEnd(14)} ${line}`);
 }
-if (outDir) console.log(`--- PATH 3 (supporting) fixtures written to ${outDir} (run: node sdk/dist/cli.js check <fixture>)`);
+if (outDir) console.log(`--- PATH 3 (supporting) fixtures written to ${outDir} (run: node packages/sdk/dist/cli.js check <fixture>)`);

sdk/package.json → packages/sdk/package.json

@@ -24,7 +24,7 @@
     "prepare": "npm run build",
     "typecheck": "tsc --noEmit && tsc -p tsconfig.type-tests.json",
     "typecheck:tests": "tsc -p tsconfig.tests.json",
-    "test:prep": "( cd ../kernel && sh ../ops/cargo.sh build ) && ( [ ! -d ../testdata/preflight ] || find ../testdata/preflight -name '*-cli' -type f -exec chmod +x {} + )",
+    "test:prep": "( cd ../../kernel && sh ../ops/cargo.sh build ) && ( [ ! -d ../../testdata/preflight ] || find ../../testdata/preflight -name '*-cli' -type f -exec chmod +x {} + )",
     "test": "sh scripts/test.sh",
     "test:watch": "vitest"
   },

sdk/tests/backlog-picker-flow.test.ts → packages/sdk/tests/backlog-picker-flow.test.ts

@@ -18,7 +18,7 @@ import { describe, expect, it } from 'vitest';
  * test of a paraphrase would pass while the flow stayed broken.
  */
 function stepCommands(): Record<string, string> {
-  const flowPath = join(__dirname, '..', '..', 'testdata', 'backlog-picker.flow.yaml');
+  const flowPath = join(__dirname, '..', '..', '..', 'testdata', 'backlog-picker.flow.yaml');
   const flow = load(readFileSync(flowPath, 'utf8')) as { steps: Array<{ id: string; command: string }> };
   return Object.fromEntries(flow.steps.map((s) => [s.id, s.command]));
 }
@@ -114,7 +114,7 @@ describe('backlog-picker canonical spec', () => {
     // caught it. A divergence between the two is silent by nature: both files
     // are valid, the tests over the yaml pass, and the kernel keeps executing
     // the stale command.
-    const root = join(__dirname, '..', '..');
+    const root = join(__dirname, '..', '..', '..');
     const flow = load(readFileSync(join(root, 'testdata', 'backlog-picker.flow.yaml'), 'utf8')) as {
       steps: Array<{ id: string; command?: string }>;
     };
@@ -143,7 +143,7 @@ describe('backlog-picker canonical spec', () => {
     // The rule is shape, not content: whatever fields the kernel-authored
     // steps carry, every step must carry, and no step may carry an authoring
     // -surface alias the kernel does not read.
-    const root = join(__dirname, '..', '..');
+    const root = join(__dirname, '..', '..', '..');
     const canonical = JSON.parse(
       readFileSync(join(root, 'testdata', 'backlog-picker.spec.canonical.json'), 'utf8'),
     ) as { steps: Array<Record<string, unknown>> };
@@ -176,7 +176,7 @@ describe('backlog-picker canonical spec', () => {
     // yaml declares the dependencies; the canonical spec must carry the same
     // ones under `depends_on`. This cannot go stale as the kernel's schema
     // grows, because it asserts a relationship rather than a field list.
-    const root = join(__dirname, '..', '..');
+    const root = join(__dirname, '..', '..', '..');
     const flow = load(readFileSync(join(root, 'testdata', 'backlog-picker.flow.yaml'), 'utf8')) as {
       steps: Array<{ id: string; dependsOn?: string[] }>;
     };

sdk/tests/backlog-picker.test.ts → packages/sdk/tests/backlog-picker.test.ts

@@ -60,7 +60,7 @@ describe('backlog picker', () => {
   });
 
   it('does not treat backticked prose containing a slash as a file in scope', () => {
-    const flowPath = join(__dirname, '..', '..', 'testdata', 'backlog-picker.flow.yaml');
+    const flowPath = join(__dirname, '..', '..', '..', 'testdata', 'backlog-picker.flow.yaml');
     const flow = load(readFileSync(flowPath, 'utf8')) as {
       steps: Array<{ id: string; command: string }>;
     };
@@ -138,7 +138,7 @@ describe('work package validation', () => {
   });
 
   it('keeps at least twenty real backlog entries actionable', async () => {
-    const backlog = readFileSync(join(__dirname, '..', '..', 'ops', 'BACKLOG.md'), 'utf8');
+    const backlog = readFileSync(join(__dirname, '..', '..', '..', 'ops', 'BACKLOG.md'), 'utf8');
     const entries = [...backlog.matchAll(/^- \*\*(.+?)\*\*\s*(.*(?:\n  .*)*)/gm)].map(
       (match) => ({
         title: match[1] ?? '',

sdk/tests/bin.test.ts → packages/sdk/tests/bin.test.ts

@@ -12,8 +12,8 @@ import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { afterEach, describe, expect, it } from 'vitest';
 
-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 PREFLIGHT = join(ROOT, 'testdata', 'preflight');
 const temporaryDirectories: string[] = [];

sdk/tests/cli.test.ts → packages/sdk/tests/cli.test.ts

@@ -22,7 +22,7 @@ import {
   type LoopbackHandlers,
 } from './journal-client-loopback.js';
 
-const TESTDATA = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'testdata');
+const TESTDATA = join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..', 'testdata');
 const DIRECT_INPUT_FLOW = join(dirname(fileURLToPath(import.meta.url)), 'fixtures', 'direct-input.flow.ts');
 const PREFLIGHT = join(TESTDATA, 'preflight');
 const LADDER = ['hello-deterministic', 'hello-llm', 'hello-agent'] as const;

sdk/tests/direct-input.test.ts → packages/sdk/tests/direct-input.test.ts

@@ -15,11 +15,11 @@ import { spawn, spawnSync, type ChildProcess } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { afterEach, beforeAll, describe, expect, it } from 'vitest';
 
-const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
-const BUILT_CLI = join(ROOT, 'sdk', 'dist', 'cli.js');
-const FLOW = join(ROOT, 'sdk', 'tests', 'fixtures', 'direct-input.flow.ts');
-const CONTROL_FLOW = join(ROOT, 'sdk', 'tests', 'fixtures', 'direct-output-control.flow.ts');
-const SIDE_EFFECT_FLOW = join(ROOT, 'sdk', 'tests', 'fixtures', 'pre-journal-side-effect.flow.ts');
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+const BUILT_CLI = join(ROOT, 'packages', 'sdk', 'dist', 'cli.js');
+const FLOW = join(ROOT, 'packages', 'sdk', 'tests', 'fixtures', 'direct-input.flow.ts');
+const CONTROL_FLOW = join(ROOT, 'packages', 'sdk', 'tests', 'fixtures', 'direct-output-control.flow.ts');
+const SIDE_EFFECT_FLOW = join(ROOT, 'packages', 'sdk', 'tests', 'fixtures', 'pre-journal-side-effect.flow.ts');
 const TOOLCHAIN_TARGET = process.env['CARGO_TARGET_DIR']
   ?? join(process.env['RELAYFLOWS_TOOLCHAIN_HOME'] ?? join(homedir(), '.relayflows-toolchain'), 'target');
 const RELAYFLOWD = resolve(process.env['RELAYFLOWD_BIN'] ?? locateRelayflowd());

sdk/tests/gate-contract.test.ts → packages/sdk/tests/gate-contract.test.ts

@@ -11,7 +11,7 @@ import { preflight } from '../src/index.js';
 import type { FlowSpec } from '../src/spec.js';
 import { validateSpec } from '../src/validate.js';
 
-const TESTDATA = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'testdata');
+const TESTDATA = join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..', 'testdata');
 
 function schemaFixture(name: 'valid' | 'invalid'): unknown {
   return JSON.parse(readFileSync(join(TESTDATA, `json-schema-${name}.json`), 'utf8'));