@fgv/ts-agent-memory 5.1.0-37 → 5.1.0-39

package/dist/ts-agent-memory.d.ts

@@ -1,3 +1,4 @@
+import { AiAssist } from '@fgv/ts-extras';
 import { Brand } from '@fgv/ts-utils';
 import { Converter } from '@fgv/ts-utils';
 import { FileTree } from '@fgv/ts-json-base';
@@ -20,6 +21,46 @@ export declare type AdmissionDecision = {
     readonly evict: ReadonlyArray<MemoryId>;
 };
 
+/**
+ * Temporal retriever returning, for each temporal entity matching the query, the
+ * version valid at `query.asOf` (epoch ms). `asOf` is this retriever's axis: a
+ * query without it yields an empty success (a no-op contribution to a
+ * {@link HybridRetriever}, not a failure). Results are recency-ordered and
+ * limited.
+ * @public
+ */
+export declare class AsOfRetriever implements IMemoryRetriever {
+    private readonly _index;
+    private constructor();
+    /** {@inheritDoc IMemoryRetriever.capabilities} */
+    get capabilities(): IMemoryRetrieverCapabilities;
+    /** Family-convention factory. */
+    static create(index: IMemoryIndex): Result<AsOfRetriever>;
+    /** {@inheritDoc IMemoryRetriever.retrieve} */
+    retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;
+}
+
+/**
+ * Write-time cycle guard. Given the graph's EXISTING directed edges plus a set of
+ * PROPOSED edges, verify that adding the proposed edges keeps the union graph a
+ * DAG. Fails loudly, naming the first proposed edge that would close a directed
+ * cycle.
+ *
+ * @remarks
+ * Distinct from the read-time BFS in `LinkTraversalRetriever` (which tolerates
+ * cycles via a visited-set): this is a WRITE-time admission check. Cycle
+ * detection is DFS reachability — a proposed `source -> target` edge closes a
+ * cycle iff `target` already reaches `source` in the graph built so far. Proposed
+ * edges are folded in one at a time (in order), so an intra-batch cycle
+ * (`A->B`, `B->A` both proposed) is caught as well as a batch-vs-existing cycle.
+ *
+ * See the design note §4: this enforces GLOBAL directed-acyclicity over all link
+ * types (conservative — a mutual associative pair is rejected). Callers that need
+ * mutual links disable the guard.
+ * @public
+ */
+export declare function assertNoCycles(existing: ReadonlyArray<ICycleGuardEdge>, proposed: ReadonlyArray<ICycleGuardEdge>): Result<true>;
+
 /**
  * Validates a single filename stem against the POSIX portable filename set
  * (`[A-Za-z0-9._-]`), rejecting a leading or trailing `.` and reserved Windows
@@ -64,6 +105,22 @@ export declare class BodyConverterRegistry implements IBodyConverterRegistry {
     convert(kind: Kind, body: unknown): Result<unknown>;
 }
 
+/**
+ * Build the design's `buildCycleKey` — a deterministic, canonical (RFC-8785,
+ * via `Crc32Normalizer` from `@fgv/ts-utils`) identity for a directed edge. Used
+ * to de-duplicate proposed edges so a repeated `(source, target, type)` proposal
+ * contributes a single graph edge (and never spuriously "re-closes" a cycle).
+ * @public
+ */
+export declare function buildCycleKey(edge: ICycleGuardEdge): Result<string>;
+
+/**
+ * The link type whose presence on a temporal-kind candidate fires the
+ * contradicts→temporal-versioned interlock.
+ * @public
+ */
+export declare const CONTRADICTS_LINK_TYPE: LinkType;
+
 /**
  * Converters for the branded identifier scalars. Each validates an `unknown`
  * value into the corresponding brand, enforcing the shared hygiene
@@ -79,6 +136,51 @@ export declare const Convert: {
     readonly linkType: Converter<LinkType>;
 };
 
+/**
+ * Build the selected suite of memory `AiAssist.IAiClientTool`s over a
+ * pre-scoped store — ready to hand to `AiAssist.executeClientToolTurn` (and, via
+ * the shared `JsonSchema.object(...)` schemas, `@fgv/ts-extras-mcp`).
+ *
+ * @remarks
+ * **Scope isolation is make-or-break.** The returned tools close over the
+ * pre-scoped {@link ICreateMemoryToolsParams.store | store}; no tool's
+ * `parametersSchema` declares a `scope` (or any scope-widening) property, so an
+ * LLM cannot steer a tool at another actor's memory. The store instance is the
+ * sole scope authority.
+ *
+ * The default selection is {@link DEFAULT_MEMORY_TOOLS} (the read-only set) —
+ * `memory_write` / `memory_delete` are included only when named in
+ * {@link ICreateMemoryToolsParams.tools | tools}.
+ * @public
+ */
+export declare function createMemoryTools(params: ICreateMemoryToolsParams): ReadonlyArray<AiAssist.IAiClientTool>;
+
+/**
+ * Temporal retriever returning the **current** version of each temporal entity
+ * matching the query (the newest version whose `invalid_at` is null/absent),
+ * recency-ordered and limited. A fully-invalidated (soft-deleted) entity
+ * contributes nothing. Non-temporal records are not this retriever's concern.
+ * @public
+ */
+export declare class CurrentValidRetriever implements IMemoryRetriever {
+    private readonly _index;
+    private constructor();
+    /** {@inheritDoc IMemoryRetriever.capabilities} */
+    get capabilities(): IMemoryRetrieverCapabilities;
+    /** Family-convention factory. */
+    static create(index: IMemoryIndex): Result<CurrentValidRetriever>;
+    /** {@inheritDoc IMemoryRetriever.retrieve} */
+    retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;
+}
+
+/**
+ * How the write-time cycle guard behaves: `'reject'` (default — a cycle-inducing
+ * edge fails the ingest) or `'off'` (no acyclicity constraint, for deployments
+ * whose link graphs are legitimately cyclic — e.g. mutual associative links).
+ * @public
+ */
+export declare type CycleGuardMode = 'reject' | 'off';
+
 /**
  * The granularity at which the store deduplicates an incoming write against the
  * existing vault, declared per kind via {@link IWritePolicy.dedupScope}.
@@ -103,6 +205,29 @@ export declare type DedupScope = 'content' | 'entity';
  */
 export declare const DEFAULT_DEDUP_SCOPE: DedupScope;
 
