@snoai/memory 0.0.0-stage → 1.0.1

package/dist/atomic-memory-extraction-d9EG-4ti.d.ts

@@ -0,0 +1,327 @@
+import { i as LlmClientConfig, l as ModelCallId, p as LlmRoutingConfig, r as LlmClient } from "./plugin-config-schema-C0UUbOmG.js";
+import { n as Locale } from "./locales-JxGmkG6t.js";
+import { qt as AdapterAMemoryView } from "./index-BO4RU_mc.js";
+import { C as MemoryStore, c as AtomicExtractionRunParameters, f as AtomicExtractionWriteResult, g as BeginAtomicExtractionChunkResult, r as AtomicExtractionLedgerKey, s as AtomicExtractionReprocessReason, x as MemoryRelationPredicate } from "./memory-store-base-CQ_bHlYA.js";
+import "./store-C8sUTssE.js";
+import "./llm-client-DOTSGzhe.js";
+import { z } from "zod";
+//#region src/engine/extraction/calendar-instruction.d.ts
+type CalendarPrecision = "year" | "month" | "week" | "day" | "minute";
+interface CalendarClock {
+  hour?: number;
+  minute?: number;
+  timezone?: string;
+}
+type CalendarInstruction = {
+  kind: "none";
+} | {
+  kind: "unresolved";
+} | ({
+  kind: "absolute";
+  year: number;
+  month?: number;
+  day?: number;
+  precision: CalendarPrecision;
+} & CalendarClock) | ({
+  kind: "relative";
+  amount: number;
+  unit: "year" | "month" | "week" | "day" | "hour" | "minute";
+  precision: CalendarPrecision;
+} & CalendarClock) | ({
+  kind: "weekday";
+  day_name: Weekday;
+  direction: "previous" | "next";
+  precision: "day" | "minute";
+} & CalendarClock);
+/** Day names in ISO order; the wire carries the name because models do not share one numbering. */
+declare const WEEKDAYS: readonly ["monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday"];
+type Weekday = (typeof WEEKDAYS)[number];
+interface CalendarResult {
+  year: number;
+  month: number;
+  day: number;
+  hour?: number;
+  minute?: number;
+  precision: CalendarPrecision;
+  timezone: string;
+  label: string;
+  from: number;
+  until: number;
+}
+//#endregion
+//#region src/engine/extraction/atomic-extraction-reply.d.ts
+type AtomicExtractionTurnRole = "system" | "user" | "assistant";
+interface AtomicExtractionTurn {
+  role: AtomicExtractionTurnRole;
+  content: string;
+}
+type AtomicExtractionResolvedTime = CalendarResult;
+interface AtomicExtractionSourceSpan {
+  turnIndex: number;
+  quote: string;
+}
+interface AtomicExtractionRelation {
+  subject: string;
+  predicate: string;
+  object: string;
+}
+interface AtomicExtractionRecord {
+  kind: "occurrence" | "standing";
+  claimText: string;
+  subject: string;
+  subjectKind: "user" | "agent" | "named_entity" | "unresolved";
+  attribute: string | null;
+  refusedAttribute?: string;
+  value: string;
+  temporalPhrase: string | null;
+  time: CalendarInstruction;
+  endedTime: CalendarInstruction;
+  /** Calculated only from a structured instruction, never from the phrase. */
+  resolvedTime: AtomicExtractionResolvedTime | null;
+  endsCurrent: boolean;
+  /** Source evidence for the ending; `endedTime` is the instruction used for calculation. */
+  endedAtPhrase: string | null;
+  endedAt: AtomicExtractionResolvedTime | null;
+  importance: "high" | "medium" | "low";
+  changesCurrentState: boolean;
+  todo: "open" | "done" | "removed" | "none";
+  closeReason: string | null;
+  sourceSpan: AtomicExtractionSourceSpan;
+  relations: AtomicExtractionRelation[];
+  singleClaim: boolean;
+  atomicSanitizerMatches?: string[];
+}
+//#endregion
+//#region src/engine/extraction/atomic-extraction-gauntlet.d.ts
+type AtomicExtractionDispositionReason = "compound" | "subject-unverified" | "subject-rejected";
+interface ResolvedAtomicExtractionSourceSpan extends AtomicExtractionSourceSpan {
+  startOffset: number;
+  endOffset: number;
+}
+interface AtomicGauntletRelation {
+  subject: string;
+  predicate: MemoryRelationPredicate;
+  object: string;
+}
+interface AtomicGauntletRecord extends Omit<AtomicExtractionRecord, "subject" | "attribute" | "sourceSpan" | "relations"> {
+  subject: string | null;
+  attribute: string | null;
+  sourceSpan: ResolvedAtomicExtractionSourceSpan | null;
+  relations: AtomicGauntletRelation[];
+  lane: "active" | "parked";
+  dispositionReason: AtomicExtractionDispositionReason | null;
+  resplit: boolean;
+  resplitFailure?: string;
+  resolvedTimeInvalid?: boolean;
+  /**
+   * The quote the model gave, kept ONLY when it could not be found in its turn.
+   *
+   * `sourceSpan` becomes null in that case and the quote is otherwise gone, so a parked row's
+   * replay record cannot say what failed to match — measured 2026-09-04, a dictated email
+   * produced seven well-formed records, all seven parked for an unresolved span, and every
+   * stored candidate read back as `QUOTE null`.
+   */
+  unresolvedSourceSpan?: AtomicExtractionSourceSpan;
+}
+interface AtomicResplitTransport {
+  resplit(input: {
+    records: readonly AtomicExtractionRecord[];
+    turns: readonly AtomicExtractionTurn[];
+  }): Promise<AtomicExtractionRecord[] | null>;
+}
+//#endregion
+//#region src/engine/extraction/atomic-profile-keying.d.ts
+interface AtomicProfileKeyingTransport {
+  keyTurn(input: {
+    turnIndex: number;
+    turn: AtomicExtractionTurn;
+    locale?: Locale;
+  }): Promise<AtomicExtractionRecord[] | null>;
+}
+interface AtomicKeyedRecord extends AtomicGauntletRecord {
+  category: "episodic" | "profile" | "state";
+  keyingNote?: "keying-unmatched" | "bare-base-grounded" | "keying-failed" | "keying-skipped:span-unresolvable";
+  baseProvenance?: Array<{
+    claimText: string;
+    sourceSpan: AtomicGauntletRecord["sourceSpan"];
+    relations: AtomicGauntletRecord["relations"];
+  }>;
+}
+//#endregion
+//#region src/engine/extraction/atomic-generic-extractor.d.ts
+interface AtomicGenericExtractionRequest {
+  callId: ModelCallId;
+  prompt: string;
+  maxTokens: number;
+  requestId?: string;
+}
+interface AtomicGenericExtractionCompletion {
+  text: string;
+  truncated: boolean;
+  outputTokens?: number;
+}
+interface AtomicGenericExtractionTransport {
+  complete(request: AtomicGenericExtractionRequest): Promise<AtomicGenericExtractionCompletion | null>;
+}
+type AtomicGenericExtractionResult = {
+  status: "complete";
+  records: AtomicExtractionRecord[];
+  progressTurns: ReadonlySet<number>;
+} | {
+  status: "pending";
+  reason: AtomicExtractionReprocessReason;
+} | {
+  status: "skip";
+  entry: BeginAtomicExtractionChunkResult["entry"];
+} | {
+  status: "off";
+};
+//#endregion
+//#region src/engine/extraction/atomic-subject-guard.d.ts
+interface AtomicSubjectGuardTransport {
+  repairMissingHalf(input: {
+    episode: AtomicKeyedRecord;
+    turn: AtomicExtractionTurn;
+    turns: readonly AtomicExtractionTurn[];
+    locale?: Locale;
+  }): Promise<AtomicExtractionRecord[] | null>;
+  guardUserSubjects(input: {
+    records: readonly AtomicKeyedRecord[];
+    locale?: Locale;
+  }): Promise<readonly (boolean | null)[] | null>;
+}
+//#endregion
+//#region src/engine/extraction/atomic-memory-extraction.d.ts
+/** One (older, newer) pair put to the conflict-adjudication adapter; its raw reply, or null. */
+interface AtomicRetirementVerdictTransport {
+  judge(pair: {
+    older: AdapterAMemoryView;
+    newer: AdapterAMemoryView;
+  }): Promise<string | null>;
+}
+interface AtomicMemoryExtractionTransports {
+  generic: AtomicGenericExtractionTransport;
+  profileKeying: AtomicProfileKeyingTransport;
+  resplit: AtomicResplitTransport;
+  subjectGuard: AtomicSubjectGuardTransport;
+  retirementVerdict: AtomicRetirementVerdictTransport;
+}
+interface RunAtomicMemoryExtractionInput {
+  diagnostics?: WindowDiagnostics;
+  writerAgentId?: string;
+  store: MemoryStore;
+  projectId: string;
+  ledgerKey: AtomicExtractionLedgerKey;
+  turns: readonly AtomicExtractionTurn[];
+  contextTurns?: readonly AtomicExtractionTurn[];
+  followingTurns?: readonly AtomicExtractionTurn[];
+  rawChunk: string;
+  routingSnapshotId: string;
+  runParameters: AtomicExtractionRunParameters;
+  estimatedInputTokens: number;
+  extractorVersion: string;
+  sessionDateTime: string;
+  sessionTimestampMs: number;
+  sessionTimezone: string;
+  sourceTurnOffset?: number;
+  admittedSourceTurnIndexes?: readonly number[];
+  /**
+   * Per global turn, the quote spans (character ranges of the turn) some record has already
+   * been written for: seeded from earlier passes of this conversation, and added to as each
+   * window writes. Windows write in order, and a window's slice reaches back over exactly the
+   * previous window's turns, so an entry can only ever be filled in by the window after the one
+   * that owns it. A span is the record's own evidence anchor; a record whose quote could not be
+   * placed in the turn claims the whole turn.
+   */
+  claimedSourceSpans?: Map<number, ClaimedFact[]>;
+  /**
+   * Per document family (`email`, `project`, `meeting`), the names this conversation has given
+   * it so far, each with the global turn it was stated at. Shared by the windows of one call.
+   */
+  documentNames?: Map<string, DocumentName[]>;
+  waitForDocumentNames?: () => Promise<void>;
+  onDocumentNamesSettled?: () => void;
+  onSubjectGuardSettled?: () => void;
+  waitForWriteTurn?: () => Promise<void>;
+  transports: AtomicMemoryExtractionTransports;
+  nowMs: () => number;
+  locale?: Locale;
+  requestId?: string;
+}
+/**
+ * The words one record claims on a turn, for the windows of ONE call. A quote the gauntlet placed
+ * claims its character range. A quote it could not place claims only itself, by its own words:
+ * sealing its whole turn would drop every other fact the turn states, and claiming nothing would
+ * let the next window write the same sentence again.
+ */
+/** One claim already made on a turn: the words it quotes, and the fact it states. */
+interface ClaimedFact {
+  readonly span: ClaimedSpan;
+  /** The model-extracted subject, attribute and value claimed by this record. */
+  readonly factKey: string | null;
+}
+type ClaimedSpan = {
+  readonly kind: "range";
+  readonly start: number;
+  readonly end: number;
+} | {
+  readonly kind: "quote";
+  readonly quote: string;
+};
+interface DocumentName {
+  turn: number;
+  name: string;
+}
+type AtomicMemoryExtractionResult = Exclude<AtomicGenericExtractionResult, {
+  status: "complete";
+}> | {
+  status: "complete";
+  records: AtomicKeyedRecord[];
+  write: AtomicExtractionWriteResult;
+};
+interface AtomicExtractPersistOptions {
+  scope?: string;
+  writerAgentId?: string;
+  sessionDateTime?: string;
+  sessionTimezone?: string;
+}
+interface AtomicExtractPersistResult {
+  created: number;
+  merged: 0;
+  skipped: number;
+  addressLessRefusedCount: 0;
+  todoTransitionsWithoutSourceCount: number;
+  llmFailures?: number;
+}
+interface AtomicInsightDistillerConfig {
+  defaultScope: string;
+  locale?: Locale;
+}
+interface WindowDiagnostics {
+  proposed: number;
+  parseRejected: number;
+  discarded: number;
+  unkeyed: number;
+  persisted: number;
+  suppressed: number;
+  modelMs: number;
+  writeMs: number;
+  outcome: string;
+  rowIds: string[];
+  reasons: Record<string, number>;
+  parked: number;
+}
+declare function createAtomicResplitTransport(llm: LlmClient, locale: Locale): AtomicResplitTransport;
+declare function createSignedAtomicMemoryExtractionTransports(config: Omit<LlmClientConfig, "routing"> & {
+  routing: LlmRoutingConfig;
+}, locale?: Locale): AtomicMemoryExtractionTransports;
+declare class AtomicInsightDistiller {
+  private readonly store;
+  private readonly transports;
+  private readonly config;
+  constructor(store: MemoryStore, transports: AtomicMemoryExtractionTransports, config: AtomicInsightDistillerConfig);
+  extractAndPersist(conversationText: string, sessionKey: string, options?: AtomicExtractPersistOptions): Promise<AtomicExtractPersistResult>;
+}
+declare function runAtomicMemoryExtraction(input: RunAtomicMemoryExtractionInput): Promise<AtomicMemoryExtractionResult>;
+//#endregion
+export { AtomicMemoryExtractionTransports as a, ClaimedSpan as c, createAtomicResplitTransport as d, createSignedAtomicMemoryExtractionTransports as f, AtomicMemoryExtractionResult as i, DocumentName as l, AtomicExtractPersistResult as n, AtomicRetirementVerdictTransport as o, runAtomicMemoryExtraction as p, AtomicInsightDistiller as r, ClaimedFact as s, AtomicExtractPersistOptions as t, RunAtomicMemoryExtractionInput as u };