@inixiative/foundry-core 0.1.0

package/src/context-stack.ts

@@ -0,0 +1,223 @@
+import { ContextLayer, computeHash, type LayerState } from "./context-layer";
+import type { OwnershipScope } from "./scope";
+
+export type LayerFilter = (layer: ContextLayer) => boolean;
+
+/**
+ * Read-only view of a ContextStack for middleware introspection.
+ *
+ * Middleware needs to know what a thread already knows — which layers
+ * are present, what they contain, and whether they're warm — without
+ * being able to mutate the stack. This interface provides exactly that.
+ */
+export interface ContextStackView {
+  /** Check if a specific layer exists and is warm. */
+  hasLayer(id: string): boolean;
+  /** Get a layer's current content (returns empty string if not warm). */
+  getContent(id: string): string;
+  /** Get a layer's current state. */
+  getState(id: string): LayerState | undefined;
+  /** List all layer IDs. */
+  readonly layerIds: readonly string[];
+  /** Estimated total tokens across all warm layers. */
+  readonly estimatedTokens: number;
+}
+
+/** A single block in the assembled prompt output. */
+export interface PromptBlock {
+  readonly role: "system" | "layer" | "content";
+  readonly id?: string;
+  readonly text: string;
+  /**
+   * Explicit injection segment (instructions, domain-knowledge,
+   * thread-knowledge, routing, guard-findings). Decorated blocks declare it;
+   * plain layer blocks leave it unset and are classified by the artifact builder.
+   */
+  readonly segment?: string;
+  /** Who produced this block (a domain, the router, a layer id). */
+  readonly source?: string;
+}
+
+/** Structured prompt assembled from agent prompt + layer prompts + layer content. */
+export interface AssembledContext {
+  readonly blocks: PromptBlock[];
+  /** Convenience: all blocks joined into a single string. */
+  readonly text: string;
+}
+
+export interface ContextSnapshot {
+  readonly hash: string;
+  readonly content: string;
+  readonly layerHashes: Record<string, string>;
+  readonly timestamp: number;
+}
+
+export type LayerAddedCallback = (layer: ContextLayer) => void;
+
+export class ContextStack {
+  private _layers: ContextLayer[] = [];
+  private _onLayerAdded: LayerAddedCallback[] = [];
+
+  constructor(layers?: ContextLayer[]) {
+    if (layers) this._layers = [...layers];
+  }
+
+  // -- Layer management --
+
+  get layers(): ReadonlyArray<ContextLayer> {
+    return this._layers;
+  }
+
+  /**
+   * New stack whose layers are independent clones of this stack's layers, in
+   * order. A scope binds every scope-aware source to the owning thread/project.
+   */
+  clone(scope?: OwnershipScope): ContextStack {
+    return new ContextStack(this._layers.map((layer) => layer.clone(scope)));
+  }
+
+  /** Register a callback for when layers are added (used by CacheLifecycle). */
+  onLayerAdded(cb: LayerAddedCallback): () => void {
+    this._onLayerAdded.push(cb);
+    return () => {
+      const idx = this._onLayerAdded.indexOf(cb);
+      if (idx !== -1) this._onLayerAdded.splice(idx, 1);
+    };
+  }
+
+  addLayer(layer: ContextLayer, position?: number): void {
+    if (position !== undefined) {
+      this._layers.splice(position, 0, layer);
+    } else {
+      this._layers.push(layer);
+    }
+    for (const cb of this._onLayerAdded) cb(layer);
+  }
+
+  removeLayer(id: string): boolean {
+    const idx = this._layers.findIndex((l) => l.id === id);
+    if (idx === -1) return false;
+    this._layers.splice(idx, 1);
+    return true;
+  }
+
+  getLayer(id: string): ContextLayer | undefined {
+    return this._layers.find((l) => l.id === id);
+  }
+
+  reorder(ids: string[]): void {
+    const layerMap = new Map(this._layers.map((l) => [l.id, l]));
+    const ordered: ContextLayer[] = [];
+    const seen = new Set<string>();
+
+    for (const id of ids) {
+      const layer = layerMap.get(id);
+      if (layer) {
+        ordered.push(layer);
+        seen.add(id);
+      }
+    }
+    for (const layer of this._layers) {
+      if (!seen.has(layer.id)) ordered.push(layer);
+    }
+    this._layers = ordered;
+  }
+
+  // -- Warming --
+
+  async warmAll(): Promise<void> {
+    // Check staleness before deciding what to warm
+    for (const l of this._layers) l.checkStaleness();
+    await Promise.all(
+      this._layers.filter((l) => !l.isWarm).map((l) => l.warm())
+    );
+  }
+
+  async refresh(): Promise<void> {
+    for (const l of this._layers) l.checkStaleness();
+    await Promise.all(
+      this._layers.filter((l) => l.isStale).map((l) => l.warm())
+    );
+  }
+
+  // -- Merging --
+
+  merge(filter?: LayerFilter): string {
+    const layers = filter ? this._layers.filter(filter) : this._layers;
+    return layers
+      .filter((l) => l.isWarm && l.content.length > 0)
+      .map((l) => l.content)
+      .join("\n\n");
+  }
+
+  slice(filter: LayerFilter): string {
+    return this.merge(filter);
+  }
+
+  sliceByIds(...ids: string[]): string {
+    const idSet = new Set(ids);
+    return this.merge((l) => idSet.has(l.id));
+  }
+
+  /**
+   * Assemble structured prompt blocks from an optional agent system prompt,
+   * layer prompts, and layer content. Each layer with a prompt gets a
+   * prompt block followed by its content block. Layers without prompts
+   * get just a content block.
+   */
+  assemble(agentPrompt?: string, filter?: LayerFilter): AssembledContext {
+    const blocks: PromptBlock[] = [];
+
+    if (agentPrompt) {
+      blocks.push({ role: "system", text: agentPrompt });
+    }
+
+    const layers = filter ? this._layers.filter(filter) : this._layers;
+
+    for (const layer of layers) {
+      if (!layer.isWarm || layer.content.length === 0) continue;
+
+      if (layer.prompt) {
+        // A layer prompt is always an instruction; it never inherits the content segment.
+        blocks.push({ role: "layer", id: layer.id, text: layer.prompt });
+      }
+      // The content block carries the layer's declared segment when it has one; legacy
+      // layers leave it unset and the artifact builder falls back to its id heuristic.
+      blocks.push({ role: "content", id: layer.id, text: layer.content, ...(layer.segment ? { segment: layer.segment } : {}) });
+    }
+
+    const text = blocks.map((b) => b.text).join("\n\n");
+    return { blocks, text };
+  }
+
+  // -- Snapshots --
+
+  snapshot(): ContextSnapshot {
+    const content = this.merge();
+    const layerHashes: Record<string, string> = {};
+    for (const layer of this._layers) {
+      if (layer.isWarm) {
+        layerHashes[layer.id] = layer.hash;
+      }
+    }
+
+    return {
+      hash: computeHash(content),
+      content,
+      layerHashes,
+      timestamp: Date.now(),
+    };
+  }
+
+  // -- Utilities --
+
+  estimateTokens(): number {
+    return Math.ceil(this.merge().length / 4);
+  }
+
+  invalidateAll(): void {
+    for (const layer of this._layers) {
+      layer.invalidate();
+    }
+  }
+}

