wingfoil 0.2.2 → 0.3.0

package/dist/memory/query.js

@@ -1,14 +1,24 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.E_EMPTY_SEARCH_QUERY = void 0;
+exports.E_EMPTY_SEARCH_QUERY = exports.W_MEMORY_UNREADABLE = void 0;
 exports.computeMemoryContentRoots = computeMemoryContentRoots;
+exports.memoryUnreadableDiagnostic = memoryUnreadableDiagnostic;
+exports.firstLineOf = firstLineOf;
 exports.listMemoryDocumentPaths = listMemoryDocumentPaths;
 exports.loadMemoryDocumentSummary = loadMemoryDocumentSummary;
+exports.loadMemoryDocuments = loadMemoryDocuments;
+exports.listMemoryDocumentPathsAtRev = listMemoryDocumentPathsAtRev;
+exports.loadMemoryDocumentsAtRev = loadMemoryDocumentsAtRev;
+exports.loadMemoryDocumentsAtCommit = loadMemoryDocumentsAtCommit;
+exports.loadMemoryDocumentSummaryAtRev = loadMemoryDocumentSummaryAtRev;
 exports.findMemoryDocumentById = findMemoryDocumentById;
+exports.findMemoryDocumentByIdAtRev = findMemoryDocumentByIdAtRev;
 exports.listMemoryDocumentsByType = listMemoryDocumentsByType;
 exports.findMemoryDocumentByTypeAndId = findMemoryDocumentByTypeAndId;
+exports.findMemoryDocumentByTypeAndIdAtRev = findMemoryDocumentByTypeAndIdAtRev;
 exports.validateSearchQuery = validateSearchQuery;
 exports.searchMemoryDocuments = searchMemoryDocuments;
+exports.loadTypeDocumentCopiesAtRevs = loadTypeDocumentCopiesAtRevs;
 /**
  * Memory query primitives (task-008-dna-memory-query-latency, REQ-PERF-02; match/rank algorithm and
  * empty-query validation hardened by task-023-implement-keyword-search, P1.12) — the performance-
@@ -53,12 +63,34 @@ exports.searchMemoryDocuments = searchMemoryDocuments;
  * `draft` is deliberately NOT excluded here: spec-012 §6 excludes drafts from an assembled agent
  * *context*, but REQ-STATE-06 scopes default-search exclusion to archived content only, so a draft
  * document a user is actively working on stays findable. The two filters are different sets on purpose.
+ *
+ * **Fail closed on archived elements (task-171, `dl-038` option 1).** {@link listMemoryDocumentsByType}
+ * and {@link findMemoryDocumentByTypeAndId} (and its `…AtRev` sibling) exclude archived documents by
+ * default too, so a consumer that forgets to filter does not reach them; the one that must —
+ * `wingfoil://memory/{type}/{id}` — passes `includeArchived: true`. {@link findMemoryDocumentById}
+ * stays neutral: `memory history` and the transition verbs act on archived elements.
+ *
+ * **Tolerant reads (task-171, `bug-031`, `spec-017` §1.4).** A scan never throws on a document it
+ * cannot read. A document whose frontmatter does not parse, and a symbolic link (never followed and
+ * never parsed, by either baseline, `bug-189`), are left out and reported to the caller's
+ * {@link MemoryScanOptions.onDiagnostic} as {@link W_MEMORY_UNREADABLE}, in path order. Only the
+ * single-file read {@link loadMemoryDocumentSummary} still throws: its caller named that file.
+ *
+ * **The `format` key (task-257, `bug-241`, `dl-149`).** An element keeps the `format` of the template
+ * it was copied from and reads with that counter, `MEMORY_TEMPLATE_FORMAT`; absent reads as `1`. An
+ * element written in a newer format is not read by today's rules: a collection scan leaves it out and
+ * reports it as {@link W_MEMORY_UNREADABLE}, naming the file and the "upgrade WingFoil" refusal; a
+ * single-file read, and a lookup by id that reaches the element it names, throw that refusal
+ * (`ValidationError`, `E_INVALID_FORMAT`, exit `1`); a lookup reports one it passes on its way.
  */
 const fs_1 = require("fs");
 const path_1 = require("path");
 const validation_1 = require("../validation");
 const state_machine_1 = require("./state-machine");
 const storage_1 = require("../storage");
