@relayflows/sdk 2.0.8 → 2.0.10

package/src/authored-flow-loader.ts

@@ -1,6 +1,6 @@
-import { accessSync, constants } from 'node:fs';
+import { accessSync, constants, realpathSync } from 'node:fs';
 import { createRequire } from 'node:module';
-import { resolve } from 'node:path';
+import { dirname, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import {
   getAuthoredFlowDefinition,
@@ -9,7 +9,7 @@ import {
 } from './authored-flow.js';
 
 export class AuthoredFlowLoadError extends Error {
-  constructor(message: string) {
+  constructor(message: string, readonly kind: 'invalid_spec' | 'use_not_found' | 'use_invalid' | 'use_cycle' = 'invalid_spec') {
     super(message);
     this.name = 'AuthoredFlowLoadError';
   }
@@ -28,10 +28,67 @@ export interface LoadedAuthoredFlow {
    * `getAuthoredFlowDefinition` import.
    */
   readonly getDefinition: GetFlowDefinition;
+  /** Dependency-first load order, each canonical absolute path appearing once. */
+  readonly graph: readonly LoadedAuthoredFlowNode[];
+}
+
+export interface LoadedAuthoredFlowNode {
+  readonly path: string;
+  readonly handle: FlowHandle;
+  readonly getDefinition: GetFlowDefinition;
+  readonly use: readonly string[];
 }
 
 /** Import and validate a direct-run module without executing its authored body. */
 export async function loadAuthoredFlow(path: string): Promise<LoadedAuthoredFlow> {
+  const loaded = new Map<string, LoadedAuthoredFlowNode>();
+  const visiting = new Set<string>();
+  async function visit(sourcePath: string, isRoot = false): Promise<LoadedAuthoredFlowNode> {
+    let absolutePath: string;
+    try {
+      absolutePath = realpathSync(sourcePath);
+      accessSync(absolutePath, constants.R_OK);
+    } catch {
+      throw new AuthoredFlowLoadError(`Flow "${sourcePath}" is not readable.`, isRoot ? 'invalid_spec' : 'use_not_found');
+    }
+    if (visiting.has(absolutePath)) {
+      throw new AuthoredFlowLoadError(`Flow use cycle: ${[...visiting, absolutePath].join(' -> ')}`, 'use_cycle');
+    }
+    const cached = loaded.get(absolutePath);
+    if (cached !== undefined) return cached;
+    visiting.add(absolutePath);
+    try {
+      const { handle, getDefinition } = await importAuthoredFlow(absolutePath);
+      const dependencies: string[] = [];
+      for (const entry of getDefinition(handle).header.use ?? []) {
+        // Validate again at the SDK boundary: the author's surface package may
+        // be a different version from the runtime loading the graph.
+        if (!/^(?:\.\/|\.\.\/).+\.flow\.ts$/.test(entry) || /[?#\\\\]/.test(entry)) {
+          throw new AuthoredFlowLoadError(`Flow "${absolutePath}" use must contain relative .flow.ts paths.`, 'use_invalid');
+        }
+        const child = await visit(resolve(dirname(absolutePath), entry));
+        if (dependencies.includes(child.path)) {
+          throw new AuthoredFlowLoadError(`Flow "${absolutePath}" declares the same use path more than once.`, 'use_invalid');
+        }
+        dependencies.push(child.path);
+      }
+      const node = Object.freeze({ path: absolutePath, handle, getDefinition, use: Object.freeze(dependencies) });
+      loaded.set(absolutePath, node);
+      return node;
+    } catch (error) {
+      if (error instanceof AuthoredFlowLoadError && error.kind === 'invalid_spec' && !isRoot) {
+        throw new AuthoredFlowLoadError(error.message, 'use_invalid');
+      }
+      throw error;
+    } finally {
+      visiting.delete(absolutePath);
+    }
+  }
+  const root = await visit(resolve(path), true);
+  return Object.freeze({ handle: root.handle, getDefinition: root.getDefinition, graph: Object.freeze([...loaded.values()]) });
+}
+
+async function importAuthoredFlow(path: string): Promise<Pick<LoadedAuthoredFlow, 'handle' | 'getDefinition'>> {
   const absolutePath = resolve(path);
   try {
     accessSync(absolutePath, constants.R_OK);

package/src/authored-flow-operation.ts

@@ -1,17 +1,36 @@
 import { executionAsyncId } from 'node:async_hooks';
-import type { Step } from '@relayflows/surface';
+import type { NamedGate, Step } from '@relayflows/surface';
 import { AuthoredFlowExecutionError } from './authored-flow-error.js';
 import {
   AuthoredFlowLifecycle,
   type AuthoredOperationInvocation,
 } from './authored-flow-lifecycle.js';
 
+/** Slice-P kinds the surface `.gate(config)` accepts and the SDK lowers. */
+const NAMED_GATE_KINDS = new Set([
+  'references_input', 'subprocess_gate', 'word_count_bounds', 'regex_match',
+]);
+
+function isNamedGateConfig(candidate: unknown): candidate is NamedGate {
+  return typeof candidate === 'object' && candidate !== null && !Array.isArray(candidate)
+    && typeof (candidate as { type?: unknown }).type === 'string'
+    && NAMED_GATE_KINDS.has((candidate as { type: string }).type);
+}
+
 type OperationState = 'created' | 'running' | 'fulfilled' | 'rejected';
 const nativePromiseThen = Promise.prototype.then;
 
 /** A root authored operation whose outcome cannot be hidden by promise handlers. */
 export class AuthoredFlowOperation<T> {
   readonly step: Step<T>;
+  /**
+   * Named-gate config attached via `.gate({type: '…', …})`. The start closure
+   * reads this at spec-build time and injects it into the compiled StepSpec's
+   * `verification:` field — journal-honest via slice P's named-gate lowering.
+   * Undefined means no postfix gate (default behavior). Predicate `.gate(fn)`
+   * still throws `unsupported_gate` and never sets this field.
+   */
+  namedGate: NamedGate | undefined = undefined;
   private state: OperationState = 'created';
   private thenInvoked = false;
   private rootFailureRecorded = false;
@@ -40,11 +59,21 @@ export class AuthoredFlowOperation<T> {
 
     observeRejection(this.promise, (error) => this.recordRootFailure(error));
     const operation = this;
-    this.step = Object.freeze({
-      gate(): never {
+    const step: Step<T> = {
+      gate(configOrPredicate: NamedGate | ((value: T) => boolean), _because?: string): Step<T> {
+        if (isNamedGateConfig(configOrPredicate)) {
+          // Config-object gate: lowers into the compiled StepSpec's
+          // `verification:` field via slice-P named-gate lowering.
+          operation.namedGate = configOrPredicate;
+          return step;
+        }
+        // Predicate gate: closures cannot be journaled (covenant 1
+        // journal-as-truth). Refuse — authors should use a config-object
+        // gate or the declarative `verification:` block.
         throw new AuthoredFlowExecutionError(
           'unsupported_gate',
-          'postfix gates are not lowered by the initial authored executor',
+          'postfix .gate(predicate) closures cannot be journaled; '
+            + 'use .gate({type: "…", …}) with a slice-P named gate instead.',
         );
       },
       then<TResult1 = T, TResult2 = never>(
@@ -64,7 +93,11 @@ export class AuthoredFlowOperation<T> {
           (error) => operation.recordCallbackFailure(error),
         );
       },
-    });
+    };
+    // Freeze the `then`/`gate` method table so the surface's Step contract
+    // stays intact, but keep `namedGate` reachable via the enclosing
+    // operation reference (not through the surface Step handle).
+    this.step = Object.freeze(step);
     this.scope.registerStep(this.step, this);
   }
 

package/src/authored-helper-effect.ts

@@ -0,0 +1,143 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { JournalClient } from './journal-client.js';
+import { AuthoredFlowExecutionError, type AuthoredFlowExecutionErrorCode } from './authored-flow-error.js';
+import { readCompletedStepOutput } from './authored-step-output.js';
+import type { AuthoredFlowJournalStep } from './authored-flow-executor.js';
+import { compileSpec, toKernelSpec } from './compile.js';
+import { SPEC_SCHEMA_VERSION, type KernelAgentStep } from './spec.js';
+import type { StepDispatchEvent } from './protocol.js';
+import { withWorkerLease } from './worker-lease.js';
+import { helperProviders, type HelperCall } from '@relayflows/surface/runtime';
+import { helperWriteback, HelperDeliveryError } from './helper-writeback.js';
+import { checkSlackHelpers } from './slack-preflight.js';
+import { atomicJson, readSlackReceipt, receiptPath, slackWriteback, type SlackCall } from './slack-writeback.js';
+
+type ProviderCall = HelperCall | SlackCall;
+
+export function assertHelperCredentials(provider: string): void {
+  const namespace = helperProviders.find(p => p.provider === provider)?.namespace;
+  if (!namespace) throw new AuthoredFlowExecutionError('helper_provider.unsupported', `Unknown helper ${provider}`);
+  const report = checkSlackHelpers({ header: { tools: { [namespace]: true } }, body() {} });
+  if (!report.ok) {
+    const diagnostic = report.diagnostics[0]!;
+    throw new AuthoredFlowExecutionError(
+      diagnostic.kind as AuthoredFlowExecutionErrorCode, diagnostic.message);
+  }
+}
+
+/** Each helper uses the existing agent lease + effect protocol; no new kernel verb. */
+export async function runHelperEffect(
+  journal: JournalClient, name: string, stepId: string, call: ProviderCall,
+  dataDir: string, journalSteps: AuthoredFlowJournalStep[],
+): Promise<unknown> {
+  assertHelperCredentials(call.provider);
+  if (call.provider === 'notion' && call.verb === 'appendBlock' && process.env.RELAYFLOWS_NOTION_MOCK !== '1') {
+    throw new AuthoredFlowExecutionError('helper_provider.unsupported', 'Notion appendBlock has no upstream mount writeback route');
+  }
+  const stream = `${call.provider}-helper-${randomUUID()}`;
+  const spec = toKernelSpec(compileSpec({
+    version: SPEC_SCHEMA_VERSION, name: `${name}/${stepId}`,
+    steps: [{ id: stepId, type: 'agent', instruction: JSON.stringify(call),
+      maxIterations: 3, recoveryMode: 'reset',
+      surfaces: { streams: [{ stream }], external: [`/${call.provider}`] } }],
+  }));
+  const outcome = await journal.runStart(spec);
+  await atomicJson(join(dataDir, 'helper-runs', `${outcome.run_id}.json`), { provider: call.provider });
+  await driveHelperEffect(journal, outcome.run_id, spec.steps[0] as KernelAgentStep, call, dataDir);
+  const output = await readCompletedStepOutput(journal, outcome.run_id, stepId, journalSteps);
+  return (output as { receipt: unknown }).receipt;
+}
+
+/** Recognize only the journaled helper envelope, so ordinary agent runs keep their worker path. */
+export async function resumeHelperEffect(journal: JournalClient, runId: string, dataDir: string): Promise<boolean> {
+  if (!/^[A-Za-z0-9_-]+$/.test(runId) || !existsSync(join(dataDir, 'helper-runs', `${runId}.json`))) return false;
+  const entries = (await journal.journalRead(runId, 1)).entries as Array<{
+    entry_type: string; payload: { spec?: { steps?: KernelAgentStep[] } };
+  }>;
+  const steps = entries.find(entry => entry.entry_type === 'run.spawned')?.payload.spec?.steps;
+  if (steps?.length !== 1) return false;
+  const step = steps[0]!;
+  if (step.type !== 'agent' || !step.surfaces?.streams?.[0]?.stream.includes('-helper-')) return false;
+  const call = JSON.parse(step.instruction) as ProviderCall;
+  if (call.type !== 'effect' || !helperProviders.some(p => p.provider === call.provider && p.supported)) return false;
+  const snapshot = await journal.runGet(runId);
+  if (snapshot.status === 'completed' || snapshot.status === 'failed') return true;
+  assertHelperCredentials(call.provider);
+  await driveHelperEffect(journal, runId, step, call, dataDir);
+  return true;
+}
+
+async function driveHelperEffect(
+  journal: JournalClient, runId: string, step: KernelAgentStep, call: ProviderCall, dataDir: string,
+): Promise<void> {
+  const client = new JournalClient(journal.socketPath);
+  const stream = step.surfaces!.streams![0]!.stream;
+  const pins = { workspace: [], streams: [{ stream, read_offset: 0 }] };
+  let resolve!: () => void;
+  let reject!: (error: unknown) => void;
+  const completed = new Promise<void>((yes, no) => { resolve = yes; reject = no; });
+  // Observe early dispatch failures even while attach/run.resume is still pending.
+  void completed.catch(() => undefined);
+  let executing = false;
+  client.on('step.dispatch', (dispatch: StepDispatchEvent) => {
+    if (executing || dispatch.run_id !== runId || dispatch.step_id !== step.id) return;
+    executing = true;
+    void completeHelperDispatch(client, dispatch, call, dataDir).then(resolve, reject);
+  });
+  client.on('error', reject);
+  try {
+    await client.connect();
+    await client.hello('flows-provider-helper');
+    await client.workerAttach(`${call.provider}-${randomUUID()}`, ['agent'], pins, 1);
+    const outcome = await journal.runResume(runId);
+    if (outcome.status === 'completed') return;
+    if (outcome.status === 'failed') {
+      throw new AuthoredFlowExecutionError('step_failed', `Helper run ${runId} ${outcome.status}`, undefined, runId);
+    }
+    await completed;
+  } catch (error) {
+    if (error instanceof AuthoredFlowExecutionError) throw error;
+    throw new AuthoredFlowExecutionError('step_failed', error instanceof Error ? error.message : 'Helper effect failed', 'worker_error', runId);
+  } finally { client.close(); }
+}
+
+async function completeHelperDispatch(client: JournalClient, dispatch: StepDispatchEvent, call: ProviderCall, dataDir: string): Promise<void> {
+  let output: unknown;
+  try {
+    output = await withWorkerLease(client, dispatch, async signal => {
+      const file = receiptPath(dataDir, dispatch.run_id, dispatch.step_id);
+      let receipt: unknown;
+      await client.performEffect({
+        runId: dispatch.run_id, stepId: dispatch.step_id, attempt: dispatch.attempt,
+        idempotencyKey: dispatch.idempotency_key, surfacePath: `/${call.provider}`,
+        revisionBefore: 'pending', revisionAfter: `${dispatch.run_id}:${dispatch.step_id}`,
+      }, async () => {
+        try { receipt = await readSlackReceipt(file); }
+        catch (error) {
+          if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+          receipt = await (call.provider === 'slack' && 'params' in call
+            ? slackWriteback(call, dataDir, dispatch.run_id, dispatch.step_id, signal)
+            : helperWriteback(call as HelperCall, dataDir, dispatch.run_id, dispatch.step_id, signal));
+          await atomicJson(file, receipt);
+        }
+        signal.throwIfAborted();
+      });
+      // Also required after a confirmed election followed by a crash before step.complete.
+      if (receipt === undefined) receipt = await readSlackReceipt(file);
+      return { ...call, idempotencyKey: `${dispatch.run_id}:${dispatch.step_id}`, receipt };
+    });
+  } catch (error) {
+    if (!(error instanceof HelperDeliveryError)) throw error;
+    await client.stepComplete(dispatch.run_id, dispatch.step_id, dispatch.attempt,
+      dispatch.idempotency_key, 'worker_error', {
+        output: { ...call, diagnostic: error.message },
+        started_pins: dispatch.pins, end_pins: dispatch.pins, effects: [],
+      });
+    return;
+  }
+  await client.stepComplete(dispatch.run_id, dispatch.step_id, dispatch.attempt,
+    dispatch.idempotency_key, 'success', { output, started_pins: dispatch.pins, end_pins: dispatch.pins,
+      effects: [{ surface_path: `/${call.provider}`, idempotency_key: dispatch.idempotency_key }] });
+}

package/src/authored-mcp.ts

@@ -0,0 +1,166 @@
+import { createHash, randomUUID } from 'node:crypto';
+import type { Ctx, Step } from '@relayflows/surface';
+import { compileSpec, toKernelSpec } from './compile.js';
+import { snapshotJsonValue } from './json-value.js';
+import { McpError, openMcpSession } from './mcp-client.js';
+import type { McpServerConfig } from './spec.js';
+import { SPEC_SCHEMA_VERSION } from './spec.js';
+import type { JournalClient } from './journal-client.js';
+import type { StepDispatchEvent } from './protocol.js';
+import { AuthoredFlowExecutionError } from './authored-flow-error.js';
+import type { AuthoredFlowJournalStep } from './authored-flow-executor.js';
+import { readCompletedStepOutput } from './authored-step-output.js';
+import { withWorkerLease } from './worker-lease.js';
+
+/** Own keys expose precisely the preflight inventory, including prototype-like names. */
+export function buildMcpProxy(
+  inventory: Readonly<Record<string, readonly string[]>>,
+  invoke: (server: string, tool: string, args: unknown, known: boolean) => Step<unknown>,
+): Ctx['mcp'] {
+  const servers: Record<string, Record<string, (args: unknown) => Step<unknown>>> = Object.create(null);
+  for (const [server, names] of Object.entries(inventory)) {
+    const tools: Record<string, (args: unknown) => Step<unknown>> = Object.create(null);
+    const call = (tool: string, known: boolean) => (args: unknown) =>
+      invoke(server, tool, snapshotJsonValue(args, `f.mcp.${server}.${tool} arguments`), known);
+    for (const tool of names) tools[tool] = call(tool, true);
+    servers[server] = new Proxy(Object.freeze(tools), {
+      get(target, key) {
+        if (typeof key !== 'string') return undefined;
+        if (Object.hasOwn(target, key)) return target[key];
+        // Calling a tool outside the inventory still creates an operation,
+        // so worker_error is journaled like other runtime failures.
+        return call(key, false);
+      },
+    });
+  }
+  return Object.freeze(servers);
+}
+
+export class McpStepError extends AuthoredFlowExecutionError {
+  constructor(readonly diagnostic: string, runId: string) {
+    super('step_failed', diagnostic, 'worker_error', runId);
+  }
+}
+
+/** Helpers lower to an existing agent effect, never a fourth kernel primitive.
+ * The MCP receipt lives in step.completed.output: { type, input, output, ... }.
+ * A private stream routes the step to this short-lived SDK worker exclusively.
+ */
+export async function runMcpEffect(
+  journal: JournalClient, flowName: string, id: string, server: string, tool: string,
+  args: unknown, known: boolean, config: McpServerConfig,
+  journalSteps: AuthoredFlowJournalStep[],
+): Promise<unknown> {
+  const idempotencyKey = `mcp:${server}:${tool}:${createHash('sha256').update(JSON.stringify(args)).digest('hex')}`;
+  const surfacePath = `/mcp/${pathPart(server)}/${pathPart(tool)}`;
+  const stream = `mcp-worker-${randomUUID()}`;
+  const instruction = JSON.stringify({ type: 'mcp', server, tool, input: args });
+  const peer = journal.createPeer();
+  let diagnostic: string | undefined;
+  let settled!: () => void;
+  let failed!: (error: unknown) => void;
+  const completed = new Promise<void>((resolve, reject) => { settled = resolve; failed = reject; });
+  void completed.catch(() => undefined);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let work: Promise<void> | undefined;
+  let dispatchExpired = false;
+  const dispatch = (event: StepDispatchEvent): void => {
+    if (dispatchExpired) return;
+    const dispatched = event.spec as { instruction?: string; surfaces?: { streams?: { stream: string }[] } };
+    if (event.step_id !== id || event.step_type !== 'agent' || work !== undefined
+      || dispatched?.instruction !== instruction
+      || !dispatched.surfaces?.streams?.some(pin => pin.stream === stream)) {
+      failed(new Error('MCP worker received an unexpected dispatch'));
+      return;
+    }
+    clearTimeout(timer);
+    timer = undefined;
+    work = execute(event);
+    void work.then(settled, failed);
+  };
+  async function execute(event: StepDispatchEvent): Promise<void> {
+    const receipt = { type: 'mcp' as const, server, tool, input: args, idempotencyKey };
+    let output: unknown;
+    let confirmed = false;
+    try {
+      if (!known) throw new Error('mcp_unknown_tool');
+      // Renew the worker lease while the MCP tool is in flight. Without this,
+      // a tool that runs longer than the initial lease loses ownership and
+      // the write-back path fails — see worker-lease.ts for the renewal contract.
+      confirmed = await withWorkerLease(peer, event, async () => {
+        return peer.performEffect({
+          runId: event.run_id, stepId: id, attempt: event.attempt, idempotencyKey: event.idempotency_key,
+          surfacePath, revisionBefore: 'pending', revisionAfter: idempotencyKey,
+        }, async () => {
+          const session = await openMcpSession(config, 10_000);
+          try {
+            output = await session.callTool(tool, args);
+            if (typeof output === 'object' && output !== null && 'isError' in output && output.isError === true) {
+              throw new Error('mcp_tool_error');
+            }
+          } finally { await session.close(); }
+        });
+      });
+      // A confirmed election without its receipt is an interrupted writeback,
+      // not a successful result we may invent or a call we may safely repeat.
+      if (!confirmed) throw new Error('mcp_result_unavailable');
+    } catch (error) {
+      if (error instanceof McpError) diagnostic = error.code;
+      else if (error instanceof Error && ['mcp_unknown_tool', 'mcp_tool_error', 'mcp_result_unavailable'].includes(error.message)) diagnostic = error.message;
+      else throw error; // Journal failures remain fail-closed, never provider errors.
+    }
+    await peer.stepComplete(event.run_id, id, event.attempt, event.idempotency_key,
+      diagnostic === undefined ? 'success' : 'worker_error', {
+        output: { ...receipt, output: output ?? null, ...(diagnostic ? { diagnostic } : {}) },
+        started_pins: event.pins, end_pins: event.pins,
+        ...(diagnostic ? { trajectory_tail: { ...receipt, diagnostic } } : {}),
+        effects: confirmed ? [{ surface_path: surfacePath, idempotency_key: event.idempotency_key }] : [],
+      });
+  }
+  let childRunId: string | undefined;
+  try {
+    await peer.connect();
+    await peer.hello('flows-mcp');
+    peer.on('step.dispatch', dispatch);
+    await peer.workerAttach(stream, ['agent'], { workspace: [], streams: [{ stream, read_offset: 0 }] }, 1);
+    const spec = toKernelSpec(compileSpec({ version: SPEC_SCHEMA_VERSION, name: `${flowName}/${id}`,
+      steps: [{ id, type: 'agent', instruction,
+        surfaces: { streams: [{ stream }], external: [surfacePath] }, maxIterations: 1 }],
+    }));
+    timer = setTimeout(() => {
+      dispatchExpired = true;
+      failed(new Error('MCP worker dispatch deadline exceeded'));
+    }, 30_000);
+    // Propagate a dispatch failure even if run.start itself is still pending.
+    const starting = journal.runStart(spec);
+    await Promise.race([starting, completed]);
+    const outcome = await starting;
+    childRunId = outcome.run_id;
+    await completed;
+    if (diagnostic !== undefined) {
+      try { await readCompletedStepOutput(journal, outcome.run_id, id, journalSteps); }
+      catch (error) {
+        if (!(error instanceof AuthoredFlowExecutionError) || error.code !== 'step_failed') throw error;
+        throw new McpStepError(diagnostic, outcome.run_id);
+      }
+    }
+    const receipt = await readCompletedStepOutput(journal, outcome.run_id, id, journalSteps) as { output: unknown };
+    return receipt.output;
+  } finally {
+    clearTimeout(timer);
+    peer.off('step.dispatch', dispatch);
+    // If the dispatch deadline fired we started a child run that will never
+    // be worked -- cancel it so its journal doesn't stay indeterminate.
+    // Best-effort: the parent flow already surfaced the deadline via the
+    // rejected `completed` promise, so a cancel error here must not mask it.
+    if (dispatchExpired && childRunId !== undefined) {
+      try { await journal.runCancel(childRunId); } catch { /* fail-open on cleanup */ }
+    }
+    peer.close();
+    await work?.catch(() => undefined);
+  }
+}
+
+function pathPart(value: string): string {
+  return encodeURIComponent(value).replaceAll('.', '%2E');
+}

package/src/authored-memory.ts

@@ -0,0 +1,55 @@
+import type { MemoryHelper } from '@relayflows/surface';
+import { createHash } from 'node:crypto';
+import { access, stat } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { AuthoredFlowExecutionError } from './authored-flow-error.js';
+import { preflightMemory } from './preflight.js';
+
+/** Stable across runs; disjoint from other flow files and other named flows. */
+export function scriptMemoryScope(flowPath: string, name: string): string {
+  const absolute = resolve(flowPath);
+  const key = createHash('sha256').update(JSON.stringify([absolute, name])).digest('hex');
+  return join(dirname(absolute), '.relayflows', 'memory', 'scripts', key);
+}
+
+export async function probeScriptMemory(): Promise<void> {
+  const { defaultDbPath, openAiHist } = await import('ai-hist');
+  const path = defaultDbPath();
+  await access(path, constants.R_OK);
+  if (!(await stat(path)).isFile()) throw new Error('memory database must be a file');
+  const reader = await openAiHist({ dbPath: path, fallback: 'error' });
+  try { reader.search('', { limit: 1 }); } finally { reader.close(); }
+}
+
+export async function assertMemoryReachable(): Promise<void> {
+  const refusal = await preflightMemory(probeScriptMemory);
+  if (refusal) throw new AuthoredFlowExecutionError('memory_unreachable', refusal.message);
+}
+
+export function authoredMemory(
+  scope: string,
+  assertOpen: () => void,
+  enabled: boolean,
+): MemoryHelper {
+  async function read<T>(action: (reader: import('ai-hist').AiHist) => T): Promise<T> {
+    assertOpen();
+    if (!enabled) throw new AuthoredFlowExecutionError('unsupported_header', 'f.memory requires script memory; memory.script is false');
+    await assertMemoryReachable();
+    assertOpen();
+    const { openAiHist } = await import('ai-hist');
+    const reader = await openAiHist({ projectScope: scope, fallback: 'error' });
+    try { return action(reader); } finally { reader.close(); }
+  }
+  return {
+    recall: (query, options) => read(reader => reader.search(query, { ...options, project: scope })),
+    why: task => read(reader => {
+      const entry = reader.whyForTask(task);
+      return entry?.projectId === scope ? [entry] : [];
+    }),
+    async learn() {
+      assertOpen();
+      throw new AuthoredFlowExecutionError('unsupported_verb', 'f.memory.learn requires the follow-up journal-backed trajectory writer');
+    },
+  };
+}