@graphorin/core 0.5.0

package/dist/channels/pause.js

@@ -0,0 +1,90 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+//#region src/channels/pause.ts
+/**
+* Brand attached to the signal thrown by `pause(value)` so that the
+* workflow runtime can recognise it across realms (Worker threads,
+* sandboxes, …) without `instanceof`.
+*
+* @stable
+*/
+const PAUSE_SIGNAL_BRAND = Symbol.for("graphorin.PauseSignal");
+/**
+* Thrown by `pause(value)` from inside a workflow node. The runtime
+* catches it, persists state with a pending pause, and suspends the
+* thread until `Workflow.resume(threadId, directive)` is called.
+*
+* Application code should never construct or catch this directly —
+* always go through `pause(...)`.
+*
+* @stable
+*/
+var PauseSignal = class extends Error {
+	[PAUSE_SIGNAL_BRAND] = true;
+	value;
+	constructor(value) {
+		super("graphorin: workflow paused");
+		this.name = "PauseSignal";
+		this.value = value;
+	}
+};
+const pauseResumeStorage = new AsyncLocalStorage();
+/**
+* Run `fn` inside a scope where successive `pause(...)` calls return the
+* supplied `values` in order instead of throwing a fresh
+* {@link PauseSignal} (WF-2: a node body re-executes from the top on
+* every resume, so earlier pauses must replay their already-delivered
+* values and only the FIRST unsatisfied `pause()` suspends again). An
+* empty `values` array behaves exactly like no scope — every `pause()`
+* suspends — which is what a static-gate resume needs so a programmatic
+* `pause()` inside the node is never silently satisfied.
+*
+* This helper is the contract between the runtime and `pause(...)`.
+* Consumers of `pause(...)` never call it directly — only the workflow
+* engine wires it up around the resumed node body.
+*
+* @internal
+*/
+function runWithPauseResume(values, fn) {
+	const scope = {
+		values,
+		cursor: 0
+	};
+	return pauseResumeStorage.run(scope, async () => fn());
+}
+/**
+* Programmatically suspend the current workflow node. The `value` is
+* surfaced to callers via the `WorkflowSuspendedEvent.value` field; the
+* eventual `Directive({ resume })` is delivered as the return value of
+* this call once the runtime resumes the thread.
+*
+* Implementation note: when the call is made outside a runtime-managed
+* resume scope, `pause(...)` throws a fresh {@link PauseSignal} so the
+* engine can catch it, persist state, and suspend. When the runtime
+* later resumes the node body, it wraps the second invocation in
+* {@link runWithPauseResume}, which causes the same `pause(...)` call to
+* return the operator-supplied resume value instead of throwing.
+*
+* @stable
+*/
+function pause(value) {
+	const scope = pauseResumeStorage.getStore();
+	if (scope !== void 0 && scope.cursor < scope.values.length) {
+		const next = scope.values[scope.cursor];
+		scope.cursor += 1;
+		return next;
+	}
+	throw new PauseSignal(value);
+}
+/**
+* Cross-realm safe type guard for `PauseSignal`.
+*
+* @stable
+*/
+function isPauseSignal(err) {
+	return typeof err === "object" && err !== null && err[PAUSE_SIGNAL_BRAND] === true;
+}
+
+//#endregion
+export { PAUSE_SIGNAL_BRAND, PauseSignal, isPauseSignal, pause, runWithPauseResume };
+//# sourceMappingURL=pause.js.map

package/dist/channels/pause.js.map

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

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

