@graphorin/core 0.6.0 → 0.7.0

package/src/channels/index.ts

@@ -0,0 +1,62 @@
+/**
+ * Workflow channel kinds + control-flow primitives.
+ *
+ * Names are Graphorin's own design (`Directive`, `Dispatch`, `pause`,
+ * `LatestValue`, `Reducer`, `Stream`, `Barrier`, `Ephemeral`, `AnyValue`)
+ * and must not be aliased to terms from other workflow libraries.
+ *
+ * @packageDocumentation
+ */
+
+export type {
+  AnyValue,
+  Barrier,
+  Channel,
+  ChannelKind,
+  Ephemeral,
+  LatestValue,
+  ListAggregate,
+  Reducer,
+  Stream,
+} from './channels.js';
+export {
+  anyValue,
+  barrier,
+  ephemeral,
+  latestValue,
+  listAggregate,
+  reducer,
+  stream,
+} from './channels.js';
+
+export type { DirectiveOptions } from './directive.js';
+export { Directive } from './directive.js';
+export { Dispatch, dispatch } from './dispatch.js';
+export type {
+  ApprovalPauseValue,
+  AwakeablePauseValue,
+  TimerPauseValue,
+} from './durable.js';
+export {
+  APPROVAL_PAUSE_KIND,
+  AWAKEABLE_PAUSE_KIND,
+  awaitExternal,
+  isApprovalPauseValue,
+  isAwakeablePauseValue,
+  isTimerPauseValue,
+  requestApproval,
+  sleepFor,
+  sleepUntil,
+  TIMER_PAUSE_KIND,
+} from './durable.js';
+export type { PauseIdentity, PauseResumeScope } from './pause.js';
+export {
+  isPauseSignal,
+  isReplayDivergenceSignal,
+  PAUSE_SIGNAL_BRAND,
+  PauseSignal,
+  pause,
+  REPLAY_DIVERGENCE_BRAND,
+  ReplayDivergenceSignal,
+  runWithPauseResume,
+} from './pause.js';

package/src/channels/pause.ts

