experimental-ash 0.2.0-alpha.20 → 0.2.0-alpha.21

package/docs/internals/context.md

@@ -1,276 +1,126 @@
 # Unified Context
 
-Ash uses a single `AshContext` container, bound by one `AsyncLocalStorage` instance, to carry all
-runtime state through the execution stack. There are no secondary `AsyncLocalStorage` bindings, no
-custom dehydration protocols, and no out-of-band parameter passing for contextual data.
+Ash uses one `AshContext` container, bound by one `AsyncLocalStorage`, to carry all ambient runtime
+data through execution. There is no second authored-state channel and no separate dehydration path
+for public context.
 
-## Files To Read
+## Core Model
 
-- `packages/ash/src/context/key.ts`
-- `packages/ash/src/context/container.ts`
-- `packages/ash/src/context/provider.ts`
-- `packages/ash/src/context/keys.ts`
-- `packages/ash/src/context/serialize.ts`
-- `packages/ash/src/context/run-step.ts`
-- `packages/ash/src/context/accessors.ts`
-- `packages/ash/src/context/providers/session.ts`
-- `packages/ash/src/context/providers/sandbox.ts`
-- `packages/ash/src/context/providers/skill.ts`
-
-## Core Primitives
+Ash now has two key categories:
 
-### ContextKey
+- `ContextKey<T>`: public durable authored context. Values live on `session.context`.
+- `RuntimeContextKey<T>`: private framework-only runtime values. These seed one step and may be
+  reconstructed on the next step.
 
-A typed key identifies a value in the container. Keys that hold non-JSON-safe values declare a
-codec for serialization at `"use step"` boundaries.
-
-```ts
-class ContextKey<T> {
-  readonly name: string;
-  readonly codec?: {
-    serialize(value: T): unknown;
-    deserialize(data: unknown): T | Promise<T>;
-  };
-}
-```
-
-### AshContext
-
-The container interface. One instance per execution scope.
+`AshContext` exposes a uniform API:
 
 ```ts
 interface AshContext {
-  get<T>(key: ContextKey<T>): T;
-  tryGet<T>(key: ContextKey<T>): T | undefined;
-  has(key: ContextKey<unknown>): boolean;
-  set<T>(key: ContextKey<T>, value: T): void;
+  get<T>(key: ContextStoreKey<T>): T;
+  tryGet<T>(key: ContextStoreKey<T>): T | undefined;
+  has<T>(key: ContextStoreKey<T>): boolean;
+  set<T>(key: ContextStoreKey<T>, value: T): void;
+  ensure<T>(key: ContextStoreKey<T>, valueOrFactory: T | (() => T)): T;
 }
 ```
 
-### contextStorage
+Public helpers such as `getContext`, `setContext`, `ensureContext`, `getSession`, `getSandbox`, and
+`getSkill` all delegate to this container.
 
-The single `AsyncLocalStorage<AshContext>` instance. Only `runStep` and the runtime entry points
-call `contextStorage.run(...)`. Everything else reads via `requireContext()`.
+## Durable Context Lifecycle
 
-### requireContext()
+Durable authored context no longer piggybacks on runtime seed serialization.
 
-Returns the active `AshContext` from `contextStorage`, or throws. Authored code (tools, steps,
-model callbacks) uses this implicitly through the public accessors.
+Every step now follows this flow:
 
-## Key Categories
+1. Deserialize runtime seed keys with `deserializeRuntimeContext(...)`.
+2. Hydrate all registered public `ContextKey`s from `session.context`.
+3. Seed internal framework bookkeeping from `session.internal`.
+4. Apply deliver-time auth and run `channel.onDeliver(...)`.
+5. Run providers and step code inside `contextStorage.run(...)`.
+6. Commit the full durable context bag back to `session.context`.
 
-### Seed keys
+The main files are:
 
-Set by the runtime entry point with live values. Serialized and deserialized at durable step
-boundaries via their codec.
+- `packages/ash/src/context/serialize.ts`
+- `packages/ash/src/context/durable-context.ts`
+- `packages/ash/src/execution/step-context.ts`
+- `packages/ash/src/context/run-step.ts`
 
