@oortmem/core 0.1.1 → 0.2.0

package/dist/recall.js

@@ -1,22 +1,28 @@
 import { activation } from './activation.js';
-import { fuse, isValid } from './fusion.js';
+import { fuse, isVisible } from './fusion.js';
 import { localGrant } from './grant.js';
 import { scrub } from './scrub.js';
+import { isCurrent } from './model.js';
+import { temporalIntent } from './temporal.js';
+import { isStale, lastConfirmed } from './volatile.js';
 import { CONFIDENT_COVERAGE, CONFIDENT_COVERAGE_GAP, informativeTokens, queryCoverage, } from './relevance.js';
 const clock = () => performance.now();
 /**
- * Hybrid recall: lexical + dense first stage, cold hydration, activation-aware
- * fusion, optional rerank. Adapter failures degrade, never throw; so do store
- * failures in the dense search and in cold hydration (lexical-only, with the
- * reason in `degraded`). The lexical search is the floor: its failure rejects.
+ * Hybrid recall: lexical + dense first stage, activation-aware fusion, optional
+ * rerank, relevance gate, then (only for what is returned, within `budgetChars`
+ * when set) cold hydration and the access record. Adapter failures degrade,
+ * never throw; so do store failures in the dense search, in cold hydration and
+ * in the access record (with the reason in `degraded`). The lexical search is
+ * the floor: its failure rejects.
  */
 export async function recall(q, deps) {
     const { store, config } = deps;
     // The store enforces scope; recall reads and hydrates only inside q.scope.
     const grant = localGrant(q.scope);
-    // Scrub once: the query text reaches embedders and rerankers, which may be remote.
-    const text = scrub(q.text).text;
     const now = deps.now ?? new Date();
+    // Scrub once: the query text reaches embedders and rerankers, which may be remote. Temporal
+    // words ("on 2 April", "changed over time") pick the view and are not searched for.
+    const { view, temporal, text } = viewFor(q, scrub(q.text).text, now);
     const t0 = clock();
     const degraded = [];
     const timings = {
@@ -56,7 +62,7 @@ export async function recall(q, deps) {
     let embedSkipped;
     if (deps.embed && config.recall.lexicalFirst) {
         const first = await lexicalP;
-        if (await lexicalIsConfident(first, queryTokens, read, now, q.asOf)) {
+        if (await lexicalIsConfident(first, queryTokens, read, now, view)) {
             embedSkipped = 'lexical-confident';
         }
     }
@@ -86,52 +92,16 @@ export async function recall(q, deps) {
                 return [];
             })),
     ]);
+    // Live rows only: a cold row keeps its text, stub and entities, which is all fusion, the gate
+    // and the reranker read. Hydration waits until we know what is returned (CON-47).
     const ids = [...new Set([...lexical, ...dense].map((h) => h.id))];
-    const coldIds = new Set([...lexical, ...dense].filter((h) => h.tier === 'cold').map((h) => h.id));
-    const th = clock();
-    const hydratedIds = new Set();
-    let hydrateFailed = false;
-    const loaded = await Promise.all(ids.map(async (id) => {
-        const live = await read(id);
-        if (live === null)
-            return null;
-        if (live.tier !== 'cold' && !coldIds.has(id))
-            return live;
-        try {
-            const blob = await store.coldGet(grant, id);
-            // A lost or torn blob: the memory stays cold, lexical-only.
-            // TODO(Phase 2): re-embed on hydration when an embedder is present.
-            if (!blob?.embedding)
-                return live;
-            const hydrated = {
-                ...live,
-                text: blob.text,
-                stub: blob.stub,
-                entities: blob.entities,
-                embedding: blob.embedding,
-                tier: 'warm',
-            };
-            await store.upsert(grant, hydrated);
-            hydratedIds.add(id);
-            return hydrated;
-        }
-        catch {
-            hydrateFailed = true;
-            return live;
-        }
-    }));
-    timings['hydrateMs'] = clock() - th;
-    if (hydrateFailed)
-        degraded.push('hydrate-failed');
+    const loaded = await Promise.all(ids.map((id) => read(id)));
     const memories = new Map();
     for (const m of loaded)
         if (m !== null)
             memories.set(m.id, m);
     const tf = clock();
