@graphorin/core 0.6.0 → 0.7.0

package/src/types/index.ts

@@ -0,0 +1,148 @@
+/**
+ * Plain TypeScript types for the Graphorin framework.
+ *
+ * @packageDocumentation
+ */
+
+export type {
+  AgentCancellingEvent,
+  AgentEndEvent,
+  AgentErrorEvent,
+  AgentEvaluatorConvergedEvent,
+  AgentEvaluatorIterationEvent,
+  AgentEvent,
+  AgentFanOutMergedEvent,
+  AgentFanOutSpawnedEvent,
+  AgentFollowUpQueuedEvent,
+  AgentLateralLeakDetectedEvent,
+  AgentModelFellbackEvent,
+  AgentProgressReadEvent,
+  AgentProgressWrittenEvent,
+  AgentResult,
+  AgentStartEvent,
+  AgentSteeredEvent,
+  ContextCompactedEvent,
+  FanOutChildMetadata,
+  GuardrailTrippedEvent,
+  HandoffEvent,
+  LateralLeakVector,
+  ProgressArtifactRef,
+  ReasoningDeltaEvent,
+  StepEndEvent,
+  StepStartEvent,
+  TextCompleteEvent,
+  TextDeltaEvent,
+  ToolApprovalDeniedEvent,
+  ToolApprovalGrantedEvent,
+  ToolApprovalRequestedEvent,
+  ToolCallDeltaEvent,
+  ToolCallEndEvent,
+  ToolCallStartEvent,
+  ToolExecuteEndEvent,
+  ToolExecuteErrorEvent,
+  ToolExecutePartialEvent,
+  ToolExecuteProgressEvent,
+  ToolExecuteStartEvent,
+  VerifierResultEvent,
+} from './agent-event.js';
+export type {
+  WireAgentEndEvent,
+  WireAgentEvent,
+  WireContentChunk,
+  WireFileGeneratedEvent,
+  WireToolExecutePartialEvent,
+} from './agent-event-wire.js';
+export { fromWireAgentEvent, toWireAgentEvent } from './agent-event-wire.js';
+export type {
+  Handoff,
+  HandoffFilter,
+  HandoffInputFilterDescriptor,
+  HandoffRecord,
+  HandoffSecretsInheritance,
+} from './handoff.js';
+export type {
+  Block,
+  EntityRole,
+  Episode,
+  Fact,
+  GraphEntity,
+  Insight,
+  MemoryHit,
+  MemoryKind,
+  MemoryMetadata,
+  MemoryOwner,
+  MemoryProvenance,
+  MemoryRecord,
+  MemorySearchOptions,
+  MemoryStatus,
+  Rule,
+} from './memory.js';
+export type {
+  AssistantMessage,
+  AudioContent,
+  FileContent,
+  ImageContent,
+  Message,
+  MessageContent,
+  MessageRole,
+  ReasoningContent,
+  ReasoningContentMeta,
+  SystemMessage,
+  TextContent,
+  ToolMessage,
+  UserMessage,
+} from './message.js';
+export {
+  flattenUsageByModel,
+  type ReadonlyRunState,
+  type RunContext,
+  type RunError,
+  type RunState,
+  type RunStateUsageByModel,
+  type RunStatus,
+  type RunStep,
+  type RunStepProviderResponse,
+  type RunTaintSummary,
+  type TodoItem,
+} from './run.js';
+export type { Sensitivity } from './sensitivity.js';
+export { acceptsSensitivity, SENSITIVITY_ORDER } from './sensitivity.js';
+export type { SessionScope } from './session-scope.js';
+export type { StopCondition } from './stop-condition.js';
+export { and, hasToolCall, isStepCount, isTerminal, not, or } from './stop-condition.js';
+export type {
+  CompletedToolCall,
+  ContentChunk,
+  InboundSanitizationPolicy,
+  MemoryGuardTier,
+  RecoveryHint,
+  ResultHandle,
+  SandboxPolicy,
+  SideEffectClass,
+  ToolApproval,
+  ToolCall,
+  ToolError,
+  ToolErrorKind,
+  ToolOutcome,
+  ToolResult,
+  ToolSource,
+  ToolTrustClass,
+  TruncationStrategy,
+} from './tool.js';
+export type { Cost, ModelUsage, Usage, UsageAccumulator, UsageSnapshot } from './usage.js';
+export { zeroUsage } from './usage.js';
+export type {
+  WorkflowChannelUpdateEvent,
+  WorkflowCheckpointWrittenEvent,
+  WorkflowCustomEvent,
+  WorkflowEndEvent,
+  WorkflowErrorEvent,
+  WorkflowEvent,
+  WorkflowResumedEvent,
+  WorkflowStartEvent,
+  WorkflowStepEndEvent,
+  WorkflowStepStartEvent,
+  WorkflowSuspendedEvent,
+  WorkflowTaskEndEvent,
+  WorkflowTaskStartEvent,
+} from './workflow-event.js';

