@relayflows/sdk 2.0.0

package/src/authored-flow-loader.ts

@@ -0,0 +1,44 @@
+import { accessSync, constants } from 'node:fs';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { getAuthoredFlowDefinition, type FlowHandle } from './authored-flow.js';
+
+export class AuthoredFlowLoadError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'AuthoredFlowLoadError';
+  }
+}
+
+/** Import and validate a direct-run module without executing its authored body. */
+export async function loadAuthoredFlow(path: string): Promise<FlowHandle> {
+  const absolutePath = resolve(path);
+  try {
+    accessSync(absolutePath, constants.R_OK);
+  } catch {
+    throw new AuthoredFlowLoadError(`Flow "${path}" is not readable.`);
+  }
+
+  let authoredModule: Record<string, unknown>;
+  try {
+    authoredModule = await import(pathToFileURL(absolutePath).href) as Record<string, unknown>;
+  } catch (error) {
+    throw new AuthoredFlowLoadError(
+      `Flow "${path}" could not be imported: ${errorMessage(error)}`,
+    );
+  }
+
+  const handle = authoredModule['default'] as FlowHandle;
+  try {
+    getAuthoredFlowDefinition(handle);
+  } catch (error) {
+    throw new AuthoredFlowLoadError(
+      `Flow "${path}" must default-export flow(...): ${errorMessage(error)}`,
+    );
+  }
+  return handle;
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : 'unknown authored-flow error';
+}

package/src/authored-flow-operation.ts