@@ -0,0 +1,216 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+/**
+ * Brand attached to the signal thrown by `pause(value)` so that the
+ * workflow runtime can recognise it across realms (Worker threads,
+ * sandboxes, …) without `instanceof`.
+ *
+ * @stable
+ */
+export const PAUSE_SIGNAL_BRAND: unique symbol = Symbol.for('graphorin.PauseSignal');
+
+/**
+ * Thrown by `pause(value)` from inside a workflow node. The runtime
+ * catches it, persists state with a pending pause, and suspends the
+ * thread until `Workflow.resume(threadId, directive)` is called.
+ *
+ * Application code should never construct or catch this directly -
+ * always go through `pause(...)`.
+ *
+ * @stable
+ */
+export class PauseSignal<TValue = unknown> extends Error {
+  readonly [PAUSE_SIGNAL_BRAND]: true = true;
+  readonly value: TValue;
+
+  constructor(value: TValue) {
+    super('graphorin: workflow paused');
+    this.name = 'PauseSignal';
+    this.value = value;
+  }
+}
+
+/**
+ * Brand attached to the signal thrown by `pause(value)` when the
+ * positional replay diverges from the journaled pause identity
+ * (W-120). Cross-realm safe like {@link PAUSE_SIGNAL_BRAND}.
+ *
+ * @stable
+ */
+export const REPLAY_DIVERGENCE_BRAND: unique symbol = Symbol.for(
+  'graphorin.ReplayDivergenceSignal',
+);
+
+/**
+ * Identity of one pause as recorded next to its satisfied resume value
+ * (W-120): the durable-primitive `kind` (`timer` / `awakeable` /
+ * `approval`) and the awakeable/approval `name`. A plain `pause()` has
+ * neither - two plain pauses are indistinguishable BY DESIGN (no
+ * false positives; the check is deliberately conservative).
+ *
+ * @stable
+ */
+export interface PauseIdentity {
+  readonly kind?: string;
+  readonly name?: string;
+}
+
+/**
+ * Thrown by `pause(value)` during replay when the CURRENT pause's
+ * identity does not match what the journal recorded for this cursor
+ * position (W-120): the node body's pause order depends on
+ * time/state/LLM output, so a positional replay would silently hand a
+ * resume value to the wrong pause. The workflow engine converts this
+ * into a typed `pause-replay-divergence` WorkflowError.
+ *
+ * @stable
+ */
+export class ReplayDivergenceSignal extends Error {
+  readonly [REPLAY_DIVERGENCE_BRAND]: true = true;
+  readonly expected: PauseIdentity;
+  readonly actual: PauseIdentity;
+  readonly cursor: number;
+
+  constructor(expected: PauseIdentity, actual: PauseIdentity, cursor: number) {
+    super(
+      `graphorin: pause replay divergence at cursor ${cursor}: paused as ${describeIdentity(actual)} where the journal recorded ${describeIdentity(expected)}`,
+    );
+    this.name = 'ReplayDivergenceSignal';
+    this.expected = expected;
+    this.actual = actual;
+    this.cursor = cursor;
+  }
+}
+
+/** Cross-realm safe type guard for {@link ReplayDivergenceSignal}. @stable */
+export function isReplayDivergenceSignal(err: unknown): err is ReplayDivergenceSignal {
+  return (
+    typeof err === 'object' &&
+    err !== null &&
+    (err as Record<symbol, unknown>)[REPLAY_DIVERGENCE_BRAND] === true
+  );
+}
+
+function describeIdentity(id: PauseIdentity): string {
+  const parts: string[] = [];
+  if (id.kind !== undefined) parts.push(`kind '${id.kind}'`);
+  if (id.name !== undefined) parts.push(`name '${id.name}'`);
+  return parts.length > 0 ? parts.join(' / ') : 'a plain pause';
+}
+
+/**
+ * Extract the {@link PauseIdentity} of a pause payload: generic field
+ * access only (no import of the durable-primitive types - that would
+ * cycle).
+ */
+function identityOfPauseValue(value: unknown): PauseIdentity {
+  if (typeof value !== 'object' || value === null) return {};
+  const v = value as { readonly kind?: unknown; readonly name?: unknown };
+  return {
+    ...(typeof v.kind === 'string' ? { kind: v.kind } : {}),
+    ...(typeof v.name === 'string' ? { name: v.name } : {}),
+  };
+}
+
+/**
+ * Resume-injection scope set by the workflow runtime around the second
+ * (and later) invocations of a paused node body. When the scope is
+ * present, `pause(...)` consults it to decide whether to throw a fresh
+ * {@link PauseSignal} or return the injected value the runtime supplied
+ * via `Workflow.resume(threadId, new Directive({ resume }))`.
+ *
+ * This is the storage mechanism that gives `pause()` its symmetric
+ * pair semantics (`pause` ↔ `resume`) without forcing every node body
+ * to be re-architected as a state machine.
+ *
+ * @internal
+ */
+export interface PauseResumeScope {
+  /** Ordered resume values replayed to successive `pause()` calls (WF-2). */
+  readonly values: ReadonlyArray<unknown>;
+  /**
+   * W-120: per-value identity of the pause each value answered.
+   * Absent (legacy checkpoints) or `null`/empty entries skip the check.
+   */
+  readonly meta?: ReadonlyArray<PauseIdentity | null | undefined>;
+  cursor: number;
+}
+
+const pauseResumeStorage = new AsyncLocalStorage<PauseResumeScope>();
+
+/**
+ * Run `fn` inside a scope where successive `pause(...)` calls return the
+ * supplied `values` in order instead of throwing a fresh
+ * {@link PauseSignal} (WF-2: a node body re-executes from the top on
+ * every resume, so earlier pauses must replay their already-delivered
+ * values and only the FIRST unsatisfied `pause()` suspends again). An
+ * empty `values` array behaves exactly like no scope - every `pause()`
+ * suspends - which is what a static-gate resume needs so a programmatic
+ * `pause()` inside the node is never silently satisfied.
+ *
+ * This helper is the contract between the runtime and `pause(...)`.
+ * Consumers of `pause(...)` never call it directly - only the workflow
+ * engine wires it up around the resumed node body.
+ *
+ * @internal
+ */
+export function runWithPauseResume<R>(
+  values: ReadonlyArray<unknown>,
+  fn: () => R | Promise<R>,
+  meta?: ReadonlyArray<PauseIdentity | null | undefined>,
+): Promise<R> {
+  const scope: PauseResumeScope = { values, ...(meta !== undefined ? { meta } : {}), cursor: 0 };
+  return pauseResumeStorage.run(scope, async () => fn());
+}
+
+/**
+ * Programmatically suspend the current workflow node. The `value` is
+ * surfaced to callers via the `WorkflowSuspendedEvent.value` field; the
+ * eventual `Directive({ resume })` is delivered as the return value of
+ * this call once the runtime resumes the thread.
+ *
+ * Implementation note: when the call is made outside a runtime-managed
+ * resume scope, `pause(...)` throws a fresh {@link PauseSignal} so the
+ * engine can catch it, persist state, and suspend. When the runtime
+ * later resumes the node body, it wraps the second invocation in
+ * {@link runWithPauseResume}, which causes the same `pause(...)` call to
+ * return the operator-supplied resume value instead of throwing.
+ *
+ * @stable
+ */
+export function pause<TValue, TResume = unknown>(value: TValue): TResume {
+  const scope = pauseResumeStorage.getStore();
+  if (scope !== undefined && scope.cursor < scope.values.length) {
+    // W-120: verify the replayed value is answering the SAME pause the
+    // journal recorded at this cursor. Legacy checkpoints (no meta) and
+    // plain pauses (empty identity) replay unchecked - conservative by
+    // design, false positives are impossible.
+    const expected = scope.meta?.[scope.cursor];
+    if (expected != null && (expected.kind !== undefined || expected.name !== undefined)) {
+      const actual = identityOfPauseValue(value);
+      if (
+        (expected.kind !== undefined && expected.kind !== actual.kind) ||
+        (expected.name !== undefined && expected.name !== actual.name)
+      ) {
+        throw new ReplayDivergenceSignal(expected, actual, scope.cursor);
+      }
+    }
+    const next = scope.values[scope.cursor];
+    scope.cursor += 1;
+    return next as TResume;
+  }
+  throw new PauseSignal<TValue>(value);
+}
+
+/**
+ * Cross-realm safe type guard for `PauseSignal`.
+ *
+ * @stable
+ */
+export function isPauseSignal(err: unknown): err is PauseSignal {
+  return (
+    typeof err === 'object' &&
+    err !== null &&
+    (err as Record<symbol, unknown>)[PAUSE_SIGNAL_BRAND] === true
+  );
+}

