@graphorin/core 0.6.1 → 0.7.0

package/src/contracts/index.ts

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

package/src/contracts/local-provider-trust.ts

@@ -0,0 +1,33 @@
+/**
+ * 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
+ */
+export 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.
+ */
+export type OllamaTrust = LocalProviderTrust;

package/src/contracts/logger.ts

@@ -0,0 +1,61 @@
+/**
+ * Severity levels supported by the project logger. Mirrors the canonical
+ * `trace < debug < info < warn < error` hierarchy used by every common
+ * structured logger.
+ *
+ * @stable
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export const NOOP_LOGGER: Logger = {
+  trace(): void {},
+  debug(): void {},
+  info(): void {},
+  warn(): void {},
+  error(): void {},
+  child(): Logger {
+    return NOOP_LOGGER;
+  },
+};

package/src/contracts/memory-store.ts

@@ -0,0 +1,187 @@
+import type {
+  Block,
+  Episode,
+  Fact,
+  MemoryHit,
+  MemoryRecord,
+  MemorySearchOptions,
+  Rule,
+} from '../types/memory.js';
+import type { Message } from '../types/message.js';
+import type { SessionScope } from '../types/session-scope.js';
+
+/**
+ * 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.
+ *
+ * **Baseline vs full adapter (W-048).** This interface is the MINIMUM a
+ * third-party adapter must implement; `@graphorin/memory` accepts it and
+ * degrades gracefully (vector search, decay, consolidation, insights,
+ * graph expansion, conflict audit switch off where the surface is
+ * absent). Full feature parity with `@graphorin/store-sqlite` (asOf
+ * reads, vector KNN, decay signals, insights, entity graph, conflicts,
+ * consolidator state/DLQ) is described by `MemoryStoreAdapter` and the
+ * `*MemoryStoreExt` interfaces exported from the root of
+ * `@graphorin/memory`. Every Ext addition over the six tier namespaces
+ * is optional BY CONTRACT - a type test in `@graphorin/memory` pins
+ * `MemoryStore extends MemoryStoreAdapter`, so a core-only adapter can
+ * never stop compiling.
+ *
+ * @stable
+ */
+export 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>;
+}
+
+/**
+ * Maintenance extension over {@link MemoryStore} (W-066), mirroring
+ * the `SessionStoreExt` precedent: capabilities the sqlite adapter
+ * guarantees but a custom `MemoryStore` is not obliged to implement.
+ * The base contract is unchanged - existing implementations keep
+ * compiling.
+ *
+ * @stable
+ */
+export interface MemoryStoreExt extends MemoryStore {
+  /**
+   * Delete `memory_history` rows older than the given AGE in
+   * milliseconds. The argument is an AGE (the implementation computes
+   * `cutoff = now - olderThanMs`), never an epoch cutoff - passing an
+   * epoch value would compute a nonsense cutoff far in the past and
+   * silently prune nothing. Returns the number of rows removed.
+   * History grows by design (every supersede / quarantine transition
+   * appends) and `purge()` already scrubs sensitive text; this is the
+   * storage-cost hygiene lever - nothing prunes automatically.
+   */
+  pruneHistory(olderThanMs: number): Promise<number>;
+}
+
+/** @stable */
+export 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
+ */
+export 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
+ */
+export interface SessionMessageWithMetadata {
+  readonly message: Message;
+  readonly messageId: string;
+  readonly sequence: number;
+  readonly createdAt: string;
+}
+
+/** @stable */
+export 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>>;
+  /**
+   * Full-text search over the scoped session messages.
+   *
+   * Query precedence (W-127): the POSITIONAL `query` parameter is
+   * authoritative; when the caller also sets `opts.query` (the field
+   * exists because {@link MemorySearchOptions} is shared with the
+   * option-object search surfaces), implementations MUST ignore it.
+   * The duplication is a known wart: narrowing `opts` to
+   * `Omit<MemorySearchOptions, 'query'>` is a candidate for the next
+   * major, not a change this line can make compatibly.
+   */
+  search(
+    scope: SessionScope,
+    query: string,
+    opts?: MemorySearchOptions,
+  ): Promise<ReadonlyArray<MemoryHit>>;
+}
+
+/** @stable */
+export interface SessionListOptions {
+  readonly lastN?: number;
+  readonly sinceMessageId?: string;
+  readonly agentId?: string;
+  readonly role?: 'system' | 'user' | 'assistant' | 'tool';
+}
+
+/** @stable */
+export interface EpisodicMemoryStore {
+  put(episode: Episode): Promise<void>;
+  search(
+    scope: SessionScope,
+    opts: MemorySearchOptions,
+  ): Promise<ReadonlyArray<MemoryHit<Episode>>>;
+  get(id: string): Promise<Episode | null>;
+}
+
+/** @stable */
+export 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>;
+  /**
+   * Soft-delete a fact. W-154: when `scope` is supplied, adapters that
+   * support tenant isolation MUST treat a fact outside the scope as a
+   * deterministic no-op (0 rows changed) - defense in depth so a
+   * leaked / cross-user id reaching a mutator cannot touch another
+   * user's memory. Omitting `scope` preserves the historical unscoped
+   * behaviour (trusted internal callers: consolidator, erasure
+   * cascades). The parameter is additive - existing adapter
+   * implementations with the narrower arity remain structurally
+   * compatible.
+   */
+  forget(id: string, reason?: string, scope?: SessionScope): Promise<void>;
+}
+
+/** @stable */
+export interface ProceduralMemoryStore {
+  add(rule: Rule): Promise<void>;
+  list(scope: SessionScope): Promise<ReadonlyArray<Rule>>;
+  remove(id: string, reason?: string): Promise<void>;
+}
+
+/** @stable */
+export interface SharedMemoryStore {
+  attach(recordId: string, agentId: string): Promise<void>;
+  detach(recordId: string, agentId: string): Promise<void>;
+  listFor(agentId: string): Promise<ReadonlyArray<MemoryRecord>>;
+}

