@graphorin/core 0.5.0 → 0.6.1

package/dist/channels/pause.d.ts

@@ -12,7 +12,7 @@ declare const PAUSE_SIGNAL_BRAND: unique symbol;
  * 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 —
+ * Application code should never construct or catch this directly -
  * always go through `pause(...)`.
  *
  * @stable
@@ -46,12 +46,12 @@ interface PauseResumeScope {
  * {@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
+ * 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
+ * Consumers of `pause(...)` never call it directly - only the workflow
  * engine wires it up around the resumed node body.
  *
  * @internal

package/dist/channels/pause.js

@@ -14,7 +14,7 @@ const PAUSE_SIGNAL_BRAND = Symbol.for("graphorin.PauseSignal");
 * 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 —
+* Application code should never construct or catch this directly -
 * always go through `pause(...)`.
 *
 * @stable
@@ -35,12 +35,12 @@ const pauseResumeStorage = new AsyncLocalStorage();
 * {@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
+* 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
+* Consumers of `pause(...)` never call it directly - only the workflow
 * engine wires it up around the resumed node body.
 *
 * @internal

package/dist/channels/pause.js.map

@@ -1 +1 @@
-{"version":3,"file":"pause.js","names":["PAUSE_SIGNAL_BRAND: unique symbol","scope: PauseResumeScope"],"sources":["../../src/channels/pause.ts"],"sourcesContent":["import { AsyncLocalStorage } from 'node:async_hooks';\n\n/**\n * Brand attached to the signal thrown by `pause(value)` so that the\n * workflow runtime can recognise it across realms (Worker threads,\n * sandboxes, …) without `instanceof`.\n *\n * @stable\n */\nexport const PAUSE_SIGNAL_BRAND: unique symbol = Symbol.for('graphorin.PauseSignal');\n\n/**\n * Thrown by `pause(value)` from inside a workflow node. The runtime\n * catches it, persists state with a pending pause, and suspends the\n * thread until `Workflow.resume(threadId, directive)` is called.\n *\n * Application code should never construct or catch this directly —\n * always go through `pause(...)`.\n *\n * @stable\n */\nexport class PauseSignal<TValue = unknown> extends Error {\n  readonly [PAUSE_SIGNAL_BRAND]: true = true;\n  readonly value: TValue;\n\n  constructor(value: TValue) {\n    super('graphorin: workflow paused');\n    this.name = 'PauseSignal';\n    this.value = value;\n  }\n}\n\n/**\n * Resume-injection scope set by the workflow runtime around the second\n * (and later) invocations of a paused node body. When the scope is\n * present, `pause(...)` consults it to decide whether to throw a fresh\n * {@link PauseSignal} or return the injected value the runtime supplied\n * via `Workflow.resume(threadId, new Directive({ resume }))`.\n *\n * This is the storage mechanism that gives `pause()` its symmetric\n * pair semantics (`pause` ↔ `resume`) without forcing every node body\n * to be re-architected as a state machine.\n *\n * @internal\n */\nexport interface PauseResumeScope {\n  /** Ordered resume values replayed to successive `pause()` calls (WF-2). */\n  readonly values: ReadonlyArray<unknown>;\n  cursor: number;\n}\n\nconst pauseResumeStorage = new AsyncLocalStorage<PauseResumeScope>();\n\n/**\n * Run `fn` inside a scope where successive `pause(...)` calls return the\n * supplied `values` in order instead of throwing a fresh\n * {@link PauseSignal} (WF-2: a node body re-executes from the top on\n * every resume, so earlier pauses must replay their already-delivered\n * values and only the FIRST unsatisfied `pause()` suspends again). An\n * empty `values` array behaves exactly like no scope — every `pause()`\n * suspends — which is what a static-gate resume needs so a programmatic\n * `pause()` inside the node is never silently satisfied.\n *\n * This helper is the contract between the runtime and `pause(...)`.\n * Consumers of `pause(...)` never call it directly — only the workflow\n * engine wires it up around the resumed node body.\n *\n * @internal\n */\nexport function runWithPauseResume<R>(\n  values: ReadonlyArray<unknown>,\n  fn: () => R | Promise<R>,\n): Promise<R> {\n  const scope: PauseResumeScope = { values, cursor: 0 };\n  return pauseResumeStorage.run(scope, async () => fn());\n}\n\n/**\n * Programmatically suspend the current workflow node. The `value` is\n * surfaced to callers via the `WorkflowSuspendedEvent.value` field; the\n * eventual `Directive({ resume })` is delivered as the return value of\n * this call once the runtime resumes the thread.\n *\n * Implementation note: when the call is made outside a runtime-managed\n * resume scope, `pause(...)` throws a fresh {@link PauseSignal} so the\n * engine can catch it, persist state, and suspend. When the runtime\n * later resumes the node body, it wraps the second invocation in\n * {@link runWithPauseResume}, which causes the same `pause(...)` call to\n * return the operator-supplied resume value instead of throwing.\n *\n * @stable\n */\nexport function pause<TValue, TResume = unknown>(value: TValue): TResume {\n  const scope = pauseResumeStorage.getStore();\n  if (scope !== undefined && scope.cursor < scope.values.length) {\n    const next = scope.values[scope.cursor];\n    scope.cursor += 1;\n    return next as TResume;\n  }\n  throw new PauseSignal<TValue>(value);\n}\n\n/**\n * Cross-realm safe type guard for `PauseSignal`.\n *\n * @stable\n */\nexport function isPauseSignal(err: unknown): err is PauseSignal {\n  return (\n    typeof err === 'object' &&\n    err !== null &&\n    (err as Record<symbol, unknown>)[PAUSE_SIGNAL_BRAND] === true\n  );\n}\n"],"mappings":";;;;;;;;;;AASA,MAAaA,qBAAoC,OAAO,IAAI,wBAAwB;;;;;;;;;;;AAYpF,IAAa,cAAb,cAAmD,MAAM;CACvD,CAAU,sBAA4B;CACtC,AAAS;CAET,YAAY,OAAe;AACzB,QAAM,6BAA6B;AACnC,OAAK,OAAO;AACZ,OAAK,QAAQ;;;AAuBjB,MAAM,qBAAqB,IAAI,mBAAqC;;;;;;;;;;;;;;;;;AAkBpE,SAAgB,mBACd,QACA,IACY;CACZ,MAAMC,QAA0B;EAAE;EAAQ,QAAQ;EAAG;AACrD,QAAO,mBAAmB,IAAI,OAAO,YAAY,IAAI,CAAC;;;;;;;;;;;;;;;;;AAkBxD,SAAgB,MAAiC,OAAwB;CACvE,MAAM,QAAQ,mBAAmB,UAAU;AAC3C,KAAI,UAAU,UAAa,MAAM,SAAS,MAAM,OAAO,QAAQ;EAC7D,MAAM,OAAO,MAAM,OAAO,MAAM;AAChC,QAAM,UAAU;AAChB,SAAO;;AAET,OAAM,IAAI,YAAoB,MAAM;;;;;;;AAQtC,SAAgB,cAAc,KAAkC;AAC9D,QACE,OAAO,QAAQ,YACf,QAAQ,QACP,IAAgC,wBAAwB"}
+{"version":3,"file":"pause.js","names":["PAUSE_SIGNAL_BRAND: unique symbol","scope: PauseResumeScope"],"sources":["../../src/channels/pause.ts"],"sourcesContent":["import { AsyncLocalStorage } from 'node:async_hooks';\n\n/**\n * Brand attached to the signal thrown by `pause(value)` so that the\n * workflow runtime can recognise it across realms (Worker threads,\n * sandboxes, …) without `instanceof`.\n *\n * @stable\n */\nexport const PAUSE_SIGNAL_BRAND: unique symbol = Symbol.for('graphorin.PauseSignal');\n\n/**\n * Thrown by `pause(value)` from inside a workflow node. The runtime\n * catches it, persists state with a pending pause, and suspends the\n * thread until `Workflow.resume(threadId, directive)` is called.\n *\n * Application code should never construct or catch this directly -\n * always go through `pause(...)`.\n *\n * @stable\n */\nexport class PauseSignal<TValue = unknown> extends Error {\n  readonly [PAUSE_SIGNAL_BRAND]: true = true;\n  readonly value: TValue;\n\n  constructor(value: TValue) {\n    super('graphorin: workflow paused');\n    this.name = 'PauseSignal';\n    this.value = value;\n  }\n}\n\n/**\n * Resume-injection scope set by the workflow runtime around the second\n * (and later) invocations of a paused node body. When the scope is\n * present, `pause(...)` consults it to decide whether to throw a fresh\n * {@link PauseSignal} or return the injected value the runtime supplied\n * via `Workflow.resume(threadId, new Directive({ resume }))`.\n *\n * This is the storage mechanism that gives `pause()` its symmetric\n * pair semantics (`pause` ↔ `resume`) without forcing every node body\n * to be re-architected as a state machine.\n *\n * @internal\n */\nexport interface PauseResumeScope {\n  /** Ordered resume values replayed to successive `pause()` calls (WF-2). */\n  readonly values: ReadonlyArray<unknown>;\n  cursor: number;\n}\n\nconst pauseResumeStorage = new AsyncLocalStorage<PauseResumeScope>();\n\n/**\n * Run `fn` inside a scope where successive `pause(...)` calls return the\n * supplied `values` in order instead of throwing a fresh\n * {@link PauseSignal} (WF-2: a node body re-executes from the top on\n * every resume, so earlier pauses must replay their already-delivered\n * values and only the FIRST unsatisfied `pause()` suspends again). An\n * empty `values` array behaves exactly like no scope - every `pause()`\n * suspends - which is what a static-gate resume needs so a programmatic\n * `pause()` inside the node is never silently satisfied.\n *\n * This helper is the contract between the runtime and `pause(...)`.\n * Consumers of `pause(...)` never call it directly - only the workflow\n * engine wires it up around the resumed node body.\n *\n * @internal\n */\nexport function runWithPauseResume<R>(\n  values: ReadonlyArray<unknown>,\n  fn: () => R | Promise<R>,\n): Promise<R> {\n  const scope: PauseResumeScope = { values, cursor: 0 };\n  return pauseResumeStorage.run(scope, async () => fn());\n}\n\n/**\n * Programmatically suspend the current workflow node. The `value` is\n * surfaced to callers via the `WorkflowSuspendedEvent.value` field; the\n * eventual `Directive({ resume })` is delivered as the return value of\n * this call once the runtime resumes the thread.\n *\n * Implementation note: when the call is made outside a runtime-managed\n * resume scope, `pause(...)` throws a fresh {@link PauseSignal} so the\n * engine can catch it, persist state, and suspend. When the runtime\n * later resumes the node body, it wraps the second invocation in\n * {@link runWithPauseResume}, which causes the same `pause(...)` call to\n * return the operator-supplied resume value instead of throwing.\n *\n * @stable\n */\nexport function pause<TValue, TResume = unknown>(value: TValue): TResume {\n  const scope = pauseResumeStorage.getStore();\n  if (scope !== undefined && scope.cursor < scope.values.length) {\n    const next = scope.values[scope.cursor];\n    scope.cursor += 1;\n    return next as TResume;\n  }\n  throw new PauseSignal<TValue>(value);\n}\n\n/**\n * Cross-realm safe type guard for `PauseSignal`.\n *\n * @stable\n */\nexport function isPauseSignal(err: unknown): err is PauseSignal {\n  return (\n    typeof err === 'object' &&\n    err !== null &&\n    (err as Record<symbol, unknown>)[PAUSE_SIGNAL_BRAND] === true\n  );\n}\n"],"mappings":";;;;;;;;;;AASA,MAAaA,qBAAoC,OAAO,IAAI,wBAAwB;;;;;;;;;;;AAYpF,IAAa,cAAb,cAAmD,MAAM;CACvD,CAAU,sBAA4B;CACtC,AAAS;CAET,YAAY,OAAe;AACzB,QAAM,6BAA6B;AACnC,OAAK,OAAO;AACZ,OAAK,QAAQ;;;AAuBjB,MAAM,qBAAqB,IAAI,mBAAqC;;;;;;;;;;;;;;;;;AAkBpE,SAAgB,mBACd,QACA,IACY;CACZ,MAAMC,QAA0B;EAAE;EAAQ,QAAQ;EAAG;AACrD,QAAO,mBAAmB,IAAI,OAAO,YAAY,IAAI,CAAC;;;;;;;;;;;;;;;;;AAkBxD,SAAgB,MAAiC,OAAwB;CACvE,MAAM,QAAQ,mBAAmB,UAAU;AAC3C,KAAI,UAAU,UAAa,MAAM,SAAS,MAAM,OAAO,QAAQ;EAC7D,MAAM,OAAO,MAAM,OAAO,MAAM;AAChC,QAAM,UAAU;AAChB,SAAO;;AAET,OAAM,IAAI,YAAoB,MAAM;;;;;;;AAQtC,SAAgB,cAAc,KAAkC;AAC9D,QACE,OAAO,QAAQ,YACf,QAAQ,QACP,IAAgC,wBAAwB"}

package/dist/contracts/auth-token-store.d.ts

@@ -13,7 +13,7 @@ interface AuthTokenRecord {
   readonly hashHex: string;
   /** Optional human-readable label rendered in CLI listings. */
   readonly label?: string;
-  /** Scope grammar — opaque strings of the form `<resource>:<action>[:<id-or-glob>]`. */
+  /** Scope grammar - opaque strings of the form `<resource>:<action>[:<id-or-glob>]`. */
   readonly scopes: ReadonlyArray<string>;
   readonly createdAt: string;
   readonly expiresAt?: string;
@@ -35,7 +35,7 @@ interface AuthTokenStore {
   recordUse(id: string, usedAt: string): Promise<void>;
   /**
    * Indexed lookup by HMAC hash (SPL-19). When present, the verifier
-   * uses it on cache-miss instead of walking `list()` — O(1) instead of
+   * uses it on cache-miss instead of walking `list()` - O(1) instead of
    * an O(n) full-table scan per verification.
    */
   getByHash?(hashHex: string): Promise<AuthTokenRecord | null>;

package/dist/contracts/checkpoint-store.d.ts

@@ -18,7 +18,7 @@ interface Checkpoint {
   readonly threadId: string;
   readonly namespace: string;
   readonly parentId?: CheckpointId;
-  /** Serialized state blob — adapter-specific encoding (JSON / superjson / …). */
+  /** Serialized state blob - adapter-specific encoding (JSON / superjson / …). */
   readonly state: unknown;
   /** Per-channel monotonic versions used by the workflow scheduler. */
   readonly channelVersions: Readonly<Record<string, number>>;
@@ -32,7 +32,13 @@ interface Checkpoint {
  * @stable
  */
 interface CheckpointMetadata {
-  readonly source: 'sync' | 'async' | 'exit';
+  /**
+   * Durability mode that produced this write. The legacy `'async'`
+   * value was removed (workflow-14 / WF-7 - it was byte-identical to
+   * `'sync'`); adapters normalize legacy persisted rows to `'sync'` at
+   * read time.
+   */
+  readonly source: 'sync' | 'exit';
   readonly status: 'running' | 'suspended' | 'completed' | 'failed' | 'aborted';
   readonly nodeName?: string;
   readonly tags?: ReadonlyArray<string>;
@@ -59,7 +65,7 @@ interface PendingWrite {
   readonly taskId: string;
   readonly index: number;
   readonly channel: string;
-  /** Serialized value blob — adapter-specific encoding. */
+  /** Serialized value blob - adapter-specific encoding. */
   readonly value: unknown;
 }
 /**
@@ -72,6 +78,36 @@ interface ListOptions {
   readonly before?: CheckpointId;
   readonly status?: CheckpointMetadata['status'];
 }
+/**
+ * Optional atomicity contract for {@link CheckpointStore.put} (D1 /
+ * workflow-01). When `expectedLatestId` is supplied, the store MUST
+ * perform the latest-checkpoint comparison and the insert atomically
+ * (single transaction / synchronous critical section) and throw
+ * {@link CheckpointConflictError} on mismatch - closing the TOCTOU
+ * window an engine-level read-then-write cannot. `null` means "expect
+ * no checkpoint for this thread yet"; `undefined` (or a store that
+ * ignores the argument) preserves the unguarded legacy behaviour, which
+ * the engine backstops with its own pre-check.
+ *
+ * @stable
+ */
+interface CheckpointPutOptions {
+  readonly expectedLatestId?: CheckpointId | null;
+}
+/**
+ * Thrown by a {@link CheckpointStore.put} honouring
+ * {@link CheckpointPutOptions.expectedLatestId} when another writer
+ * advanced the thread in between. The workflow engine maps it to its
+ * `checkpoint-version-conflict` error.
+ *
+ * @stable
+ */
+declare class CheckpointConflictError extends Error {
+  readonly threadId: string;
+  readonly expectedLatestId: CheckpointId | null;
+  readonly actualLatestId: CheckpointId | null;
+  constructor(threadId: string, expected: CheckpointId | null, actual: CheckpointId | null);
+}
 /**
  * Pluggable checkpoint storage interface. The default implementation
  * lives in `@graphorin/store-sqlite`.
@@ -79,12 +115,12 @@ interface ListOptions {
  * @stable
  */
 interface CheckpointStore {
-  put(threadId: string, namespace: string, checkpoint: Checkpoint, metadata: CheckpointMetadata): Promise<CheckpointId>;
+  put(threadId: string, namespace: string, checkpoint: Checkpoint, metadata: CheckpointMetadata, opts?: CheckpointPutOptions): Promise<CheckpointId>;
   putWrites(threadId: string, namespace: string, checkpointId: CheckpointId, writes: ReadonlyArray<PendingWrite>, taskId: string): Promise<void>;
   getTuple(threadId: string, namespace: string, checkpointId?: CheckpointId): Promise<CheckpointTuple | null>;
   list(threadId: string, namespace: string, opts?: ListOptions): AsyncIterable<CheckpointTuple>;
   deleteThread(threadId: string): Promise<void>;
 }
 //#endregion
-export { Checkpoint, CheckpointId, CheckpointMetadata, CheckpointStore, CheckpointTuple, ListOptions, PendingWrite };
+export { Checkpoint, CheckpointConflictError, CheckpointId, CheckpointMetadata, CheckpointPutOptions, CheckpointStore, CheckpointTuple, ListOptions, PendingWrite };
 //# sourceMappingURL=checkpoint-store.d.ts.map

package/dist/contracts/checkpoint-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"checkpoint-store.d.ts","names":[],"sources":["../../src/contracts/checkpoint-store.ts"],"sourcesContent":[],"mappings":";;AAOA;AAQA;;;;;AAQoC,KAhBxB,YAAA,GAgBwB,MAAA;AAWpC;AAaA;;;;;AAGwC,UAnCvB,UAAA,CAmCuB;EAUvB,SAAA,EAAA,EA5CF,YA4Cc;EAaZ,SAAA,QAAW,EAAA,MAAA;EAYX,SAAA,SAAe,EAAA,MAAA;EAIhB,SAAA,QAAA,CAAA,EAtEM,YAsEN;EACF;EACD,SAAA,KAAA,EAAA,OAAA;EAAR;EAKa,SAAA,eAAA,EAzEU,QAyEV,CAzEmB,MAyEnB,CAAA,MAAA,EAAA,MAAA,CAAA,CAAA;EACQ,SAAA,UAAA,EAAA,MAAA;EAAd,SAAA,SAAA,EAAA,MAAA;;;;;;;;AAYsB,UA3EjB,kBAAA,CA2EiB;EAAO,SAAA,MAAA,EAAA,MAAA,GAAA,OAAA,GAAA,MAAA;;;kBAvEvB;;;;;;;;UASD,eAAA;uBACM;qBACF;2BACM,cAAc;;;;;;;;;UAUxB,YAAA;;;;;;;;;;;;UAaA,WAAA;;oBAEG;oBACA;;;;;;;;UASH,eAAA;uDAID,sBACF,qBACT,QAAQ;+DAKK,sBACN,cAAc,gCAErB;+DAKc,eACd,QAAQ;mDAEsC,cAAc,cAAc;kCAE7C"}
+{"version":3,"file":"checkpoint-store.d.ts","names":[],"sources":["../../src/contracts/checkpoint-store.ts"],"sourcesContent":[],"mappings":";;AAOA;AAQA;;;;;AAQoC,KAhBxB,YAAA,GAgBwB,MAAA;AAWpC;AAmBA;;;;;AAGwC,UAzCvB,UAAA,CAyCuB;EAUvB,SAAA,EAAA,EAlDF,YAkDc;EAaZ,SAAA,QAAW,EAAA,MAER;EAiBH,SAAA,SAAA,EAAA,MAAoB;EAYxB,SAAA,QAAA,CAAA,EA3FS,YA2Fe;EAER;EACF,SAAA,KAAA,EAAA,OAAA;EAEe;EAA6B,SAAA,eAAA,EA5F3C,QA4F2C,CA5FlC,MA4FkC,CAAA,MAAA,EAAA,MAAA,CAAA,CAAA;EAL1B,SAAA,UAAA,EAAA,MAAA;EAAK,SAAA,SAAA,EAAA,MAAA;AAsBlD;;;;;;;AAa0B,UA/GT,kBAAA,CA+GS;EAAd;;;;;;EAUmE,SAAA,MAAA,EAAA,MAAA,GAAA,MAAA;EAAd,SAAA,MAAA,EAAA,SAAA,GAAA,WAAA,GAAA,WAAA,GAAA,QAAA,GAAA,SAAA;EAE/B,SAAA,QAAA,CAAA,EAAA,MAAA;EAAO,SAAA,IAAA,CAAA,EAjHvB,aAiHuB,CAAA,MAAA,CAAA;;;;;;;;UAxGxB,eAAA;uBACM;qBACF;2BACM,cAAc;;;;;;;;;UAUxB,YAAA;;;;;;;;;;;;UAaA,WAAA;;oBAEG;oBACA;;;;;;;;;;;;;;;UAgBH,oBAAA;8BACa;;;;;;;;;;cAWjB,uBAAA,SAAgC,KAAA;;6BAEhB;2BACF;0CAEe,6BAA6B;;;;;;;;UAiBtD,eAAA;uDAID,sBACF,2BACH,uBACN,QAAQ;+DAKK,sBACN,cAAc,gCAErB;+DAKc,eACd,QAAQ;mDAEsC,cAAc,cAAc;kCAE7C"}

package/dist/contracts/checkpoint-store.js

@@ -0,0 +1,25 @@
+//#region src/contracts/checkpoint-store.ts
+/**
+* Thrown by a {@link CheckpointStore.put} honouring
+* {@link CheckpointPutOptions.expectedLatestId} when another writer
+* advanced the thread in between. The workflow engine maps it to its
+* `checkpoint-version-conflict` error.
+*
+* @stable
+*/
+var CheckpointConflictError = class extends Error {
+	threadId;
+	expectedLatestId;
+	actualLatestId;
+	constructor(threadId, expected, actual) {
+		super(`checkpoint conflict on thread "${threadId}": expected latest ${expected ?? "<none>"}, found ${actual ?? "<none>"}`);
+		this.name = "CheckpointConflictError";
+		this.threadId = threadId;
+		this.expectedLatestId = expected;
+		this.actualLatestId = actual;
+	}
+};
+
+//#endregion
+export { CheckpointConflictError };
+//# sourceMappingURL=checkpoint-store.js.map

package/dist/contracts/checkpoint-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-store.js","names":[],"sources":["../../src/contracts/checkpoint-store.ts"],"sourcesContent":["/**\n * Opaque identifier for a single workflow checkpoint. Treated as a string\n * by every consumer so adapters can pick whatever encoding they prefer\n * (ULID, UUID, snowflake-like, …).\n *\n * @stable\n */\nexport type CheckpointId = string;\n\n/**\n * Serialized snapshot of workflow state, written after every execution\n * step.\n *\n * @stable\n */\nexport interface Checkpoint {\n  readonly id: CheckpointId;\n  readonly threadId: string;\n  readonly namespace: string;\n  readonly parentId?: CheckpointId;\n  /** Serialized state blob - adapter-specific encoding (JSON / superjson / …). */\n  readonly state: unknown;\n  /** Per-channel monotonic versions used by the workflow scheduler. */\n  readonly channelVersions: Readonly<Record<string, number>>;\n  readonly stepNumber: number;\n  readonly createdAt: string;\n}\n\n/**\n * Metadata associated with a checkpoint write. Adapters store this in a\n * sidecar table for efficient listing.\n *\n * @stable\n */\nexport interface CheckpointMetadata {\n  /**\n   * Durability mode that produced this write. The legacy `'async'`\n   * value was removed (workflow-14 / WF-7 - it was byte-identical to\n   * `'sync'`); adapters normalize legacy persisted rows to `'sync'` at\n   * read time.\n   */\n  readonly source: 'sync' | 'exit';\n  readonly status: 'running' | 'suspended' | 'completed' | 'failed' | 'aborted';\n  readonly nodeName?: string;\n  readonly tags?: ReadonlyArray<string>;\n}\n\n/**\n * A checkpoint paired with its sidecar metadata. Returned by\n * `CheckpointStore.getTuple(...)` and the `list(...)` iterator.\n *\n * @stable\n */\nexport interface CheckpointTuple {\n  readonly checkpoint: Checkpoint;\n  readonly metadata: CheckpointMetadata;\n  readonly pendingWrites?: ReadonlyArray<PendingWrite>;\n}\n\n/**\n * Per-task pending write. Captured when a task in an execution step\n * succeeds while a sibling task fails: the next resume attempt skips the\n * already-completed work.\n *\n * @stable\n */\nexport interface PendingWrite {\n  readonly taskId: string;\n  readonly index: number;\n  readonly channel: string;\n  /** Serialized value blob - adapter-specific encoding. */\n  readonly value: unknown;\n}\n\n/**\n * Optional listing range for `CheckpointStore.list(...)`.\n *\n * @stable\n */\nexport interface ListOptions {\n  readonly limit?: number;\n  readonly before?: CheckpointId;\n  readonly status?: CheckpointMetadata['status'];\n}\n\n/**\n * Optional atomicity contract for {@link CheckpointStore.put} (D1 /\n * workflow-01). When `expectedLatestId` is supplied, the store MUST\n * perform the latest-checkpoint comparison and the insert atomically\n * (single transaction / synchronous critical section) and throw\n * {@link CheckpointConflictError} on mismatch - closing the TOCTOU\n * window an engine-level read-then-write cannot. `null` means \"expect\n * no checkpoint for this thread yet\"; `undefined` (or a store that\n * ignores the argument) preserves the unguarded legacy behaviour, which\n * the engine backstops with its own pre-check.\n *\n * @stable\n */\nexport interface CheckpointPutOptions {\n  readonly expectedLatestId?: CheckpointId | null;\n}\n\n/**\n * Thrown by a {@link CheckpointStore.put} honouring\n * {@link CheckpointPutOptions.expectedLatestId} when another writer\n * advanced the thread in between. The workflow engine maps it to its\n * `checkpoint-version-conflict` error.\n *\n * @stable\n */\nexport class CheckpointConflictError extends Error {\n  readonly threadId: string;\n  readonly expectedLatestId: CheckpointId | null;\n  readonly actualLatestId: CheckpointId | null;\n\n  constructor(threadId: string, expected: CheckpointId | null, actual: CheckpointId | null) {\n    super(\n      `checkpoint conflict on thread \"${threadId}\": expected latest ${expected ?? '<none>'}, found ${actual ?? '<none>'}`,\n    );\n    this.name = 'CheckpointConflictError';\n    this.threadId = threadId;\n    this.expectedLatestId = expected;\n    this.actualLatestId = actual;\n  }\n}\n\n/**\n * Pluggable checkpoint storage interface. The default implementation\n * lives in `@graphorin/store-sqlite`.\n *\n * @stable\n */\nexport interface CheckpointStore {\n  put(\n    threadId: string,\n    namespace: string,\n    checkpoint: Checkpoint,\n    metadata: CheckpointMetadata,\n    opts?: CheckpointPutOptions,\n  ): Promise<CheckpointId>;\n\n  putWrites(\n    threadId: string,\n    namespace: string,\n    checkpointId: CheckpointId,\n    writes: ReadonlyArray<PendingWrite>,\n    taskId: string,\n  ): Promise<void>;\n\n  getTuple(\n    threadId: string,\n    namespace: string,\n    checkpointId?: CheckpointId,\n  ): Promise<CheckpointTuple | null>;\n\n  list(threadId: string, namespace: string, opts?: ListOptions): AsyncIterable<CheckpointTuple>;\n\n  deleteThread(threadId: string): Promise<void>;\n}\n"],"mappings":";;;;;;;;;AA8GA,IAAa,0BAAb,cAA6C,MAAM;CACjD,AAAS;CACT,AAAS;CACT,AAAS;CAET,YAAY,UAAkB,UAA+B,QAA6B;AACxF,QACE,kCAAkC,SAAS,qBAAqB,YAAY,SAAS,UAAU,UAAU,WAC1G;AACD,OAAK,OAAO;AACZ,OAAK,WAAW;AAChB,OAAK,mBAAmB;AACxB,OAAK,iBAAiB"}

package/dist/contracts/embedder.d.ts

@@ -33,7 +33,7 @@ interface EmbedOptions {
   readonly requestId?: string;
   /**
    * Asymmetric retrieval role of the input (PS-10). Embedders for models that
-   * require asymmetric prefixes — the E5 family's `query:` / `passage:` — apply
+   * require asymmetric prefixes - the E5 family's `query:` / `passage:` - apply
    * the matching prefix; embedders for symmetric models ignore it. Memory tiers
    * pass `'query'` when embedding a search query and `'passage'` when embedding
    * content for storage.

package/dist/contracts/index.d.ts

@@ -1,5 +1,5 @@
 import { AuthTokenRecord, AuthTokenStore } from "./auth-token-store.js";
-import { Checkpoint, CheckpointId, CheckpointMetadata, CheckpointStore, CheckpointTuple, ListOptions, PendingWrite } from "./checkpoint-store.js";
+import { Checkpoint, CheckpointConflictError, CheckpointId, CheckpointMetadata, CheckpointPutOptions, CheckpointStore, CheckpointTuple, ListOptions, PendingWrite } from "./checkpoint-store.js";
 import { EmbedOptions, EmbedderProvider } from "./embedder.js";
 import { EvalSample, EvalScore, EvalScorer } from "./eval-scorer.js";
 import { LocalProviderTrust, OllamaTrust } from "./local-provider-trust.js";
@@ -7,8 +7,9 @@ import { LogFields, LogLevel, Logger, NOOP_LOGGER } from "./logger.js";
 import { EpisodicMemoryStore, MemoryStore, MessageRef, ProceduralMemoryStore, SemanticMemoryStore, SessionListOptions, SessionMemoryStore, SessionMessageWithMetadata, SharedMemoryStore, WorkingMemoryStore } from "./memory-store.js";
 import { OAuthServerRecord, OAuthServerStore } from "./oauth-server-store.js";
 import { MODEL_HINTS, ModelHint, ModelSpec, ProviderLike } from "./preferred-model.js";
+import { AISpan, NOOP_TRACER, SpanAttributeValue, SpanAttributes, SpanStatus, SpanType, StartSpanOptions, Tracer } from "./tracer.js";
 import { ReasoningContract, ReasoningRetention } from "./reasoning-retention.js";
-import { ComposeProviderMiddleware, FinishReason, OutputSpec, Provider, ProviderCapabilities, ProviderError, ProviderErrorKind, ProviderEvent, ProviderMiddleware, ProviderRequest, ProviderRequestMetadata, ProviderResponse, ResponseMetadata, ToolChoice, ToolDefinition, ToolDefinitionExample } from "./provider.js";
+import { ComposeProviderMiddleware, FinishReason, OutputSpec, Provider, ProviderCachePolicy, ProviderCapabilities, ProviderError, ProviderErrorKind, ProviderEvent, ProviderMiddleware, ProviderRequest, ProviderRequestMetadata, ProviderResponse, ResponseMetadata, ToolChoice, ToolDefinition, ToolDefinitionExample } from "./provider.js";
 import { RedactionInput, RedactionOutput, RedactionValidator } from "./redaction-validator.js";
 import { Sandbox, SandboxCode, SandboxResult, SandboxRunOptions } from "./sandbox.js";
 import { SecretRef } from "./secret-ref.js";
@@ -16,7 +17,6 @@ import { NODEJS_INSPECT_CUSTOM, SECRET_VALUE_BRAND, SecretValue, SecretValueOpti
 import { SecretMetadata, SecretResolver, SecretResolverContext, SecretsSetOptions, SecretsStore } from "./secrets-store.js";
 import { AgentRegistryEntry, SessionAuditEntry, SessionMetadata, SessionStore, SessionStoreExt, SessionWorkflowRun } from "./session-store.js";
 import { TokenCounter } from "./token-counter.js";
-import { AISpan, NOOP_TRACER, SpanAttributeValue, SpanAttributes, SpanStatus, SpanType, StartSpanOptions, Tracer } from "./tracer.js";
 import { ResolvedTool, Tool, ToolExample, ToolExecutionContext, ToolReturn, ToolSecretsAccessor } from "./tool.js";
 import { TriggerState, TriggerStore } from "./trigger-store.js";
-export { type AISpan, type AgentRegistryEntry, type AuthTokenRecord, type AuthTokenStore, type Checkpoint, type CheckpointId, type CheckpointMetadata, type CheckpointStore, type CheckpointTuple, type ComposeProviderMiddleware, type EmbedOptions, type EmbedderProvider, type EpisodicMemoryStore, type EvalSample, type EvalScore, type EvalScorer, type FinishReason, type ListOptions, type LocalProviderTrust, type LogFields, type LogLevel, type Logger, MODEL_HINTS, type MemoryStore, type MessageRef, type ModelHint, type ModelSpec, NODEJS_INSPECT_CUSTOM, NOOP_LOGGER, NOOP_TRACER, type OAuthServerRecord, type OAuthServerStore, type OllamaTrust, type OutputSpec, type PendingWrite, type ProceduralMemoryStore, type Provider, type ProviderCapabilities, type ProviderError, type ProviderErrorKind, type ProviderEvent, type ProviderLike, type ProviderMiddleware, type ProviderRequest, type ProviderRequestMetadata, type ProviderResponse, type ReasoningContract, type ReasoningRetention, type RedactionInput, type RedactionOutput, type RedactionValidator, type ResolvedTool, type ResponseMetadata, SECRET_VALUE_BRAND, type Sandbox, type SandboxCode, type SandboxResult, type SandboxRunOptions, type SecretMetadata, type SecretRef, type SecretResolver, type SecretResolverContext, type SecretValue, type SecretValueOptions, type SecretValueStatic, type SecretsSetOptions, type SecretsStore, type SemanticMemoryStore, type SessionAuditEntry, type SessionListOptions, type SessionMemoryStore, type SessionMessageWithMetadata, type SessionMetadata, type SessionStore, type SessionStoreExt, type SessionWorkflowRun, type SharedMemoryStore, type SpanAttributeValue, type SpanAttributes, type SpanStatus, type SpanType, type StartSpanOptions, type TokenCounter, type Tool, type ToolChoice, type ToolDefinition, type ToolDefinitionExample, type ToolExample, type ToolExecutionContext, type ToolReturn, type ToolSecretsAccessor, type Tracer, type TriggerState, type TriggerStore, type WorkingMemoryStore };
+export { type AISpan, type AgentRegistryEntry, type AuthTokenRecord, type AuthTokenStore, type Checkpoint, CheckpointConflictError, type CheckpointId, type CheckpointMetadata, type CheckpointPutOptions, type CheckpointStore, type CheckpointTuple, type ComposeProviderMiddleware, type EmbedOptions, type EmbedderProvider, type EpisodicMemoryStore, type EvalSample, type EvalScore, type EvalScorer, type FinishReason, type ListOptions, type LocalProviderTrust, type LogFields, type LogLevel, type Logger, MODEL_HINTS, type MemoryStore, type MessageRef, type ModelHint, type ModelSpec, NODEJS_INSPECT_CUSTOM, NOOP_LOGGER, NOOP_TRACER, type OAuthServerRecord, type OAuthServerStore, type OllamaTrust, type OutputSpec, type PendingWrite, type ProceduralMemoryStore, type Provider, type ProviderCachePolicy, type ProviderCapabilities, type ProviderError, type ProviderErrorKind, type ProviderEvent, type ProviderLike, type ProviderMiddleware, type ProviderRequest, type ProviderRequestMetadata, type ProviderResponse, type ReasoningContract, type ReasoningRetention, type RedactionInput, type RedactionOutput, type RedactionValidator, type ResolvedTool, type ResponseMetadata, SECRET_VALUE_BRAND, type Sandbox, type SandboxCode, type SandboxResult, type SandboxRunOptions, type SecretMetadata, type SecretRef, type SecretResolver, type SecretResolverContext, type SecretValue, type SecretValueOptions, type SecretValueStatic, type SecretsSetOptions, type SecretsStore, type SemanticMemoryStore, type SessionAuditEntry, type SessionListOptions, type SessionMemoryStore, type SessionMessageWithMetadata, type SessionMetadata, type SessionStore, type SessionStoreExt, type SessionWorkflowRun, type SharedMemoryStore, type SpanAttributeValue, type SpanAttributes, type SpanStatus, type SpanType, type StartSpanOptions, type TokenCounter, type Tool, type ToolChoice, type ToolDefinition, type ToolDefinitionExample, type ToolExample, type ToolExecutionContext, type ToolReturn, type ToolSecretsAccessor, type Tracer, type TriggerState, type TriggerStore, type WorkingMemoryStore };

package/dist/contracts/index.js

@@ -1,6 +1,7 @@
+import { CheckpointConflictError } from "./checkpoint-store.js";
 import { NOOP_LOGGER } from "./logger.js";
 import { MODEL_HINTS } from "./preferred-model.js";
 import { NODEJS_INSPECT_CUSTOM, SECRET_VALUE_BRAND } from "./secret-value.js";
 import { NOOP_TRACER } from "./tracer.js";
 
-export { MODEL_HINTS, NODEJS_INSPECT_CUSTOM, NOOP_LOGGER, NOOP_TRACER, SECRET_VALUE_BRAND };
+export { CheckpointConflictError, MODEL_HINTS, NODEJS_INSPECT_CUSTOM, NOOP_LOGGER, NOOP_TRACER, SECRET_VALUE_BRAND };

package/dist/contracts/local-provider-trust.d.ts

@@ -9,15 +9,15 @@
  *
  * Tier semantics:
  *
- * - `'loopback'`         — `localhost` / `127.0.0.0/8` / `::1` /
+ * - `'loopback'`         - `localhost` / `127.0.0.0/8` / `::1` /
  *   `unix:///path` (or any in-process adapter that has no `baseUrl`).
  *   Same trust boundary as the host process.
- * - `'private'`          — RFC 1918 (`10/8`, `172.16/12`,
+ * - `'private'`          - RFC 1918 (`10/8`, `172.16/12`,
  *   `192.168/16`); RFC 6598 CGNAT (`100.64/10`); link-local
  *   (`169.254/16`, `fe80::/10`); `*.local` / `*.lan` / `*.internal` /
  *   `*.home.arpa`.
- * - `'public-tls'`       — public IP / hostname AND `https://`.
- * - `'public-cleartext'` — public IP / hostname AND `http://`. Adapters
+ * - `'public-tls'`       - public IP / hostname AND `https://`.
+ * - `'public-cleartext'` - public IP / hostname AND `http://`. Adapters
  *   refuse to start unless explicitly overridden.
  *
  * @stable

package/dist/contracts/logger.d.ts

@@ -18,7 +18,7 @@ type LogFields = Readonly<Record<string, unknown>>;
 /**
  * Pluggable logger contract consumed by every `@graphorin/*` runtime
  * package. The concrete implementation lives in `@graphorin/observability`
- * — declaring the interface here keeps level-zero packages free of an
+ * - declaring the interface here keeps level-zero packages free of an
  * observability dependency.
  *
  * Loggers are intentionally **structured** and **side-effect-free** in the

package/dist/contracts/logger.js.map

@@ -1 +1 @@
-{"version":3,"file":"logger.js","names":["NOOP_LOGGER: Logger"],"sources":["../../src/contracts/logger.ts"],"sourcesContent":["/**\n * Severity levels supported by the project logger. Mirrors the canonical\n * `trace < debug < info < warn < error` hierarchy used by every common\n * structured logger.\n *\n * @stable\n */\nexport type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error';\n\n/**\n * Free-form structured fields that accompany a log record. Values must be\n * JSON-serializable; concrete loggers redact `SecretValue` and other\n * sensitive shapes per the framework's redaction policy.\n *\n * @stable\n */\nexport type LogFields = Readonly<Record<string, unknown>>;\n\n/**\n * Pluggable logger contract consumed by every `@graphorin/*` runtime\n * package. The concrete implementation lives in `@graphorin/observability`\n * — declaring the interface here keeps level-zero packages free of an\n * observability dependency.\n *\n * Loggers are intentionally **structured** and **side-effect-free** in the\n * type contract: the `info(msg, fields?)` signature is a hint, not a\n * mandate to actually emit anything. Implementations may sample, drop, or\n * batch.\n *\n * @stable\n */\nexport interface Logger {\n  trace(message: string, fields?: LogFields): void;\n  debug(message: string, fields?: LogFields): void;\n  info(message: string, fields?: LogFields): void;\n  warn(message: string, fields?: LogFields): void;\n  error(message: string, fields?: LogFields): void;\n  /**\n   * Return a child logger with `fields` merged into every record's\n   * structured payload. Useful for binding `runId` / `sessionId` /\n   * `agentId` once at the top of a request.\n   */\n  child(fields: LogFields): Logger;\n}\n\n/**\n * Minimal no-op logger. Useful as a typed default when downstream code\n * needs a non-null `Logger` without taking the observability dependency.\n *\n * @stable\n */\nexport const NOOP_LOGGER: Logger = {\n  trace(): void {},\n  debug(): void {},\n  info(): void {},\n  warn(): void {},\n  error(): void {},\n  child(): Logger {\n    return NOOP_LOGGER;\n  },\n};\n"],"mappings":";;;;;;;AAmDA,MAAaA,cAAsB;CACjC,QAAc;CACd,QAAc;CACd,OAAa;CACb,OAAa;CACb,QAAc;CACd,QAAgB;AACd,SAAO;;CAEV"}
+{"version":3,"file":"logger.js","names":["NOOP_LOGGER: Logger"],"sources":["../../src/contracts/logger.ts"],"sourcesContent":["/**\n * Severity levels supported by the project logger. Mirrors the canonical\n * `trace < debug < info < warn < error` hierarchy used by every common\n * structured logger.\n *\n * @stable\n */\nexport type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error';\n\n/**\n * Free-form structured fields that accompany a log record. Values must be\n * JSON-serializable; concrete loggers redact `SecretValue` and other\n * sensitive shapes per the framework's redaction policy.\n *\n * @stable\n */\nexport type LogFields = Readonly<Record<string, unknown>>;\n\n/**\n * Pluggable logger contract consumed by every `@graphorin/*` runtime\n * package. The concrete implementation lives in `@graphorin/observability`\n * - declaring the interface here keeps level-zero packages free of an\n * observability dependency.\n *\n * Loggers are intentionally **structured** and **side-effect-free** in the\n * type contract: the `info(msg, fields?)` signature is a hint, not a\n * mandate to actually emit anything. Implementations may sample, drop, or\n * batch.\n *\n * @stable\n */\nexport interface Logger {\n  trace(message: string, fields?: LogFields): void;\n  debug(message: string, fields?: LogFields): void;\n  info(message: string, fields?: LogFields): void;\n  warn(message: string, fields?: LogFields): void;\n  error(message: string, fields?: LogFields): void;\n  /**\n   * Return a child logger with `fields` merged into every record's\n   * structured payload. Useful for binding `runId` / `sessionId` /\n   * `agentId` once at the top of a request.\n   */\n  child(fields: LogFields): Logger;\n}\n\n/**\n * Minimal no-op logger. Useful as a typed default when downstream code\n * needs a non-null `Logger` without taking the observability dependency.\n *\n * @stable\n */\nexport const NOOP_LOGGER: Logger = {\n  trace(): void {},\n  debug(): void {},\n  info(): void {},\n  warn(): void {},\n  error(): void {},\n  child(): Logger {\n    return NOOP_LOGGER;\n  },\n};\n"],"mappings":";;;;;;;AAmDA,MAAaA,cAAsB;CACjC,QAAc;CACd,QAAc;CACd,OAAa;CACb,OAAa;CACb,QAAc;CACd,QAAgB;AACd,SAAO;;CAEV"}

package/dist/contracts/memory-store.d.ts

@@ -11,7 +11,7 @@ import { SessionScope } from "../types/session-scope.js";
  *
  * Sub-namespaces map 1:1 to the six tiers so each implementation can
  * pick its own physical layout (one big table, six tables, mixed) while
- * preserving append-only semantics — soft-delete only.
+ * preserving append-only semantics - soft-delete only.
  *
  * @stable
  */

package/dist/contracts/memory-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memory-store.d.ts","names":[],"sources":["../../src/contracts/memory-store.ts"],"sourcesContent":[],"mappings":"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"}
+{"version":3,"file":"memory-store.d.ts","names":[],"sources":["../../src/contracts/memory-store.ts"],"sourcesContent":[],"mappings":";;;;;;;;AAuBA;;;;;;;;;AAWkB,UAXD,WAAA,CAWC;EAID,SAAA,OAAA,EAdG,kBAce;EACrB,SAAA,OAAA,EAdM,kBAcN;EAAqC,SAAA,QAAA,EAb9B,mBAa8B;EAAd,SAAA,QAAA,EAZhB,mBAYgB;EAAR,SAAA,UAAA,EAXN,qBAWM;EAChB,SAAA,MAAA,EAXM,iBAWN;EAAsC;EAAR,IAAA,EAAA,EARjC,OAQiC,CAAA,IAAA,CAAA;EAC3B;EAAqB,KAAA,EAAA,EAP1B,OAO0B,CAAA,IAAA,CAAA;;;AAC0B,UAJ9C,kBAAA,CAI8C;EAAO,IAAA,CAAA,KAAA,EAHxD,YAGwD,CAAA,EAHzC,OAGyC,CAHjC,aAGiC,CAHnB,KAGmB,CAAA,CAAA;EASrD,GAAA,CAAA,KAAA,EAXJ,YAWc,EAAA,KAAA,EAAA,MAAA,CAAA,EAXgB,OAWhB,CAXwB,KAWxB,GAAA,IAAA,CAAA;EAaV,MAAA,CAAA,KAAA,EAvBD,YAuBC,EAAA,KAA0B,EAvBN,KAuBM,CACvB,EAxByB,OAwBlB,CAAA,IAAA,CAAA;EAOV,MAAA,CAAA,KAAA,EA9BD,YA8BmB,EAAA,KAAA,EAAA,MAAA,EAAA,MAAA,CAAA,EAAA,MAAA,CAAA,EA9B4B,OA8B5B,CAAA,IAAA,CAAA;;;;;;;;AAE6B,UAvB/C,UAAA,CAuB+C;EAAR,SAAA,SAAA,EAAA,MAAA;EAM7C,SAAA,QAAA,EAAA,MAAA;EACA,SAAA,WAAA,EAAA,MAAA;;;;;;;;;AAMC,UAvBK,0BAAA,CAuBL;EAIK,SAAA,OAAA,EA1BG,OA0Be;EAQlB,SAAA,SAAA,EAAA,MAAmB;EACrB,SAAA,QAAA,EAAA,MAAA;EAAU,SAAA,SAAA,EAAA,MAAA;;;AAIY,UAhCpB,kBAAA,CAgCoB;EAAV,IAAA,CAAA,KAAA,EA/Bb,YA+Ba,EAAA,OAAA,EA/BU,OA+BV,CAAA,EA/BoB,OA+BpB,CA/B4B,UA+B5B,CAAA;EAAd,IAAA,CAAA,KAAA,EA9BC,YA8BD,EAAA,IAAA,CAAA,EA9BsB,kBA8BtB,CAAA,EA9B2C,OA8B3C,CA9BmD,aA8BnD,CA9BiE,OA8BjE,CAAA,CAAA;EAAR;;;;EAKY,gBAAA,EAAA,KAAmB,EA7BzB,YA6ByB,EAAA,IAAA,CAAA,EA5BzB,kBA4ByB,CAAA,EA3B/B,OA2B+B,CA3BvB,aA2BuB,CA3BT,0BA2BS,CAAA,CAAA;EACnB,MAAA,CAAA,KAAA,EA1BN,YA0BM,EAAA,KAAA,EAAA,MAAA,EAAA,IAAA,CAAA,EAxBN,mBAwBM,CAAA,EAvBZ,OAuBY,CAvBJ,aAuBI,CAvBU,SAuBV,CAAA,CAAA;;;AACmB,UApBnB,kBAAA,CAoBmB;EAAsD,SAAA,KAAA,CAAA,EAAA,MAAA;EAAV,SAAA,cAAA,CAAA,EAAA,MAAA;EAAd,SAAA,OAAA,CAAA,EAAA,MAAA;EAAR,SAAA,IAAA,CAAA,EAAA,QAAA,GAAA,MAAA,GAAA,WAAA,GAAA,MAAA;;;AAEnB,UAdtB,mBAAA,CAcsB;EAAO,GAAA,CAAA,OAAA,EAb/B,OAa+B,CAAA,EAbrB,OAaqB,CAAA,IAAA,CAAA;EAI7B,MAAA,CAAA,KAAA,EAfN,YAe2B,EAAA,IAAA,EAd5B,mBAc4B,CAAA,EAbjC,OAaiC,CAbzB,aAayB,CAbX,SAaW,CAbD,OAaC,CAAA,CAAA,CAAA;EAC1B,GAAA,CAAA,EAAA,EAAA,MAAA,CAAA,EAbO,OAaP,CAbe,OAaf,GAAA,IAAA,CAAA;;;AACuC,UAVlC,mBAAA,CAUkC;EAAd,QAAA,CAAA,IAAA,EATpB,IASoB,CAAA,EATb,OASa,CAAA,IAAA,CAAA;EAAR,MAAA,CAAA,KAAA,EARb,YAQa,EAAA,IAAA,EARO,mBAQP,CAAA,EAR6B,OAQ7B,CARqC,aAQrC,CARmD,SAQnD,CAR6D,IAQ7D,CAAA,CAAA,CAAA;EACU,SAAA,CAAA,KAAA,EAAA,MAAA,EAAA,OAAA,EARH,IAQG,EAAA,MAAA,CAAA,EAAA,MAAA,CAAA,EARqB,OAQrB,CAAA,IAAA,CAAA;EAAO,MAAA,CAAA,EAAA,EAAA,MAAA,EAAA,MAAA,CAAA,EAAA,MAAA,CAAA,EAPP,OAOO,CAAA,IAAA,CAAA;AAI9C;;AAE6C,UAT5B,qBAAA,CAS4B;EACK,GAAA,CAAA,IAAA,EATtC,IASsC,CAAA,EAT/B,OAS+B,CAAA,IAAA,CAAA;EAAd,IAAA,CAAA,KAAA,EARtB,YAQsB,CAAA,EARP,OAQO,CARC,aAQD,CARe,IAQf,CAAA,CAAA;EAAR,MAAA,CAAA,EAAA,EAAA,MAAA,EAAA,MAAA,CAAA,EAAA,MAAA,CAAA,EAPW,OAOX,CAAA,IAAA,CAAA;;;UAHX,iBAAA;6CAC4B;6CACA;4BACjB,QAAQ,cAAc"}

package/dist/contracts/oauth-server-store.d.ts

@@ -1,7 +1,7 @@
 //#region src/contracts/oauth-server-store.d.ts
 /**
  * Persisted metadata for an OAuth server registration. The framework
- * never stores raw token material here — the access, refresh, id, and
+ * never stores raw token material here - the access, refresh, id, and
  * client-secret tokens live in the {@link SecretsStore} and this
  * record only holds the {@link SecretRef} URIs that resolve them.
  *

package/dist/contracts/preferred-model.d.ts

@@ -8,14 +8,14 @@
  * The three tiers describe canonical cloud-provider price-quality
  * envelopes circa 2026:
  *
- * - `'fast'`     — low-cost / low-latency / file-navigation /
+ * - `'fast'`     - low-cost / low-latency / file-navigation /
  *   parameter-extraction / low-stakes calls.
- * - `'balanced'` — median cost-quality; the default tier for most
+ * - `'balanced'` - median cost-quality; the default tier for most
  *   tools.
- * - `'smart'`    — high-quality / high-stakes / reasoning-heavy /
+ * - `'smart'`    - high-quality / high-stakes / reasoning-heavy /
  *   summarization / code-review calls.
  *
- * The vocabulary is Graphorin's own design — no third-party routing-
+ * The vocabulary is Graphorin's own design - no third-party routing-
  * guide attribution leaks into the public surface. Per-provider
  * dispatch lives in `@graphorin/provider/model-tier/classify.ts`.
  *

package/dist/contracts/preferred-model.js.map

@@ -1 +1 @@
-{"version":3,"file":"preferred-model.js","names":["MODEL_HINTS: readonly ModelHint[]"],"sources":["../../src/contracts/preferred-model.ts"],"sourcesContent":["/**\n * Cost-tier vocabulary for declaring a preferred model on a tool or\n * agent. Provider-agnostic at the tool-author level; the operator-side\n * `Agent.modelTierMap?: Partial<Record<ModelHint, ModelSpec>>` mapping\n * resolves the hint to a concrete provider per agent.\n *\n * The three tiers describe canonical cloud-provider price-quality\n * envelopes circa 2026:\n *\n * - `'fast'`     — low-cost / low-latency / file-navigation /\n *   parameter-extraction / low-stakes calls.\n * - `'balanced'` — median cost-quality; the default tier for most\n *   tools.\n * - `'smart'`    — high-quality / high-stakes / reasoning-heavy /\n *   summarization / code-review calls.\n *\n * The vocabulary is Graphorin's own design — no third-party routing-\n * guide attribution leaks into the public surface. Per-provider\n * dispatch lives in `@graphorin/provider/model-tier/classify.ts`.\n *\n * @stable\n */\nexport type ModelHint = 'fast' | 'balanced' | 'smart';\n\n/**\n * Discriminated string-literal triple for type-level work.\n *\n * @stable\n */\nexport const MODEL_HINTS: readonly ModelHint[] = ['fast', 'balanced', 'smart'] as const;\n\n/**\n * Forward-declared shape of `Provider`. Re-declared here as a minimal\n * structural type so this module stays cycle-free with respect to\n * `./provider.ts` and downstream consumers can use `ModelSpec` without\n * importing the heavier `Provider` interface.\n *\n * @internal\n */\nexport interface ProviderLike {\n  readonly name: string;\n  readonly modelId: string;\n}\n\n/**\n * Concrete provider declaration used at site of the per-tool hint\n * override (Phase 07), the per-tier mapping\n * (`Agent.modelTierMap`, Phase 12), and the agent-level fallback chain\n * (`Agent.fallbackModels`, Phase 12).\n *\n * The shape is unified deliberately so operators learn one thing and\n * use it three places.\n *\n * @stable\n */\nexport type ModelSpec = ProviderLike | { readonly provider: ProviderLike; readonly model: string };\n"],"mappings":";;;;;;AA6BA,MAAaA,cAAoC;CAAC;CAAQ;CAAY;CAAQ"}
+{"version":3,"file":"preferred-model.js","names":["MODEL_HINTS: readonly ModelHint[]"],"sources":["../../src/contracts/preferred-model.ts"],"sourcesContent":["/**\n * Cost-tier vocabulary for declaring a preferred model on a tool or\n * agent. Provider-agnostic at the tool-author level; the operator-side\n * `Agent.modelTierMap?: Partial<Record<ModelHint, ModelSpec>>` mapping\n * resolves the hint to a concrete provider per agent.\n *\n * The three tiers describe canonical cloud-provider price-quality\n * envelopes circa 2026:\n *\n * - `'fast'`     - low-cost / low-latency / file-navigation /\n *   parameter-extraction / low-stakes calls.\n * - `'balanced'` - median cost-quality; the default tier for most\n *   tools.\n * - `'smart'`    - high-quality / high-stakes / reasoning-heavy /\n *   summarization / code-review calls.\n *\n * The vocabulary is Graphorin's own design - no third-party routing-\n * guide attribution leaks into the public surface. Per-provider\n * dispatch lives in `@graphorin/provider/model-tier/classify.ts`.\n *\n * @stable\n */\nexport type ModelHint = 'fast' | 'balanced' | 'smart';\n\n/**\n * Discriminated string-literal triple for type-level work.\n *\n * @stable\n */\nexport const MODEL_HINTS: readonly ModelHint[] = ['fast', 'balanced', 'smart'] as const;\n\n/**\n * Forward-declared shape of `Provider`. Re-declared here as a minimal\n * structural type so this module stays cycle-free with respect to\n * `./provider.ts` and downstream consumers can use `ModelSpec` without\n * importing the heavier `Provider` interface.\n *\n * @internal\n */\nexport interface ProviderLike {\n  readonly name: string;\n  readonly modelId: string;\n}\n\n/**\n * Concrete provider declaration used at site of the per-tool hint\n * override (Phase 07), the per-tier mapping\n * (`Agent.modelTierMap`, Phase 12), and the agent-level fallback chain\n * (`Agent.fallbackModels`, Phase 12).\n *\n * The shape is unified deliberately so operators learn one thing and\n * use it three places.\n *\n * @stable\n */\nexport type ModelSpec = ProviderLike | { readonly provider: ProviderLike; readonly model: string };\n"],"mappings":";;;;;;AA6BA,MAAaA,cAAoC;CAAC;CAAQ;CAAY;CAAQ"}

package/dist/contracts/provider.d.ts

@@ -1,5 +1,6 @@
 import { Sensitivity } from "../types/sensitivity.js";
 import { Message } from "../types/message.js";
+import { AISpan } from "./tracer.js";
 import { Usage } from "../types/usage.js";
 import { ReasoningContract, ReasoningRetention } from "./reasoning-retention.js";
 
@@ -61,6 +62,23 @@ interface ProviderCapabilities {
    */
   readonly reasoningContract?: ReasoningContract;
 }
+/**
+ * Opt-in prompt-cache breakpoint policy (core-provider-02).
+ *
+ * `breakpoints: 'auto'` asks the adapter to place provider-native cache
+ * anchors around the stable request prefix: the Anthropic path (via the
+ * vercel adapter) marks the first and last conversation messages with
+ * `cache_control: { type: 'ephemeral' }` so tools + system + the stable
+ * prefix are written once and read at ~0.1x input price on subsequent
+ * steps. Providers with automatic caching (OpenAI) or no cache concept
+ * ignore the policy. `ttl` maps to Anthropic's extended cache TTL.
+ *
+ * @stable
+ */
+interface ProviderCachePolicy {
+  readonly breakpoints: 'auto' | 'none';
+  readonly ttl?: '5m' | '1h';
+}
 /**
  * Provider-call request payload.
  *
@@ -76,6 +94,14 @@ interface ProviderRequest {
   readonly maxTokens?: number;
   readonly signal?: AbortSignal;
   readonly providerOptions?: Readonly<Record<string, unknown>>;
+  readonly cachePolicy?: ProviderCachePolicy;
+  /**
+   * C7: live parent span for the provider call. Like `signal`, this is a
+   * runtime handle (never serialized): `withTracing` parents its
+   * provider.generate/stream span under it so a run's traces form one
+   * tree instead of disconnected fragments.
+   */
+  readonly parentSpan?: AISpan;
   readonly metadata?: ProviderRequestMetadata;
   /**
    * Per-request override of the provider's auto-detected
@@ -123,7 +149,7 @@ interface ProviderResponse {
 type FinishReason = 'stop' | 'length' | 'tool-calls' | 'content-filter' | 'error' | 'aborted';
 /**
  * Streamed provider event. Shape matches the wire-stable subset of the
- * provider event union — adapters hide vendor specifics.
+ * provider event union - adapters hide vendor specifics.
  *
  * @stable
  */
@@ -214,7 +240,7 @@ interface ToolDefinition {
   readonly examples?: ReadonlyArray<ToolDefinitionExample>;
 }
 /**
- * A single worked example as projected onto the provider wire contract —
+ * A single worked example as projected onto the provider wire contract -
  * a serializable, schema-agnostic view of a `ToolExample`. `input` /
  * `output` carry the example's already-parsed values; `comment` is the
  * optional rationale shown to the model.
@@ -259,8 +285,8 @@ type ProviderMiddleware = (next: Provider) => Provider;
  * Type signature for the canonical middleware composer (the runtime
  * implementation lives in `@graphorin/provider`).
  *
- * The concrete composer guarantees a deterministic ordering — order of
- * arguments mirrors order of execution from outermost to innermost — and
+ * The concrete composer guarantees a deterministic ordering - order of
+ * arguments mirrors order of execution from outermost to innermost - and
  * is the only blessed entry point for chaining middleware in
  * `@graphorin/*` code (per the security-first ordering rule).
  *
@@ -268,5 +294,5 @@ type ProviderMiddleware = (next: Provider) => Provider;
  */
 type ComposeProviderMiddleware = (middlewares: ReadonlyArray<ProviderMiddleware>) => ProviderMiddleware;
 //#endregion
-export { ComposeProviderMiddleware, FinishReason, OutputSpec, Provider, ProviderCapabilities, ProviderError, ProviderErrorKind, ProviderEvent, ProviderMiddleware, ProviderRequest, ProviderRequestMetadata, ProviderResponse, ResponseMetadata, ToolChoice, ToolDefinition, ToolDefinitionExample };
+export { ComposeProviderMiddleware, FinishReason, OutputSpec, Provider, ProviderCachePolicy, ProviderCapabilities, ProviderError, ProviderErrorKind, ProviderEvent, ProviderMiddleware, ProviderRequest, ProviderRequestMetadata, ProviderResponse, ResponseMetadata, ToolChoice, ToolDefinition, ToolDefinitionExample };
 //# sourceMappingURL=provider.d.ts.map

package/dist/contracts/provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider.d.ts","names":[],"sources":["../../src/contracts/provider.ts"],"sourcesContent":[],"mappings":";;;;;;;;;AAgBA;;;;;;;;;AAYsC,UAZrB,QAAA,CAYqB;EAOQ,SAAA,IAAA,EAAA,MAAA;EAAd,SAAA,OAAA,EAAA,MAAA;EAAa,SAAA,YAAA,EAhBpB,oBAgBoB;EAQ5B;EA6BA,MAAA,CAAA,GAAA,EAlDH,eAkDkB,CAAA,EAlDA,aAkDA,CAlDc,aAkDd,CAAA;EACG;EAAd,QAAA,CAAA,GAAA,EAhDL,eAgDK,CAAA,EAhDa,OAgDb,CAhDqB,gBAgDrB,CAAA;EACY;EAAd,WAAA,EAAA,GAAA,EA9CC,eA8CD,CAAA,EA9CmB,OA8CnB,CAAA,MAAA,CAAA;EACK;;;;;EAOF,SAAA,kBAAA,CAAA,EA/CU,aA+CV,CA/CwB,WA+CxB,CAAA;;;AAiBtB;AAaA;;;AAQyB,UA7ER,oBAAA,CA6EQ;EACc,SAAA,SAAA,EAAA,OAAA;EAAT,SAAA,WAAA,EAAA,OAAA;EAAQ,SAAA,iBAAA,EAAA,OAAA;EAQ1B,SAAA,UAAY,EAAA,OAAA;EAcZ,SAAA,gBAAa,EAAA,OAAA;EAC+B,SAAA,SAAA,EAAA,OAAA;EAUe;EAEjB,SAAA,aAAA,EAAA,MAAA;EAA8B;EACtC,SAAA,SAAA,EAAA,MAAA;EAAa;AAO3D;AAYA;AAOA;AAgBA;;;;;;EAkBsB,SAAA,iBAAA,CAAA,EAzJS,iBAyJT;;AAWtB;AAWA;AAQA;AAeA;AAaA;AAC6B,UA5MZ,eAAA,CA4MY;EAAd,SAAA,QAAA,EA3MM,aA2MN,CA3MoB,OA2MpB,CAAA;EACV,SAAA,KAAA,CAAA,EA3Mc,aA2Md,CA3M4B,cA2M5B,CAAA;EAAkB,SAAA,UAAA,CAAA,EA1MC,UA0MD;wBAzMC;;;;oBAIJ;6BACS,SAAS;sBAChB;;;;;;;;;gCASU;;;;;;;UAQf,uBAAA;;;;;;;;;;;;UAaA,gBAAA;;uBAEM;;;;;kBAKL;yBACO;8BACK,SAAS;;;;;;;KAQ3B,YAAA;;;;;;;KAcA,aAAA;;qBAC4C;;;;;;;;;;;;;;;;;;;;;;iBAUe;;;;;;;yBAEjB;kBAA8B;;;kBACtC;;;;;;;UAO7B,gBAAA;;;;;;;;;;;UAYA,aAAA;iBACA;;;;;KAML,iBAAA;;;;;;;UAgBK,cAAA;;;wBAGO,SAAS;;;;;;;0BAOP,SAAS;;;;;;;;sBAQb,cAAc;;;;;;;;;;UAWnB,qBAAA;;;;;;;;;;KAWL,UAAA;;;;;;;;;UAQK,UAAA;;;wBAGO,SAAS;;;;;;;;;;;KAYrB,kBAAA,UAA4B,aAAa;;;;;;;;;;;;KAazC,yBAAA,iBACG,cAAc,wBACxB"}
+{"version":3,"file":"provider.d.ts","names":[],"sources":["../../src/contracts/provider.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;AAgBA;;;;;;;;AAYoB,UAZH,QAAA,CAYG;EAAkB,SAAA,IAAA,EAAA,MAAA;EAOQ,SAAA,OAAA,EAAA,MAAA;EAAd,SAAA,YAAA,EAhBP,oBAgBO;EAAa;EAQ5B,MAAA,CAAA,GAAA,EArBH,eAqBuB,CAAA,EArBL,aA0CD,CA1Ce,aA0CE,CAAA;EAgB/B;EAUA,QAAA,CAAA,GAAA,EAjED,eAiEgB,CAAA,EAjEE,OAiEF,CAjEU,gBAiEV,CAAA;EACG;EAAd,WAAA,EAAA,GAAA,EA/DD,eA+DC,CAAA,EA/DiB,OA+DjB,CAAA,MAAA,CAAA;EACY;;;;;EAOK,SAAA,kBAAA,CAAA,EAhEN,aAgEM,CAhEQ,WAgER,CAAA;;;;;;;AA0BrB,UAlFA,oBAAA,CAkFuB;EAavB,SAAA,SAAA,EAAgB,OAAA;EAEV,SAAA,WAAA,EAAA,OAAA;EAKL,SAAA,iBAAA,EAAA,OAAA;EACO,SAAA,UAAA,EAAA,OAAA;EACc,SAAA,gBAAA,EAAA,OAAA;EAAT,SAAA,SAAA,EAAA,OAAA;EAAQ;EAQ1B,SAAA,aAAY,EAAA,MAAA;EAcZ;EAC4C,SAAA,SAAA,EAAA,MAAA;EAUe;;;;;AAUvE;AAYA;AAOA;AAgBA;;EAGwB,SAAA,iBAAA,CAAA,EApKO,iBAoKP;;;;;;AA0BxB;AAWA;AAQA;AAeA;AAaA;;;;;UA7NiB,mBAAA;;;;;;;;;UAUA,eAAA;qBACI,cAAc;mBAChB,cAAc;wBACT;wBACA;;;;oBAIJ;6BACS,SAAS;yBACb;;;;;;;wBAAmB;sBAQtB;;;;;;;;;gCASU;;;;;;;UAQf,uBAAA;;;;;;;;;;;;UAaA,gBAAA;;uBAEM;;;;;kBAKL;yBACO;8BACK,SAAS;;;;;;;KAQ3B,YAAA;;;;;;;KAcA,aAAA;;qBAC4C;;;;;;;;;;;;;;;;;;;;;;iBAUe;;;;;;;yBAEjB;kBAA8B;;;kBACtC;;;;;;;UAO7B,gBAAA;;;;;;;;;;;UAYA,aAAA;iBACA;;;;;KAML,iBAAA;;;;;;;UAgBK,cAAA;;;wBAGO,SAAS;;;;;;;0BAOP,SAAS;;;;;;;;sBAQb,cAAc;;;;;;;;;;UAWnB,qBAAA;;;;;;;;;;KAWL,UAAA;;;;;;;;;UAQK,UAAA;;;wBAGO,SAAS;;;;;;;;;;;KAYrB,kBAAA,UAA4B,aAAa;;;;;;;;;;;;KAazC,yBAAA,iBACG,cAAc,wBACxB"}

package/dist/contracts/reasoning-retention.d.ts

@@ -7,16 +7,16 @@
  * Three independent lifecycle operations exist for reasoning content
  * in the provider layer:
  *
- * 1. **Intra-loop transmission** — controlled by this enum. Default is
+ * 1. **Intra-loop transmission** - controlled by this enum. Default is
  *    auto-detected per provider:
  *    - Hidden chain-of-thought providers (e.g. OpenAI o1/o3, Google
  *      Gemini reasoning): `'strip'`.
  *    - Round-trip-required providers (e.g. Anthropic Claude tool-use
  *      with thinking blocks): `'pass-through-claude'`.
- * 2. **Sub-agent handoff transmission** — always strips reasoning
+ * 2. **Sub-agent handoff transmission** - always strips reasoning
  *    regardless of this setting; lives in
  *    `@graphorin/sessions` handoff filters.
- * 3. **Prompt-cache key calculation** — reasoning blocks are excluded
+ * 3. **Prompt-cache key calculation** - reasoning blocks are excluded
  *    from cache-key hashes but included in outbound transmission.
  *
  * @stable

package/dist/contracts/redaction-validator.d.ts

@@ -42,7 +42,7 @@ interface RedactionInput {
   };
 }
 /**
- * Result of `RedactionValidator.validate(...)` — either the sanitized
+ * Result of `RedactionValidator.validate(...)` - either the sanitized
  * payload (possibly equal to the input) or `null` if the value must be
  * dropped entirely.
  *

package/dist/contracts/sandbox.d.ts

@@ -50,7 +50,7 @@ interface SandboxRunOptions<TInput = unknown> {
   readonly signal?: AbortSignal;
 }
 /**
- * Result of a sandboxed run. The shape mirrors the `ToolOutcome` union —
+ * Result of a sandboxed run. The shape mirrors the `ToolOutcome` union -
  * the runtime maps `SandboxResult` to `ToolOutcome` after the call.
  *
  * @stable

package/dist/contracts/secret-value.d.ts

@@ -26,7 +26,7 @@ declare const NODEJS_INSPECT_CUSTOM: unique symbol;
  * a parameter as `SecretValue` therefore avoid taking a security
  * dependency.
  *
- * Note: `SecretValue` is **not** a TypeScript branded primitive — it is
+ * Note: `SecretValue` is **not** a TypeScript branded primitive - it is
  * a full wrapper class with explicit leakage barriers
  * (`Symbol.toPrimitive`, `toJSON`, `[nodejs.util.inspect.custom]`, …).
  * Any conforming implementation must ensure that:

package/dist/contracts/secret-value.js.map

@@ -1 +1 @@
-{"version":3,"file":"secret-value.js","names":["SECRET_VALUE_BRAND: unique symbol","NODEJS_INSPECT_CUSTOM: unique symbol"],"sources":["../../src/contracts/secret-value.ts"],"sourcesContent":["/**\n * Cross-realm symbol used to brand `SecretValue` instances. Implementations\n * (e.g. the wrapper class shipped from `@graphorin/security`) attach this\n * symbol so that `isSecretValue(...)` works across realms (Worker threads,\n * sandboxes, etc.).\n *\n * @stable\n */\nexport const SECRET_VALUE_BRAND: unique symbol = Symbol.for('graphorin.SecretValue');\n\n/**\n * Well-known symbol used by `node:util.inspect()` to format the wrapper.\n * Re-exported here so downstream packages can reference it without taking\n * an unconditional dependency on `node:util`.\n *\n * Equivalent to `Symbol.for('nodejs.util.inspect.custom')`.\n *\n * @stable\n */\nexport const NODEJS_INSPECT_CUSTOM: unique symbol = Symbol.for('nodejs.util.inspect.custom');\n\n/**\n * Runtime-safe wrapper around an opaque secret (API key, token, password).\n *\n * The shape declared here is the **interface contract**: the concrete\n * wrapper class lives in `@graphorin/security`. Downstream packages typing\n * a parameter as `SecretValue` therefore avoid taking a security\n * dependency.\n *\n * Note: `SecretValue` is **not** a TypeScript branded primitive — it is\n * a full wrapper class with explicit leakage barriers\n * (`Symbol.toPrimitive`, `toJSON`, `[nodejs.util.inspect.custom]`, …).\n * Any conforming implementation must ensure that:\n *\n * - String coercion (`String(s)`, `` `${s}` ``, `s + ''`, …) yields a\n *   redacted placeholder, **not** the underlying value.\n * - JSON serialization (`JSON.stringify({ apiKey: s })`) yields a\n *   redacted placeholder.\n * - Inspector output (`util.inspect(s)`) yields\n *   `'SecretValue([REDACTED])'`.\n * - The underlying value is only reachable through `.use(fn)`,\n *   `.useBuffer(fn)` or the audited `.reveal()` escape hatch.\n *\n * @stable\n */\nexport interface SecretValue {\n  /** Number of bytes in the wrapped value. Safe to log. */\n  readonly length: number;\n\n  /**\n   * Run `fn` with the unwrapped string and return its result. Preferred\n   * over `.reveal()` because it scopes the unwrapped value to a single\n   * synchronous / asynchronous turn.\n   */\n  use<T>(fn: (raw: string) => T | Promise<T>): Promise<T>;\n\n  /**\n   * Run `fn` with the unwrapped value as a `Buffer`. Useful for binary\n   * secrets (encryption keys, HMAC keys) where round-tripping through a\n   * V8 string would defeat the wrapper's hygiene.\n   */\n  useBuffer<T>(fn: (buf: Buffer) => T | Promise<T>): Promise<T>;\n\n  /**\n   * One-shot reveal as a string. Audited by the implementation. Prefer\n   * `.use(fn)` whenever possible.\n   */\n  reveal(): string;\n\n  /**\n   * Best-effort zeroization of the underlying buffer. Does not affect\n   * derived V8 strings already created via `.use(fn)` / `.reveal()`.\n   */\n  dispose(): void;\n\n  /** Cross-realm brand. Implementations set this to `SECRET_VALUE_BRAND`. */\n  readonly [SECRET_VALUE_BRAND]: true;\n\n  /** Leakage barrier for ToPrimitive coercion. Returns the placeholder. */\n  [Symbol.toPrimitive](hint: string): string | number;\n\n  /** Leakage barrier for `JSON.stringify(...)`. Returns the placeholder. */\n  toJSON(): string;\n\n  /**\n   * Leakage barrier for `node:util.inspect(...)`. Returns the placeholder\n   * (`'SecretValue([REDACTED])'`) so that REPL / `console.log` /\n   * structured-logger output never reveals the underlying value.\n   */\n  [NODEJS_INSPECT_CUSTOM](depth?: number, opts?: unknown, inspect?: unknown): string;\n}\n\n/**\n * Static helpers expected on every concrete `SecretValue` constructor.\n *\n * @stable\n */\nexport interface SecretValueStatic {\n  /** Cross-realm safe type guard. */\n  isSecretValue(value: unknown): value is SecretValue;\n  /** Constant-time equality. */\n  timingSafeEquals(a: SecretValue, b: SecretValue): boolean;\n  /** Construct from a plain string. */\n  fromString(raw: string, opts?: SecretValueOptions): SecretValue;\n  /** Construct from a Node.js `Buffer`. */\n  fromBuffer(buf: Buffer, opts?: SecretValueOptions): SecretValue;\n}\n\n/**\n * Optional metadata attached to a freshly constructed `SecretValue`.\n *\n * @stable\n */\nexport interface SecretValueOptions {\n  /** Free-form provenance string for the audit log. */\n  readonly source?: { readonly resolver?: string; readonly ref?: string };\n}\n"],"mappings":";;;;;;;;;AAQA,MAAaA,qBAAoC,OAAO,IAAI,wBAAwB;;;;;;;;;;AAWpF,MAAaC,wBAAuC,OAAO,IAAI,6BAA6B"}
+{"version":3,"file":"secret-value.js","names":["SECRET_VALUE_BRAND: unique symbol","NODEJS_INSPECT_CUSTOM: unique symbol"],"sources":["../../src/contracts/secret-value.ts"],"sourcesContent":["/**\n * Cross-realm symbol used to brand `SecretValue` instances. Implementations\n * (e.g. the wrapper class shipped from `@graphorin/security`) attach this\n * symbol so that `isSecretValue(...)` works across realms (Worker threads,\n * sandboxes, etc.).\n *\n * @stable\n */\nexport const SECRET_VALUE_BRAND: unique symbol = Symbol.for('graphorin.SecretValue');\n\n/**\n * Well-known symbol used by `node:util.inspect()` to format the wrapper.\n * Re-exported here so downstream packages can reference it without taking\n * an unconditional dependency on `node:util`.\n *\n * Equivalent to `Symbol.for('nodejs.util.inspect.custom')`.\n *\n * @stable\n */\nexport const NODEJS_INSPECT_CUSTOM: unique symbol = Symbol.for('nodejs.util.inspect.custom');\n\n/**\n * Runtime-safe wrapper around an opaque secret (API key, token, password).\n *\n * The shape declared here is the **interface contract**: the concrete\n * wrapper class lives in `@graphorin/security`. Downstream packages typing\n * a parameter as `SecretValue` therefore avoid taking a security\n * dependency.\n *\n * Note: `SecretValue` is **not** a TypeScript branded primitive - it is\n * a full wrapper class with explicit leakage barriers\n * (`Symbol.toPrimitive`, `toJSON`, `[nodejs.util.inspect.custom]`, …).\n * Any conforming implementation must ensure that:\n *\n * - String coercion (`String(s)`, `` `${s}` ``, `s + ''`, …) yields a\n *   redacted placeholder, **not** the underlying value.\n * - JSON serialization (`JSON.stringify({ apiKey: s })`) yields a\n *   redacted placeholder.\n * - Inspector output (`util.inspect(s)`) yields\n *   `'SecretValue([REDACTED])'`.\n * - The underlying value is only reachable through `.use(fn)`,\n *   `.useBuffer(fn)` or the audited `.reveal()` escape hatch.\n *\n * @stable\n */\nexport interface SecretValue {\n  /** Number of bytes in the wrapped value. Safe to log. */\n  readonly length: number;\n\n  /**\n   * Run `fn` with the unwrapped string and return its result. Preferred\n   * over `.reveal()` because it scopes the unwrapped value to a single\n   * synchronous / asynchronous turn.\n   */\n  use<T>(fn: (raw: string) => T | Promise<T>): Promise<T>;\n\n  /**\n   * Run `fn` with the unwrapped value as a `Buffer`. Useful for binary\n   * secrets (encryption keys, HMAC keys) where round-tripping through a\n   * V8 string would defeat the wrapper's hygiene.\n   */\n  useBuffer<T>(fn: (buf: Buffer) => T | Promise<T>): Promise<T>;\n\n  /**\n   * One-shot reveal as a string. Audited by the implementation. Prefer\n   * `.use(fn)` whenever possible.\n   */\n  reveal(): string;\n\n  /**\n   * Best-effort zeroization of the underlying buffer. Does not affect\n   * derived V8 strings already created via `.use(fn)` / `.reveal()`.\n   */\n  dispose(): void;\n\n  /** Cross-realm brand. Implementations set this to `SECRET_VALUE_BRAND`. */\n  readonly [SECRET_VALUE_BRAND]: true;\n\n  /** Leakage barrier for ToPrimitive coercion. Returns the placeholder. */\n  [Symbol.toPrimitive](hint: string): string | number;\n\n  /** Leakage barrier for `JSON.stringify(...)`. Returns the placeholder. */\n  toJSON(): string;\n\n  /**\n   * Leakage barrier for `node:util.inspect(...)`. Returns the placeholder\n   * (`'SecretValue([REDACTED])'`) so that REPL / `console.log` /\n   * structured-logger output never reveals the underlying value.\n   */\n  [NODEJS_INSPECT_CUSTOM](depth?: number, opts?: unknown, inspect?: unknown): string;\n}\n\n/**\n * Static helpers expected on every concrete `SecretValue` constructor.\n *\n * @stable\n */\nexport interface SecretValueStatic {\n  /** Cross-realm safe type guard. */\n  isSecretValue(value: unknown): value is SecretValue;\n  /** Constant-time equality. */\n  timingSafeEquals(a: SecretValue, b: SecretValue): boolean;\n  /** Construct from a plain string. */\n  fromString(raw: string, opts?: SecretValueOptions): SecretValue;\n  /** Construct from a Node.js `Buffer`. */\n  fromBuffer(buf: Buffer, opts?: SecretValueOptions): SecretValue;\n}\n\n/**\n * Optional metadata attached to a freshly constructed `SecretValue`.\n *\n * @stable\n */\nexport interface SecretValueOptions {\n  /** Free-form provenance string for the audit log. */\n  readonly source?: { readonly resolver?: string; readonly ref?: string };\n}\n"],"mappings":";;;;;;;;;AAQA,MAAaA,qBAAoC,OAAO,IAAI,wBAAwB;;;;;;;;;;AAWpF,MAAaC,wBAAuC,OAAO,IAAI,6BAA6B"}

package/dist/contracts/secrets-store.d.ts

@@ -5,7 +5,7 @@ import { SecretValue } from "./secret-value.js";
 //#region src/contracts/secrets-store.d.ts
 
 /**
- * Pluggable secret resolver — turns a parsed `SecretRef` into a live
+ * Pluggable secret resolver - turns a parsed `SecretRef` into a live
  * `SecretValue`. Concrete resolvers live in `@graphorin/security` (env,
  * keyring, file, encrypted-file, literal, ref, vault) and in optional
  * adapter packages (`@graphorin/secret-1password`, …).
@@ -55,7 +55,7 @@ interface SecretsStore {
    */
   set(key: string, value: string | SecretValue, opts?: SecretsSetOptions): Promise<void>;
   delete(key: string, scope?: SessionScope): Promise<void>;
-  /** Returns metadata about every key — never the values themselves. */
+  /** Returns metadata about every key - never the values themselves. */
   list(scope?: SessionScope): Promise<ReadonlyArray<SecretMetadata>>;
 }
 /**
@@ -69,7 +69,7 @@ interface SecretsSetOptions {
   readonly tags?: ReadonlyArray<string>;
 }
 /**
- * Public metadata about a stored secret. Safe to log — never carries the
+ * Public metadata about a stored secret. Safe to log - never carries the
  * value itself.
  *
  * @stable