@@ -0,0 +1,252 @@
+import { executionAsyncId } from 'node:async_hooks';
+import type { Step } from '@relayflows/surface';
+import { AuthoredFlowExecutionError } from './authored-flow-error.js';
+import {
+  AuthoredFlowLifecycle,
+  type AuthoredOperationInvocation,
+} from './authored-flow-lifecycle.js';
+
+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>;
+  private state: OperationState = 'created';
+  private thenInvoked = false;
+  private rootFailureRecorded = false;
+  private rootFailure: unknown;
+  private callbackFailureRecorded = false;
+  private callbackFailure: unknown;
+  private readonly promise: Promise<T>;
+  private readonly resolve: (value: T | PromiseLike<T>) => void;
+  private readonly reject: (reason?: unknown) => void;
+
+  constructor(
+    readonly id: string,
+    readonly verb: string,
+    private readonly assertCanStart: () => void,
+    private readonly start: () => Promise<T>,
+    private readonly scope: AuthoredFlowLifecycle,
+  ) {
+    let resolve!: (value: T | PromiseLike<T>) => void;
+    let reject!: (reason?: unknown) => void;
+    this.promise = new Promise<T>((promiseResolve, promiseReject) => {
+      resolve = promiseResolve;
+      reject = promiseReject;
+    });
+    this.resolve = resolve;
+    this.reject = reject;
+
+    observeRejection(this.promise, (error) => this.recordRootFailure(error));
+    const operation = this;
+    this.step = Object.freeze({
+      gate(): never {
+        throw new AuthoredFlowExecutionError(
+          'unsupported_gate',
+          'postfix gates are not lowered by the initial authored executor',
+        );
+      },
+      then<TResult1 = T, TResult2 = never>(
+        onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null,
+        onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null,
+      ): Promise<TResult1 | TResult2> {
+        operation.thenInvoked = true;
+        const invocation = operation.scope.registerInvocation(operation, executionAsyncId());
+        void operation.begin();
+        const derived = nativeThen(
+          operation.promise,
+          wrapResolver(operation, invocation, onfulfilled),
+          wrapResolver(operation, invocation, onrejected),
+        );
+        return trackDerivedPromise(
+          derived,
+          (error) => operation.recordCallbackFailure(error),
+        );
+      },
+    });
+    this.scope.registerStep(this.step, this);
+  }
+
+  get lifecycle(): OperationState {
+    return this.state;
+  }
+
+  get wasManuallyChained(): boolean {
+    return this.thenInvoked && !this.scope.hasBoundConsumer(this);
+  }
+
+  get wasAwaited(): boolean {
+    return this.scope.hasBoundConsumer(this);
+  }
+
+  get failure(): { readonly recorded: boolean; readonly value: unknown } {
+    return { recorded: this.rootFailureRecorded, value: this.rootFailure };
+  }
+
+  get derivedFailure(): { readonly recorded: boolean; readonly value: unknown } {
+    return { recorded: this.callbackFailureRecorded, value: this.callbackFailure };
+  }
+
+  cancel(error: unknown): void {
+    if (this.state !== 'created') return;
+    this.state = 'rejected';
+    this.recordRootFailure(error);
+    this.reject(error);
+  }
+
+  async waitForSettlement(): Promise<void> {
+    await nativeThen(this.promise, () => undefined, () => undefined);
+  }
+
+  invokeResolver<TResult>(
+    invocation: AuthoredOperationInvocation,
+    callback: () => TResult,
+  ): TResult {
+    return this.scope.invokeResolver(invocation, callback);
+  }
+
+  private async begin(): Promise<void> {
+    if (this.state !== 'created') return;
+    try {
+      this.assertCanStart();
+      this.state = 'running';
+      const value = await this.start();
+      this.state = 'fulfilled';
+      this.resolve(value);
+    } catch (error) {
+      this.state = 'rejected';
+      this.recordRootFailure(error);
+      this.reject(error);
+    }
+  }
+
+  private recordRootFailure(error: unknown): void {
+    if (this.rootFailureRecorded) return;
+    this.rootFailureRecorded = true;
+    this.rootFailure = error;
+  }
+
+  private recordCallbackFailure(error: unknown): void {
+    if (this.callbackFailureRecorded) return;
+    this.callbackFailureRecorded = true;
+    this.callbackFailure = error;
+  }
+}
+
+export async function verifyAuthoredOperations(
+  flowName: string,
+  operations: readonly AuthoredFlowOperation<unknown>[],
+  lifecycle: AuthoredFlowLifecycle,
+): Promise<void> {
+  const canceled = new Set(operations.filter((operation) => operation.lifecycle === 'created'));
+
+  if (canceled.size > 0) {
+    const error = unawaitedError(flowName, [...canceled]);
+    for (const operation of operations) operation.cancel(error);
+  }
+
+  // Read the in-flight set before the gate awaits anything: "was derived work
+  // still running when the body returned" is the question, and every await here
+  // would move the answer.
+  const inFlight = lifecycle.derivedWorkInFlight(operations);
+
+  await Promise.all(operations.map((operation) => operation.waitForSettlement()));
+  await lifecycle.observeCallbackFailures(operations);
+  const unawaited = operations.filter((operation) =>
+    !lifecycle.isHandled(operation)
+    || operation.lifecycle === 'created'
+    || operation.lifecycle === 'running');
+
+  const failed = operations.find((operation) =>
+    operation.failure.recorded && !canceled.has(operation));
+  if (failed !== undefined) {
+    throw failed.failure.value;
+  }
+  const callbackFailed = operations.find((operation) =>
+    operation.derivedFailure.recorded || lifecycle.callbackFailure(operation).recorded);
+  if (callbackFailed !== undefined) {
+    const failure = callbackFailed.derivedFailure.recorded
+      ? callbackFailed.derivedFailure.value
+      : lifecycle.callbackFailure(callbackFailed).value;
+    throw new AuthoredFlowExecutionError(
+      'operation_callback_failed',
+      `flow "${flowName}" derived handler for ${formatOperation(callbackFailed)} rejected: ${describeError(failure)}`,
+    );
+  }
+  if (unawaited.length > 0) {
+    throw unawaitedError(flowName, unawaited);
+  }
+  if (inFlight.length > 0) {
+    throw new AuthoredFlowExecutionError(
+      'unsettled_derived_work',
+      `flow "${flowName}" completed while work derived from ${inFlight.map(formatOperation).join(', ')} was still in flight`,
+    );
+  }
+}
+
+export async function stopAuthoredOperations(
+  operations: readonly AuthoredFlowOperation<unknown>[],
+  reason: unknown,
+): Promise<void> {
+  for (const operation of operations) operation.cancel(reason);
+  await Promise.all(operations.map((operation) => operation.waitForSettlement()));
+}
+
+function unawaitedError(
+  flowName: string,
+  operations: readonly AuthoredFlowOperation<unknown>[],
+): AuthoredFlowExecutionError {
+  return new AuthoredFlowExecutionError(
+    'unawaited_step',
+    `flow "${flowName}" returned with unawaited steps: ${operations.map(formatOperation).join(', ')}`,
+  );
+}
+
+function formatOperation(operation: AuthoredFlowOperation<unknown>): string {
+  return `${operation.id} (f.${operation.verb})`;
+}
+
+function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function observeRejection<T>(promise: Promise<T>, record: (error: unknown) => void): void {
+  void nativeThen(promise, undefined, (error) => record(error));
+}
+
+function nativeThen<T, TResult1 = T, TResult2 = never>(
+  promise: Promise<T>,
+  onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null,
+  onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null,
+): Promise<TResult1 | TResult2> {
+  return nativePromiseThen.call(promise, onfulfilled, onrejected) as Promise<TResult1 | TResult2>;
+}
+
+function wrapResolver<T, TValue, TResult>(
+  operation: AuthoredFlowOperation<T>,
+  invocation: AuthoredOperationInvocation,
+  callback?: ((value: TValue) => TResult | PromiseLike<TResult>) | null,
+): ((value: TValue) => TResult | PromiseLike<TResult>) | undefined {
+  if (callback === undefined || callback === null) return undefined;
+  return (value) => operation.invokeResolver(invocation, () => callback(value));
+}
+
+function trackDerivedPromise<T>(
+  promise: Promise<T>,
+  record: (error: unknown) => void,
+): Promise<T> {
+  observeRejection(promise, record);
+  Object.defineProperty(promise, 'then', {
+    value<TResult1 = T, TResult2 = never>(
+      onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null,
+      onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null,
+    ): Promise<TResult1 | TResult2> {
+      return trackDerivedPromise(
+        nativeThen(promise, onfulfilled, onrejected),
+        record,
+      );
+    },
+  });
+  return promise;
+}