package/src/contracts/oauth-server-store.ts

@@ -0,0 +1,78 @@
+/**
+ * Persisted metadata for an OAuth server registration. The framework
+ * 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.
+ *
+ * Schema mirrors the canonical `oauth_servers` SQLite table provided
+ * by `@graphorin/store-sqlite`.
+ *
+ * @stable
+ */
+export interface OAuthServerRecord {
+  /** Stable, human-readable identifier (e.g. `'linear-mcp'`). */
+  readonly id: string;
+  /** Base URL of the OAuth-protected resource server (e.g. MCP endpoint). */
+  readonly serverUrl: string;
+  /** Authorization-server `authorization_endpoint`. */
+  readonly authorizationEndpoint?: string;
+  /** Authorization-server `token_endpoint`. */
+  readonly tokenEndpoint?: string;
+  /** Authorization-server `registration_endpoint` (RFC 7591). */
+  readonly registrationEndpoint?: string;
+  /** Authorization-server `revocation_endpoint` (RFC 7009). */
+  readonly revocationEndpoint?: string;
+  /** Authorization-server `device_authorization_endpoint` (RFC 8628). */
+  readonly deviceAuthorizationEndpoint?: string;
+  /** Issuer identifier reported in the discovery response. */
+  readonly issuer?: string;
+  /** Public client identifier; safe to log. */
+  readonly clientId: string;
+  /** {@link SecretRef} URI for the confidential-client secret. */
+  readonly clientSecretRef?: string;
+  /** {@link SecretRef} URI for the access token. */
+  readonly accessTokenRef?: string;
+  /** {@link SecretRef} URI for the refresh token. */
+  readonly refreshTokenRef?: string;
+  /** {@link SecretRef} URI for the OIDC ID token. */
+  readonly idTokenRef?: string;
+  /** Epoch milliseconds when the access token stops being valid. */
+  readonly expiresAt?: number;
+  /** Granted scopes (space-separated string per the OAuth spec). */
+  readonly scope?: string;
+  /** Redirect URI that was used during the most recent code flow. */
+  readonly redirectUri?: string;
+  /** Whether the client was registered via Dynamic Client Registration. */
+  readonly registeredVia?: 'dcr' | 'manual';
+  /** Epoch milliseconds of the last successful refresh. */
+  readonly lastRefreshedAt?: number;
+  /** Last error string captured from a failing refresh attempt. */
+  readonly lastRefreshError?: string;
+  /** Epoch milliseconds when the record was first created. */
+  readonly createdAt: number;
+  /** Epoch milliseconds when the record was last updated. */
+  readonly updatedAt: number;
+}
+
+/**
+ * Pluggable storage for OAuth server registrations + token metadata.
+ *
+ * The default implementation lives in `@graphorin/store-sqlite`
+ * (`oauth_servers` table). `@graphorin/security` ships an in-memory
+ * implementation that callers can use until the SQLite-backed store
+ * is wired up.
+ *
+ * @stable
+ */
+export interface OAuthServerStore {
+  /** Insert or replace the record for `id`. */
+  put(record: OAuthServerRecord): Promise<void>;
+  /** Read the record for `id`, returning `null` when absent. */
+  get(id: string): Promise<OAuthServerRecord | null>;
+  /** Snapshot of all stored records, ordered by `id`. */
+  list(): Promise<ReadonlyArray<OAuthServerRecord>>;
+  /** Apply a partial update to the record at `id`. */
+  update(id: string, patch: Partial<OAuthServerRecord>): Promise<OAuthServerRecord>;
+  /** Remove the record for `id`. */
+  delete(id: string): Promise<void>;
+}