@@ -0,0 +1,45 @@
+//#region src/contracts/auth-token-store.d.ts
+/**
+ * Persisted server auth token record. Holds a per-token HMAC hash + scope
+ * grammar; raw tokens are never persisted (the runtime carries them via
+ * `SecretValue`).
+ *
+ * @stable
+ */
+interface AuthTokenRecord {
+  /** Stable identifier (the public part of the token, before the secret). */
+  readonly id: string;
+  /** HMAC-SHA256 of the secret part, peppered. Hex-encoded. */
+  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>]`. */
+  readonly scopes: ReadonlyArray<string>;
+  readonly createdAt: string;
+  readonly expiresAt?: string;
+  readonly revokedAt?: string;
+  readonly lastUsedAt?: string;
+}
+/**
+ * Pluggable storage for server auth tokens. The default implementation
+ * lives in `@graphorin/store-sqlite` (`auth_tokens` table). The server
+ * package implements `verifyToken(...)` on top of this contract.
+ *
+ * @stable
+ */
+interface AuthTokenStore {
+  put(record: AuthTokenRecord): Promise<void>;
+  get(id: string): Promise<AuthTokenRecord | null>;
+  list(): Promise<ReadonlyArray<AuthTokenRecord>>;
+  revoke(id: string, revokedAt: string): Promise<void>;
+  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
+   * an O(n) full-table scan per verification.
+   */
+  getByHash?(hashHex: string): Promise<AuthTokenRecord | null>;
+}
+//#endregion
+export { AuthTokenRecord, AuthTokenStore };
+//# sourceMappingURL=auth-token-store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"auth-token-store.d.ts","names":[],"sources":["../../src/contracts/auth-token-store.ts"],"sourcesContent":[],"mappings":";;AAOA;AAsBA;;;;;AAGgC,UAzBf,eAAA,CAyBe;EAAd;EAAR,SAAA,EAAA,EAAA,MAAA;EAC+B;EACA,SAAA,OAAA,EAAA,MAAA;EAMF;EAAR,SAAA,KAAA,CAAA,EAAA,MAAA;EAAO;mBAzBnB;;;;;;;;;;;;;UAcF,cAAA;cACH,kBAAkB;mBACb,QAAQ;UACjB,QAAQ,cAAc;yCACS;yCACA;;;;;;+BAMV,QAAQ"}

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

@@ -0,0 +1,90 @@
+//#region src/contracts/checkpoint-store.d.ts
+/**
+ * Opaque identifier for a single workflow checkpoint. Treated as a string
+ * by every consumer so adapters can pick whatever encoding they prefer
+ * (ULID, UUID, snowflake-like, …).
+ *
+ * @stable
+ */
+type CheckpointId = string;
+/**
+ * Serialized snapshot of workflow state, written after every execution
+ * step.
+ *
+ * @stable
+ */
+interface Checkpoint {
+  readonly id: CheckpointId;
+  readonly threadId: string;
+  readonly namespace: string;
+  readonly parentId?: CheckpointId;
+  /** 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>>;
+  readonly stepNumber: number;
+  readonly createdAt: string;
+}
+/**
+ * Metadata associated with a checkpoint write. Adapters store this in a
+ * sidecar table for efficient listing.
+ *
+ * @stable
+ */
+interface CheckpointMetadata {
+  readonly source: 'sync' | 'async' | 'exit';
+  readonly status: 'running' | 'suspended' | 'completed' | 'failed' | 'aborted';
+  readonly nodeName?: string;
+  readonly tags?: ReadonlyArray<string>;
+}
+/**
+ * A checkpoint paired with its sidecar metadata. Returned by
+ * `CheckpointStore.getTuple(...)` and the `list(...)` iterator.
+ *
+ * @stable
+ */
+interface CheckpointTuple {
+  readonly checkpoint: Checkpoint;
+  readonly metadata: CheckpointMetadata;
+  readonly pendingWrites?: ReadonlyArray<PendingWrite>;
+}
+/**
+ * Per-task pending write. Captured when a task in an execution step
+ * succeeds while a sibling task fails: the next resume attempt skips the
+ * already-completed work.
+ *
+ * @stable
+ */
+interface PendingWrite {
+  readonly taskId: string;
+  readonly index: number;
+  readonly channel: string;
+  /** Serialized value blob — adapter-specific encoding. */
+  readonly value: unknown;
+}
+/**
+ * Optional listing range for `CheckpointStore.list(...)`.
+ *
+ * @stable
+ */
+interface ListOptions {
+  readonly limit?: number;
+  readonly before?: CheckpointId;
+  readonly status?: CheckpointMetadata['status'];
+}
+/**
+ * Pluggable checkpoint storage interface. The default implementation
+ * lives in `@graphorin/store-sqlite`.
+ *
+ * @stable
+ */
+interface CheckpointStore {
+  put(threadId: string, namespace: string, checkpoint: Checkpoint, metadata: CheckpointMetadata): 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 };
+//# sourceMappingURL=checkpoint-store.d.ts.map

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

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

package/dist/contracts/embedder.d.ts

@@ -0,0 +1,45 @@
+//#region src/contracts/embedder.d.ts
+/**
+ * Pluggable embedding provider. Implementations live in the embedder
+ * adapter packages (`@graphorin/embedder-transformersjs` (default),
+ * `@graphorin/embedder-ollama`, …).
+ *
+ * Each embedder advertises its model `id`, output `dim`, and a stable
+ * `configHash` used by the multi-table per-embedder vec0 layout in the
+ * default SQLite store: facts indexed under embedder A and facts indexed
+ * under embedder B live in separate vec0 tables; the `configHash` is the
+ * lookup key.
+ *
+ * @stable
+ */
+interface EmbedderProvider {
+  /** Stable identifier (e.g. `'transformersjs:Xenova/multilingual-e5-base'`). */
+  id(): string;
+  /** Output dimensionality of the embedding vectors. */
+  dim(): number;
+  /** Stable hash of the embedder's configuration (model + revision + opts). */
+  configHash(): string;
+  /** Compute embeddings for a batch of texts. Returns one vector per text. */
+  embed(texts: ReadonlyArray<string>, opts?: EmbedOptions): Promise<ReadonlyArray<Float32Array>>;
+}
+/**
+ * Per-call options for `EmbedderProvider.embed(...)`.
+ *
+ * @stable
+ */
+interface EmbedOptions {
+  readonly signal?: AbortSignal;
+  /** Optional per-call request id forwarded to the trace span. */
+  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
+   * 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.
+   */
+  readonly taskType?: 'query' | 'passage';
+}
+//#endregion
+export { EmbedOptions, EmbedderProvider };
+//# sourceMappingURL=embedder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"embedder.d.ts","names":[],"sources":["../../src/contracts/embedder.ts"],"sourcesContent":[],"mappings":";;AAaA;;;;;;;AAgBA;;;;;UAhBiB,gBAAA;;;;;;;;eAQF,8BAA8B,eAAe,QAAQ,cAAc;;;;;;;UAQjE,YAAA;oBACG"}

package/dist/contracts/eval-scorer.d.ts

@@ -0,0 +1,46 @@
+//#region src/contracts/eval-scorer.d.ts
+/**
+ * Pluggable evaluation scorer. Generic over the input / output types
+ * carried by the eval dataset. Concrete implementations live in the
+ * separate `@graphorin/evals` package (post-MVP); the interface lives
+ * here so that:
+ *
+ * - The minimal inline runner shipped with `@graphorin/observability` can
+ *   type-check against it.
+ * - Custom application-level scorers can be defined without taking an
+ *   evals dependency.
+ *
+ * @stable
+ */
+interface EvalScorer<TInput = unknown, TOutput = unknown> {
+  readonly id: string;
+  readonly description?: string;
+  score(sample: EvalSample<TInput, TOutput>): Promise<EvalScore>;
+}
+/**
+ * A single sample from an eval dataset.
+ *
+ * @stable
+ */
+interface EvalSample<TInput = unknown, TOutput = unknown> {
+  readonly id: string;
+  readonly input: TInput;
+  readonly expected?: TOutput;
+  readonly actual: TOutput;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Result of `EvalScorer.score(...)`. `value` is normalized to `[0, 1]`
+ * by convention; raw scores can be carried in `details`.
+ *
+ * @stable
+ */
+interface EvalScore {
+  readonly value: number;
+  readonly pass?: boolean;
+  readonly rationale?: string;
+  readonly details?: Readonly<Record<string, unknown>>;
+}
+//#endregion
+export { EvalSample, EvalScore, EvalScorer };
+//# sourceMappingURL=eval-scorer.d.ts.map

package/dist/contracts/eval-scorer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"eval-scorer.d.ts","names":[],"sources":["../../src/contracts/eval-scorer.ts"],"sourcesContent":[],"mappings":";;AAaA;;;;;;;AAWA;;;;;AAKsB,UAhBL,UAgBK,CAAA,SAAA,OAAA,EAAA,UAAA,OAAA,CAAA,CAAA;EAAQ,SAAA,EAAA,EAAA,MAAA;EASb,SAAA,WAAS,CAAA,EAAA,MAII;gBA1Bd,WAAW,QAAQ,WAAW,QAAQ;;;;;;;UAQrC;;kBAEC;sBACI;mBACH;sBACG,SAAS;;;;;;;;UASd,SAAA;;;;qBAII,SAAS"}

package/dist/contracts/index.d.ts

@@ -0,0 +1,22 @@
+import { AuthTokenRecord, AuthTokenStore } from "./auth-token-store.js";
+import { Checkpoint, CheckpointId, CheckpointMetadata, 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";
+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 { 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 { RedactionInput, RedactionOutput, RedactionValidator } from "./redaction-validator.js";
+import { Sandbox, SandboxCode, SandboxResult, SandboxRunOptions } from "./sandbox.js";
+import { SecretRef } from "./secret-ref.js";
+import { NODEJS_INSPECT_CUSTOM, SECRET_VALUE_BRAND, SecretValue, SecretValueOptions, SecretValueStatic } from "./secret-value.js";
+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 };

package/dist/contracts/index.js

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

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

@@ -0,0 +1,36 @@
+//#region src/contracts/local-provider-trust.d.ts
+/**
+ * Trust class assigned to a local-LLM provider based on the
+ * configured `baseUrl`. The classifier dispatcher lives in
+ * `@graphorin/provider/trust/classify-local-provider.ts`; the literal
+ * union is hoisted here so consumers (security policy, observability,
+ * prompt redaction) can type-check against it without depending on
+ * `@graphorin/provider`.
+ *
+ * Tier semantics:
+ *
+ * - `'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`,
+ *   `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
+ *   refuse to start unless explicitly overridden.
+ *
+ * @stable
+ */
+type LocalProviderTrust = 'loopback' | 'private' | 'public-tls' | 'public-cleartext';
+/**
+ * Legacy alias preserved for downstream packages that still import the
+ * Ollama-specific name. Removed in v0.2 per the legacy-sugar
+ * deprecation policy.
+ *
+ * @deprecated Use {@link LocalProviderTrust} instead. Removed in v0.2.
+ */
+type OllamaTrust = LocalProviderTrust;
+//#endregion
+export { LocalProviderTrust, OllamaTrust };
+//# sourceMappingURL=local-provider-trust.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"local-provider-trust.d.ts","names":[],"sources":["../../src/contracts/local-provider-trust.ts"],"sourcesContent":[],"mappings":";;AAuBA;AASA;;;;;;;;;;;;;;;;;;;;;KATY,kBAAA;;;;;;;;KASA,WAAA,GAAc"}

package/dist/contracts/logger.d.ts

@@ -0,0 +1,53 @@
+//#region src/contracts/logger.d.ts
+/**
+ * Severity levels supported by the project logger. Mirrors the canonical
+ * `trace < debug < info < warn < error` hierarchy used by every common
+ * structured logger.
+ *
+ * @stable
+ */
+type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Free-form structured fields that accompany a log record. Values must be
+ * JSON-serializable; concrete loggers redact `SecretValue` and other
+ * sensitive shapes per the framework's redaction policy.
+ *
+ * @stable
+ */
+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
+ * observability dependency.
+ *
+ * Loggers are intentionally **structured** and **side-effect-free** in the
+ * type contract: the `info(msg, fields?)` signature is a hint, not a
+ * mandate to actually emit anything. Implementations may sample, drop, or
+ * batch.
+ *
+ * @stable
+ */
+interface Logger {
+  trace(message: string, fields?: LogFields): void;
+  debug(message: string, fields?: LogFields): void;
+  info(message: string, fields?: LogFields): void;
+  warn(message: string, fields?: LogFields): void;
+  error(message: string, fields?: LogFields): void;
+  /**
+   * Return a child logger with `fields` merged into every record's
+   * structured payload. Useful for binding `runId` / `sessionId` /
+   * `agentId` once at the top of a request.
+   */
+  child(fields: LogFields): Logger;
+}
+/**
+ * Minimal no-op logger. Useful as a typed default when downstream code
+ * needs a non-null `Logger` without taking the observability dependency.
+ *
+ * @stable
+ */
+declare const NOOP_LOGGER: Logger;
+//#endregion
+export { LogFields, LogLevel, Logger, NOOP_LOGGER };
+//# sourceMappingURL=logger.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","names":[],"sources":["../../src/contracts/logger.ts"],"sourcesContent":[],"mappings":";;AAOA;AASA;AAeA;;;;AAIiC,KA5BrB,QAAA,GA4BqB,OAAA,GAAA,OAAA,GAAA,MAAA,GAAA,MAAA,GAAA,OAAA;;;;;AAgBjC;;;KAnCY,SAAA,GAAY,SAAS;;;;;;;;;;;;;;UAehB,MAAA;kCACiB;kCACA;iCACD;iCACA;kCACC;;;;;;gBAMlB,YAAY;;;;;;;;cASf,aAAa"}

package/dist/contracts/logger.js

@@ -0,0 +1,21 @@
+//#region src/contracts/logger.ts
+/**
+* Minimal no-op logger. Useful as a typed default when downstream code
+* needs a non-null `Logger` without taking the observability dependency.
+*
+* @stable
+*/
+const NOOP_LOGGER = {
+	trace() {},
+	debug() {},
+	info() {},
+	warn() {},
+	error() {},
+	child() {
+		return NOOP_LOGGER;
+	}
+};
+
+//#endregion
+export { NOOP_LOGGER };
+//# sourceMappingURL=logger.js.map

package/dist/contracts/logger.js.map

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

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

@@ -0,0 +1,106 @@
+import { Block, Episode, Fact, MemoryHit, MemoryRecord, MemorySearchOptions, Rule } from "../types/memory.js";
+import { Message } from "../types/message.js";
+import { SessionScope } from "../types/session-scope.js";
+
+//#region src/contracts/memory-store.d.ts
+
+/**
+ * Persistent storage interface for the six memory tiers. Implementations
+ * live in the storage adapter packages (`@graphorin/store-sqlite` is the
+ * default).
+ *
+ * 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.
+ *
+ * @stable
+ */
+interface MemoryStore {
+  readonly working: WorkingMemoryStore;
+  readonly session: SessionMemoryStore;
+  readonly episodic: EpisodicMemoryStore;
+  readonly semantic: SemanticMemoryStore;
+  readonly procedural: ProceduralMemoryStore;
+  readonly shared: SharedMemoryStore;
+  /** Initialize / migrate the underlying storage. Idempotent. */
+  init(): Promise<void>;
+  /** Cleanly close any underlying handles. Idempotent. */
+  close(): Promise<void>;
+}
+/** @stable */
+interface WorkingMemoryStore {
+  list(scope: SessionScope): Promise<ReadonlyArray<Block>>;
+  get(scope: SessionScope, label: string): Promise<Block | null>;
+  upsert(scope: SessionScope, block: Block): Promise<void>;
+  delete(scope: SessionScope, label: string, reason?: string): Promise<void>;
+}
+/**
+ * Reference returned by `SessionMemoryStore.push(...)`. Carries the
+ * persisted message id and a sequence number for ordering.
+ *
+ * @stable
+ */
+interface MessageRef {
+  readonly messageId: string;
+  readonly sequence: number;
+  readonly persistedAt: string;
+}
+/**
+ * A stored message paired with its persisted identity (RP-5). The {@link Message}
+ * type itself carries no id / timestamp; these come from the store row, so an
+ * exporter can preserve message identity + chronology across a round-trip.
+ *
+ * @stable
+ */
+interface SessionMessageWithMetadata {
+  readonly message: Message;
+  readonly messageId: string;
+  readonly sequence: number;
+  readonly createdAt: string;
+}
+/** @stable */
+interface SessionMemoryStore {
+  push(scope: SessionScope, message: Message): Promise<MessageRef>;
+  list(scope: SessionScope, opts?: SessionListOptions): Promise<ReadonlyArray<Message>>;
+  /**
+   * List messages with their persisted identity (RP-5). Optional: stores that
+   * don't implement it fall back to `list` + fabricated ids on the export path.
+   */
+  listWithMetadata?(scope: SessionScope, opts?: SessionListOptions): Promise<ReadonlyArray<SessionMessageWithMetadata>>;
+  search(scope: SessionScope, query: string, opts?: MemorySearchOptions): Promise<ReadonlyArray<MemoryHit>>;
+}
+/** @stable */
+interface SessionListOptions {
+  readonly lastN?: number;
+  readonly sinceMessageId?: string;
+  readonly agentId?: string;
+  readonly role?: 'system' | 'user' | 'assistant' | 'tool';
+}
+/** @stable */
+interface EpisodicMemoryStore {
+  put(episode: Episode): Promise<void>;
+  search(scope: SessionScope, opts: MemorySearchOptions): Promise<ReadonlyArray<MemoryHit<Episode>>>;
+  get(id: string): Promise<Episode | null>;
+}
+/** @stable */
+interface SemanticMemoryStore {
+  remember(fact: Fact): Promise<void>;
+  search(scope: SessionScope, opts: MemorySearchOptions): Promise<ReadonlyArray<MemoryHit<Fact>>>;
+  supersede(oldId: string, newFact: Fact, reason?: string): Promise<void>;
+  forget(id: string, reason?: string): Promise<void>;
+}
+/** @stable */
+interface ProceduralMemoryStore {
+  add(rule: Rule): Promise<void>;
+  list(scope: SessionScope): Promise<ReadonlyArray<Rule>>;
+  remove(id: string, reason?: string): Promise<void>;
+}
+/** @stable */
+interface SharedMemoryStore {
+  attach(recordId: string, agentId: string): Promise<void>;
+  detach(recordId: string, agentId: string): Promise<void>;
+  listFor(agentId: string): Promise<ReadonlyArray<MemoryRecord>>;
+}
+//#endregion
+export { EpisodicMemoryStore, MemoryStore, MessageRef, ProceduralMemoryStore, SemanticMemoryStore, SessionListOptions, SessionMemoryStore, SessionMessageWithMetadata, SharedMemoryStore, WorkingMemoryStore };
+//# sourceMappingURL=memory-store.d.ts.map

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

@@ -0,0 +1 @@
+{"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,CAAA,EAvBE,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"}