package/src/credentials.ts

@@ -0,0 +1,14 @@
+/** Credential references belong in configuration; secrets stay behind the resolver. */
+export type CredentialReference = { type: 'managed'; id: string } | { type: 'kingdom-runtime' };
+
+export interface CredentialScope {
+  service: string;
+  url: string;
+  projectId: string;
+  kastleId?: string;
+}
+
+export interface CredentialResolver {
+  /** Resolve afresh for each request. Reject a reference outside its permitted scope. */
+  resolve(reference: CredentialReference, scope: CredentialScope): Promise<string>;
+}

package/src/decider.ts

@@ -0,0 +1,62 @@
+import { computeHash } from "./context-layer";
+import { BaseAgent, type AgentConfig, type ExecutionResult } from "./base-agent";
+import type { ContextStack, LayerFilter } from "./context-stack";
+import type { ExecuteMeta } from "./executor";
+
+export interface Decision<T = unknown> {
+  readonly value: T;
+  readonly confidence?: number;
+  readonly reasoning?: string;
+}
+
+/**
+ * Decision handlers receive the same dispatch metadata as executors (thread
+ * id, cwd, annotations) so session-aware providers can give each thread's
+ * auxiliary decisions their own identity instead of a shared default session.
+ */
+export type DecideHandler<TPayload, TDecision> = (
+  context: string,
+  payload: TPayload,
+  meta?: ExecuteMeta
+) => Promise<Decision<TDecision>>;
+
+export interface DeciderConfig<TPayload = unknown, TDecision = unknown>
+  extends AgentConfig {
+  handler: DecideHandler<TPayload, TDecision>;
+}
+
+/**
+ * A Decider takes context + payload, makes a decision, and returns
+ * ONLY the decision — not the context it used to make it.
+ *
+ * This is the "trusted authority" pattern. The Decider has rich context
+ * (docs, memory, taxonomy, whatever) but the caller just gets back a
+ * slim decision. The caller trusts the Decider because it had the context.
+ */
+export class Decider<TPayload = unknown, TDecision = unknown> extends BaseAgent<
+  TPayload,
+  Decision<TDecision>
+> {
+  protected _handler: DecideHandler<TPayload, TDecision>;
+
+  constructor(config: DeciderConfig<TPayload, TDecision>) {
+    super(config);
+    this._handler = config.handler;
+  }
+
+  withStack(stack: ContextStack): Decider<TPayload, TDecision> {
+    return new Decider<TPayload, TDecision>({ ...this.agentConfig(stack), handler: this._handler });
+  }
+
+  async run(
+    payload: TPayload,
+    filterOverride?: LayerFilter,
+    meta?: ExecuteMeta
+  ): Promise<ExecutionResult<Decision<TDecision>>> {
+    const context = this.getContextWith(filterOverride);
+    const contextHash = computeHash(context);
+    const decision = await this._handler(context, payload, meta);
+
+    return { output: decision, contextHash };
+  }
+}

