@lostgradient/weft 0.2.0

package/dist/core/effect-log/index.d.ts

@@ -0,0 +1,194 @@
+import { WeftError } from '../weft-error.ts';
+/**
+ * Durable effect log for replay deduplication.
+ *
+ * When workflow code is restored from a checkpoint, a non-idempotent external
+ * effect can be requested again while the outcome of the original request is
+ * still unknown. Without a durability fence at the effect boundary, payments,
+ * state mutations, or single-use token presentations can execute twice.
+ *
+ * This module solves the problem with an effect log keyed by a *semantic hash*
+ * of each effect call's intent-critical fields. Before executing an effect,
+ * callers consult the log:
+ *
+ * - **committed** → replay the stored result; skip the effect entirely.
+ * - **in-flight** → the previous run crashed mid-execution; throw
+ *   {@link EffectReplayConflictError} so the caller can escalate.
+ * - **absent** → record as `in-flight`, execute the effect, then
+ *   {@link EffectLog.commit} or {@link EffectLog.abort}.
+ *
+ * The log is backed by the {@link Storage} interface (any KV adapter).
+ * Records are scoped to `(workflowId, operationId)` so parallel branches do not
+ * collide.
+ *
+ * @see arXiv 2603.20625 ("ACRFence") for the threat model and experimental
+ *   evidence that motivated this design.
+ *
+ * @module core/effect-log
+ */
+import type { Storage } from '../../storage/interface.ts';
+import { type JSONValue } from '../json.ts';
+/**
+ * An effect record stored in the log. The `status` field drives deduplication.
+ *
+ * @example Inspect the record returned by EffectLog.lookup
+ * ```ts
+ * import type { EffectRecord } from '@lostgradient/weft';
+ *
+ * function describeRecord(record: EffectRecord): string {
+ *   switch (record.status) {
+ *     case 'in-flight': return `${record.effectName} started at ${record.recordedAt}`;
+ *     case 'committed': return `${record.effectName} -> ${JSON.stringify(record.output)}`;
+ *     case 'aborted':   return `${record.effectName} failed: ${record.reason}`;
+ *   }
+ * }
+ * ```
+ */
+export type EffectRecord = {
+    status: 'in-flight';
+    effectName: string;
+    recordedAt: number;
+} | {
+    status: 'committed';
+    effectName: string;
+    output: JSONValue;
+    completedAt: number;
+} | {
+    status: 'aborted';
+    effectName: string;
+    reason: string;
+    completedAt: number;
+};
+/**
+ * Public contract callers rely on when deduplicating effect calls.
+ *
+ * This narrower type keeps tests honest without forcing them to construct a
+ * full {@link EffectLog} instance when they only need the runtime-facing
+ * methods and counter.
+ *
+ * @example
+ * ```ts
+ * import type { EffectLogLike } from '@lostgradient/weft';
+ *
+ * async function dedupe(log: EffectLogLike, hash: string): Promise<boolean> {
+ *   const existing = await log.lookup(hash);
+ *   return existing !== null;
+ * }
+ * ```
+ */
+export type EffectLogLike = Pick<EffectLog, 'lookup' | 'recordReplay' | 'record' | 'commit' | 'abort' | 'duplicatesPrevented'>;
+/**
+ * Thrown when a caller detects a lingering `in-flight` record during a
+ * checkpoint-restore cycle. This indicates the process crashed between
+ * recording the in-flight intent and receiving the effect
+ * result — the outcome of the original call is unknown.
+ *
+ * Callers should escalate (e.g. human review) rather than silently
+ * re-executing a potentially non-idempotent tool.
+ *
+ * @example Catch a replay conflict and route to human review
+ * ```ts
+ * import { EffectReplayConflictError } from '@lostgradient/weft';
+ *
+ * try {
+ *   // ... effect execution
+ * } catch (error) {
+ *   if (error instanceof EffectReplayConflictError) {
+ *     console.error(
+ *       `Conflict for effect "${error.effectName}" (hash ${error.semanticHash}).`,
+ *       'Route to human review before retrying.',
+ *     );
+ *   }
+ * }
+ * ```
+ */
+export declare class EffectReplayConflictError extends WeftError<'EffectReplayConflictError'> {
+    readonly effectName: string;
+    readonly semanticHash: string;
+    constructor(semanticHash: string, effectName: string);
+}
+/**
+ * Compute a stable 16-character hex semantic hash of an arbitrary input
+ * value. Keys within objects are sorted recursively so that
+ * `{a:1,b:2}` and `{b:2,a:1}` produce the same hash.
+ *
+ * Callers may override this default by hashing only the intent-critical fields
+ * before recording an effect, ignoring fields whose variance does not affect
+ * the observable effect (retry counters, timestamps, nonces).
+ *
+ * @example Hash only the fields that determine a payment's observable effect
+ * ```ts
+ * import { computeSemanticHash } from '@lostgradient/weft';
+ *
+ * const hash = computeSemanticHash({ recipient: 'alice', amount: 100 });
+ * // Key order is irrelevant — same hash regardless of property insertion order.
+ * const sameHash = computeSemanticHash({ amount: 100, recipient: 'alice' });
+ * console.log(hash === sameHash); // true
+ * ```
+ */
+export declare function computeSemanticHash(input: unknown): string;
+/**
+ * Per-operation effect log.
+ *
+ * Scoped to a `(workflowId, operationId)` pair so that concurrent branches do
+ * not share hash space.
+ *
+ * `operationId` should be stable across checkpoint-restore cycles for any
+ * operation that wants deterministic effect replay.
+ *
+ * @example Create and use an EffectLog for durable deduplication
+ * ```ts
+ * import { EffectLog, computeSemanticHash } from '@lostgradient/weft';
+ * import { MemoryStorage } from '@lostgradient/weft/storage/memory';
+ *
+ * const storage = new MemoryStorage();
+ * const log = new EffectLog(storage, 'workflow-abc', 'operation-1');
+ *
+ * const hash = computeSemanticHash({ recipient: 'alice', amount: 100 });
+ * await log.record(hash, 'charge');
+ * await log.commit(hash, 'charge', { success: true });
+ *
+ * const record = await log.lookup(hash);
+ * console.log(record?.status); // 'committed'
+ * ```
+ */
+export declare class EffectLog {
+    #private;
+    constructor(storage: Storage, workflowId: string, operationId: string);
+    /** Number of committed-replay short-circuits recorded during this instance's lifetime. */
+    get duplicatesPrevented(): number;
+    /**
+     * Increment the duplicate-prevention counter.
+     * Called each time a committed replay short-circuits an effect invocation.
+     * Separated from {@link lookup} so callers control when they count a replay.
+     */
+    recordReplay(): void;
+    /**
+     * Look up the effect record for a given semantic hash.
+     * Returns `null` when no record exists.
+     */
+    lookup(semanticHash: string): Promise<EffectRecord | null>;
+    /**
+     * Record an effect call as `in-flight`.
+     *
+     * Call this **before** invoking the effect so that a crash between this
+     * write and the effect response is detectable on restore.
+     */
+    record(semanticHash: string, effectName: string): Promise<void>;
+    /**
+     * Mark the call as `committed` and store the effect output.
+     *
+     * Call this after the effect has returned successfully so that a subsequent
+     * restore will replay this output instead of re-executing.
+     */
+    commit(semanticHash: string, effectName: string, output: unknown): Promise<void>;
+    /**
+     * Mark the call as `aborted` with a reason string.
+     *
+     * Call this when an effect fails and that failure should not be replayed
+     * from the effect log. On restore the caller can re-execute the effect rather
+     * than replaying the error, so only use this for failures where a future retry
+     * is safe and desired.
+     */
+    abort(semanticHash: string, effectName: string, reason: string): Promise<void>;
+}

