@graphorin/core 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# @graphorin/core
+
+## 0.1.0
+
+### Minor Changes
+
+- Initial release of the dependency-free root package for the Graphorin
+  framework. Ships the public type system (`Message`, `AgentEvent`,
+  `WorkflowEvent`, `RunContext`, `RunState`, `Usage`, `Sensitivity`,
+  `MemoryKind`, `MemoryMetadata`, `Handoff`, `StopCondition`, …), every
+  cross-package contract interface (`Provider`, `Tool`, `Logger`,
+  `MemoryStore`, `CheckpointStore`, `SessionStore`, `TriggerStore`,
+  `AuthTokenStore`, `EmbedderProvider`, `TokenCounter`, `Tracer`,
+  `AISpan`, `RedactionValidator`, `SecretsStore`, `SecretValue`,
+  `SecretRef`, `SecretResolver`, `Sandbox`, `EvalScorer`, …) and a small
+  set of dependency-free utilities (`collect`, `mapStream`, `merge`,
+  `withSignal`, `assertNever`, `md5`, `xxhash`, …).
+- Workflow channel primitives under `@graphorin/core/channels`:
+  `Directive`, `Dispatch`, `pause`, `LatestValue`, `Reducer`, `Stream`,
+  `Barrier`, `Ephemeral`, `AnyValue`, `ListAggregate` — Graphorin's own
+  vocabulary; names are part of the public API.
+- Typed no-op defaults `NOOP_TRACER` and `NOOP_LOGGER` so downstream
+  packages can carry a non-null observability surface without taking the
+  observability dependency.
+- `zod` is declared as a peer dependency (`^3.23 || ^4`); `@graphorin/core`
+  has no other runtime dependencies and no internal dependencies on any
+  other `@graphorin/*` package.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oleksiy Stepurenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,70 @@
+# @graphorin/core
+
+> The dependency-free root package every other `@graphorin/*` package builds on.
+
+`@graphorin/core` defines the **public type system** and the **cross-package
+contracts** for the Graphorin framework. It contains no runtime: every
+implementation (sandbox, secrets store, memory store, provider adapters,
+agent runtime, workflow engine, server, …) lives in a sibling package and
+depends on the interfaces declared here.
+
+- **Status:** v0.5.0 — type and contract surface for the v0.1 release line.
+- **License:** [MIT](./LICENSE) — © 2026 Oleksiy Stepurenko.
+- **Engines:** Node.js 22+ (ESM only).
+- **Runtime dependencies:** none.
+- **Peer dependency:** `zod` (`^3.23 || ^4`) — used for schema-typed values
+  (`stateSchema`, `inputSchema`, `outputSchema`, `EvalScorer`, …). Bring
+  whichever Zod version your application already uses.
+
+## Installation
+
+```bash
+pnpm add @graphorin/core zod
+```
+
+## What is in here?
+
+The package is organized into four sub-modules with their own `exports`
+sub-paths so that consumers can import only what they need:
+
+| Sub-path                  | Contents                                                                                                |
+| ------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `@graphorin/core`         | Re-export of the entire surface (types + contracts + utilities + channels).                             |
+| `@graphorin/core/types`   | Plain TypeScript types: `Message`, `AgentEvent`, `WorkflowEvent`, `RunContext`, `RunState`, `Usage`, …   |
+| `@graphorin/core/contracts` | Interfaces consumed by other `@graphorin/*` packages: `Provider`, `MemoryStore`, `Tracer`, `Sandbox`, … |
+| `@graphorin/core/utils`   | Tiny dependency-free helpers: `collect`, `mapStream`, `merge`, `withSignal`, `md5`, `xxhash`, …          |
+| `@graphorin/core/channels`| Workflow channel types: `LatestValue`, `Reducer`, `Stream`, `Barrier`, `Ephemeral`, `AnyValue`.          |
+
+## Naming notes
+
+- The workflow primitive set in `@graphorin/core/channels` is **Graphorin's
+  own design**: `Directive` for control flow, `Dispatch` for dynamic tasks,
+  `pause(value)` for programmatic suspension, plus the channel kinds
+  `LatestValue`, `Reducer`, `Stream`, `Barrier`, `Ephemeral`, `AnyValue`.
+  These names are part of the public API and must not be aliased to terms
+  from other workflow libraries (a dedicated lint rule lands later in the
+  release).
+- `SecretValue` is exposed here as an **interface**, not a class: the runtime
+  implementation lives in `@graphorin/security`. Downstream packages typing
+  parameters as `SecretValue` therefore depend only on `@graphorin/core`.
+
+## Stability
+
+Every exported type is annotated with one of two TSDoc tags:
+
+- `@stable` — covered by semver guarantees for the `v0.x` line.
+- `@experimental` — may change between minor versions; a deprecation note
+  in the `CHANGELOG.md` will accompany every removal.
+
+The vast majority of the surface ships as `@stable`; the deliberately
+loose `@experimental` corners exist because their underlying decision
+records are still being refined for v0.2.
+
+## Versioning
+
+`@graphorin/core` follows the same lockstep release as the rest of the
+`@graphorin/*` packages while the framework is on the `0.x` line.
+
+---
+
+**Graphorin** · v0.5.0 · MIT License · © 2026 Oleksiy Stepurenko · <https://github.com/o-stepper/graphorin>

