@deepstrike/sdk 0.2.50 → 0.2.51

package/README.md

@@ -82,7 +82,7 @@ const reply = await collectText(runner.run({ sessionId: "chat-1", goal: "What is
 
 Use `InMemorySessionLog` for process-local sessions or `FileSessionLog` when replay should survive restarts. `wake(sessionId)` resumes from the event log without inserting a duplicate `run_started` event.
 
-### Package layout (v0.2.30)
+### Package layout (v0.2.50)
 
 The root export is the **intent layer** — what you reach for to run an agent, run a workflow, author a tool, or pick a provider (~30 symbols). Advanced machinery lives behind subpaths, so the common surface stays small and tree-shakeable:
 
@@ -96,7 +96,7 @@ The root export is the **intent layer** — what you reach for to run an agent,
 | `@deepstrike/sdk/harness` | `AttemptLoop`, body/judge/carry policies, `judge` |
 | `@deepstrike/sdk/os` | profiles, `KernelPrimitivesDashboard`, `primitiveForKind` / `KernelPrimitive`, signals, `PermissionManager`, replay-testing utilities |
 
-> **Migration from 0.2.x:** the kernel-lowering converters (`*ToKernel`), low-level prompt/eval builders, and the `OpenAIChatProvider` alias are no longer exported from root; backend providers, planes, memory, harness, and OS utilities moved to the subpaths above. See [`MIGRATION-v0.2.300.md`](./MIGRATION-v0.2.300.md).
+> **Migration from 0.2.x:** the kernel-lowering converters (`*ToKernel`), low-level prompt/eval builders, and the `OpenAIChatProvider` alias are no longer exported from root; backend providers, planes, memory, harness, and OS utilities moved to the subpaths above. See [`MIGRATION-v0.2.30.md`](./MIGRATION-v0.2.30.md).
 
 ### Recipes — the canonical entry points
 
@@ -163,19 +163,19 @@ for await (const event of runner.run({ sessionId: "readme-1", goal: "Summarize R
 │  RuntimeRunner (Layer 1.5)                              │
 │  LLMProvider · ExecutionPlane · SessionLog · DreamStore │
 └───────────────────────────┬─────────────────────────────┘
-                            │ step(JSON event) ↔ actions / observations
+                            │ durable prepare / append / commit
 ┌───────────────────────────▼─────────────────────────────┐
-│  @deepstrike/core KernelRuntime                         │
+│  @deepstrike/core Canonical Kernel ABI                  │
 │  P1 Syscall · P2 Sched · P3 MM · Proc · IPC             │
 └─────────────────────────────────────────────────────────┘
 ```
 
-The runner drives a single loop:
+The runner drives one durable operation loop:
 
-1. Kernel returns an **action** — `call_provider`, `execute_tool`, `evaluate_milestone`, or `done`.
-2. SDK executes the action (stream LLM, run tools, call milestone verifier).
-3. SDK feeds the result back as a kernel **event** (`provider_result`, `tool_results`, …).
-4. Kernel **observations** (compression, page-out, spool, signals, …) are drained into `SessionLog`.
+1. The host prepares one canonical envelope and durably appends the exact core-produced record.
+2. After commit, the kernel publishes typed **effects** such as provider, tool, or task work.
+3. The SDK executes those effects and returns each outcome through the single `resolve_effect` input.
+4. Typed observations and the terminal disposition are projected into `SessionLog` and the public stream.
 
 Kernel session events carry an optional `category` tag (`syscall` · `sched` · `mm` · `proc` · `ipc`) for diagnostics and OS snapshot rebuilds.
 
@@ -186,26 +186,26 @@ The mechanisms above are not internal refactors — they change what you can bui
 **Kernel-mediated runtime (M0–M4)**  
 Tool calls, spawns, compression, and signals pass through one kernel gate with an explicit lifecycle (Ready / Running / Blocked / Suspended). You implement I/O; the kernel decides *when* and *whether*. Node, Python, and Rust share the same decision path, so `wake(sessionId)` and cross-language tooling see consistent behavior.
 
-**Longer, sturdier sessions (Layer-1 spool + semantic page-out)**  
-Oversized tool results (> 50 KB) stay in context as a preview plus a `.spool/` reference — the model reads the full payload on demand via ordinary file tools. When pressure triggers semantic eviction, the SDK summarizes archived content into `DreamStore`. Long tasks survive token pressure instead of failing mid-run.
+**Longer, sturdier sessions (external payloads + semantic page-out)**
+The host atomically persists oversized tool results before submitting an `External` result. Core journals only the opaque locator, digest, size, and preview; `read_result` becomes a correlated `LoadPayload` effect. When pressure triggers semantic eviction, the SDK summarizes archived content into `DreamStore`.
 
 **Safety and governance by default (OS native profile)**  
 Every run loads declarative `governancePolicy` (deny / ask_user / rate-limit / param rules) and in-kernel signal routing (`signalPolicy`, default queue 64). Dangerous tools, external interrupts, and approval flows are policy — not ad-hoc `if` checks in your handlers.
 
 **Long-term memory as syscalls (Phase-7)**  
-`writeMemory` and `queryMemory` run outside the main tool loop: kernel validation before `DreamStore.commit`, search → `selectMemories` → `memory_retrieval_result` on query. Failed writes emit `memory_validation_failed` for audit; good memory is durable without polluting history.
+`writeMemory` and `queryMemory` run outside the main tool loop: kernel validation happens before `DreamStore.upsert`, while queries call `DreamStore.search` and journal `memory_retrieval_result`. Failed writes emit `memory_validation_failed` for audit; good memory is durable without polluting history.
 
 **Multi-agent and multi-signal orchestration**  
 Sub-agents register in the kernel process table (`agent_process_changed`); parent runs suspend explicitly until `sub_agent_completed`. Signals get disposition (Interrupt / Queue / Observe / Dropped) in-kernel, so gateways, cron, and heartbeats compose with the main loop instead of racing it.
 
 **Observable like an OS log**  
-Spool, page-out, signals, processes, budgets, and memory events land in `SessionLog` with categories. Rebuild an OS snapshot (`pageOutCount`, `spoolCount`, `processByAgent`, memory counters) from one event stream — replay still strips audit events when reconstructing LLM messages.
+Page-out, signals, processes, budgets, and memory events land in `SessionLog` with categories. Rebuild an OS snapshot (`pageOutCount`, `processByAgent`, memory counters) from one event stream; payload residency stays in the canonical journal.
 
 | You need… | Use… |
 |---|---|
 | Policy before tools run | `governancePolicy` (default: allow-all native profile) |
 | External interrupts | `signalSource` + in-kernel `signalPolicy` |
-| Huge tool output | Automatic Layer-1 spool; optional custom `resultSpool` |
+| Huge tool output | Canonical external payload; optional custom `payloadStore` |
 | Durable recall across runs | `DreamStore` + semantic `page_out` via `dreamSummarizer` |
 | Programmatic memory I/O | `runner.writeMemory()` / `runner.queryMemory()` |
 | Debug / compliance | `SessionLog` events + OS snapshot helpers |
@@ -228,27 +228,56 @@ const outcome = await runner.runWorkflow({
     { task: "Skeptic: which flags are real violations?",  role: "verify", dependsOn: [0, 1, 2] },
   ],
 })
-// → { completed: ["wf-node0", … ], failed: [], outputs: { "wf-node3": "…" } }
+const completed = outcome.nodeOutcomes.filter(node => node.status === "completed")
+const partial = outcome.nodeOutcomes.filter(node => node.status === "completed_partial")
+const failed = outcome.nodeOutcomes.filter(node => node.status === "failed")
+// outcome.outputs["wf-node3"] contains the skeptic's final text.
+// outcome.rejection is present only when the whole workflow was rejected before any node ran.
 ```
 
-`runWorkflow` works **standalone** — call it on a freshly-constructed runner (e.g. inside a stateless HTTP handler) and it auto-bootstraps a kernel that owns the DAG, drives it under the same governance/quota/attention policies a full `run()` gets, and tears it down on completion. Called *during* a `run()`, it instead drives the workflow on the active kernel. Either way every node's final text comes back in `outputs`, keyed by node agent-id. To resume an interrupted standalone run, pass the prior session id: `runner.resumeWorkflow(spec, { sessionId })`.
+`runWorkflow` works **standalone** — call it on a freshly-constructed runner (e.g. inside a stateless HTTP handler) and it auto-bootstraps a kernel that owns the DAG, drives it under the same governance/quota/attention policies a full `run()` gets, and tears it down on completion. Called *during* a `run()`, it instead drives the workflow on the active kernel. Either way every node's final text comes back in `outputs`, keyed by node agent-id.
 
-A node's `kind` selects the control-flow shape; the same executor drives them all, every spawn passing the syscall gate:
+A workflow node has no public `kind` field. Its control-flow shape is selected by one of four
+mutually exclusive fields; omit all four for a normal spawn. The same executor drives every shape,
+and every spawn passes the syscall gate:
 
-| Node `kind` | Behavior |
+| Public `WorkflowNodeSpec` field | Behavior |
 |---|---|
-| `{ type: "spawn" }` (default) | Run the node's agent once |
-| `{ type: "loop", maxIters }` | Re-run until the agent signals it's done, capped at `maxIters` |
-| `{ type: "classify", branches }` | The classifier's result selects one branch; the rest are pruned |
-| `{ type: "tournament", entrants }` | Generate N entrants, then a pairwise-judge bracket to one winner |
-| `{ type: "reduce", reducer }` | **Tokenless host-compute** — a pure function (`dedupe_lines` / `merge_json_arrays` / `concat` / `count`, or your own via the `reducers` runner option) over the node's dependency outputs |
+| none (default) | Run the node's agent once |
+| `loop: { maxIters }` | Re-run until the agent signals it's done, capped at `maxIters` |
+| `classify: { branches }` | The classifier's result selects one branch; the rest are pruned |
+| `tournament: { entrants }` | Generate N entrants, then a pairwise-judge bracket to one winner |
+| `reducer: "concat"` | **Tokenless host-compute** — a pure function (`dedupe_lines` / `merge_json_arrays` / `concat` / `count`, or your own via the `reducers` runner option) over the node's `dependsOn` outputs |
 
-### 0.2.11 capabilities
+Dependencies use `dependsOn: number[]`, where each number is a node index, and `depPolicy` controls
+how upstream terminal states gate the node (`all_success` by default, plus `accept_partial`,
+`all_terminal`, and `optional`).
 
-- **Runtime fan-out** — give a node the `submitWorkflowNodesTool` and its agent can append nodes to the live DAG mid-run (true loop-until-done; one verifier per claim it discovers). Recorded and replayed on `resumeWorkflow`. Governance rejection fails the submitting node instead of acknowledging work that was never appended.
+### Workflow capabilities (v0.2.50)
+
+- **Runtime fan-out** — register `submitWorkflowNodesTool` on the parent execution plane and a trusted node can append nodes to the live DAG mid-run (true loop-until-done; one verifier per discovered claim). The tool schema is exported from `@deepstrike/sdk/workflow`, not the package root. Submission events remain audit projections; checkpoint state owns recovery. Governance rejection fails the submitting node instead of acknowledging work that was never appended.
 - **Quarantine, no escape** — set `trust: "quarantined"` on a node that reads untrusted content; it's denied write-capable isolation in-kernel, and any nodes it submits are coerced to quarantined too (no privilege escalation).
 - **Structured output** — set `outputSchema` on a node; the runner instructs the agent, validates the result against the JSON-Schema subset, and re-runs once with the errors on mismatch. A node that never conforms fails (its dependents starve).
-- **Budget as signal** — with a `maxWorkflowNodes` / `maxConcurrentSubagents` quota installed, each spawned node's goal carries its remaining headroom so a coordinator can size its fan-out to fit.
+- **Budget as signal** — set `resourceQuota.maxWorkflowNodes` and/or `resourceQuota.maxConcurrentSubagents`; each spawned node's goal carries its remaining headroom so a coordinator can size its fan-out to fit.
+
+`submitWorkflowNodesTool` is a `ToolSchema`, while execution planes register `RegisteredTool`
+instances. Adapt it once on the parent plane; the runner intercepts the call before the placeholder
+handler executes:
+
+```typescript
+import { tool } from "@deepstrike/sdk"
+import { submitWorkflowNodesTool } from "@deepstrike/sdk/workflow"
+
+plane.register(tool(
+  submitWorkflowNodesTool.name,
+  submitWorkflowNodesTool.description,
+  JSON.parse(submitWorkflowNodesTool.parameters),
+  async () => "", // intercepted by RuntimeRunner
+))
+```
+
+Trusted workflow nodes inherit the parent plane, so the tool is visible to all of them. There is no
+per-node tool allowlist on `WorkflowNodeSpec`; quarantined nodes use a filtered, deny-all plane.
 
 ---
 
@@ -337,7 +366,7 @@ Full reference: [docs/concepts/context-slots-compression.md](../docs/concepts/co
 import {
   DEFAULT_NATIVE_GOVERNANCE_POLICY,
   DEFAULT_NATIVE_SIGNAL_POLICY,
-} from "@deepstrike/sdk"
+} from "@deepstrike/sdk/os"
 
 const runner = new RuntimeRunner({
   provider,
@@ -359,14 +388,15 @@ const runner = new RuntimeRunner({
   // Resource quotas (M2) — enforced at the kernel syscall trap. Opt-in; omit for unbounded.
   resourceQuota: {
     maxConcurrentSubagents: 4,                       // deny spawn while at cap
+    maxTotalSubagents: 20,                           // cumulative cap across the RunGroup
     maxSpawnDepth: 2,                                // deny spawn past nesting depth
+    maxWorkflowNodes: 32,                            // cap one live DAG, including submitted nodes
     memoryWritesPerWindow: { maxWrites: 20, windowMs: 60_000 }, // rate-limit writeMemory
   },
 
-  // Long-term memory policy (set_memory_policy) — opt-in, kernel-enforced; omit for defaults.
+  // Canonical long-term memory policy — opt-in, kernel-enforced; omit for defaults.
   memoryPolicy: {
-    memoryPath: "./.memory",     // where the SDK persists/scans memories (SDK-consumed)
-    staleWarningDays: 30,        // flag recalled memories older than this (SDK-consumed)
+    staleWarningDays: 30,        // flag recalled memories older than this
     retrievalTopK: 5,            // kernel caps query_memory requested_k to this
     validationEnabled: true,     // false → admit writes without validation
     maxContentBytes: 10_000,     // override write_memory content-size limit
@@ -414,13 +444,14 @@ const runner = new RuntimeRunner({
 
 | Option | Purpose |
 |--------|---------|
-| `governancePolicy` | Declarative deny / ask_user / rate-limit / param rules loaded into the kernel before `start_run` |
+| `governancePolicy` | Declarative deny / ask_user / rate-limit / param rules installed before canonical root start |
 | `signalPolicy` | Versioned in-kernel signal queue/TTL policy (default queue 64) |
 | `promptBudget` | Provider-envelope overhead, output reserve, and safety margin deducted from the context window |
-| `resourceQuota` | M2 declarative limits — `maxConcurrentSubagents` / `maxSpawnDepth` / `memoryWritesPerWindow` — enforced at the kernel syscall trap (`set_resource_quota`); over-quota spawns roll back, over-rate writes surface as `memory_validation_failed` |
-| `memoryPolicy` | Long-term memory config sent as `set_memory_policy` and **kernel-enforced**: `validationEnabled: false` admits writes without validation, `maxContentBytes` / `maxNameLength` override validation limits, `retrievalTopK` caps `query_memory` breadth; `memoryPath` / `staleWarningDays` are SDK-consumed (requires `dreamStore` + `agentId` to enable memory) |
+| `resourceQuota` | M2 declarative limits — `maxConcurrentSubagents` / `maxTotalSubagents` / `maxSpawnDepth` / `maxWorkflowNodes` / `memoryWritesPerWindow` — enforced at the kernel syscall trap (`set_resource_quota`); over-quota spawns roll back, over-rate writes surface as `memory_validation_failed` |
+| `memoryPolicy` | Canonical long-term memory policy: `validationEnabled: false` admits writes without validation, `maxContentBytes` / `maxNameLength` override validation limits, `retrievalTopK` caps `query_memory` breadth, and `staleWarningDays` controls stale recall policy. Storage belongs to the configured `dreamStore`. |
 | `onPermissionRequest` | Resolves `tool_gated` + `suspended` → kernel `resume` with approved/denied call IDs |
 | `compressionStore` | Writes archived messages on `compressed` observations |
+| `payloadStore` | Resolves canonical opaque payload locators (default: `.payloads/`) |
 | `asyncSummarizer` | Background LLM summary after compression; stored as `summary_upgraded` |
 | `dreamSummarizer` | Summarizes `page_out { tier_hint: "semantic" }` into `DreamStore` during a run |
 | `dreamProvider` | Separate LLM for `dream()` idle consolidation (falls back to `provider`) |
@@ -428,37 +459,33 @@ const runner = new RuntimeRunner({
 Rebuild an OS diagnostics snapshot from session events:
 
 ```typescript
-import { rebuildOsSnapshotFromSessionEvents } from "@deepstrike/sdk"
+import { rebuildOsSnapshotFromSessionEvents } from "@deepstrike/sdk/os"
 
 const events = (await sessionLog.read(sessionId)).map(e => e.event)
 const snap = rebuildOsSnapshotFromSessionEvents(events)
-// snap.pageOutCount, snap.spoolCount, snap.signals, snap.processByAgent, …
+// snap.pageOutCount, snap.signals, snap.processByAgent, …
 ```
 
 ---
 
-## Large result spool (Layer 1)
+## External tool payloads
 
-When a single tool result exceeds **50 KB**, the kernel keeps a short preview in context and emits `large_result_spooled`. The SDK writes the full payload to `.spool/` under the process cwd (SHA-256 keyed files) and logs `spool_ref` in the session.
+When a tool result exceeds the configured inline threshold, the SDK persists the full body before sending the canonical `External` result. The kernel receives only `payload_ref`, `digest`, `original_size`, and a bounded preview.
 
-The model can retrieve full content via ordinary read tools — `LocalExecutionPlane` transparently resolves paths under `.spool/`:
+The locator is opaque and never passed to ordinary file tools. The model calls `read_result`; core authorizes the reachable handle and emits `LoadPayload`, which the runner resolves through `PayloadStore`.
 
-```typescript
-// Kernel context shows a preview + spool reference.
-// LLM calls read_file({ path: ".spool/abc123…" }) → full content returned.
-```
-
-No configuration is required; customize the directory by passing a `resultSpool` instance when constructing `RuntimeRunner` (see tests under `tests/runtime/large-result-spool.test.ts`).
+No configuration is required. Pass a `PayloadStore` through `RuntimeOptions.payloadStore` to use a different filesystem root or storage adapter.
 
 ---
 
 ## Tools
 
 ```typescript
-import { tool, readFile } from "@deepstrike/sdk"
+import { tool } from "@deepstrike/sdk"
+import { readFile } from "@deepstrike/sdk/workflow"
 
 plane.register(tool("search", "Search.", schema, async (args) => ...))
-plane.register(readFile)     // built-in: read files from disk (also resolves .spool/ refs)
+plane.register(readFile)     // built-in: read files explicitly named by the caller
 plane.unregister("search")
 ```
 
@@ -553,35 +580,31 @@ mem.clear()
 import type { DreamStore } from "@deepstrike/sdk/memory"
 
 class MyStore implements DreamStore {
-  async loadSessions(agentId) { ... }
-  async loadMemories(agentId) { ... }
-  async commit(agentId, result, existing) { ... }
-  async search(agentId, query) { ... } // Promise<MemoryRecall[]>
+  async upsert(agentId, record) { ... }      // the only durable memory mutation
+  async search(agentId, query) { ... }       // Promise<MemoryRecall[]>
+  async saveSession(session) { ... }         // completed transcript for extraction
 }
 
+const memoryScope = { tenant_id: "acme", namespace: "assistant" }
 const runner = new RuntimeRunner({
   provider,
   executionPlane: plane,
   sessionLog: new FileSessionLog(".deepstrike/sessions"),
   maxTokens: 4096,
   dreamStore: new MyStore(),
-  agentId: "my-agent",  // enables `memory` meta-tool + semantic page-out archival
+  agentId: "my-agent",
+  memoryScope,          // scopes run-start recall, queries, extraction, and semantic page-out
 })
 ```
 
-Three memory paths:
+Four memory paths:
 
 | Path | When | What happens |
 |------|------|--------------|
 | In-session `memory(query)` | LLM calls meta-tool | `DreamStore.search()` → history tool result |
 | `initialMemory` | Run start | Injected into Slot 2 (`systemKnowledge`) |
-| Semantic `page_out` | Kernel evicts with `tier_hint: "semantic"` | SDK summarizes via `dreamSummarizer` / `dreamProvider` → `DreamStore.commit()` |
-| `dream(agentId)` | Explicit idle call | `IdlePipeline` batch-consolidates past sessions |
-
-```typescript
-// Post-session batch consolidation
-const result = await runner.dream("my-agent", Date.now())
-```
+| `writeMemory(record)` | Host writes a durable record | Kernel validation / quota / dedup → `DreamStore.upsert()` |
+| Semantic `page_out` | Kernel evicts with `tier_hint: "semantic"` | SDK summarizes via `dreamSummarizer` / `dreamProvider` → gated `writeMemory()` |
 
 ### Phase-7 memory syscalls (`writeMemory` / `queryMemory`)
 
@@ -682,7 +705,7 @@ Inbound signals are routed by the in-kernel attention policy (default queue size
 | queue full | `dropped` |
 
 ```typescript
-import { SignalGateway, ScheduledPrompt } from "@deepstrike/sdk"
+import { SignalGateway, ScheduledPrompt } from "@deepstrike/sdk/os"
 
 const gw = new SignalGateway()
 gw.schedule(new ScheduledPrompt("standup", Date.now() + 3600_000))

package/dist/index.d.ts

@@ -4,20 +4,18 @@ export type { LoopSpec, LoopOutcome } from "./runtime/loop-driver.js";
 export type { RunAgentOptions, RunFanoutOptions } from "./runtime/facade.js";
 export { RuntimeRunner, collectText } from "./runtime/runner.js";
 export type { RuntimeOptions, KernelReliabilityOptions, OperationCancellationReason, PromptBudget, SchedulerPolicy } from "./runtime/runner.js";
+export { PayloadStore } from "./runtime/payload-store.js";
+export type { PayloadStoreConfig } from "./runtime/payload-store.js";
 export type { InstructionProfile, NudgeRule, NudgeTrigger } from "./harness/public.js";
 export type { SignalPolicy } from "./runtime/os-profile.js";
-export { readKernelDiagnostics, restoreKernelRuntime, snapshotKernelRuntime } from "./runtime/kernel-step.js";
-export type { KernelDiagnostics, KernelSnapshot } from "./runtime/kernel-step.js";
-export { rebuildKernelRuntime } from "./runtime/kernel-rebuild.js";
-export type { KernelRebuildResult } from "./runtime/kernel-rebuild.js";
 export { CONTEXT_POLICY_VERSION, DEFAULT_CONTEXT_POLICY_V1, PPM_SCALE, contextPolicyV1, normalizeContextPolicyV1, ratioToPpm, } from "./runtime/context-policy.js";
 export type { ContextPolicyOverridesV1, ContextPolicyV1, ContextPolicyWireV1, ContextPressureThresholdsV1, } from "./runtime/context-policy.js";
 export { LocalExecutionPlane } from "./runtime/execution-plane.js";
 export type { ExecutionPlane, RunContext } from "./runtime/execution-plane.js";
 export { InMemorySessionLog, FileSessionLog } from "./runtime/session-log.js";
-export type { KernelTransactionEntry, SessionLog, SessionEvent } from "./runtime/session-log.js";
-export { KERNEL_LOG_RECORD_VERSION, KernelLogConflictError, KernelLogIntegrityError, canonicalKernelJson, createKernelOperationGenesis, createKernelTransaction, kernelRecordDigest, verifyKernelOperationGenesis, verifyKernelTransaction, verifyKernelTransactionStream, verifyKernelTransactionSuccessor, } from "./runtime/kernel-transaction-log.js";
-export type { DurableAppendReceipt, KernelGenesisReceipt, KernelOperationCursor, KernelOperationGenesis, KernelOperationGenesisBody, KernelTransaction, KernelTransactionBody, } from "./runtime/kernel-transaction-log.js";
+export type { SessionLog, SessionEvent } from "./runtime/session-log.js";
+export { FileKernelJournal, InMemoryKernelJournal, JournalCasConflictError, JournalIntegrityError, JournalIoError, } from "./runtime/kernel-journal.js";
+export type { CheckpointCandidate, InstalledCheckpoint, JournalAppendReceipt, JournalEntry, JournalHead, JournalPruneReceipt, JournalRecordInput, KernelJournal, } from "./runtime/kernel-journal.js";
 export { InMemoryGroupBudgetStore, GroupBudgetScope } from "./runtime/run-group.js";
 export type { RunGroup, GroupBudgetStore, GroupLedger, GroupCharge, GroupMember, GroupBudgetRequest, GroupBudgetReservation, } from "./runtime/run-group.js";
 export { InMemoryEventStream, isVisibleTo } from "./runtime/event-stream.js";

package/dist/index.js

@@ -15,13 +15,13 @@ export { runAgent, runFanout } from "./runtime/facade.js";
 // ③ dynamic loop agents: self-pacing rounds over the kernel pacing trap.
 export { runLoop, LoopDriver, foldLoopState } from "./runtime/loop-driver.js";
 export { RuntimeRunner, collectText } from "./runtime/runner.js";
-export { readKernelDiagnostics, restoreKernelRuntime, snapshotKernelRuntime } from "./runtime/kernel-step.js";
-export { rebuildKernelRuntime } from "./runtime/kernel-rebuild.js";
+export { PayloadStore } from "./runtime/payload-store.js";
 export { CONTEXT_POLICY_VERSION, DEFAULT_CONTEXT_POLICY_V1, PPM_SCALE, contextPolicyV1, normalizeContextPolicyV1, ratioToPpm, } from "./runtime/context-policy.js";
 // ── Execution plane + session log (the defaults) ────────────────────────────
 export { LocalExecutionPlane } from "./runtime/execution-plane.js";
 export { InMemorySessionLog, FileSessionLog } from "./runtime/session-log.js";
-export { KERNEL_LOG_RECORD_VERSION, KernelLogConflictError, KernelLogIntegrityError, canonicalKernelJson, createKernelOperationGenesis, createKernelTransaction, kernelRecordDigest, verifyKernelOperationGenesis, verifyKernelTransaction, verifyKernelTransactionStream, verifyKernelTransactionSuccessor, } from "./runtime/kernel-transaction-log.js";
+// ── Durable transaction capability (Canonical Kernel ABI §9.1) ──────────────
+export { FileKernelJournal, InMemoryKernelJournal, JournalCasConflictError, JournalIntegrityError, JournalIoError, } from "./runtime/kernel-journal.js";
 export { InMemoryGroupBudgetStore, GroupBudgetScope } from "./runtime/run-group.js";
 export { InMemoryEventStream, isVisibleTo } from "./runtime/event-stream.js";
 export { ManagedTaskScope, operationAbortSignal } from "./runtime/reliability.js";

package/dist/kernel.d.ts

@@ -1,4 +1,4 @@
-import type { Message, RenderedContext } from "./types.js";
+import type { Message } from "./types.js";
 export interface GovernanceVerdict {
     kind: "allow" | "deny" | "rate_limited" | "ask_user";
     reason?: string;
@@ -33,16 +33,12 @@ export interface ResourceQuota {
 /**
  * Long-term memory policy — declarative knobs for the kernel's memory subsystem.
  *
- * Installed through the versioned JSON event ABI (`set_memory_policy`), the same channel as
- * governance / scheduler / quota config, so memory configuration is replayable and
- * session-loggable rather than a side-channel setter. Installing the policy is opt-in and
- * kernel-enforced; omitted fields fall back to the kernel defaults (empty path, 2-day stale
- * warning, top-5 retrieval, validation on). Enabling memory is still `dreamStore` + `agentId`.
+ * Included in canonical operation configuration, so memory policy is replayable and
+ * kernel-enforced. Omitted fields retain the canonical defaults. Host storage belongs to the
+ * configured `DreamStore`, never to this contract.
  */
 export interface MemoryPolicy {
-    /** Filesystem root the SDK uses to persist/scan memories; carried for SDK recall I/O. */
-    memoryPath?: string;
-    /** Age after which a recalled memory is flagged stale (days); consumed SDK-side. */
+    /** Age after which a recalled memory is flagged stale (days). */
     staleWarningDays?: number;
     /** Upper bound on retrieval breadth: the kernel clamps `query_memory` top-k to this. */
     retrievalTopK?: number;
@@ -108,31 +104,65 @@ export interface Verdict {
         content: string;
     };
 }
-export interface KernelRuntimeInstance {
-    step(inputJson: string): string;
-    prepareStep(inputJson: string): string;
-    commitPrepared(prepareToken: string): string;
-    abortPrepared(prepareToken: string): void;
-    snapshot(): string;
-    restore(snapshotJson: string): void;
-    diagnostics(): string;
-    isTerminal(): boolean;
-    turn(): number;
-    /** L1 (RunGroup): cumulative sub-agent spawns this run, for charging the group ledger at run end. */
-    localSubagentsSpawned(): number;
-    recoveryContentBytes(): number;
-    render(): RenderedContext;
-    drainNewMessages(): Message[];
-    preservedRefs(): string[];
+export interface CanonicalPrepared {
+    status: "prepared";
+    prepareToken: string;
+    stepSeq: string;
+    expectedHead?: string;
+    recordDigest: string;
+    recordBytes: Buffer;
+    plannedStepJson: string;
+}
+export interface CanonicalReplayed {
+    status: "replayed";
+    stepSeq: string;
+    expectedHead?: string;
+    recordDigest: string;
+    recordBytes?: Buffer;
+    plannedStepJson?: string;
+}
+export interface CanonicalRejected {
+    status: "rejected";
+    faultJson: string;
+}
+/** Closed §7.13 result; only `prepared` carries a token that may be committed or aborted. */
+export type CanonicalPreparation = CanonicalPrepared | CanonicalReplayed | CanonicalRejected;
+export interface CanonicalCommit {
+    stepSeq: string;
+    recordDigest: string;
+    plannedStepJson: string;
+    checkpointAdviceJson?: string;
+}
+export interface CanonicalCheckpoint {
+    checkpointBytes: Buffer;
+    throughStepSeq: string;
+    coveredHead: string;
+    stateDigest: string;
+    ackToken: string;
+}
+export interface CanonicalRestoreCost {
+    recordsBeforeCheckpoint: string;
+    tailInputsReplayed: string;
+    recordsAfterCheckpoint: string;
+    bytesRead: string;
+}
+export interface CanonicalKernelInstance {
+    prepare(inputJson: string): CanonicalPreparation;
+    commit(prepareToken: string, appendedHead: string): CanonicalCommit;
+    abort(prepareToken: string): void;
+    checkpointCandidate(): CanonicalCheckpoint;
+    checkpointRebase(checkpointBytes: Buffer): CanonicalCheckpoint;
+    ackCheckpoint(throughStepSeq: string, coveredHead: string): void;
+    /** Replaces native state in place; the JavaScript handle retains its identity. */
+    restore(checkpointBytes: Buffer | undefined, recordBytes: Buffer[]): CanonicalRestoreCost;
+    lifecycle(): "created" | "configured" | "running" | "suspended" | "completed" | "cancelled" | "failed";
+    pendingEffectsJson(): string;
+    terminalJson(): string | undefined;
 }
 interface KernelModule {
     Governance: new (defaultAction?: "allow" | "deny" | "ask_user") => GovernanceInstance;
-    KernelRuntime: new (policy: {
-        maxTokens: number;
-        maxTurns?: number;
-        maxTotalTokens?: bigint;
-        timeoutMs?: bigint;
-    }) => KernelRuntimeInstance;
+    CanonicalKernel: new () => CanonicalKernelInstance;
+    kernelAbiVersion(): number;
     SignalRouter: new (maxQueueSize: number) => SignalRouterInstance;
     buildEvalMessages(goal: string, criteria: NativeCriterion[], result: string, attempt: number, extractSkillOnPass: boolean): Message[];
     parseVerdict(content: string): Verdict;

package/dist/runtime/canonical-kernel-step.d.ts

@@ -0,0 +1,143 @@
+import type { CanonicalKernelInstance, CanonicalRestoreCost } from "../kernel.js";
+import type { Message } from "../types.js";
+import { type InstalledCheckpoint, type KernelJournal } from "./kernel-journal.js";
+import { type KernelObservation, type KernelRunnerAction } from "./kernel-step.js";
+export declare const MAX_CHAIN_POSITION = 1000000000000;
+export type CanonicalKernelInput = Record<string, unknown> & {
+    kind: string;
+};
+export interface CanonicalPlannedStep {
+    root_kind?: "agent" | "workflow";
+    focus?: Record<string, unknown>;
+    observations?: Array<Record<string, unknown>>;
+    disposition: {
+        kind: "effects";
+        effects?: Array<Record<string, unknown>>;
+    } | {
+        kind: "terminal";
+        terminal: Record<string, unknown>;
+    };
+}
+export interface CanonicalTransitionOptions {
+    /** Caller-stable idempotency key. Generated once when omitted. */
+    inputId?: string;
+    /** Decimal-u64 host observation. Captured once when omitted and preserved across every retry. */
+    observedAtMs?: string;
+}
+export interface CanonicalTransition {
+    inputJson: string;
+    stepSeq: number;
+    recordDigest: string;
+    plannedStep: CanonicalPlannedStep;
+    checkpointAdvice?: Record<string, unknown>;
+    replayed: boolean;
+}
+export declare function canonicalUnsupportedEffectResolution(effectId: string, effectKind: string): CanonicalKernelInput;
+/** The only ABI-v3 planned-step → Node host-action projection. */
+export declare function canonicalActionFromPlannedStep(plannedStep: CanonicalPlannedStep): KernelRunnerAction | null;
+export declare class CanonicalKernelRejectedError extends Error {
+    readonly fault: Record<string, unknown>;
+    constructor(faultJson: string);
+}
+/**
+ * A record is already authoritative once the journal append returns. A later native commit failure
+ * is therefore a rebuild boundary, never an abort boundary.
+ */
+export declare class CanonicalKernelRebuildRequiredError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Node's canonical durable staged-transition host.
+ *
+ * It owns no scheduler truth. Core prepares opaque record bytes; `KernelJournal` makes those bytes
+ * authoritative; only then may core commit and expose the planned effects/terminal to the runner.
+ */
+export declare class CanonicalKernelHost {
+    readonly kernel: CanonicalKernelInstance;
+    readonly journal: KernelJournal;
+    readonly operationId: string;
+    constructor(kernel: CanonicalKernelInstance, journal: KernelJournal, operationId: string);
+    transition(input: CanonicalKernelInput, options?: CanonicalTransitionOptions): Promise<CanonicalTransition>;
+    /** Restore the latest installed checkpoint and its authoritative record tail in place. */
+    restore(): Promise<CanonicalRestoreCost>;
+    /**
+     * Replay a crash-window outbound envelope with identical bytes (adjudication 5e.3).
+     * No-op when nothing is staged. Clears the stage after commit/replay/reject.
+     */
+    drainOutboundEnvelope(): Promise<CanonicalTransition | undefined>;
+    /** Execute the full §12.3 install/ack/reclaim boundary. */
+    checkpoint(): Promise<InstalledCheckpoint>;
+    private transitionEnvelope;
+}
+export interface CanonicalRunnerRuntimeOptions {
+    maxContextTokens: number;
+    maxTurns?: number;
+    maxTotalTokens?: number;
+    maxWallMs?: number;
+    memoryBindingId?: string;
+    persistPayload?: (callId: string, content: string, previewBytes: number) => Promise<{
+        payloadRef: string;
+        digest: string;
+        originalSize: string;
+        preview: string;
+    }>;
+}
+/**
+ * Canonical operation runtime used by the Node host.
+ * Every durable transition below is one of the canonical ABI's five input classes; no legacy
+ * envelope or synthesized host transaction reaches core or storage.
+ */
+export declare class CanonicalRunnerRuntime {
+    private readonly options;
+    private readonly host;
+    private readonly config;
+    private readonly initialContext;
+    private configured;
+    private started;
+    private turns;
+    private lastAction;
+    private readonly newMessages;
+    private readonly hostObservations;
+    private spawnedTasks;
+    private readonly memoryBindingId;
+    private payloadInlineThreshold;
+    private payloadPreviewBytes;
+    constructor(kernel: CanonicalKernelInstance, journal: KernelJournal, operationId: string, options: CanonicalRunnerRuntimeOptions);
+    get operationId(): string;
+    get journal(): KernelJournal;
+    turn(): number;
+    isTerminal(): boolean;
+    recoveryContentBytes(): number;
+    preservedRefs(): string[];
+    drainNewMessages(): Message[];
+    drainHostObservations(): KernelObservationLike[];
+    terminal(): Record<string, unknown> | undefined;
+    localSubagentsSpawned(): number;
+    restore(): Promise<void>;
+    resumeAction(): KernelRunnerAction | null;
+    startAgent(taskValue: Record<string, unknown>, runSpecValue?: Record<string, unknown>): Promise<KernelRunnerAction | null>;
+    startWorkflow(specValue: Record<string, unknown>): Promise<KernelRunnerAction | null>;
+    applyHostEvent(event: Record<string, unknown>): Promise<KernelRunnerAction | null>;
+    private ensureConfigured;
+    private commit;
+    private currentAction;
+    private pendingEffects;
+    private succeededEffect;
+    private failedEffect;
+    private pageOutResolution;
+    private canonicalSignal;
+    private canonicalCapabilityCommand;
+    private applyBootstrapEvent;
+    private featurePolicy;
+    private executionPolicy;
+    private mergeHostConfig;
+}
+export declare function canonicalKernelApply(runtime: CanonicalRunnerRuntime, pending: KernelObservationLike[], event: Record<string, unknown>): Promise<KernelObservationLike[]>;
+export declare function canonicalKernelMaybeAction(runtime: CanonicalRunnerRuntime, pending: KernelObservationLike[], event: Record<string, unknown>): Promise<KernelRunnerAction | null>;
+export declare function canonicalKernelAction(runtime: CanonicalRunnerRuntime, pending: KernelObservationLike[], event: Record<string, unknown>): Promise<KernelRunnerAction>;
+export declare function canonicalStartAgent(runtime: CanonicalRunnerRuntime, pending: KernelObservationLike[], task: Record<string, unknown>, runSpec?: Record<string, unknown>): Promise<KernelRunnerAction>;
+export declare function canonicalStartWorkflow(runtime: CanonicalRunnerRuntime, pending: KernelObservationLike[], spec: Record<string, unknown>): Promise<KernelRunnerAction | null>;
+type KernelObservationLike = KernelObservation;
+export {};