@remnic/core 9.69.55 → 9.69.57

package/dist/temporal-index.d.ts

@@ -1 +1,230 @@
-export { I as INDEX_VERSION, T as TagIndex, a as TagNode, b as TemporalIndex, c as TemporalIndexCompatibilityMutation, d as TemporalIndexEntry, e as TemporalIndexEvent, f as addPathToSet, g as addTagGraphEntry, h as applyTagIndexCompatibilityMutation, i as applyTemporalIndexCompatibilityMutation, clearIndexes, j as clearIndexesAsync, k as deindexMemoriesBatchAsync, deindexMemory, l as deindexMemoryAsync, m as ensureStateDir, n as extractTagsFromPrompt, o as hasCurrentTemporalIndexSchemaForCompatibility, indexMemoriesBatch, p as indexMemoriesBatchAsync, indexMemory, q as indexMemoryAsync, indexesExist, r as indexesExistAsync, s as isTemporalQuery, t as isoDateFromTimestamp, u as queryByDateRangeAsync, v as queryByTagsAsync, w as queryTemporalTimelineAsync, x as readIndexSnapshotAsync, y as recencyWindowBoundsFromPrompt, z as recencyWindowFromPrompt, A as removePathFromAllSets, B as removePathFromAllTagEntries, C as removePathFromSet, D as removeTagGraphEntry, E as resolvePromptTagPrefilterAsync, F as setIndexReadObserverForTest, G as setIndexWriteFailureForTest, H as setIndexWriteObserverForTest, J as temporalEventFromEntry, K as updateTagIndex, L as updateTemporalIndex, M as withMemoryDirMutex } from './temporal-index-compat.js';
+/**
+ * Temporal and Tag Indexes (v8.1 — SwiftMem-inspired)
+ *
+ * Maintains two fast on-disk lookup structures in `state/`:
+ *   index_time.json — maps YYYY-MM-DD date buckets to memory file paths
+ *   index_tags.json — maps tag strings to memory file paths
+ *
+ * Used as an optional prefilter in the retrieval pipeline:
+ * given a time range or a set of tags, narrow the candidate set
+ * before the QMD hybrid search so we can pass a smaller pool to scoring.
+ *
+ * Design constraints:
+ * - Must be fail-open (any error returns empty / unfiltered)
+ * - Reads/writes are batched per extraction run
+ * - Both indexes are plain JSON; no external dependencies
+ */
+export { clearIndexes, deindexMemory, indexMemoriesBatch, indexMemory, indexesExist, } from "./temporal-index-compat.js";
+export { deindexMemoriesBatchAsync, indexMemoriesBatchAsync, } from "./temporal-index-batch.js";
+export interface TemporalIndex {
+    /** version bumped when schema changes */
+    version: number;
+    /** Last full rebuild timestamp (ISO string) */
+    lastRebuildAt?: string;
+    /** Map from YYYY-MM-DD → array of memory paths */
+    dates: Record<string, string[]>;
+    /**
+     * Per-memory event-time rows used to reconstruct one chronology across
+     * source sessions. Keyed by path so an update replaces the prior row.
+     */
+    events: Record<string, TemporalIndexEvent>;
+}
+export interface TemporalIndexEvent {
+    path: string;
+    /** Event/valid time used for chronology. */
+    eventAt: string;
+    /** Ingest/source-observation time, when known. */
+    observedAt?: string;
+    /** Source session provenance, when the extractor recorded it. */
+    sessionKey?: string;
+    /** Exclusive validity end, when the event is bounded. */
+    validUntil?: string;
+    /** SHA-256 lexical fingerprints for bounded query-aware candidate selection. */
+    searchTokenHashes?: string[];
+}
+export interface TemporalIndexEntry {
+    path: string;
+    createdAt: string;
+    tags: string[];
+    validAt?: string;
+    observedAt?: string;
+    sessionKey?: string;
+    validUntil?: string;
+    /** Used only to derive token hashes; raw text is never persisted in the index. */
+    searchText?: string;
+}
+export interface TagIndex {
+    version: number;
+    lastRebuildAt?: string;
+    /** Map from canonical tag string → node metadata */
+    tags: Record<string, TagNode | string[]>;
+    /** Map from alias string → canonical tags */
+    aliases?: Record<string, string[]>;
+}
+export interface TagNode {
+    paths: string[];
+    aliases?: string[];
+    parents?: string[];
+}
+export declare const INDEX_VERSION = 2;
+/** Test-only observer for asserting cache read/parse behavior. */
+export declare function setIndexReadObserverForTest(observer?: () => void): void;
+/** Test-only observer fired once per committed atomic index write. */
+export declare function setIndexWriteObserverForTest(observer?: (filePath: string) => void): void;
+/**
+ * Test-only hook to deterministically fail an atomic index write for matching
+ * paths. Return true to fail the write for a given path. Lets partial-failure
+ * branches be exercised without relying on filesystem permissions, which no-op
+ * for privileged users (common in containerized CI) and differ on Windows.
+ */
+export declare function setIndexWriteFailureForTest(shouldFail?: (filePath: string) => boolean): void;
+export declare function ensureStateDir(memoryDir: string): Promise<void>;
+/**
+ * Operation-level mutex keyed by memoryDir (issue #1911, Codex Medium). Wraps a
+ * whole logical index mutation (which writes BOTH the temporal and tag index
+ * files) so overlapping mutators on the same memoryDir cannot interleave their
+ * per-file writes and commit mismatched halves. The inner per-file writeChains
+ * still protect each file; this outer chain just orders complete operations.
+ */
+export declare function withMemoryDirMutex<T>(memoryDir: string, op: () => Promise<T>): Promise<T>;
+export declare function updateTemporalIndex(memoryDir: string, update: (index: TemporalIndex) => void): Promise<boolean>;
+export declare function updateTagIndex(memoryDir: string, update: (index: TagIndex) => void): Promise<void>;
+export declare function isoDateFromTimestamp(isoString: string): string;
+export declare function temporalEventFromEntry(entry: TemporalIndexEntry): TemporalIndexEvent;
+export declare function addPathToSet(record: Record<string, string[]>, key: string, p: string): void;
+export declare function removePathFromSet(record: Record<string, string[]>, key: string, p: string): void;
+export declare function removePathFromAllSets(record: Record<string, string[]>, p: string): void;
+export declare function addTagGraphEntry(index: TagIndex, rawTag: string, memoryPath: string): void;
+export declare function removeTagGraphEntry(index: TagIndex, rawTag: string, memoryPath: string): void;
+export declare function removePathFromAllTagEntries(index: TagIndex, memoryPath: string): void;
+export type TemporalIndexCompatibilityMutation = {
+    kind: "index";
+    entries: TemporalIndexEntry[];
+} | {
+    kind: "deindex";
+    entries: TemporalIndexEntry[];
+} | {
+    kind: "clear";
+};
+/** @internal Pure model shared by the deprecated synchronous compatibility surface. */
+export declare function applyTemporalIndexCompatibilityMutation(raw: unknown, mutation: TemporalIndexCompatibilityMutation): TemporalIndex;
+/** @internal Pure model shared by the deprecated synchronous compatibility surface. */
+export declare function applyTagIndexCompatibilityMutation(raw: unknown, mutation: TemporalIndexCompatibilityMutation): TagIndex;
+/** @internal Schema check shared by the deprecated synchronous compatibility surface. */
+export declare function hasCurrentTemporalIndexSchemaForCompatibility(raw: unknown): boolean;
+/**
+ * Add (or update) a memory file in both indexes.
+ *
+ * @param memoryDir Root memory directory
+ * @param memoryPath Absolute path to the memory file
+ * @param createdAt ISO timestamp of the memory's creation date
+ * @param tags Array of tag strings from the memory's frontmatter
+ */
+export declare function indexMemoryAsync(memoryDir: string, memoryPath: string, createdAt: string, tags: string[], temporal?: Omit<Partial<TemporalIndexEntry>, "path" | "createdAt" | "tags">): Promise<void>;
+/**
+ * Remove a memory file from both indexes (called on deletion/archival).
+ */
+export declare function deindexMemoryAsync(memoryDir: string, memoryPath: string, createdAt: string, tags: string[]): Promise<void>;
+/**
+ * Reset both index files to empty state.
+ * Called before a full-corpus rebuild so stale paths in any surviving index
+ * file do not persist after the rebuild completes.
+ */
+export declare function clearIndexesAsync(memoryDir: string): Promise<void>;
+/**
+ * Returns true when both index files exist on disk.
+ * Used to detect first-time enablement so callers can trigger a full rebuild.
+ */
+export declare function indexesExistAsync(memoryDir: string): Promise<boolean>;
+/**
+ * Return the set of memory paths whose index date falls in [fromDate, toDate).
+ *
+ * Boundary semantics (exclusive upper bound):
+ * - `fromDate` is INCLUSIVE — entries on this date ARE returned.
+ * - `toDate`   is EXCLUSIVE — entries on this date are NOT returned.
+ *   Pass `recencyWindowBoundsFromPrompt(query).toDate` to get the correct
+ *   exclusive boundary; do NOT add +1 day yourself.
+ * - Default `toDate` = tomorrow, so omitting it includes all of today.
+ *
+ * @param memoryDir - root memory directory (contains state/index_time.json)
+ * @param fromDate  - inclusive start date, YYYY-MM-DD
+ * @param toDate    - exclusive end date, YYYY-MM-DD (default: tomorrow)
+ * @returns Set of matching file paths, or null if the index is unavailable.
+ */
+export declare function queryByDateRangeAsync(memoryDir: string, fromDate: string, toDate?: string): Promise<Set<string> | null>;
+/**
+ * Return the persisted event-time rows as one deterministic cross-session
+ * chronology. Equal event times are ordered by observation time, then path.
+ * Returns `null` when the index is missing, corrupt, or from an older schema;
+ * callers can then fail open to the pre-index recall path.
+ */
+export declare function queryTemporalTimelineAsync(memoryDir: string, options?: {
+    query?: string;
+    limit?: number;
+}): Promise<TemporalIndexEvent[] | null>;
+/**
+ * Async version of queryByTags — uses non-blocking fs.promises.readFile
+ * to avoid blocking the Node.js event loop.
+ */
+export declare function queryByTagsAsync(memoryDir: string, tags: string[]): Promise<Set<string> | null>;
+/**
+ * Extract tags from a prompt for tag-based prefiltering.
+ * Looks for hashtag-style tokens (#foo).
+ * Returns lowercase, deduplicated list.
+ */
+export declare function extractTagsFromPrompt(prompt: string): string[];
+export declare function resolvePromptTagPrefilterAsync(memoryDir: string, prompt: string): Promise<{
+    matchedTags: string[];
+    expandedTags: string[];
+    paths: Set<string> | null;
+}>;
+/**
+ * Run a group of index reads as ONE consistent snapshot (issue #1911, Codex
+ * Medium). The `read` callback executes inside a single withMemoryDirMutex
+ * acquisition — the same in-memory op-lock every async mutator holds across its
+ * paired temporal+tag writes — so no mutation can land between the reads inside
+ * it. A recall that reads the temporal and tag indexes together therefore never
+ * observes a half-updated state (e.g. a new temporal row with a not-yet-written
+ * tag membership) that would let prefiltering drop the current memory. The
+ * genuine-tag-miss contract is preserved: a truly absent tag still yields an
+ * empty set, only now never as a transient artifact of an in-flight write.
+ * Index reads are cache-backed (microseconds), so ordering them on the op-chain
+ * is negligible beside the multi-second QMD phase.
+ */
+export declare function readIndexSnapshotAsync<T>(memoryDir: string, read: () => Promise<T>): Promise<T>;
+/**
+ * Detect if a prompt is time-sensitive (mentions specific time references).
+ * Used to decide whether to activate the temporal prefilter.
+ */
+export declare function isTemporalQuery(prompt: string): boolean;
+/**
+ * Compute a "from date" string (YYYY-MM-DD) for a recency-based temporal query.
+ * For "recent" / "lately" returns 7 days ago; for today/yesterday the obvious window.
+ */
+export declare function recencyWindowFromPrompt(prompt: string, nowMs?: number): string;
+/**
+ * Returns both the start and end of the temporal window implied by the prompt.
+ *
+ * `fromDate` is computed by delegating to `recencyWindowFromPrompt`, so the two
+ * functions cannot diverge on the lower bound.  `toDate` is computed independently
+ * here using the same pattern-priority ordering, because the upper-bound arithmetic
+ * differs (exclusive end vs. inclusive start) and would not be expressible as a
+ * simple wrapper.
+ *
+ * Known divergence to be aware of: for "N hours ago", `recencyWindowFromPrompt`
+ * uses `Math.max(1, Math.ceil(hours/24))` days back, so `fromDate` = yesterday for
+ * sub-24h values.  `toDate` here is always `tomorrow` when no explicit date is
+ * specified (see the `toDaysBack === 0` branch), giving a 2-day window.  This is
+ * intentional — the window must cover both yesterday and today for recent hour-level
+ * queries.  Any fix to the hours formula in `recencyWindowFromPrompt` must be
+ * manually reflected here.
+ *
+ * - `fromDate`: first day of the implied window (same as `recencyWindowFromPrompt`)
+ * - `toDate`: first day NOT in the window (exclusive upper bound), so callers
+ *   should filter with `date >= fromDate && date < toDate`.
+ */
+export declare function recencyWindowBoundsFromPrompt(prompt: string, nowMs?: number): {
+    fromDate: string;
+    toDate: string;
+};
+//# sourceMappingURL=temporal-index.d.ts.map