package/src/contracts/auth-token-store.ts

@@ -0,0 +1,42 @@
+/**
+ * Persisted server auth token record. Holds a per-token HMAC hash + scope
+ * grammar; raw tokens are never persisted (the runtime carries them via
+ * `SecretValue`).
+ *
+ * @stable
+ */
+export interface AuthTokenRecord {
+  /** Stable identifier (the public part of the token, before the secret). */
+  readonly id: string;
+  /** HMAC-SHA256 of the secret part, peppered. Hex-encoded. */
+  readonly hashHex: string;
+  /** Optional human-readable label rendered in CLI listings. */
+  readonly label?: string;
+  /** Scope grammar - opaque strings of the form `<resource>:<action>[:<id-or-glob>]`. */
+  readonly scopes: ReadonlyArray<string>;
+  readonly createdAt: string;
+  readonly expiresAt?: string;
+  readonly revokedAt?: string;
+  readonly lastUsedAt?: string;
+}
+
+/**
+ * Pluggable storage for server auth tokens. The default implementation
+ * lives in `@graphorin/store-sqlite` (`auth_tokens` table). The server
+ * package implements `verifyToken(...)` on top of this contract.
+ *
+ * @stable
+ */
+export interface AuthTokenStore {
+  put(record: AuthTokenRecord): Promise<void>;
+  get(id: string): Promise<AuthTokenRecord | null>;
+  list(): Promise<ReadonlyArray<AuthTokenRecord>>;
+  revoke(id: string, revokedAt: string): Promise<void>;
+  recordUse(id: string, usedAt: string): Promise<void>;
+  /**
+   * Indexed lookup by HMAC hash (SPL-19). When present, the verifier
+   * uses it on cache-miss instead of walking `list()` - O(1) instead of
+   * an O(n) full-table scan per verification.
+   */
+  getByHash?(hashHex: string): Promise<AuthTokenRecord | null>;
+}

package/src/contracts/checkpoint-store.ts