package/src/authored-flow.ts

@@ -0,0 +1,21 @@
+import {
+  getFlowDefinition,
+  type AuthoredFlowDefinition,
+  type FlowHandle,
+} from '@relayflows/surface/runtime';
+
+/**
+ * Recover the immutable program retained by an authored flow handle.
+ *
+ * Importing the module evaluates author code only far enough to define the
+ * flow. The SDK does not yet expose a public executor because authored-body
+ * progress has no durable root journal. Internal lowering tests recover the
+ * definition here without making that seam a supported runner.
+ */
+export function getAuthoredFlowDefinition<Input = unknown>(
+  handle: FlowHandle,
+): AuthoredFlowDefinition<Input> {
+  return getFlowDefinition<Input>(handle);
+}
+
+export type { AuthoredFlowDefinition, FlowHandle };

package/src/authored-promise-graph.ts

@@ -0,0 +1,196 @@
+import { createHook, executionAsyncId, type AsyncHook } from 'node:async_hooks';
+
+/**
+ * The promise graph an authored flow body actually creates.
+ *
+ * Three properties matter and each one is a repair of a measured defect:
+ *
+ * 1. **Scoped.** Only promises created while the owning lifecycle is the active
+ *    `AsyncLocalStorage` store are recorded. A previous revision recorded every
+ *    promise created anywhere in the process for the life of the flow; a probe
+ *    measured 20 002 unrelated promises retained.
+ * 2. **Eagerly attributed.** A promise is attributed to a root the moment it is
+ *    created, or the moment its parent becomes attributed — never by walking the
+ *    graph per candidate at completion time. The walk made the completion gate
+ *    quadratic: a 27 ms body with 30 000 ordinary awaits spent 95.8 s in the gate.
+ * 3. **Complete, not sampled.** `pending` is the set of tracked promises that have
+ *    not settled. Derived work in flight is a fact the gate can read, so the gate
+ *    never has to guess whether a failure "has landed yet".
+ *
+ * Attribution flows forward along the same `trigger` edge the previous revision
+ * walked backward, so it admits exactly the same set — it just knows the answer
+ * before it is asked. Children created before their parent becomes a root are
+ * parked in `unattributedChildren` and flooded when the root is registered; a
+ * promise cannot settle before its ancestors, and a root is always registered
+ * before it settles, so no parked child is ever missed.
+ */
+export class AuthoredPromiseGraph {
+  private readonly hook: AsyncHook;
+  private readonly triggers = new Map<number, number>();
+  private readonly creationContexts = new Map<number, number>();
+  private readonly resolutionCauses = new Map<number, number>();
+  private readonly promiseIds = new WeakMap<object, number>();
+  private readonly handles = new Map<number, Promise<unknown>>();
+  private readonly unattributedChildren = new Map<number, number[]>();
+  private readonly attributedRoots = new Map<number, number>();
+  private readonly roots = new Set<number>();
+  private readonly pending = new Set<number>();
+  private dependencyCache: { readonly start: number; readonly found: ReadonlySet<number> } | undefined;
+
+  constructor(
+    private readonly inScope: () => boolean,
+    private readonly onPromiseResolve: (asyncId: number) => void,
+  ) {
+    this.hook = createHook({
+      init: (asyncId, type, triggerAsyncId, resource) => {
+        if (type !== 'PROMISE' || typeof resource !== 'object' || resource === null) return;
+        if (!this.inScope()) return;
+        this.triggers.set(asyncId, triggerAsyncId);
+        this.creationContexts.set(asyncId, executionAsyncId());
+        this.promiseIds.set(resource, asyncId);
+        this.handles.set(asyncId, resource as Promise<unknown>);
+        this.pending.add(asyncId);
+        const root = this.roots.has(triggerAsyncId)
+          ? triggerAsyncId
+          : this.attributedRoots.get(triggerAsyncId);
+        if (root !== undefined) this.attribute(asyncId, root);
+        else if (this.triggers.has(triggerAsyncId)) this.park(triggerAsyncId, asyncId);
+      },
+      promiseResolve: (asyncId) => {
+        this.onPromiseResolve(asyncId);
+        if (!this.triggers.has(asyncId)) return;
+        const cause = executionAsyncId();
+        if (cause !== asyncId) this.resolutionCauses.set(asyncId, cause);
+        this.pending.delete(asyncId);
+        if (this.attributedRoots.has(asyncId) || this.roots.has(asyncId)) return;
+        // A combinator's aggregate is resolved from inside the reaction of one of
+        // its members, so it is not downstream of any member by `trigger` and can
+        // only inherit attribution here, from the context that resolved it. Without
+        // this, only `Promise.all` was covered — because it is the one combinator
+        // registered explicitly — and `Promise.allSettled`, `Promise.any` and
+        // `Promise.race` each carried a deferred derived failure to terminal
+        // success. Measured; see ops/probes/pr134-repair-0903/combinators.mjs.
+        const adopted = this.attributedRoots.get(cause);
+        if (adopted !== undefined) {
+          this.attribute(asyncId, adopted);
+          return;
+        }
+        // A settled, unattributed promise can never become attributed: attribution
+        // only reaches a promise while its root is still pending. Release it.
+        this.handles.delete(asyncId);
+        this.unattributedChildren.delete(asyncId);
+      },
+    });
+  }
+
+  enable(): void {
+    this.hook.enable();
+  }
+
+  disable(): void {
+    this.hook.disable();
+  }
+
+  idOf(value: object): number | undefined {
+    return this.promiseIds.get(value);
+  }
+
+  /** Mark a promise whose descendants belong to an authored operation. */
+  registerRoot(asyncId: number): void {
+    if (asyncId <= 0 || this.roots.has(asyncId)) return;
+    this.roots.add(asyncId);
+    const parked = this.unattributedChildren.get(asyncId);
+    if (parked === undefined) return;
+    this.unattributedChildren.delete(asyncId);
+    for (const child of parked) this.attribute(child, asyncId);
+  }
+
+  /** Promises derived from `roots` that have not settled. */
+  inFlightFrom(roots: ReadonlySet<number>): number[] {
+    const found: number[] = [];
+    for (const asyncId of this.pending) {
+      const root = this.attributedRoots.get(asyncId);
+      if (root !== undefined && roots.has(root)) found.push(asyncId);
+    }
+    return found;
+  }
+
+  /** Settled promises derived from `roots`, with their handles. */
+  settledFrom(roots: ReadonlySet<number>): Promise<unknown>[] {
+    const found: Promise<unknown>[] = [];
+    for (const [asyncId, root] of this.attributedRoots) {
+      if (!roots.has(root) || this.pending.has(asyncId)) continue;
+      const handle = this.handles.get(asyncId);
+      if (handle !== undefined) found.push(handle);
+    }
+    return found;
+  }
+
+  dependsOn(descendant: number, ancestor: number): boolean {
+    return this.dependenciesOf(descendant).has(ancestor);
+  }
+
+  clear(): void {
+    this.triggers.clear();
+    this.creationContexts.clear();
+    this.resolutionCauses.clear();
+    this.handles.clear();
+    this.unattributedChildren.clear();
+    this.attributedRoots.clear();
+    this.roots.clear();
+    this.pending.clear();
+    this.dependencyCache = undefined;
+  }
+
+  private attribute(start: number, root: number): void {
+    const stack = [start];
+    while (stack.length > 0) {
+      const current = stack.pop()!;
+      if (this.attributedRoots.has(current) || this.roots.has(current)) continue;
+      this.attributedRoots.set(current, root);
+      const parked = this.unattributedChildren.get(current);
+      if (parked === undefined) continue;
+      this.unattributedChildren.delete(current);
+      for (const child of parked) stack.push(child);
+    }
+  }
+
+  private park(parent: number, child: number): void {
+    const parked = this.unattributedChildren.get(parent);
+    if (parked === undefined) this.unattributedChildren.set(parent, [child]);
+    else parked.push(child);
+  }
+
+  /**
+   * Everything the promise identified by `start` could have waited for.
+   *
+   * Three edges, and the third is the repair. `trigger` and `resolutionCause`
+   * alone do not connect an async function's resumption context to the context
+   * it was suspended from, so a walk from `done()` reached only the *last*
+   * await's lineage: `const steps = [f.run(a), f.run(b)]; for (const s of steps)
+   * await s;` reported run-1 unawaited even though every step was awaited. The
+   * init-time `executionAsyncId()` — the context a promise was created in — is
+   * that missing edge, and it is a fact the runtime reports, not a widened
+   * approximation.
+   */
+  private dependenciesOf(start: number): ReadonlySet<number> {
+    const cached = this.dependencyCache;
+    if (cached !== undefined && cached.start === start) return cached.found;
+    const found = new Set<number>();
+    const stack = [start];
+    while (stack.length > 0) {
+      const current = stack.pop()!;
+      if (found.has(current)) continue;
+      found.add(current);
+      for (const edge of [
+        this.triggers.get(current),
+        this.resolutionCauses.get(current),
+        this.creationContexts.get(current),
+      ]) {
+        if (edge !== undefined && edge !== current) stack.push(edge);
+      }
+    }
+    this.dependencyCache = { start, found };
+    return found;
+  }
+}