-    const fused = fuse([lexical, dense], memories, now, {
-        activation: config.activation,
-        ...(q.asOf !== undefined ? { asOf: q.asOf } : {}),
-    });
+    const fused = fuse([lexical, dense], memories, now, { activation: config.activation, view });
     timings['fuseMs'] = clock() - tf;
     const coverage = new Map();
     for (const f of fused) {
@@ -218,14 +188,68 @@ export async function recall(q, deps) {
                 coverage: coverage.get(f.id) ?? 0,
                 ...(ds !== undefined ? { dense: ds } : {}),
                 activation: activation(m.accessLog, m.salience, now, config.activation),
-                hydrated: hydratedIds.has(f.id),
+                hydrated: false,
             },
         });
     }
-    await store.recordAccess(grant, out.map((m) => m.id), now);
+    let result = view.mode === 'history' ? await withChains(out, read, now, view, queryTokens, config) : out;
+    for (const m of result) {
+        if (isCurrent(m, now) && isStale(m, now, config.recall.staleAfterDays)) {
+            m.explanation.stale = true;
+        }
+    }
+    // With a budget, return only what the injection block holds, so nothing cut is touched below.
+    if (q.budgetChars !== undefined)
+        result = fitForInjection(result, q.budgetChars, now).kept;
+    // Touch only what is returned: the search's own hits (not chain-only versions). Cold ones that
+    // are current come back to warm; a version that is no longer current is shown from its live row,
+    // since consolidate would only send it back to cold.
+    const returned = new Set(result.map((m) => m.id));
+    const touched = new Set(out.filter((m) => returned.has(m.id)).map((m) => m.id));
+    const th = clock();
+    let hydrateFailed = false;
+    result = await Promise.all(result.map(async (m) => {
+        if (!touched.has(m.id) || m.tier !== 'cold' || !isCurrent(m, now))
+            return m;
+        try {
+            const blob = await store.coldGet(grant, m.id);
+            // A lost or torn blob: the memory stays cold, lexical-only.
+            // TODO(Phase 2): re-embed on hydration when an embedder is present.
+            if (!blob?.embedding)
+                return m;
+            const { explanation, ...live } = m;
+            const hydrated = {
+                ...live,
+                text: blob.text,
+                stub: blob.stub,
+                entities: blob.entities,
+                embedding: blob.embedding,
+                tier: 'warm',
+            };
+            await store.upsert(grant, hydrated);
+            return { ...hydrated, explanation: { ...explanation, hydrated: true } };
+        }
+        catch {
+            hydrateFailed = true;
+            return m;
+        }
+    }));
+    timings['hydrateMs'] = clock() - th;
+    if (hydrateFailed)
+        degraded.push('hydrate-failed');
+    // Access drives tiering, so it is recorded for the returned memories only. A failed write (e.g.
+    // SQLITE_BUSY) is reported, never a reason to lose the answer.
+    if (touched.size > 0) {
+        try {
+            await store.recordAccess(grant, [...touched], now);
+        }
+        catch {
+            degraded.push('access-failed');
+        }
+    }
     timings['totalMs'] = clock() - t0;
     return {
-        memories: out,
+        memories: result,
         ...(degraded.length > 0 ? { degraded } : {}),
         ...(out.length === 0 && candidates.length > 0 ? { abstained: true } : {}),
         ...(dropped > 0
@@ -239,9 +263,89 @@ export async function recall(q, deps) {
             : {}),
         ...(rerankSkipped !== undefined ? { rerankSkipped } : {}),
         ...(embedSkipped !== undefined ? { embedSkipped } : {}),
+        temporal,
         timings,
     };
 }
