@graphorin/core 0.6.0 → 0.7.0

package/dist/utils/binary-json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"binary-json.js","names":["B64_LOOKUP: ReadonlyMap<string, number>"],"sources":["../../src/utils/binary-json.ts"],"sourcesContent":["/**\n * JSON-safe projection of binary-bearing message content (W-004).\n *\n * `Message` and `ToolResult.contentParts` carry `Uint8Array | URL`\n * payloads that a naive `JSON.stringify` silently corrupts: a\n * `Uint8Array` turns into an object with numeric keys and a `URL`\n * into `{}`. The wire types below replace those fields with explicit\n * {@link EncodedBytes} / {@link EncodedUrl} envelopes so a run state\n * (or any message transcript) survives `JSON.parse(JSON.stringify(x))`\n * byte-for-byte.\n *\n * The codec is runtime-neutral by design: base64 is hand-rolled (no\n * `Buffer`, no `btoa`) so the module works in browsers, workers and\n * edge runtimes exactly as it does under Node.\n *\n * @packageDocumentation\n */\n\nimport type {\n  AssistantMessage,\n  AudioContent,\n  FileContent,\n  ImageContent,\n  Message,\n  MessageContent,\n  SystemMessage,\n  ToolMessage,\n  UserMessage,\n} from '../types/message.js';\nimport type { PendingSubRun, RunState, RunStep } from '../types/run.js';\nimport type { CompletedToolCall, ToolError, ToolResult } from '../types/tool.js';\n\n/**\n * Base64-encoded binary payload as it appears on the wire.\n *\n * @stable\n */\nexport interface EncodedBytes {\n  readonly enc: 'base64';\n  readonly data: string;\n}\n\n/**\n * URL reference as it appears on the wire (`URL` instances do not\n * survive `JSON.stringify`).\n *\n * @stable\n */\nexport interface EncodedUrl {\n  readonly enc: 'url';\n  readonly href: string;\n}\n\n/**\n * Wire form of a `Uint8Array | URL` binary field.\n *\n * @stable\n */\nexport type EncodedBinary = EncodedBytes | EncodedUrl;\n\n/** Wire twin of {@link ImageContent}. @stable */\nexport interface WireImageContent extends Omit<ImageContent, 'image'> {\n  readonly image: EncodedBinary;\n}\n\n/** Wire twin of {@link AudioContent}. @stable */\nexport interface WireAudioContent extends Omit<AudioContent, 'audio'> {\n  readonly audio: EncodedBinary;\n}\n\n/** Wire twin of {@link FileContent}. @stable */\nexport interface WireFileContent extends Omit<FileContent, 'file'> {\n  readonly file: EncodedBinary;\n}\n\n/**\n * JSON-safe twin of {@link MessageContent}: binary-bearing variants\n * carry {@link EncodedBinary} envelopes, text/reasoning variants pass\n * through untouched.\n *\n * @stable\n */\nexport type WireMessageContent =\n  | Exclude<MessageContent, ImageContent | AudioContent | FileContent>\n  | WireImageContent\n  | WireAudioContent\n  | WireFileContent;\n\n/** Wire twin of {@link UserMessage}. @stable */\nexport interface WireUserMessage extends Omit<UserMessage, 'content'> {\n  readonly content: string | readonly WireMessageContent[];\n}\n\n/** Wire twin of {@link AssistantMessage}. @stable */\nexport interface WireAssistantMessage extends Omit<AssistantMessage, 'content'> {\n  readonly content: string | readonly WireMessageContent[];\n}\n\n/** Wire twin of {@link ToolMessage}. @stable */\nexport interface WireToolMessage extends Omit<ToolMessage, 'content'> {\n  readonly content: string | readonly WireMessageContent[];\n}\n\n/**\n * JSON-safe twin of {@link Message}. System messages are plain strings\n * and pass through unchanged.\n *\n * @stable\n */\nexport type WireMessage = SystemMessage | WireUserMessage | WireAssistantMessage | WireToolMessage;\n\n/** Wire twin of {@link ToolResult}: `contentParts` are encoded. @stable */\nexport type WireToolResult<TOutput = unknown> = Omit<ToolResult<TOutput>, 'contentParts'> & {\n  readonly contentParts?: readonly WireMessageContent[];\n};\n\n/** Wire twin of `ToolOutcome`. @stable */\nexport type WireToolOutcome<TOutput = unknown> = WireToolResult<TOutput> | ToolError;\n\n/** Wire twin of {@link CompletedToolCall}. @stable */\nexport type WireCompletedToolCall<TOutput = unknown> = Omit<\n  CompletedToolCall<TOutput>,\n  'outcome'\n> & {\n  readonly outcome: WireToolOutcome<TOutput>;\n};\n\n/** Wire twin of {@link RunStep}. @stable */\nexport type WireRunStep = Omit<RunStep, 'toolCalls'> & {\n  readonly toolCalls: readonly WireCompletedToolCall[];\n};\n\n/** Wire twin of {@link PendingSubRun}: the child state recurses. @stable */\nexport type WirePendingSubRun = Omit<PendingSubRun, 'state'> & {\n  readonly state: WireRunState;\n};\n\n/**\n * JSON-safe twin of {@link RunState}: `messages`, every\n * `steps[].toolCalls[].outcome.contentParts`, and each parked\n * `pendingSubRuns[].state` (recursively, W-001) are projected through\n * the binary codec. Everything else is structurally identical.\n *\n * `pendingApprovals[].args` and `ToolResult.output` are model-produced\n * JSON and are assumed JSON-safe already - the projection does not\n * walk them.\n *\n * @stable\n */\nexport type WireRunState = Omit<RunState, 'messages' | 'steps' | 'pendingSubRuns'> & {\n  readonly messages: readonly WireMessage[];\n  readonly steps: readonly WireRunStep[];\n  readonly pendingSubRuns?: readonly WirePendingSubRun[];\n};\n\nconst B64_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';\n\nconst B64_LOOKUP: ReadonlyMap<string, number> = new Map(\n  [...B64_ALPHABET].map((ch, i) => [ch, i] as const),\n);\n\n/**\n * Encode bytes as standard (padded) base64 without relying on `Buffer`\n * or `btoa`.\n *\n * @stable\n */\nexport function bytesToBase64(bytes: Uint8Array): string {\n  let out = '';\n  for (let i = 0; i < bytes.length; i += 3) {\n    const b0 = bytes[i] as number;\n    const b1 = i + 1 < bytes.length ? (bytes[i + 1] as number) : undefined;\n    const b2 = i + 2 < bytes.length ? (bytes[i + 2] as number) : undefined;\n    out += B64_ALPHABET[b0 >> 2];\n    out += B64_ALPHABET[((b0 & 0x03) << 4) | ((b1 ?? 0) >> 4)];\n    out += b1 === undefined ? '=' : B64_ALPHABET[((b1 & 0x0f) << 2) | ((b2 ?? 0) >> 6)];\n    out += b2 === undefined ? '=' : B64_ALPHABET[b2 & 0x3f];\n  }\n  return out;\n}\n\n/**\n * Decode standard base64 (padding optional). Throws on characters\n * outside the base64 alphabet.\n *\n * @stable\n */\nexport function base64ToBytes(data: string): Uint8Array {\n  // Strip trailing padding with a loop: /=+$/ backtracks polynomially\n  // on '='-heavy adversarial input (CodeQL js/polynomial-redos).\n  let end = data.length;\n  while (end > 0 && data.charCodeAt(end - 1) === 0x3d /* '=' */) end -= 1;\n  const stripped = data.slice(0, end);\n  const out = new Uint8Array(Math.floor((stripped.length * 6) / 8));\n  let offset = 0;\n  let buffer = 0;\n  let bits = 0;\n  for (const ch of stripped) {\n    const value = B64_LOOKUP.get(ch);\n    if (value === undefined) {\n      throw new Error(`base64ToBytes: invalid base64 character ${JSON.stringify(ch)}`);\n    }\n    buffer = (buffer << 6) | value;\n    bits += 6;\n    if (bits >= 8) {\n      bits -= 8;\n      out[offset] = (buffer >> bits) & 0xff;\n      offset += 1;\n    }\n  }\n  return out;\n}\n\nfunction isRecord(v: unknown): v is Record<string, unknown> {\n  return typeof v === 'object' && v !== null && !Array.isArray(v);\n}\n\nfunction encodeBinary(value: Uint8Array | URL | EncodedBinary): EncodedBinary {\n  if (value instanceof Uint8Array) return { enc: 'base64', data: bytesToBase64(value) };\n  if (value instanceof URL) return { enc: 'url', href: value.href };\n  // Already wire-encoded (idempotent re-projection).\n  return value;\n}\n\n/**\n * Repair the exact corruption `JSON.stringify(Uint8Array)` produces: an\n * object whose keys are the dense indices `0..n-1` with byte values.\n * Applied ONLY to known binary fields of legacy (schema <= 1.1)\n * payloads; anything else is returned as-is.\n */\nfunction repairNumericKeyBytes(value: Record<string, unknown>): Uint8Array | undefined {\n  const keys = Object.keys(value);\n  if (keys.length === 0) return undefined;\n  const out = new Uint8Array(keys.length);\n  for (let i = 0; i < keys.length; i += 1) {\n    const raw = value[String(i)];\n    if (typeof raw !== 'number' || !Number.isInteger(raw) || raw < 0 || raw > 255) {\n      return undefined;\n    }\n    out[i] = raw;\n  }\n  return out;\n}\n\nfunction decodeBinary(value: unknown): Uint8Array | URL | unknown {\n  if (value instanceof Uint8Array || value instanceof URL) return value;\n  if (!isRecord(value)) return value;\n  if (value.enc === 'base64' && typeof value.data === 'string') {\n    return base64ToBytes(value.data);\n  }\n  if (value.enc === 'url' && typeof value.href === 'string') {\n    return new URL(value.href);\n  }\n  // Legacy repair path: schema 1.0/1.1 checkpoints stringified the raw\n  // Uint8Array into a numeric-key object. A corrupted URL serialized to\n  // `{}` and is unrecoverable - it stays as-is.\n  const repaired = repairNumericKeyBytes(value);\n  return repaired ?? value;\n}\n\nfunction encodeContentPart(part: MessageContent | WireMessageContent): WireMessageContent {\n  switch (part.type) {\n    case 'image':\n      return { ...part, image: encodeBinary(part.image) };\n    case 'audio':\n      return { ...part, audio: encodeBinary(part.audio) };\n    case 'file':\n      return { ...part, file: encodeBinary(part.file) };\n    default:\n      return part;\n  }\n}\n\nfunction decodeContentPart(part: WireMessageContent | MessageContent): MessageContent {\n  switch (part.type) {\n    case 'image':\n      return { ...part, image: decodeBinary(part.image) as Uint8Array | URL };\n    case 'audio':\n      return { ...part, audio: decodeBinary(part.audio) as Uint8Array | URL };\n    case 'file':\n      return { ...part, file: decodeBinary(part.file) as Uint8Array | URL };\n    default:\n      return part;\n  }\n}\n\n/**\n * Project multimodal content parts into their JSON-safe wire form.\n * Text and reasoning parts pass through untouched.\n *\n * @stable\n */\nexport function toJsonSafeContentParts(\n  parts: readonly MessageContent[],\n): readonly WireMessageContent[] {\n  return parts.map(encodeContentPart);\n}\n\n/**\n * Inverse of {@link toJsonSafeContentParts}. Accepts legacy corrupted\n * payloads (numeric-key byte objects) and repairs them best-effort.\n *\n * @stable\n */\nexport function fromJsonSafeContentParts(\n  parts: readonly WireMessageContent[],\n): readonly MessageContent[] {\n  return parts.map(decodeContentPart);\n}\n\n/**\n * Project a {@link Message} into its JSON-safe wire form. Idempotent:\n * projecting an already-wire message returns an equivalent value.\n *\n * @stable\n */\nexport function toJsonSafeMessage(message: Message | WireMessage): WireMessage {\n  if (message.role === 'system' || typeof message.content === 'string') {\n    return message as WireMessage;\n  }\n  return { ...message, content: message.content.map(encodeContentPart) } as WireMessage;\n}\n\n/**\n * Inverse of {@link toJsonSafeMessage}.\n *\n * @stable\n */\nexport function fromJsonSafeMessage(message: WireMessage | Message): Message {\n  if (message.role === 'system' || typeof message.content === 'string') {\n    return message as Message;\n  }\n  return { ...message, content: message.content.map(decodeContentPart) } as Message;\n}\n\nfunction encodeOutcome(outcome: CompletedToolCall['outcome']): WireToolOutcome {\n  // Defensive: tolerate loose historical/fixture shapes where the\n  // outcome is missing or not an object.\n  if (isRecord(outcome) && Array.isArray(outcome.contentParts)) {\n    return {\n      ...outcome,\n      contentParts: toJsonSafeContentParts(outcome.contentParts as readonly MessageContent[]),\n    } as WireToolOutcome;\n  }\n  return outcome as WireToolOutcome;\n}\n\nfunction decodeOutcome(outcome: WireToolOutcome): CompletedToolCall['outcome'] {\n  if (isRecord(outcome) && Array.isArray(outcome.contentParts)) {\n    return {\n      ...outcome,\n      contentParts: fromJsonSafeContentParts(outcome.contentParts as readonly WireMessageContent[]),\n    } as CompletedToolCall['outcome'];\n  }\n  return outcome as CompletedToolCall['outcome'];\n}\n\nfunction encodeStep(step: RunStep | WireRunStep): WireRunStep {\n  if (step.toolCalls.length === 0) return step as WireRunStep;\n  return {\n    ...step,\n    toolCalls: step.toolCalls.map((tc) => ({\n      ...tc,\n      outcome: encodeOutcome(tc.outcome as CompletedToolCall['outcome']),\n    })),\n  };\n}\n\nfunction decodeStep(step: WireRunStep): RunStep {\n  if (step.toolCalls.length === 0) return step as unknown as RunStep;\n  return {\n    ...step,\n    toolCalls: step.toolCalls.map((tc) => ({ ...tc, outcome: decodeOutcome(tc.outcome) })),\n  } as unknown as RunStep;\n}\n\n/**\n * Project a full {@link RunState} into its JSON-safe {@link WireRunState}\n * twin: `messages` and `steps[].toolCalls[].outcome.contentParts` go\n * through the binary codec, everything else is copied structurally.\n *\n * @stable\n */\nexport function toJsonSafeRunState(state: RunState | WireRunState): WireRunState {\n  const subRuns = state.pendingSubRuns;\n  return {\n    ...state,\n    messages: state.messages.map(toJsonSafeMessage),\n    steps: state.steps.map(encodeStep),\n    // W-001: parked child states carry binary-bearing messages of their\n    // own - project them recursively (idempotent, like every codec leg).\n    ...(subRuns !== undefined && subRuns.length > 0\n      ? {\n          pendingSubRuns: subRuns.map((sub) => ({\n            ...sub,\n            state: toJsonSafeRunState(sub.state),\n          })),\n        }\n      : {}),\n  } as WireRunState;\n}\n\n/**\n * Inverse of {@link toJsonSafeRunState}. Best-effort: legacy corrupted\n * binary fields (numeric-key byte objects from schema <= 1.1 payloads)\n * are repaired to `Uint8Array`; unrecoverable shapes are left as-is.\n *\n * @stable\n */\nexport function fromJsonSafeRunState(state: WireRunState): RunState {\n  const subRuns = state.pendingSubRuns;\n  return {\n    ...state,\n    messages: state.messages.map(fromJsonSafeMessage),\n    steps: state.steps.map(decodeStep),\n    ...(subRuns !== undefined && subRuns.length > 0\n      ? {\n          pendingSubRuns: subRuns.map((sub) => ({\n            ...sub,\n            state: fromJsonSafeRunState(sub.state),\n          })),\n        }\n      : {}),\n  } as RunState;\n}\n"],"mappings":"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"}