package/src/delivery-evidence.ts

@@ -0,0 +1,85 @@
+/** Portable SHA-256 for public evidence, shared by Bun and the historical browser.
+ * This is an integrity join, not a signature or native delivery acknowledgment. */
+export function evidenceDigest(text: string): string {
+  const input = new TextEncoder().encode(text), bytes = new Uint8Array(Math.ceil((input.length + 9) / 64) * 64);
+  bytes.set(input); bytes[input.length] = 128;
+  const view = new DataView(bytes.buffer), bits = input.length * 8;
+  view.setUint32(bytes.length - 8, Math.floor(bits / 4294967296)); view.setUint32(bytes.length - 4, bits >>> 0);
+  const h = [0x6a09e667,0xbb67ae85,0x3c6ef372,0xa54ff53a,0x510e527f,0x9b05688c,0x1f83d9ab,0x5be0cd19];
+  const k = [0x428a2f98,0x71374491,0xb5c0fbcf,0xe9b5dba5,0x3956c25b,0x59f111f1,0x923f82a4,0xab1c5ed5,0xd807aa98,0x12835b01,0x243185be,0x550c7dc3,0x72be5d74,0x80deb1fe,0x9bdc06a7,0xc19bf174,0xe49b69c1,0xefbe4786,0x0fc19dc6,0x240ca1cc,0x2de92c6f,0x4a7484aa,0x5cb0a9dc,0x76f988da,0x983e5152,0xa831c66d,0xb00327c8,0xbf597fc7,0xc6e00bf3,0xd5a79147,0x06ca6351,0x14292967,0x27b70a85,0x2e1b2138,0x4d2c6dfc,0x53380d13,0x650a7354,0x766a0abb,0x81c2c92e,0x92722c85,0xa2bfe8a1,0xa81a664b,0xc24b8b70,0xc76c51a3,0xd192e819,0xd6990624,0xf40e3585,0x106aa070,0x19a4c116,0x1e376c08,0x2748774c,0x34b0bcb5,0x391c0cb3,0x4ed8aa4a,0x5b9cca4f,0x682e6ff3,0x748f82ee,0x78a5636f,0x84c87814,0x8cc70208,0x90befffa,0xa4506ceb,0xbef9a3f7,0xc67178f2];
+  const rr = (v: number, n: number) => (v >>> n) | (v << (32 - n)), w = new Uint32Array(64);
+  for (let offset = 0; offset < bytes.length; offset += 64) {
+    for (let i = 0; i < 16; i++) w[i] = view.getUint32(offset + 4 * i);
+    for (let i = 16; i < 64; i++) { const x=w[i-15]!, y=w[i-2]!; w[i]=w[i-16]!+(rr(x,7)^rr(x,18)^(x>>>3))+w[i-7]!+(rr(y,17)^rr(y,19)^(y>>>10)); }
+    let [a,b,c,d,e,f,g,j] = h as [number,number,number,number,number,number,number,number];
+    for (let i=0;i<64;i++) { const t=(j+(rr(e,6)^rr(e,11)^rr(e,25))+((e&f)^(~e&g))+k[i]!+w[i]!)|0;
+      const u=((rr(a,2)^rr(a,13)^rr(a,22))+((a&b)^(a&c)^(b&c)))|0; j=g;g=f;f=e;e=(d+t)|0;d=c;c=b;b=a;a=(t+u)|0; }
+    [a,b,c,d,e,f,g,j].forEach((v,i)=>{h[i]=(h[i]!+v)>>>0;});
+  }
+  return h.map(v=>v.toString(16).padStart(8,"0")).join("");
+}
+
+export interface DeliveryOwner { threadId: string; messageId: string; projectId?: string }
+export interface ProviderBoundaryReceipt {
+  schema: 1; owner: DeliveryOwner; assemblyHash: string; messagesHash: string;
+  /** Exactly one initial system message starts with the assembled context. */
+  systemMessageIndex: number;
+}
+// Fixed top-level field order over the preserved serialization, never the current cache.
+export function assemblyDigest(i: any): string {
+  return evidenceDigest(JSON.stringify([i.threadId,i.projectId ?? null,i.messageId,i.executorContext,i.userMessage,
+    i.layers,i.blocks,i.decoration]));
+}
+export function boundaryReceipt(i: any, owner: DeliveryOwner): ProviderBoundaryReceipt {
+  const matches = i.providerMessages.flatMap((m: any, n: number) => m.role === "system" && typeof m.content === "string"
+    && typeof i.executorContext === "string" && i.executorContext.length > 0
+    && (m.content === i.executorContext || m.content.startsWith(i.executorContext + "\n\n")) ? [n] : []);
+  return { schema: 1, owner: { ...owner }, assemblyHash: assemblyDigest(i),
+    messagesHash: evidenceDigest(JSON.stringify(i.providerMessages)), systemMessageIndex: matches.length === 1 ? matches[0] : -1 };
+}
+export interface ExpertDeliveryProof {
+  domain: string; layerId: string; assessedRevision: number; deliveredRevision: number;
+  deliveredHash: string; relation: "assessed" | "advanced"; content: string;
+}
+/** One validation contract used by inspection, the runner and the copy-only audit. */
+export function verifyExpertDelivery(i: any, delivery: any, domain: string, expected: DeliveryOwner): ExpertDeliveryProof {
+  const fail = () => { throw Error("Recorded expert delivery invalid"); };
+  const one = (rows: any, predicate: (row: any) => boolean): any => {
+    if (!Array.isArray(rows)) return fail(); const found = rows.filter(predicate); return found.length === 1 ? found[0] : fail();
+  };
+  const owner = (x: any) => x?.threadId === expected.threadId && x?.projectId === expected.projectId;
+  const receipt = i?.providerBoundary;
+  if (!expected.threadId || !expected.messageId || !owner(i) || i.messageId !== expected.messageId
+    || !owner(i.decoration?.input?.currentMessage) || i.decoration.input.currentMessage.messageId !== expected.messageId
+    || receipt?.schema !== 1 || !owner(receipt.owner) || receipt.owner.messageId !== expected.messageId
+    || receipt.assemblyHash !== assemblyDigest(i) || !Array.isArray(i.providerMessages)
+    || receipt.messagesHash !== evidenceDigest(JSON.stringify(i.providerMessages))) fail();
+  const system = i.providerMessages[receipt.systemMessageIndex];
+  if (!Number.isSafeInteger(receipt.systemMessageIndex) || system?.role !== "system" || typeof system.content !== "string"
+    || !i.executorContext || !(system.content === i.executorContext || system.content.startsWith(i.executorContext + "\n\n"))) fail();
+  const p = one(i.decoration?.participants, p => p?.id === domain), id = `thread-knowledge:${domain}`;
+  const e = one(delivery?.layers, e => e?.id === id), l = one(i.layers, l => l?.id === id);
+  if (new Set(delivery.layers.map((row: any) => row?.id)).size !== delivery.layers.length) fail();
+  for (const row of delivery.layers.filter((x: any) => x?.domain === domain && x.id !== id)) {
+    const cache = one(i.layers, l => l?.id === row.id);
+    if (!owner(cache) || !owner(row) || cache.included !== true || row.assessedRevision !== undefined
+      || row.relation !== undefined || row.assessedHash !== p.provenance?.cacheHash
+      || row.deliveredHash !== cache.hash || row.drift !== (row.assessedHash !== row.deliveredHash)) fail();
+  }
+  if (delivery.layers.filter((e: any) => e?.domain === domain && e?.assessedRevision !== undefined).length !== 1) fail();
+  const v=l.version, ar=p.provenance?.threadKnowledgeRevision, ah=p.provenance?.threadKnowledgeHash, r=e.deliveredRevision;
+  if (!owner(l) || l.included !== true || l.segment !== "thread-knowledge" || l.definitionId !== id
+    || !owner(v) || v?.domain !== domain || e.domain !== domain || !owner(e)
+    || !Number.isSafeInteger(ar) || ar < 0 || !Number.isSafeInteger(r) || r < 0
+    || e.assessedRevision !== ar || e.assessedHash !== ah || typeof ah !== "string"
+    || typeof p.segments?.threadKnowledge !== "string" || typeof l.content !== "string"
+    || e.deliveredHash !== l.hash || v.hash !== l.hash || v.revision !== r
+    || e.drift !== (e.assessedHash !== e.deliveredHash)
+    || (e.relation === "assessed" ? r !== ar || ah !== l.hash : e.relation === "advanced" ? r <= ar : true)) fail();
+  const b = one(i.blocks, b => b?.source === id && b.kind === "thread-knowledge");
+  if (b.text !== l.content || b.hash !== l.hash || b.id !== `thread-knowledge:${id}:${l.hash}`) fail();
+  // Intended assembled block, not a matching quotation in the user message.
+  const body = i.blocks.map((b: any) => b.text).join("\n\n");
+  if (body !== i.executorContext) fail();
+  return { domain, layerId:id, assessedRevision:ar, deliveredRevision:r, deliveredHash:l.hash, relation:e.relation, content:l.content };
+}