-| Key | Type | Codec |
-|-----|------|-------|
-| `AuthKey` | `SessionAuthContext \| null` | none (JSON-safe) |
-| `InitiatorAuthKey` | `SessionAuthContext \| null` | none |
-| `SessionIdKey` | `string` | none |
-| `RunIdKey` | `string` | none |
-| `ContinuationTokenKey` | `string` | none |
-| `ModeKey` | `RunMode` | none |
-| `NodeSelectorKey` | `string` | none — points at the active graph node (root or a delegated subagent selector) |
-| `ParentSessionKey` | `SessionParent` | none — set only on delegated child contexts to carry parent lineage |
-| `ChannelKey` | `Channel` | serializes kind + state, deserializes by hydrating the correct channel class |
-| `BundleKey` | `CompiledBundle` | serializes to `compiledArtifactsSource`, deserializes via `getCompiledRuntimeAgentBundle` |
+## Runtime Seed Serialization
 
-Keys self-register in a global registry at construction time. The serialization
-layer uses this registry to resolve string names back to typed keys — there is no
-explicit seed key list.
+`serializeRuntimeContext(...)` and `deserializeRuntimeContext(...)` only handle
+`RuntimeContextKey`s marked `serializable: true`.
 
-### Derived keys
+That includes seed values such as:
 
-Created by providers during `runStep`. Never serialized — providers reconstruct them each step
-from seed keys and the harness session.
+- auth and initiator auth
+- session id and continuation token
+- run mode
+- parent lineage
+- compiled bundle
+- serialized channel
 
-| Key | Type | Provider |
-|-----|------|----------|
-| `SessionKey` | `Session` | `sessionProvider` |
-| `SandboxKey` | `SandboxAccess` | `sandboxProvider` |
-| `SkillKey` | `SkillAccess` | `skillProvider` |
+Durable authored context is intentionally excluded. `assertNoDurableContextInRuntimeSeed(...)`
+guards against leaking a public `ContextKey` into the runtime seed payload.
 
 ## Providers
 