package/dist/channels/channels.d.ts

@@ -0,0 +1,156 @@
+//#region src/channels/channels.d.ts
+/**
+ * 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
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+interface Ephemeral<T = unknown> {
+  readonly kind: 'ephemeral';
+  readonly default?: T;
+}
+/**
+ * Construct a `LatestValue` channel.
+ *
+ * @stable
+ */
+declare function latestValue<T>(opts?: {
+  readonly default?: T;
+}): LatestValue<T>;
+/**
+ * Construct an `AnyValue` channel.
+ *
+ * @stable
+ */
+declare function anyValue<T>(opts?: {
+  readonly default?: T;
+}): AnyValue<T>;
+/**
+ * Construct a `Reducer` channel.
+ *
+ * @stable
+ */
+declare function reducer<T>(reduce: (prev: T, next: T) => T, opts?: {
+  readonly default?: T;
+}): Reducer<T>;
+/**
+ * Construct a `ListAggregate` channel.
+ *
+ * @stable
+ */
+declare function listAggregate<T>(opts?: {
+  readonly default?: ReadonlyArray<T>;
+}): ListAggregate<T>;
+/**
+ * Construct a `Stream` channel.
+ *
+ * @stable
+ */
+declare function stream<T>(opts?: {
+  readonly unique?: boolean;
+  readonly default?: ReadonlyArray<T>;
+}): Stream<T>;
+/**
+ * Construct a `Barrier` channel.
+ *
+ * @stable
+ */
+declare function barrier<T>(from: ReadonlyArray<string>, opts?: {
+  readonly default?: T;
+}): Barrier<T>;
+/**
+ * Construct an `Ephemeral` channel.
+ *
+ * @stable
+ */
+declare function ephemeral<T>(opts?: {
+  readonly default?: T;
+}): Ephemeral<T>;
+//#endregion
+export { AnyValue, Barrier, Channel, ChannelKind, Ephemeral, LatestValue, ListAggregate, Reducer, Stream, anyValue, barrier, ephemeral, latestValue, listAggregate, reducer, stream };
+//# sourceMappingURL=channels.d.ts.map

