@relayflows/sdk 2.0.41 → 2.0.43

package/src/helper-operation-use.ts

@@ -0,0 +1,285 @@
+import { isFunction, isNode, memberName, parseFlowBody, walkReferences, type AstNode } from './helper-reference.js';
+
+/**
+ * Whether a flow body calls `f.<namespace>.<method>`.
+ *
+ * - `called`: a direct, named call such as `f.notion.appendBlock(...)`.
+ * - `absent`: the namespace is only ever used directly — `f.notion.x(...)` with
+ *   named methods — or read (`if (f.notion)`, `typeof`, comparisons, a discarded
+ *   `f.notion && ...`), so the call provably does not occur.
+ * - `unprovable`: the namespace or the whole context leaves direct use — an
+ *   alias, destructuring, an argument, a return, a property, a computed member
+ *   or namespace. Its later calls cannot be attributed statically, so callers
+ *   that must fail closed treat this as the call.
+ *
+ * Same scoped parse as `helperNamespacesUsed`: strings and comments naming the
+ * call are not uses, and a nested binding of the context name is not the context.
+ * An unparseable body falls back to the text, permissively.
+ */
+export function helperOperationUse(body: string, root: string, namespace: string, method: string): 'called' | 'absent' | 'unprovable' {
+  const program = parseFlowBody(body);
+  if (program === null) return new RegExp(`\\.\\s*${method}\\b`).test(body) ? 'unprovable' : 'absent';
+  const parents = new WeakMap<AstNode, AstNode>();
+  const all: AstNode[] = [];
+  const link = (node: AstNode): void => {
+    all.push(node);
+    for (const key of Object.keys(node)) {
+      if (key === 'type' || key === 'start' || key === 'end' || key === 'loc') continue;
+      const child = node[key];
+      for (const entry of Array.isArray(child) ? child : [child]) {
+        if (isNode(entry)) { parents.set(entry, node); link(entry); }
+      }
+    }
+  };
+  link(program);
+  let result: 'called' | 'absent' | 'unprovable' = 'absent';
+  const mark = (found: 'called' | 'unprovable') => { if (result !== 'unprovable') result = found; };
+  // Body-wide, whatever scope binds the context name: code that rewrites the
+  // prototypes helpers inherit from (or runs source text) can intercept the
+  // helper anywhere, so nothing is attributable once it is present.
+  if (all.some(node => reachesMachinery(node, parents))) return 'unprovable';
+  walkReferences(program, root, false, { rootFunctionFound: false }, (node) => {
+    // `arguments[0]` is the context in a non-arrow root body without naming it.
+    if (node.type === 'Identifier' && node.name === 'arguments' && rootArguments(node, parents)) return mark('unprovable');
+    if (node.type !== 'Identifier' || node.name !== root) return;
+    const parent = parents.get(node);
+    if (parent === undefined || declares(parent, node)) return;
+    if (parent.type === 'MemberExpression' && parent.object === node) {
+      const name = memberName(parent);
+      if (name === undefined) return mark('unprovable'); // f[expr]
+      if (name !== namespace) return;
+      const grand = parents.get(parent);
+      if (grand?.type === 'MemberExpression' && grand.object === parent) {
+        const operation = memberName(grand);
+        if (operation === undefined) mark('unprovable'); // f.notion[expr]
+        else if (operation === method) {
+          // Calling it is the operation; a read (typeof, comparison) is not;
+          // anything else hands the function on.
+          // Any use but a pure read reaches the operation: a call, however
+          // wrapped (parentheses, comma, ||, ?:, new), or the function handed on.
+          if (!readOrCall(grand, parents, false)) mark('called');
+        }
+        // Inherited object members (valueOf, constructor, toString, ...) can hand
+        // the helper back — directly, or through a prototype the body replaced —
+        // so none is attributable; helper methods return steps.
+        else if (operation === '__proto__' || Object.prototype.hasOwnProperty.call(Object.prototype, operation)) mark('unprovable');
+        return;
+      }
+      if (!readOrCall(parent, parents)) mark('unprovable');
+      return;
+    }
+    // The whole context used as a value (`const { notion } = f`, `use(f)`).
+    if (!readOrCall(node, parents)) mark('unprovable');
+  });
+  return result;
+}
+
+/** Every name a binding pattern introduces. */
+function patternNames(pattern: AstNode | undefined | null, into: Set<string>): void {
+  if (!pattern) return;
+  if (pattern.type === 'Identifier') into.add(pattern.name!);
+  else if (pattern.type === 'AssignmentPattern') patternNames(pattern.left as AstNode, into);
+  else if (pattern.type === 'RestElement') patternNames(pattern.argument as AstNode, into);
+  else if (pattern.type === 'ArrayPattern') for (const element of pattern.elements as Array<AstNode | null>) patternNames(element, into);
+  else if (pattern.type === 'ObjectPattern') {
+    for (const property of pattern.properties as AstNode[]) patternNames((property.type === 'Property' ? property.value : property.argument) as AstNode, into);
+  }
+}
+
+/** The names one scope node binds directly: its parameters, function name, catch parameter, or declarations. */
+function scopeBindings(scope: AstNode): Set<string> {
+  const names = new Set<string>();
+  if (isFunction(scope)) {
+    if (scope.type === 'FunctionExpression') patternNames(scope.id as AstNode | undefined, names);
+    for (const param of (scope.params as AstNode[] | undefined) ?? []) patternNames(param, names);
+  }
+  if (scope.type === 'CatchClause') patternNames(scope.param as AstNode | undefined, names);
+  const statements = scope.type === 'BlockStatement' || scope.type === 'Program' ? scope.body as AstNode[]
+    : ['ForStatement', 'ForInStatement', 'ForOfStatement'].includes(scope.type) ? [(scope.init ?? scope.left) as AstNode] : [];
+  for (const statement of statements ?? []) {
+    if (statement?.type === 'VariableDeclaration') {
+      for (const declarator of statement.declarations as AstNode[]) patternNames(declarator.id as AstNode, names);
+    } else if (statement?.type === 'FunctionDeclaration' || statement?.type === 'ClassDeclaration') {
+      patternNames(statement.id as AstNode | undefined, names);
+    }
+  }
+  return names;
+}
+
+/** Whether `node`, a use of `name`, resolves to a binding in an enclosing scope rather than the global. */
+function boundLocally(node: AstNode, name: string, parents: WeakMap<AstNode, AstNode>): boolean {
+  for (let at = parents.get(node); at !== undefined; at = parents.get(at)) {
+    if (scopeBindings(at).has(name)) return true;
+  }
+  return false;
+}
+
+/** Prototype machinery, eval or Function: anything that lets the body intercept or hide a helper use. */
+function reachesMachinery(node: AstNode, parents: WeakMap<AstNode, AstNode>): boolean {
+  // memberName also reads string-literal computed keys (Object['prototype']).
+  if (node.type === 'MemberExpression' && PROTOTYPE_MACHINERY.has(memberName(node) ?? '')) {
+    // A class or function the body defines has its own prototype, which cannot
+    // reach the helper: Local.prototype.flag = true is not machinery.
+    const object = node.object as AstNode | undefined;
+    return !(memberName(node) === 'prototype' && object?.type === 'Identifier' && ownConstructor(object, parents));
+  }
+  // A prototype-bearing global is safe only as the object of a static,
+  // non-machinery member (Object.keys, Symbol.iterator). Aliasing it, passing
+  // it, destructuring it or indexing it with a runtime key can reach the
+  // machinery under another name.
+  if (node.type === 'Identifier' && (MACHINERY_GLOBALS.has(node.name!) || GLOBAL_ROOTS.has(node.name!))) {
+    const parent = parents.get(node);
+    if (parent !== undefined && declares(parent, node)) return false;
+    if (parent?.type === 'VariableDeclarator' && parent.id === node) return false;
+    if (boundLocally(node, node.name!, parents)) return false;
+    if (!GLOBAL_ROOTS.has(node.name!)) return onlyStaticSafeMember(node, parents);
+    // A global root (globalThis, global, window, self) reaches every global:
+    // follow root-to-root chains, then judge a named prototype-bearing global
+    // like the bare one. Any other use of a root can reach them by any name.
+    let value: AstNode = node;
+    for (let up = parents.get(value); up?.type === 'MemberExpression' && up.object === value
+      && GLOBAL_ROOTS.has(memberName(up) ?? ''); up = parents.get(value)) value = up;
+    const up = parents.get(value);
+    const named = up?.type === 'MemberExpression' && up.object === value ? memberName(up) : undefined;
+    if (named !== undefined && MACHINERY_GLOBALS.has(named)) return onlyStaticSafeMember(up!, parents);
+    return named === undefined || PROTOTYPE_MACHINERY.has(named);
+  }
+  // Destructuring a prototype-bearing global at all (computed keys, rest)
+  // can pick out any of its machinery.
+  if ((node.type === 'VariableDeclarator' && (node.id as AstNode).type === 'ObjectPattern')
+    || (node.type === 'AssignmentExpression' && (node.left as AstNode).type === 'ObjectPattern')) {
+    const source = (node.type === 'VariableDeclarator' ? node.init : node.right) as AstNode | undefined;
+    if (source?.type === 'Identifier' && MACHINERY_GLOBALS.has(source.name!) && !boundLocally(source, source.name!, parents)) return true;
+  }
+  // Destructuring reads the same members: const { prototype: p } = Object.
+  if (node.type === 'Property' && parents.get(node)?.type === 'ObjectPattern') {
+    const key = node.key as AstNode | undefined;
+    const name = key?.type === 'Identifier' && node.computed !== true ? key.name
+      : key?.type === 'Literal' && typeof key.value === 'string' ? key.value : undefined;
+    if (name !== undefined && PROTOTYPE_MACHINERY.has(name)) return true;
+  }
+  if (node.type === 'Identifier' && ['Reflect', 'Proxy', 'eval', 'Function'].includes(node.name!)) {
+    const parent = parents.get(node);
+    if (parent !== undefined && declares(parent, node)) return false;
+    if (parent?.type === 'VariableDeclarator' && parent.id === node) return false;
+    // eval and Function matter only when called; a use resolving to a local
+    // binding (scope by scope, not body-wide) is not the global.
+    // Any use of eval (indirect call, alias) runs source text the scan never
+    // sees; Function is judged with the other prototype-bearing globals.
+    return !boundLocally(node, node.name!, parents);
+  }
+  return false;
+}
+
+/** Whether `node` names a class or function the body itself defines, in an enclosing scope. */
+function ownConstructor(node: AstNode, parents: WeakMap<AstNode, AstNode>): boolean {
+  const name = node.name!;
+  // Class and function bindings are reassignable; one that is reassigned
+  // anywhere could hold any constructor.
+  let program: AstNode = node;
+  for (let at = parents.get(node); at !== undefined; at = parents.get(at)) program = at;
+  if (reassigns(program, name)) return false;
+  const constructs = (value: AstNode | undefined) => value?.type === 'ClassExpression' || value?.type === 'FunctionExpression';
+  for (let scope = parents.get(node); scope !== undefined; scope = parents.get(scope)) {
+    const statements = scope.type === 'BlockStatement' || scope.type === 'Program' ? scope.body as AstNode[] : [];
+    for (const statement of statements) {
+      if ((statement.type === 'ClassDeclaration' || statement.type === 'FunctionDeclaration')
+        && (statement.id as AstNode | undefined)?.name === name) return true;
+      if (statement.type === 'VariableDeclaration' && statement.kind === 'const') {
+        for (const declarator of statement.declarations as AstNode[]) {
+          if ((declarator.id as AstNode).type === 'Identifier' && (declarator.id as AstNode).name === name) return constructs(declarator.init as AstNode | undefined);
+        }
+      }
+    }
+    if (scopeBindings(scope).has(name)) return false; // bound here to something else
+  }
+  return false;
+}
+
+/** Whether any assignment or update anywhere under `node` targets the identifier `name`. */
+function reassigns(node: AstNode, name: string): boolean {
+  if ((node.type === 'AssignmentExpression' && (node.left as AstNode).type === 'Identifier' && (node.left as AstNode).name === name)
+    || (node.type === 'UpdateExpression' && (node.argument as AstNode).type === 'Identifier' && (node.argument as AstNode).name === name)) return true;
+  for (const key of Object.keys(node)) {
+    if (key === 'type' || key === 'start' || key === 'end' || key === 'loc') continue;
+    const child = node[key];
+    for (const entry of Array.isArray(child) ? child : [child]) if (isNode(entry) && reassigns(entry, name)) return true;
+  }
+  return false;
+}
+
+/**
+ * For a value that is a prototype-bearing global: true (machinery reached)
+ * unless it is only the object of a static, non-machinery member.
+ */
+function onlyStaticSafeMember(value: AstNode, parents: WeakMap<AstNode, AstNode>): boolean {
+  const parent = parents.get(value);
+  const member = parent?.type === 'MemberExpression' && parent.object === value ? memberName(parent) : undefined;
+  return member === undefined || PROTOTYPE_MACHINERY.has(member);
+}
+
+/** Globals whose members include the prototype machinery. */
+const MACHINERY_GLOBALS = new Set(['Object', 'Symbol', 'Reflect', 'Function', 'Proxy']);
+/** Names for the global object itself, through which every global is reachable. */
+const GLOBAL_ROOTS = new Set(['globalThis', 'global', 'window', 'self']);
+
+/** Members through which a body can reach or rewrite the prototypes every helper inherits from. */
+const PROTOTYPE_MACHINERY = new Set(['prototype', '__proto__', 'defineProperty', 'defineProperties',
+  'setPrototypeOf', 'getPrototypeOf', 'toPrimitive', '__defineGetter__', '__defineSetter__',
+  '__lookupGetter__', '__lookupSetter__',
+  // Any function's (or global's) constructor chain reaches Function, which compiles source text,
+  // and eval (globalThis.eval, ...) runs it directly.
+  'constructor', 'eval']);
+
+/**
+ * A use that cannot hand the value on: a discarded value or a read, and —
+ * when `allowCall` — a direct call of it.
+ */
+function readOrCall(value: AstNode, parents: WeakMap<AstNode, AstNode>, allowCall = true): boolean {
+  let current = value;
+  let parent = parents.get(current);
+  // Wrappers that pass their operand's value through unchanged.
+  while (parent !== undefined && ['ChainExpression', 'ParenthesizedExpression', 'AwaitExpression',
+    'LogicalExpression', 'ConditionalExpression', 'SequenceExpression'].includes(parent.type)
+    && !(parent.type === 'ConditionalExpression' && parent.test === current)) {
+    // Only a sequence's last operand is its value; earlier ones are discarded reads.
+    if (parent.type === 'SequenceExpression' && (parent.expressions as AstNode[]).at(-1) !== current) return true;
+    current = parent;
+    parent = parents.get(current);
+  }
+  if (parent === undefined) return false;
+  if ((parent.type === 'CallExpression' || parent.type === 'NewExpression') && parent.callee === current) return allowCall;
+  // `instanceof` hands its left operand to the right side's Symbol.hasInstance.
+  if (parent.type === 'BinaryExpression') return parent.operator !== 'instanceof';
+  if (['ExpressionStatement', 'UnaryExpression'].includes(parent.type)) return true;
+  // `${f.notion}` coerces to a string; a tagged template hands the value to its tag.
+  if (parent.type === 'TemplateLiteral') return parents.get(parent)?.type !== 'TaggedTemplateExpression';
+  return ['IfStatement', 'WhileStatement', 'DoWhileStatement', 'ForStatement', 'ConditionalExpression'].includes(parent.type)
+    && parent.test === current;
+}
+
+/**
+ * `arguments` used (not named) inside the root flow function itself — the
+ * outermost non-arrow function, whatever shape its context parameter has — not
+ * inside a nested non-arrow function with its own `arguments`.
+ */
+function rootArguments(node: AstNode, parents: WeakMap<AstNode, AstNode>): boolean {
+  const parent = parents.get(node);
+  if (parent !== undefined && declares(parent, node)) return false;
+  let owner: AstNode | undefined;
+  for (let at = parents.get(node); at !== undefined; at = parents.get(at)) {
+    if (at.type === 'FunctionDeclaration' || at.type === 'FunctionExpression') { owner = at; break; }
+  }
+  if (owner === undefined) return false;
+  for (let at = parents.get(owner); at !== undefined; at = parents.get(at)) {
+    if (at.type === 'FunctionDeclaration' || at.type === 'FunctionExpression' || at.type === 'ArrowFunctionExpression') return false;
+  }
+  return true;
+}
+
+/** The identifier is a name being declared or a property name, not a use of the context. */
+function declares(parent: AstNode, node: AstNode): boolean {
+  if (isFunction(parent)) return ((parent.params as AstNode[] | undefined) ?? []).includes(node);
+  if (parent.type === 'Property') return parent.key === node && parent.computed !== true && parent.shorthand !== true;
+  return parent.type === 'MemberExpression' && parent.property === node && parent.computed !== true;
+}