+/** The view a query asks for: explicit options first, else read from the query in code. */
+function viewFor(q, text, now) {
+    const at = (iso) => iso ?? now.toISOString();
+    let view;
+    let inferred = false;
+    let search = text;
+    if (q.mode !== undefined) {
+        view = { mode: q.mode };
+        if (q.mode === 'as-of')
+            view.asOf = at(q.asOf);
+        if (q.mode === 'known-at')
+            view.knownAt = at(q.knownAt);
+    }
+    else if (q.asOf !== undefined) {
+        view = { mode: 'as-of', asOf: q.asOf };
+    }
+    else if (q.knownAt !== undefined) {
+        view = { mode: 'known-at', knownAt: q.knownAt };
+    }
+    else {
+        const i = temporalIntent(text, now);
+        view = {
+            mode: i.mode,
+            ...(i.asOf !== undefined && { asOf: i.asOf }),
+            ...(i.knownAt !== undefined && { knownAt: i.knownAt }),
+        };
+        inferred = true;
+        search = i.text ?? text;
+    }
+    return { view, temporal: { ...view, inferred }, text: search };
+}
+/** Longest stretch of a supersede chain walked in each direction. */
+const CHAIN_MAX = 8;
+/**
+ * History mode: each recalled fact with the rest of its supersede chain, oldest first, the
+ * first-ranked chain first. Corrected versions are skipped (they were never true) but walked
+ * through. Versions only the walk found are marked `chain`.
+ */
+async function withChains(out, read, now, view, queryTokens, config) {
+    const byId = new Map(out.map((m) => [m.id, m]));
+    const seen = new Set();
+    const result = [];
+    for (const head of out) {
+        if (seen.has(head.id))
+            continue;
+        const links = [head];
+        for (const dir of ['supersedes', 'supersededBy']) {
+            let cur = head;
+            for (let n = 0; n < CHAIN_MAX; n++) {
+                const next = cur[dir];
+                if (next === null || seen.has(next) || links.some((l) => l.id === next))
+                    break;
+                const m = await read(next);
+                if (m === null)
+                    break;
+                links.push(m);
+                cur = m;
+            }
+        }
+        links.sort((a, b) => Date.parse(a.validFrom) - Date.parse(b.validFrom));
+        for (const m of links) {
+            seen.add(m.id);
+            if (!isVisible(m, now, view))
+                continue;
+            result.push(byId.get(m.id) ?? {
+                ...m,
+                explanation: {
+                    fused: 0,
+                    rrf: 0,
+                    coverage: queryCoverage(queryTokens, m),
+                    activation: activation(m.accessLog, m.salience, now, config.activation),
+                    hydrated: false,
+                    chain: true,
+                },
+            });
+        }
+    }
+    return result;
+}
 const TIMED_OUT = Symbol('timed-out');
 const RERANK_TIMEOUT = new Error('rerank-timeout');
 /** `p`, or `TIMED_OUT` after `ms` (0: no limit). A late result is dropped, never rejected. */
