@graphorin/core 0.5.0

package/dist/types/usage.d.ts

@@ -0,0 +1,82 @@
+//#region src/types/usage.d.ts
+/**
+ * Token / cost metrics for a single LLM call.
+ *
+ * `cost` is optional because the framework cannot compute it without a
+ * pricing snapshot — providers/middleware fill it in (e.g. through the
+ * separate `@graphorin/pricing` package) when the snapshot is available.
+ *
+ * @stable
+ */
+interface Usage {
+  promptTokens: number;
+  completionTokens: number;
+  reasoningTokens?: number;
+  totalTokens: number;
+  cost?: Cost;
+}
+/**
+ * Money figure attached to a `Usage`. Always carries a 3-letter currency
+ * code so that consumers can perform aggregation safely.
+ *
+ * @stable
+ */
+interface Cost {
+  /** Amount in the smallest fractional unit of the declared currency. */
+  amount: number;
+  /** ISO-4217 currency code; default `'USD'`. */
+  currency: string;
+}
+/**
+ * Per-model breakdown used by aggregators (e.g. `CostTracker` in
+ * `@graphorin/observability`).
+ *
+ * @stable
+ */
+interface ModelUsage {
+  modelId: string;
+  promptTokens: number;
+  completionTokens: number;
+  reasoningTokens?: number;
+  totalTokens: number;
+  cost?: Cost;
+  callCount: number;
+}
+/**
+ * A live accumulator of token / cost figures. Implementations live in
+ * `@graphorin/observability`. The contract sits here so every package
+ * (agent, workflow, server, …) can type a parameter as `UsageAccumulator`
+ * without taking an observability dependency.
+ *
+ * @stable
+ */
+interface UsageAccumulator {
+  /** Current rolled-up totals across every model that has been added. */
+  readonly total: Usage;
+  /** Per-model breakdown; preserves call counts for observability. */
+  readonly byModel: ReadonlyMap<string, ModelUsage>;
+  /** Add a single LLM-call usage record under the given model id. */
+  add(modelId: string, usage: Usage): void;
+  /** Reset the accumulator to a zeroed state. */
+  reset(): void;
+  /** Render an immutable snapshot suitable for serialization / span attrs. */
+  snapshot(): UsageSnapshot;
+}
+/**
+ * Immutable, JSON-serializable snapshot of a `UsageAccumulator`.
+ *
+ * @stable
+ */
+interface UsageSnapshot {
+  readonly total: Usage;
+  readonly byModel: readonly ModelUsage[];
+}
+/**
+ * Returns a fresh, zeroed `Usage` value.
+ *
+ * @stable
+ */
+declare function zeroUsage(): Usage;
+//#endregion
+export { Cost, ModelUsage, Usage, UsageAccumulator, UsageSnapshot, zeroUsage };
+//# sourceMappingURL=usage.d.ts.map

package/dist/types/usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.d.ts","names":[],"sources":["../../src/types/usage.ts"],"sourcesContent":[],"mappings":";;AASA;AAcA;AAaA;AAkBA;;;;;AAWc,UAxDG,KAAA,CAwDH;EAAa,YAAA,EAAA,MAAA;EAQV,gBAAa,EAAA,MAAA;EAUd,eAAS,CAAA,EAAA,MAAA;;SArEhB;;;;;;;;UASQ,IAAA;;;;;;;;;;;;UAaA,UAAA;;;;;;SAMR;;;;;;;;;;;UAYQ,gBAAA;;kBAEC;;oBAEE,oBAAoB;;8BAGV;;;;cAIhB;;;;;;;UAQG,aAAA;kBACC;6BACW;;;;;;;iBAQb,SAAA,CAAA,GAAa"}

package/dist/types/usage.js

@@ -0,0 +1,17 @@
+//#region src/types/usage.ts
+/**
+* Returns a fresh, zeroed `Usage` value.
+*
+* @stable
+*/
+function zeroUsage() {
+	return {
+		promptTokens: 0,
+		completionTokens: 0,
+		totalTokens: 0
+	};
+}
+
+//#endregion
+export { zeroUsage };
+//# sourceMappingURL=usage.js.map

package/dist/types/usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.js","names":[],"sources":["../../src/types/usage.ts"],"sourcesContent":["/**\n * Token / cost metrics for a single LLM call.\n *\n * `cost` is optional because the framework cannot compute it without a\n * pricing snapshot — providers/middleware fill it in (e.g. through the\n * separate `@graphorin/pricing` package) when the snapshot is available.\n *\n * @stable\n */\nexport interface Usage {\n  promptTokens: number;\n  completionTokens: number;\n  reasoningTokens?: number;\n  totalTokens: number;\n  cost?: Cost;\n}\n\n/**\n * Money figure attached to a `Usage`. Always carries a 3-letter currency\n * code so that consumers can perform aggregation safely.\n *\n * @stable\n */\nexport interface Cost {\n  /** Amount in the smallest fractional unit of the declared currency. */\n  amount: number;\n  /** ISO-4217 currency code; default `'USD'`. */\n  currency: string;\n}\n\n/**\n * Per-model breakdown used by aggregators (e.g. `CostTracker` in\n * `@graphorin/observability`).\n *\n * @stable\n */\nexport interface ModelUsage {\n  modelId: string;\n  promptTokens: number;\n  completionTokens: number;\n  reasoningTokens?: number;\n  totalTokens: number;\n  cost?: Cost;\n  callCount: number;\n}\n\n/**\n * A live accumulator of token / cost figures. Implementations live in\n * `@graphorin/observability`. The contract sits here so every package\n * (agent, workflow, server, …) can type a parameter as `UsageAccumulator`\n * without taking an observability dependency.\n *\n * @stable\n */\nexport interface UsageAccumulator {\n  /** Current rolled-up totals across every model that has been added. */\n  readonly total: Usage;\n  /** Per-model breakdown; preserves call counts for observability. */\n  readonly byModel: ReadonlyMap<string, ModelUsage>;\n\n  /** Add a single LLM-call usage record under the given model id. */\n  add(modelId: string, usage: Usage): void;\n  /** Reset the accumulator to a zeroed state. */\n  reset(): void;\n  /** Render an immutable snapshot suitable for serialization / span attrs. */\n  snapshot(): UsageSnapshot;\n}\n\n/**\n * Immutable, JSON-serializable snapshot of a `UsageAccumulator`.\n *\n * @stable\n */\nexport interface UsageSnapshot {\n  readonly total: Usage;\n  readonly byModel: readonly ModelUsage[];\n}\n\n/**\n * Returns a fresh, zeroed `Usage` value.\n *\n * @stable\n */\nexport function zeroUsage(): Usage {\n  return { promptTokens: 0, completionTokens: 0, totalTokens: 0 };\n}\n"],"mappings":";;;;;;AAmFA,SAAgB,YAAmB;AACjC,QAAO;EAAE,cAAc;EAAG,kBAAkB;EAAG,aAAa;EAAG"}