package/dist/channels/channels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channels.d.ts","names":[],"sources":["../../src/channels/channels.ts"],"sourcesContent":[],"mappings":";;AAYA;AAkBA;;;;;;;;;;AAKI,KAvBQ,WAAA,GAuBR,cAAA,GAAA,WAAA,GAAA,SAAA,GAAA,gBAAA,GAAA,QAAA,GAAA,SAAA,GAAA,WAAA;;;;;;AAUJ;AAWA;AAYA;;AAG0B,KAzCd,OAyCc,CAAA,IAAA,OAAA,CAAA,GAxCtB,WAwCsB,CAxCV,CAwCU,CAAA,GAvCtB,QAuCsB,CAvCb,CAuCa,CAAA,GAtCtB,OAsCsB,CAtCd,CAsCc,CAAA,GArCtB,aAqCsB,CArCR,CAqCQ,CAAA,GApCtB,MAoCsB,CApCf,CAoCe,CAAA,GAnCtB,OAmCsB,CAnCd,CAmCc,CAAA,GAlCtB,SAkCsB,CAlCZ,CAkCY,CAAA;;;;AAQ1B;AAWA;AAWA;AAYiB,UApEA,WAoES,CAAA,IAEJ,OAAA,CAAA,CAAA;EAQN,SAAA,IAAA,EAAW,cAAA;EAAgC,SAAA,OAAA,CAAA,EA5EtC,CA4EsC;;;;AAW3D;;;;AAAsE,UA9ErD,QA8EqD,CAAA,IAAA,OAAA,CAAA,CAAA;EAWtD,SAAA,IAAO,EAAA,WAAA;EACN,SAAA,OAAA,CAAA,EAxFI,CAwFJ;;;;;;;AAajB;;AAA6D,UA3F5C,OA2F4C,CAAA,IAAA,OAAA,CAAA,CAAA;EAAmC,SAAA,IAAA,EAAA,SAAA;EAAd,SAAA,OAAA,CAAA,EAzF7D,CAyF6D;EAAa,SAAA,MAAA,EAAA,CAAA,IAAA,EAxFrE,CAwFqE,EAAA,IAAA,EAxF5D,CAwF4D,EAAA,GAxFtD,CAwFsD;AAW/F;;;;;;AAiBgB,UA5GC,aA4GM,CAAA,IAAA,OAAA,CAAA,CAAA;EACf,SAAA,IAAA,EAAA,gBAAA;EACsB,SAAA,OAAA,CAAA,EA5GT,aA4GS,CA5GK,CA4GL,CAAA;;;;AAY9B;;;;AAAwE,UA/GvD,MA+GuD,CAAA,IAAA,OAAA,CAAA,CAAA;;;qBA5GnD,cAAc;;;;;;;UAQlB;;iBAEA;qBACI;;;;;;;;UASJ;;qBAEI;;;;;;;iBAQL;qBAA2C;IAAM,YAAY;;;;;;iBAW7D;qBAAwC;IAAM,SAAS;;;;;;iBAWvD,0BACC,SAAS,MAAM;qBACF;IAC3B,QAAQ;;;;;;iBAWK;qBAA6C,cAAc;IAAO,cAAc;;;;;;iBAWhF;;qBAEK,cAAc;IAC/B,OAAO;;;;;;iBAcK,iBACR;qBACsB;IAC3B,QAAQ;;;;;;iBAWK;qBAAyC;IAAM,UAAU"}

package/dist/channels/channels.js

@@ -0,0 +1,90 @@
+//#region src/channels/channels.ts
+/**
+* Construct a `LatestValue` channel.
+*
+* @stable
+*/
+function latestValue(opts) {
+	return opts !== void 0 && "default" in opts && opts.default !== void 0 ? {
+		kind: "latest-value",
+		default: opts.default
+	} : { kind: "latest-value" };
+}
+/**
+* Construct an `AnyValue` channel.
+*
+* @stable
+*/
+function anyValue(opts) {
+	return opts !== void 0 && "default" in opts && opts.default !== void 0 ? {
+		kind: "any-value",
+		default: opts.default
+	} : { kind: "any-value" };
+}
+/**
+* Construct a `Reducer` channel.
+*
+* @stable
+*/
+function reducer(reduce, opts) {
+	return opts !== void 0 && "default" in opts && opts.default !== void 0 ? {
+		kind: "reducer",
+		reduce,
+		default: opts.default
+	} : {
+		kind: "reducer",
+		reduce
+	};
+}
+/**
+* Construct a `ListAggregate` channel.
+*
+* @stable
+*/
+function listAggregate(opts) {
+	return opts !== void 0 && "default" in opts && opts.default !== void 0 ? {
+		kind: "list-aggregate",
+		default: opts.default
+	} : { kind: "list-aggregate" };
+}
+/**
+* Construct a `Stream` channel.
+*
+* @stable
+*/
+function stream(opts) {
+	const out = { kind: "stream" };
+	if (opts?.unique !== void 0) out.unique = opts.unique;
+	if (opts?.default !== void 0) out.default = opts.default;
+	return out;
+}
+/**
+* Construct a `Barrier` channel.
+*
+* @stable
+*/
+function barrier(from, opts) {
+	return opts !== void 0 && "default" in opts && opts.default !== void 0 ? {
+		kind: "barrier",
+		from,
+		default: opts.default
+	} : {
+		kind: "barrier",
+		from
+	};
+}
+/**
+* Construct an `Ephemeral` channel.
+*
+* @stable
+*/
+function ephemeral(opts) {
+	return opts !== void 0 && "default" in opts && opts.default !== void 0 ? {
+		kind: "ephemeral",
+		default: opts.default
+	} : { kind: "ephemeral" };
+}
+
+//#endregion
+export { anyValue, barrier, ephemeral, latestValue, listAggregate, reducer, stream };
+//# sourceMappingURL=channels.js.map