+/**
+ * The default tool subset when {@link ICreateMemoryToolsParams.tools | tools} is
+ * omitted: the read-only set. Mutating tools (`memory_write` / `memory_delete`)
+ * are **off by default** and must be named explicitly — writes stay
+ * curation-mediated unless the host opts in.
+ * @public
+ */
+export declare const DEFAULT_MEMORY_TOOLS: ReadonlyArray<MemoryToolName>;
+
+/**
+ * The default stage-4 layer-2 cosine similarity threshold (design note §2). A
+ * near-duplicate candidate is surfaced to the {@link IEntityResolver} only when
+ * its nearest neighbor scores `>= 0.85`.
+ * @public
+ */
+export declare const DEFAULT_SIMILARITY_THRESHOLD: number;
+
+/**
+ * The default top-K for stage-4 layer-2 similarity candidate generation.
+ * @public
+ */
+export declare const DEFAULT_SIMILARITY_TOP_K: number;
+
 /**
  * Encode a {@link MemoryScopeKey} to its on-disk directory path. The scope may
  * be multi-segment (`/`-separated) — each component is validated independently
@@ -155,9 +280,11 @@ export declare const envelopeYamlConverter: Converter<IMemoryEnvelope>;
  * write-lock so the index and the on-disk files never interleave.
  *
  * @remarks
- * B1 supports flat (non-versioned) layout only and string (markdown) bodies.
- * A codec reporting `isVersioned: true`, or a non-string body, fails loudly —
- * the versioned/temporal write path is a fast-follow.
+ * Bodies are string (markdown). Both layouts are supported: flat
+ * (one-file-per-entity, non-versioned) and versioned (subtree-per-entity,
+ * invalidate-don't-delete), dispatched per kind by the codec's `isVersioned`
+ * flag. A kind is flat with zero behavioral impact unless it opts into a
+ * {@link ITemporalIdentityCodec}.
  * @public
  */
 export declare class FileTreeMemoryStore implements IMemoryStore {
@@ -207,6 +334,14 @@ export declare class FileTreeMemoryStore implements IMemoryStore {
     getById(scope: MemoryScopeKey, id: MemoryId): Promise<Result<IMemoryRecord<unknown> | undefined>>;
     /** {@inheritDoc IMemoryStore.list} */
     list(filter?: IMemoryStoreListFilter): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;
+    /**
+     * Collapse temporal records to the single version valid at `asOf` per entity;
+     * non-temporal records are timeless and pass through unchanged (valid-time
+     * `asOf` applies only to versioned kinds; transaction-time / full bi-temporal
+     * filtering is deferred — OQ-9). An entity with no version valid at `asOf`
+     * contributes nothing.
+     */
+    private static _projectAsOf;
     /** {@inheritDoc IMemoryStore.put} */
     put(record: IMemoryRecord<unknown>): Promise<Result<IMemoryRecord<unknown>>>;
     /** {@inheritDoc IMemoryStore.delete} */
@@ -308,6 +443,73 @@ export declare class FileTreeMemoryStore implements IMemoryStore {
     /** Serialize and write a fully-stamped record, then patch the index. */
     private _persist;
     private _deleteLocked;
+    /**
+     * Flat (non-versioned) delete: physically remove the record file + index
+     * entry, then prune the vector best-effort. Structurally unchanged from the
+     * pre-temporal delete path.
+     */
+    private _deleteFlat;
+    /**
+     * Resolve the current version of a temporal entity from the derived index: the
+     * highest-`seq` version under the entity subtree `scope` whose `invalid_at` is
+     * null/absent. `undefined` when the entity has no current version (never
+     * written, or fully invalidated / soft-deleted).
+     */
+    private _readVersionedCurrent;
+    /**
+     * Every persisted version of the entity whose subtree is `scope`. All version
+     * files for one entity live under exactly that scope (which encodes the
+     * entityId), so a scope filter over the index isolates one entity's versions.
+     */
+    private _versionsForEntity;
+    /**
+     * Versioned write (invalidate-don't-delete). Builds the new version's content
+     * (a first version from the incoming record, or a merge of the incoming patch
+     * over the current version), persists it as a NEW version file, then sets
+     * `invalid_at` on the prior current version.
+     *
+     * Durability order: the new version is persisted FIRST. It carries the highest
+     * `seq`, so a crash before the prior-version invalidation completes still
+     * resolves the new version as current (`selectCurrentVersion` breaks a
+     * two-current tie by highest `seq`), and `asOf` reads stay correct because each
+     * version's `valid_at` lower-bounds its interval.
+     */
+    private _putVersioned;
+    /**
+     * Invalidate a set of still-current versions (close each world-truth interval at
+     * `invalidAt`; stamp transaction-time `updated` = `now`). Chained so a mid-list
+     * failure propagates. Invalidating every prior current — not just the
+     * highest-`seq` pick — self-heals a state where a previous write's invalidation
+     * only partially completed (P2-7).
+     */
+    private _invalidateCurrents;
+    /**
+     * Build the new version to persist. A first version takes the incoming
+     * content verbatim (its dedup `hash` is reused); a subsequent version projects
+     * the incoming record's mutable fields into a merge-patch and lets the policy
+     * merge them over the CURRENT version (the merge-patch-under-versioning
+     * contract), recomputing the content hash from the policy's output. Each
+     * version is its own record with its own transaction time (`created` = `now`)
+     * and a store-minted `id` = the version stem, so `id === filename stem` holds.
+     */
+    private _buildVersionedRecord;
+    /**
+     * Set `invalid_at` on a prior current version (invalidate-don't-delete) and
+     * rewrite its file + index entry. The content hash is unchanged — `invalid_at`
+     * is temporal metadata, not part of `{ kind, body, links }` — so the version's
+     * identity is stable.
+     */
+    private _invalidateVersion;
+    /**
+     * Versioned delete: SOFT delete (invalidate-don't-delete). Sets `invalid_at` on
+     * the current version, leaving the entity's history intact and the entity with
+     * no current version. Returns the invalidated version's {@link MemoryId}. Fails
+     * with "no record found" when there is no current version — matching the flat
+     * delete's not-found semantics. History is retained deliberately: temporal
+     * kinds exist to preserve the audit trail (and the L3 `contradicts` interlock
+     * builds on it), so a hard delete would defeat the purpose.
+     */
+    private _deleteVersioned;
     /** Evict (physically delete) a single record file by id, patching the index. */
     private _evict;
     /** Project the incoming record's mutable fields into a merge-patch. */
@@ -321,8 +523,26 @@ export declare class FileTreeMemoryStore implements IMemoryStore {
      * across first-writes and updates.
      */
     private _admissionCohort;
-    /** Find a record in `scope` whose `contentHash` equals `hash`, if any. */
+    /**
+     * Find a record in `scope` whose `contentHash` equals `hash`, if any,
+     * optionally excluding a specific id. `excludeId` lets the content-scoped
+     * dedup skip the same-id record so it does not shadow the LWW update path.
+     */
     private _findByContentHash;
+    /**
+     * True when `incoming`'s caller-authored mutable metadata (`tags` / `provenance`)
+     * canonically equals `existing`'s. `body` and `links` are covered by the content
+     * hash; `embeddingRef` is store-derived (not caller metadata) and is deliberately
+     * excluded so a same-content re-put is not treated as changed merely because the
+     * store already stamped an embedding. Used to keep an identical re-put a no-op
+     * without swallowing a genuine metadata revision.
+     *
+     * Canonicalization never fails for a validated record (`tags`/`provenance` are
+     * always plain JSON); a failure is defaulted to a non-matching sentinel so the
+     * write flows to `applyUpdate` (which re-validates) rather than silently
+     * no-op-ing on an un-canonicalizable value.
+     */
+    private _isMutableMetadataUnchanged;
     private _contentHash;
     private _codecFor;
     private _policyFor;
@@ -332,7 +552,15 @@ export declare class FileTreeMemoryStore implements IMemoryStore {
      * filename round-trip on every load.
      */
     private _readRecord;
-    /** Enforce `envelope.id === filename stem` and the codec round-trip on load. */
+    /**
+     * Enforce `envelope.id === filename stem`, the codec round-trip, AND that the
+     * envelope's own `entityId` agrees with the id decoded from the subtree scope.
+     * The round-trip only validates (scope, stem) consistency; the codec derives
+     * `entityId` from the scope path and never reads the envelope's `entityId`
+     * field, so a tampered/corrupt file whose frontmatter declares a foreign
+     * `entityId` would otherwise load undetected — and `entityId` is trusted
+     * verbatim downstream (e.g. merge-into re-addressing). Cross-check it here.
+     */
     private _verifyLoaded;
     /**
      * Resolve the directory for a scope, returning `undefined` when it does not
@@ -368,6 +596,44 @@ export declare class FileTreeMemoryStore implements IMemoryStore {
  */
 export declare function guardRetrieverCapabilities(query: IMemoryQuery, capabilities: IMemoryRetrieverCapabilities): Result<true>;
 
+/**
+ * Temporal retriever returning **every** version of each temporal entity matching
+ * the query, ordered ascending by `valid_at` (then `seq` as a stable tiebreak) —
+ * the entity's full history. Limited after ordering.
+ *
+ * @remarks
+ * When the query matches more than one entity, the result is a single
+ * CROSS-entity list globally sorted by `valid_at` — versions of different
+ * entities interleave, NOT grouped per entity — so `limit` truncates that
+ * globally-sorted list. Constrain to one entity (e.g. via `query.scope`) for a
+ * single entity's contiguous history.
+ * @public
+ */
+export declare class HistoryRetriever implements IMemoryRetriever {
+    private readonly _index;
+    private constructor();
+    /** {@inheritDoc IMemoryRetriever.capabilities} */
+    get capabilities(): IMemoryRetrieverCapabilities;
+    /** Family-convention factory. */
+    static create(index: IMemoryIndex): Result<HistoryRetriever>;
+    /** {@inheritDoc IMemoryRetriever.retrieve} */
+    retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;
+    /** A version's world-truth start: its `valid_at`, defaulting to `created` when absent. */
+    private static _startOf;
+    /**
+     * Ascending-by-`valid_at` comparator (a version's `valid_at` defaults to its
+     * `created` when absent), with `seq` as a stable ascending tiebreak so
+     * same-instant versions order by write sequence.
+     */
+    private static _byValidAtAscending;
+}
+
+/**
+ * The provenance source stamped on every record the ingest pipeline writes.
+ * @public
+ */
+export declare const HOST_INGEST_PROVENANCE_SOURCE: string;
+
 /**
  * Composes several retrievers, dispatches a query to each, and merges their
  * results via an injectable {@link IMergeStrategy}. Its capabilities are the
@@ -445,6 +711,100 @@ export declare interface IBodyConverterRegistry {
     convert(kind: Kind, body: unknown): Result<unknown>;
 }
 
+/**
+ * A stage-5 attributed edge proposal: the {@link ICandidateEdge.edge | edge} to
+ * add, sourced from {@link ICandidateEdge.source | source}. The source MUST be a
+ * candidate being written in this ingest (edges land on the source record's
+ * `envelope.links`); the edge's `target` must resolve to a sibling candidate or
+ * an existing store record.
+ * @public
+ */
+export declare interface ICandidateEdge {
+    /** The reference id (codec `idStem`) of the candidate the edge originates from. */
+    readonly source: MemoryId;
+    /** The attributed edge (type / target / optional confidence / provenance). */
+    readonly edge: IEdge;
+}
+
+/**
+ * A host-extracted candidate record (stage 3 output). The host supplies the
+ * full envelope MINUS the {@link StoreStampedEnvelopeField | store-stamped
+ * fields} (fgv derives `id` from the codec; the store stamps the rest) plus the
+ * typed body. Every candidate body is validated against the kind's registered
+ * Converter before it can reach the store (the typed validation boundary).
+ * @public
+ */
+export declare interface ICandidateRecord {
+    /** The host-supplied envelope, minus the store-stamped fields. */
+    readonly envelope: Omit<IMemoryEnvelope, StoreStampedEnvelopeField>;
+    /** The per-kind body (a markdown string in v1), validated on ingest. */
+    readonly body: unknown;
+}
+
+/**
+ * Parameters for {@link createMemoryTools}.
+ *
+ * @remarks
+ * **Scope isolation is constructor-fixed.** The {@link
+ * ICreateMemoryToolsParams.store | store} is the sole scope authority — it is the
+ * actor's own, pre-scoped memory root. No tool's `parametersSchema` declares a
+ * `scope` (or any scope-widening) property, so an LLM cannot steer a tool at
+ * another actor's memory.
+ * @public
+ */
+export declare interface ICreateMemoryToolsParams {
+    /**
+     * The pre-scoped memory store (the actor's own memory root). Sole scope
+     * authority — backs `memory_write` / `memory_read` / `memory_delete`.
+     */
+    readonly store: IMemoryStore;
+    /** Retriever backing `memory_search` (and `memory_context` via link traversal). */
+    readonly retriever: IMemoryRetriever;
+    /** Body converter registry — gates the toolable kinds via `has(kind)`. */
+    readonly registry: IBodyConverterRegistry;
+    /**
+     * The per-tool enable subset. Defaults to {@link DEFAULT_MEMORY_TOOLS} (the
+     * read-only set). Name `memory_write` / `memory_delete` here to opt into the
+     * mutating tools.
+     */
+    readonly tools?: ReadonlyArray<MemoryToolName>;
+    /**
+     * Optional whitelist of toolable kinds. When present, a tool `kind` argument
+     * outside this set is rejected. When absent, {@link
+     * IBodyConverterRegistry.has | registry.has} is the sole kind gate.
+     */
+    readonly kinds?: ReadonlyArray<Kind>;
+    /**
+     * Per-kind identity codecs, used by `memory_write` to map the domain
+     * {@link EntityId} to the record's storage id (the store resolves codecs
+     * internally for `get` / `delete`, so read / delete do not need them). Absent
+     * → `memory_write` uses {@link ICreateMemoryToolsParams.defaultCodec |
+     * defaultCodec}, and fails loudly for a kind with no resolvable codec. The
+     * read-only default tool set needs no codecs.
+     */
+    readonly codecs?: ReadonlyMap<Kind, IIdentityCodec>;
+    /** Default identity codec for kinds without an explicit {@link ICreateMemoryToolsParams.codecs | codecs} entry. */
+    readonly defaultCodec?: IIdentityCodec;
+    /**
+     * Optional host hook mapping a record to its agent-visible handle (an evocative
+     * mnemonic tag). When supplied, `memory_search` / `memory_context` results use
+     * the returned handle as the agent-visible key; when absent the raw
+     * {@link MemoryId} is used.
+     */
+    readonly handleFor?: (record: IMemoryRecord<unknown>) => string;
+}
+
+/**
+ * A directed edge in the link graph the cycle guard reasons over: `source` links
+ * to `target` under relation `type`.
+ * @public
+ */
+export declare interface ICycleGuardEdge {
+    readonly source: MemoryId;
+    readonly target: MemoryId;
+    readonly type: LinkType;
+}
+
 /**
  * An attributed link between two records. Carries the relation type, the
  * target id, and optional confidence / provenance / world-truth validity.
@@ -470,6 +830,54 @@ export declare interface IEdge {
     readonly invalid_at?: number | null;
 }
 
+/**
+ * A near-duplicate candidate surfaced to the {@link IEntityResolver} by stage-4
+ * layer-2 similarity search: an existing record whose embedding is within the
+ * similarity threshold of the incoming candidate.
+ * @public
+ */
+export declare interface IEntityResolutionCandidate {
+    /** The existing record's id. */
+    readonly id: MemoryId;
+    /** The existing record. */
+    readonly record: IMemoryRecord<unknown>;
+    /** The backend similarity score (higher = more similar). */
+    readonly score: number;
+}
+
+/**
+ * Stage 4 (optional) — the host's entity resolver (OQ-13, LOCKED OPTIONAL). When
+ * supplied, fgv surfaces near-duplicate {@link IEntityResolutionCandidate}s (from
+ * layer-2 similarity search) and the resolver returns a
+ * {@link ResolutionVerdict}. When ABSENT, stage-4 dedup falls back to
+ * exact-`{ kind, body }`-hash only — the deterministic-identity host path.
+ * @public
+ */
+export declare interface IEntityResolver {
+    /**
+     * Decide whether `candidate` is new, a duplicate of / supersedes / merges into
+     * one of the surfaced `similar` records. `similar` is non-empty and ordered by
+     * descending score when the resolver is invoked (fgv only calls it when
+     * layer-2 surfaces at least one over-threshold neighbor).
+     */
+    resolve(candidate: ICandidateRecord, similar: ReadonlyArray<IEntityResolutionCandidate>): Promise<Result<ResolutionVerdict>>;
+}
+
+/**
+ * Stage 3 — the host's fact extractor. Turns a classified item into zero or more
+ * {@link ICandidateRecord}s. Each candidate's body is validated against the
+ * kind's registered Converter by fgv before it can reach the store (the typed
+ * validation boundary — no unchecked host data is persisted).
+ * @public
+ */
+export declare interface IFactExtractor {
+    /**
+     * Extract candidate records from a classified item. An empty array is a valid
+     * result (the item yielded nothing memorable).
+     */
+    extract(item: IIngestItem, classification: IMemoryClassification): Promise<Result<ReadonlyArray<ICandidateRecord>>>;
+}
+
 /**
  * Parameters for {@link FileTreeMemoryStore.create}.
  * @public
@@ -587,6 +995,87 @@ export declare interface IIndexedMemoryRecord {
     readonly record: IMemoryRecord<unknown>;
 }
 
+/**
+ * Per-candidate outcome of an ingest run.
+ * @public
+ */
+export declare interface IIngestedRecordResult {
+    /** The candidate the outcome is for. */
+    readonly candidate: ICandidateRecord;
+    /** The resolution verdict fgv reached (or the resolver returned). */
+    readonly resolution: ResolutionVerdict;
+    /** What the write ultimately did. */
+    readonly disposition: IngestDisposition;
+    /**
+     * The stored record's id: the newly-written id (`written` / `merged`), or the
+     * existing target's id (`deduped`).
+     */
+    readonly id: MemoryId;
+    /** The persisted record, when a write happened (`written` / `merged`). */
+    readonly record?: IMemoryRecord<unknown>;
+    /** The stage-5 edges attached to this candidate before the write. */
+    readonly edges: ReadonlyArray<ICandidateEdge>;
+    /**
+     * Informational diagnostic, set to `'temporal-versioned'` when the
+     * contradicts→temporal interlock is recognized: a `contradicts` edge was
+     * attached to a candidate of a temporal kind.
+     *
+     * @remarks
+     * A temporal kind ALWAYS writes through the store's versioned put path (that is
+     * the codec's `isVersioned` behavior — the prior version is invalidated and a
+     * new version written on every write, contradicts edge or not). This flag does
+     * NOT cause that routing; it is a diagnostic marker that the contradicts-driven
+     * scenario occurred, so callers can distinguish a contradiction-superseding
+     * version from an ordinary revision.
+     */
+    readonly interlock?: 'temporal-versioned';
+}
+
+/**
+ * A single unit of raw source material handed to the ingest pipeline. The host
+ * owns the shape of {@link IIngestItem.content | content} — fgv never interprets
+ * it; it flows opaquely into the host's classifier and extractor (stages 2-3).
+ *
+ * Single-item ingest is FIRST-CLASS: the orchestrator's primary entry point
+ * takes one `IIngestItem` (per-turn streaming), and the batch entry point is a
+ * convenience loop over it.
+ * @public
+ */
+export declare interface IIngestItem {
+    /**
+     * Host-owned identity for this source item. Opaque to fgv; used only in
+     * diagnostics and echoed back on the {@link IIngestItemResult}.
+     */
+    readonly id: string;
+    /**
+     * The opaque source payload the host's classifier / extractor understand
+     * (e.g. a raw turn, a document, a tool-call transcript). Never interpreted by
+     * fgv.
+     */
+    readonly content: unknown;
+    /**
+     * Optional back-link to the memory record this item was derived from (e.g. the
+     * MTM turn an extracted fact came from). When present, fgv stamps it as
+     * {@link IProvenance.derivedFrom | provenance.derivedFrom} on every record
+     * ingested from this item (stage 6) — the cross-kind provenance spine.
+     */
+    readonly sourceId?: MemoryId;
+    /** Optional opaque metadata carried alongside the item; never interpreted by fgv. */
+    readonly metadata?: Record<string, unknown>;
+}
+
+/**
+ * The result of ingesting a single {@link IIngestItem}: the item plus the
+ * per-candidate outcomes (one item can yield zero or many candidate records).
+ * @public
+ */
+export declare interface IIngestItemResult {
+    /** The item that was ingested. */
+    readonly item: IIngestItem;
+    /** The per-candidate outcomes, in extraction order. */
+    readonly records: ReadonlyArray<IIngestedRecordResult>;
+}
+
 /**
  * Parameters for {@link MemoryCapCullPolicy.create}.
  * @public
@@ -606,6 +1095,41 @@ export declare interface IMemoryCapCullPolicyParams {
     readonly mutableFields: ReadonlyArray<string>;
 }
 
+/**
+ * The host classifier's verdict for an {@link IIngestItem} (stage 2). Guides the
+ * host's own extractor (stage 3) and supplies the default `kind` / `tags` /
+ * `confidence` fgv stamps when the extractor does not override them.
+ *
+ * Extensible: the `[key: string]: unknown` arm lets the host attach an opaque
+ * classification payload without changing this interface.
+ * @public
+ */
+export declare interface IMemoryClassification {
+    /** The record kind the item classifies as. */
+    readonly kind: Kind;
+    /** Optional tags the classifier assigns. */
+    readonly tags?: ReadonlyArray<Tag>;
+    /** Optional classifier confidence in `[0, 1]`; flows to `provenance.confidence`. */
+    readonly confidence?: number;
+    /** Opaque, host-owned extension payload — never interpreted by fgv. */
+    readonly [key: string]: unknown;
+}
+
+/**
+ * Stage 2 — the host's classifier. Decides what {@link IIngestItem} maps to
+ * which memory {@link Kind} (and optional tags / confidence). LOCKED as a
+ * separate staged interface (OQ-10): the host plugs its existing classifier
+ * machinery in here rather than surrendering to an opaque ingestor.
+ * @public
+ */
+export declare interface IMemoryClassifier {
+    /**
+     * Classify one item. A `fail` aborts the item's ingest loudly (fgv never
+     * guesses a kind).
+     */
+    classify(item: IIngestItem): Promise<Result<IMemoryClassification>>;
+}
+
 /**
  * The invariant identity + transaction-time envelope carried by every memory
  * record, independent of the per-kind body.
@@ -700,6 +1224,75 @@ export declare interface IMemoryIndex {
     backlinks(target: MemoryId): ReadonlyArray<MemoryId>;
 }
 
+/**
+ * The fgv-owned six-stage ingest orchestrator. Composes the host's staged
+ * classify / extract / (optional) resolve / relate machinery around fgv's owned
+ * validation boundary, dedup, edge + cycle safety, provenance stamping, and the
+ * contradicts→temporal interlock.
+ * @public
+ */
+export declare interface IMemoryIngestOrchestrator {
+    /**
+     * Ingest a SINGLE item end-to-end (the first-class per-turn streaming path).
+     */
+    ingestItem(item: IIngestItem): Promise<Result<IIngestItemResult>>;
+    /**
+     * Ingest a batch of items. A convenience loop over {@link
+     * IMemoryIngestOrchestrator.ingestItem | ingestItem} — items are processed in
+     * order and the first failure aborts the batch.
+     */
+    ingestBatch(items: ReadonlyArray<IIngestItem>): Promise<Result<ReadonlyArray<IIngestItemResult>>>;
+}
+
+/**
+ * Parameters for {@link MemoryIngestOrchestrator.create}.
+ * @public
+ */
+export declare interface IMemoryIngestOrchestratorCreateParams {
+    /** The store every write bottoms out in (stage 6). */
+    readonly store: IMemoryStore;
+    /** Per-kind body converter registry — the stage-3 typed validation boundary. */
+    readonly registry: IBodyConverterRegistry;
+    /** Per-kind identity codecs (maps a candidate `entityId` to its storage address). */
+    readonly codecs?: ReadonlyMap<Kind, IIdentityCodec>;
+    /** Default identity codec for kinds without an explicit entry. */
+    readonly defaultCodec?: IIdentityCodec;
+    /** Stage 2 — the host's classifier. */
+    readonly classifier: IMemoryClassifier;
+    /** Stage 3 — the host's fact extractor. */
+    readonly extractor: IFactExtractor;
+    /** Stage 5 — the host's relation extractor. */
+    readonly relationExtractor: IRelationExtractor;
+    /**
+     * Stage 4 (optional, OQ-13) — the host's entity resolver. Absent → stage-4
+     * dedup is exact-`{ kind, body }`-hash only (the deterministic-identity path).
+     */
+    readonly entityResolver?: IEntityResolver;
+    /**
+     * Optional vector index for stage-4 layer-2 similarity candidate-gen. Wired
+     * together with {@link IMemoryIngestOrchestratorCreateParams.embed | embed} AND
+     * {@link IMemoryIngestOrchestratorCreateParams.entityResolver | entityResolver};
+     * absent (or either co-requisite absent) → layer-2 is skipped and dedup is
+     * exact-only.
+     */
+    readonly vectorIndex?: IVectorIndex;
+    /** Optional embedder used to embed a candidate for layer-2 similarity search. */
+    readonly embed?: MemoryEmbedder;
+    /**
+     * Stage-4 layer-2 cosine threshold. Defaults to {@link
+     * DEFAULT_SIMILARITY_THRESHOLD} (`0.85`).
+     */
+    readonly similarityThreshold?: number;
+    /**
+     * Stage-4 layer-2 top-K. Defaults to {@link DEFAULT_SIMILARITY_TOP_K} (`5`).
+     */
+    readonly similarityTopK?: number;
+    /** Write-time cycle guard mode. Defaults to `'reject'`. */
+    readonly cycleGuard?: CycleGuardMode;
+    /** Diagnostic logger (defaults to a no-op). */
+    readonly logger?: Logging.ILogger;
+}
+
 /**
  * Query criteria for {@link MemoryObservationStore.query}. All supplied criteria
  * are AND-combined.
@@ -913,7 +1506,9 @@ export declare interface IMemoryStore {
     /**
      * Keyed read by entity id. Resolves `entityId` to a storage address via the
      * registered {@link IIdentityCodec} for `kind`. Returns `undefined` when no
-     * record exists.
+     * record exists. For a versioned (temporal) kind this returns the current
+     * version, resolved from the derived in-memory index (not re-read/re-verified
+     * from disk per call — the index is kept in sync with every write).
      */
     get(kind: Kind, entityId: EntityId): Promise<Result<IMemoryRecord<unknown> | undefined>>;
     /**
@@ -934,7 +1529,10 @@ export declare interface IMemoryStore {
     put(record: IMemoryRecord<unknown>): Promise<Result<IMemoryRecord<unknown>>>;
     /**
      * Delete a record by `(kind, entityId)`. Non-temporal kinds physically delete
-     * the file. Returns the {@link MemoryId} of the deleted record.
+     * the file and return the deleted record's {@link MemoryId}. Temporal
+     * (versioned) kinds SOFT-delete: the current version is invalidated
+     * (`invalid_at` set), history is retained, and the invalidated version's
+     * {@link MemoryId} is returned.
      */
     delete(kind: Kind, entityId: EntityId): Promise<Result<MemoryId>>;
 }
@@ -951,12 +1549,48 @@ export declare interface IMemoryStoreListFilter {
     /** Restrict to records carrying this tag (exact match). */
     readonly tag?: Tag;
     /**
-     * For temporal kinds: return only records valid at this epoch ms. No-op in
-     * B1 (no temporal kinds wired).
+     * For temporal (versioned) kinds: collapse each entity to the single version
+     * valid at this epoch ms. Non-temporal records are timeless and pass through
+     * unchanged. Absent = no temporal projection (every version is returned).
      */
     readonly asOf?: number;
 }
 
+/**
+ * A single agent-visible search / context result item. The agent-facing key is
+ * {@link IMemoryToolResultItem.handle | handle}: the host mnemonic when a
+ * {@link ICreateMemoryToolsParams.handleFor | handleFor} hook is supplied, else
+ * the raw {@link MemoryId}.
+ * @public
+ */
+export declare interface IMemoryToolResultItem {
+    /** The agent-visible key (host handle when supplied, raw {@link MemoryId} otherwise). */
+    readonly handle: string;
+    /** The record's {@link Kind}. */
+    readonly kind: Kind;
+    /** The record's domain {@link EntityId}. */
+    readonly entityId: EntityId;
+    /** The record's tags. */
+    readonly tags: ReadonlyArray<string>;
+    /** The record body (a markdown string in B1). */
+    readonly body: unknown;
+}
+
+/**
+ * The success value returned by `memory_write.execute`.
+ * @public
+ */
+export declare interface IMemoryWriteResult {
+    /** What the write did — see {@link MemoryWriteOutcome}. */
+    readonly outcome: MemoryWriteOutcome;
+    /** The stored record's {@link MemoryId}. */
+    readonly id: MemoryId;
+    /** The domain {@link EntityId} the write targeted. */
+    readonly entityId: EntityId;
+    /** The record's {@link Kind}. */
+    readonly kind: Kind;
+}
+
 /**
  * Strategy for combining the result sets of the retrievers a
  * {@link HybridRetriever} composes. Injectable so a consumer can weight,
@@ -979,6 +1613,18 @@ export declare interface IMergeStrategy {
  */
 export declare function indexedRecordMatchesQuery(entry: IIndexedMemoryRecord, query: IMemoryQuery): boolean;
 
+/**
+ * How a candidate was ultimately written (or not) after resolution.
+ *
+ * - `written` — persisted as a fresh record (verdict `new`), or as a superseding
+ *   record (verdict `supersede`).
+ * - `deduped` — not written; an existing record satisfied it (verdict
+ *   `duplicate-of`, incl. every layer-1 exact `{ kind, body }` match).
+ * - `merged` — merged into an existing target entity (verdict `merge-into`).
+ * @public
+ */
+export declare type IngestDisposition = 'written' | 'deduped' | 'merged';
+
 /**
  * The brute-force, in-memory cosine {@link IVectorIndex}. Stores one
  * `Float32Array` per record and answers a query by computing cosine similarity
@@ -1067,6 +1713,48 @@ export declare interface IProvenance {
     readonly [key: string]: unknown;
 }
 
+/**
+ * A candidate paired with its resolved reference id, handed to the relation
+ * extractor so it can source edges from it.
+ * @public
+ */
+export declare interface IRelationCandidate {
+    /** The candidate about to be written. */
+    readonly candidate: ICandidateRecord;
+    /** Its resolved reference id (codec `idStem` — the stable entity reference). */
+    readonly id: MemoryId;
+}
+
+/**
+ * The context fgv hands the host's relation extractor (stage 5): the source item
+ * plus the candidates fgv is about to write, each paired with its resolved
+ * reference id (the codec `idStem`). The extractor proposes attributed edges over
+ * these ids and existing store records.
+ * @public
+ */
+export declare interface IRelationContext {
+    /** The item being ingested. */
+    readonly item: IIngestItem;
+    /** The candidates fgv is about to write, each with its resolved reference id. */
+    readonly candidates: ReadonlyArray<IRelationCandidate>;
+}
+
+/**
+ * Stage 5 — the host's relation extractor. Proposes attributed edges among the
+ * candidates and existing records. fgv owns the validation, the write-time cycle
+ * guard, and the actual persistence of the edges (the host brings only the
+ * relationship judgment).
+ * @public
+ */
+export declare interface IRelationExtractor {
+    /**
+     * Propose the edges to attach for this ingest. An empty array is valid (no
+     * relations). Every proposed {@link ICandidateEdge.source | source} must be one
+     * of the context's candidate reference ids.
+     */
+    relate(context: IRelationContext): Promise<Result<ReadonlyArray<ICandidateEdge>>>;
+}
+
 /**
  * The semantic backend wired into a {@link SemanticRetriever}: the vector index
  * to query and the embedder that turns the query text into a vector. Both are
@@ -1096,6 +1784,41 @@ export declare interface ISemanticRetrieverCreateParams {
     readonly backend?: ISemanticBackend;
 }
 
+/**
+ * Narrow an {@link IIdentityCodec} to {@link ITemporalIdentityCodec} by probing
+ * for the versioned methods. Used by the store when an `encode` result reports
+ * `isVersioned: true`.
+ * @public
+ */
+export declare function isTemporalIdentityCodec(codec: IIdentityCodec): codec is ITemporalIdentityCodec;
+
+/**
+ * Whether a record participates in the versioned (temporal) layout. A temporal
+ * record always carries a {@link ITemporalBlock | temporal} block (the store
+ * stamps `valid_at` on every versioned write); an atemporal record never does,
+ * so presence of `temporal` is the discriminator. Independent of `id`/`entityId`
+ * divergence (MTM is flat yet has `entityId !== id`).
+ * @public
+ */
+export declare function isTemporalRecord(record: IMemoryRecord<unknown>): boolean;
+
+/**
+ * Whether a temporal record is a *current* version — its `temporal.invalid_at`
+ * is `null` or absent (the still-valid sentinel). A non-temporal record is never
+ * current in this sense (returns `false`).
+ * @public
+ */
+export declare function isVersionCurrent(record: IMemoryRecord<unknown>): boolean;
+
+/**
+ * Whether a temporal record's validity interval contains `asOf` (epoch ms):
+ * `valid_at <= asOf` and (`invalid_at` is null/absent OR `asOf < invalid_at`).
+ * The version's `valid_at` defaults to its `created` when absent; a non-temporal
+ * record is never "valid at" a point (returns `false`).
+ * @public
+ */
+export declare function isVersionValidAt(record: IMemoryRecord<unknown>, asOf: number): boolean;
+
 /**
  * Optional bi-temporal validity block on an envelope. Present only on
  * temporal kinds; absent = zero cost for atemporal kinds.
@@ -1108,6 +1831,42 @@ export declare interface ITemporalBlock {
     readonly invalid_at?: number | null;
 }
 
+/**
+ * Additive extension of {@link IIdentityCodec} for versioned (temporal) kinds. A
+ * codec whose {@link IIdentityCodec.encode | encode} reports `isVersioned: true`
+ * implements this so the store can form and parse per-version filenames without
+ * knowing the layout. Non-versioned codecs do NOT implement it (probe with
+ * {@link isTemporalIdentityCodec}).
+ * @public
+ */
+export declare interface ITemporalIdentityCodec extends IIdentityCodec {
+    /**
+     * Form the version filename stem for a specific `(entityId, seq)`. The store
+     * appends the extension and writes it under the entity subtree returned by
+     * {@link IIdentityCodec.encode | encode}.
+     */
+    encodeVersion(entityId: EntityId, seq: number): Result<string>;
+    /**
+     * Parse a `(subtree scope, version stem)` back to its
+     * {@link ITemporalVersionAddress}. The subtree scope is authoritative for the
+     * `entityId`, disambiguating a stem whose `entityId` itself ends in
+     * `-v<digits>`.
+     */
+    decodeVersion(scope: MemoryScopeKey, stem: string): Result<ITemporalVersionAddress>;
+}
+
+/**
+ * The `(entityId, version seq)` an {@link ITemporalIdentityCodec.decodeVersion}
+ * recovers from a version file address.
+ * @public
+ */
+export declare interface ITemporalVersionAddress {
+    /** The stable consumer-supplied domain key. */
+    readonly entityId: EntityId;
+    /** The version's monotonic `seq` (the `v<seq>` component of the file stem). */
+    readonly seq: number;
+}
+
 /**
  * The vector-index seam an embedding backend implements to make
  * {@link SemanticRetriever | semantic recall} operational.
@@ -1216,7 +1975,6 @@ export declare function joinFrontmatter(frontmatter: string, body: string): stri
 export declare type Kind = Brand<string, 'Kind'>;
 
 /**
- /**
  * Identity codec for the knowledge kind family. A knowledge entity is keyed
  * by its consumer-supplied `docId`, which is used verbatim as the filename
  * stem under the flat `knowledge` scope.
@@ -1547,6 +2305,108 @@ export declare class MemoryIndex implements IMemoryIndex {
  */
 export declare type MemoryIndexPatchOp = 'put' | 'delete';
 
+/**
+ * Default {@link IMemoryIngestOrchestrator}.
+ * @public
+ */
+export declare class MemoryIngestOrchestrator implements IMemoryIngestOrchestrator {
+    private readonly _store;
+    private readonly _registry;
+    private readonly _codecs;
+    private readonly _defaultCodec;
+    private readonly _classifier;
+    private readonly _extractor;
+    private readonly _relationExtractor;
+    private readonly _similarity;
+    private readonly _similarityThreshold;
+    private readonly _similarityTopK;
+    private readonly _cycleGuard;
+    private readonly _logger;
+    private readonly _hasher;
+    private constructor();
+    /** Family-convention factory. */
+    static create(params: IMemoryIngestOrchestratorCreateParams): Result<MemoryIngestOrchestrator>;
+    /** {@inheritDoc IMemoryIngestOrchestrator.ingestItem} */
+    ingestItem(item: IIngestItem): Promise<Result<IIngestItemResult>>;
+    /** {@inheritDoc IMemoryIngestOrchestrator.ingestBatch} */
+    ingestBatch(items: ReadonlyArray<IIngestItem>): Promise<Result<ReadonlyArray<IIngestItemResult>>>;
+    /** Stage 2 — classify (host), normalizing a rejected promise into a Failure. */
+    private _classify;
+    /** Stage 3 — extract (host), normalizing a rejected promise into a Failure. */
+    private _extract;
+    /**
+     * Stages 3b-6 over the extracted candidates: validate bodies, resolve/dedup
+     * (stage 4), relate + cycle guard (stage 5), and load-with-provenance (stage 6).
+     */
+    private _processCandidates;
+    /** Stage 3b + 4 for one candidate: validate body, resolve address, resolve verdict. */
+    private _planCandidate;
+    /**
+     * Turn a resolved verdict into a candidate plan. A `new` verdict writes under the
+     * candidate's own address. Every TARGET-bearing verdict
+     * (`duplicate-of` / `supersede` / `merge-into`) is validated uniformly: the
+     * target must be a real store record (fgv owns validation — a non-compliant host
+     * resolver never smuggles a bogus id through) AND its kind must equal the
+     * candidate's kind (a cross-kind target would write to the wrong scope). Only
+     * `merge-into` re-addresses the write to the target's entity.
+     */
+    private _planFromVerdict;
+    /**
+     * Stage 4 — resolve a dedup verdict. Layer 1: an exact `{ kind, body }` match in
+     * the candidate's scope is a `duplicate-of` (design note §1). Layer 2 (only when
+     * a resolver + vector index + embedder are all wired): embed the candidate,
+     * surface over-threshold neighbors, and dispatch to the {@link IEntityResolver}.
+     * Otherwise the verdict is `new` (the exact-only fall-back path).
+     */
+    private _resolveVerdict;
+    /** Layer-2 similarity candidate-gen + resolver dispatch. */
+    private _resolveViaSimilarity;
+    /** Layer-2 continuation once the candidate has a provisional record to embed. */
+    private _resolveViaSimilarityEmbedded;
+    /**
+     * Find an existing record in `scope` whose `{ kind, body }` hash matches the
+     * candidate's (layer-1 exact dedup). Invalidated temporal versions are excluded
+     * — only a live (non-temporal or current) record deduplicates a candidate.
+     */
+    private _findExactMatch;
+    /**
+     * The body of a persisted record, required to be a string (the store persists
+     * only string bodies). Fails loudly rather than blind-casting an `unknown` body
+     * into the exact-dedup hash — a non-string existing body is a store-integrity
+     * fault, surfaced with context, not a silent miscompute.
+     */
+    private static _recordBodyString;
+    /** The stage-4 exact-dedup key over `{ kind, body }` (design note §1). */
+    private _exactKey;
+    /** Stage 5 — relate (host), validate edges, and run the write-time cycle guard. */
+    private _relate;
+    /**
+     * Validate stage-5 edges: each `source` must be a candidate being written; each
+     * `target` must resolve to a sibling candidate or an existing store record.
+     */
+    private _validateEdges;
+    /** Stage 6 — stamp provenance + edges, admit through the store, record the outcome. */
+    private _loadCandidate;
+    /** Build the fully-stamped record to persist (provenance + edges + placeholder txn fields). */
+    private _buildRecord;
+    /** Union two tag lists, de-duplicated, preserving first-occurrence order. */
+    private static _unionTags;
+    /** De-duplicate a link list by canonical edge hash, preserving first-occurrence order. */
+    private _dedupEdges;
+    /** Resolve a `(kind, entityId)` to its storage address via the registered codec. */
+    private _resolveAddress;
+    /** Run a host hook, normalizing a thrown/rejected hook into a Failure (never throws across the seam). */
+    private _capture;
+    /** Index a record snapshot by id (last write wins on an id collision across scopes). */
+    private static _indexById;
+    /** Every existing outbound edge in the snapshot, as cycle-guard edges. */
+    private static _existingEdges;
+    /** A provisional record for embedding a candidate (placeholder txn-time fields). */
+    private static _provisionalRecord;
+    /** Require a candidate body to be a string (the store persists only string bodies). */
+    private static _asStringBody;
+}
+
 /**
  * The outcome of the observed operation.
  * @public
@@ -1655,6 +2515,30 @@ export declare class MemoryObservationStore implements IMemoryObserver {
  */
 export declare type MemoryScopeKey = Brand<string, 'MemoryScopeKey'>;
 
+/**
+ * The names of the five proof-set memory tools. A caller selects a subset via
+ * {@link ICreateMemoryToolsParams.tools | tools}.
+ * @public
+ */
+export declare type MemoryToolName = 'memory_write' | 'memory_read' | 'memory_search' | 'memory_context' | 'memory_delete';
+
+/**
+ * Discriminates the outcome of a {@link createMemoryTools | memory_write} call so
+ * the agent can reason about what its write actually did.
+ *
+ * @remarks
+ * - `written` — a new record was persisted, or an existing entity was updated.
+ * - `deduped` — the content already existed (content-hash dedup no-op); the
+ *   store returned the existing record unchanged.
+ *
+ * The store's public `put` return does not surface cap-cull evictions, so a
+ * `culled` outcome is not distinguishable at this layer without an L1 change or
+ * observer wiring (both out of scope for L2). The writer's own record is always
+ * `written` even when the write triggers a cull of older siblings.
+ * @public
+ */
+export declare type MemoryWriteOutcome = 'written' | 'deduped';
+
 /**
  * Identity codec for the medium-term-memory (MTM) kind family. An MTM entity is
  * keyed by the colon-composite `<conversationId>:<turnIndex>` and maps into a
@@ -1763,6 +2647,25 @@ export declare class RecencyRetriever implements IMemoryRetriever {
     retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;
 }
 
+/**
+ * The four dedup verdicts a {@link IEntityResolver} (or fgv's exact-match layer)
+ * returns for a candidate. See the design note §3 for the verdict → write
+ * disposition mapping.
+ * @public
+ */
+export declare type ResolutionVerdict = {
+    readonly verdict: 'new';
+} | {
+    readonly verdict: 'duplicate-of';
+    readonly target: MemoryId;
+} | {
+    readonly verdict: 'supersede';
+    readonly target: MemoryId;
+} | {
+    readonly verdict: 'merge-into';
+    readonly target: MemoryId;
+};
+
 /**
  * The reference {@link IMergeStrategy}: a score-union. Every record is scored by
  * the number of composed result sets it appears in (deduplicated by
@@ -1790,6 +2693,22 @@ export declare class ScoreUnionMergeStrategy implements IMergeStrategy {
  */
 export declare function selectByQuery(entries: ReadonlyArray<IIndexedMemoryRecord>, query: IMemoryQuery): IMemoryRecord<unknown>[];
 
+/**
+ * Select the current version from a set of an entity's versions: the newest
+ * (highest `seq`) version whose `invalid_at` is null/absent. `undefined` when the
+ * entity has no current version (fully invalidated / soft-deleted, or empty).
+ * @public
+ */
+export declare function selectCurrentVersion(versions: ReadonlyArray<IMemoryRecord<unknown>>): IMemoryRecord<unknown> | undefined;
+
+/**
+ * Select the version of an entity valid at `asOf` (epoch ms): the newest
+ * (highest `seq`) version whose validity interval contains `asOf`. `undefined`
+ * when no version was valid at that instant.
+ * @public
+ */
+export declare function selectVersionAsOf(versions: ReadonlyArray<IMemoryRecord<unknown>>, asOf: number): IMemoryRecord<unknown> | undefined;
+
 /**
  * The loud-degradation message a retriever returns when `query.semantic` is set
  * but no {@link IVectorIndex} is wired.
@@ -1843,6 +2762,14 @@ export declare function serializeMemoryFile(envelope: IMemoryEnvelope, body: str
  */
 export declare function splitFrontmatter(raw: string): Result<IMemoryFileParts>;
 
+/**
+ * The store-owned envelope fields fgv derives or stamps: `id` (from the codec),
+ * and the transaction-time metadata (`seq` / `contentHash` / `created` /
+ * `updated`). A {@link ICandidateRecord} supplies everything EXCEPT these.
+ * @public
+ */
+export declare type StoreStampedEnvelopeField = 'id' | 'seq' | 'contentHash' | 'created' | 'updated';
+
 /**
  * Returns records matching `query.filter`, narrowed by any scope / kind / tag
  * pre-filter and recency-ordered. The predicate is this retriever's axis: a
@@ -1885,12 +2812,67 @@ export declare class TagRetriever implements IMemoryRetriever {
     retrieve(query: IMemoryQuery): Promise<Result<ReadonlyArray<IMemoryRecord<unknown>>>>;
 }
 
+/**
+ * The capabilities every temporal retriever exposes: temporal "as-of" queries
+ * are operational (semantic recall and link traversal are not this retriever's
+ * concern).
+ * @public
+ */
+export declare const TEMPORAL_CAPABILITIES: IMemoryRetrieverCapabilities;
+
 /**
  * Converter for the optional {@link ITemporalBlock}.
  * @public
  */
 export declare const temporalConverter: Converter<ITemporalBlock>;
 
+/**
+ * Identity codec for a versioned (temporal) kind family, resolving OQ-11 to the
+ * subtree-per-entity layout: every version of an entity is a distinct file under
+ * a per-entity subtree.
+ *
+ * @remarks
+ * - `encode`: scope = `<baseScope>/entities/<entityId>`, idStem = `<entityId>`,
+ *   `isVersioned = true`. The idStem is the stable entity prefix; the store forms
+ *   each version's filename via {@link TemporalIdentityCodec.encodeVersion}.
+ * - `encodeVersion`: version stem = `<entityId>-v<seq>`.
+ * - `decode` / `decodeVersion`: recover `entityId` (and `seq`) from a
+ *   `(subtree scope, version stem)` pair; the scope is authoritative for the
+ *   `entityId`.
+ * - Escaping: `baseScope` and `entityId` must each match the POSIX portable
+ *   filename set (they become path segments); `seq` is a non-negative integer.
+ * - Layout: `vault/<baseScope>/entities/<entityId>/<entityId>-v<seq>.md`.
+ * @public
+ */
+export declare class TemporalIdentityCodec implements ITemporalIdentityCodec {
+    /** The fixed subtree segment separating an entity's versions from its scope. */
+    static readonly entitiesSegment: string;
+    /** The version-stem infix: `<entityId>` + this + `<seq>`. */
+    static readonly versionInfix: string;
+    /** A non-negative integer string (the version seq). */
+    private static readonly _versionSeqRe;
+    /** The base scope segment this codec's entities live under. */
+    readonly baseScope: string;
+    private constructor();
+    /**
+     * Family-convention factory. Validates that `baseScope` is a single portable
+     * filename segment (it becomes the top-level path component).
+     */
+    static create(baseScope: string): Result<TemporalIdentityCodec>;
+    /** {@inheritDoc IIdentityCodec.encode} */
+    encode(entityId: EntityId): Result<IIdentityCodecResult>;
+    /** {@inheritDoc ITemporalIdentityCodec.encodeVersion} */
+    encodeVersion(entityId: EntityId, seq: number): Result<string>;
+    /** {@inheritDoc IIdentityCodec.decode} */
+    decode(scope: MemoryScopeKey, encodedStem: string): Result<EntityId>;
+    /** {@inheritDoc ITemporalIdentityCodec.decodeVersion} */
+    decodeVersion(scope: MemoryScopeKey, stem: string): Result<ITemporalVersionAddress>;
+    /** {@inheritDoc IIdentityCodec.verifyRoundTrip} */
+    verifyRoundTrip(scope: MemoryScopeKey, stem: string): Result<true>;
+    /** Validate and extract the `entityId` from a `<baseScope>/entities/<entityId>` scope. */
+    private _entityIdFromScope;
+}
+
 /**
  * Build the loud-degradation message a retriever returns when `query.asOf` is
  * set but no temporal index is wired.
@@ -1898,4 +2880,54 @@ export declare const temporalConverter: Converter<ITemporalBlock>;
  */
 export declare function temporalUnwiredMessage(kind?: Kind): string;
 
+/**
+ * Write policy for a versioned (temporal) kind family, implementing
+ * invalidate-don't-delete. Admission always accepts — history is retained, never
+ * culled — and updates apply the same RFC-7386 merge patch as
+ * {@link KnowledgeLwwPolicy}, restricted to the temporal mutable surface.
+ *
+ * @remarks
+ * The policy does NOT perform the version file writes or set `invalid_at` — that
+ * is the store's versioned write branch, driven by the kind's
+ * {@link ITemporalIdentityCodec}. The policy's role is limited to admission and
+ * the merge that forms the **new version's** content from the **current**
+ * version plus the incoming patch (the merge-patch-under-versioning contract).
+ *
+ * - **Dedup scope.** `'entity'` — an identical re-put of the current content is a
+ *   no-op (the store compares the incoming content hash against the current
+ *   version), so identical writes do not spawn redundant versions.
+ * - **Mutable surface.** `body` + the envelope metadata a consumer may revise
+ *   (`tags` / `links` / `provenance` / `embeddingRef`). `temporal` is NOT mutable
+ *   here — `valid_at` / `invalid_at` are set by the store's versioned branch.
+ * @public
+ */
+export declare class TemporalVersionedPolicy implements IWritePolicy {
+    /** The temporal mutable surface (mirrors {@link KnowledgeLwwPolicy}). */
+    readonly mutableFields: ReadonlyArray<string>;
+    /** Versioned kinds dedup per-entity against the current version (see the class remarks). */
+    readonly dedupScope: DedupScope;
+    /** Deep-clones the mutable view without RFC-7386 null-deletion semantics. */
+    private readonly _cloneEditor;
+    /** Applies the RFC-7386 merge patch. */
+    private readonly _mergeEditor;
+    private constructor();
+    /**
+     * Family-convention factory. Constructs the shared `JsonEditor` instances (one
+     * for cloning, one for the RFC-7386 merge), rules disabled — the same merge
+     * config as the shipped policies.
+     */
+    static create(): Result<TemporalVersionedPolicy>;
+    /** {@inheritDoc IWritePolicy.admit} */
+    admit(__incoming: IMemoryRecord<unknown>, __existing: ReadonlyArray<IMemoryRecord<unknown>>): Result<AdmissionDecision>;
+    /** {@inheritDoc IWritePolicy.applyUpdate} */
+    applyUpdate(existing: IMemoryRecord<unknown>, patch: Record<string, unknown>): Result<IMemoryRecord<unknown>>;
+    /**
+     * Reassemble a record from the merged mutable view. `body` / `tags` / `links` /
+     * `provenance` are required and may not be deleted by a patch; `embeddingRef`,
+     * when dropped by the merge, is restored as `undefined` (absent) — the same
+     * hash-stable semantics as {@link KnowledgeLwwPolicy}.
+     */
+    private _rebuild;
+}
+
 export { }