package/dist/types/workflow-event.d.ts

@@ -0,0 +1,108 @@
+//#region src/types/workflow-event.d.ts
+/**
+ * Discriminated union of every event produced by `Workflow.execute(...)`
+ * and `Workflow.resume(...)`.
+ *
+ * Generic over `TState` so that downstream consumers can discriminate on
+ * the workflow's typed state shape.
+ *
+ * @stable
+ */
+type WorkflowEvent<TState = unknown> = WorkflowStartEvent | WorkflowStepStartEvent<TState> | WorkflowStepEndEvent<TState> | WorkflowTaskStartEvent | WorkflowTaskEndEvent | WorkflowChannelUpdateEvent<TState> | WorkflowCheckpointWrittenEvent | WorkflowSuspendedEvent<TState> | WorkflowResumedEvent<TState> | WorkflowEndEvent<TState> | WorkflowErrorEvent | WorkflowCustomEvent;
+/** @stable */
+interface WorkflowStartEvent {
+  readonly type: 'workflow.start';
+  readonly threadId: string;
+  readonly workflowId: string;
+}
+/** @stable */
+interface WorkflowStepStartEvent<TState = unknown> {
+  readonly type: 'workflow.step.start';
+  readonly stepNumber: number;
+  readonly state: TState;
+}
+/** @stable */
+interface WorkflowStepEndEvent<TState = unknown> {
+  readonly type: 'workflow.step.end';
+  readonly stepNumber: number;
+  readonly state: TState;
+}
+/** @stable */
+interface WorkflowTaskStartEvent {
+  readonly type: 'workflow.task.start';
+  readonly stepNumber: number;
+  readonly taskId: string;
+  readonly nodeName: string;
+}
+/** @stable */
+interface WorkflowTaskEndEvent {
+  readonly type: 'workflow.task.end';
+  readonly stepNumber: number;
+  readonly taskId: string;
+  readonly nodeName: string;
+  readonly status: 'completed' | 'failed' | 'paused';
+  readonly durationMs: number;
+}
+/** @stable */
+interface WorkflowChannelUpdateEvent<TState = unknown> {
+  readonly type: 'workflow.channel.update';
+  readonly stepNumber: number;
+  readonly channel: keyof TState & string;
+  readonly version: number;
+}
+/** @stable */
+interface WorkflowCheckpointWrittenEvent {
+  readonly type: 'workflow.checkpoint.written';
+  readonly checkpointId: string;
+  readonly stepNumber: number;
+}
+/**
+ * Workflow paused — for HITL approvals or programmatic `pause(value)`
+ * calls. Carries the value passed to `pause(...)` so the caller can
+ * choose how to surface the prompt to the user.
+ *
+ * @stable
+ */
+interface WorkflowSuspendedEvent<TState = unknown> {
+  readonly type: 'workflow.suspended';
+  readonly threadId: string;
+  readonly stepNumber: number;
+  readonly state: TState;
+  readonly value: unknown;
+}
+/** @stable */
+interface WorkflowResumedEvent<TState = unknown> {
+  readonly type: 'workflow.resumed';
+  readonly threadId: string;
+  readonly stepNumber: number;
+  readonly state: TState;
+}
+/** @stable */
+interface WorkflowEndEvent<TState = unknown> {
+  readonly type: 'workflow.end';
+  readonly threadId: string;
+  readonly state: TState;
+}
+/** @stable */
+interface WorkflowErrorEvent {
+  readonly type: 'workflow.error';
+  readonly threadId: string;
+  readonly error: {
+    readonly message: string;
+    readonly code: string;
+  };
+}
+/**
+ * Application-defined event emitted from inside a workflow node via
+ * `ctx.emit(name, payload)`. The runtime never produces these on its own.
+ *
+ * @stable
+ */
+interface WorkflowCustomEvent {
+  readonly type: 'workflow.custom';
+  readonly name: string;
+  readonly payload: unknown;
+}
+//#endregion
+export { WorkflowChannelUpdateEvent, WorkflowCheckpointWrittenEvent, WorkflowCustomEvent, WorkflowEndEvent, WorkflowErrorEvent, WorkflowEvent, WorkflowResumedEvent, WorkflowStartEvent, WorkflowStepEndEvent, WorkflowStepStartEvent, WorkflowSuspendedEvent, WorkflowTaskEndEvent, WorkflowTaskStartEvent };
+//# sourceMappingURL=workflow-event.d.ts.map

