@graphorin/core 0.5.0 → 0.6.0

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

@@ -1 +1 @@
-{"version":3,"file":"tool.d.ts","names":[],"sources":["../../src/types/tool.ts"],"sourcesContent":[],"mappings":";;;;;;;;AAWA;AAsBA;AAyBA;AAmBA;AAuBA;AAUA;AAeY,KAlHA,aAAA,GAkHU,MAAA,GAAA,WAAA,GAAA,UAAA,GAAA,QAAA;AAmBtB;AAgBA;;;;;AAgCA;AA+BA;AAmBA;AAiBA;;;;;AASA;AAcA;;;;;KAzPY,eAAA;;;;;;;;;;;;;;;;;;;KAyBA,eAAA;;;;;;;;;;;;;;;;;;KAmBA,yBAAA;;;;;;;;;;;;;;;;;KAuBA,kBAAA;;;;;;;;;KAUA,cAAA;;;;;;;;KAeA,UAAA;;;;;;;;;;;;;;;;;;;;;;;;KAmBA,YAAA;;;;;;;;;iBAGiC;;;;;;;;UAa5B;;;mBAGE;;;;;;mCAAO,cAAA;;;;;;;;;;0BAgBA;;;;;;;;;;;;UAaT,YAAA;;;;;;;;;;;;;;;;;;;;;;gCAsBe;;;;;;;;KASpB,aAAA;;;;;;;UAmBK,SAAA;;;iBAGA;;;;;;;;;;;;;KAcL,iCAAiC,WAAW,WAAW;;;;;;;;UASlD,YAAA;;;;;;;;;;;;;UAcA;iBACA;oBACG,YAAY"}
+{"version":3,"file":"tool.d.ts","names":[],"sources":["../../src/types/tool.ts"],"sourcesContent":[],"mappings":";;;;;;;;AAWA;AAsBA;AAyBA;AAmBA;AAuBA;AAUA;AAeY,KAlHA,aAAA,GAkHU,MAAA,GAAA,WAAA,GAAA,UAAA,GAAA,QAAA;AAmBtB;AAgBA;;;;;AAgCA;AA+BA;AA8BA;AAQA;AAyBA;;;;;AASA;AAcA;;;;AAE+B,KAtRnB,eAAA,GAsRmB,MAAA,GAAA,0BAAA,GAAA,cAAA,GAAA,SAAA,GAAA,WAAA;;;;;;;;;;;;;;;;;;;KA7PnB,eAAA;;;;;;;;;;;;;;;;;;KAmBA,yBAAA;;;;;;;;;;;;;;;;;KAuBA,kBAAA;;;;;;;;;KAUA,cAAA;;;;;;;;KAeA,UAAA;;;;;;;;;;;;;;;;;;;;;;;;KAmBA,YAAA;;;;;;;;;iBAGiC;;;;;;;;UAa5B;;;mBAGE;;;;;;mCAAO,cAAA;;;;;;;;;;0BAgBA;;;;;;;;;;;;UAaT,YAAA;;;;;;;;;;;;;;;;;;;;;;gCAsBe;;;;;;;;KASpB,aAAA;;;;;;;;;;;;;;;;;KA8BA,YAAA;;;;;;;UAQK,SAAA;;;iBAGA;;;;;;;;;;;;;0BAaS;;;;;;;;KASd,iCAAiC,WAAW,WAAW;;;;;;;;UASlD,YAAA;;;;;;;;;;;;;UAcA;iBACA;oBACG,YAAY"}

package/dist/types/usage.d.ts

@@ -3,15 +3,37 @@
  * 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