-Providers implement `ContextProvider<T>`:
-
-```ts
-interface ContextProvider<T> {
-  readonly key: ContextKey<T>;
-  create(ctx: AshContext, session: HarnessSession):
-    ProviderResult<T> | undefined | Promise<ProviderResult<T> | undefined>;
-  commit?(value: T, session: HarnessSession):
-    HarnessSession | Promise<HarnessSession>;
-}
-```
-
-`create` receives the context (with seed keys and earlier providers already set) and the current
-harness session. It returns a `ProviderResult` with the live value and optionally a modified
-session (e.g. skills enriching the system prompt). Returning `undefined` means the provider is not
-active for this step.
-
-`commit` is called after the step completes. It receives the live value (which may have been
-mutated during the step) and the harness session from the step result. It returns an updated
-session with any state changes persisted. Only providers with mutable state need this (sandbox
-snapshots, skill activations).
-
-Provider ordering matters. The framework providers are baked into `runStep` in dependency order:
-
-1. `sessionProvider` — depends only on seed keys
-2. `sandboxProvider` — depends on `BundleKey` and `SessionIdKey`
-3. `skillProvider` — depends on `BundleKey`
-
-There is no separate provider list to import — `runStep` knows its providers internally.
-
-## Step Runner
-
-`runStep` orchestrates the provider lifecycle around a step callback:
-
-1. Iterates providers in order — each may set its key on the context and optionally modify the
-   harness session.
-2. Runs the callback inside `contextStorage.run(ctx, ...)` so authored code can read the context.
-3. After the callback completes, iterates providers again to call `commit` hooks, persisting
-   mutable state back onto the session.
-
-## Serialization At Step Boundaries
-
-`serializeContext` and `deserializeContext` handle durable step boundaries generically.
-`serializeContext` iterates all entries in the context, calling each codec-backed key's codec
-when present. `deserializeContext` iterates the plain JSON record
-and resolves each string name back to its registered `ContextKey` via the global key registry.
-Keys without a codec are stored as-is (they must be JSON-safe).
-
-The workflow runtime serializes the context once at `start()` time. Each `"use step"` boundary
-deserializes it back, then providers reconstruct derived values.
-
-The channel codec is owned by the `ChannelKey` definition in `context/keys.ts`.
-Channel classes themselves have no knowledge of serialization.
-
-## Channel Context
-
-Auth is separate from the channel — it lives on `RunInput.auth` and `DeliverInput.auth`. There is
-no `ContextUpdater` callback, no `withAuth`/`withContext` wrappers, and no deliver-updater-registry
-side-channel.
-
-### Auth
-
-Auth lives on the run and deliver inputs, not on the channel itself:
-
-- `RunInput.auth` — the caller for the current run
-- `RunInput.initiatorAuth` — the caller that started the durable session (defaults to `auth` on root
-  runs; subagent passes the parent's initiator)
-
-The runtime reads `RunInput.auth` and `RunInput.initiatorAuth` when seeding `AuthKey` and
-`InitiatorAuthKey`. On `deliver()`, the runtime updates `AuthKey` from `DeliverInput.auth` so that
-`session.auth.current` reflects the follow-up caller while `session.auth.initiator` stays the same.
-
-### Custom context via `Channel.onDeliver`
-
-Channels set custom context keys inside `onDeliver(ctx, payload)`. The method receives a narrow
-`ContextAccessor` as its first argument (typed `get`/`set` with `ContextKey`) and returns a
-`Promise<StepInput>`. This runs once per turn — both the initial `run()` and each `deliver()` —
-after auth keys are seeded. Channel code stays workflow-agnostic because it only touches the
-accessor.
-
-```ts
-class TenantChannel extends Channel {
-  static readonly kind = "tenant-channel";
-
-  private readonly inner: Channel;
-  private readonly tenantId: string;
-
-  constructor(state: { readonly tenantId: string }) {
-    super();
-    this.tenantId = state.tenantId;
-    this.inner = new HttpChannel();
-  }
-
-  async onEvent(event) {
-    return await this.inner.onEvent(event);
-  }
-
-  async onDeliver(ctx, payload) {
-    ctx.set(TenantKey, this.tenantId);
-    return await this.inner.onDeliver(ctx, payload);
-  }
-
-  serialize() {
-    return { tenantId: this.tenantId };
-  }
-}
-```
-
-### Deliver path
-
-On `deliver()`, the channel is deserialized from the session (it was serialized at `run()` time via
-the `ChannelKey` codec). The runtime applies `DeliverInput.auth` to update the auth key, then calls
-`channel.onDeliver(ctx, payload)` on the deserialized channel. No process-local user registration or
-function stashing is needed because the runtime rebuilds the channel from the compiled bundle's
-channel registry plus the serialized channel state.
+Providers still reconstruct derived runtime values on each step:
 
-### Files
+- `SessionKey` via `sessionProvider`
+- `SandboxKey` via `sandboxProvider`
+- `SkillKey` via `skillProvider`
 
-- `packages/ash/src/channel/types.ts` — `Channel`, `ContextAccessor` types
-- `packages/ash/src/execution/runtime-context.ts` — `buildRunContext` (reads `RunInput.auth`,
-  seeds auth keys)
-- `packages/ash/src/execution/workflow-steps.ts` — deserializes channel, applies deliver auth
-- `packages/ash/src/execution/continuous-entry.ts` — applies deliver auth on in-memory channel
+These are runtime-only values, so they use `RuntimeContextKey`, not public `ContextKey`.
 
-## Integration Points
+Provider-owned mutable state stays separate from authored durable context:
 
-### Runtime entry (workflow)
+- durable authored values live on `session.context`
+- internal framework bookkeeping lives on `session.internal`
+- provider snapshots such as `sandboxState` stay on their dedicated session fields
 
-`workflow-runtime.ts` builds an `AshContextImpl` via `createRootContext` (for `run()`) or
-`createDelegatedChildContext` (for `delegate()`), sets seed keys, serializes, and passes
-`serializedContext` to `workflowEntry` via `start()`. The ambient runtime is registered at
-this point so durable steps can later recover it via `tryGetAmbientWorkflowRuntime()`.
+## Channel Setup
 
-### Runtime entry (continuous)
+`packages/ash/src/execution/step-context.ts` owns the pre-step channel path for both runtimes:
 
-`continuous-runtime.ts` builds an `AshContextImpl` via the same two helpers and passes the
-live context directly to `runStep` (no serialization needed since there are no durable step
-boundaries). `RuntimeKey` is attached to the context once at run creation.
+1. rebuild the fresh step context
+2. hydrate durable context
+3. seed pending input request bookkeeping
+4. apply deliver-time auth
+5. call `channel.onDeliver(ctx, payload)`
+6. assert that serialized channel state did not change
 
-### Delegation
+That ordering matters. `onDeliver(...)` runs after durable context hydration, so channel-seeded
+context cannot be overwritten by later hydration.
 
-`runtime.delegate(input)` starts a child run rooted at a non-root graph node. Its
-`DelegateInput` extends `RunInput` and adds `parent: SessionParent` and
-`target: { selector }`. `createDelegatedChildContext` seeds the child context with the
-forwarded initiator auth, the delegate's current auth, the parent lineage, the child node
-selector, and the child's own run/session identifiers. The subagent tool wrapper in
-`execution/subagent-tool.ts` is the sole in-tree caller of `delegate()`.
+## Channel State Rule
 
-### Durable step boundary
+Serialized channel state is immutable after the run starts.
 
-`workflow-steps.ts` deserializes the context from the serialized record, attaches the ambient
-workflow runtime via `RuntimeKey` (when one is registered), resolves the active graph node
-from `NodeSelectorKey`, and calls `runStep` with the framework providers.
+The runtime snapshots `channel.serialize()` before `onDeliver(...)` and again after step execution.
+If the serialized shape changes, the runtime throws with guidance to move that data into:
 
-### Tool executors
+- durable context when authored code needs it across turns
+- internal `session.internal` when only framework bookkeeping needs it
 
-Tool executors read from the container via `requireContext()`. Sandbox tools read `SandboxKey`;
-the `load_skill` action reads `SkillKey`. Authored tools access context through the public
-accessors (`getSession`, `getSandbox`, etc.).
+This keeps channel responsibilities narrow:
 
-### Public API
+- transport normalization
+- continuation token ownership
+- per-turn context seeding
+- delivery policy
 
-The public accessors in `context/accessors.ts` delegate to `requireContext()`:
+It prevents channels from becoming an untracked second session storage system.
 
-- `getSession()` reads `SessionKey`
-- `getSandbox(name)` reads `SandboxKey`
-- `getSkill(identifier)` reads `SkillKey`
+## Runtime Split
 
-## What Was Removed
+Both runtime flavors now use the same context story:
 
-The unified context replaced these six prior mechanisms:
+- workflow runtime stores runtime seed keys once, then rebuilds a fresh step context on every
+  durable step
+- continuous runtime also rebuilds a fresh step context on every step, even though the process is
+  still live
 
-- `execution/runtime-context.ts` — execution-layer `AsyncLocalStorage` and `RuntimeContext`
-- `runtime/session-context.ts` — runtime-layer `AsyncLocalStorage` and `AuthoredRuntimeContext`
-- `execution/framework-context.ts` — `FrameworkContext`, `Dehydratable`, channel emitter
-  dehydration
-- `execution/context.ts` — `StepExecutionContext`, `ManagedRuntimeContext`, incremental context
-  assembly
-- The `Dehydratable` interface on channel emitters (replaced by key codecs)
-- Separate `session` parameter threading through tool executors and action handlers
+That removes the old semantic split where in-memory runs behaved differently from durable workflow
+runs.

package/docs/public/README.md

@@ -19,21 +19,22 @@ Read in this order:
 2. [project-layout.md](./project-layout.md)
 3. [agent-ts.md](./agent-ts.md)
 4. [typescript-api.md](./typescript-api.md)
-5. [context-control.md](./context-control.md)
-6. [skills.md](./skills.md)
-7. [tools.md](./tools.md)
-8. [workspace.md](./workspace.md)
-9. [sandboxes.md](./sandboxes.md)
-10. [channels/README.md](./channels/README.md)
-11. [human-in-the-loop.md](./human-in-the-loop.md)
-12. [session-context.md](./session-context.md)
-13. [runs-and-streaming.md](./runs-and-streaming.md)
-14. [subagents.md](./subagents.md)
-15. [schedules.md](./schedules.md)
-16. [evals.md](./evals.md)
-17. [auth-and-route-protection.md](./auth-and-route-protection.md)
-18. [vercel-deployment.md](./vercel-deployment.md)
-19. [cli-build-and-debugging.md](./cli-build-and-debugging.md)
+5. [migration-guide.md](./migration-guide.md)
+6. [context-control.md](./context-control.md)
+7. [skills.md](./skills.md)
+8. [tools.md](./tools.md)
+9. [workspace.md](./workspace.md)
+10. [sandboxes.md](./sandboxes.md)
+11. [channels/README.md](./channels/README.md)
+12. [human-in-the-loop.md](./human-in-the-loop.md)
+13. [session-context.md](./session-context.md)
+14. [runs-and-streaming.md](./runs-and-streaming.md)
+15. [subagents.md](./subagents.md)
+16. [schedules.md](./schedules.md)
+17. [evals.md](./evals.md)
+18. [auth-and-route-protection.md](./auth-and-route-protection.md)
+19. [vercel-deployment.md](./vercel-deployment.md)
+20. [cli-build-and-debugging.md](./cli-build-and-debugging.md)
 
 ## The Public Mental Model
 
@@ -56,10 +57,11 @@ Ash then gives you:
 - a stable HTTP message route
 - optional channel webhook routes
 - a reconnectable session stream
-- durable session state across turns
+- durable session context across turns
 - a shared runtime workspace
 - optional isolated sandboxes
-- typed runtime helpers such as `getSession()`, `getSandbox()`, and `getSkill()`
+- typed runtime helpers such as `getSession()`, `getContext()`, `setContext()`, `ensureContext()`,
+  `getSandbox()`, and `getSkill()`
 
 ## The Runtime Shape
 

package/docs/public/channels/README.md

@@ -9,6 +9,7 @@ Channels are the transport layer in Ash's channel-harness-runtime split. A chann
 - deriving or resuming the stable `continuationToken`
 - applying route auth and network policy
 - deciding how runtime events are delivered back to the platform
+- seeding per-turn durable context inside `onDeliver(...)`
 
 The runtime and harness still own the model turn, tool execution, compaction, and session
 persistence.
@@ -86,6 +87,9 @@ Use a custom channel when you want:
 - transport-specific delivery behavior
 - custom request parsing before the runtime turn starts
 
+Channel constructor state is for stable serialized transport identity only. Once a run starts, keep
+that state immutable and move mutable per-session data into durable context or `session.internal`.
+
 ## What To Read Next
 
 - [`../project-layout.md`](../project-layout.md)

package/docs/public/migration-guide.md

@@ -0,0 +1,71 @@
+# Migration Guide
+
+Ash now has one durable authored-context model.
+
+## Breaking Changes
+
+- `getState(key)` is now `getContext(key)`.
+- `setState(key, value)` is now `setContext(key, value)`.
+- `ensureContext(key, valueOrFactory)` replaces `ContextKey({ initial })`.
+- `ContextKeyOptions.initial` was removed.
+- Public `ContextKey` values are session-durable by default.
+- `HarnessSession.state` is now split into `session.context` and internal `session.internal`.
+- Tool compaction hooks no longer return `sessionPatch`. Mutate durable context through `ctx` instead.
+
+## Before
+
+```ts
+import { ContextKey, getState, setState } from "experimental-ash";
+
+const NotesKey = new ContextKey("myapp.notes", {
+  initial: () => ({ notes: [] }),
+});
+
+setState(NotesKey, (current) => ({
+  notes: [...current.notes, "hello"],
+}));
+
+return getState(NotesKey);
+```
+
+## After
+
+```ts
+import { ContextKey, ensureContext, getContext, setContext } from "experimental-ash";
+
+const NotesKey = new ContextKey("myapp.notes");
+
+const current = ensureContext(NotesKey, () => ({ notes: [] }));
+
+setContext(NotesKey, {
+  notes: [...current.notes, "hello"],
+});
+
+return getContext(NotesKey);
+```
+
+## Channel Guidance
+
+- Use `channel.onDeliver(ctx, payload)` to seed or extend durable context on every turn.
+- Treat serialized channel state as immutable after the run starts.
+- Move mutable per-session data into durable context or `session.internal`, not onto the channel instance.
+
+## Compaction Hooks
+
+Before:
+
+```ts
+onCompact() {
+  return {
+    sessionPatch: { state: {} },
+  };
+}
+```
+
+After:
+
+```ts
+onCompact({ ctx }) {
+  ctx.set(NotesKey, { notes: [] });
+}
+```

package/docs/public/session-context.md

@@ -1,8 +1,11 @@
 # Session Context
 
-Ash exposes three runtime helpers for authored code:
+Ash exposes six runtime helpers for authored code:
 
 - `getSession()`
+- `getContext(key)`
+- `setContext(key, value)`
+- `ensureContext(key, valueOrFactory)`
 - `getSandbox(name)`
 - `getSkill(identifier)`
 
@@ -93,6 +96,27 @@ Important behavior:
 
 See [`skills.md`](./skills.md) for the full authoring model.
 
+## Durable Authored Context
+
+`ContextKey` values are session-durable by default. Once authored code sets a key, Ash hydrates it
+from `session.context` before later steps and commits it back after each step.
+
+```ts
+import { ContextKey, ensureContext, getContext, setContext } from "experimental-ash";
+
+const TenantKey = new ContextKey<string>("myapp.tenant");
+const NotesKey = new ContextKey<{ readonly notes: readonly string[] }>("myapp.notes");
+
+const tenant = getContext(TenantKey);
+const notes = ensureContext(NotesKey, () => ({ notes: [] }));
+
+setContext(NotesKey, {
+  notes: [...notes.notes, `Handled tenant ${tenant}`],
+});
+```
+
+Use `ensureContext` when a key needs a default value. `ContextKey({ initial })` no longer exists.
+
 ## Passing Custom Context From a Channel
 
 Channels can inject custom typed context into the agent inside `onDeliver`. This is useful when a
@@ -115,8 +139,9 @@ export const TenantKey = new ContextKey<string>("myapp.tenant");
 ### Setting context from a channel
 
 Wrap an existing channel with `onDeliver` to set custom context keys. The hook receives a narrow
-`ContextAccessor` (typed `get`/`set`) as its first argument and a `DeliverPayload` as the second. It
-runs on both `run()` and `deliver()`.
+`ContextAccessor` (`get`, `tryGet`, `has`, `set`, `ensure`) as its first argument and a
+`DeliverPayload` as the second. It runs on both `run()` and `deliver()`, after Ash has hydrated the
+durable context bag for that turn.
 
 `agent/channels/slack.ts`
 
@@ -143,7 +168,7 @@ class TenantSlackChannel extends SlackChannel<TenantSlackState> {
   }
 
   async onDeliver(ctx, payload) {
-    ctx.set(TenantKey, this.state.tenantId);
+    ctx.set(TenantKey, this.state().tenantId);
     return await super.onDeliver(ctx, payload);
   }
 }