package/dist/temporal-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"temporal-index.d.ts","sourceRoot":"","sources":["../src/temporal-index.ts"],"names":[],"mappings":"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"}

package/dist/temporal-supersession.d.ts

@@ -1,23 +1,3 @@
-import { M as MemoryFile, m as MemoryFrontmatter, K as MemoryLifecycleEvent } from './types-Du6VdoAg.js';
-import { D as DependencyPropagationDeliveryPort } from './dependency-propagation-delivery-BrhPjAHQ.js';
-import './message-parts/index.js';
-import './bounded-jsonl-state.js';
-import './operator-doctor-types.js';
-import './external-wiki-config.js';
-import './recall-state-view.js';
-import './contradiction-config.js';
-import './graph-path-scoring-config.js';
-import './background-generation-config.js';
-import './deep-recall-config.js';
-import './recall-navigation-config.js';
-import './recall-recognition-tier.js';
-import './causal-trajectory.js';
-import './objective-state.js';
-import './active-context-config.js';
-import './local-llm-config.js';
-import './semantic-merge-config.js';
-import './types-continuity.js';
-
 /**
  * Temporal Supersession (issue #375)
  *
@@ -32,8 +12,9 @@ import './types-continuity.js';
  * cached `readAllMemories()` path so cost is amortized with the rest of the
  * write pipeline.
  */