package/src/contracts/preferred-model.ts

@@ -0,0 +1,56 @@
+/**
+ * Cost-tier vocabulary for declaring a preferred model on a tool or
+ * agent. Provider-agnostic at the tool-author level; the operator-side
+ * `Agent.modelTierMap?: Partial<Record<ModelHint, ModelSpec>>` mapping
+ * resolves the hint to a concrete provider per agent.
+ *
+ * The three tiers describe canonical cloud-provider price-quality
+ * envelopes circa 2026:
+ *
+ * - `'fast'`     - low-cost / low-latency / file-navigation /
+ *   parameter-extraction / low-stakes calls.
+ * - `'balanced'` - median cost-quality; the default tier for most
+ *   tools.
+ * - `'smart'`    - high-quality / high-stakes / reasoning-heavy /
+ *   summarization / code-review calls.
+ *
+ * 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`.
+ *
+ * @stable
+ */
+export type ModelHint = 'fast' | 'balanced' | 'smart';
+
+/**
+ * Discriminated string-literal triple for type-level work.
+ *
+ * @stable
+ */
+export const MODEL_HINTS: readonly ModelHint[] = ['fast', 'balanced', 'smart'] as const;
+
+/**
+ * Forward-declared shape of `Provider`. Re-declared here as a minimal
+ * structural type so this module stays cycle-free with respect to
+ * `./provider.ts` and downstream consumers can use `ModelSpec` without
+ * importing the heavier `Provider` interface.
+ *
+ * @internal
+ */
+export interface ProviderLike {
+  readonly name: string;
+  readonly modelId: string;
+}
+
+/**
+ * Concrete provider declaration used at site of the per-tool hint
+ * override (Phase 07), the per-tier mapping
+ * (`Agent.modelTierMap`, Phase 12), and the agent-level fallback chain
+ * (`Agent.fallbackModels`, Phase 12).
+ *
+ * The shape is unified deliberately so operators learn one thing and
+ * use it three places.
+ *
+ * @stable
+ */
+export type ModelSpec = ProviderLike | { readonly provider: ProviderLike; readonly model: string };