package/dist/channels/channels.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channels.js","names":["out: { kind: 'stream'; unique?: boolean; default?: ReadonlyArray<T> }"],"sources":["../../src/channels/channels.ts"],"sourcesContent":["/**\n * Workflow channel kinds. Every state field declared on a workflow's\n * `stateSchema` is bound to a channel that decides the merge strategy\n * applied when multiple writers update the same field within a single\n * execution step.\n *\n * The names are **Graphorin's own design** and must not be aliased to\n * terms from other workflow libraries. A dedicated lint rule lands later\n * in the release line to enforce this.\n *\n * @stable\n */\nexport type ChannelKind =\n  | 'latest-value'\n  | 'any-value'\n  | 'reducer'\n  | 'list-aggregate'\n  | 'stream'\n  | 'barrier'\n  | 'ephemeral';\n\n/**\n * Discriminated union of every channel descriptor.\n *\n * Channels are a *description* of the merge strategy, not a runtime\n * value: the engine reads the `kind` field plus optional auxiliary\n * fields (`reduce`, `from`, `unique`) to decide how to combine writes.\n *\n * @stable\n */\nexport type Channel<T = unknown> =\n  | LatestValue<T>\n  | AnyValue<T>\n  | Reducer<T>\n  | ListAggregate<T>\n  | Stream<T>\n  | Barrier<T>\n  | Ephemeral<T>;\n\n/**\n * Overwrite-on-write. Multiple writes within the same execution step\n * raise `MultiWriteError` (use `AnyValue` if collisions are acceptable).\n *\n * @stable\n */\nexport interface LatestValue<T = unknown> {\n  readonly kind: 'latest-value';\n  readonly default?: T;\n}\n\n/**\n * Overwrite-on-write — collisions are silently allowed (last-write-wins\n * semantics within a step).\n *\n * @stable\n */\nexport interface AnyValue<T = unknown> {\n  readonly kind: 'any-value';\n  readonly default?: T;\n}\n\n/**\n * Fold writes via a user-provided `reduce` function. The reducer is\n * invoked left-to-right over the writes collected within an execution\n * step.\n *\n * @stable\n */\nexport interface Reducer<T = unknown> {\n  readonly kind: 'reducer';\n  readonly default?: T;\n  readonly reduce: (prev: T, next: T) => T;\n}\n\n/**\n * Specialization of `Reducer<T[]>` that appends each write to a list.\n *\n * @stable\n */\nexport interface ListAggregate<T = unknown> {\n  readonly kind: 'list-aggregate';\n  readonly default?: ReadonlyArray<T>;\n}\n\n/**\n * Append-only queue. Used for dynamic task creation via `Dispatch(...)`\n * and for application-defined event streams.\n *\n * @stable\n */\nexport interface Stream<T = unknown> {\n  readonly kind: 'stream';\n  readonly unique?: boolean;\n  readonly default?: ReadonlyArray<T>;\n}\n\n/**\n * Barrier — completes when every writer in `from` has produced a value.\n *\n * @stable\n */\nexport interface Barrier<T = unknown> {\n  readonly kind: 'barrier';\n  readonly from: ReadonlyArray<string>;\n  readonly default?: T;\n}\n\n/**\n * Value scoped to a single execution step — discarded when the step\n * ends.\n *\n * @stable\n */\nexport interface Ephemeral<T = unknown> {\n  readonly kind: 'ephemeral';\n  readonly default?: T;\n}\n\n/**\n * Construct a `LatestValue` channel.\n *\n * @stable\n */\nexport function latestValue<T>(opts?: { readonly default?: T }): LatestValue<T> {\n  return opts !== undefined && 'default' in opts && opts.default !== undefined\n    ? { kind: 'latest-value', default: opts.default }\n    : { kind: 'latest-value' };\n}\n\n/**\n * Construct an `AnyValue` channel.\n *\n * @stable\n */\nexport function anyValue<T>(opts?: { readonly default?: T }): AnyValue<T> {\n  return opts !== undefined && 'default' in opts && opts.default !== undefined\n    ? { kind: 'any-value', default: opts.default }\n    : { kind: 'any-value' };\n}\n\n/**\n * Construct a `Reducer` channel.\n *\n * @stable\n */\nexport function reducer<T>(\n  reduce: (prev: T, next: T) => T,\n  opts?: { readonly default?: T },\n): Reducer<T> {\n  return opts !== undefined && 'default' in opts && opts.default !== undefined\n    ? { kind: 'reducer', reduce, default: opts.default }\n    : { kind: 'reducer', reduce };\n}\n\n/**\n * Construct a `ListAggregate` channel.\n *\n * @stable\n */\nexport function listAggregate<T>(opts?: { readonly default?: ReadonlyArray<T> }): ListAggregate<T> {\n  return opts !== undefined && 'default' in opts && opts.default !== undefined\n    ? { kind: 'list-aggregate', default: opts.default }\n    : { kind: 'list-aggregate' };\n}\n\n/**\n * Construct a `Stream` channel.\n *\n * @stable\n */\nexport function stream<T>(opts?: {\n  readonly unique?: boolean;\n  readonly default?: ReadonlyArray<T>;\n}): Stream<T> {\n  const out: { kind: 'stream'; unique?: boolean; default?: ReadonlyArray<T> } = {\n    kind: 'stream',\n  };\n  if (opts?.unique !== undefined) out.unique = opts.unique;\n  if (opts?.default !== undefined) out.default = opts.default;\n  return out;\n}\n\n/**\n * Construct a `Barrier` channel.\n *\n * @stable\n */\nexport function barrier<T>(\n  from: ReadonlyArray<string>,\n  opts?: { readonly default?: T },\n): Barrier<T> {\n  return opts !== undefined && 'default' in opts && opts.default !== undefined\n    ? { kind: 'barrier', from, default: opts.default }\n    : { kind: 'barrier', from };\n}\n\n/**\n * Construct an `Ephemeral` channel.\n *\n * @stable\n */\nexport function ephemeral<T>(opts?: { readonly default?: T }): Ephemeral<T> {\n  return opts !== undefined && 'default' in opts && opts.default !== undefined\n    ? { kind: 'ephemeral', default: opts.default }\n    : { kind: 'ephemeral' };\n}\n"],"mappings":";;;;;;AA2HA,SAAgB,YAAe,MAAiD;AAC9E,QAAO,SAAS,UAAa,aAAa,QAAQ,KAAK,YAAY,SAC/D;EAAE,MAAM;EAAgB,SAAS,KAAK;EAAS,GAC/C,EAAE,MAAM,gBAAgB;;;;;;;AAQ9B,SAAgB,SAAY,MAA8C;AACxE,QAAO,SAAS,UAAa,aAAa,QAAQ,KAAK,YAAY,SAC/D;EAAE,MAAM;EAAa,SAAS,KAAK;EAAS,GAC5C,EAAE,MAAM,aAAa;;;;;;;AAQ3B,SAAgB,QACd,QACA,MACY;AACZ,QAAO,SAAS,UAAa,aAAa,QAAQ,KAAK,YAAY,SAC/D;EAAE,MAAM;EAAW;EAAQ,SAAS,KAAK;EAAS,GAClD;EAAE,MAAM;EAAW;EAAQ;;;;;;;AAQjC,SAAgB,cAAiB,MAAkE;AACjG,QAAO,SAAS,UAAa,aAAa,QAAQ,KAAK,YAAY,SAC/D;EAAE,MAAM;EAAkB,SAAS,KAAK;EAAS,GACjD,EAAE,MAAM,kBAAkB;;;;;;;AAQhC,SAAgB,OAAU,MAGZ;CACZ,MAAMA,MAAwE,EAC5E,MAAM,UACP;AACD,KAAI,MAAM,WAAW,OAAW,KAAI,SAAS,KAAK;AAClD,KAAI,MAAM,YAAY,OAAW,KAAI,UAAU,KAAK;AACpD,QAAO;;;;;;;AAQT,SAAgB,QACd,MACA,MACY;AACZ,QAAO,SAAS,UAAa,aAAa,QAAQ,KAAK,YAAY,SAC/D;EAAE,MAAM;EAAW;EAAM,SAAS,KAAK;EAAS,GAChD;EAAE,MAAM;EAAW;EAAM;;;;;;;AAQ/B,SAAgB,UAAa,MAA+C;AAC1E,QAAO,SAAS,UAAa,aAAa,QAAQ,KAAK,YAAY,SAC/D;EAAE,MAAM;EAAa,SAAS,KAAK;EAAS,GAC5C,EAAE,MAAM,aAAa"}