@@ -268,14 +372,14 @@ async function withBudget(p, ms) {
  * informative words, the top lexical hit is valid now (or at `asOf`) and holds every one of them,
  * and the next hit holds clearly fewer. Dense search could only confirm such a result.
  */
-async function lexicalIsConfident(lexical, queryTokens, read, now, asOf) {
+async function lexicalIsConfident(lexical, queryTokens, read, now, view) {
     if (queryTokens.size < 2)
         return false;
     const top = lexical[0];
     if (top === undefined)
         return false;
     const m = await read(top.id);
-    if (m === null || !isValid(m, now, asOf))
+    if (m === null || !isVisible(m, now, view))
         return false;
     if (queryCoverage(queryTokens, m) < 1)
         return false;
@@ -308,6 +412,14 @@ function isConfident(ordered, lexical, dense, coverage) {
         return true;
     return (coverage.get(second.id) ?? 0) <= topCov - CONFIDENT_COVERAGE_GAP;
 }
+const ymd = (iso) => iso.slice(0, 10);
+/** How a memory is dated in the block: its age when current, else the interval it held. */
+function when(m, now) {
+    if (isCurrent(m, now))
+        return age(m.validFrom, now);
+    const span = `${ymd(m.validFrom)} to ${m.validTo === null ? 'now' : ymd(m.validTo)}`;
+    return m.endReason === 'corrected' ? `${span}, later corrected` : span;
+}
 function age(validFrom, now) {
     const days = Math.max(0, Math.floor((now.getTime() - Date.parse(validFrom)) / 86_400_000));
     if (days < 1)
@@ -328,22 +440,33 @@ function age(validFrom, now) {
  * memory stored before a rule existed, written by another tool, or missed by a regression.
  */
 export function formatForInjection(r, budgetChars, now = new Date()) {
-    if (r.memories.length === 0)
+    const { lines } = fitForInjection(r.memories, budgetChars, now);
+    if (lines.length === 0)
         return '';
-    const open = '<oort-memory>\n';
-    const close = '\n</oort-memory>';
-    let total = open.length + close.length;
+    return INJECT_OPEN + lines.join('\n') + INJECT_CLOSE;
+}
+const INJECT_OPEN = '<oort-memory>\n';
+const INJECT_CLOSE = '\n</oort-memory>';
+/**
+ * The memories `formatForInjection` renders within `budgetChars`, in order (a prefix: whole
+ * lines only, stopping at the first that does not fit), with their lines.
+ */
+export function fitForInjection(memories, budgetChars, now = new Date()) {
+    let total = INJECT_OPEN.length + INJECT_CLOSE.length;
     const lines = [];
-    for (const m of r.memories) {
-        const line = `- [${m.type}, ${age(m.validFrom, now)}] ${scrub(m.text).text}`;
+    const kept = [];
+    for (const m of memories) {
+        const note = m.explanation.stale === true
+            ? ` (may be outdated; last confirmed ${age(lastConfirmed(m), now)})`
+            : '';
+        const line = `- [${m.type}, ${when(m, now)}] ${scrub(m.text).text}${note}`;
         const cost = line.length + (lines.length > 0 ? 1 : 0);
         if (total + cost > budgetChars)
             break;
         lines.push(line);
+        kept.push(m);
         total += cost;
     }
-    if (lines.length === 0)
-        return '';
-    return open + lines.join('\n') + close;
+    return { kept, lines };
 }
 //# sourceMappingURL=recall.js.map

package/dist/scope.d.ts

@@ -1,7 +1,21 @@
 import type { Scope } from './model.js';
 export type { Scope };
 export declare function localScope(projectId?: string): Scope;
-/** Walk up from `start` to the first directory containing `.git`. */
+/**
+ * `p` resolved, then realpathed by the OS (`realpath(3)`), or `p` resolved when
+ * it cannot be (it vanished, a permission error). The native call returns the
+ * spelling on disk, so on a case-insensitive filesystem (APFS, HFS+, NTFS)
+ * `~/Repos/Oort` and `~/repos/oort` give one path, where `fs.realpathSync`
+ * would keep the case as typed and split one repository into two project ids.
+ * Every path that feeds an id or a trust binding goes through this.
+ */
+export declare function canonicalPath(p: string): string;
+/**
+ * Walk up from `start` to the first directory containing `.git`. The walk
+ * starts from `start` realpathed, as git does (it walks from the physical
+ * cwd): a symlink inside one repository that leads into another must land on
+ * the other, never on the repository the symlink happens to sit in.
+ */
 export declare function findGitRoot(start: string): string | undefined;
 /** The main repository root above `cwd` (a linked worktree resolves to its main checkout). */
 export declare function projectRootFor(cwd: string): string | undefined;
@@ -24,11 +38,12 @@ export declare const PROJECT_LINKS_FILE = "project-links.json";
 export declare function readProjectLinks(home: string): Record<string, string>;
 /**
  * Binds main repository root `root` to project id `id` (unprefixed) in the
- * user's trust file (0600). The key is `root` realpathed, the form
- * `projectRootFor` returns, so a binding made through a symlink still applies.
+ * user's trust file (0600). The key is `canonicalPath(root)`, the form
+ * `projectRootFor` returns, so a binding made through a symlink or with other
+ * case still applies.
  */
 export declare function linkProject(home: string, root: string, id: string): void;
-/** Removes `root`'s binding (realpathed, as `linkProject` keys it); false when there was none. */
+/** Removes `root`'s binding (canonicalised, as `linkProject` keys it); false when there was none. */
 export declare function unlinkProject(home: string, root: string): boolean;
 export interface ProjectResolution {
     /** The project id, or undefined outside a repository. */

package/dist/scope.js

@@ -9,9 +9,31 @@ export function localScope(projectId) {
         scope.projectId = projectId;
     return scope;
 }
-/** Walk up from `start` to the first directory containing `.git`. */
+/**
+ * `p` resolved, then realpathed by the OS (`realpath(3)`), or `p` resolved when
+ * it cannot be (it vanished, a permission error). The native call returns the
+ * spelling on disk, so on a case-insensitive filesystem (APFS, HFS+, NTFS)
+ * `~/Repos/Oort` and `~/repos/oort` give one path, where `fs.realpathSync`
+ * would keep the case as typed and split one repository into two project ids.
+ * Every path that feeds an id or a trust binding goes through this.
+ */
+export function canonicalPath(p) {
+    const resolved = path.resolve(p);
+    try {
+        return fs.realpathSync.native(resolved);
+    }
+    catch {
+        return resolved;
+    }
+}
+/**
+ * Walk up from `start` to the first directory containing `.git`. The walk
+ * starts from `start` realpathed, as git does (it walks from the physical
+ * cwd): a symlink inside one repository that leads into another must land on
+ * the other, never on the repository the symlink happens to sit in.
+ */
 export function findGitRoot(start) {
-    let dir = path.resolve(start);
+    let dir = canonicalPath(start);
     for (;;) {
         if (fs.existsSync(path.join(dir, '.git')))
             return dir;
@@ -21,15 +43,6 @@ export function findGitRoot(start) {
         dir = parent;
     }
 }
-/** `p` realpathed, or `p` itself when it cannot be (it vanished, a permission error). */
-function realOr(p) {
-    try {
-        return fs.realpathSync(p);
-    }
-    catch {
-        return p;
-    }
-}
 /**
  * The main repository root for a checkout root, always realpathed, so derived
  * ids and trust bindings agree however the checkout was reached. A `.git`
@@ -47,10 +60,23 @@ function realOr(p) {
  * from that verified `commonDir` and nothing else: a lexical resolution of the
  * written path could run through an attacker's symlink to another repository.
  * Any mismatch, missing file or read error (a submodule has no `commondir`)
- * falls back to `root` itself.
+ * falls back to `root` itself. That includes a stale worktree whose main
+ * checkout was moved or deleted (its `gitdir` no longer exists) or replaced
+ * by an unrelated repository (no back-pointer naming this checkout): it gets
+ * the id of its own root, never an error and never the new repository's id.
+ *
+ * Stale admin dirs (decided for CON-53): a worktree deleted without
+ * `git worktree prune` leaves `<commonDir>/worktrees/<name>/` behind, so a
+ * directory recreated at exactly that path with the same `.git` file passes
+ * both checks and shares the main repository's id. This matches git, which
+ * treats that directory as the worktree and serves it the main repository's
+ * objects and refs, so the id grants nothing git does not already. An mtime
+ * rule (the admin `gitdir` no older than the checkout's `.git`) was rejected:
+ * `git worktree add` writes `gitdir` before `.git`, so it would refuse every
+ * fresh worktree, and an extracted archive sets whatever mtimes it carries.
  */
 function mainRootOf(root) {
-    const own = realOr(root);
+    const own = canonicalPath(root);
     const dotGit = path.join(root, '.git');
     try {
         // A symlinked `.git` (to a file or a directory) never inherits another
@@ -63,11 +89,11 @@ function mainRootOf(root) {
         const m = /^gitdir:\s*(.+?)\s*$/m.exec(fs.readFileSync(dotGit, 'utf8'));
         if (m?.[1] === undefined)
             return own;
-        const gitdir = fs.realpathSync(path.resolve(root, m[1]));
+        const gitdir = fs.realpathSync.native(path.resolve(root, m[1]));
         const common = fs.readFileSync(path.join(gitdir, 'commondir'), 'utf8').trim();
         if (common === '')
             return own;
-        const commonDir = fs.realpathSync(path.resolve(gitdir, common));
+        const commonDir = fs.realpathSync.native(path.resolve(gitdir, common));
         if (!fs.statSync(commonDir).isDirectory())
             return own;
         if (path.dirname(gitdir) !== path.join(commonDir, 'worktrees'))
@@ -76,7 +102,7 @@ function mainRootOf(root) {
         if (back === '')
             return own;
         // The back-pointer must name this checkout's own `.git`, not wherever it leads.
-        if (fs.realpathSync(path.resolve(gitdir, back)) !== path.join(own, '.git'))
+        if (fs.realpathSync.native(path.resolve(gitdir, back)) !== path.join(own, '.git'))
             return own;
         return path.basename(commonDir) === '.git' ? path.dirname(commonDir) : commonDir;
     }
@@ -134,18 +160,19 @@ function writeProjectLinks(home, links) {
 }
 /**
  * Binds main repository root `root` to project id `id` (unprefixed) in the
- * user's trust file (0600). The key is `root` realpathed, the form
- * `projectRootFor` returns, so a binding made through a symlink still applies.
+ * user's trust file (0600). The key is `canonicalPath(root)`, the form
+ * `projectRootFor` returns, so a binding made through a symlink or with other
+ * case still applies.
  */
 export function linkProject(home, root, id) {
     if (id === '' || [...id].some((c) => c.charCodeAt(0) < 0x20)) {
         throw new RangeError('project id must be non-empty, without control characters');
     }
-    writeProjectLinks(home, { ...readProjectLinks(home), [realOr(root)]: id });
+    writeProjectLinks(home, { ...readProjectLinks(home), [canonicalPath(root)]: id });
 }
-/** Removes `root`'s binding (realpathed, as `linkProject` keys it); false when there was none. */
+/** Removes `root`'s binding (canonicalised, as `linkProject` keys it); false when there was none. */
 export function unlinkProject(home, root) {
-    root = realOr(root);
+    root = canonicalPath(root);
     const links = readProjectLinks(home);
     if (!(root in links))
         return false;

package/dist/store-conformance.js

@@ -141,6 +141,71 @@ export function storeConformance(name, make) {
             await store.upsertMany(TG, [{ ...makeMemory({ id: 'c2' }), tier: 'hot' }]);
             expect(await store.coldGet(TG, 'c2')).toBeNull();
         });
+        it('temporal-fields-roundtrip', async () => {
+            // CON-34/49: confirmation, correction and the new decision stages survive a round trip.
+            const m = makeMemory({
+                id: 't1',
+                text: 'auth listens on port 3000',
+                embedding: vec(1, 2, 3, 4),
+                validFrom: '2026-01-01T00:00:00.000Z',
+                validTo: '2026-02-01T00:00:00.000Z',
+                expiredAt: '2026-01-15T00:00:00.000Z',
+                endReason: 'corrected',
+                lastConfirmedAt: '2026-01-10T08:30:00.000Z',
+                supersededBy: 't2',
+                source: {
+                    harness: 'test',
+                    turnRef: 'turn-9',
+                    decisions: [
+                        { stage: 'gate', question: 'volatile', answer: 'yes', probability: 0.8 },
+                        {
+                            stage: 'temporal',
+                            question: 'interval',
+                            answer: 'turn .. 2026-02-01',
+                            probability: 1,
+                        },
+                        {
+                            stage: 'temporal',
+                            question: 'writer-date',
+                            answer: '2026-01-02 -> 2026-01-03',
+                            probability: 1,
+                        },
+                        {
+                            stage: 'refine',
+                            question: 'previous-text',
+                            answer: 'auth on 3000',
+                            probability: 0.7,
+                        },
+                        { stage: 'write', question: 'action', answer: 'CORRECT', probability: 0.9 },
+                    ],
+                },
+            });
+            await store.upsert(TG, m);
+            expect(await store.get(TG, 't1')).toEqual(m);
+        });
+        it('refine-in-place-of-a-cold-record-stays-consistent', async () => {
+            // A REFINE rewrites a cold memory in place and promotes it: the cold copy goes, so a later
+            // hydration cannot bring the old wording back.
+            const m = makeMemory({ id: 'r1', text: 'auth on port 3000', embedding: vec(1, 2, 3, 4) });
+            await seedCold(store, m);
+            const cold = await store.get(TG, 'r1');
+            if (cold === null)
+                throw new Error('coldPut lost the main record');
+            expect(cold.tier).toBe('cold');
+            const refined = {
+                ...cold,
+                text: 'auth on port 3000 over TLS',
+                stub: 'auth port TLS',
+                embedding: vec(4, 3, 2, 1),
+                tier: 'warm',
+                lastConfirmedAt: '2026-01-10T00:00:00.000Z',
+                updatedAt: '2026-01-10T00:00:00.000Z',
+            };
+            await store.upsert(TG, refined);
+            expect(await store.get(TG, 'r1')).toEqual(refined);
+            expect(await store.coldGet(TG, 'r1')).toBeNull();
+            expect((await store.lexical(TG, 'TLS', 5)).map((h) => h.id)).toEqual(['r1']);
+        });
         it('cold-put-many-roundtrip', async () => {
             const a = makeMemory({ id: 'a', text: 'alpha', embedding: vec(1, 2, 3, 4) });
             const b = makeMemory({ id: 'b', text: 'beta', tier: 'hot', embedding: vec(4, 3, 2, 1) });
@@ -442,6 +507,20 @@ export function storeConformance(name, make) {
             ]);
             expect(ids(await store.list(localGrant(LOCAL), { tier: 'hot' }))).toEqual(['old']);
         });
+        it('list-pinned-only-and-without-embeddings', async () => {
+            await store.upsert(TG, makeMemory({ id: 'pin', pinned: true, embedding: vec(1, 2, 3, 4) }));
+            await store.upsert(TG, makeMemory({ id: 'hot', tier: 'hot', embedding: vec(1, 2, 3, 4) }));
+            await store.upsert(TG, makeMemory({ id: 'plain', embedding: vec(1, 2, 3, 4) }));
+            expect(ids(await store.list(localGrant(LOCAL), { pinned: true }))).toEqual(['pin']);
+            expect(ids(await store.list(localGrant(LOCAL), { pinned: true, tier: 'hot' }))).toEqual([]);
+            // Callers that only read text and metadata (SessionStart) skip the embedding fetch.
+            const bare = await store.list(localGrant(LOCAL), { embeddings: false });
+            expect(bare).toHaveLength(3);
+            for (const m of bare)
+                expect(m.embedding).toBeUndefined();
+            const full = await store.list(localGrant(LOCAL), { tier: 'hot' });
+            expect(full[0]?.embedding).toEqual(vec(1, 2, 3, 4));
+        });
         it('list-valid-only-uses-isCurrent', async () => {
             await store.upsert(TG, makeMemory({ id: 'future', validTo: '2999-01-01T00:00:00.000Z' }));
             await store.upsert(TG, makeMemory({

package/dist/temporal.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The UTC offset, in minutes, an ISO timestamp states (`+02:00` is 120, `Z` is 0), or
+ * undefined when it states none.
+ */
+export declare function utcOffset(iso: string): number | undefined;
+export interface FactInterval {
+    /** ISO start of the fact's validity, when the text bounds it ("since", "starting"). */
+    validFrom?: string;
+    /** ISO end (exclusive) of the fact's validity, when the text bounds it ("until Friday"). */
+    validTo?: string;
+}
+/**
+ * The validity bounds a written memory states about itself, resolved against `at` (the turn's
+ * time) in `offset` minutes east of UTC. "Until Friday" ends the fact after that Friday, and an
+ * end in the past is kept (the fact is stored already ended). "Starting next week" looks ahead,
+ * "since last Monday" looks back, and "as of", "effective" or "from" take the closer reading
+ * within a week, else the past one. "From Monday to Friday" is a schedule, not a start. A plain
+ * date ("on 2026-11-03 we chose pnpm") dates an event and sets no bound. An end at or before a
+ * stated start contradicts it and is dropped.
+ */
+export declare function factInterval(text: string, at: Date, offset?: number): FactInterval;
+export interface WriterDateCheck {
+    text: string;
+    /** The written day was replaced by the resolved one. */
+    fixed?: {
+        from: string;
+        to: string;
+    };
+    /** The written day differs from the resolved one but was kept (a stated or distant date). */
+    mismatch?: {
+        written: string;
+        resolved: string;
+    };
+}
+/**
+ * Checks the writer's absolute date against the turn. When the turn names exactly one relative
+ * day ("yesterday") and the written fact carries exactly one ISO day, that day should be
+ * chrono's reading of the relative one. It is replaced only when it looks like an arithmetic
+ * slip: within two days of the reading, and not a date the turn itself states. Otherwise the
+ * difference is reported in `mismatch` and the text is kept ("Today we agreed the cutover is
+ * 2026-12-01" is about the cutover, not today).
+ */
+export declare function checkWriterDate(turnText: string, factText: string, at: Date, offset?: number): WriterDateCheck;
+export type RecallMode = 'current' | 'as-of' | 'history' | 'known-at';
+export interface TemporalIntent {
+    mode: RecallMode;
+    /** For `as-of`: the end of the day the query names. */
+    asOf?: string;
+    /** For `known-at`: the end of the day the query names. */
+    knownAt?: string;
+    /** The query without its temporal words, to search with; absent when nothing was removed. */
+    text?: string;
+}
+/**
+ * A cheap read of a query's temporal intent, in code: "what did we believe … on <day>" is
+ * known-at that day; an anchored history question ("how has X changed") asks for the chain; a
+ * past day with a cue ("on 2 April 2026", "in March", "yesterday") is as-of that day; anything
+ * else, including "now", coming weekdays and other future days, is the current state. A month
+ * and day with no year that reads more than 30 days ahead means the last one ("in March" asked
+ * in November is this year's March).
+ */
+export declare function temporalIntent(query: string, now: Date): TemporalIntent;