package/dist/utils/index.d.ts

@@ -1,6 +1,7 @@
 import { ValidationResult, ZodLikeError, ZodLikeSafeParseResult, ZodLikeSchema, validate, validateOrThrow } from "./validation.js";
+import { EncodedBinary, EncodedBytes, EncodedUrl, WireAssistantMessage, WireAudioContent, WireCompletedToolCall, WireFileContent, WireImageContent, WireMessage, WireMessageContent, WireRunState, WireRunStep, WireToolMessage, WireToolOutcome, WireToolResult, WireUserMessage, base64ToBytes, bytesToBase64, fromJsonSafeContentParts, fromJsonSafeMessage, fromJsonSafeRunState, toJsonSafeContentParts, toJsonSafeMessage, toJsonSafeRunState } from "./binary-json.js";
 import { assertNever } from "./assert-never.js";
 import { AsyncContext, createAsyncContext } from "./async-context.js";
 import { md5, xxhash } from "./hash.js";
 import { collect, filter, mapStream, merge, take, takeWhile, withSignal } from "./streams.js";
-export { type AsyncContext, type ValidationResult, type ZodLikeError, type ZodLikeSafeParseResult, type ZodLikeSchema, assertNever, collect, createAsyncContext, filter, mapStream, md5, merge, take, takeWhile, validate, validateOrThrow, withSignal, xxhash };
+export { type AsyncContext, type EncodedBinary, type EncodedBytes, type EncodedUrl, type ValidationResult, type WireAssistantMessage, type WireAudioContent, type WireCompletedToolCall, type WireFileContent, type WireImageContent, type WireMessage, type WireMessageContent, type WireRunState, type WireRunStep, type WireToolMessage, type WireToolOutcome, type WireToolResult, type WireUserMessage, type ZodLikeError, type ZodLikeSafeParseResult, type ZodLikeSchema, assertNever, base64ToBytes, bytesToBase64, collect, createAsyncContext, filter, fromJsonSafeContentParts, fromJsonSafeMessage, fromJsonSafeRunState, mapStream, md5, merge, take, takeWhile, toJsonSafeContentParts, toJsonSafeMessage, toJsonSafeRunState, validate, validateOrThrow, withSignal, xxhash };