package/src/event-stream.ts

@@ -0,0 +1,105 @@
+import type { LifecycleEvent } from "./cache-lifecycle";
+import type { Dispatch } from "./thread";
+import type { Signal } from "./signal";
+import type { DispatchContext } from "./middleware";
+import type { ActionPrompt } from "./action-prompt";
+
+/** Session lifecycle events (minimal type for event stream). */
+export interface SessionEvent {
+  readonly type: "thread:added" | "thread:removed" | "thread:spawned";
+  readonly threadId: string;
+  readonly parentId?: string;
+  readonly timestamp: number;
+}
+
+/**
+ * Every observable event in the system, tagged by origin.
+ */
+export type StreamEvent =
+  | { kind: "journal"; threadId: string; turnId: string | null; projectId?: string; timestamp: number; scope?: "phase" | "learning"; outcome?: "durable" | "failed" }
+  | { kind: "layer"; threadId: string; event: LifecycleEvent }
+  | { kind: "dispatch"; threadId: string; dispatch: Dispatch }
+  | { kind: "signal"; threadId: string; signal: Signal }
+  | { kind: "prompt"; threadId: string; prompt: ActionPrompt }
+  | { kind: "session"; event: SessionEvent }
+  | { kind: "middleware"; threadId: string; phase: "before" | "after"; context: DispatchContext }
+  | { kind: "error"; source: string; message: string; severity: "error" | "warn"; timestamp: number };
+
+/**
+ * Unified event stream across all threads and sessions.
+ *
+ * The UI subscribes to this — it's the single source of truth for
+ * what's happening in the system. Every layer state change, every dispatch,
+ * every signal, every thread spawn shows up here in order.
+ *
+ * Supports both push (subscribe) and pull (recent history) access patterns.
+ */
+export class EventStream {
+  private _listeners: Array<(event: StreamEvent) => void> = [];
+  private _history: StreamEvent[] = [];
+  private _maxHistory: number;
+
+  constructor(maxHistory: number = 5000) {
+    this._maxHistory = maxHistory;
+  }
+
+  /** Push an event into the stream. */
+  push(event: StreamEvent): void {
+    this._history.push(event);
+    if (this._history.length > this._maxHistory) {
+      this._history.shift();
+    }
+
+    // Snapshot to avoid mutation during iteration (listener may unsubscribe)
+    const listeners = [...this._listeners];
+    for (const listener of listeners) {
+      try {
+        listener(event);
+      } catch (err) {
+        console.warn("[EventStream] listener error:", (err as Error).message ?? err);
+      }
+    }
+  }
+
+  /** Subscribe to all events. Returns unsubscribe function. */
+  subscribe(listener: (event: StreamEvent) => void): () => void {
+    this._listeners.push(listener);
+    return () => {
+      const idx = this._listeners.indexOf(listener);
+      if (idx !== -1) this._listeners.splice(idx, 1);
+    };
+  }
+
+  /** Get recent events, optionally filtered by kind and/or thread. */
+  recent(opts?: {
+    kind?: StreamEvent["kind"];
+    threadId?: string;
+    limit?: number;
+  }): ReadonlyArray<StreamEvent> {
+    let events: StreamEvent[] = this._history;
+
+    if (opts?.kind) {
+      events = events.filter((e) => e.kind === opts.kind);
+    }
+
+    if (opts?.threadId) {
+      events = events.filter((e) => {
+        if (e.kind === "session") return true; // session events are global
+        return "threadId" in e && e.threadId === opts.threadId;
+      });
+    }
+
+    const limit = opts?.limit ?? 100;
+    return events.slice(-limit);
+  }
+
+  /** Push an error event — surfaced as a toast in the viewer UI. */
+  pushError(source: string, message: string, severity: "error" | "warn" = "error"): void {
+    this.push({ kind: "error", source, message, severity, timestamp: Date.now() });
+  }
+
+  /** Clear history. */
+  clear(): void {
+    this._history = [];
+  }
+}