-
-interface TemporalSupersessionStorage {
+import type { MemoryFile, MemoryFrontmatter, MemoryLifecycleEvent } from "./types.js";
+import type { DependencyPropagationDeliveryPort } from "./orchestration/dependency-propagation-delivery.js";
+export interface TemporalSupersessionStorage {
     readAllMemories(): Promise<MemoryFile[]>;
     readAllColdMemories(): Promise<MemoryFile[]>;
     readMemoryByPath(memoryPath: string): Promise<MemoryFile | null>;
@@ -80,7 +61,7 @@ interface TemporalSupersessionStorage {
  *
  * Exported so external tests can verify the canonical form.
  */
-declare function normalizeSupersessionKey(raw: string): string;
+export declare function normalizeSupersessionKey(raw: string): string;
 /**
  * Stable supersession key for an (entityRef, attributeName) pair.
  *
@@ -91,12 +72,12 @@ declare function normalizeSupersessionKey(raw: string): string;
  *
  * Exported so tests and tools can recompute it without depending on storage.
  */
-declare function computeSupersessionKey(entityRef: string | undefined, attributeName: string): string | null;
+export declare function computeSupersessionKey(entityRef: string | undefined, attributeName: string): string | null;
 /**
  * Compute the full set of supersession keys for a fact with structured
  * attributes.  Returns an empty array if no keys can be derived.
  */
-declare function supersessionKeysForFact(spec: {
+export declare function supersessionKeysForFact(spec: {
     entityRef?: string;
     structuredAttributes?: Record<string, string>;
 }): string[];
@@ -110,7 +91,7 @@ declare function supersessionKeysForFact(spec: {
  *
  * The storage format is NOT changed — we only normalize at lookup time.
  */
-declare function lookupAttributeByNormalizedKey(attributes: Record<string, unknown>, rawKey: string): unknown;
+export declare function lookupAttributeByNormalizedKey(attributes: Record<string, unknown>, rawKey: string): unknown;
 /**
  * Decide whether an existing memory should be superseded by a newly-written
  * memory that carries the supplied supersession key set.
@@ -125,7 +106,7 @@ declare function lookupAttributeByNormalizedKey(attributes: Record<string, unkno
  * changed — if fact A sets `{city: Austin, tool: vim}` and fact B sets
  * `{city: NYC}`, only the city attribute is superseded, not the tool.
  */
-declare function shouldSupersedeExisting(args: {
+export declare function shouldSupersedeExisting(args: {
     candidate: MemoryFrontmatter;
     newEntityRef: string;
     newAttributes: Record<string, string>;
@@ -134,19 +115,19 @@ declare function shouldSupersedeExisting(args: {
 }): {
     matchedKeys: string[];
 } | null;
-interface TemporalSupersessionMutation {
+export interface TemporalSupersessionMutation {
     supersededAt: string;
     invalidAt?: string;
     matchedKeys: string[];
 }
-declare function applyTemporalSupersessionPrimaryMutation(args: {
+export declare function applyTemporalSupersessionPrimaryMutation(args: {
     storage: TemporalSupersessionStorage;
     oldMemory: MemoryFile;
     replacementId: string;
     mutation: TemporalSupersessionMutation;
     allCandidates?: MemoryFile[];
 }): Promise<boolean>;
-interface TemporalSupersessionResult {
+export interface TemporalSupersessionResult {
     supersededIds: string[];
     matchedKeys: string[];
 }
@@ -155,7 +136,7 @@ interface TemporalSupersessionResult {
  * just-written memory.  Fails open on I/O errors — the new memory is already
  * on disk, and supersession is a best-effort hygiene step.
  */
-declare function applyTemporalSupersession(args: {
+export declare function applyTemporalSupersession(args: {
     storage: TemporalSupersessionStorage;
     newMemoryId: string;
     entityRef?: string;
@@ -181,9 +162,8 @@ declare function applyTemporalSupersession(args: {
  * `includeInRecall` is true, this always returns false (the fact is kept),
  * matching the audit/history opt-in described in the config.
  */
-declare function shouldFilterSupersededFromRecall(frontmatter: MemoryFrontmatter, options: {
+export declare function shouldFilterSupersededFromRecall(frontmatter: MemoryFrontmatter, options: {
     enabled: boolean;
     includeInRecall: boolean;
 }): boolean;
-
-export { type TemporalSupersessionMutation, type TemporalSupersessionResult, type TemporalSupersessionStorage, applyTemporalSupersession, applyTemporalSupersessionPrimaryMutation, computeSupersessionKey, lookupAttributeByNormalizedKey, normalizeSupersessionKey, shouldFilterSupersededFromRecall, shouldSupersedeExisting, supersessionKeysForFact };
+//# sourceMappingURL=temporal-supersession.d.ts.map

package/dist/temporal-supersession.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"temporal-supersession.d.ts","sourceRoot":"","sources":["../src/temporal-supersession.ts"],"names":[],"mappings":"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"}

package/dist/temporal-timeline-recall.d.ts

@@ -1,30 +1,12 @@
-import { M as MemoryFile } from './types-Du6VdoAg.js';
-import './message-parts/index.js';
-import './bounded-jsonl-state.js';
-import './operator-doctor-types.js';
-import './external-wiki-config.js';
-import './recall-state-view.js';
-import './contradiction-config.js';
-import './graph-path-scoring-config.js';
-import './background-generation-config.js';
-import './deep-recall-config.js';
-import './recall-navigation-config.js';
-import './recall-recognition-tier.js';
-import './causal-trajectory.js';
-import './objective-state.js';
-import './active-context-config.js';
-import './local-llm-config.js';
-import './semantic-merge-config.js';
-import './types-continuity.js';
-
-interface TemporalTimelineRecallItem {
+import type { MemoryFile } from "./types.js";
+export interface TemporalTimelineRecallItem {
     memory: MemoryFile;
     eventAt: string;
     observedAt?: string;
     sessionKey?: string;
     validUntil?: string;
 }
-interface TemporalTimelineRecallOptions {
+export interface TemporalTimelineRecallOptions {
     items: readonly TemporalTimelineRecallItem[];
     query: string;
     maxChars: number;
@@ -37,6 +19,5 @@ interface TemporalTimelineRecallOptions {
  * Build a query-focused timeline from ingest-indexed memory primitives.
  * Selection is relevance-first; presentation is always event-time ordered.
  */
-declare function buildTemporalTimelineRecallSection(options: TemporalTimelineRecallOptions): string;
-
-export { type TemporalTimelineRecallItem, type TemporalTimelineRecallOptions, buildTemporalTimelineRecallSection };
+export declare function buildTemporalTimelineRecallSection(options: TemporalTimelineRecallOptions): string;
+//# sourceMappingURL=temporal-timeline-recall.d.ts.map

package/dist/temporal-timeline-recall.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"temporal-timeline-recall.d.ts","sourceRoot":"","sources":["../src/temporal-timeline-recall.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,UAAU,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,6BAA6B;IAC5C,KAAK,EAAE,SAAS,0BAA0B,EAAE,CAAC;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AA4CD;;;GAGG;AACH,wBAAgB,kCAAkC,CAChD,OAAO,EAAE,6BAA6B,GACrC,MAAM,CAoDR"}

package/dist/temporal-validity.d.ts

@@ -1,22 +1,3 @@
-import { m as MemoryFrontmatter } from './types-Du6VdoAg.js';
-import './message-parts/index.js';
-import './bounded-jsonl-state.js';
-import './operator-doctor-types.js';
-import './external-wiki-config.js';
-import './recall-state-view.js';
-import './contradiction-config.js';
-import './graph-path-scoring-config.js';
-import './background-generation-config.js';
-import './deep-recall-config.js';
-import './recall-navigation-config.js';
-import './recall-recognition-tier.js';
-import './causal-trajectory.js';
-import './objective-state.js';
-import './active-context-config.js';
-import './local-llm-config.js';
-import './semantic-merge-config.js';
-import './types-continuity.js';
-
 /**
  * Temporal validity helpers (issue #680).
  *
@@ -43,9 +24,9 @@ import './types-continuity.js';
  * model — at the instant a successor's `valid_at` fires, the predecessor
  * is no longer authoritative.
  */
-
-declare function effectiveValidAt(fm: Pick<MemoryFrontmatter, "valid_at" | "created">): string;
-declare function effectiveInvalidAt(fm: Pick<MemoryFrontmatter, "invalid_at" | "supersededAt" | "status">): string | undefined;
+import type { MemoryFrontmatter } from "./types.js";
+export declare function effectiveValidAt(fm: Pick<MemoryFrontmatter, "valid_at" | "created">): string;
+export declare function effectiveInvalidAt(fm: Pick<MemoryFrontmatter, "invalid_at" | "supersededAt" | "status">): string | undefined;
 /**
  * Returns true when the fact was authoritative at `asOfMs` (parsed
  * milliseconds since epoch).  Half-open semantics: a fact is valid in
@@ -57,7 +38,7 @@ declare function effectiveInvalidAt(fm: Pick<MemoryFrontmatter, "invalid_at" | "
  * the historical filter (CLAUDE.md gotcha #34: distinguish empty from
  * malformed).
  */
-declare function isValidAsOf(fm: Pick<MemoryFrontmatter, "valid_at" | "invalid_at" | "created" | "supersededAt" | "status" | "eventTimeSource">, asOfMs: number): boolean;
+export declare function isValidAsOf(fm: Pick<MemoryFrontmatter, "valid_at" | "invalid_at" | "created" | "supersededAt" | "status" | "eventTimeSource">, asOfMs: number): boolean;
 /**
  * Bi-temporal injection filter (issue #1578).
  *
@@ -77,13 +58,12 @@ declare function isValidAsOf(fm: Pick<MemoryFrontmatter, "valid_at" | "invalid_a
  * still be validity-valid within its historical window (issue pitfall: the
  * filter is status-orthogonal).
  */
-declare function isValidityExpiredNow(fm: Pick<MemoryFrontmatter, "invalid_at">, nowMs: number): boolean;
+export declare function isValidityExpiredNow(fm: Pick<MemoryFrontmatter, "invalid_at">, nowMs: number): boolean;
 /**
  * Parse and validate an `as_of` value supplied at an input boundary
  * (CLI flag, HTTP query param, MCP field).  Returns parsed milliseconds
  * on success; throws a `RangeError` with a helpful message on malformed
  * input.  CLAUDE.md rule 51 — never silently default invalid input.
  */
-declare function parseAsOfTimestamp(raw: unknown): number;
-
-export { effectiveInvalidAt, effectiveValidAt, isValidAsOf, isValidityExpiredNow, parseAsOfTimestamp };
+export declare function parseAsOfTimestamp(raw: unknown): number;
+//# sourceMappingURL=temporal-validity.d.ts.map

package/dist/temporal-validity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"temporal-validity.d.ts","sourceRoot":"","sources":["../src/temporal-validity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,IAAI,CAAC,iBAAiB,EAAE,UAAU,GAAG,SAAS,CAAC,GAAG,MAAM,CAO5F;AAED,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,IAAI,CAAC,iBAAiB,EAAE,YAAY,GAAG,cAAc,GAAG,QAAQ,CAAC,GACpE,MAAM,GAAG,SAAS,CA6BpB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CACzB,EAAE,EAAE,IAAI,CACN,iBAAiB,EACf,UAAU,GACV,YAAY,GACZ,SAAS,GACT,cAAc,GACd,QAAQ,GACR,iBAAiB,CACpB,EACD,MAAM,EAAE,MAAM,GACb,OAAO,CAgCT;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,IAAI,CAAC,iBAAiB,EAAE,YAAY,CAAC,EACzC,KAAK,EAAE,MAAM,GACZ,OAAO,CAUT;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAavD"}

package/dist/testing/lifecycle-matrix.d.ts

@@ -21,12 +21,12 @@
  * keeps the builtin specifier, and runtime code must never import this module.
  */
 /** The nine canonical AGENTS.md session/retrieval/cache matrix rows. */
-type MatrixRowId = "explicit-provider-identity" | "sparse-metadata-with-binding" | "sparse-metadata-without-binding" | "provider-rebinding" | "restart-reload-recovery" | "compaction-flush" | "before-reset" | "session-end" | "dedupe-replay";
+export type MatrixRowId = "explicit-provider-identity" | "sparse-metadata-with-binding" | "sparse-metadata-without-binding" | "provider-rebinding" | "restart-reload-recovery" | "compaction-flush" | "before-reset" | "session-end" | "dedupe-replay";
 /**
  * Typed scenario axes a subject can branch on instead of re-parsing the row
  * id. These encode the real dimensions the AGENTS.md matrix probes.
  */
-interface MatrixRowDimensions {
+export interface MatrixRowDimensions {
     /** How the session's provider/identity binding is established. */
     readonly providerIdentity: "explicit" | "sparse" | "rebound" | "none";
     /** Whether a previously remembered binding is available to reuse. */
@@ -38,7 +38,7 @@ interface MatrixRowDimensions {
     /** Whether the scenario replays/duplicates content through the dedupe path. */
     readonly dedupeOrReplay: boolean;
 }
-interface MatrixRow {
+export interface MatrixRow {
     readonly id: MatrixRowId;
     /** Human-readable row title (matches the AGENTS.md bullet). */
     readonly title: string;
@@ -49,7 +49,7 @@ interface MatrixRow {
  * "Minimum scenario matrix for session/retrieval/cache work". Frozen so an
  * adopter cannot mutate the shared set.
  */
-declare const MATRIX_ROWS: readonly MatrixRow[];
+export declare const MATRIX_ROWS: readonly MatrixRow[];
 /**
  * A subsystem adapter. Each row runs `setup → exercise → invariants`. `setup`
  * is transactional — it cleans up its own partial state if it throws — and once
@@ -61,7 +61,7 @@ declare const MATRIX_ROWS: readonly MatrixRow[];
  * reason from `appliesTo` and the harness registers it as an explicit skipped
  * test (a mock-only pass is a finding about the code, not the harness — #1993).
  */
-interface LifecycleSubject<S> {
+export interface LifecycleSubject<S> {
     /** Build the row-specific fixture; MUST clean up its own partial state if it throws. */
     setup(row: MatrixRow): Promise<S>;
     /** Drive the behavior under test. */
@@ -78,9 +78,9 @@ interface LifecycleSubject<S> {
     appliesTo?(row: MatrixRow): boolean | string;
 }
 /** Minimal test registrar seam (defaults to `node:test`), injectable for self-test. */
-type MatrixTestRegistrar = (name: string, fn: () => void | Promise<void>) => void;
-type MatrixSkipRegistrar = (name: string, reason: string) => void;
-interface RunLifecycleMatrixOptions {
+export type MatrixTestRegistrar = (name: string, fn: () => void | Promise<void>) => void;
+export type MatrixSkipRegistrar = (name: string, reason: string) => void;
+export interface RunLifecycleMatrixOptions {
     /** Override the test registrar (self-test injects a capturing fake). */
     readonly register?: MatrixTestRegistrar;
     /** Override the skip registrar. */
@@ -89,12 +89,11 @@ interface RunLifecycleMatrixOptions {
     readonly rows?: readonly MatrixRow[];
 }
 /** Deterministic, greppable test name — the coverage manifest and CI depend on it. */
-declare function lifecycleTestName(subjectName: string, row: MatrixRow): string;
+export declare function lifecycleTestName(subjectName: string, row: MatrixRow): string;
 /**
  * Register one test per matrix row for `subject`, named with the row identity
  * so a failing row is unambiguous in CI output. Runs `setup → exercise →
  * invariants`; `teardown` runs whenever `setup` produced a fixture.
  */
-declare function runLifecycleMatrix<S>(subjectName: string, subject: LifecycleSubject<S>, options?: RunLifecycleMatrixOptions): void;
-
-export { type LifecycleSubject, MATRIX_ROWS, type MatrixRow, type MatrixRowDimensions, type MatrixRowId, type MatrixSkipRegistrar, type MatrixTestRegistrar, type RunLifecycleMatrixOptions, lifecycleTestName, runLifecycleMatrix };
+export declare function runLifecycleMatrix<S>(subjectName: string, subject: LifecycleSubject<S>, options?: RunLifecycleMatrixOptions): void;
+//# sourceMappingURL=lifecycle-matrix.d.ts.map

package/dist/testing/lifecycle-matrix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-matrix.d.ts","sourceRoot":"","sources":["../../src/testing/lifecycle-matrix.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,wEAAwE;AACxE,MAAM,MAAM,WAAW,GACnB,4BAA4B,GAC5B,8BAA8B,GAC9B,iCAAiC,GACjC,oBAAoB,GACpB,yBAAyB,GACzB,kBAAkB,GAClB,cAAc,GACd,aAAa,GACb,eAAe,CAAC;AAEpB;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,kEAAkE;IAClE,QAAQ,CAAC,gBAAgB,EAAE,UAAU,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;IACtE,qEAAqE;IACrE,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC;IACpC,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,gEAAgE;IAChE,QAAQ,CAAC,KAAK,EAAE,cAAc,GAAG,aAAa,GAAG,YAAY,GAAG,MAAM,CAAC;IACvE,+EAA+E;IAC/E,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;CAClC;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,EAAE,WAAW,CAAC;IACzB,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,mBAAmB,CAAC;CAC1C;AAED;;;;GAIG;AACH,eAAO,MAAM,WAAW,EAAE,SAAS,SAAS,EAoGjC,CAAC;AAEZ;;;;;;;;;;GAUG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC;IACjC,wFAAwF;IACxF,KAAK,CAAC,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAClC,qCAAqC;IACrC,QAAQ,CAAC,OAAO,EAAE,CAAC,EAAE,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,0DAA0D;IAC1D,UAAU,CAAC,OAAO,EAAE,CAAC,EAAE,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,0BAA0B;IAC1B,QAAQ,CAAC,OAAO,EAAE,CAAC,EAAE,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD;;;;OAIG;IACH,SAAS,CAAC,CAAC,GAAG,EAAE,SAAS,GAAG,OAAO,GAAG,MAAM,CAAC;CAC9C;AAED,uFAAuF;AACvF,MAAM,MAAM,mBAAmB,GAAG,CAChC,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAC3B,IAAI,CAAC;AAEV,MAAM,MAAM,mBAAmB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;AAEzE,MAAM,WAAW,yBAAyB;IACxC,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IACxC,mCAAmC;IACnC,QAAQ,CAAC,eAAe,CAAC,EAAE,mBAAmB,CAAC;IAC/C,kFAAkF;IAClF,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;CACtC;AAED,sFAAsF;AACtF,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,GAAG,MAAM,CAE7E;AAoBD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC5B,OAAO,GAAE,yBAA8B,GACtC,IAAI,CAmCN"}

package/dist/testing/orchestrator-lite.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Orchestrator-lite test fixtures for the lifecycle scenario-matrix harness
+ * (issue #1993). These helpers are lifted in spirit from the entity-hardening
+ * characterization suite (tests/orchestrator-characterization.test.ts) so the
+ * matrix rows exercise the REAL orchestrator paths — offline-safe config, temp
+ * memoryDir, field-level extraction stub (never a production hook), and the
+ * on-disk assertion helpers — rather than reinventing (or mocking) them.
+ *
+ * Test-support only (lives under src/testing/, never bundled, never exported).
+ */
+import { type AbstractionNodeStoreStatus } from "../abstraction-nodes.js";
+import type { Orchestrator } from "../orchestrator.js";
+import type { ExtractionRunCoordinatorDeps } from "../orchestration/extraction-run.js";
+import type { BufferTurn, ExtractionResult, PluginConfig } from "../types.js";
+/**
+ * Offline-safe config: QMD off, embedding fallback off, planner off (so the
+ * deterministic filesystem recall scan runs), extraction thresholds floored so
+ * single short turns are extractable, consolidation pushed far out, and the
+ * init gate floored so a recall() that never ran initialize() does not block.
+ * Mirrors tests/orchestrator-characterization.test.ts:makeConfig.
+ */
+export declare function makeLifecycleConfig(memoryDir: string, overrides?: Record<string, unknown>): PluginConfig;
+/** Enable the production harmonic-construction persistence path for a lifecycle row. */
+export declare function makeHarmonicLifecycleConfig(memoryDir: string, overrides?: Record<string, unknown>): PluginConfig;
+/** Read and validate abstraction nodes written by the production store path. */
+export declare function harmonicNodeStoreStatus(memoryDir: string, abstractionNodeStoreDir?: string): Promise<AbstractionNodeStoreStatus>;
+/** Create a fresh temp memory dir with a stable `remnic-lifecycle-<label>-` prefix. */
+export declare function mkTempMemoryDir(label: string): Promise<string>;
+/** One hour in the past — never the same millisecond as any `now` bound (readRecent uses `ts < now`). */
+export declare function pastIso(): string;
+/** Linear async sleep (shared by the retrying cleanup and pollers). */
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * Remove a temp memory dir, retrying transient ENOTEMPTY/EBUSY races: the
+ * orchestrator keeps best-effort background writers that can still be running
+ * while rm runs. Mirrors the characterization suite's cleanupDir.
+ */
+export declare function cleanupDir(dir: string): Promise<void>;
+/**
+ * Stub the LLM extraction client at the orchestrator FIELD level (the
+ * established seam — never a production hook). Records every turn slice the
+ * engine is asked to extract; storage/persist stays fully real.
+ */
+export declare function stubExtraction(orchestrator: Orchestrator, factory: (turns: BufferTurn[], call: number) => ExtractionResult | Promise<ExtractionResult>): BufferTurn[][];
+/**
+ * The production `persistExtraction` signature (issue #2068). Sourced from the
+ * extraction-run delegate contract — the single canonical shape the orchestrator
+ * both exposes as a private method and delegates to. Test doubles and typed
+ * private-access surfaces import THIS so any production signature change breaks
+ * every consumer at compile time instead of drifting into stale inline casts.
+ */
+export type PersistExtractionFn = ExtractionRunCoordinatorDeps["persistExtraction"];
+/**
+ * The full argument tuple of a {@link PersistExtractionFn} call. Recording the
+ * whole tuple — not just the leading ExtractionResult — means a change to ANY
+ * parameter (storage, source-context, capability sets) surfaces in every
+ * consumer that reads the call log, not only the first argument.
+ */
+export type PersistExtractionArgs = Parameters<PersistExtractionFn>;
+/**
+ * Stub the orchestrator's `persistExtraction` method (the mutation
+ * surface the extraction-run coordinator closure drives). Records the full
+ * {@link PersistExtractionArgs} tuple of every call for assertions; wraps the
+ * factory's persisted-id list into the rich coordinator return shape, or
+ * returns empty IDs when no factory is given. The replacement is typed as the
+ * production {@link PersistExtractionFn}, so a production signature change
+ * fails to compile here rather than silently passing a stale mock.
+ */
+export declare function stubPersistExtraction(orchestrator: Orchestrator, factory?: (args: PersistExtractionArgs, call: number) => string[] | Promise<string[]>): PersistExtractionArgs[];
+/** A single-fact extraction result. */
+export declare function singleFactResult(content: string): ExtractionResult;
+/** Seed a recallable fact file directly on disk with PAST timestamps. */
+export declare function seedFactFile(memoryDir: string, id: string, content: string): Promise<string>;
+/** All markdown files under `root` (recursive); [] when the dir is absent. */
+export declare function markdownFilesUnder(root: string): Promise<string[]>;
+/** Markdown files under `root` whose body contains `needle`. */
+export declare function memoryFilesContaining(root: string, needle: string): Promise<string[]>;
+/** Poll `probe` until it yields a truthy value (async effects settle out-of-band). */
+export declare function eventually<T>(probe: () => Promise<T | null | undefined | false>, label: string, timeoutMs?: number): Promise<T>;
+//# sourceMappingURL=orchestrator-lite.d.ts.map