package/dist/utils/index.js

@@ -1,7 +1,8 @@
+import { base64ToBytes, bytesToBase64, fromJsonSafeContentParts, fromJsonSafeMessage, fromJsonSafeRunState, toJsonSafeContentParts, toJsonSafeMessage, toJsonSafeRunState } from "./binary-json.js";
 import { assertNever } from "./assert-never.js";
 import { createAsyncContext } from "./async-context.js";
 import { md5, xxhash } from "./hash.js";
 import { collect, filter, mapStream, merge, take, takeWhile, withSignal } from "./streams.js";
 import { validate, validateOrThrow } from "./validation.js";
 
-export { assertNever, collect, createAsyncContext, filter, mapStream, md5, merge, take, takeWhile, validate, validateOrThrow, withSignal, xxhash };
+export { assertNever, base64ToBytes, bytesToBase64, collect, createAsyncContext, filter, fromJsonSafeContentParts, fromJsonSafeMessage, fromJsonSafeRunState, mapStream, md5, merge, take, takeWhile, toJsonSafeContentParts, toJsonSafeMessage, toJsonSafeRunState, validate, validateOrThrow, withSignal, xxhash };

package/dist/utils/validation.d.ts

@@ -28,7 +28,16 @@ interface ZodLikeError<_TInput = unknown> {
   readonly name: string;
   readonly message: string;
   readonly issues: ReadonlyArray<{
-    readonly path: ReadonlyArray<string | number>;
+    /**
+     * W-013: `PropertyKey`, not `string | number` - zod 4 bases
+     * `$ZodIssue.path` on `PropertyKey`, and this shim must be a
+     * SUPERSET of both supported peer majors or the canonical
+     * `tool({ inputSchema: z.object({...}) })` fails to typecheck for
+     * every zod@4 consumer. Type-level widening of a produced position
+     * (breaking for downstream code assigning elements to
+     * `string | number`).
+     */
+    readonly path: ReadonlyArray<PropertyKey>;
     readonly message: string;
   }>;
 }