package/dist/types/workflow-event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-event.d.ts","names":[],"sources":["../../src/types/workflow-event.ts"],"sourcesContent":[],"mappings":";;AASA;;;;;;;;AAM+B,KANnB,aAMmB,CAAA,SAAA,OAAA,CAAA,GAL3B,kBAK2B,GAJ3B,sBAI2B,CAJJ,MAII,CAAA,GAH3B,oBAG2B,CAHN,MAGM,CAAA,GAF3B,sBAE2B,GAD3B,oBAC2B,GAA3B,0BAA2B,CAAA,MAAA,CAAA,GAC3B,8BAD2B,GAE3B,sBAF2B,CAEJ,MAFI,CAAA,GAG3B,oBAH2B,CAGN,MAHM,CAAA,GAI3B,gBAJ2B,CAIV,MAJU,CAAA,GAK3B,kBAL2B,GAM3B,mBAN2B;;AAC3B,UAQa,kBAAA,CARb;EACuB,SAAA,IAAA,EAAA,gBAAA;EAAvB,SAAA,QAAA,EAAA,MAAA;EACqB,SAAA,UAAA,EAAA,MAAA;;;AACrB,UAYa,sBAZb,CAAA,SAAA,OAAA,CAAA,CAAA;EACA,SAAA,IAAA,EAAA,qBAAA;EACA,SAAA,UAAA,EAAA,MAAA;EAAmB,SAAA,KAAA,EAaL,MAbK;AAGvB;AAOA;AAOiB,UAAA,oBAAoB,CAAA,SAGnB,OAAM,CAAA,CAAA;EAIP,SAAA,IAAA,EAAA,mBAAsB;EAQtB,SAAA,UAAA,EAAA,MAAoB;EAUpB,SAAA,KAAA,EAtBC,MAsBD;AAQjB;AAaA;AASiB,UAhDA,sBAAA,CAgDoB;EAQpB,SAAA,IAAA,EAAA,qBAAgB;EAOhB,SAAA,UAAA,EAAkB,MAAA;EAYlB,SAAA,MAAA,EAAA,MAAmB;;;;UAnEnB,oBAAA;;;;;;;;;UAUA;;;0BAGS;;;;UAKT,8BAAA;;;;;;;;;;;;UAaA;;;;kBAIC;;;;UAKD;;;;kBAIC;;;UAID;;;kBAGC;;;UAID,kBAAA;;;;;;;;;;;;;;UAYA,mBAAA"}

package/dist/utils/assert-never.d.ts

@@ -0,0 +1,26 @@
+//#region src/utils/assert-never.d.ts
+/**
+ * Exhaustiveness helper. Place at the end of a `switch (...)` over a
+ * discriminated union: TypeScript narrows the operand to `never` if
+ * every variant is handled. Adding a new variant later turns the call
+ * site into a compile error — the regression net for our event unions.
+ *
+ * @example
+ * ```ts
+ * function describe(event: AgentEvent): string {
+ *   switch (event.type) {
+ *     case 'agent.start': return 'started';
+ *     case 'agent.end':   return 'ended';
+ *     // ... every other variant ...
+ *     default:
+ *       return assertNever(event, 'Unhandled AgentEvent variant');
+ *   }
+ * }
+ * ```
+ *
+ * @stable
+ */
+declare function assertNever(value: never, message?: string): never;
+//#endregion
+export { assertNever };
+//# sourceMappingURL=assert-never.d.ts.map

package/dist/utils/assert-never.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert-never.d.ts","names":[],"sources":["../../src/utils/assert-never.ts"],"sourcesContent":[],"mappings":";;AAqBA;;;;;;;;;;;;;;;;;;;;iBAAgB,WAAA"}

package/dist/utils/assert-never.js

@@ -0,0 +1,29 @@
+//#region src/utils/assert-never.ts
+/**
+* Exhaustiveness helper. Place at the end of a `switch (...)` over a
+* discriminated union: TypeScript narrows the operand to `never` if
+* every variant is handled. Adding a new variant later turns the call
+* site into a compile error — the regression net for our event unions.
+*
+* @example
+* ```ts
+* function describe(event: AgentEvent): string {
+*   switch (event.type) {
+*     case 'agent.start': return 'started';
+*     case 'agent.end':   return 'ended';
+*     // ... every other variant ...
+*     default:
+*       return assertNever(event, 'Unhandled AgentEvent variant');
+*   }
+* }
+* ```
+*
+* @stable
+*/
+function assertNever(value, message) {
+	throw new Error(message ?? `graphorin: unhandled discriminated-union variant: ${String(value)}`);
+}
+
+//#endregion
+export { assertNever };
+//# sourceMappingURL=assert-never.js.map