@@ -0,0 +1,256 @@
+/**
+ * Opaque identifier for a single workflow checkpoint. Treated as a string
+ * by every consumer so adapters can pick whatever encoding they prefer
+ * (ULID, UUID, snowflake-like, …).
+ *
+ * @stable
+ */
+export type CheckpointId = string;
+
+/**
+ * Serialized snapshot of workflow state, written after every execution
+ * step.
+ *
+ * @stable
+ */
+export interface Checkpoint {
+  readonly id: CheckpointId;
+  readonly threadId: string;
+  readonly namespace: string;
+  readonly parentId?: CheckpointId;
+  /** Serialized state blob - adapter-specific encoding (JSON / superjson / …). */
+  readonly state: unknown;
+  /** Per-channel monotonic versions used by the workflow scheduler. */
+  readonly channelVersions: Readonly<Record<string, number>>;
+  readonly stepNumber: number;
+  readonly createdAt: string;
+}
+
+/**
+ * Metadata associated with a checkpoint write. Adapters store this in a
+ * sidecar table for efficient listing.
+ *
+ * @stable
+ */
+export interface CheckpointMetadata {
+  /**
+   * Durability mode that produced this write. The legacy `'async'`
+   * value was removed (workflow-14 / WF-7 - it was byte-identical to
+   * `'sync'`); adapters normalize legacy persisted rows to `'sync'` at
+   * read time.
+   */
+  readonly source: 'sync' | 'exit';
+  readonly status: 'running' | 'suspended' | 'completed' | 'failed' | 'aborted';
+  readonly nodeName?: string;
+  readonly tags?: ReadonlyArray<string>;
+  /**
+   * Session this checkpoint's state belongs to, when known (W-005).
+   * The agent runtime stamps it on every HITL-suspend write so a
+   * session hard-delete can cascade into `workflow_checkpoints` /
+   * `workflow_pending_writes` without parsing the opaque state blob.
+   * Optional and additive: third-party stores may ignore it, but any
+   * store that also implements `SessionStoreExt.deleteSession` should
+   * use it to honour the full erasure contract.
+   */
+  readonly sessionId?: string;
+  /**
+   * W-032: earliest due durable timer among this checkpoint's frontier
+   * pauses (epoch ms). The workflow engine stamps it on every
+   * `suspended` write whose frontier holds a timer, so a store's
+   * {@link CheckpointStore.listSuspended} can enumerate due threads
+   * without parsing the opaque tags. Absent on non-timer suspends and
+   * on checkpoints written before the field existed - such threads
+   * need one manual `tick` (or a resume) to become driver-visible.
+   */
+  readonly wakeAt?: number;
+}
+
+/**
+ * A checkpoint paired with its sidecar metadata. Returned by
+ * `CheckpointStore.getTuple(...)` and the `list(...)` iterator.
+ *
+ * @stable
+ */
+export interface CheckpointTuple {
+  readonly checkpoint: Checkpoint;
+  readonly metadata: CheckpointMetadata;
+  readonly pendingWrites?: ReadonlyArray<PendingWrite>;
+}
+
+/**
+ * Per-task pending write. Captured when a task in an execution step
+ * succeeds while a sibling task fails: the next resume attempt skips the
+ * already-completed work.
+ *
+ * @stable
+ */
+export interface PendingWrite {
+  readonly taskId: string;
+  readonly index: number;
+  readonly channel: string;
+  /** Serialized value blob - adapter-specific encoding. */
+  readonly value: unknown;
+}
+
+/**
+ * Optional listing range for `CheckpointStore.list(...)`.
+ *
+ * @stable
+ */
+export interface ListOptions {
+  readonly limit?: number;
+  readonly before?: CheckpointId;
+  readonly status?: CheckpointMetadata['status'];
+}
+
+/**
+ * Optional atomicity contract for {@link CheckpointStore.put} (D1 /
+ * workflow-01). When `expectedLatestId` is supplied, the store MUST
+ * perform the latest-checkpoint comparison and the insert atomically
+ * (single transaction / synchronous critical section) and throw
+ * {@link CheckpointConflictError} on mismatch - closing the TOCTOU
+ * window an engine-level read-then-write cannot. `null` means "expect
+ * no checkpoint for this thread yet"; `undefined` (or a store that
+ * ignores the argument) preserves the unguarded legacy behaviour, which
+ * the engine backstops with its own pre-check.
+ *
+ * @stable
+ */
+export interface CheckpointPutOptions {
+  readonly expectedLatestId?: CheckpointId | null;
+}
+
+/**
+ * Thrown by a {@link CheckpointStore.put} honouring
+ * {@link CheckpointPutOptions.expectedLatestId} when another writer
+ * advanced the thread in between. The workflow engine maps it to its
+ * `checkpoint-version-conflict` error.
+ *
+ * @stable
+ */
+export class CheckpointConflictError extends Error {
+  readonly threadId: string;
+  readonly expectedLatestId: CheckpointId | null;
+  readonly actualLatestId: CheckpointId | null;
+
+  constructor(threadId: string, expected: CheckpointId | null, actual: CheckpointId | null) {
+    super(
+      `checkpoint conflict on thread "${threadId}": expected latest ${expected ?? '<none>'}, found ${actual ?? '<none>'}`,
+    );
+    this.name = 'CheckpointConflictError';
+    this.threadId = threadId;
+    this.expectedLatestId = expected;
+    this.actualLatestId = actual;
+  }
+}
+
+/**
+ * Pluggable checkpoint storage interface. The default implementation
+ * lives in `@graphorin/store-sqlite`.
+ *
+ * @stable
+ */
+export interface CheckpointStore {
+  put(
+    threadId: string,
+    namespace: string,
+    checkpoint: Checkpoint,
+    metadata: CheckpointMetadata,
+    opts?: CheckpointPutOptions,
+  ): Promise<CheckpointId>;
+
+  putWrites(
+    threadId: string,
+    namespace: string,
+    checkpointId: CheckpointId,
+    writes: ReadonlyArray<PendingWrite>,
+    taskId: string,
+  ): Promise<void>;
+
+  getTuple(
+    threadId: string,
+    namespace: string,
+    checkpointId?: CheckpointId,
+  ): Promise<CheckpointTuple | null>;
+
+  list(threadId: string, namespace: string, opts?: ListOptions): AsyncIterable<CheckpointTuple>;
+
+  /**
+   * Full erasure primitive: delete every checkpoint and pending write of
+   * this thread across ALL namespaces. Namespace-blind by contract -
+   * retention sweeps must use {@link CheckpointStoreExt.pruneThreads}
+   * instead, which is namespace-scoped and protects suspended threads.
+   */
+  deleteThread(threadId: string): Promise<void>;
+
+  /**
+   * W-032: enumerate threads whose LATEST checkpoint in `namespace` is
+   * `suspended` with a due `wakeAt` (`<= opts.dueBefore`, default: any
+   * stamped wakeAt). This is what a durable-timer driver polls -
+   * without it an operator would have to keep an external registry of
+   * sleeping threadIds. OPTIONAL so third-party stores compile
+   * unchanged; `createTimerDriver` throws a typed error when the store
+   * lacks it (deterministic policy, no silent no-op).
+   */
+  listSuspended?(
+    namespace: string,
+    opts?: { readonly dueBefore?: number; readonly limit?: number },
+  ): Promise<ReadonlyArray<{ readonly threadId: string; readonly wakeAt: number }>>;
+}
+
+/**
+ * Options for {@link CheckpointStoreExt.pruneThreads}.
+ *
+ * @stable
+ */
+export interface PruneThreadsOptions {
+  /**
+   * Cutoff: a `(threadId, namespace)` pair qualifies when its LATEST
+   * checkpoint (by `stepNumber`) was created before this epoch-ms
+   * instant.
+   */
+  readonly beforeEpochMs: number;
+  /**
+   * When `true` (the default), only pairs whose latest checkpoint has a
+   * terminal status (`completed` / `failed` / `aborted`) are pruned -
+   * suspended threads hold live HITL approvals / awakeables and must
+   * survive a retention sweep. Set to `false` for a hard age-based
+   * sweep that also removes suspended threads.
+   */
+  readonly onlyTerminal?: boolean;
+}
+
+/**
+ * Retention extension over {@link CheckpointStore} (W-009). The engine
+ * intentionally never deletes finished threads itself - a completed
+ * thread is still needed for inspection and duplicate-resume refusal;
+ * how long to keep it is an operator decision. These primitives are
+ * what an operator (or a host scheduler) drives.
+ *
+ * Additive: third-party `CheckpointStore` implementations compile
+ * unchanged; hosts feature-detect with `'pruneThreads' in store`.
+ *
+ * @stable
+ */
+export interface CheckpointStoreExt extends CheckpointStore {
+  /**
+   * Namespace-scoped retention sweep: for every `(threadId, namespace)`
+   * pair matching the policy, delete that pair's checkpoints and pending
+   * writes - and ONLY that pair's. Never implemented via
+   * {@link CheckpointStore.deleteThread} (namespace-blind): with a
+   * reused threadId, pruning a terminal thread of workflow A must not
+   * erase the suspended checkpoints of workflow B. Returns the number
+   * of pairs pruned.
+   */
+  pruneThreads(opts: PruneThreadsOptions): Promise<number>;
+
+  /**
+   * Keep only the `keepLast` most recent checkpoints (by `stepNumber`)
+   * of one `(threadId, namespace)` pair, deleting older ones together
+   * with their pending writes. `keepLast >= 1`; resume works from the
+   * latest tuple, so compaction never breaks resumability - it does
+   * remove time-travel/fork targets. Returns the number of checkpoints
+   * deleted.
+   */
+  compactThread(threadId: string, namespace: string, keepLast: number): Promise<number>;
+}