package/dist/core/effect-log/index.js

@@ -0,0 +1,104 @@
+import { hashString } from "../../runtime/portable.js";
+import { WeftError } from "../weft-error.js";
+import { KEYS } from "../../storage/interface.js";
+import { decode, encode } from "../codec.js";
+import { isJSONValue, normalizeJSONValue } from "../json.js";
+
+export class EffectReplayConflictError extends WeftError {
+  effectName;
+  semanticHash;
+  constructor(semanticHash, effectName) {
+    super("EffectReplayConflictError", `Effect replay conflict: "${effectName}" (semantic hash ${semanticHash}) was in-flight when the process crashed. The outcome of the original call ` + "is unknown \u2014 re-executing a non-idempotent effect may cause duplicate effects. " + "Inspect the effect log or route to human review before retrying.");
+    this.effectName = effectName;
+    this.semanticHash = semanticHash;
+  }
+}
+export function computeSemanticHash(input) {
+  const canonical = canonicalize(input);
+  return hashString(canonical);
+}
+const UNDEFINED_SENTINEL = "\x00undefined";
+function canonicalize(value) {
+  if (value === null)
+    return "null";
+  if (value === void 0)
+    return UNDEFINED_SENTINEL;
+  if (typeof value !== "object")
+    return JSON.stringify(value);
+  if (Array.isArray(value))
+    return "[" + value.map(canonicalize).join(",") + "]";
+  const record = value;
+  return "{" + Object.keys(record).toSorted().filter((key) => record[key] !== void 0).map((key) => `${JSON.stringify(key)}:${canonicalize(record[key])}`).join(",") + "}";
+}
+function isEffectRecord(value) {
+  if (typeof value !== "object" || value === null)
+    return !1;
+  const obj = value;
+  if (typeof obj.status !== "string" || typeof obj.effectName !== "string")
+    return !1;
+  const status = obj.status;
+  if (status === "in-flight")
+    return typeof obj.recordedAt === "number";
+  if (status === "committed")
+    return isJSONValue(obj.output) && typeof obj.completedAt === "number";
+  if (status === "aborted")
+    return typeof obj.reason === "string" && typeof obj.completedAt === "number";
+  return !1;
+}
+
+export class EffectLog {
+  #storage;
+  #workflowId;
+  #operationId;
+  #duplicatesPrevented = 0;
+  constructor(storage, workflowId, operationId) {
+    this.#storage = storage;
+    this.#workflowId = workflowId;
+    this.#operationId = operationId;
+  }
+  get duplicatesPrevented() {
+    return this.#duplicatesPrevented;
+  }
+  recordReplay() {
+    this.#duplicatesPrevented++;
+  }
+  async lookup(semanticHash) {
+    const key = KEYS.toolEffect(this.#workflowId, this.#operationId, semanticHash), bytes = await this.#storage.get(key);
+    if (!bytes)
+      return null;
+    const decoded = decode(bytes);
+    if (!isEffectRecord(decoded))
+      return null;
+    return decoded;
+  }
+  async record(semanticHash, effectName) {
+    const record = {
+      status: "in-flight",
+      effectName,
+      recordedAt: Date.now()
+    };
+    await this.#put(semanticHash, record);
+  }
+  async commit(semanticHash, effectName, output) {
+    const record = {
+      status: "committed",
+      effectName,
+      output: normalizeJSONValue(output),
+      completedAt: Date.now()
+    };
+    await this.#put(semanticHash, record);
+  }
+  async abort(semanticHash, effectName, reason) {
+    const record = {
+      status: "aborted",
+      effectName,
+      reason,
+      completedAt: Date.now()
+    };
+    await this.#put(semanticHash, record);
+  }
+  async#put(semanticHash, record) {
+    const key = KEYS.toolEffect(this.#workflowId, this.#operationId, semanticHash);
+    await this.#storage.put(key, encode(record));
+  }
+}

package/dist/core/engine/activity-reconciliation.d.ts

@@ -0,0 +1,108 @@
+import { type Storage } from '../../storage/interface.ts';
+import type { ContextOperationRequest } from '../context.ts';
+import type { ActivityVerificationContext, ActivityVerificationResult } from '../types.ts';
+import { WeftError } from '../weft-error.ts';
+import type { EngineInternals } from './internals.ts';
+type ActivityOperation = Extract<ContextOperationRequest, {
+    type: 'activity';
+}>;
+export type ActivityReconciliationMetadata = {
+    verify?: (result: unknown, context?: ActivityVerificationContext) => Promise<ActivityVerificationResult> | ActivityVerificationResult;
+    idempotencyKey?: (input: unknown) => string;
+};
+export type ActivityReconciliationRecord = {
+    version: 1;
+    status: 'started';
+    workflowId: string;
+    operationId: string;
+    activityName: string;
+    idempotencyKeyDigest: string;
+    attempt: number;
+    ownerId: string;
+    createdAt: number;
+    updatedAt: number;
+} | {
+    version: 1;
+    status: 'completed';
+    workflowId: string;
+    operationId: string;
+    activityName: string;
+    idempotencyKeyDigest: string;
+    attempt: number;
+    ownerId: string;
+    result: unknown;
+    createdAt: number;
+    updatedAt: number;
+};
+export type ActivityReconciliationReference = {
+    key: string;
+    idempotencyKeyDigest: string;
+};
+/**
+ * Thrown before dispatching a keyed activity when the configured storage
+ * adapter cannot claim the reconciliation marker atomically. Use a storage
+ * adapter with `conditionalBatch` support before relying on Tier-0 activity
+ * result reconciliation.
+ *
+ * @example
+ * ```ts
+ * import { ActivityReconciliationCapabilityError } from '@lostgradient/weft';
+ *
+ * function needsConditionalBatchStorage(error: unknown): boolean {
+ *   return error instanceof ActivityReconciliationCapabilityError;
+ * }
+ * ```
+ */
+export declare class ActivityReconciliationCapabilityError extends WeftError<'ActivityReconciliationCapabilityError'> {
+    constructor();
+}
+/**
+ * Thrown when another engine turn changes the keyed activity reconciliation
+ * marker between the read and the compare-and-set transition. Retry the
+ * workflow turn so it can re-read the current marker state.
+ *
+ * @example
+ * ```ts
+ * import { ActivityReconciliationConflictError } from '@lostgradient/weft';
+ *
+ * function shouldRetryWorkflowTurn(error: unknown): boolean {
+ *   return error instanceof ActivityReconciliationConflictError;
+ * }
+ * ```
+ */
+export declare class ActivityReconciliationConflictError extends WeftError<'ActivityReconciliationConflictError'> {
+    constructor(message: string);
+}
+/**
+ * Thrown when a keyed activity has a prior dispatch marker but the engine
+ * cannot prove whether the external work completed with a reusable result.
+ * This is a fail-closed state: resolve the external side effect manually, then
+ * resume with a verifier that returns a definitive reconciliation state.
+ *
+ * @example
+ * ```ts
+ * import { ActivityReconciliationIndeterminateError } from '@lostgradient/weft';
+ *
+ * function needsOperatorReconciliation(error: unknown): boolean {
+ *   return error instanceof ActivityReconciliationIndeterminateError;
+ * }
+ * ```
+ */
+export declare class ActivityReconciliationIndeterminateError extends WeftError<'ActivityReconciliationIndeterminateError'> {
+    constructor(message: string);
+}
+export declare function buildActivityReconciliationReference(workflowId: string, activityName: string, idempotencyKey: string): Promise<ActivityReconciliationReference>;
+export declare function resolveActivityIdempotencyKey(activity: ActivityReconciliationMetadata | undefined, operation: ActivityOperation): string | undefined;
+export declare function readActivityReconciliationRecord(storage: Storage, key: string): Promise<ActivityReconciliationRecord | null>;
+export declare function validateActivityResultForReconciliation(result: unknown, maxPayloadBytes: number | null): Uint8Array;
+export declare function claimActivityReconciliationStart(storage: Storage, reference: ActivityReconciliationReference, record: ActivityReconciliationRecord): Promise<boolean>;
+export declare function createCompletedActivityReconciliationRecord(startedRecord: ActivityReconciliationRecord, result: unknown, now: number): ActivityReconciliationRecord;
+export declare function resolveStartedActivityReconciliationRecord(internals: EngineInternals, workflowId: string, operation: ActivityOperation, reference: ActivityReconciliationReference, activity: ActivityReconciliationMetadata | undefined, idempotencyKey: string, attempt: number): Promise<ActivityReconciliationRecord | {
+    completedResult: unknown;
+}>;
+export declare function writeActivityReconciliationTransition(storage: Storage, reference: ActivityReconciliationReference, expectedRecord: ActivityReconciliationRecord, nextRecord: ActivityReconciliationRecord): Promise<void>;
+export declare function normalizePreDispatchVerificationResult(result: ActivityVerificationResult): 'not-completed' | 'completed-result-unavailable' | 'indeterminate' | {
+    result: unknown;
+};
+export declare function buildActivityVerificationContext(phase: ActivityVerificationContext['phase'], workflowId: string, operationId: string, activityName: string, input: unknown, idempotencyKey: string | undefined, attempt: number): ActivityVerificationContext;
+export {};

package/dist/core/engine/activity-reconciliation.js

@@ -0,0 +1,182 @@
+import {
+  KEYS,
+  requireStorageCapability,
+  storageConditionalBatch
+} from "../../storage/interface.js";
+import { decode, encode } from "../codec.js";
+import { assertPayloadWithinLimit } from "../payload-size.js";
+import { WeftError } from "../weft-error.js";
+
+export class ActivityReconciliationCapabilityError extends WeftError {
+  constructor() {
+    super("ActivityReconciliationCapabilityError", 'Activity result reconciliation requires storage capability "conditionalBatch".');
+  }
+}
+
+export class ActivityReconciliationConflictError extends WeftError {
+  constructor(message) {
+    super("ActivityReconciliationConflictError", message);
+  }
+}
+
+export class ActivityReconciliationIndeterminateError extends WeftError {
+  constructor(message) {
+    super("ActivityReconciliationIndeterminateError", message);
+  }
+}
+export async function buildActivityReconciliationReference(workflowId, activityName, idempotencyKey) {
+  const idempotencyKeyDigest = await digestIdempotencyKey(idempotencyKey);
+  return {
+    idempotencyKeyDigest,
+    key: KEYS.activityReconciliation(workflowId, activityName, idempotencyKeyDigest)
+  };
+}
+export function resolveActivityIdempotencyKey(activity, operation) {
+  const definitionKey = activity?.idempotencyKey?.(operation.input);
+  if (definitionKey !== void 0)
+    return definitionKey;
+  const optionKey = operation.options?.idempotencyKey;
+  return typeof optionKey === "string" ? optionKey : void 0;
+}
+export async function readActivityReconciliationRecord(storage, key) {
+  const bytes = await storage.get(key);
+  if (bytes === null)
+    return null;
+  return parseActivityReconciliationRecord(decode(bytes));
+}
+export function validateActivityResultForReconciliation(result, maxPayloadBytes) {
+  assertPayloadWithinLimit(result, maxPayloadBytes, "activity result");
+  return encode(result);
+}
+export async function claimActivityReconciliationStart(storage, reference, record) {
+  if (!storage.capabilities().conditionalBatch)
+    throw new ActivityReconciliationCapabilityError;
+  requireStorageCapability(storage, "conditionalBatch", "activity result reconciliation");
+  return storageConditionalBatch(storage, [{ key: reference.key, expectedValue: null }], [{ type: "put", key: reference.key, value: encode(record) }]);
+}
+export function createCompletedActivityReconciliationRecord(startedRecord, result, now) {
+  return {
+    ...startedRecord,
+    status: "completed",
+    result,
+    updatedAt: now
+  };
+}
+export async function resolveStartedActivityReconciliationRecord(internals, workflowId, operation, reference, activity, idempotencyKey, attempt) {
+  let record = await readActivityReconciliationRecord(internals.storage, reference.key);
+  if (record === null) {
+    const claimed = await claimStartedRecord(internals, workflowId, operation, reference, attempt);
+    if (claimed.didClaim)
+      return claimed.record;
+    record = claimed.record;
+  }
+  if (record.status === "completed")
+    return { completedResult: record.result };
+  if (!activity?.verify)
+    throw new ActivityReconciliationIndeterminateError(`Activity "${operation.activityName}" has a prior dispatch marker but no Tier-0 verifier.`);
+  const normalized = normalizePreDispatchVerificationResult(await runPreDispatchVerification(activity, workflowId, operation, idempotencyKey, record));
+  if (normalized === "not-completed") {
+    const nextRecord = {
+      ...record,
+      attempt: record.attempt + 1,
+      ownerId: crypto.randomUUID(),
+      updatedAt: internals.options.getNow()
+    };
+    await writeActivityReconciliationTransition(internals.storage, reference, record, nextRecord);
+    return nextRecord;
+  }
+  if (normalized === "completed-result-unavailable")
+    throw new ActivityReconciliationIndeterminateError(`Activity "${operation.activityName}" completed externally but its result is unavailable.`);
+  if (normalized === "indeterminate")
+    throw new ActivityReconciliationIndeterminateError(`Activity "${operation.activityName}" reconciliation is indeterminate.`);
+  validateActivityResultForReconciliation(normalized.result, internals.options.payloadSizePolicy.maxBytes);
+  const completedRecord = createCompletedActivityReconciliationRecord(record, normalized.result, internals.options.getNow());
+  await writeActivityReconciliationTransition(internals.storage, reference, record, completedRecord);
+  return { completedResult: normalized.result };
+}
+export async function writeActivityReconciliationTransition(storage, reference, expectedRecord, nextRecord) {
+  if (!await storageConditionalBatch(storage, [{ key: reference.key, expectedValue: encode(expectedRecord) }], [{ type: "put", key: reference.key, value: encode(nextRecord) }]))
+    throw new ActivityReconciliationConflictError("Activity reconciliation completion lost compare-and-set ownership.");
+}
+export function normalizePreDispatchVerificationResult(result) {
+  if (result === "not-completed")
+    return "not-completed";
+  if (result === "completed-result-unavailable")
+    return "completed-result-unavailable";
+  if (result === "indeterminate")
+    return "indeterminate";
+  if (typeof result === "object" && result !== null && "status" in result) {
+    const record = result;
+    if (record.status === "completed-with-result")
+      return { result: record.result };
+  }
+  throw new ActivityReconciliationIndeterminateError("Activity verifier did not return a Tier-0 pre-dispatch reconciliation state.");
+}
+export function buildActivityVerificationContext(phase, workflowId, operationId, activityName, input, idempotencyKey, attempt) {
+  return {
+    phase,
+    workflowId,
+    operationId,
+    activityName,
+    input,
+    ...idempotencyKey === void 0 ? {} : { idempotencyKey },
+    attempt
+  };
+}
+function parseActivityReconciliationRecord(value) {
+  if (typeof value !== "object" || value === null)
+    throw new ActivityReconciliationIndeterminateError("Activity reconciliation record is not an object.");
+  const record = value;
+  if (!isActivityReconciliationRecordBase(record))
+    throw new ActivityReconciliationIndeterminateError("Activity reconciliation record has an invalid shape.");
+  if (record.status === "started")
+    return record;
+  if (record.status === "completed" && "result" in record)
+    return record;
+  throw new ActivityReconciliationIndeterminateError("Activity reconciliation record has an unsupported status.");
+}
+async function digestIdempotencyKey(idempotencyKey) {
+  const bytes = new TextEncoder().encode(idempotencyKey), digest = await crypto.subtle.digest("SHA-256", bytes);
+  return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function createStartedRecord(workflowId, operation, reference, attempt, now) {
+  return {
+    version: 1,
+    status: "started",
+    workflowId,
+    operationId: operation.operationId,
+    activityName: operation.activityName,
+    idempotencyKeyDigest: reference.idempotencyKeyDigest,
+    attempt,
+    ownerId: crypto.randomUUID(),
+    createdAt: now,
+    updatedAt: now
+  };
+}
+async function claimStartedRecord(internals, workflowId, operation, reference, attempt) {
+  const startedRecord = createStartedRecord(workflowId, operation, reference, attempt, internals.options.getNow());
+  if (await claimActivityReconciliationStart(internals.storage, reference, startedRecord))
+    return { didClaim: !0, record: startedRecord };
+  const record = await readActivityReconciliationRecord(internals.storage, reference.key);
+  if (record === null)
+    throw new ActivityReconciliationIndeterminateError("Activity reconciliation claim conflicted but no record could be read.");
+  return { didClaim: !1, record };
+}
+async function runPreDispatchVerification(activity, workflowId, operation, idempotencyKey, record) {
+  try {
+    return await activity.verify(void 0, buildActivityVerificationContext("pre-dispatch-reconciliation", workflowId, operation.operationId, operation.activityName, operation.input, idempotencyKey, record.attempt));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new ActivityReconciliationIndeterminateError(`Activity "${operation.activityName}" verifier threw during pre-dispatch reconciliation: ${message}`);
+  }
+}
+function isActivityReconciliationRecordBase(record) {
+  const stringFields = [
+    "workflowId",
+    "operationId",
+    "activityName",
+    "idempotencyKeyDigest",
+    "ownerId"
+  ], numberFields = ["attempt", "createdAt", "updatedAt"];
+  return record.version === 1 && stringFields.every((field) => typeof record[field] === "string") && numberFields.every((field) => typeof record[field] === "number");
+}

package/dist/core/engine/aggregate.d.ts

@@ -0,0 +1,47 @@
+/**
+ * `engine.aggregate()` — group-by counts over a {@link ListFilter}.
+ * Shares the candidate-resolution path with `engine.list()` so the
+ * watermark gate, scan cap, and indexed narrowing behave identically.
+ *
+ * @module core/engine/aggregate
+ */
+import { type AggregateGroupBy, type AggregateOptions } from '../aggregate-validation.ts';
+import type { ListFilter } from '../types.ts';
+import { WeftError } from '../weft-error.ts';
+import type { EngineInternals } from './internals.ts';
+/** One group in an {@link AggregateResult}. `key === null` collects workflows missing the dimension. */
+export type AggregateGroup = {
+    key: string | null;
+    count: number;
+};
+/**
+ * Result of `engine.aggregate()`. `total` is the count of candidates that
+ * passed filtering; `groups` is sorted by `count desc, key asc` and
+ * truncated to the caller's `limit`. `truncated` is `true` when there
+ * were more groups than `limit` allowed.
+ */
+export type AggregateResult = {
+    total: number;
+    groups: AggregateGroup[];
+    truncated: boolean;
+};
+type AggregateExecutionOptions = {
+    distinctKeyCap?: number;
+};
+/**
+ * Thrown when an aggregate `groupBy: { attribute }` references a search
+ * attribute that no registration declares. Maps to an `Unprocessable`
+ * fault at the operation boundary.
+ */
+export declare class UnknownAggregateAttributeError extends WeftError<'UnknownAggregateAttributeError'> {
+    readonly attribute: string;
+    constructor(attribute: string);
+}
+/**
+ * Aggregate workflows by a single dimension. The filter shape matches
+ * `engine.list()`; `limit` and `offset` on the filter are ignored
+ * (aggregation always considers every candidate that passes the rest of
+ * the filter). The aggregate `limit` bounds the returned groups instead.
+ */
+export declare function aggregate(internals: EngineInternals, filter: ListFilter | undefined, options: AggregateOptions, executionOptions?: AggregateExecutionOptions): Promise<AggregateResult>;
+export type { AggregateGroupBy, AggregateOptions };