package/dist/channels/directive.d.ts

@@ -0,0 +1,34 @@
+//#region src/channels/directive.d.ts
+/**
+ * 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.
+ * - `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
+ */
+declare class Directive<TUpdate = Record<string, unknown>, TResume = unknown> {
+  readonly goto?: string;
+  readonly resume?: TResume;
+  readonly update?: TUpdate;
+  constructor(opts: DirectiveOptions<TUpdate, TResume>);
+}
+/**
+ * Constructor parameters for `Directive`.
+ *
+ * @stable
+ */
+interface DirectiveOptions<TUpdate = Record<string, unknown>, TResume = unknown> {
+  readonly goto?: string;
+  readonly resume?: TResume;
+  readonly update?: TUpdate;
+}
+//#endregion
+export { Directive, DirectiveOptions };
+//# sourceMappingURL=directive.d.ts.map

package/dist/channels/directive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"directive.d.ts","names":[],"sources":["../../src/channels/directive.ts"],"sourcesContent":[],"mappings":";;AAcA;;;;;;;;AAiBA;;;;;cAjBa,oBAAoB;;oBAEb;oBACA;oBAEA,iBAAiB,SAAS;;;;;;;UAY7B,2BAA2B;;oBAExB;oBACA"}

package/dist/channels/directive.js