package/dist/utils/validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validation.d.ts","names":[],"sources":["../../src/utils/validation.ts"],"sourcesContent":[],"mappings":";;AASA;;;;;;;;AASY,UATK,aASiB,CAAA,UAAA,OAAA,EAAA,SAAA,OAAA,CAAA,CAAA;EACW,KAAA,CAAA,IAAA,EAAA,OAAA,CAAA,EATrB,OASqB;EACe,SAAA,CAAA,IAAA,EAAA,OAAA,CAAA,EAThC,sBASgC,CATT,OASS,EATA,MASA,CAAA;EAAb;EAAY,SAAA,OAAA,CAAA,EAPtC,OAOsC;EAG1C,SAAA,MAAY,CAAA,EATT,MASS;AAgB7B;AAWA;AAAkD,KAhCtC,sBAgCsC,CAAA,OAAA,EAAA,MAAA,CAAA,GAAA;EAAd,SAAA,OAAA,EAAA,IAAA;EAAmD,SAAA,IAAA,EA/B1C,OA+B0C;CAAjB,GAAA;EAAgB,SAAA,OAAA,EAAA,KAAA;EAatE,SAAA,KAAA,EA3C+B,YA2ChB,CA3C6B,MA2C7B,CAAA;CAA0B;;AAAmC,UAxC3E,YAwC2E,CAAA,UAAA,OAAA,CAAA,CAAA;EAAC,SAAA,IAAA,EAAA,MAAA;;mBArC1E;mBACA;;;;;;;;;;;KAYP;;kBAC6B;;;kBACC;;;;;;;;;iBAS1B,oBAAoB,cAAc,oBAAoB,iBAAiB;;;;;;;;iBAavE,2BAA2B,cAAc,mCAAmC"}
+{"version":3,"file":"validation.d.ts","names":[],"sources":["../../src/utils/validation.ts"],"sourcesContent":[],"mappings":";;AASA;;;;;;;;AASY,UATK,aASiB,CAAA,UAAA,OAAA,EAAA,SAAA,OAAA,CAAA,CAAA;EACW,KAAA,CAAA,IAAA,EAAA,OAAA,CAAA,EATrB,OASqB;EACe,SAAA,CAAA,IAAA,EAAA,OAAA,CAAA,EAThC,sBASgC,CATT,OASS,EATA,MASA,CAAA;EAAb;EAAY,SAAA,OAAA,CAAA,EAPtC,OAOsC;EAG1C,SAAA,MAAY,CAAA,EATT,MASS;;;AAGV,KARP,sBAQO,CAAA,OAAA,EAAA,MAAA,CAAA,GAAA;EAAa,SAAA,OAAA,EAAA,IAAA;EAsBpB,SAAA,IAAA,EA7BiC,OA6BjB;AAW5B,CAAA,GAAgB;EAAkC,SAAA,OAAA,EAAA,KAAA;EAAd,SAAA,KAAA,EAvCW,YAuCX,CAvCwB,MAuCxB,CAAA;CAAmD;;AAAD,UApCrE,YAoCqE,CAAA,UAAA,OAAA,CAAA,CAAA;EAatE,SAAA,IAAA,EAAA,MAAe;EAA0B,SAAA,OAAA,EAAA,MAAA;EAAd,SAAA,MAAA,EA9CxB,aA8CwB,CAAA;IAAiD;;;;;;;;;mBApCzE,cAAc;;;;;;;;;;;KAYrB;;kBAC6B;;;kBACC;;;;;;;;;iBAS1B,oBAAoB,cAAc,oBAAoB,iBAAiB;;;;;;;;iBAavE,2BAA2B,cAAc,mCAAmC"}

package/dist/utils/validation.js