package/src/backlog-picker.ts

@@ -0,0 +1,153 @@
+/**
+ * Gate-3 foundation: choose the next work package from ops/BACKLOG.md.
+ *
+ * The selection rule lived only inside a shell one-liner in
+ * testdata/backlog-picker.flow.yaml, which made the flow's central claim —
+ * that selection is DETERMINISTIC — impossible to assert. Review caught the
+ * missing test (PR #20, P1). A rule that cannot be tested is a rule nobody can
+ * rely on, so it lives here and the flow calls it.
+ *
+ * The rule: the first top-level bullet whose title is bold. Deliberately dull.
+ * A Garden that proposes its own work must be predictable before it is clever
+ * — if two runs over identical input can disagree, nothing downstream can
+ * reason about what the system decided or why.
+ */
+
+/** First bold top-level bullet: `- **Title** rest`. */
+const ENTRY = /^- \*\*(.+?)\*\*\s*(.*(?:\n  .*)*)/m;
+const CODE_REFERENCE = /`([^`]+)`/g;
+// Outcomes include explicit changes and concrete defect statements. A list of
+// identifiers or links alone carries neither, so it cannot qualify as work.
+const ENGINEERING_OUTCOME =
+  /\b(?:add|asserts?|breaks?|build|cannot|capture|catches?|change|close|collapses?|cross-compile|delete|document|drift|duplicates?|fails?|fix|implement|invoke|leaks?|make|missing|must|needs?|no (?:end-to-end )?coverage|persist|refuse|register|replace|reserve|restore|run|scope|should|spawn|untested|update|use|validate|verified?|wire|wrong)\b/i;
+
+export interface BacklogEntry {
+  title: string;
+  body: string;
+}
+
+export interface ValidatedWorkPackage {
+  title: string;
+  files_in_scope: string[];
+  definition_of_done: string[];
+  description?: string;
+  gate?: number | null;
+}
+
+export type WorkPackageValidationReason =
+  | 'missing_title'
+  | 'unterminated_backticks'
+  | 'missing_scope'
+  | 'missing_definition_of_done';
+
+export type WorkPackageValidation =
+  | { accepted: true; work: ValidatedWorkPackage }
+  | { accepted: false; reason: WorkPackageValidationReason };
+
+/**
+ * Returns the selected entry, or null when the backlog holds no actionable
+ * one. Null is a real answer — "nothing to do" — not a failure.
+ */
+export function selectBacklogEntry(markdown: string): BacklogEntry | null {
+  const match = ENTRY.exec(markdown);
+  if (!match) return null;
+  return { title: match[1] ?? '', body: (match[2] ?? '').trim() };
+}
+
+/** Render the selected entry as a work package. */
+export function renderWorkPackage(entry: BacklogEntry): string {
+  return [
+    `# NEXT — ${entry.title}`,
+    '',
+    'Selected from ops/BACKLOG.md by the backlog picker (gate 3).',
+    'Selection rule: the first top-level bullet whose title is bold.',
+    '',
+    '## Scope',
+    '',
+    entry.body || '(the backlog entry carried no detail beyond its title)',
+    '',
+    '## Definition of done',
+    '',
+    'Restate the entry as passing commands before building against it. An entry',
+    'that cannot be turned into a command is not yet a work package.',
+    '',
+  ].join('\n');
+}
+
+/** Accept a complete emitted package, or name the first missing requirement. */
+export function validateWorkPackage(input: unknown): WorkPackageValidation {
+  if (!isRecord(input) || !isNonEmptyString(input['title'])) {
+    return { accepted: false, reason: 'missing_title' };
+  }
+  if (hasUnterminatedBackticks(input)) {
+    return { accepted: false, reason: 'unterminated_backticks' };
+  }
+  if (!isNonEmptyStringArray(input['files_in_scope'])) {
+    return { accepted: false, reason: 'missing_scope' };
+  }
+  if (!isNonEmptyStringArray(input['definition_of_done'])) {
+    return { accepted: false, reason: 'missing_definition_of_done' };
+  }
+  return { accepted: true, work: input as unknown as ValidatedWorkPackage };
+}
+
+/** Whether the backlog text used to derive a package has an unmatched backtick. */
+export function hasUnterminatedBackticks(input: Record<string, unknown>): boolean {
+  const text = [input['title'], input['description']]
+    .filter((value): value is string => typeof value === 'string')
+    .join(' ');
+  return (text.match(/`/g)?.length ?? 0) % 2 === 1;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function isNonEmptyStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.length > 0 && value.every(isNonEmptyString);
+}
+
+/**
+ * Build a work package from a backlog entry.
+ *
+ * This lives in the SDK because two flow steps need it: `select-entry` has to
+ * build a candidate package to know whether an entry is actionable at all, and
+ * `emit-package` has to build the package it emits. When the logic was inlined
+ * in both, the two could drift silently — the flow would select an entry on one
+ * rule and describe it by another.
+ */
+export function packageFromEntry(entry: BacklogEntry): Record<string, unknown> {
+  const blob = `${entry.title} ${entry.body}`;
+  const references = [...entry.body.matchAll(CODE_REFERENCE)].map((match) => match[1] ?? '');
+  const files = [
+    ...new Set(
+      references
+        .filter(
+          (candidate): candidate is string =>
+            /^[A-Za-z_][A-Za-z0-9._-]*(?:\/[A-Za-z0-9._-]*)+$/.test(candidate) &&
+            !/^\/|\/\//.test(candidate),
+        ),
+    ),
+  ];
+  const hasEngineeringOutcome = ENGINEERING_OUTCOME.test(entry.body);
+  // A symbol or command locates work in this repository, but not necessarily
+  // one file. Preserve that honest breadth instead of discarding the signal.
+  if (files.length === 0 && references.length > 0 && hasEngineeringOutcome) {
+    files.push('.');
+  }
+  const gate = blob.match(/\bgate[ -]?(\d+)\b/i);
+  const definitionOfDone = hasEngineeringOutcome
+    ? [entry.title.replace(/[.:]\s*$/, '')]
+    : [];
+  return {
+    title: entry.title,
+    description: entry.body,
+    files_in_scope: files,
+    gate: gate ? Number(gate[1]) : null,
+    definition_of_done: definitionOfDone,
+  };
+}