+ * pricing snapshot - providers/middleware fill it in (e.g. through the
  * separate `@graphorin/pricing` package) when the snapshot is available.
  *
  * @stable
  */
 interface Usage {
+  /**
+   * Total input tokens for the call, INCLUDING any prompt-cache reads and
+   * writes (`cachedReadTokens` / `cacheWriteTokens` are informational
+   * subsets, not additions). This matches the context size the model saw.
+   */
   promptTokens: number;
   completionTokens: number;
+  /**
+   * Reasoning tokens billed IN ADDITION to `completionTokens` (exclusive;
+   * adapters that receive an inclusive total split it so the sum stays
+   * exact). Cost formulas may add this to the output leg without
+   * double-counting.
+   */
   reasoningTokens?: number;
+  /**
+   * Prompt tokens served from the provider's prompt cache (a subset of
+   * `promptTokens`), billed at the discounted cache-read rate.
+   */
+  cachedReadTokens?: number;
+  /**
+   * Prompt tokens written to the provider's prompt cache this call (a
+   * subset of `promptTokens`), billed at the cache-write premium where the
+   * provider charges one (Anthropic does; OpenAI does not report writes).
+   */
+  cacheWriteTokens?: number;
   totalTokens: number;
   cost?: Cost;
 }
@@ -38,6 +60,8 @@ interface ModelUsage {
   promptTokens: number;
   completionTokens: number;
   reasoningTokens?: number;
+  cachedReadTokens?: number;
+  cacheWriteTokens?: number;
   totalTokens: number;
   cost?: Cost;
   callCount: number;

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

@@ -1 +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"}
+{"version":3,"file":"usage.d.ts","names":[],"sources":["../../src/types/usage.ts"],"sourcesContent":[],"mappings":";;AASA;AAoCA;AAaA;AAoBA;;;;;AAWc,UAhFG,KAAA,CAgFH;EAAa;AAQ3B;AAUA;;;;;;;;;;;;;;;;;;;;;;;;SAvES;;;;;;;;UASQ,IAAA;;;;;;;;;;;;UAaA,UAAA;;;;;;;;SAQR;;;;;;;;;;;UAYQ,gBAAA;;kBAEC;;oBAEE,oBAAoB;;8BAGV;;;;cAIhB;;;;;;;UAQG,aAAA;kBACC;6BACW;;;;;;;iBAQb,SAAA,CAAA,GAAa"}

package/dist/types/usage.js.map

@@ -1 +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"}
+{"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  /**\n   * Total input tokens for the call, INCLUDING any prompt-cache reads and\n   * writes (`cachedReadTokens` / `cacheWriteTokens` are informational\n   * subsets, not additions). This matches the context size the model saw.\n   */\n  promptTokens: number;\n  completionTokens: number;\n  /**\n   * Reasoning tokens billed IN ADDITION to `completionTokens` (exclusive;\n   * adapters that receive an inclusive total split it so the sum stays\n   * exact). Cost formulas may add this to the output leg without\n   * double-counting.\n   */\n  reasoningTokens?: number;\n  /**\n   * Prompt tokens served from the provider's prompt cache (a subset of\n   * `promptTokens`), billed at the discounted cache-read rate.\n   */\n  cachedReadTokens?: number;\n  /**\n   * Prompt tokens written to the provider's prompt cache this call (a\n   * subset of `promptTokens`), billed at the cache-write premium where the\n   * provider charges one (Anthropic does; OpenAI does not report writes).\n   */\n  cacheWriteTokens?: 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  cachedReadTokens?: number;\n  cacheWriteTokens?: 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":";;;;;;AA2GA,SAAgB,YAAmB;AACjC,QAAO;EAAE,cAAc;EAAG,kBAAkB;EAAG,aAAa;EAAG"}

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

@@ -49,6 +49,13 @@ interface WorkflowChannelUpdateEvent<TState = unknown> {
   readonly stepNumber: number;
   readonly channel: keyof TState & string;
   readonly version: number;
+  /**
+   * The merged value, carried ONLY for `ephemeral` channels
+   * (workflow-07): their values are wiped from state before the next
+   * planning round, so this event is the one place a consumer can
+   * observe them. Persistent channels omit it - read the state instead.
+   */
+  readonly value?: unknown;
 }
 /** @stable */
 interface WorkflowCheckpointWrittenEvent {
@@ -57,7 +64,7 @@ interface WorkflowCheckpointWrittenEvent {
   readonly stepNumber: number;
 }
 /**
- * Workflow paused — for HITL approvals or programmatic `pause(value)`
+ * 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.
  *

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

@@ -1 +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"}
+{"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;AAejB;AAaA;AASiB,UAvDA,sBAAA,CAuDoB;EAQpB,SAAA,IAAA,EAAA,qBAAgB;EAOhB,SAAA,UAAA,EAAkB,MAAA;EAYlB,SAAA,MAAA,EAAA,MAAmB;;;;UA1EnB,oBAAA;;;;;;;;;UAUA;;;0BAGS;;;;;;;;;;;UAYT,8BAAA;;;;;;;;;;;;UAaA;;;;kBAIC;;;;UAKD;;;;kBAIC;;;UAID;;;kBAGC;;;UAID,kBAAA;;;;;;;;;;;;;;UAYA,mBAAA"}

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

@@ -3,7 +3,7 @@
  * 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.
+ * site into a compile error - the regression net for our event unions.
  *
  * @example
  * ```ts

package/dist/utils/assert-never.js

@@ -3,7 +3,7 @@
 * 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.
+* site into a compile error - the regression net for our event unions.
 *
 * @example
 * ```ts

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

@@ -1 +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"}
+{"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/hash.d.ts

@@ -3,22 +3,24 @@
  * 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).
+ * MD5 is **not** collision-resistant (practical chosen-prefix
+ * collisions exist) and is **not** used as a cryptographic primitive
+ * here - it is a fast content-addressing convenience where an
+ * adversarial collision merely suppresses a duplicate memory write.
+ * Do not use this helper for password hashing, MAC, tamper evidence,
+ * or any other security-sensitive use case (use `@graphorin/security`
+ * for those; the audit log uses SHA-256).
  *
  * @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)`
+ * - 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
+ * Not security-sensitive - never use for tampering detection of an
  * untrusted attacker; for that the audit log uses SHA-256 (in
  * `@graphorin/security`).
  *

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

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

package/dist/utils/hash.js

@@ -5,11 +5,13 @@ import { createHash } from "node:crypto";
 * 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).
+* MD5 is **not** collision-resistant (practical chosen-prefix
+* collisions exist) and is **not** used as a cryptographic primitive
+* here - it is a fast content-addressing convenience where an
+* adversarial collision merely suppresses a duplicate memory write.
+* Do not use this helper for password hashing, MAC, tamper evidence,
+* or any other security-sensitive use case (use `@graphorin/security`
+* for those; the audit log uses SHA-256).
 *
 * @stable
 */
@@ -21,11 +23,11 @@ function md5(content) {
 }
 /**
 * Pure-JS XXH32 implementation. Used by the memory-modification guard
-* — fast, non-cryptographic content fingerprinting (`xxhash(content)`
+* - 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
+* Not security-sensitive - never use for tampering detection of an
 * untrusted attacker; for that the audit log uses SHA-256 (in
 * `@graphorin/security`).
 *

package/dist/utils/hash.js.map

@@ -1 +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"}
+{"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** collision-resistant (practical chosen-prefix\n * collisions exist) and is **not** used as a cryptographic primitive\n * here - it is a fast content-addressing convenience where an\n * adversarial collision merely suppresses a duplicate memory write.\n * Do not use this helper for password hashing, MAC, tamper evidence,\n * or any other security-sensitive use case (use `@graphorin/security`\n * for those; the audit log uses SHA-256).\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":";;;;;;;;;;;;;;;;;AAgBA,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/validation.d.ts

@@ -48,7 +48,7 @@ type ValidationResult<T> = {
 };
 /**
  * Synchronous validation wrapper. Does **not** swallow errors thrown by
- * the schema's transformations — only normalizes the success / failure
+ * the schema's transformations - only normalizes the success / failure
  * signal.
  *
  * @stable

package/dist/utils/validation.js

@@ -1,7 +1,7 @@
 //#region src/utils/validation.ts
 /**
 * Synchronous validation wrapper. Does **not** swallow errors thrown by
-* the schema's transformations — only normalizes the success / failure
+* the schema's transformations - only normalizes the success / failure
 * signal.
 *
 * @stable

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    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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphorin/core",
-  "version": "0.5.0",
+  "version": "0.6.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",