package/src/contracts/embedder.ts

@@ -0,0 +1,42 @@
+/**
+ * Pluggable embedding provider. Implementations live in the embedder
+ * adapter packages (`@graphorin/embedder-transformersjs` (default),
+ * `@graphorin/embedder-ollama`, …).
+ *
+ * Each embedder advertises its model `id`, output `dim`, and a stable
+ * `configHash` used by the multi-table per-embedder vec0 layout in the
+ * default SQLite store: facts indexed under embedder A and facts indexed
+ * under embedder B live in separate vec0 tables; the `configHash` is the
+ * lookup key.
+ *
+ * @stable
+ */
+export interface EmbedderProvider {
+  /** Stable identifier (e.g. `'transformersjs:Xenova/multilingual-e5-base'`). */
+  id(): string;
+  /** Output dimensionality of the embedding vectors. */
+  dim(): number;
+  /** Stable hash of the embedder's configuration (model + revision + opts). */
+  configHash(): string;
+  /** Compute embeddings for a batch of texts. Returns one vector per text. */
+  embed(texts: ReadonlyArray<string>, opts?: EmbedOptions): Promise<ReadonlyArray<Float32Array>>;
+}
+
+/**
+ * Per-call options for `EmbedderProvider.embed(...)`.
+ *
+ * @stable
+ */
+export interface EmbedOptions {
+  readonly signal?: AbortSignal;
+  /** Optional per-call request id forwarded to the trace span. */
+  readonly requestId?: string;
+  /**
+   * Asymmetric retrieval role of the input (PS-10). Embedders for models that
+   * require asymmetric prefixes - the E5 family's `query:` / `passage:` - apply
+   * the matching prefix; embedders for symmetric models ignore it. Memory tiers
+   * pass `'query'` when embedding a search query and `'passage'` when embedding
+   * content for storage.
+   */
+  readonly taskType?: 'query' | 'passage';
+}