package/src/types/memory.ts

@@ -0,0 +1,427 @@
+import type { Sensitivity } from './sensitivity.js';
+
+/**
+ * Kinds of memory record in the Graphorin model. The first six are the
+ * storage tiers the {@link MemoryStore} contract exposes as 1:1
+ * sub-namespaces; `insight` is the derived, reflection-synthesized
+ * record kind (P1-1) - it has no base-tier namespace and is persisted
+ * through the optional insight surface adapters expose. Used as the
+ * discriminator for span types and the `MemoryRecord` union.
+ *
+ * @stable
+ */
+export type MemoryKind =
+  | 'working'
+  | 'session'
+  | 'episodic'
+  | 'semantic'
+  | 'procedural'
+  | 'shared'
+  | 'insight';
+
+/**
+ * Where a memory came from - the trust-provenance tag carried by every
+ * fact / episode / induced procedure. `user` (the human said it) and
+ * `tool` (a tool the agent invoked returned it) are first-party;
+ * `extraction` (consolidator distilled it from a transcript),
+ * `reflection` (a synthesis pass inferred it), and `induction` (an
+ * AWM-style pass distilled a reusable workflow from a successful agent
+ * trajectory, P2-2) are *derived* and therefore land quarantined by
+ * default; `imported` is bulk-loaded from an external store. Used by
+ * P1-4 to gate action-driving recall against memory-poisoning (MINJA /
+ * MemoryGraft) - induced procedures drive *actions*, so the quarantine
+ * gate matters most for them.
+ *
+ * @stable
+ */
+export type MemoryProvenance =
+  | 'user'
+  | 'tool'
+  | 'extraction'
+  | 'reflection'
+  | 'induction'
+  | 'imported';
+
+/**
+ * Retrieval-trust state of a memory. `active` rows are eligible for
+ * default recall; `quarantined` rows are persisted and auditable but
+ * excluded from action-driving recall until explicitly validated (P1-4).
+ * Quarantine is a *retrieval gate*, never a delete.
+ *
+ * @stable
+ */
+export type MemoryStatus = 'active' | 'quarantined';
+
+/**
+ * Principal a memory belongs to (D3) - the *who-owns-this* dimension,
+ * orthogonal to {@link MemoryProvenance} (*where-it-came-from*):
+ * `user` for user-stated content, `agent` for the agent's own
+ * inferences (consolidator extraction / reflection / induction stamp
+ * this), `shared` for records deliberately published to a multi-agent
+ * shared tier. Absent (rows written before the feature, or writers
+ * that do not care) is treated as `user` at filter time; default
+ * reads apply **no owner filter**, so behaviour is unchanged until a
+ * caller opts into a retrieval-time scope filter.
+ *
+ * @stable
+ */
+export type MemoryOwner = 'user' | 'agent' | 'shared';
+
+/**
+ * Snapshot of memory-tier counters surfaced to the model via the
+ * memory-aware system prompt. Implementations live in `@graphorin/memory`;
+ * the type sits here so the agent runtime can include it in its
+ * `RunContext` without a memory dependency.
+ *
+ * @stable
+ */
+export interface MemoryMetadata {
+  /** Total number of facts in the user's semantic memory. */
+  readonly factCount: number;
+  /** Number of episodes stored for the user. */
+  readonly episodeCount: number;
+  /** Number of past messages indexed for retrieval. */
+  readonly messageCount: number;
+  /** Active rules count (after context filtering). */
+  readonly activeRuleCount: number;
+  /** Number of declared working blocks. */
+  readonly workingBlockCount: number;
+  /** Last consolidator run, ISO-8601, if any. */
+  readonly lastConsolidatedAt?: string;
+  /** Optional, free-form metadata tags surfaced to the model. */
+  readonly tags?: ReadonlyArray<string>;
+}
+
+/**
+ * Marker shared by every memory record. Concrete records (`Block`,
+ * `Fact`, `Episode`, `Rule`, message rows) all extend it.
+ *
+ * @stable
+ */
+export interface MemoryRecord {
+  readonly id: string;
+  readonly kind: MemoryKind;
+  readonly userId: string;
+  readonly agentId?: string;
+  readonly sessionId?: string;
+  readonly sensitivity: Sensitivity;
+  readonly createdAt: string;
+  readonly updatedAt?: string;
+  /**
+   * Soft-delete tombstone. Append-only stores set this instead of removing
+   * rows, so prior history is preserved per principle 8.
+   */
+  readonly deletedAt?: string;
+  readonly tags?: ReadonlyArray<string>;
+}
+
+/**
+ * Working-memory block - a labeled, char-bounded slot rendered into the
+ * system prompt every turn.
+ *
+ * @stable
+ */
+export interface Block extends MemoryRecord {
+  readonly kind: 'working';
+  readonly label: string;
+  readonly description?: string;
+  readonly value: string;
+  readonly charLimit: number;
+  readonly readOnly?: boolean;
+}
+
+/**
+ * Single semantic-memory fact: an atomic statement about the user / world.
+ *
+ * @stable
+ */
+export interface Fact extends MemoryRecord {
+  readonly kind: 'semantic';
+  readonly text: string;
+  /**
+   * Structured `(subject, predicate, object)` triple for the in-SQLite
+   * relation graph (P2-1). The consolidator's extraction prompt emits
+   * these; first-party `remember({ text })` writes usually omit them.
+   * `subject`/`object` are the graph *entities* (resolved to canonical
+   * ids in `fact_entities`); `predicate` is the relation label and is
+   * not itself an entity. Absent on rows written before the feature, and
+   * on plain free-text facts - they are a soft enrichment that powers
+   * one-hop expansion ({@link MemorySearchOptions} has no field; the
+   * memory tier's search opts in), never a recall gate.
+   */
+  readonly subject?: string;
+  /** Relation label of the {@link Fact.subject}→{@link Fact.object} triple (P2-1). */
+  readonly predicate?: string;
+  /** Object entity of the s/p/o triple (P2-1). See {@link Fact.subject}. */
+  readonly object?: string;
+  readonly confidence?: number;
+  /**
+   * Optional salience hint in `[0, 1]` for multi-signal forgetting
+   * (X-1). A *soft* signal - higher importance slows a fact's decay and
+   * delays capacity-bounded eviction, but never gates recall and never
+   * forces retention. Absent on rows written before the feature
+   * (treated as neutral, `0.5`).
+   */
+  readonly importance?: number;
+  /** Bi-temporal: when the fact became true, ISO-8601. */
+  readonly validFrom?: string;
+  /** Bi-temporal: when the fact stopped being true, ISO-8601. */
+  readonly validTo?: string;
+  /** ID of the fact this one supersedes, if any. */
+  readonly supersedes?: string;
+  /** ID of the fact that supersedes this one, if any. */
+  readonly supersededBy?: string;
+  /**
+   * Trust-provenance tag (P1-4). Absent on rows written before the
+   * feature; treated as first-party (`active`) when missing.
+   */
+  readonly provenance?: MemoryProvenance;
+  /**
+   * Retrieval-trust state (P1-4). Defaults to `active`; derived /
+   * injection-flagged writes land `quarantined` and are excluded from
+   * default recall.
+   */
+  readonly status?: MemoryStatus;
+  /**
+   * Principal dimension (D3). `'agent'` on consolidator-synthesized
+   * facts; absent ⇒ treated as `'user'` at filter time. Never gates
+   * default recall - only an explicit owner search filter reads it.
+   */
+  readonly owner?: MemoryOwner;
+}
+
+/**
+ * Episode - a summarized stretch of past activity.
+ *
+ * @stable
+ */
+export interface Episode extends MemoryRecord {
+  readonly kind: 'episodic';
+  readonly summary: string;
+  /** ISO-8601 of the earliest event in the episode. */
+  readonly startedAt: string;
+  /** ISO-8601 of the latest event in the episode. */
+  readonly endedAt: string;
+  /** Optional importance score in `[0, 1]`. */
+  readonly importance?: number;
+  /** Trust-provenance tag (P1-4). See {@link MemoryProvenance}. */
+  readonly provenance?: MemoryProvenance;
+  /** Retrieval-trust state (P1-4). See {@link MemoryStatus}. */
+  readonly status?: MemoryStatus;
+  /** Principal dimension (D3). See {@link MemoryOwner}. */
+  readonly owner?: MemoryOwner;
+}
+
+/**
+ * Procedural rule - a standing order activated when its `condition` matches.
+ *
+ * @stable
+ */
+export interface Rule extends MemoryRecord {
+  readonly kind: 'procedural';
+  readonly text: string;
+  readonly condition?: string;
+  readonly priority: number;
+  /**
+   * Ordered, value-abstracted step sequence of an *induced* workflow
+   * (P2-2) - e.g. `['search for {product}', 'add {quantity} to cart',
+   * 'check out']`. Present only on procedures distilled from successful
+   * agent trajectories; author-defined rules omit it.
+   */
+  readonly steps?: ReadonlyArray<string>;
+  /**
+   * Names of the variables abstracted from the trajectory's concrete
+   * values (P2-2) - the `{product}` / `{quantity}` placeholders that
+   * appear in {@link Rule.steps}. Lets a reused procedure be re-bound to
+   * fresh arguments instead of replaying one run's literals.
+   */
+  readonly variables?: ReadonlyArray<string>;
+  /**
+   * Voyager-style verifiable success criteria stored alongside an induced
+   * procedure (P2-2) so a reuse can *self-verify* its outcome instead of
+   * trusting the procedure blindly. Author-defined rules omit it.
+   */
+  readonly successCriteria?: ReadonlyArray<string>;
+  /**
+   * Trust-provenance tag (P1-4 / P2-2). Induced procedures are
+   * `'induction'`; author-defined rules omit it (treated first-party).
+   * See {@link MemoryProvenance}.
+   */
+  readonly provenance?: MemoryProvenance;
+  /**
+   * Retrieval-trust state (P1-4 / P2-2). Induced procedures land
+   * `'quarantined'` and are excluded from activation (they must not drive
+   * actions) until validated; author-defined rules omit it (treated
+   * `'active'`). See {@link MemoryStatus}.
+   */
+  readonly status?: MemoryStatus;
+  /**
+   * Demonstrated-success counter (MCON-2 part 4). Incremented by
+   * `ProceduralMemory.recordOutcome(...)` on each verified successful
+   * reuse; drives promotion-by-demonstrated-success for quarantined
+   * induced procedures once the configured threshold is reached.
+   * Absent ⇒ never counted (adapters without the column).
+   */
+  readonly successCount?: number;
+  /** Principal dimension (D3). `'agent'` on induced procedures. See {@link MemoryOwner}. */
+  readonly owner?: MemoryOwner;
+}
+
+/**
+ * Insight - a higher-order observation the consolidator's reflection
+ * pass (P1-1) synthesizes over recent memories ("the user has cancelled
+ * three evening plans this month - they may be overcommitted"). No
+ * single turn states it; it is *inferred*, so it is always
+ * `provenance: 'reflection'` and lands `status: 'quarantined'` (P1-4),
+ * excluded from action-driving recall until validated.
+ *
+ * Every insight carries **mandatory citations** (`cites`) - the ids of
+ * the supporting memories it was synthesized from - so a reader can
+ * trace it back to evidence; this is the "trustworthy reflection"
+ * mitigation against confirmation-bias loops. Insights are managed with
+ * an ExpeL-style salience counter (new insights start at `2`, pruned at
+ * `≤ 0`) and are retrieval-ranked **below** the primary facts they cite.
+ *
+ * Core defines only the record shape; the storage surface for insights
+ * is NOT part of the baseline {@link MemoryStore} contract - it lives in
+ * the optional `InsightMemoryStoreExt` exported from `@graphorin/memory`
+ * (W-048). Adapters without it simply have no insight tier.
+ *
+ * @stable
+ */
+export interface Insight extends MemoryRecord {
+  readonly kind: 'insight';
+  /** The synthesized higher-order observation. */
+  readonly text: string;
+  /**
+   * IDs of the supporting memories (facts / episodes) this insight was
+   * synthesized from. Always ≥ 1 - citations are mandatory; an insight
+   * with no traceable evidence is never persisted.
+   */
+  readonly cites: ReadonlyArray<string>;
+  /**
+   * ExpeL-style salience counter. New insights start at `2`; a
+   * maintenance pass up-/down-votes on subsequent corroboration /
+   * contradiction and prunes (soft-deletes) insights at `≤ 0`.
+   */
+  readonly salience: number;
+  /**
+   * Trust-provenance tag (P1-4). Reflection-synthesized insights are
+   * `'reflection'`. See {@link MemoryProvenance}.
+   */
+  readonly provenance?: MemoryProvenance;
+  /**
+   * Retrieval-trust state (P1-4). Insights land `'quarantined'`. See
+   * {@link MemoryStatus}.
+   */
+  readonly status?: MemoryStatus;
+  /** Principal dimension (D3). Reflection-synthesized insights are `'agent'`. */
+  readonly owner?: MemoryOwner;
+}
+
+/**
+ * Role a {@link GraphEntity} plays in a {@link Fact}'s s/p/o triple
+ * (P2-1) - the `subject` or the `object`. The `predicate` is a relation
+ * label, not an entity, so it has no role here.
+ *
+ * @stable
+ */
+export type EntityRole = 'subject' | 'object';
+
+/**
+ * Canonical entity in the lightweight in-SQLite relation graph (P2-1).
+ * The entity resolver (`@graphorin/memory`) deduplicates the raw
+ * `subject`/`object` strings on facts into canonical entities - merging
+ * aliases ("Anna", "Anna S.", "my sister") via lexical + embedding
+ * similarity (with optional LLM adjudication) - so multi-hop recall can
+ * traverse relationships instead of fragmenting them.
+ *
+ * Merges are **append-only and reversible**: a merged entity is never
+ * deleted - its {@link GraphEntity.mergedInto} points at the surviving
+ * canonical entity, every merge / unmerge is recorded in an audit
+ * ledger, and `mergedInto` is single-level (it always points directly at
+ * a root), so `mergedInto ?? id` is the canonical id.
+ *
+ * Core defines only the record shape; the storage surface for the graph
+ * (upsert / link / merge / one-hop expansion) is NOT part of the
+ * baseline {@link MemoryStore} contract - it lives in the optional
+ * `GraphMemoryStoreExt` exported from `@graphorin/memory` (W-048).
+ * Adapters without it simply have no relation graph.
+ *
+ * @stable
+ */
+export interface GraphEntity {
+  readonly id: string;
+  readonly userId: string;
+  /** Display name as first observed (the surface form that minted it). */
+  readonly name: string;
+  /** Case/space-folded key used for lexical dedup + the canonical unique index. */
+  readonly normalizedName: string;
+  /**
+   * Canonical pointer. `undefined` ⇒ this entity is itself a root.
+   * Otherwise it is the id of the surviving entity this one was merged
+   * into; single-level by construction, so `mergedInto ?? id` resolves
+   * the canonical id without a recursive walk.
+   */
+  readonly mergedInto?: string;
+  readonly createdAt: string;
+  readonly updatedAt?: string;
+}
+
+/**
+ * Search options shared across memory tiers.
+ *
+ * @stable
+ */
+export interface MemorySearchOptions {
+  readonly query: string;
+  readonly topK?: number;
+  readonly tags?: ReadonlyArray<string>;
+  readonly dateRange?: { readonly from?: string; readonly to?: string };
+  readonly includeArchived?: boolean;
+  /**
+   * Include quarantined memories in the result set (P1-4). Defaults to
+   * `false`: action-driving recall never returns quarantined rows. Set
+   * `true` only for the validation / inspector path - never for
+   * auto-recall fed back into the model.
+   */
+  readonly includeQuarantined?: boolean;
+  readonly signal?: AbortSignal;
+  /**
+   * Point-in-time ("as of") read. When set, only records whose
+   * validity interval contains this instant are returned. For facts:
+   * `(valid_from IS NULL OR valid_from <= asOf) AND (valid_to IS NULL OR valid_to > asOf)`;
+   * for episodes: `started_at <= asOf`. ISO-8601. Absent ⇒ fact reads
+   * evaluate validity at NOW (see {@link includeSuperseded}).
+   */
+  readonly asOf?: string;
+  /**
+   * Include superseded / validity-expired facts in the result set
+   * (memory-retrieval-01). Defaults to `false`: a default read behaves
+   * as `asOf = now`, so a fact whose `validTo` was closed (e.g. by
+   * `supersede`) never surfaces as current - exactly what the
+   * `fact_supersede` tool promises. Set `true` only for inspector /
+   * audit paths that need the full history. Ignored when an explicit
+   * {@link asOf} is supplied.
+   */
+  readonly includeSuperseded?: boolean;
+  /**
+   * Retrieval-time principal filter (D3). When set, only records whose
+   * owner is in the requested set match; rows written before the
+   * feature (owner absent) are treated as `'user'`. Absent ⇒ no owner
+   * filter - behaviour is unchanged.
+   */
+  readonly owner?: MemoryOwner | ReadonlyArray<MemoryOwner>;
+}
+
+/**
+ * A single retrieval hit with similarity / relevance metadata.
+ *
+ * @stable
+ */
+export interface MemoryHit<TRecord extends MemoryRecord = MemoryRecord> {
+  readonly record: TRecord;
+  readonly score: number;
+  /** Optional source signals contributing to `score` (BM25, vec, RRF, …). */
+  readonly signals?: Readonly<Record<string, number>>;
+}