feat: declare and journal step placement with workspace pins (#225)

kernel/evidence/225/README.md

@@ -0,0 +1,71 @@
+# Issue 225 — gate 7 slice 1
+
+The red test was committed before implementation in `fa54257`. It submits two
+deterministic steps with placement requirements: the first copies a source file
+into a relative output file, the second reads that output. Resume runs from a
+different working directory. The initial failure was the kernel rejecting
+`requirements`, captured verbatim in [red.txt](red.txt).
+
+The implementation adds:
+
+- Authoring and kernel `requirements`: execution (`batch` or `interactive`),
+  workspace, network, expected duration, and cost/latency/reliability/balanced
+  preference. Duration lowers from `expectedDurationMs` to `expected_duration_ms`.
+  Provider names and revisions are not authoring fields. Shared canonical JSON,
+  hash, and an acceptance/rejection corpus pin both dialects.
+- `step.routed`: profile, provider, fallbacks attempted, and optional provider
+  workspace identity. A step has one routing fact, written before execution and
+  retained on retries and epoch rollover. `StepDispatch.routing` carries that
+  fact to the adapter. Duplicate routing writes fail inside the SQLite append
+  transaction. A failed append prevents attempt start and dispatch.
+- Fixed local batch placement for deterministic steps. Declaring requirements
+  opts into a shared worktree unless `workspace: false`; submission records its
+  canonical directory. Attempts and completions record its Git base commit.
+  Each command executes in the recorded directory, including after resume from
+  elsewhere. Local interactive execution and unavailable source commits are
+  refused before submission. Network is a capability need (`false` means no
+  need), not a network isolation policy; duration and preference are hints for
+  later ranking.
+- The default in-process worker pin source reads declared worktree base commits
+  instead of returning empty workspace pins. Remote workers continue to report
+  their own revision facts through the existing override/protocol.
+
+## Scope and integration boundary
+
+This is a declaration and journal slice, not all of gate 7. No sandbox, source
+uploader, root lease manager, provider SDK, or ranking engine is introduced.
+`StepDispatcher::routing_decision` is the adapter hook for an existing provider
+orchestrator; it is invoked only until its decision is durable. Dispatch must
+consume the recorded decision without selecting another provider on retry.
+The default attached-worker dispatcher rejects unsupported placement declarations.
+
+The remote-shaped test uses `test-cloud-adapter`, an in-process test dispatcher.
+It is **not a live cloud run**. No claim is made that Daytona source sync,
+remote deterministic execution, or actual sandbox destruction was verified.
+Connecting the flows transport to cloud's existing code-sync and sandbox
+orchestration remains integration work. Git pins here are worktree base commits,
+as allowed by Appendix A; they are not snapshots of uncommitted files. Agent
+reset/inspect/manual recovery retains its existing revision protocol.
+
+Existing specs without requirements keep their execution behavior; local
+worktree pinning is enabled by the new declaration. Their routing choices are
+still recorded when execution is admitted.
+
+## Captured commands and output
+
+Each transcript contains the literal command, stdout/stderr, and exit code.
+
+- [Red regression](red.txt):
+  `cd kernel && cargo test --workspace --test crash_resume placement:: -- --nocapture`
+- [Complete kernel gate](green-kernel.txt):
+  `cd kernel && cargo test --workspace`
+- [SDK parity and type checks](green-sdk.txt):
+  `cd packages/sdk && node node_modules/vitest/vitest.mjs run tests/placement.test.ts tests/spec-parity.test.ts`
+  plus `node node_modules/typescript/bin/tsc --noEmit` and
+  `node node_modules/typescript/bin/tsc -p tsconfig.type-tests.json` in that directory.
+
+The SDK dependencies were copied into this worktree from the existing
+`flows-212-channels-wt/packages/sdk/node_modules` after the local `npm` process
+stalled before installing dependencies. No dependency manifest or lockfile was
+changed for that copy. The Rust dev dependency on the already-used `rusqlite`
+crate supports an actual SQLite failure-injection test.

kernel/evidence/225/SPEC-REVIEW-0907.md

@@ -0,0 +1,38 @@
+# Spec review 2026-09-07: not approved for merge
+
+Four focused regression tests failed before the repair and passed after it.
+These are before/after regressions, not a full mutation-verification claim.
+- [Before](spec-review-regressions-before.txt)
+- [After](spec-review-regressions-after.txt)
+
+The full workspace run initially failed in doctests because ambient rustdoc
+used a different compiler from the explicitly selected rustc. The failure is
+preserved in [first run](spec-review-kernel-tests.txt). Selecting matching
+RUSTC and RUSTDOC produced the [final workspace output](spec-review-kernel-tests-final.txt),
+including crash/resume tests and doctests. [SDK output](spec-review-sdk-tests.txt)
+covers placement, parity and verb-field lint. Each file contains its literal
+command, complete captured output, and exit code.
+
+Repairs tighten admission/replay without adding further vocabulary:
+- Attempt-scoped routes now fail replay with the same diagnostic as append.
+- Epoch routing is validated transactionally, including preservation of prior
+  routes; a raw summary cannot silently drop or replace a routing decision.
+- Worktree pins peel HEAD to a commit and refuse non-commit objects.
+
+Unresolved blockers:
+1. RFC-0001 decision #13 / the assigned vocabulary rule: `step.routed`,
+   `epoch.summary.routing`, `StepDispatch.routing`, and the exact kernel
+   `requirements` schema have no explicit specification in RFC-0001. Gate 7
+   requires routing evidence but does not settle this extension's schema.
+   Khaliq/spec owner must settle the contract or require lowering to existing
+   facts. This repair does not amend the RFC or approve the vocabulary.
+2. `engine/placement.rs:163` still re-reads HEAD at every deterministic attempt.
+   [Reproduction](spec-review-source-drift-repro.txt) shows a source commit
+   changed between steps and resume completing against different source pins.
+   The [repro script](spec-review-source-drift-repro.py) takes the built daemon
+   path. Pin storage/recovery needs a design consistent with the settled
+   vocabulary; this patch does not invent another durable field to conceal it.
+
+The existing descriptor and blank routing-field findings were already fixed
+at the reviewed head. Neither local passing tests nor vendor checks supply
+independent review or override the specification blockers.