@@ -27,7 +27,7 @@ function validate(schema, data) {
 function validateOrThrow(schema, data, what) {
 	const r = validate(schema, data);
 	if (r.ok) return r.value;
-	const summary = r.error.issues.map((i) => `${i.path.join(".") || "."}: ${i.message}`).join("; ");
+	const summary = r.error.issues.map((i) => `${i.path.map(String).join(".") || "."}: ${i.message}`).join("; ");
 	throw new TypeError(`graphorin: validation failed${what ? ` for ${what}` : ""}: ${summary}`);
 }
 

package/dist/utils/validation.js.map

@@ -1 +1 @@
-{"version":3,"file":"validation.js","names":[],"sources":["../../src/utils/validation.ts"],"sourcesContent":["/**\n * Type-only Zod compatibility shim. We declare a structural type for the\n * subset of `zod` we depend on so that `@graphorin/core` can be type-\n * checked without importing zod directly. Consumers that do `import {\n *   z } from 'zod'` get the real types via the user's `zod` install (the\n * peer dependency).\n *\n * @stable\n */\nexport interface ZodLikeSchema<TOutput = unknown, TInput = unknown> {\n  parse(data: unknown): TOutput;\n  safeParse(data: unknown): ZodLikeSafeParseResult<TOutput, TInput>;\n  /** Internal phantom used by Zod for inference. We don't dereference it. */\n  readonly _output?: TOutput;\n  readonly _input?: TInput;\n}\n\n/** @stable */\nexport type ZodLikeSafeParseResult<TOutput, TInput> =\n  | { readonly success: true; readonly data: TOutput }\n  | { readonly success: false; readonly error: ZodLikeError<TInput> };\n\n/** @stable */\nexport interface ZodLikeError<_TInput = unknown> {\n  readonly name: string;\n  readonly message: string;\n  readonly issues: ReadonlyArray<{\n    readonly path: ReadonlyArray<string | number>;\n    readonly message: string;\n  }>;\n}\n\n/**\n * Validate `data` against `schema` and return a `Result` instead of\n * throwing. Use this in code paths where you want explicit\n * pattern-matching over success / failure.\n *\n * @stable\n */\nexport type ValidationResult<T> =\n  | { readonly ok: true; readonly value: T }\n  | { readonly ok: false; readonly error: ZodLikeError };\n\n/**\n * Synchronous validation wrapper. Does **not** swallow errors thrown by\n * the schema's transformations - only normalizes the success / failure\n * signal.\n *\n * @stable\n */\nexport function validate<T>(schema: ZodLikeSchema<T>, data: unknown): ValidationResult<T> {\n  const result = schema.safeParse(data);\n  if (result.success) return { ok: true, value: result.data };\n  return { ok: false, error: result.error };\n}\n\n/**\n * Throwing variant of `validate(...)` that surfaces a `TypeError` carrying\n * a stable, parser-style message. Useful at module-boundary entry points\n * where a thrown error is the natural failure mode.\n *\n * @stable\n */\nexport function validateOrThrow<T>(schema: ZodLikeSchema<T>, data: unknown, what?: string): T {\n  const r = validate(schema, data);\n  if (r.ok) return r.value;\n  const summary = r.error.issues.map((i) => `${i.path.join('.') || '.'}: ${i.message}`).join('; ');\n  throw new TypeError(`graphorin: validation failed${what ? ` for ${what}` : ''}: ${summary}`);\n}\n"],"mappings":";;;;;;;;AAkDA,SAAgB,SAAY,QAA0B,MAAoC;CACxF,MAAM,SAAS,OAAO,UAAU,KAAK;AACrC,KAAI,OAAO,QAAS,QAAO;EAAE,IAAI;EAAM,OAAO,OAAO;EAAM;AAC3D,QAAO;EAAE,IAAI;EAAO,OAAO,OAAO;EAAO;;;;;;;;;AAU3C,SAAgB,gBAAmB,QAA0B,MAAe,MAAkB;CAC5F,MAAM,IAAI,SAAS,QAAQ,KAAK;AAChC,KAAI,EAAE,GAAI,QAAO,EAAE;CACnB,MAAM,UAAU,EAAE,MAAM,OAAO,KAAK,MAAM,GAAG,EAAE,KAAK,KAAK,IAAI,IAAI,IAAI,IAAI,EAAE,UAAU,CAAC,KAAK,KAAK;AAChG,OAAM,IAAI,UAAU,+BAA+B,OAAO,QAAQ,SAAS,GAAG,IAAI,UAAU"}
+{"version":3,"file":"validation.js","names":[],"sources":["../../src/utils/validation.ts"],"sourcesContent":["/**\n * Type-only Zod compatibility shim. We declare a structural type for the\n * subset of `zod` we depend on so that `@graphorin/core` can be type-\n * checked without importing zod directly. Consumers that do `import {\n *   z } from 'zod'` get the real types via the user's `zod` install (the\n * peer dependency).\n *\n * @stable\n */\nexport interface ZodLikeSchema<TOutput = unknown, TInput = unknown> {\n  parse(data: unknown): TOutput;\n  safeParse(data: unknown): ZodLikeSafeParseResult<TOutput, TInput>;\n  /** Internal phantom used by Zod for inference. We don't dereference it. */\n  readonly _output?: TOutput;\n  readonly _input?: TInput;\n}\n\n/** @stable */\nexport type ZodLikeSafeParseResult<TOutput, TInput> =\n  | { readonly success: true; readonly data: TOutput }\n  | { readonly success: false; readonly error: ZodLikeError<TInput> };\n\n/** @stable */\nexport interface ZodLikeError<_TInput = unknown> {\n  readonly name: string;\n  readonly message: string;\n  readonly issues: ReadonlyArray<{\n    /**\n     * W-013: `PropertyKey`, not `string | number` - zod 4 bases\n     * `$ZodIssue.path` on `PropertyKey`, and this shim must be a\n     * SUPERSET of both supported peer majors or the canonical\n     * `tool({ inputSchema: z.object({...}) })` fails to typecheck for\n     * every zod@4 consumer. Type-level widening of a produced position\n     * (breaking for downstream code assigning elements to\n     * `string | number`).\n     */\n    readonly path: ReadonlyArray<PropertyKey>;\n    readonly message: string;\n  }>;\n}\n\n/**\n * Validate `data` against `schema` and return a `Result` instead of\n * throwing. Use this in code paths where you want explicit\n * pattern-matching over success / failure.\n *\n * @stable\n */\nexport type ValidationResult<T> =\n  | { readonly ok: true; readonly value: T }\n  | { readonly ok: false; readonly error: ZodLikeError };\n\n/**\n * Synchronous validation wrapper. Does **not** swallow errors thrown by\n * the schema's transformations - only normalizes the success / failure\n * signal.\n *\n * @stable\n */\nexport function validate<T>(schema: ZodLikeSchema<T>, data: unknown): ValidationResult<T> {\n  const result = schema.safeParse(data);\n  if (result.success) return { ok: true, value: result.data };\n  return { ok: false, error: result.error };\n}\n\n/**\n * Throwing variant of `validate(...)` that surfaces a `TypeError` carrying\n * a stable, parser-style message. Useful at module-boundary entry points\n * where a thrown error is the natural failure mode.\n *\n * @stable\n */\nexport function validateOrThrow<T>(schema: ZodLikeSchema<T>, data: unknown, what?: string): T {\n  const r = validate(schema, data);\n  if (r.ok) return r.value;\n  // W-013: `Array.prototype.join` THROWS on symbol elements - map to\n  // String first (zod 4 paths are PropertyKey-based).\n  const summary = r.error.issues\n    .map((i) => `${i.path.map(String).join('.') || '.'}: ${i.message}`)\n    .join('; ');\n  throw new TypeError(`graphorin: validation failed${what ? ` for ${what}` : ''}: ${summary}`);\n}\n"],"mappings":";;;;;;;;AA2DA,SAAgB,SAAY,QAA0B,MAAoC;CACxF,MAAM,SAAS,OAAO,UAAU,KAAK;AACrC,KAAI,OAAO,QAAS,QAAO;EAAE,IAAI;EAAM,OAAO,OAAO;EAAM;AAC3D,QAAO;EAAE,IAAI;EAAO,OAAO,OAAO;EAAO;;;;;;;;;AAU3C,SAAgB,gBAAmB,QAA0B,MAAe,MAAkB;CAC5F,MAAM,IAAI,SAAS,QAAQ,KAAK;AAChC,KAAI,EAAE,GAAI,QAAO,EAAE;CAGnB,MAAM,UAAU,EAAE,MAAM,OACrB,KAAK,MAAM,GAAG,EAAE,KAAK,IAAI,OAAO,CAAC,KAAK,IAAI,IAAI,IAAI,IAAI,EAAE,UAAU,CAClE,KAAK,KAAK;AACb,OAAM,IAAI,UAAU,+BAA+B,OAAO,QAAQ,SAAS,GAAG,IAAI,UAAU"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphorin/core",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Core types, contracts, and utilities for the Graphorin framework. Dependency-free root package every other @graphorin/* package depends on.",
   "license": "MIT",
   "author": "Oleksiy Stepurenko",
@@ -22,8 +22,9 @@
     "contracts"
   ],
   "type": "module",
+  "sideEffects": false,
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=22.12.0"
   },
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -31,28 +32,29 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "default": "./dist/index.js"
     },
     "./types": {
       "types": "./dist/types/index.d.ts",
-      "import": "./dist/types/index.js"
+      "default": "./dist/types/index.js"
     },
     "./contracts": {
       "types": "./dist/contracts/index.d.ts",
-      "import": "./dist/contracts/index.js"
+      "default": "./dist/contracts/index.js"
     },
     "./utils": {
       "types": "./dist/utils/index.d.ts",
-      "import": "./dist/utils/index.js"
+      "default": "./dist/utils/index.js"
     },
     "./channels": {
       "types": "./dist/channels/index.d.ts",
-      "import": "./dist/channels/index.js"
+      "default": "./dist/channels/index.js"
     },
     "./package.json": "./package.json"
   },
   "files": [
     "dist",
+    "src",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"

package/src/channels/channels.ts

@@ -0,0 +1,206 @@
+/**
+ * Workflow channel kinds. Every state field declared on a workflow's
+ * `stateSchema` is bound to a channel that decides the merge strategy
+ * applied when multiple writers update the same field within a single
+ * execution step.
+ *
+ * The names are **Graphorin's own design** and must not be aliased to
+ * terms from other workflow libraries. A dedicated lint rule lands later
+ * in the release line to enforce this.
+ *
+ * @stable
+ */
+export type ChannelKind =
+  | 'latest-value'
+  | 'any-value'
+  | 'reducer'
+  | 'list-aggregate'
+  | 'stream'
+  | 'barrier'
+  | 'ephemeral';
+
+/**
+ * Discriminated union of every channel descriptor.
+ *
+ * Channels are a *description* of the merge strategy, not a runtime
+ * value: the engine reads the `kind` field plus optional auxiliary
+ * fields (`reduce`, `from`, `unique`) to decide how to combine writes.
+ *
+ * @stable
+ */
+export type Channel<T = unknown> =
+  | LatestValue<T>
+  | AnyValue<T>
+  | Reducer<T>
+  | ListAggregate<T>
+  | Stream<T>
+  | Barrier<T>
+  | Ephemeral<T>;
+
+/**
+ * Overwrite-on-write. Multiple writes within the same execution step
+ * raise `MultiWriteError` (use `AnyValue` if collisions are acceptable).
+ *
+ * @stable
+ */
+export interface LatestValue<T = unknown> {
+  readonly kind: 'latest-value';
+  readonly default?: T;
+}
+
+/**
+ * Overwrite-on-write - collisions are silently allowed (last-write-wins
+ * semantics within a step).
+ *
+ * @stable
+ */
+export interface AnyValue<T = unknown> {
+  readonly kind: 'any-value';
+  readonly default?: T;
+}
+
+/**
+ * Fold writes via a user-provided `reduce` function. The reducer is
+ * invoked left-to-right over the writes collected within an execution
+ * step.
+ *
+ * @stable
+ */
+export interface Reducer<T = unknown> {
+  readonly kind: 'reducer';
+  readonly default?: T;
+  readonly reduce: (prev: T, next: T) => T;
+}
+
+/**
+ * Specialization of `Reducer<T[]>` that appends each write to a list.
+ *
+ * @stable
+ */
+export interface ListAggregate<T = unknown> {
+  readonly kind: 'list-aggregate';
+  readonly default?: ReadonlyArray<T>;
+}
+
+/**
+ * Append-only queue. Used for dynamic task creation via `Dispatch(...)`
+ * and for application-defined event streams.
+ *
+ * @stable
+ */
+export interface Stream<T = unknown> {
+  readonly kind: 'stream';
+  readonly unique?: boolean;
+  readonly default?: ReadonlyArray<T>;
+}
+
+/**
+ * Barrier - completes when every writer in `from` has produced a value.
+ *
+ * @stable
+ */
+export interface Barrier<T = unknown> {
+  readonly kind: 'barrier';
+  readonly from: ReadonlyArray<string>;
+  readonly default?: T;
+}
+
+/**
+ * Value scoped to a single execution step - discarded when the step
+ * ends.
+ *
+ * @stable
+ */
+export interface Ephemeral<T = unknown> {
+  readonly kind: 'ephemeral';
+  readonly default?: T;
+}
+
+/**
+ * Construct a `LatestValue` channel.
+ *
+ * @stable
+ */
+export function latestValue<T>(opts?: { readonly default?: T }): LatestValue<T> {
+  return opts !== undefined && 'default' in opts && opts.default !== undefined
+    ? { kind: 'latest-value', default: opts.default }
+    : { kind: 'latest-value' };
+}
+
+/**
+ * Construct an `AnyValue` channel.
+ *
+ * @stable
+ */
+export function anyValue<T>(opts?: { readonly default?: T }): AnyValue<T> {
+  return opts !== undefined && 'default' in opts && opts.default !== undefined
+    ? { kind: 'any-value', default: opts.default }
+    : { kind: 'any-value' };
+}
+
+/**
+ * Construct a `Reducer` channel.
+ *
+ * @stable
+ */
+export function reducer<T>(
+  reduce: (prev: T, next: T) => T,
+  opts?: { readonly default?: T },
+): Reducer<T> {
+  return opts !== undefined && 'default' in opts && opts.default !== undefined
+    ? { kind: 'reducer', reduce, default: opts.default }
+    : { kind: 'reducer', reduce };
+}
+
+/**
+ * Construct a `ListAggregate` channel.
+ *
+ * @stable
+ */
+export function listAggregate<T>(opts?: { readonly default?: ReadonlyArray<T> }): ListAggregate<T> {
+  return opts !== undefined && 'default' in opts && opts.default !== undefined
+    ? { kind: 'list-aggregate', default: opts.default }
+    : { kind: 'list-aggregate' };
+}
+
+/**
+ * Construct a `Stream` channel.
+ *
+ * @stable
+ */
+export function stream<T>(opts?: {
+  readonly unique?: boolean;
+  readonly default?: ReadonlyArray<T>;
+}): Stream<T> {
+  const out: { kind: 'stream'; unique?: boolean; default?: ReadonlyArray<T> } = {
+    kind: 'stream',
+  };
+  if (opts?.unique !== undefined) out.unique = opts.unique;
+  if (opts?.default !== undefined) out.default = opts.default;
+  return out;
+}
+
+/**
+ * Construct a `Barrier` channel.
+ *
+ * @stable
+ */
+export function barrier<T>(
+  from: ReadonlyArray<string>,
+  opts?: { readonly default?: T },
+): Barrier<T> {
+  return opts !== undefined && 'default' in opts && opts.default !== undefined
+    ? { kind: 'barrier', from, default: opts.default }
+    : { kind: 'barrier', from };
+}
+
+/**
+ * Construct an `Ephemeral` channel.
+ *
+ * @stable
+ */
+export function ephemeral<T>(opts?: { readonly default?: T }): Ephemeral<T> {
+  return opts !== undefined && 'default' in opts && opts.default !== undefined
+    ? { kind: 'ephemeral', default: opts.default }
+    : { kind: 'ephemeral' };
+}

package/src/channels/directive.ts

@@ -0,0 +1,41 @@
+/**
+ * Workflow control-flow primitive: a single value handed to
+ * `Workflow.resume(threadId, directive?)` (or returned from a node's
+ * `pause(...)` resolution) carrying any combination of:
+ *
+ * - `goto`   - jump to a named node, bypassing the edge graph.
+ *   **Destructive (workflow-09):** the restored frontier is discarded -
+ *   surviving dynamic tasks, completed-but-unwalked nodes, and every
+ *   pending pause record (including already-delivered pause answers)
+ *   are dropped in favour of the single goto task. Use it as an
+ *   operator escape hatch, not routine control flow.
+ * - `resume` - value supplied to the `pause(value)` call that suspended.
+ * - `update` - additional channel writes applied before the next step.
+ *
+ * The shape is **Graphorin's own design** (the name `Directive` is part
+ * of the public API).
+ *
+ * @stable
+ */
+export class Directive<TUpdate = Record<string, unknown>, TResume = unknown> {
+  readonly goto?: string;
+  readonly resume?: TResume;
+  readonly update?: TUpdate;
+
+  constructor(opts: DirectiveOptions<TUpdate, TResume>) {
+    if (opts.goto !== undefined) this.goto = opts.goto;
+    if ('resume' in opts && opts.resume !== undefined) this.resume = opts.resume;
+    if (opts.update !== undefined) this.update = opts.update;
+  }
+}
+
+/**
+ * Constructor parameters for `Directive`.
+ *
+ * @stable
+ */
+export interface DirectiveOptions<TUpdate = Record<string, unknown>, TResume = unknown> {
+  readonly goto?: string;
+  readonly resume?: TResume;
+  readonly update?: TUpdate;
+}

package/src/channels/dispatch.ts

@@ -0,0 +1,37 @@
+/**
+ * Workflow dynamic-task primitive. A node returns one or more
+ * `Dispatch(nodeName, args)` values to schedule additional tasks in the
+ * next execution step.
+ *
+ * The class is intentionally tiny - the engine inspects only the public
+ * `nodeName` and `args` fields. The shape is **Graphorin's own design**
+ * (the name `Dispatch` is part of the public API).
+ *
+ * @stable
+ */
+export class Dispatch<TArgs = unknown> {
+  /**
+   * Cross-realm brand (workflow-13): the engine's structural fallback
+   * requires this marker so a plain state object that happens to carry
+   * `nodeName` + `args` keys is treated as channel WRITES, never
+   * silently swallowed as a dispatch. A plain own property (not a
+   * symbol) so it survives `structuredClone` across worker boundaries.
+   */
+  readonly __graphorinDispatch: true = true;
+  readonly nodeName: string;
+  readonly args: TArgs;
+
+  constructor(nodeName: string, args: TArgs) {
+    this.nodeName = nodeName;
+    this.args = args;
+  }
+}
+
+/**
+ * Convenience factory equivalent to `new Dispatch(nodeName, args)`.
+ *
+ * @stable
+ */
+export function dispatch<TArgs>(nodeName: string, args: TArgs): Dispatch<TArgs> {
+  return new Dispatch(nodeName, args);
+}

package/src/channels/durable.ts

@@ -0,0 +1,151 @@
+/**
+ * Durable workflow primitives (D1) built on the `pause(...)` substrate:
+ *
+ * - {@link sleepUntil} / {@link sleepFor} - **durable timers**: the node
+ *   suspends with a persisted wake-at timestamp; `workflow.tick(threadId)`
+ *   (or any scheduler calling it) resumes the thread once the deadline
+ *   passes. The timer survives process restarts because it lives in the
+ *   checkpointed frontier, not in a `setTimeout`.
+ * - {@link awaitExternal} - **durable promises (awakeables)**: the node
+ *   suspends under a caller-chosen name; an external system resolves it
+ *   later via `workflow.resolveAwakeable(threadId, name, value)` and the
+ *   node receives `value` as the call's return.
+ * - {@link requestApproval} - **first-class persisted approvals**: an
+ *   awakeable specialized for human sign-off, resolved via
+ *   `workflow.approve(threadId, name, decision)`.
+ *
+ * Each helper throws the same branded `PauseSignal` that `pause(...)`
+ * throws, carrying a reserved, JSON-safe pause value the engine
+ * recognises (`kind: 'graphorin.timer' | 'graphorin.awakeable' |
+ * 'graphorin.approval'`) to stamp `wakeAt` / `name` onto the persisted
+ * pause record. On resume the body re-executes from the top and the
+ * already-delivered values replay in order (WF-2), exactly like plain
+ * `pause(...)`.
+ *
+ * @packageDocumentation
+ */
+
+import { pause } from './pause.js';
+
+/** Reserved pause-value kind for durable timers (D1). */
+export const TIMER_PAUSE_KIND = 'graphorin.timer' as const;
+/** Reserved pause-value kind for awakeables / durable promises (D1). */
+export const AWAKEABLE_PAUSE_KIND = 'graphorin.awakeable' as const;
+/** Reserved pause-value kind for persisted approvals (D1). */
+export const APPROVAL_PAUSE_KIND = 'graphorin.approval' as const;
+
+/** Pause value carried by a durable-timer suspension. */
+export interface TimerPauseValue {
+  readonly kind: typeof TIMER_PAUSE_KIND;
+  /** Epoch milliseconds at which the timer becomes due. */
+  readonly wakeAt: number;
+}
+
+/** Pause value carried by an awakeable suspension. */
+export interface AwakeablePauseValue {
+  readonly kind: typeof AWAKEABLE_PAUSE_KIND;
+  /** Caller-chosen name targeted by `workflow.resolveAwakeable(...)`. */
+  readonly name: string;
+}
+
+/** Pause value carried by a persisted-approval suspension. */
+export interface ApprovalPauseValue {
+  readonly kind: typeof APPROVAL_PAUSE_KIND;
+  /** Caller-chosen name targeted by `workflow.approve(...)`. */
+  readonly name: string;
+  /** Free-form payload surfaced to the approver (what is being approved). */
+  readonly payload?: unknown;
+}
+
+/** Type guard for {@link TimerPauseValue}. @stable */
+export function isTimerPauseValue(value: unknown): value is TimerPauseValue {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    (value as { kind?: unknown }).kind === TIMER_PAUSE_KIND &&
+    typeof (value as { wakeAt?: unknown }).wakeAt === 'number'
+  );
+}
+
+/** Type guard for {@link AwakeablePauseValue}. @stable */
+export function isAwakeablePauseValue(value: unknown): value is AwakeablePauseValue {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    (value as { kind?: unknown }).kind === AWAKEABLE_PAUSE_KIND &&
+    typeof (value as { name?: unknown }).name === 'string'
+  );
+}
+
+/** Type guard for {@link ApprovalPauseValue}. @stable */
+export function isApprovalPauseValue(value: unknown): value is ApprovalPauseValue {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    (value as { kind?: unknown }).kind === APPROVAL_PAUSE_KIND &&
+    typeof (value as { name?: unknown }).name === 'string'
+  );
+}
+
+/**
+ * Durably sleep until an absolute instant. Suspends the workflow thread
+ * with a persisted wake-at timestamp; `workflow.tick(threadId)` resumes
+ * it once due. Returns nothing on resume.
+ *
+ * @stable
+ */
+export function sleepUntil(at: string | number | Date): void {
+  const wakeAt = typeof at === 'number' ? at : at instanceof Date ? at.getTime() : Date.parse(at);
+  if (!Number.isFinite(wakeAt)) {
+    throw new TypeError(
+      `[graphorin/core] sleepUntil(...) got an unparseable instant: ${String(at)}`,
+    );
+  }
+  pause<TimerPauseValue, unknown>({ kind: TIMER_PAUSE_KIND, wakeAt });
+}
+
+/**
+ * Durably sleep for a relative duration (sugar over {@link sleepUntil}).
+ *
+ * @stable
+ */
+export function sleepFor(ms: number): void {
+  if (!Number.isFinite(ms) || ms < 0) {
+    throw new TypeError(`[graphorin/core] sleepFor(...) needs a non-negative duration, got ${ms}`);
+  }
+  sleepUntil(Date.now() + ms);
+}
+
+/**
+ * Suspend on a named durable promise. The thread stays suspended (and
+ * survives restarts) until an external caller resolves it via
+ * `workflow.resolveAwakeable(threadId, name, value)`; that `value` is
+ * returned here.
+ *
+ * @stable
+ */
+export function awaitExternal<TResume = unknown>(name: string): TResume {
+  if (typeof name !== 'string' || name.length === 0) {
+    throw new TypeError('[graphorin/core] awaitExternal(name) needs a non-empty name');
+  }
+  return pause<AwakeablePauseValue, TResume>({ kind: AWAKEABLE_PAUSE_KIND, name });
+}
+
+/**
+ * Suspend on a named persisted approval. Resolved by
+ * `workflow.approve(threadId, name, decision)`; the decision is returned
+ * here. The optional payload is surfaced on the pending pause record so
+ * an approval UI can show what is being approved.
+ *
+ * @stable
+ */
+export function requestApproval<TDecision = unknown>(name: string, payload?: unknown): TDecision {
+  if (typeof name !== 'string' || name.length === 0) {
+    throw new TypeError('[graphorin/core] requestApproval(name) needs a non-empty name');
+  }
+  return pause<ApprovalPauseValue, TDecision>({
+    kind: APPROVAL_PAUSE_KIND,
+    name,
+    ...(payload !== undefined ? { payload } : {}),
+  });
+}