@@ -0,0 +1,29 @@
+//#region src/channels/directive.ts
+/**
+* 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.
+* - `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
+*/
+var Directive = class {
+	goto;
+	resume;
+	update;
+	constructor(opts) {
+		if (opts.goto !== void 0) this.goto = opts.goto;
+		if ("resume" in opts && opts.resume !== void 0) this.resume = opts.resume;
+		if (opts.update !== void 0) this.update = opts.update;
+	}
+};
+
+//#endregion
+export { Directive };
+//# sourceMappingURL=directive.js.map

package/dist/channels/directive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"directive.js","names":[],"sources":["../../src/channels/directive.ts"],"sourcesContent":["/**\n * Workflow control-flow primitive: a single value handed to\n * `Workflow.resume(threadId, directive?)` (or returned from a node's\n * `pause(...)` resolution) carrying any combination of:\n *\n * - `goto`   — jump to a named node, bypassing the edge graph.\n * - `resume` — value supplied to the `pause(value)` call that suspended.\n * - `update` — additional channel writes applied before the next step.\n *\n * The shape is **Graphorin's own design** (the name `Directive` is part\n * of the public API).\n *\n * @stable\n */\nexport class Directive<TUpdate = Record<string, unknown>, TResume = unknown> {\n  readonly goto?: string;\n  readonly resume?: TResume;\n  readonly update?: TUpdate;\n\n  constructor(opts: DirectiveOptions<TUpdate, TResume>) {\n    if (opts.goto !== undefined) this.goto = opts.goto;\n    if ('resume' in opts && opts.resume !== undefined) this.resume = opts.resume;\n    if (opts.update !== undefined) this.update = opts.update;\n  }\n}\n\n/**\n * Constructor parameters for `Directive`.\n *\n * @stable\n */\nexport interface DirectiveOptions<TUpdate = Record<string, unknown>, TResume = unknown> {\n  readonly goto?: string;\n  readonly resume?: TResume;\n  readonly update?: TUpdate;\n}\n"],"mappings":";;;;;;;;;;;;;;;AAcA,IAAa,YAAb,MAA6E;CAC3E,AAAS;CACT,AAAS;CACT,AAAS;CAET,YAAY,MAA0C;AACpD,MAAI,KAAK,SAAS,OAAW,MAAK,OAAO,KAAK;AAC9C,MAAI,YAAY,QAAQ,KAAK,WAAW,OAAW,MAAK,SAAS,KAAK;AACtE,MAAI,KAAK,WAAW,OAAW,MAAK,SAAS,KAAK"}