+// The module, not the `../core` barrel: `src/core` imports this module, and `./revision` depends on
+// `../storage` alone, so nothing here closes a load-time cycle.
+const revision_1 = require("../core/revision");
 /**
  * The static (placeholder-free) directory prefix of a `memory.yaml` type `path` pattern — e.g.
  * `"docs/04_memory/design/adrs/{id}.md"` -> `"docs/04_memory/design/adrs"`. A pattern whose first
@@ -88,8 +120,43 @@ function computeMemoryContentRoots(memoryYaml) {
     const all = [...dirs].sort();
     return all.filter((dir) => !all.some((other) => other !== dir && dir.startsWith(`${other}/`)));
 }
-/** Recursively list every `.md` file under `root/dir`, as root-relative POSIX paths, sorted. */
-function listMarkdownFilesUnder(root, dir) {
+/** `W_MEMORY_UNREADABLE` (`spec-017` §1.4, §2): a Memory file a scan left out because it cannot read it. */
+exports.W_MEMORY_UNREADABLE = 'W_MEMORY_UNREADABLE';
+/** The reason {@link W_MEMORY_UNREADABLE} gives for a symbolic link (task-171, `bug-189`). */
+const SYMLINK_REASON = 'a symbolic link is not read as a Memory document';
+/**
+ * The one builder of a {@link W_MEMORY_UNREADABLE} diagnostic, shared by the scan here and by
+ * `spec-017`'s deduction: `spec-003`'s shape, `file` repository-relative, `path` `''` (the whole file),
+ * and `spec-017` §1.4's message `unreadable frontmatter in <file>: <reason>`.
+ */
+function memoryUnreadableDiagnostic(file, reason) {
+    return { code: exports.W_MEMORY_UNREADABLE, severity: 'warning', file, path: '', message: `unreadable frontmatter in ${file}: ${reason}` };
+}
+/** The first line of a parse error: js-yaml appends a multi-line excerpt a one-line warning cannot carry. */
+function firstLineOf(message) {
+    return message.split('\n')[0].trim();
+}
+/**
+ * Code-unit order of two strings, as `Array.prototype.sort()` orders them by default, written without
+ * a branch: `1`, `0` or `-1`.
+ */
+function compareText(a, b) {
+    return Number(a > b) - Number(a < b);
+}
+/** Ascending by path. */
+function byPath(a, b) {
+    return compareText(a.path, b.path);
+}
+/**
+ * Recursively list every `.md` entry under `root/dir`, as root-relative POSIX paths, sorted.
+ *
+ * One rule with the read at a commit (task-171, `bug-189`): a symbolic link is never followed — a
+ * `.md` link is listed as a link, so the caller can report it, and a link to a directory is not
+ * entered — and a directory holding `.git` (a nested repository, which a commit records as a gitlink
+ * at most) is not entered. With `followSymlinks` the walk is the pre-task-171 one, for
+ * {@link MemoryIdLookupOptions.followSymlinks}'s explain-only use.
+ */
+function listMarkdownFilesUnder(root, dir, followSymlinks) {
     const absoluteDir = (0, path_1.join)(root, dir);
     if (!(0, fs_1.existsSync)(absoluteDir) || !(0, fs_1.statSync)(absoluteDir).isDirectory())
         return [];
@@ -98,47 +165,275 @@ function listMarkdownFilesUnder(root, dir) {
         for (const entry of (0, fs_1.readdirSync)(current).sort()) {
             const full = (0, path_1.join)(current, entry);
             const relative = `${relativePrefix}/${entry}`;
-            if ((0, fs_1.statSync)(full).isDirectory()) {
+            const own = (0, fs_1.lstatSync)(full);
+            if (own.isSymbolicLink() && !followSymlinks) {
+                if (entry.endsWith('.md'))
+                    out.push({ path: relative, symlink: true });
+                continue;
+            }
+            // Following (explain-only): a dangling link names nothing to read, so it is passed over.
+            if (own.isSymbolicLink() && !(0, fs_1.existsSync)(full))
+                continue;
+            const stats = own.isSymbolicLink() ? (0, fs_1.statSync)(full) : own;
+            if (stats.isDirectory()) {
+                if (!followSymlinks && (0, fs_1.existsSync)((0, path_1.join)(full, '.git')))
+                    continue;
                 walk(full, relative);
             }
             else if (entry.endsWith('.md')) {
-                out.push(relative);
+                out.push({ path: relative, symlink: false });
             }
         }
     };
     walk(absoluteDir, dir);
     return out;
 }
+/** Every `.md` entry under the scan roots of `memoryYaml`, sorted, links marked (see {@link listMarkdownFilesUnder}). */
+function scanWorkingTree(root, memoryYaml, followSymlinks = false) {
+    const out = new Map();
+    for (const dir of computeMemoryContentRoots(memoryYaml)) {
+        for (const file of listMarkdownFilesUnder(root, dir, followSymlinks))
+            out.set(file.path, file);
+    }
+    return [...out.values()].sort(byPath);
+}
 /**
  * List every Memory document under `root`, as root-relative POSIX paths, sorted lexicographically
  * (REQ-SYS-07 — deterministic, no unordered iteration). Scans only the directories
- * {@link computeMemoryContentRoots} derives from `memoryYaml`, never the whole project tree.
+ * {@link computeMemoryContentRoots} derives from `memoryYaml`, never the whole project tree. A
+ * symbolic link is not a document and is not listed (task-171, `bug-189`), the same as
+ * {@link listMemoryDocumentPathsAtRev} at a commit.
  */
 function listMemoryDocumentPaths(root, memoryYaml) {
-    const out = new Set();
-    for (const dir of computeMemoryContentRoots(memoryYaml)) {
-        for (const path of listMarkdownFilesUnder(root, dir))
-            out.add(path);
-    }
-    return [...out].sort();
+    return scanWorkingTree(root, memoryYaml)
+        .filter((file) => !file.symlink)
+        .map((file) => file.path);
 }
 /**
  * Read one Memory document and split it into its parsed frontmatter and body text, without running
  * it through any type's Zod schema — `memory search`/`history` must handle documents of every type
  * and any (even structurally imperfect) state, so this is a read, never a validation.
+ *
+ * This single-file read **throws** `ValidationError` (`E_YAML_PARSE_ERROR`) when the frontmatter does
+ * not parse: its caller named the file. The scans built on it are what is tolerant (task-171,
+ * `bug-031`): each one leaves such a document out and reports it as {@link W_MEMORY_UNREADABLE} to its
+ * {@link MemoryScanOptions.onDiagnostic}, so one malformed document never fails a query about another.
  */
 function loadMemoryDocumentSummary(root, relativePath) {
     const absolute = (0, path_1.join)(root, relativePath);
-    const raw = (0, storage_1.readDocument)(absolute);
+    return refuseNewerElement(parseMemoryDocument((0, storage_1.readDocument)(absolute), relativePath, absolute));
+}
+/**
+ * A Memory document's bytes split into parsed frontmatter and body — the one parse both baselines use
+ * ({@link loadMemoryDocumentSummary} for the working tree, {@link loadMemoryDocumentsAtRev} and its
+ * siblings for a commit), so they cannot drift on what a document *is*. `label` is what a parse error
+ * names: the absolute path, or `<rev>:<path>`.
+ */
+function parseMemoryDocument(raw, relativePath, label) {
     const { frontmatter: frontmatterText, body } = (0, storage_1.splitFrontmatter)(raw);
     let frontmatter = {};
     if (frontmatterText) {
-        const parsed = (0, validation_1.parseYaml)(frontmatterText, absolute);
+        const parsed = (0, validation_1.parseYaml)(frontmatterText, label);
         if (parsed !== null && typeof parsed === 'object')
             frontmatter = parsed;
     }
     return { path: relativePath, frontmatter, body };
 }
+/**
+ * The `format` check of an element (`dl-149`, task-257, `bug-241`): `E_INVALID_FORMAT` on `format`
+ * when the document's frontmatter declares a format newer than this build reads, else `null`. An
+ * element is its template's copy (`spec-001`: the scaffold is copied verbatim, `format` line included),
+ * and keeps the format its template carries (approver ruling at the W2 B2 gate, task-251 decision 4),
+ * so it reads with the template's counter, `MEMORY_TEMPLATE_FORMAT`. An absent `format` reads as `1`.
+ * The issue names the repository-relative path, whichever baseline was read, as a scan diagnostic does.
+ *
+ * Only a newer format is checked here. The element read is loose by design (no type's schema runs on
+ * it, see {@link loadMemoryDocumentSummary}), so a `format` that is not a positive integer is left to
+ * the rules that validate an element's frontmatter, as every other field is.
+ */
+function newerElementFormat(summary) {
+    return (0, validation_1.newerFormatIssue)(summary.frontmatter, validation_1.MEMORY_TEMPLATE_FORMAT, summary.path);
+}
+/**
+ * `summary`, or the `dl-149` refusal of it as a `ValidationError` at exit `1` when it is written in a
+ * newer format: a read whose caller named this document — a single-file read, or a lookup that reached
+ * the element it looks for — refuses it, where a scan reports it ({@link readableDocuments}).
+ */
+function refuseNewerElement(summary) {
+    const newer = newerElementFormat(summary);
+    if (newer !== null)
+        throw new validation_1.ValidationError([newer], validation_1.EXIT_VALIDATION);
+    return summary;
+}
+/** The {@link W_MEMORY_UNREADABLE} report of a document written in a newer format: the file and the `dl-149` refusal. */
+function newerFormatDiagnostic(newer) {
+    return memoryUnreadableDiagnostic(newer.file, `${newer.code}: ${newer.message}`);
+}
+/**
+ * {@link parseMemoryDocument} for a scan: the document with its format check, or `undefined` after
+ * reporting it as {@link W_MEMORY_UNREADABLE} when its frontmatter does not parse. The diagnostic names
+ * the repository-relative path, whichever baseline was read.
+ */
+function parseScanned(raw, relativePath, label, options) {
+    let summary;
+    try {
+        summary = parseMemoryDocument(raw, relativePath, label);
+    }
+    catch (error) {
+        // `parseYaml` is the only thing in the parse that throws, and it throws only
+        // `ValidationError.yamlParse`, whose one issue carries the parser's message.
+        const parseError = error.issues[0];
+        options.onDiagnostic?.(memoryUnreadableDiagnostic(relativePath, firstLineOf(parseError.message)));
+        return undefined;
+    }
+    return { summary, newer: newerElementFormat(summary) };
+}
+/**
+ * The documents of a scan a **collection** reader may use: one written in a newer format is left out
+ * and reported as {@link W_MEMORY_UNREADABLE}, naming the file and the `dl-149` refusal (task-257,
+ * `bug-241`), so it is neither read by today's rules nor dropped silently.
+ */
+function* readableDocuments(documents, options) {
+    for (const { summary, newer } of documents) {
+        if (newer !== null) {
+            options.onDiagnostic?.(newerFormatDiagnostic(newer));
+            continue;
+        }
+        yield summary;
+    }
+}
+/**
+ * The first document of a scan whose frontmatter `matches`, for a **lookup**: the caller named that
+ * element, so one written in a newer format is refused (`ValidationError`, `E_INVALID_FORMAT`, exit
+ * `1`), as a single-file read refuses it; a newer-format document the lookup passes on its way is
+ * reported, as a collection scan reports it (task-257, `bug-241`).
+ */
+function findFirst(documents, matches, options) {
+    for (const { summary, newer } of documents) {
+        if (matches(summary.frontmatter))
+            return refuseNewerElement(summary);
+        if (newer !== null)
+            options.onDiagnostic?.(newerFormatDiagnostic(newer));
+    }
+    return undefined;
+}
+/**
+ * The working-tree scan every tolerant reader is built on: each document under the scan roots, parsed,
+ * lazily and in path order, so a lookup can stop at its match. A link and an unparsable document are
+ * reported and skipped.
+ */
+function* scanWorkingTreeDocuments(root, memoryYaml, options) {
+    for (const file of scanWorkingTree(root, memoryYaml, options.followSymlinks === true)) {
+        if (file.symlink) {
+            options.onDiagnostic?.(memoryUnreadableDiagnostic(file.path, SYMLINK_REASON));
+            continue;
+        }
+        const absolute = (0, path_1.join)(root, file.path);
+        const summary = parseScanned((0, storage_1.readDocument)(absolute), file.path, absolute, options);
+        if (summary !== undefined)
+            yield summary;
+    }
+}
+/**
+ * Every Memory document **in the working tree** under `root`, parsed — {@link loadMemoryDocumentsAtRev}
+ * for the live files, in {@link listMemoryDocumentPaths}'s sorted order. Archived documents are
+ * included: the caller decides what to drop. A document whose frontmatter does not parse, and a
+ * symbolic link, are left out and reported to `options.onDiagnostic` as {@link W_MEMORY_UNREADABLE}
+ * (task-171, task-253 / `bug-230`), so one malformed document never fails a read of the others.
+ */
+function loadMemoryDocuments(root, memoryYaml, options = {}) {
+    return [...readableDocuments(scanWorkingTreeDocuments(root, memoryYaml, options), options)];
+}
+// --- The same scan at a revision (task-137) -----------------------------------------------------
+//
+// `spec-012` §2 pins an agent context to `stateRef`, a commit sha, and `spec-017` §1.1/§1.3 deduce
+// workflow state from every Memory document "enumerated from `HEAD`'s tree in sorted path order". The
+// readers below are the working-tree scan above, read at one commit instead: the same scan roots
+// ({@link computeMemoryContentRoots}), the same `.md` filter, the same sort, the same parse, the same
+// tolerance and the same rule for links (task-171). Each resolves `rev` once (`resolveRevision`) and
+// reads every byte at that sha; an unknown or malformed rev throws `RevisionError` rather than
+// answering with an empty scan. Pass the `memoryYaml` loaded at the same rev (`loadMemoryYamlAtRev`),
+// and a resolved sha when several calls must see one commit.
+/** Every `.md` blob under the scan roots at `sha`, sorted, links marked (git mode `120000`). */
+function scanCommit(root, sha, memoryYaml) {
+    const out = new Map();
+    for (const dir of computeMemoryContentRoots(memoryYaml)) {
+        for (const entry of (0, revision_1.listBlobEntriesAtCommit)(root, sha, dir))
+            if (entry.path.endsWith('.md'))
+                out.set(entry.path, entry);
+    }
+    return [...out.values()].sort(byPath);
+}
+/**
+ * Every Memory document **commit `rev` holds**, as root-relative POSIX paths sorted the way
+ * {@link listMemoryDocumentPaths} sorts the working tree's (REQ-SYS-07). A document added after `rev`,
+ * or present only in the working tree, is not listed; nor is a symbolic link (task-171, `bug-189`).
+ *
+ * @throws `RevisionError` when `rev` is malformed or names no commit.
+ */
+function listMemoryDocumentPathsAtRev(root, rev, memoryYaml) {
+    return scanCommit(root, (0, revision_1.resolveRevision)(root, rev), memoryYaml)
+        .filter((file) => !file.symlink)
+        .map((file) => file.path);
+}
+/**
+ * Read `files` at `sha` in one batch and parse them **lazily**, in path order; a path the commit does
+ * holds every one of them (they were listed at it); a link or an unparsable document is reported and
+ * skipped (task-171). Lazy
+ * so that a lookup can stop at its match, as the working-tree lookup does.
+ */
+function* parseMemoryDocumentsAtSha(root, sha, rev, files, options) {
+    const raws = (0, storage_1.readPathsAtRev)(root, sha, files.filter((file) => !file.symlink).map((file) => file.path));
+    let next = 0;
+    for (const file of files) {
+        if (file.symlink) {
+            options.onDiagnostic?.(memoryUnreadableDiagnostic(file.path, SYMLINK_REASON));
+            continue;
+        }
+        // Every path here was listed as a blob of this very commit, so the commit holds it and the batch
+        // answers its bytes, never `null`.
+        const raw = raws[next++];
+        const summary = parseScanned(raw, file.path, `${rev}:${file.path}`, options);
+        if (summary !== undefined)
+            yield summary;
+    }
+}
+/**
+ * Every Memory document **commit `rev` holds**, parsed — the paths of
+ * {@link listMemoryDocumentPathsAtRev}, in its order, each read in one batch (`storage.readPathsAtRev`)
+ * and split as {@link loadMemoryDocumentSummary} splits a working-tree file. This is the snapshot a
+ * reader pinned to one commit builds from (`spec-012` §6 relevance, `spec-017` §4 deduction). A
+ * document whose frontmatter does not parse, and a link, are left out and reported (task-171).
+ *
+ * @throws `RevisionError` when `rev` is malformed or names no commit.
+ */
+function loadMemoryDocumentsAtRev(root, rev, memoryYaml, options = {}) {
+    const sha = (0, revision_1.resolveRevision)(root, rev);
+    return [...readableDocuments(parseMemoryDocumentsAtSha(root, sha, rev, scanCommit(root, sha, memoryYaml), options), options)];
+}
+/**
+ * {@link loadMemoryDocumentsAtRev} for a `sha` already resolved to a commit (`resolveRevision`,
+ * `src/core/revision.ts`): the same scan and parse, without resolving the revision again. A reader that
+ * resolves its commit once and reads several pillars at it (the workflow deduction's snapshot, task-283,
+ * `bug-309`) uses this, so one call spends one `git rev-parse`, not one per loader.
+ *
+ * @param sha - The full sha of a commit, as `resolveRevision` returned it; labels name it.
+ */
+function loadMemoryDocumentsAtCommit(root, sha, memoryYaml, options) {
+    return [...readableDocuments(parseMemoryDocumentsAtSha(root, sha, sha, scanCommit(root, sha, memoryYaml), options), options)];
+}
+/**
+ * One Memory document **as commit `rev` holds it** — {@link loadMemoryDocumentSummary} at a commit.
+ * `null` when that commit does not hold `relativePath` as a file. Like its working-tree counterpart,
+ * this single-file read throws when the frontmatter does not parse.
+ *
+ * @throws `RevisionError` when `rev` is malformed or names no commit; `ValidationError` when the
+ *   frontmatter does not parse.
+ */
+function loadMemoryDocumentSummaryAtRev(root, rev, relativePath) {
+    const raw = (0, storage_1.readPathsAtRev)(root, (0, revision_1.resolveRevision)(root, rev), [relativePath])[0];
+    return raw === null ? null : refuseNewerElement(parseMemoryDocument(raw, relativePath, `${rev}:${relativePath}`));
+}
 function asStringArray(value) {
     return Array.isArray(value) ? value.filter((entry) => typeof entry === 'string') : [];
 }
@@ -153,25 +448,40 @@ function asString(value) {
  * (single document) — there is no bare, single-segment `wingfoil://memory/{id}` form there, and this
  * `{id}` segment would collide with spec-004's `{type}` segment. task-011-mcp-resources-read-only has
  * since replaced the `wingfoil://memory/{id}` *Resource* this primitive originally backed with the
- * conformant `wingfoil://memory/{type}/{id}` form (see {@link findMemoryDocumentByTypeAndId}) — this
- * bare-id primitive itself is left in place (still covered by its own `test/memory/query.test.ts`
- * unit tests and REQ-PERF-04's ported benchmark) as a generic, type-agnostic lookup; nothing in
- * `src/mcp` calls it anymore.
+ * conformant `wingfoil://memory/{type}/{id}` form (see {@link findMemoryDocumentByTypeAndId}). This
+ * bare-id primitive is what `memory history` resolves its `<id>` with, and what the transition verbs
+ * use to explain a refusal; it is neutral about archived documents, since both act on them.
  *
- * A linear scan over every document {@link listMemoryDocumentPaths} returns, in its
- * already-deterministic sorted order, stopping at the first document whose frontmatter `id` matches
+ * A linear scan, in sorted path order, stopping at the first document whose frontmatter `id` matches
  * *exactly* (never a substring — that remains `searchMemoryDocuments`'/task-021's keyword-search
- * surface, not this primitive's). Returns `undefined` — never throws — when no document matches;
- * turning that into a protocol-level "resource not found" failure is the MCP Resource adapter's job
- * (spec-004 §2.2's general unresolvable-URI contract), not this primitive's.
+ * surface, not this primitive's). Returns `undefined` — never throws — when no document matches; a
+ * document it cannot read on the way is reported to `options.onDiagnostic` and skipped (task-171).
  */
-function findMemoryDocumentById(root, memoryYaml, id) {
-    for (const path of listMemoryDocumentPaths(root, memoryYaml)) {
-        const summary = loadMemoryDocumentSummary(root, path);
-        if (asString(summary.frontmatter.id) === id)
-            return summary;
-    }
-    return undefined;
+function findMemoryDocumentById(root, memoryYaml, id, options = {}) {
+    return findFirst(scanWorkingTreeDocuments(root, memoryYaml, options), (frontmatter) => asString(frontmatter.id) === id, options);
+}
+/**
+ * {@link findMemoryDocumentById} **at commit `rev`** (task-247, `bug-187`): the first document, in
+ * the sorted path order of {@link listMemoryDocumentPathsAtRev}, whose own frontmatter `id` matches
+ * exactly, with its frontmatter and body as `rev` holds them; `undefined` when that commit holds none.
+ * A document present only in the working tree, or added after `rev`, is never returned. This is the
+ * lookup the Memory transition verbs decide from (`spec-006-core-domain-api` §6 item 1). A document it
+ * cannot read on the way is reported to `options.onDiagnostic` and skipped (task-171).
+ *
+ * @throws `RevisionError` when `rev` is malformed or names no commit.
+ */
+function findMemoryDocumentByIdAtRev(root, rev, memoryYaml, id, options = {}) {
+    const sha = (0, revision_1.resolveRevision)(root, rev);
+    const documents = parseMemoryDocumentsAtSha(root, sha, rev, scanCommit(root, sha, memoryYaml), options);
+    return findFirst(documents, (frontmatter) => asString(frontmatter.id) === id, options);
+}
+/** The match of the (`type`, `id`) lookups: both are the document's own frontmatter values. */
+function isTypeAndId(type, id) {
+    return (frontmatter) => asString(frontmatter.type) === type && asString(frontmatter.id) === id;
+}
+/** Whether a document is kept under the archived default of {@link MemoryTypeScanOptions}. */
+function keptByArchivedDefault(frontmatter, options) {
+    return options.includeArchived === true || !(0, state_machine_1.isArchivedStatus)(asString(frontmatter.status));
 }
 /**
  * List every Memory document whose frontmatter `type:` field equals `type` (a `memory.yaml` `types:`
@@ -184,13 +494,17 @@ function findMemoryDocumentById(root, memoryYaml, id) {
  * `release`/`release-line` both resolve to `docs/04_memory/planning`; `task`'s own pattern collapses
  * all the way to `docs/04_memory` itself — see {@link computeMemoryContentRoots}'s doc comment), so a
  * directory-only filter would wrongly fold sibling types' documents into this type's collection.
+ *
+ * Archived documents are left out unless `options.includeArchived` (task-171, `dl-038` option 1), and
+ * a document the scan cannot read is reported to `options.onDiagnostic` and skipped.
  */
-function listMemoryDocumentsByType(root, memoryYaml, type) {
+function listMemoryDocumentsByType(root, memoryYaml, type, options = {}) {
     const out = [];
-    for (const path of listMemoryDocumentPaths(root, memoryYaml)) {
-        const { frontmatter } = loadMemoryDocumentSummary(root, path);
+    for (const { path, frontmatter } of readableDocuments(scanWorkingTreeDocuments(root, memoryYaml, options), options)) {
         if (asString(frontmatter.type) !== type)
             continue;
+        if (!keptByArchivedDefault(frontmatter, options))
+            continue;
         out.push({
             path,
             id: asString(frontmatter.id),
@@ -199,11 +513,9 @@ function listMemoryDocumentsByType(root, memoryYaml, type) {
             tags: asStringArray(frontmatter.tags),
         });
     }
-    return out.sort((a, b) => {
-        const keyA = a.id ?? a.path;
-        const keyB = b.id ?? b.path;
-        return keyA < keyB ? -1 : keyA > keyB ? 1 : 0;
-    });
+    // By `id`, a document with none by its path, then by path: a total order even when two files carry
+    // one `id` (REQ-SYS-07).
+    return out.sort((a, b) => compareText(a.id ?? a.path, b.id ?? b.path) || compareText(a.path, b.path));
 }
 /**
  * Resolve a single Memory document by (`type`, `id`) — spec-004 §2.1's `wingfoil://memory/{type}/{id}`
@@ -214,14 +526,25 @@ function listMemoryDocumentsByType(root, memoryYaml, type) {
  * because that type's path pattern happens to also resolve under the same directory. Returns
  * `undefined` — never throws — when nothing matches; surfacing that as a protocol-level "resource not
  * found" failure is the MCP Resource adapter's job (spec-004 §2.2), not this primitive's.
+ *
+ * An archived document matches only with `options.includeArchived` (task-171, `dl-038` option 1); the
+ * single-document Resource passes it, since REQ-STATE-06 keeps archived content retrievable.
  */
-function findMemoryDocumentByTypeAndId(root, memoryYaml, type, id) {
-    for (const path of listMemoryDocumentPaths(root, memoryYaml)) {
-        const summary = loadMemoryDocumentSummary(root, path);
-        if (asString(summary.frontmatter.type) === type && asString(summary.frontmatter.id) === id)
-            return summary;
-    }
-    return undefined;
+function findMemoryDocumentByTypeAndId(root, memoryYaml, type, id, options = {}) {
+    const found = findFirst(scanWorkingTreeDocuments(root, memoryYaml, options), isTypeAndId(type, id), options);
+    return found !== undefined && keptByArchivedDefault(found.frontmatter, options) ? found : undefined;
+}
+/**
+ * {@link findMemoryDocumentByTypeAndId} **at commit `rev`**: the document whose own frontmatter `type`
+ * and `id` match, with its frontmatter and body as `rev` holds them; `undefined` when that commit holds
+ * none, or holds it archived without `options.includeArchived`.
+ *
+ * @throws `RevisionError` when `rev` is malformed or names no commit.
+ */
+function findMemoryDocumentByTypeAndIdAtRev(root, rev, memoryYaml, type, id, options = {}) {
+    const sha = (0, revision_1.resolveRevision)(root, rev);
+    const found = findFirst(parseMemoryDocumentsAtSha(root, sha, rev, scanCommit(root, sha, memoryYaml), options), isTypeAndId(type, id), options);
+    return found !== undefined && keptByArchivedDefault(found.frontmatter, options) ? found : undefined;
 }
 /** `E_EMPTY_SEARCH_QUERY` field-level code (spec-009-validation-strategy §3) for a rejected empty
  * or whitespace-only `wingfoil memory search` query. */
@@ -256,8 +579,13 @@ function validateSearchQuery(query) {
  * concern, task-021's, not this primitive's).
  *
  * Ordering is a total, deterministic order (REQ-SYS-07): metadata matches before body-only matches,
- * then by `id` (falling back to `path` when a document has no `id`) ascending — so calling this
- * twice against unchanged state always returns the exact same array.
+ * then by `id`, then by `path` (two files may carry one `id`) ascending — so calling this twice
+ * against unchanged state always returns the exact same array.
+ *
+ * **Only elements, never a throw (task-171).** A match has an `id` and a `type` (`bug-164`); a file
+ * with neither is left out without a report. A document whose frontmatter does not parse, or a
+ * symbolic link, is left out and reported to `options.onDiagnostic` as {@link W_MEMORY_UNREADABLE}
+ * (`bug-031`), so one malformed file never fails a search.
  *
  * **REQ-STATE-06:** a document whose frontmatter `status` is archived — `deprecated` or `superseded`
  * (`isArchivedStatus`, `dl-028`) — is excluded by default, so it never appears in these "default
@@ -270,8 +598,13 @@ function validateSearchQuery(query) {
 function searchMemoryDocuments(root, memoryYaml, query, options = {}) {
     const needle = query.trim().toLowerCase();
     const matches = [];
-    for (const path of listMemoryDocumentPaths(root, memoryYaml)) {
-        const { frontmatter, body } = loadMemoryDocumentSummary(root, path);
+    for (const { path, frontmatter, body } of readableDocuments(scanWorkingTreeDocuments(root, memoryYaml, options), options)) {
+        // Only an element is a match (task-171, `bug-164`): a file with no `id` or no `type` — a plan
+        // `dl-019` grandfathered without frontmatter — is left out, silently: it is not unreadable.
+        const id = asString(frontmatter.id);
+        const type = asString(frontmatter.type);
+        if (id === undefined || type === undefined)
+            continue;
         const status = asString(frontmatter.status);
         if (!options.includeArchived && (0, state_machine_1.isArchivedStatus)(status))
             continue;
@@ -279,14 +612,12 @@ function searchMemoryDocuments(root, memoryYaml, query, options = {}) {
         if (options.tag && !tags.includes(options.tag))
             continue;
         const title = asString(frontmatter.title);
-        const id = asString(frontmatter.id);
-        const type = asString(frontmatter.type);
         let metadataMatch = false;
         let bodyMatch = false;
         if (needle.length > 0) {
             metadataMatch =
                 (title !== undefined && title.toLowerCase().includes(needle)) ||
-                    (id !== undefined && id.toLowerCase().includes(needle)) ||
+                    id.toLowerCase().includes(needle) ||
                     tags.some((tag) => tag.toLowerCase().includes(needle));
             bodyMatch = body.toLowerCase().includes(needle);
             if (!metadataMatch && !bodyMatch)
@@ -299,9 +630,58 @@ function searchMemoryDocuments(root, memoryYaml, query, options = {}) {
         const scoreB = b.metadataMatch ? 1 : 0;
         if (scoreA !== scoreB)
             return scoreB - scoreA;
-        const keyA = a.id ?? a.path;
-        const keyB = b.id ?? b.path;
-        return keyA < keyB ? -1 : keyA > keyB ? 1 : 0;
+        return compareText(a.id, b.id) || compareText(a.path, b.path);
+    });
+}
+/**
+ * The documents of type `type` each of `revs` holds, one sorted list per revision, in input order —
+ * the read the WIP-limit count across refs takes (`requireWipSlot`, `dl-156` Q1 (a), task-274).
+ *
+ * Narrow and batched, unlike one {@link loadMemoryDocumentsAtRev} per revision (which parses every
+ * document of every type at each commit): only the type's own static directory is listed, every
+ * revision's listing in one batched walk (`listBlobsAtRevs`), every distinct blob read in one batch and
+ * parsed **once** however many revisions hold it. A document counts when its own frontmatter `type` is
+ * `type`, as in every Memory scan. A link, an unparsable document and one written in a newer format are
+ * left out and reported through `options.onDiagnostic` as {@link W_MEMORY_UNREADABLE} (task-171,
+ * task-257), once per blob.
+ *
+ * @throws `StorageError` `E_GIT_READ_FAILED` when a revision names no commit or a batch read fails.
+ */
+function loadTypeDocumentCopiesAtRevs(root, revs, memoryYaml, type, options = {}) {
+    const typeEntry = memoryYaml.types[type];
+    const directory = typeEntry === undefined ? '' : staticDirPrefix(typeEntry.path);
+    const listings = (0, storage_1.listBlobsAtRevs)(root, revs, directory).map((blobs) => blobs.filter((blob) => blob.path.endsWith('.md')));
+    const reported = new Set();
+    const contents = (0, storage_1.readBlobs)(root, listings.flatMap((blobs) => blobs.filter((blob) => !blob.symlink).map((blob) => blob.oid)));
+    const parsed = new Map();
+    const frontmatterOf = (path, oid) => {
+        if (parsed.has(oid))
+            return parsed.get(oid);
+        const scanned = parseScanned(contents.get(oid), path, `${oid}:${path}`, options);
+        let frontmatter = null;
+        if (scanned !== undefined) {
+            if (scanned.newer !== null)
+                options.onDiagnostic?.(newerFormatDiagnostic(scanned.newer));
+            else
+                frontmatter = scanned.summary.frontmatter;
+        }
+        parsed.set(oid, frontmatter);
+        return frontmatter;
+    };
+    return listings.map((blobs) => {
+        const copies = [];
+        for (const blob of blobs) {
+            if (blob.symlink) {
+                if (!reported.has(blob.path))
+                    options.onDiagnostic?.(memoryUnreadableDiagnostic(blob.path, SYMLINK_REASON));
+                reported.add(blob.path);
+                continue;
+            }
+            const frontmatter = frontmatterOf(blob.path, blob.oid);
+            if (frontmatter !== null && frontmatter.type === type)
+                copies.push({ path: blob.path, oid: blob.oid, frontmatter });
+        }
+        return copies;
     });
 }
 //# sourceMappingURL=query.js.map