package/src/helper-preflight.ts

@@ -1,6 +1,7 @@
 import { helperProviders } from '@relayflows/surface/runtime';
 import type { PreflightResult, PreflightDiagnostic } from './preflight.js';
 import { helperNamespacesUsed } from './helper-reference.js';
+import { helperOperationUse } from './helper-operation-use.js';
 
 /** Static discovery never executes the body; dynamic aliases are checked at call time. */
 export function preflightHelpers(
@@ -18,6 +19,16 @@ export function preflightHelpers(
   // comment, template quasi or regex is not used, and refusing on one demands
   // a mount the flow never touches.
   const referenced = root === undefined ? new Set<string>() : helperNamespacesUsed(body, root);
+  // f.notion.appendBlock has no writeback route. It is attributed precisely only
+  // while f.notion is used directly; once it is aliased, passed on or reached by a
+  // computed name, the call cannot be ruled out and check refuses, saying why.
+  // Without a named context parameter (destructured, say) nothing can be
+  // attributed, so a declared Notion flow cannot rule the call out.
+  const notionAppend = body.trim() === '' ? 'absent'
+    : root === undefined ? 'unprovable'
+      : helperOperationUse(body, root, 'notion', 'appendBlock');
+  const appendsNotionBlock = notionAppend !== 'absent';
+  const notionAppendInferred = notionAppend === 'unprovable';
   for (const { provider, namespace, supported } of helperProviders) {
     const used = definition.header?.tools?.[namespace] === true
       || referenced.has(namespace);
@@ -32,9 +43,13 @@ export function preflightHelpers(
       diagnostics.push({ severity: 'refusal',
         kind: provider === 'slack' ? (fact.token?.trim() ? 'helper_slack.mount_required' : 'helper_slack.credential_missing') : 'helper_provider.mount_required',
         message: `f.${namespace} requires a relayfile ${provider} mount; direct-token transport is not implemented.` });
-    } else if (provider === 'notion' && !fact.mock && /\.\s*appendBlock\b/.test(body)) {
+    }
+    // Missing local mounts must not hide an operation unsupported on Cloud too.
+    if (supported && provider === 'notion' && !fact.mock && appendsNotionBlock) {
       diagnostics.push({ severity: 'refusal', kind: 'helper_provider.unsupported',
-        message: 'f.notion.appendBlock is mock-only: the Notion adapter has no append-block writeback route.' });
+        message: 'f.notion.appendBlock is mock-only: the Notion adapter has no append-block writeback route.'
+          + (notionAppendInferred ? ' f.notion is aliased, passed on or called through a computed name in this body, so the call cannot be ruled out;'
+            + ' call f.notion methods directly by name on a named context parameter (f.notion.createPage(...)) so flows check can see which ones run.' : '') });
     }
   }
   return { ok: diagnostics.length === 0, gates: [], resolutions: [], diagnostics };