package/dist/channels/dispatch.d.ts

@@ -0,0 +1,26 @@
+//#region src/channels/dispatch.d.ts
+/**
+ * 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
+ */
+declare class Dispatch<TArgs = unknown> {
+  readonly nodeName: string;
+  readonly args: TArgs;
+  constructor(nodeName: string, args: TArgs);
+}
+/**
+ * Convenience factory equivalent to `new Dispatch(nodeName, args)`.
+ *
+ * @stable
+ */
+declare function dispatch<TArgs>(nodeName: string, args: TArgs): Dispatch<TArgs>;
+//#endregion
+export { Dispatch, dispatch };
+//# sourceMappingURL=dispatch.d.ts.map

package/dist/channels/dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.d.ts","names":[],"sources":["../../src/channels/dispatch.ts"],"sourcesContent":[],"mappings":";;AAWA;AAeA;;;;;;;;;cAfa;;iBAEI;sCAEqB;;;;;;;iBAWtB,wCAAwC,QAAQ,SAAS"}

package/dist/channels/dispatch.js

@@ -0,0 +1,32 @@
+//#region src/channels/dispatch.ts
+/**
+* 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
+*/
+var Dispatch = class {
+	nodeName;
+	args;
+	constructor(nodeName, args) {
+		this.nodeName = nodeName;
+		this.args = args;
+	}
+};
+/**
+* Convenience factory equivalent to `new Dispatch(nodeName, args)`.
+*
+* @stable
+*/
+function dispatch(nodeName, args) {
+	return new Dispatch(nodeName, args);
+}
+
+//#endregion
+export { Dispatch, dispatch };
+//# sourceMappingURL=dispatch.js.map

package/dist/channels/dispatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.js","names":[],"sources":["../../src/channels/dispatch.ts"],"sourcesContent":["/**\n * Workflow dynamic-task primitive. A node returns one or more\n * `Dispatch(nodeName, args)` values to schedule additional tasks in the\n * next execution step.\n *\n * The class is intentionally tiny — the engine inspects only the public\n * `nodeName` and `args` fields. The shape is **Graphorin's own design**\n * (the name `Dispatch` is part of the public API).\n *\n * @stable\n */\nexport class Dispatch<TArgs = unknown> {\n  readonly nodeName: string;\n  readonly args: TArgs;\n\n  constructor(nodeName: string, args: TArgs) {\n    this.nodeName = nodeName;\n    this.args = args;\n  }\n}\n\n/**\n * Convenience factory equivalent to `new Dispatch(nodeName, args)`.\n *\n * @stable\n */\nexport function dispatch<TArgs>(nodeName: string, args: TArgs): Dispatch<TArgs> {\n  return new Dispatch(nodeName, args);\n}\n"],"mappings":";;;;;;;;;;;;AAWA,IAAa,WAAb,MAAuC;CACrC,AAAS;CACT,AAAS;CAET,YAAY,UAAkB,MAAa;AACzC,OAAK,WAAW;AAChB,OAAK,OAAO;;;;;;;;AAShB,SAAgB,SAAgB,UAAkB,MAA8B;AAC9E,QAAO,IAAI,SAAS,UAAU,KAAK"}