package/dist/utils/assert-never.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert-never.js","names":[],"sources":["../../src/utils/assert-never.ts"],"sourcesContent":["/**\n * Exhaustiveness helper. Place at the end of a `switch (...)` over a\n * discriminated union: TypeScript narrows the operand to `never` if\n * every variant is handled. Adding a new variant later turns the call\n * site into a compile error — the regression net for our event unions.\n *\n * @example\n * ```ts\n * function describe(event: AgentEvent): string {\n *   switch (event.type) {\n *     case 'agent.start': return 'started';\n *     case 'agent.end':   return 'ended';\n *     // ... every other variant ...\n *     default:\n *       return assertNever(event, 'Unhandled AgentEvent variant');\n *   }\n * }\n * ```\n *\n * @stable\n */\nexport function assertNever(value: never, message?: string): never {\n  throw new Error(message ?? `graphorin: unhandled discriminated-union variant: ${String(value)}`);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAqBA,SAAgB,YAAY,OAAc,SAAyB;AACjE,OAAM,IAAI,MAAM,WAAW,qDAAqD,OAAO,MAAM,GAAG"}

package/dist/utils/async-context.d.ts

@@ -0,0 +1,37 @@
+//#region src/utils/async-context.d.ts
+/**
+ * Thin typed wrapper around Node's `AsyncLocalStorage`. Used to thread a
+ * tool-execution / request-scoped context through the async stack
+ * without explicit parameter passing.
+ *
+ * The wrapper exists because:
+ * - The Node API requires a fresh `AsyncLocalStorage<T>` per scope; this
+ *   helper centralizes the construction with consistent typing.
+ * - Downstream packages (security, tools) want a single canonical
+ *   constructor so that their `getStore()` code paths share the same
+ *   identity (matters for HMR / multi-realm setups).
+ *
+ * @stable
+ */
+interface AsyncContext<T> {
+  /** Run `fn` inside a fresh scope carrying `value`. */
+  run<R>(value: T, fn: () => R): R;
+  /** Run `fn` inside a fresh scope carrying `value` (async-friendly). */
+  runAsync<R>(value: T, fn: () => Promise<R>): Promise<R>;
+  /** Get the value of the current scope, or `undefined` outside one. */
+  get(): T | undefined;
+  /** Replace the value of the current scope (advanced; rarely needed). */
+  enterWith(value: T): void;
+  /** Exit any in-flight scope (advanced; rarely needed). */
+  disable(): void;
+}
+/**
+ * Construct a typed `AsyncContext`. The optional `name` is surfaced in
+ * the diagnostics channel of `AsyncLocalStorage` (debugging only).
+ *
+ * @stable
+ */
+declare function createAsyncContext<T>(_name?: string): AsyncContext<T>;
+//#endregion
+export { AsyncContext, createAsyncContext };
+//# sourceMappingURL=async-context.d.ts.map

package/dist/utils/async-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-context.d.ts","names":[],"sources":["../../src/utils/async-context.ts"],"sourcesContent":[],"mappings":";;AAgBA;;;;;;;;;;;;AAmBA;UAnBiB;;gBAED,aAAa,IAAI;;qBAEZ,aAAa,QAAQ,KAAK,QAAQ;;SAE9C;;mBAEU;;;;;;;;;;iBAWH,uCAAuC,aAAa"}

package/dist/utils/async-context.js

@@ -0,0 +1,33 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+//#region src/utils/async-context.ts
+/**
+* Construct a typed `AsyncContext`. The optional `name` is surfaced in
+* the diagnostics channel of `AsyncLocalStorage` (debugging only).
+*
+* @stable
+*/
+function createAsyncContext(_name) {
+	const als = new AsyncLocalStorage();
+	return {
+		run(value, fn) {
+			return als.run(value, fn);
+		},
+		runAsync(value, fn) {
+			return als.run(value, fn);
+		},
+		get() {
+			return als.getStore();
+		},
+		enterWith(value) {
+			als.enterWith(value);
+		},
+		disable() {
+			als.disable();
+		}
+	};
+}
+
+//#endregion
+export { createAsyncContext };
+//# sourceMappingURL=async-context.js.map

package/dist/utils/async-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-context.js","names":[],"sources":["../../src/utils/async-context.ts"],"sourcesContent":["import { AsyncLocalStorage } from 'node:async_hooks';\n\n/**\n * Thin typed wrapper around Node's `AsyncLocalStorage`. Used to thread a\n * tool-execution / request-scoped context through the async stack\n * without explicit parameter passing.\n *\n * The wrapper exists because:\n * - The Node API requires a fresh `AsyncLocalStorage<T>` per scope; this\n *   helper centralizes the construction with consistent typing.\n * - Downstream packages (security, tools) want a single canonical\n *   constructor so that their `getStore()` code paths share the same\n *   identity (matters for HMR / multi-realm setups).\n *\n * @stable\n */\nexport interface AsyncContext<T> {\n  /** Run `fn` inside a fresh scope carrying `value`. */\n  run<R>(value: T, fn: () => R): R;\n  /** Run `fn` inside a fresh scope carrying `value` (async-friendly). */\n  runAsync<R>(value: T, fn: () => Promise<R>): Promise<R>;\n  /** Get the value of the current scope, or `undefined` outside one. */\n  get(): T | undefined;\n  /** Replace the value of the current scope (advanced; rarely needed). */\n  enterWith(value: T): void;\n  /** Exit any in-flight scope (advanced; rarely needed). */\n  disable(): void;\n}\n\n/**\n * Construct a typed `AsyncContext`. The optional `name` is surfaced in\n * the diagnostics channel of `AsyncLocalStorage` (debugging only).\n *\n * @stable\n */\nexport function createAsyncContext<T>(_name?: string): AsyncContext<T> {\n  const als = new AsyncLocalStorage<T>();\n  return {\n    run<R>(value: T, fn: () => R): R {\n      return als.run(value, fn);\n    },\n    runAsync<R>(value: T, fn: () => Promise<R>): Promise<R> {\n      return als.run(value, fn);\n    },\n    get(): T | undefined {\n      return als.getStore();\n    },\n    enterWith(value: T): void {\n      als.enterWith(value);\n    },\n    disable(): void {\n      als.disable();\n    },\n  };\n}\n"],"mappings":";;;;;;;;;AAmCA,SAAgB,mBAAsB,OAAiC;CACrE,MAAM,MAAM,IAAI,mBAAsB;AACtC,QAAO;EACL,IAAO,OAAU,IAAgB;AAC/B,UAAO,IAAI,IAAI,OAAO,GAAG;;EAE3B,SAAY,OAAU,IAAkC;AACtD,UAAO,IAAI,IAAI,OAAO,GAAG;;EAE3B,MAAqB;AACnB,UAAO,IAAI,UAAU;;EAEvB,UAAU,OAAgB;AACxB,OAAI,UAAU,MAAM;;EAEtB,UAAgB;AACd,OAAI,SAAS;;EAEhB"}

package/dist/utils/hash.d.ts

@@ -0,0 +1,30 @@
+//#region src/utils/hash.d.ts
+/**
+ * MD5 hex digest. Used by the memory layer for content deduplication
+ * (`MD5(content)` is the dedup key for incoming facts / messages).
+ *
+ * MD5 is **not** a cryptographic primitive in this codebase — it's used
+ * exclusively for collision-resistant content addressing where
+ * collision-resistance is the desired property, not pre-image resistance.
+ * Do not use this helper for password hashing, MAC, or any other
+ * security-sensitive use case (use `@graphorin/security` for those).
+ *
+ * @stable
+ */
+declare function md5(content: string | Uint8Array): string;
+/**
+ * Pure-JS XXH32 implementation. Used by the memory-modification guard
+ * — fast, non-cryptographic content fingerprinting (`xxhash(content)`
+ * tracks whether a tool's view of memory has shifted while the LLM was
+ * thinking).
+ *
+ * Not security-sensitive — never use for tampering detection of an
+ * untrusted attacker; for that the audit log uses SHA-256 (in
+ * `@graphorin/security`).
+ *
+ * @stable
+ */
+declare function xxhash(input: string | Uint8Array, seed?: number): string;
+//#endregion
+export { md5, xxhash };
+//# sourceMappingURL=hash.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","names":[],"sources":["../../src/utils/hash.ts"],"sourcesContent":[],"mappings":";;AAcA;AAsBA;;;;;;;;;;iBAtBgB,GAAA,mBAAsB;;;;;;;;;;;;;iBAsBtB,MAAA,iBAAuB"}

package/dist/utils/hash.js

@@ -0,0 +1,102 @@
+import { createHash } from "node:crypto";
+
+//#region src/utils/hash.ts
+/**
+* MD5 hex digest. Used by the memory layer for content deduplication
+* (`MD5(content)` is the dedup key for incoming facts / messages).
+*
+* MD5 is **not** a cryptographic primitive in this codebase — it's used
+* exclusively for collision-resistant content addressing where
+* collision-resistance is the desired property, not pre-image resistance.
+* Do not use this helper for password hashing, MAC, or any other
+* security-sensitive use case (use `@graphorin/security` for those).
+*
+* @stable
+*/
+function md5(content) {
+	const h = createHash("md5");
+	if (typeof content === "string") h.update(content, "utf8");
+	else h.update(content);
+	return h.digest("hex");
+}
+/**
+* Pure-JS XXH32 implementation. Used by the memory-modification guard
+* — fast, non-cryptographic content fingerprinting (`xxhash(content)`
+* tracks whether a tool's view of memory has shifted while the LLM was
+* thinking).
+*
+* Not security-sensitive — never use for tampering detection of an
+* untrusted attacker; for that the audit log uses SHA-256 (in
+* `@graphorin/security`).
+*
+* @stable
+*/
+function xxhash(input, seed = 0) {
+	return xxh32(typeof input === "string" ? utf8Encode(input) : input, seed >>> 0).toString(16).padStart(8, "0");
+}
+const PRIME32_1 = 2654435761;
+const PRIME32_2 = 2246822519;
+const PRIME32_3 = 3266489917;
+const PRIME32_4 = 668265263;
+const PRIME32_5 = 374761393;
+const utf8 = new TextEncoder();
+function utf8Encode(s) {
+	return utf8.encode(s);
+}
+function rotl32(x, r) {
+	return (x << r | x >>> 32 - r) >>> 0;
+}
+function mul32(a, b) {
+	const aLo = a & 65535;
+	const aHi = a >>> 16;
+	const bLo = b & 65535;
+	const bHi = b >>> 16;
+	return aLo * bLo + (aLo * bHi + aHi * bLo << 16 >>> 0) >>> 0;
+}
+function read32LE(buf, offset) {
+	const b0 = buf[offset] ?? 0;
+	const b1 = buf[offset + 1] ?? 0;
+	const b2 = buf[offset + 2] ?? 0;
+	const b3 = buf[offset + 3] ?? 0;
+	return (b0 | b1 << 8 | b2 << 16 | b3 << 24) >>> 0;
+}
+function xxh32(input, seed) {
+	const len = input.length;
+	let h32;
+	let i = 0;
+	if (len >= 16) {
+		let v1 = seed + PRIME32_1 + PRIME32_2 >>> 0;
+		let v2 = seed + PRIME32_2 >>> 0;
+		let v3 = seed >>> 0;
+		let v4 = seed - PRIME32_1 >>> 0;
+		while (i + 16 <= len) {
+			v1 = mul32(rotl32(v1 + mul32(read32LE(input, i), PRIME32_2) >>> 0, 13), PRIME32_1);
+			i += 4;
+			v2 = mul32(rotl32(v2 + mul32(read32LE(input, i), PRIME32_2) >>> 0, 13), PRIME32_1);
+			i += 4;
+			v3 = mul32(rotl32(v3 + mul32(read32LE(input, i), PRIME32_2) >>> 0, 13), PRIME32_1);
+			i += 4;
+			v4 = mul32(rotl32(v4 + mul32(read32LE(input, i), PRIME32_2) >>> 0, 13), PRIME32_1);
+			i += 4;
+		}
+		h32 = rotl32(v1, 1) + rotl32(v2, 7) + rotl32(v3, 12) + rotl32(v4, 18) >>> 0;
+	} else h32 = seed + PRIME32_5 >>> 0;
+	h32 = h32 + len >>> 0;
+	while (i + 4 <= len) {
+		h32 = mul32(rotl32(h32 + mul32(read32LE(input, i), PRIME32_3) >>> 0, 17), PRIME32_4);
+		i += 4;
+	}
+	while (i < len) {
+		const byte = input[i] ?? 0;
+		h32 = mul32(rotl32(h32 + mul32(byte >>> 0, PRIME32_5) >>> 0, 11), PRIME32_1);
+		i++;
+	}
+	h32 = mul32(h32 ^ h32 >>> 15, PRIME32_2);
+	h32 = mul32(h32 ^ h32 >>> 13, PRIME32_3);
+	h32 = (h32 ^ h32 >>> 16) >>> 0;
+	return h32;
+}
+
+//#endregion
+export { md5, xxhash };
+//# sourceMappingURL=hash.js.map

package/dist/utils/hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.js","names":["h32: number"],"sources":["../../src/utils/hash.ts"],"sourcesContent":["import { createHash } from 'node:crypto';\n\n/**\n * MD5 hex digest. Used by the memory layer for content deduplication\n * (`MD5(content)` is the dedup key for incoming facts / messages).\n *\n * MD5 is **not** a cryptographic primitive in this codebase — it's used\n * exclusively for collision-resistant content addressing where\n * collision-resistance is the desired property, not pre-image resistance.\n * Do not use this helper for password hashing, MAC, or any other\n * security-sensitive use case (use `@graphorin/security` for those).\n *\n * @stable\n */\nexport function md5(content: string | Uint8Array): string {\n  const h = createHash('md5');\n  if (typeof content === 'string') {\n    h.update(content, 'utf8');\n  } else {\n    h.update(content);\n  }\n  return h.digest('hex');\n}\n\n/**\n * Pure-JS XXH32 implementation. Used by the memory-modification guard\n * — fast, non-cryptographic content fingerprinting (`xxhash(content)`\n * tracks whether a tool's view of memory has shifted while the LLM was\n * thinking).\n *\n * Not security-sensitive — never use for tampering detection of an\n * untrusted attacker; for that the audit log uses SHA-256 (in\n * `@graphorin/security`).\n *\n * @stable\n */\nexport function xxhash(input: string | Uint8Array, seed = 0): string {\n  const bytes = typeof input === 'string' ? utf8Encode(input) : input;\n  const h = xxh32(bytes, seed >>> 0);\n  return h.toString(16).padStart(8, '0');\n}\n\nconst PRIME32_1 = 0x9e3779b1 >>> 0;\nconst PRIME32_2 = 0x85ebca77 >>> 0;\nconst PRIME32_3 = 0xc2b2ae3d >>> 0;\nconst PRIME32_4 = 0x27d4eb2f >>> 0;\nconst PRIME32_5 = 0x165667b1 >>> 0;\n\nconst utf8 = new TextEncoder();\nfunction utf8Encode(s: string): Uint8Array {\n  return utf8.encode(s);\n}\n\nfunction rotl32(x: number, r: number): number {\n  return ((x << r) | (x >>> (32 - r))) >>> 0;\n}\n\nfunction mul32(a: number, b: number): number {\n  // Multiply two 32-bit unsigned ints with overflow truncation.\n  const aLo = a & 0xffff;\n  const aHi = a >>> 16;\n  const bLo = b & 0xffff;\n  const bHi = b >>> 16;\n  return (aLo * bLo + (((aLo * bHi + aHi * bLo) << 16) >>> 0)) >>> 0;\n}\n\nfunction read32LE(buf: Uint8Array, offset: number): number {\n  const b0 = buf[offset] ?? 0;\n  const b1 = buf[offset + 1] ?? 0;\n  const b2 = buf[offset + 2] ?? 0;\n  const b3 = buf[offset + 3] ?? 0;\n  return (b0 | (b1 << 8) | (b2 << 16) | (b3 << 24)) >>> 0;\n}\n\nfunction xxh32(input: Uint8Array, seed: number): number {\n  const len = input.length;\n  let h32: number;\n  let i = 0;\n\n  if (len >= 16) {\n    let v1 = (seed + PRIME32_1 + PRIME32_2) >>> 0;\n    let v2 = (seed + PRIME32_2) >>> 0;\n    let v3 = seed >>> 0;\n    let v4 = (seed - PRIME32_1) >>> 0;\n\n    while (i + 16 <= len) {\n      v1 = mul32(rotl32((v1 + mul32(read32LE(input, i), PRIME32_2)) >>> 0, 13), PRIME32_1);\n      i += 4;\n      v2 = mul32(rotl32((v2 + mul32(read32LE(input, i), PRIME32_2)) >>> 0, 13), PRIME32_1);\n      i += 4;\n      v3 = mul32(rotl32((v3 + mul32(read32LE(input, i), PRIME32_2)) >>> 0, 13), PRIME32_1);\n      i += 4;\n      v4 = mul32(rotl32((v4 + mul32(read32LE(input, i), PRIME32_2)) >>> 0, 13), PRIME32_1);\n      i += 4;\n    }\n\n    h32 = (rotl32(v1, 1) + rotl32(v2, 7) + rotl32(v3, 12) + rotl32(v4, 18)) >>> 0;\n  } else {\n    h32 = (seed + PRIME32_5) >>> 0;\n  }\n\n  h32 = (h32 + len) >>> 0;\n\n  while (i + 4 <= len) {\n    h32 = mul32(rotl32((h32 + mul32(read32LE(input, i), PRIME32_3)) >>> 0, 17), PRIME32_4);\n    i += 4;\n  }\n\n  while (i < len) {\n    const byte = input[i] ?? 0;\n    h32 = mul32(rotl32((h32 + mul32(byte >>> 0, PRIME32_5)) >>> 0, 11), PRIME32_1);\n    i++;\n  }\n\n  h32 = mul32(h32 ^ (h32 >>> 15), PRIME32_2);\n  h32 = mul32(h32 ^ (h32 >>> 13), PRIME32_3);\n  h32 = (h32 ^ (h32 >>> 16)) >>> 0;\n\n  return h32;\n}\n"],"mappings":";;;;;;;;;;;;;;;AAcA,SAAgB,IAAI,SAAsC;CACxD,MAAM,IAAI,WAAW,MAAM;AAC3B,KAAI,OAAO,YAAY,SACrB,GAAE,OAAO,SAAS,OAAO;KAEzB,GAAE,OAAO,QAAQ;AAEnB,QAAO,EAAE,OAAO,MAAM;;;;;;;;;;;;;;AAexB,SAAgB,OAAO,OAA4B,OAAO,GAAW;AAGnE,QADU,MADI,OAAO,UAAU,WAAW,WAAW,MAAM,GAAG,OACvC,SAAS,EAAE,CACzB,SAAS,GAAG,CAAC,SAAS,GAAG,IAAI;;AAGxC,MAAM,YAAY;AAClB,MAAM,YAAY;AAClB,MAAM,YAAY;AAClB,MAAM,YAAY;AAClB,MAAM,YAAY;AAElB,MAAM,OAAO,IAAI,aAAa;AAC9B,SAAS,WAAW,GAAuB;AACzC,QAAO,KAAK,OAAO,EAAE;;AAGvB,SAAS,OAAO,GAAW,GAAmB;AAC5C,SAAS,KAAK,IAAM,MAAO,KAAK,OAAS;;AAG3C,SAAS,MAAM,GAAW,GAAmB;CAE3C,MAAM,MAAM,IAAI;CAChB,MAAM,MAAM,MAAM;CAClB,MAAM,MAAM,IAAI;CAChB,MAAM,MAAM,MAAM;AAClB,QAAQ,MAAM,OAAS,MAAM,MAAM,MAAM,OAAQ,OAAQ,OAAQ;;AAGnE,SAAS,SAAS,KAAiB,QAAwB;CACzD,MAAM,KAAK,IAAI,WAAW;CAC1B,MAAM,KAAK,IAAI,SAAS,MAAM;CAC9B,MAAM,KAAK,IAAI,SAAS,MAAM;CAC9B,MAAM,KAAK,IAAI,SAAS,MAAM;AAC9B,SAAQ,KAAM,MAAM,IAAM,MAAM,KAAO,MAAM,QAAS;;AAGxD,SAAS,MAAM,OAAmB,MAAsB;CACtD,MAAM,MAAM,MAAM;CAClB,IAAIA;CACJ,IAAI,IAAI;AAER,KAAI,OAAO,IAAI;EACb,IAAI,KAAM,OAAO,YAAY,cAAe;EAC5C,IAAI,KAAM,OAAO,cAAe;EAChC,IAAI,KAAK,SAAS;EAClB,IAAI,KAAM,OAAO,cAAe;AAEhC,SAAO,IAAI,MAAM,KAAK;AACpB,QAAK,MAAM,OAAQ,KAAK,MAAM,SAAS,OAAO,EAAE,EAAE,UAAU,KAAM,GAAG,GAAG,EAAE,UAAU;AACpF,QAAK;AACL,QAAK,MAAM,OAAQ,KAAK,MAAM,SAAS,OAAO,EAAE,EAAE,UAAU,KAAM,GAAG,GAAG,EAAE,UAAU;AACpF,QAAK;AACL,QAAK,MAAM,OAAQ,KAAK,MAAM,SAAS,OAAO,EAAE,EAAE,UAAU,KAAM,GAAG,GAAG,EAAE,UAAU;AACpF,QAAK;AACL,QAAK,MAAM,OAAQ,KAAK,MAAM,SAAS,OAAO,EAAE,EAAE,UAAU,KAAM,GAAG,GAAG,EAAE,UAAU;AACpF,QAAK;;AAGP,QAAO,OAAO,IAAI,EAAE,GAAG,OAAO,IAAI,EAAE,GAAG,OAAO,IAAI,GAAG,GAAG,OAAO,IAAI,GAAG,KAAM;OAE5E,OAAO,OAAO,cAAe;AAG/B,OAAO,MAAM,QAAS;AAEtB,QAAO,IAAI,KAAK,KAAK;AACnB,QAAM,MAAM,OAAQ,MAAM,MAAM,SAAS,OAAO,EAAE,EAAE,UAAU,KAAM,GAAG,GAAG,EAAE,UAAU;AACtF,OAAK;;AAGP,QAAO,IAAI,KAAK;EACd,MAAM,OAAO,MAAM,MAAM;AACzB,QAAM,MAAM,OAAQ,MAAM,MAAM,SAAS,GAAG,UAAU,KAAM,GAAG,GAAG,EAAE,UAAU;AAC9E;;AAGF,OAAM,MAAM,MAAO,QAAQ,IAAK,UAAU;AAC1C,OAAM,MAAM,MAAO,QAAQ,IAAK,UAAU;AAC1C,QAAO,MAAO,QAAQ,QAAS;AAE/B,QAAO"}

package/dist/utils/index.d.ts

@@ -0,0 +1,6 @@
+import { ValidationResult, ZodLikeError, ZodLikeSafeParseResult, ZodLikeSchema, validate, validateOrThrow } from "./validation.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 };

package/dist/utils/index.js

@@ -0,0 +1,7 @@
+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 };

package/dist/utils/streams.d.ts

@@ -0,0 +1,59 @@
+//#region src/utils/streams.d.ts
+/**
+ * Stream / async-iterable helpers. All helpers honor `AbortSignal`
+ * propagation: when the supplied signal aborts, the underlying
+ * iterator's `return()` method is invoked so that resources held by the
+ * upstream generator are released cleanly.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Drain an `AsyncIterable` into an array.
+ *
+ * @stable
+ */
+declare function collect<T>(source: AsyncIterable<T>, signal?: AbortSignal): Promise<T[]>;
+/**
+ * Map every value of an async iterable. The mapper may be async.
+ * Cancellation via `signal` is honored.
+ *
+ * @stable
+ */
+declare function mapStream<T, U>(source: AsyncIterable<T>, fn: (value: T, index: number) => U | Promise<U>, signal?: AbortSignal): AsyncIterable<U>;
+/**
+ * Filter values produced by `source`. The predicate may be async.
+ *
+ * @stable
+ */
+declare function filter<T>(source: AsyncIterable<T>, pred: (value: T, index: number) => boolean | Promise<boolean>, signal?: AbortSignal): AsyncIterable<T>;
+/**
+ * Take the first `n` items.
+ *
+ * @stable
+ */
+declare function take<T>(source: AsyncIterable<T>, n: number, signal?: AbortSignal): AsyncIterable<T>;
+/**
+ * Take items as long as `pred` returns truthy. The first item for which
+ * `pred` returns falsy ends the stream.
+ *
+ * @stable
+ */
+declare function takeWhile<T>(source: AsyncIterable<T>, pred: (value: T, index: number) => boolean | Promise<boolean>, signal?: AbortSignal): AsyncIterable<T>;
+/**
+ * Merge multiple async iterables into a single output iterable. Items
+ * are yielded in the order they arrive (interleaved), not in source
+ * order. Cancellation propagates to every upstream iterator.
+ *
+ * @stable
+ */
+declare function merge<T>(sources: ReadonlyArray<AsyncIterable<T>>, signal?: AbortSignal): AsyncIterable<T>;
+/**
+ * Wrap `source` with abort-signal propagation: when `signal` aborts the
+ * underlying iterator's `return()` is called and the loop exits cleanly.
+ *
+ * @stable
+ */
+declare function withSignal<T>(source: AsyncIterable<T>, signal?: AbortSignal): AsyncIterable<T>;
+//#endregion
+export { collect, filter, mapStream, merge, take, takeWhile, withSignal };
+//# sourceMappingURL=streams.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"streams.d.ts","names":[],"sources":["../../src/utils/streams.ts"],"sourcesContent":[],"mappings":";;AAwBA;;;;;;;AAcA;;;;;AAE+C,iBAhBzB,OAgByB,CAAA,CAAA,CAAA,CAAA,MAAA,EAhBN,aAgBM,CAhBQ,CAgBR,CAAA,EAAA,MAAA,CAAA,EAhBqB,WAgBrB,CAAA,EAhBmC,OAgBnC,CAhB2C,CAgB3C,EAAA,CAAA;;;;;;AAc/C;AACwB,iBAjBD,SAiBC,CAAA,CAAA,EAAA,CAAA,CAAA,CAAA,MAAA,EAhBd,aAgBc,CAhBA,CAgBA,CAAA,EAAA,EAAA,EAAA,CAAA,KAAA,EAfV,CAeU,EAAA,KAAA,EAAA,MAAA,EAAA,GAfW,CAeX,GAfe,OAef,CAfuB,CAevB,CAAA,EAAA,MAAA,CAAA,EAdb,WAca,CAAA,EAbrB,aAaqB,CAbP,CAaO,CAAA;;;;;;AAGrB,iBAJoB,MAIpB,CAAA,CAAA,CAAA,CAAA,MAAA,EAHO,aAGP,CAHqB,CAGrB,CAAA,EAAA,IAAA,EAAA,CAAA,KAAA,EAFa,CAEb,EAAA,KAAA,EAAA,MAAA,EAAA,GAAA,OAAA,GAF4C,OAE5C,CAAA,OAAA,CAAA,EAAA,MAAA,CAAA,EADQ,WACR,CAAA,EAAA,aAAA,CAAc,CAAd,CAAA;;AAYH;;;;AAIiB,iBAJM,IAIN,CAAA,CAAA,CAAA,CAAA,MAAA,EAHP,aAGO,CAHO,CAGP,CAAA,EAAA,CAAA,EAAA,MAAA,EAAA,MAAA,CAAA,EADN,WACM,CAAA,EAAd,aAAc,CAAA,CAAA,CAAA;;;AAejB;;;;AAE+C,iBAFxB,SAEwB,CAAA,CAAA,CAAA,CAAA,MAAA,EADrC,aACqC,CADvB,CACuB,CAAA,EAAA,IAAA,EAAA,CAAA,KAAA,EAA/B,CAA+B,EAAA,KAAA,EAAA,MAAA,EAAA,GAAA,OAAA,GAAA,OAAA,CAAA,OAAA,CAAA,EAAA,MAAA,CAAA,EACpC,WADoC,CAAA,EAE5C,aAF4C,CAE9B,CAF8B,CAAA;;;;;AAiB/C;;;AACW,iBADY,KACZ,CAAA,CAAA,CAAA,CAAA,OAAA,EAAA,aAAA,CAAc,aAAd,CAA4B,CAA5B,CAAA,CAAA,EAAA,MAAA,CAAA,EACA,WADA,CAAA,EAER,aAFQ,CAEM,CAFN,CAAA;;;;;AAiFX;;AACU,iBADa,UACb,CAAA,CAAA,CAAA,CAAA,MAAA,EAAA,aAAA,CAAc,CAAd,CAAA,EAAA,MAAA,CAAA,EACC,WADD,CAAA,EAEP,aAFO,CAEO,CAFP,CAAA"}