@@ -156,17 +181,20 @@ export default slackRoute({
 Auth lives on `RunInput.auth` and `DeliverInput.auth`, not on the channel object. There is no
 `withAuth` or `withContext` wrapper.
 
+Keep channel constructor state immutable after the run starts. Stable transport identity belongs in
+serialized channel state; mutable per-session data belongs in durable context or `session.internal`.
+
 ### Reading context from a tool
 
 ```ts
-import { getState } from "experimental-ash";
+import { getContext } from "experimental-ash";
 import { defineTool } from "experimental-ash/tools";
 import { TenantKey } from "../channels/keys.js";
 
 export default defineTool({
   description: "Return the active tenant.",
   async execute() {
-    const tenant = getState(TenantKey);
+    const tenant = getContext(TenantKey);
     return { tenant };
   },
 });
@@ -175,8 +203,8 @@ export default defineTool({
 ### Context on deliver
 
 `onDeliver` runs on every turn, including `deliver()` follow-ups. The channel is deserialized from
-the session, so its state (including any custom fields like `tenantId`) is available on follow-up
-turns.
+the session, so its stable serialized state (including custom fields like `tenantId`) is available
+on follow-up turns.
 
 Auth on `deliver()` is also honored — `session.auth.current` reflects the caller of each follow-up
 message, not just the session initiator. Deliver-time auth is passed via `DeliverInput.auth` and the
@@ -201,17 +229,18 @@ explaining the required scope.
 
 ## How It Works
 
-All three accessors read from the same `AshContext` container bound by a single `AsyncLocalStorage`.
-The framework sets up this context before invoking authored code:
+All runtime helpers read from the same `AshContext` container bound by a single
+`AsyncLocalStorage`. The framework sets up this context before invoking authored code:
 
-1. The runtime entry point creates an `AshContext` and populates seed keys (auth, session ID,
-   channel, compiled bundle).
-2. Before each step, providers create derived values (session metadata, sandbox access, skill
-   access) from the seed keys and the harness session.
-3. The step callback runs inside the `AsyncLocalStorage` scope, making the context available to
+1. The runtime entry point creates an `AshContext` and serializes only runtime seed keys such as
+   auth, session id, channel, and compiled bundle.
+2. Before each step, Ash rebuilds a fresh context, hydrates durable authored context from
+   `session.context`, seeds runtime-only bookkeeping, and runs `channel.onDeliver(...)`.
+3. Providers create derived values such as session metadata, sandbox access, and skill access.
+4. The step callback runs inside the `AsyncLocalStorage` scope, making the context available to
    all authored code in the call chain.
-4. After the step, providers with mutable state (sandboxes, skills) commit their changes back onto
-   the session for persistence.
+5. After the step, Ash commits the full durable context bag back to `session.context` and lets
+   mutable providers persist any provider-owned state.
 
 This lifecycle is fully managed by the framework. Authored code only needs to call the public
 accessors.