package/dist/channels/index.d.ts

@@ -0,0 +1,5 @@
+import { AnyValue, Barrier, Channel, ChannelKind, Ephemeral, LatestValue, ListAggregate, Reducer, Stream, anyValue, barrier, ephemeral, latestValue, listAggregate, reducer, stream } from "./channels.js";
+import { Directive, DirectiveOptions } from "./directive.js";
+import { Dispatch, dispatch } from "./dispatch.js";
+import { PAUSE_SIGNAL_BRAND, PauseResumeScope, PauseSignal, isPauseSignal, pause, runWithPauseResume } from "./pause.js";
+export { type AnyValue, type Barrier, type Channel, type ChannelKind, Directive, type DirectiveOptions, Dispatch, type Ephemeral, type LatestValue, type ListAggregate, PAUSE_SIGNAL_BRAND, type PauseResumeScope, PauseSignal, type Reducer, type Stream, anyValue, barrier, dispatch, ephemeral, isPauseSignal, latestValue, listAggregate, pause, reducer, runWithPauseResume, stream };

package/dist/channels/index.js

@@ -0,0 +1,6 @@
+import { anyValue, barrier, ephemeral, latestValue, listAggregate, reducer, stream } from "./channels.js";
+import { Directive } from "./directive.js";
+import { Dispatch, dispatch } from "./dispatch.js";
+import { PAUSE_SIGNAL_BRAND, PauseSignal, isPauseSignal, pause, runWithPauseResume } from "./pause.js";
+
+export { Directive, Dispatch, PAUSE_SIGNAL_BRAND, PauseSignal, anyValue, barrier, dispatch, ephemeral, isPauseSignal, latestValue, listAggregate, pause, reducer, runWithPauseResume, stream };

package/dist/channels/pause.d.ts

@@ -0,0 +1,84 @@
+//#region src/channels/pause.d.ts
+/**
+ * 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
+ */
+declare const PAUSE_SIGNAL_BRAND: unique symbol;
+/**
+ * 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
+ */
+declare class PauseSignal<TValue = unknown> extends Error {
+  readonly [PAUSE_SIGNAL_BRAND]: true;
+  readonly value: TValue;
+  constructor(value: TValue);
+}
+/**
+ * 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
+ */
+interface PauseResumeScope {
+  /** Ordered resume values replayed to successive `pause()` calls (WF-2). */
+  readonly values: ReadonlyArray<unknown>;
+  cursor: number;
+}
+/**
+ * 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
+ */
+declare function runWithPauseResume<R>(values: ReadonlyArray<unknown>, fn: () => R | Promise<R>): Promise<R>;
+/**
+ * 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
+ */
+declare function pause<TValue, TResume = unknown>(value: TValue): TResume;
+/**
+ * Cross-realm safe type guard for `PauseSignal`.
+ *
+ * @stable
+ */
+declare function isPauseSignal(err: unknown): err is PauseSignal;
+//#endregion
+export { PAUSE_SIGNAL_BRAND, PauseResumeScope, PauseSignal, isPauseSignal, pause, runWithPauseResume };
+//# sourceMappingURL=pause.d.ts.map

package/dist/channels/pause.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pause.d.ts","names":[],"sources":["../../src/channels/pause.ts"],"sourcesContent":[],"mappings":";;AASA;AAYA;;;;;AAAwD,cAZ3C,kBAY2C,EAAA,OAAA,MAAA;AAwBxD;AAwBA;;;;;;;;AAuBA;AAegB,cAtFH,WAsFgB,CAAuB,SAAA,OAAW,CAAA,SAtFZ,KAAA,CAsFY;YArFnD,kBAAA;kBACM;qBAEG;;;;;;;;;;;;;;;UAoBJ,gBAAA;;mBAEE;;;;;;;;;;;;;;;;;;;iBAsBH,8BACN,kCACE,IAAI,QAAQ,KACrB,QAAQ;;;;;;;;;;;;;;;;iBAoBK,wCAAwC,SAAS;;;;;;iBAejD,aAAA,uBAAoC"}