package/src/executor.ts

@@ -0,0 +1,185 @@
+import { computeHash, REQUIRED_CONTEXT_BLOCKED } from "./context-layer";
+import { BaseAgent, type AgentConfig, type ExecutionResult } from "./base-agent";
+import type { AssembledContext, ContextStack, LayerFilter } from "./context-stack";
+import { buildInjectionArtifact, type InjectionArtifact, type MessageDecoration } from "./messages";
+import type { LLMMessage } from "./types";
+import type { ToolCallObservation } from "./tools";
+import type { NativeEvidence, NativeObservation } from "./native-evidence";
+
+/** Runtime metadata passed to executor handlers at dispatch time. */
+export interface ExecuteMeta {
+  nativeObservation?: NativeObservation;
+  recordNative?: (evidence: NativeEvidence) => void;
+  recordCompleted?: (output: unknown) => void;
+  /** Working directory for this dispatch (from the thread's worktree). */
+  cwd?: string;
+  /** Thread ID that dispatched this execution. */
+  threadId?: string;
+  /** Project that owns the dispatching thread. Scopes memory tool reads. */
+  projectId?: string;
+  /** Logical message identity, not a native session or dispatch ID. */
+  messageId?: string;
+  /** Identity of this dispatch. Every tool the handler executes is attributed to it. */
+  dispatchId?: string;
+  /**
+   * Report one executed tool call. The thread turns it into a
+   * `tool_observation` signal carrying the dispatch identity, so evidence
+   * is correlated to this work and never to whichever turn finishes next.
+   */
+  observeTool?: (observation: ToolCallObservation) => void;
+  /** Arbitrary annotations from middleware. */
+  annotations?: Record<string, unknown>;
+  /**
+   * Streaming sink — when provided, the executor should emit text deltas
+   * here as they arrive. Accumulates upstream into a StreamBuffer.
+   * Absent ⇒ non-streaming (complete → full result) semantics.
+   */
+  onDelta?: (text: string) => void;
+  /** Record the initial messages at the provider boundary for inspection. */
+  recordProviderInput?: (messages: LLMMessage[]) => void;
+  /** Capture prepared input even on failure; this is not delivery acknowledgment. */
+  recordInjection?: (artifact: InjectionArtifact) => void;
+}
+
+export type ExecuteHandler<TPayload, TResult> = (
+  context: string,
+  payload: TPayload,
+  meta?: ExecuteMeta
+) => Promise<TResult>;
+
+export interface ExecutorConfig<TPayload = unknown, TResult = unknown>
+  extends AgentConfig {
+  handler: ExecuteHandler<TPayload, TResult>;
+}
+
+/**
+ * An Executor takes context + payload, goes and does work, returns full results.
+ */
+export class Executor<TPayload = unknown, TResult = unknown> extends BaseAgent<
+  TPayload,
+  TResult
+> {
+  private _handler: ExecuteHandler<TPayload, TResult>;
+
+  constructor(config: ExecutorConfig<TPayload, TResult>) {
+    super(config);
+    this._handler = config.handler;
+  }
+
+  withStack(stack: ContextStack): Executor<TPayload, TResult> {
+    return new Executor<TPayload, TResult>({ ...this.agentConfig(stack), handler: this._handler });
+  }
+
+  async run(
+    payload: TPayload,
+    filterOverride?: LayerFilter,
+    meta?: ExecuteMeta
+  ): Promise<ExecutionResult<TResult>> {
+    // Decoration composed by pre-message middleware (parallel domain advice)
+    // rides in on annotations and is appended after the assembled layers, so
+    // the executor's context, the provider input and the artifact agree.
+    const decoration = meta?.annotations?.decoration as MessageDecoration | undefined;
+    const plan = meta?.annotations?.injectionPlan;
+    const base = this.assembleContext(filterOverride);
+    const blocks = decoration?.blocks.length ? [...base.blocks, ...decoration.blocks] : base.blocks;
+    const assembled: AssembledContext = decoration?.blocks.length
+      ? { blocks, text: blocks.map((block) => block.text).join("\n\n") }
+      : base;
+    const context = assembled.text;
+    const contextHash = computeHash(context);
+    const capturedAt = Date.now();
+    const included = new Set(assembled.blocks.map(block => block.id));
+    const layers = this._stack.layers.map(layer => ({
+      ...layer.snapshotInstance(meta?.threadId),
+      id: layer.id,
+      prompt: layer.prompt,
+      sourceIds: layer.sources.map(source => source.id),
+      included: included.has(layer.id),
+    }));
+    const userMessage = typeof payload === "string" ? payload : JSON.stringify(payload);
+    const injection = buildInjectionArtifact({
+      userMessage,
+      assembled: base,
+      decoration,
+      layerFreshness: Object.fromEntries(layers.map(layer => [layer.id, {
+        state: layer.state, lastWarmed: layer.lastWarmed,
+      }])),
+    });
+    let providerMessages: LLMMessage[] | undefined;
+    let providerBoundary: ProviderBoundaryReceipt | undefined;
+    const capture = (): InjectionArtifact => ({ ...injection, capturedAt, threadId: meta?.threadId,
+      projectId: meta?.projectId, messageId: meta?.messageId, providerBoundary,
+      executorContext: context, providerMessages, layers,
+      ...(plan !== undefined ? { plan } : {}) });
+    const observe = (callback: () => void) => {
+      try { callback(); }
+      catch (error) { console.warn("[Executor] input evidence observer failed:", error); }
+    };
+    const record = () => observe(() => meta?.recordInjection?.(structuredClone(capture())));
+    // These are in-memory preparation observations, not durable writes or
+    // acknowledgment by a provider. A process crash can still lose them.
+    record();
+    // Shared layers may finish a coalesced load for a later request. Preserve
+    // the actual prepared evidence above, but never send it as this request's
+    // selection. No retry/replay is implied by refusing this provider call.
+    const mismatched = layers.filter(layer => {
+      if (!layer.included || !layer.selection) return false;
+      const selectedFor = layer.selection.currentMessage;
+      // Standalone legacy sources have no request-identity contract. A flow
+      // plan does: even its unidentified loads must not replace identified work.
+      if (!selectedFor && plan === undefined) return false;
+      const expectedId = meta?.messageId && meta.threadId ? meta.messageId : undefined;
+      return selectedFor?.messageId !== expectedId || (selectedFor !== undefined &&
+        (selectedFor.threadId !== meta?.threadId || selectedFor.projectId !== meta?.projectId));
+    });
+    if (mismatched.length) {
+      throw new Error(`Memory selection changed before provider execution: logical message ownership differs for layer(s) ${mismatched.map(l => l.id).join(", ")}`);
+    }
+    // A selecting source that could not carry required context is a reason to
+    // stop, not a note for the model. Refuse before any provider call; the
+    // recorded artifact above keeps the conflict and record ids inspectable.
+    const blocked = layers.filter(layer => layer.included).flatMap(layer => (layer.selection?.sources ?? []).flatMap(source =>
+      source.report.conflicts.filter(conflict => conflict.kind === REQUIRED_CONTEXT_BLOCKED)
+        .map(conflict => `layer ${layer.id}, source ${source.sourceId}: ${conflict.ids.join(", ")}`)));
+    if (blocked.length) {
+      throw new Error(`Required memory context blocked before provider execution: pinned records exceed the selection cap and no scoped retrieval is available (${blocked.join("; ")})`);
+    }
+    let output: TResult;
+    let native: NativeEvidence | undefined;
+    let recording = true;
+    try {
+      output = await this._handler(context, payload, {
+        ...meta,
+        recordNative: evidence => { if (recording) { native = evidence; observe(() => meta?.recordNative?.(evidence)); } },
+        recordProviderInput: messages => {
+          // The initial boundary input must not be replaced by tool followups.
+          if (providerMessages === undefined) {
+            providerMessages = structuredClone(messages);
+            if (meta?.threadId && meta.messageId) providerBoundary = boundaryReceipt(capture(), {
+              threadId: meta.threadId, messageId: meta.messageId, ...(meta.projectId ? { projectId: meta.projectId } : {}),
+            });
+          }
+          record();
+          observe(() => meta?.recordProviderInput?.(structuredClone(messages)));
+        },
+      });
+    } finally {
+      recording = false;
+      // The handler can throw a frozen error or a primitive. Observe evidence
+      // independently rather than modifying the thrown value or inventing output.
+      record();
+    }
+
+    observe(() => meta?.recordCompleted?.(structuredClone(output)));
+
+    return {
+      output,
+      contextHash,
+      meta: {
+        ...(native ? { native } : {}),
+        injection: capture(),
+      },
+    };
+  }
+}
+import { boundaryReceipt, type ProviderBoundaryReceipt } from "./delivery-evidence";