package/src/helper-reference.ts

@@ -39,7 +39,7 @@ export function helperNamespacesUsed(body: string, root: string): ReadonlySet<st
 }
 
 /** `f.slack`, `f["slack"]`, `f?.slack` — but not `f[variable]`, which is unknowable. */
-function memberName(node: AstNode): string | undefined {
+export function memberName(node: AstNode): string | undefined {
   const property = node.property as AstNode | undefined;
   if (property === undefined) return undefined;
   if (node.computed !== true) return property.type === 'Identifier' ? property.name : undefined;
@@ -55,7 +55,7 @@ function memberName(node: AstNode): string | undefined {
  * here (Node strips before evaluating, and bundlers transpile), so this is
  * plain JavaScript.
  */
-function parseFlowBody(body: string): AstNode | null {
+export function parseFlowBody(body: string): AstNode | null {
   const options = { ecmaVersion: 'latest' as const, allowAwaitOutsideFunction: true, allowReturnOutsideFunction: true };
   // `parseExpressionAt` stops at the end of the first expression and does not
   // object to what follows, so `async post(f) { … }` parses as the identifier
@@ -103,7 +103,7 @@ function textFallback(body: string, root: string): ReadonlySet<string> {
   return used;
 }
 
-type AstNode = {
+export type AstNode = {
   type: string;
   end?: number;
   name?: string;
@@ -120,7 +120,7 @@ type AstNode = {
  * would refuse the flow for a mount it never touches. Acorn gives us binding
  * shapes, so scopes are tracked as syntax instead of guessed from text.
  */
-function walkReferences(
+export function walkReferences(
   node: AstNode,
   root: string,
   shadowed: boolean,
@@ -165,7 +165,7 @@ function walkReferences(
   }
 }
 
-function isFunction(node: AstNode): boolean {
+export function isFunction(node: AstNode): boolean {
   return node.type === 'ArrowFunctionExpression'
     || node.type === 'FunctionExpression'
     || node.type === 'FunctionDeclaration';
@@ -250,6 +250,6 @@ function functionVarBinds(node: AstNode, root: string): boolean {
   return found;
 }
 
-function isNode(value: unknown): value is AstNode {
+export function isNode(value: unknown): value is AstNode {
   return typeof value === 'object' && value !== null && typeof (value as { type?: unknown }).type === 'string';
 }

package/src/index.ts

@@ -119,6 +119,17 @@ export {
 } from './flow-requirements.js';
 export { parseHumanTo, parseHumanRecipient, humanRecipientProvider, type HumanRecipient, type HumanRecipientParse } from './human-to.js';
 
+export {
+  evaluateFlow, parseFlowEvalSuite, loadFlowEvalSuite, flowEvalSuiteSha256, flowEvalVersion, flowEvalSources,
+  parseFlowEvalBaseline, FlowEvalError, FLOW_EVAL_REPORT_SCHEMA_VERSION, MAX_FLOW_EVAL_CASES, MAX_FLOW_EVAL_SOURCES,
+  type EvaluateFlowOptions, type FlowEvalBaseline, type FlowEvalCase, type FlowEvalCaseResult, type FlowEvalErrorCode,
+  type FlowEvalExecutionRequest, type FlowEvalExecutor, type FlowEvalExpectation, type FlowEvalOutcome,
+  type FlowEvalReport, type FlowEvalRun, type FlowEvalScore, type FlowEvalScorer, type FlowEvalStep,
+  type FlowEvalSuite, type FlowEvalTarget, type FlowEvalThresholds, type FlowEvalVersion,
+} from './flow-eval.js';
+export { localFlowEvalExecutor, type LocalFlowEvalExecutorOptions } from './flow-eval-local.js';
+export { cloudFlowEvalExecutor, type CloudFlowEvalExecutorOptions } from './flow-eval-cloud.js';
+
 export { canonicalize, specHash } from './canonical.js';
 export {
   compileAndHash,
@@ -217,7 +228,7 @@ export type {
 } from './protocol.js';
 export { JOURNAL_WRITE_FAILED, PROTOCOL_VERSION } from './protocol.js';
 
-export { JournalClient, type JournalClientOptions } from './journal-client.js';
+export { JournalClient, JournalRequestTimeoutError, type JournalClientOptions } from './journal-client.js';
 export { AgentWorker, type AgentWorkerOptions } from './worker.js';
 
 export {
@@ -287,3 +298,6 @@ export { createFlow, type CreateFlowOptions, type CreatedFlow } from './create-f
 export { renderProgress, type ProgressEvent } from './progress.js';
 export { webhookTriggerSpec } from './trigger-executor.js';
 export { scheduleTriggerSpec, scheduleLowering, SCHEDULE_EXECUTOR, type ScheduleLowering } from './schedule-trigger.js';
+
+export { answerCloudFlow, readCloudHumanWait, CloudAnswerError, type CloudAnswerOptions, type CloudResumeReceipt } from './cloud-answer.js';
+export type { CloudHumanWait } from './cloud-human-wait.js';

package/src/journal-budgeted-reads.ts

@@ -0,0 +1,134 @@
+import { JournalFrameError, JournalProtocolError } from './journal-connection.js';
+import type { JournalClient } from './journal-client.js';
+import { JournalReadInterruptedError, JournalReadPolicy, JournalRequestTimeoutError } from './journal-read-policy.js';
+import type { VerbContract } from './protocol.js';
+
+/**
+ * Budgeted, retried reads for one flow client, on a dedicated reader session.
+ *
+ * Reads go to a second connection so they never queue behind the primary's
+ * unbounded commands; the policy serializes them and retries timeouts and lost
+ * reader transport within the budget. Protocol refusals and malformed frames
+ * fail closed. A refused reader handshake falls back to the primary session,
+ * whose own failures keep their meaning because it also carries writes.
+ */
+export class BudgetedReads {
+  private readonly policy = new JournalReadPolicy();
+  private reader: JournalClient | undefined;
+  private readerReady: Promise<JournalClient | undefined> | undefined;
+  private readonly scoped = new Set<AbortSignal>();
+
+  constructor(
+    private readonly primary: JournalClient,
+    private readonly budgetMs: number,
+    private readonly lifecycle?: AbortSignal,
+  ) {}
+
+  /** Add an abort source (a root attempt's lease) for as long as the returned release is not called. */
+  scope(signal: AbortSignal): () => void {
+    this.scoped.add(signal);
+    return () => { this.scoped.delete(signal); };
+  }
+
+  /**
+   * Stop all reads. An unexpected primary drop (`interrupted`) ends in-flight
+   * reads as a read interruption, so the run stays resumable; a caller close
+   * keeps its plain error.
+   */
+  close(cause?: unknown, interrupted = false): void {
+    this.policy.close(interrupted ? new JournalReadInterruptedError('journal', 1, 0, undefined, { cause }) : undefined);
+    this.reader?.close(cause);
+  }
+
+  read<V extends keyof VerbContract>(verb: V, params: VerbContract[V]['params'], timeoutMs: number,
+    signal?: AbortSignal): Promise<VerbContract[V]['result']> {
+    const sources = [signal, this.lifecycle, ...this.scoped].filter((source): source is AbortSignal => source !== undefined);
+    const combined = sources.length <= 1 ? sources[0] : AbortSignal.any(sources);
+    return this.policy.read(verb, timeoutMs, this.budgetMs, async (bound, attemptSignal) => {
+      const started = performance.now();
+      const reader = await this.untilAborted(this.session(), attemptSignal).catch(error => {
+        attemptSignal.throwIfAborted();
+        // A malformed handshake frame is a protocol violation: fail closed.
+        if (error instanceof JournalFrameError) throw error;
+        throw new JournalReadInterruptedError(verb, 1, performance.now() - started, undefined, { cause: error });
+      });
+      attemptSignal.throwIfAborted();
+      const remaining = bound - (performance.now() - started);
+      if (remaining <= 0) throw new JournalRequestTimeoutError(verb, bound);
+      if (reader === undefined) return this.primary.requestOnce(verb, params, remaining, attemptSignal);
+      try {
+        return await reader.requestOnce(verb, params, remaining, attemptSignal);
+      } catch (error) {
+        // relayflowd answers one frame at a time per connection, so a canceled
+        // request still occupies this reader: drop it for a fresh session.
+        if (attemptSignal.aborted) { this.drop(reader); throw error; }
+        // A timed-out request still occupies this sequential connection: retry
+        // on a fresh reader rather than queueing behind it.
+        if (error instanceof JournalRequestTimeoutError) { this.drop(reader); throw error; }
+        if (error instanceof JournalProtocolError || error instanceof JournalFrameError) throw error;
+        // Only the dedicated reader's transport failed; reconnect within the budget.
+        this.drop(reader);
+        throw new JournalReadInterruptedError(verb, 1, performance.now() - started, undefined, { cause: error });
+      }
+    }, combined);
+  }
+
+  /** The primary session's own `hello`, retried within the same budget as reads. */
+  handshake(params: VerbContract['hello']['params'], timeoutMs: number): Promise<VerbContract['hello']['result']> {
+    return this.policy.read('hello', timeoutMs, this.budgetMs,
+      (bound, attemptSignal) => this.primary.requestOnce('hello', params, bound, attemptSignal).catch(error => {
+        if (attemptSignal.aborted || error instanceof JournalRequestTimeoutError
+          || error instanceof JournalProtocolError || error instanceof JournalFrameError) throw error;
+        // The primary's own transport failed (ECONNRESET, ...): a read
+        // interruption, not a body failure, and not retryable on this session.
+        throw new JournalReadInterruptedError('hello', 1, 0, undefined, { cause: error, retryable: false });
+      }), this.lifecycle);
+  }
+
+  private session(): Promise<JournalClient | undefined> {
+    if (this.readerReady === undefined) {
+      const reader = this.primary.createPeer();
+      this.reader = reader;
+      this.readerReady = reader.connect().then(() => reader.hello('flows-reader')).then(() => reader)
+        .catch(error => {
+          reader.close();
+          // A daemon that refuses the session will keep refusing it: read on the primary.
+          if (error instanceof JournalProtocolError) return undefined;
+          // A connect or hello that failed under load is retried with a fresh session,
+          // never by queueing reads behind the primary's unbounded commands for good.
+          if (this.reader === reader) {
+            this.reader = undefined;
+            this.readerReady = undefined;
+          }
+          throw error;
+        });
+    }
+    return this.readerReady;
+  }
+
+  /**
+   * Settle with the session, or at once with the attempt's abort — abandoning a
+   * setup still in progress, so the serialized queue never waits on it.
+   */
+  private untilAborted<T>(setup: Promise<T>, signal: AbortSignal): Promise<T> {
+    return new Promise<T>((resolve, reject) => {
+      const onAbort = () => {
+        const pending = this.reader;
+        if (pending !== undefined) this.drop(pending);
+        reject(signal.reason);
+      };
+      if (signal.aborted) { onAbort(); return; }
+      signal.addEventListener('abort', onAbort, { once: true });
+      setup.then(value => { signal.removeEventListener('abort', onAbort); resolve(value); },
+        error => { signal.removeEventListener('abort', onAbort); reject(error); });
+    });
+  }
+
+  /** Forget a reader whose transport failed so the next attempt reconnects one. */
+  private drop(reader: JournalClient): void {
+    if (this.reader !== reader) return;
+    this.reader = undefined;
+    this.readerReady = undefined;
+    reader.close();
+  }
+}