package/src/contracts/eval-scorer.ts

@@ -0,0 +1,44 @@
+/**
+ * Pluggable evaluation scorer. Generic over the input / output types
+ * carried by the eval dataset. Concrete implementations live in the
+ * separate `@graphorin/evals` package (post-MVP); the interface lives
+ * here so that:
+ *
+ * - The minimal inline runner shipped with `@graphorin/observability` can
+ *   type-check against it.
+ * - Custom application-level scorers can be defined without taking an
+ *   evals dependency.
+ *
+ * @stable
+ */
+export interface EvalScorer<TInput = unknown, TOutput = unknown> {
+  readonly id: string;
+  readonly description?: string;
+  score(sample: EvalSample<TInput, TOutput>): Promise<EvalScore>;
+}
+
+/**
+ * A single sample from an eval dataset.
+ *
+ * @stable
+ */
+export interface EvalSample<TInput = unknown, TOutput = unknown> {
+  readonly id: string;
+  readonly input: TInput;
+  readonly expected?: TOutput;
+  readonly actual: TOutput;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * Result of `EvalScorer.score(...)`. `value` is normalized to `[0, 1]`
+ * by convention; raw scores can be carried in `details`.
+ *
+ * @stable
+ */
+export interface EvalScore {
+  readonly value: number;
+  readonly pass?: boolean;
+  readonly rationale?: string;
+  readonly details?: Readonly<Record<string, unknown>>;
+}