wingfoil 0.2.1

package/dist/memory/history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../../src/memory/history.ts"],"names":[],"mappings":"AAiCA,sGAAsG;AACtG,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,qFAAqF;IACrF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAcD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAexF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,SAAS,kBAAkB,EAAE,EACtC,WAAW,EAAE,MAAM,GAAG,IAAI,GACzB,kBAAkB,EAAE,CAUtB;AAmBD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CA+B9F;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,SAAS,kBAAkB,EAAE,EACtC,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,EACtC,YAAY,EAAE,MAAM,GACnB,kBAAkB,EAAE,CAEtB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,kBAAkB,EAAE,CA4BzF"}

package/dist/memory/history.js

@@ -0,0 +1,250 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findElementCreationSha = findElementCreationSha;
+exports.dropPreCreationAncestry = dropPreCreationAncestry;
+exports.collectHistoricalPaths = collectHistoricalPaths;
+exports.attachHistoricalPaths = attachHistoricalPaths;
+exports.getMemoryHistory = getMemoryHistory;
+/**
+ * Memory history primitive (task-008-dna-memory-query-latency, REQ-PERF-02) — the git-log walk
+ * underneath `wingfoil memory history` (P1.10), which shipped in `task-049-memory-history` as
+ * `src/core`'s `memoryHistory` operation. Per ADR-007 (stateless-state-derivation), git history is
+ * the sole audit trail for a Memory element's transitions — there is no secondary `.wingfoil/state/`
+ * log to query instead — so this walks `git log` directly over the element's file.
+ *
+ * Scope (see task-008's Execution Notes): this returns *structured commit records* (sha, author
+ * name/email, ISO-8601 author date, subject, body) — the walk itself. Deriving a human-facing
+ * "state change" (e.g. "pending -> backlog") from the commit body's `Approver:`/`Reason:` lines
+ * (CLAUDE.md §5.1) is not this primitive's concern; the raw `body` field carries that text verbatim
+ * for a caller to parse, and `./audit`'s `reconstructMemoryTransitions` is the caller that does — the
+ * `memoryHistory` operation projects that reconstruction rather than re-reading this walk itself.
+ *
+ * The `git log` walk/record-splitting plumbing itself lives in `./git-log` (factored out by
+ * task-015-complete-audit-trail, which needs the same plumbing for its own attribution audit) — this
+ * module owns only the `MemoryHistoryEntry` shape and the `--follow` single-document semantics.
+ *
+ * Those `--follow` semantics are this module's real subject, and they are not the ones the flag's
+ * name suggests (`task-089-fix-history-walk-attributes-only-real-commits`,
+ * `bug-077-history-follow-attributes-template-commits`). `--follow` does not only follow renames:
+ * git's path search runs with **copy** detection enabled, so when the path is absent from a parent
+ * commit git will accept a source that still exists there. Every Memory element is created by
+ * copying its type's template, which `wingfoil init` has already committed — so the walk crossed
+ * that copy edge and reported the commit that added the TEMPLATE as an entry of the element's own
+ * history, carrying a real sha, author and timestamp with every derived field null. See
+ * {@link findElementCreationSha} for the distinction that resolves it and why rename-following is
+ * kept rather than traded away.
+ */
+const child_process_1 = require("child_process");
+const git_log_1 = require("./git-log");
+const LOG_FIELDS = ['%H', '%an', '%ae', '%aI', '%s', '%b'];
+/**
+ * The same `--follow` walk as {@link getMemoryHistory}, narrowed by git to the commits whose edge for
+ * this path is a **copy**, and printing nothing but the sha. Deliberately a second `git log`
+ * invocation rather than extra output threaded through the first: `walkGitLogFields` recovers
+ * records by field arity over a stream of `<field>NUL` groups, so anything git appends outside the
+ * `--format` string — `--name-status` output, for instance — would be read as the next record's
+ * first field (task-086).
+ */
+const CREATION_PROBE_ARGS = ['--follow', '--diff-filter=C', '--format=%H'];
+/**
+ * The sha of the commit that introduced `relativePath` as a COPY of a file that outlives it — the
+ * element's own creation — or `null` when the followed chain contains no copy edge at all.
+ *
+ * This is the distinction the fix turns on. `git log --follow` can change path across two different
+ * kinds of edge, and they mean opposite things for an audit trail:
+ *
+ *  - **`R` (rename)** — the element continuing under a new name. Keep following. This is not a
+ *    hypothetical requirement: `docs/self/docs/04_memory/planning/v1/*` became `planning/rl-v1/*` in
+ *    one commit in this repository, moving five `release` elements at once, because the `release`
+ *    type's `path` pattern interpolates the release-line id (`memory.yaml`). For one of them a plain
+ *    `git log -- <path>` returns a single commit where the followed walk returns seven, so dropping
+ *    `--follow` would delete five sixths of that element's recorded history.
+ *  - **`C` (copy)** — the element being born out of a file that still exists. `wingfoil memory add`
+ *    copies the type's template verbatim (CLAUDE.md §5.1), and `wingfoil init` has already committed
+ *    that template, so this edge is how every scaffolded element begins. Everything strictly older
+ *    than it is the template's history, not the element's.
+ *
+ * Only the newest copy edge matters — it is the element's own creation; any older one belongs to
+ * whatever the source itself was copied from. `git log` prints newest first, so that is the first
+ * line.
+ *
+ * **Throws** — never returns `null` — when git itself fails. "git could not answer" and "this
+ * element was never copied from anything" are different answers, and collapsing the first into the
+ * second would silently restore the phantom entry; it is also why this cannot borrow
+ * `walkGitLogFields`, whose `catch` returns `[]` (`bug-072-oversized-git-log-becomes-empty-history`).
+ * {@link getMemoryHistory} calls this only once the main walk has already returned commits, so at
+ * that point the repository and the path are both known good and a failure here is genuinely
+ * exceptional.
+ *
+ * @param root - Absolute path of the repository to walk.
+ * @param relativePath - The element's root-relative path, as {@link getMemoryHistory} takes it.
+ * @returns The creation commit's full sha, or `null` when the chain has no copy edge.
+ */
+function findElementCreationSha(root, relativePath) {
+    let stdout;
+    try {
+        stdout = (0, child_process_1.execFileSync)('git', ['-C', root, 'log', ...CREATION_PROBE_ARGS, '--', relativePath], {
+            encoding: 'utf-8',
+        });
+    }
+    catch (cause) {
+        throw new Error(`git log --follow --diff-filter=C failed for ${relativePath}: cannot establish where the element was created`, { cause });
+    }
+    const newestCopy = stdout.split('\n').find((line) => line.trim().length > 0);
+    return newestCopy === undefined ? null : newestCopy.trim();
+}
+/**
+ * Drop the part of an oldest-first walk that precedes the element's creation, keeping the creation
+ * commit itself — the ancestry `--follow` reached through a copy edge, which belongs to the file the
+ * element was copied from. `creationSha` of `null` (no copy edge: the document was authored in
+ * place) leaves the walk untouched.
+ *
+ * Pure: no git, no filesystem. Separated from {@link findElementCreationSha} so the truncation rule
+ * and the invariant below are exercised directly rather than through a repository fixture.
+ *
+ * **Throws** when `creationSha` is absent from `entries`. The two walks are the same walk — one is
+ * the other filtered by git — so a sha in the narrower one that is missing from the wider one is a
+ * broken invariant, not a case to absorb. Defaulting to "no truncation" there would report the
+ * phantom entry again while reporting success.
+ *
+ * @param entries - The full `--follow` walk, oldest first.
+ * @param creationSha - The element's creation commit, from {@link findElementCreationSha}.
+ * @returns `entries` from the creation commit onward (a new array; `entries` is not mutated).
+ */
+function dropPreCreationAncestry(entries, creationSha) {
+    if (creationSha === null)
+        return [...entries];
+    const creationIndex = entries.findIndex((entry) => entry.sha === creationSha);
+    if (creationIndex === -1) {
+        throw new Error(`creation commit ${creationSha} is not present in the history walk it was derived from`);
+    }
+    return entries.slice(creationIndex);
+}
+/**
+ * The same `--follow` walk again, printing each commit's sha followed by its name-status line for
+ * the followed path. A third `git log` invocation for the same reason as {@link CREATION_PROBE_ARGS}
+ * and stated in full there: `--name-status` output is appended OUTSIDE the `--format` string, and
+ * `walkGitLogFields` recovers records by field arity over a stream of `<field>NUL` groups, so it
+ * would read those lines as the next record's first field (task-086).
+ *
+ * `core.quotePath=false` is set for the invocation (never written to the repository's config) so a
+ * path carrying non-ASCII bytes arrives as its own UTF-8 rather than as git's `"\303\251"` escape
+ * form — the parser would otherwise have to un-escape it to hand `git show` something that resolves.
+ */
+const PATH_PROBE_ARGS = ['-c', 'core.quotePath=false'];
+const PATH_PROBE_LOG_ARGS = ['--follow', '--name-status', '--format=%H'];
+/** A full sha on a line of its own — git's `--format=%H` output, which carries nothing else. */
+const SHA_LINE_RE = /^[0-9a-f]{40}$/;
+/**
+ * Where `relativePath`'s document lived at each commit of its `--follow` walk, keyed by sha.
+ *
+ * `git log --follow --name-status` prints, per commit, the sha then that commit's status line for
+ * the followed path — `A <path>`, `M <path>`, `D <path>`, or `R<score> <old> <new>` at a rename. The
+ * path the file occupies **at** a commit is always the LAST tab-separated field of that line: the
+ * destination of a rename, the single path otherwise. Everything older than that rename then reports
+ * the old path, which is the whole point — it is what
+ * `git show <sha>:<path>` needs in order to resolve at all.
+ *
+ * A commit git reports no status line for (it shows no diff for a merge without `-m`) is simply
+ * absent from the map; {@link attachHistoricalPaths} decides what to do about that, so the rule is
+ * testable without a repository.
+ *
+ * **Throws** — never returns an empty map — when git itself fails, for the same reason
+ * {@link findElementCreationSha} does: "git could not answer" and "this element was never renamed"
+ * are different answers, and folding the first into the second silently reinstates `bug-080` by
+ * reading every commit at the current path again. {@link getMemoryHistory} calls this only once the
+ * main walk has returned commits, so the repository and the path are both known good by then.
+ *
+ * @param root - Absolute path of the repository to walk.
+ * @param relativePath - The element's current root-relative path, as the caller named it.
+ * @returns sha → the root-relative path the document occupied at that commit.
+ */
+function collectHistoricalPaths(root, relativePath) {
+    let stdout;
+    try {
+        stdout = (0, child_process_1.execFileSync)('git', ['-C', root, ...PATH_PROBE_ARGS, 'log', ...PATH_PROBE_LOG_ARGS, '--', relativePath], 
+        // Same `stdio` rule as `./audit`'s `readStatusAt`, for the same reason
+        // (`bug-071-read-status-at-leaks-git-stderr`): the failure is reported by the throw below, so
+        // git's own `fatal:` must land in a pipe this process owns rather than on the operator's
+        // terminal. A call added while closing that bug must not reopen it somewhere else.
+        { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] });
+    }
+    catch (cause) {
+        throw new Error(`git log --follow --name-status failed for ${relativePath}: cannot establish where the element lived at each commit`, { cause });
+    }
+    const pathBySha = new Map();
+    let currentSha = null;
+    for (const line of stdout.split('\n')) {
+        if (SHA_LINE_RE.test(line)) {
+            currentSha = line;
+            continue;
+        }
+        if (currentSha === null || !line.includes('\t') || pathBySha.has(currentSha))
+            continue;
+        const fields = line.split('\t');
+        pathBySha.set(currentSha, fields[fields.length - 1]);
+    }
+    return pathBySha;
+}
+/**
+ * Stamp each walked commit with the path the element occupied at it, from
+ * {@link collectHistoricalPaths}' map.
+ *
+ * Pure: no git, no filesystem — separated from the probe for the same reason
+ * {@link dropPreCreationAncestry} is separated from {@link findElementCreationSha}, so the rule and
+ * its fallback are exercised directly rather than through a repository fixture.
+ *
+ * Falls back to `fallbackPath` (the path the caller named) for a sha the probe reported no diff for,
+ * rather than throwing: unlike the creation probe's invariant, an absent entry here is not evidence
+ * of a broken walk — git shows no diff for a merge commit — and the fallback is precisely the
+ * behaviour that shipped before this field existed, so it can degrade no further than the status quo.
+ *
+ * @param entries - The `--follow` walk, oldest first.
+ * @param pathBySha - sha → historical path, from {@link collectHistoricalPaths}.
+ * @param fallbackPath - The element's current root-relative path.
+ * @returns A new array; `entries` is not mutated.
+ */
+function attachHistoricalPaths(entries, pathBySha, fallbackPath) {
+    return entries.map((entry) => ({ ...entry, path: pathBySha.get(entry.sha) ?? fallbackPath }));
+}
+/**
+ * Walk every commit that touched `relativePath`, oldest first (P1.10-memory-history.feature: "lists
+ * ... entries in chronological order") — `git log` itself returns newest-first, reversed by
+ * {@link walkGitLogFields} — and only those commits. The walk follows renames, so an element moved on
+ * disk keeps its history, but stops at the element's own creation rather than continuing into the
+ * template it was copied from ({@link findElementCreationSha}).
+ *
+ * Returns `[]`, rather than throwing, both when `root` has no commits touching the path at all and
+ * when `root` is not a git repository — "document not found" is a caller/feature-layer concern
+ * (task-021/026-style CLI error rendering), not this primitive's. That is also why the creation
+ * probe runs only on a non-empty walk: on an empty one there is nothing to truncate and nothing to
+ * conclude from git's silence — and the same for the path probe.
+ *
+ * Every returned entry carries the path the element occupied at its own commit
+ * ({@link MemoryHistoryEntry.path}), not the one the caller named. That is what makes this walk the
+ * single source of truth for "where was this file at this commit": a consumer that reads content per
+ * commit — `./audit`'s `reconstructMemoryTransitions`, which reads the frontmatter `status:` — must
+ * take the path from here rather than re-using its own argument (`bug-080`).
+ */
+function getMemoryHistory(root, relativePath) {
+    const records = (0, git_log_1.walkGitLogFields)(root, LOG_FIELDS, [relativePath], ['--follow']);
+    // One field per slot, `%b` included. Two consequences of task-086's arity-based framing, both
+    // deliberate:
+    //
+    //  - The body arrives WHOLE even when it carries a character that used to look like a delimiter.
+    //    `%b` being LAST was the only thing that made a `0x1f` in a reason survive before, via an
+    //    explicit `bodyParts.join(FIELD_SEP)` that undid the split it had just caused; that accident
+    //    and the reassembly compensating for it are both gone (bug-050).
+    //  - Every record has exactly `LOG_FIELDS.length` entries — `walkGitLogFields` emits whole groups
+    //    or none — so the per-slot `= ''` defaults this used to carry could never fire. They are read
+    //    as the cast below instead of kept as six permanently-unreachable branches.
+    const entries = records.map((record) => {
+        const [sha, authorName, authorEmail, date, subject, body] = record;
+        return { sha, authorName, authorEmail, date, subject, body: body.trim(), path: relativePath };
+    });
+    if (entries.length === 0)
+        return entries;
+    const located = attachHistoricalPaths(entries, collectHistoricalPaths(root, relativePath), relativePath);
+    return dropPreCreationAncestry(located, findElementCreationSha(root, relativePath));
+}
+//# sourceMappingURL=history.js.map

package/dist/memory/history.js.map

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

package/dist/memory/index.d.ts

@@ -0,0 +1,58 @@
+/**
+ * `memory` module — Project Memory pillar; git-backed documents with per-type state machines
+ * (P1.13). `memory.yaml`'s schema (spec-001-memory-yaml-schema) lives here — the pillar owns its own
+ * independent schema (REQ-SYS-02); `src/core`'s loader wires it through the shared validation
+ * pipeline. The transition-legality engine (REQ-SYS-04, task-005-per-type-state-machines) also lives
+ * here — it consumes the schema's already-validated `StateMachine` shape, it does not re-validate it.
+ * Further Memory behavior (per-type CLI verbs, frontmatter schema) lands in later tasks.
+ *
+ * task-008-dna-memory-query-latency adds the `memory search`/`memory history` query-path
+ * *primitives* (REQ-PERF-02) `./query` and `./history` — the performance-bearing foundation
+ * `task-021-implement-memory-search` (P1.5) and `task-049-memory-history` (P1.10) built their
+ * CLI/MCP surface on top of; see those modules' own doc comments and the task's Execution Notes for
+ * the foundation/feature scoping decision.
+ *
+ * task-015-complete-audit-trail adds `./audit` (REQ-SEC-02) — the audit/verification layer built on
+ * `./history`'s raw git-log walk: attribution auditing (0 "unknown author"), `Approver:`/`Reason:`
+ * commit-body parsing, full transition reconstruction, and the frontmatter-vs-commit-message
+ * consistency check. It is deliberately read-only/verification-only — write-time git-identity
+ * enforcement is task-014-git-identity-required's (REQ-SEC-01) separate concern.
+ *
+ * task-022-implement-memory-entries adds `./entry` (P1.11) — `writeMemoryEntry`, the reusable,
+ * throwing library primitive that composes `resolveConfinedMemoryPath` (task-017, REQ-SEC-06),
+ * `writeDocument`, and `commitPaths` (task-018) into the one "resolve confined path, write bytes,
+ * one commit" Memory-entry write path (REQ-SYS-01/REQ-SYS-03). `wingfoil memory add`/`submit`
+ * (task-020) wire this in behind a `CoreResult`; this module stays a plain, throwing composition,
+ * matching every other `src/storage` primitive it builds on.
+ *
+ * task-036-frontmatter-lifecycle-validation adds `validateFrontmatterState` (REQ-STATE-01,
+ * spec-010-memory-frontmatter-schema) to `./state-machine` — the per-type membership check on a
+ * document's frontmatter `status` value itself, independent of any transition attempt (distinct from
+ * `resolveTransitionTarget`'s verb-based transition legality). `task-045-memory-submit` (P1.6) is the
+ * first CLI-facing consumer.
+ *
+ * task-045-memory-submit adds the pieces every Memory transition verb shares — `resolveTypeTransition`
+ * (the `dl-032` illegal-transition contract), `./commit-message` (the one commit-message formatter) and
+ * `./frontmatter-edit` (byte-preserving field edits) — plus `./submit`, the submit-specific rules.
+ */
+export declare const MODULE_NAME: "memory";
+export { MemoryYaml, MemoryTypeEntry, StateMachine, TemplateConfig } from './schema';
+export { ARCHIVED_STATUSES, DEFAULT_STATE_MACHINE, DEPRECATED_STATE, E_INVALID_STATE, E_INVALID_TRANSITION, isArchivedStatus, resolveStateMachine, resolveTransitionTarget, resolveTypeTransition, SUPERSEDED_STATE, validateFrontmatterState, } from './state-machine';
+export type { TransitionOp } from './state-machine';
+export { computeMemoryContentRoots, E_EMPTY_SEARCH_QUERY, findMemoryDocumentById, findMemoryDocumentByTypeAndId, listMemoryDocumentPaths, listMemoryDocumentsByType, loadMemoryDocumentSummary, searchMemoryDocuments, validateSearchQuery, } from './query';
+export type { MemoryDocumentFrontmatterSummary, MemoryDocumentSummary, MemorySearchMatch, MemorySearchOptions, } from './query';
+export { getMemoryHistory } from './history';
+export type { MemoryHistoryEntry } from './history';
+export { writeMemoryEntry } from './entry';
+export type { MemoryEntryWrite } from './entry';
+export { hasNumericToken, nextSequenceNumber, parseTags, renderAddDocument, resolveTypeDirectory, slugifyTitle, } from './add';
+export type { AddDocumentFields } from './add';
+export { formatMemoryCommitMessage, normalizeReason, parseApproverTrailerLine, parseReasonBlock, reasonDefect, reasonDefectMessage, } from './commit-message';
+export type { CommitApprover, MemoryCommitMessageInput, ReasonDefect } from './commit-message';
+export { describeDocumentChanges, removeFrontmatterField, setFrontmatterField, verifyDocumentEdit, verifyFrontmatterEdit, } from './frontmatter-edit';
+export type { DocumentScope } from './frontmatter-edit';
+export { missingRequiredFields, REJECTION_REASON_FIELD, renderSubmitDocument } from './submit';
+export { renderRejectDocument } from './reject';
+export { auditAttribution, isValidAttribution, parseApprovalMetadata, parseCommitReason, reconstructMemoryTransitions, verifyTransitionConsistency, } from './audit';
+export type { AttributionEntry, ApprovalMetadata, MemoryTransition, ConsistencyMismatch } from './audit';
+//# sourceMappingURL=index.d.ts.map

package/dist/memory/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/memory/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,WAAW,EAAG,QAAiB,CAAC;AAE7C,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AACrF,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,gBAAgB,EAChB,eAAe,EACf,oBAAoB,EACpB,gBAAgB,EAChB,mBAAmB,EACnB,uBAAuB,EACvB,qBAAqB,EACrB,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,iBAAiB,CAAC;AACzB,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EACL,yBAAyB,EACzB,oBAAoB,EACpB,sBAAsB,EACtB,6BAA6B,EAC7B,uBAAuB,EACvB,yBAAyB,EACzB,yBAAyB,EACzB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,SAAS,CAAC;AACjB,YAAY,EACV,gCAAgC,EAChC,qBAAqB,EACrB,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC7C,YAAY,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAC3C,YAAY,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAChD,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,SAAS,EACT,iBAAiB,EACjB,oBAAoB,EACpB,YAAY,GACb,MAAM,OAAO,CAAC;AACf,YAAY,EAAE,iBAAiB,EAAE,MAAM,OAAO,CAAC;AAC/C,OAAO,EACL,yBAAyB,EACzB,eAAe,EACf,wBAAwB,EACxB,gBAAgB,EAChB,YAAY,EACZ,mBAAmB,GACpB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,cAAc,EAAE,wBAAwB,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAC/F,OAAO,EACL,uBAAuB,EACvB,sBAAsB,EACtB,mBAAmB,EACnB,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAC/F,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,qBAAqB,EACrB,iBAAiB,EACjB,4BAA4B,EAC5B,2BAA2B,GAC5B,MAAM,SAAS,CAAC;AACjB,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC"}

package/dist/memory/index.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isValidAttribution = exports.auditAttribution = exports.renderRejectDocument = exports.renderSubmitDocument = exports.REJECTION_REASON_FIELD = exports.missingRequiredFields = exports.verifyFrontmatterEdit = exports.verifyDocumentEdit = exports.setFrontmatterField = exports.removeFrontmatterField = exports.describeDocumentChanges = exports.reasonDefectMessage = exports.reasonDefect = exports.parseReasonBlock = exports.parseApproverTrailerLine = exports.normalizeReason = exports.formatMemoryCommitMessage = exports.slugifyTitle = exports.resolveTypeDirectory = exports.renderAddDocument = exports.parseTags = exports.nextSequenceNumber = exports.hasNumericToken = exports.writeMemoryEntry = exports.getMemoryHistory = exports.validateSearchQuery = exports.searchMemoryDocuments = exports.loadMemoryDocumentSummary = exports.listMemoryDocumentsByType = exports.listMemoryDocumentPaths = exports.findMemoryDocumentByTypeAndId = exports.findMemoryDocumentById = exports.E_EMPTY_SEARCH_QUERY = exports.computeMemoryContentRoots = exports.validateFrontmatterState = exports.SUPERSEDED_STATE = exports.resolveTypeTransition = exports.resolveTransitionTarget = exports.resolveStateMachine = exports.isArchivedStatus = exports.E_INVALID_TRANSITION = exports.E_INVALID_STATE = exports.DEPRECATED_STATE = exports.DEFAULT_STATE_MACHINE = exports.ARCHIVED_STATUSES = exports.TemplateConfig = exports.StateMachine = exports.MemoryTypeEntry = exports.MemoryYaml = exports.MODULE_NAME = void 0;
+exports.verifyTransitionConsistency = exports.reconstructMemoryTransitions = exports.parseCommitReason = exports.parseApprovalMetadata = void 0;
+/**
+ * `memory` module — Project Memory pillar; git-backed documents with per-type state machines
+ * (P1.13). `memory.yaml`'s schema (spec-001-memory-yaml-schema) lives here — the pillar owns its own
+ * independent schema (REQ-SYS-02); `src/core`'s loader wires it through the shared validation
+ * pipeline. The transition-legality engine (REQ-SYS-04, task-005-per-type-state-machines) also lives
+ * here — it consumes the schema's already-validated `StateMachine` shape, it does not re-validate it.
+ * Further Memory behavior (per-type CLI verbs, frontmatter schema) lands in later tasks.
+ *
+ * task-008-dna-memory-query-latency adds the `memory search`/`memory history` query-path
+ * *primitives* (REQ-PERF-02) `./query` and `./history` — the performance-bearing foundation
+ * `task-021-implement-memory-search` (P1.5) and `task-049-memory-history` (P1.10) built their
+ * CLI/MCP surface on top of; see those modules' own doc comments and the task's Execution Notes for
+ * the foundation/feature scoping decision.
+ *
+ * task-015-complete-audit-trail adds `./audit` (REQ-SEC-02) — the audit/verification layer built on
+ * `./history`'s raw git-log walk: attribution auditing (0 "unknown author"), `Approver:`/`Reason:`
+ * commit-body parsing, full transition reconstruction, and the frontmatter-vs-commit-message
+ * consistency check. It is deliberately read-only/verification-only — write-time git-identity
+ * enforcement is task-014-git-identity-required's (REQ-SEC-01) separate concern.
+ *
+ * task-022-implement-memory-entries adds `./entry` (P1.11) — `writeMemoryEntry`, the reusable,
+ * throwing library primitive that composes `resolveConfinedMemoryPath` (task-017, REQ-SEC-06),
+ * `writeDocument`, and `commitPaths` (task-018) into the one "resolve confined path, write bytes,
+ * one commit" Memory-entry write path (REQ-SYS-01/REQ-SYS-03). `wingfoil memory add`/`submit`
+ * (task-020) wire this in behind a `CoreResult`; this module stays a plain, throwing composition,
+ * matching every other `src/storage` primitive it builds on.
+ *
+ * task-036-frontmatter-lifecycle-validation adds `validateFrontmatterState` (REQ-STATE-01,
+ * spec-010-memory-frontmatter-schema) to `./state-machine` — the per-type membership check on a
+ * document's frontmatter `status` value itself, independent of any transition attempt (distinct from
+ * `resolveTransitionTarget`'s verb-based transition legality). `task-045-memory-submit` (P1.6) is the
+ * first CLI-facing consumer.
+ *
+ * task-045-memory-submit adds the pieces every Memory transition verb shares — `resolveTypeTransition`
+ * (the `dl-032` illegal-transition contract), `./commit-message` (the one commit-message formatter) and
+ * `./frontmatter-edit` (byte-preserving field edits) — plus `./submit`, the submit-specific rules.
+ */
+exports.MODULE_NAME = 'memory';
+var schema_1 = require("./schema");
+Object.defineProperty(exports, "MemoryYaml", { enumerable: true, get: function () { return schema_1.MemoryYaml; } });
+Object.defineProperty(exports, "MemoryTypeEntry", { enumerable: true, get: function () { return schema_1.MemoryTypeEntry; } });
+Object.defineProperty(exports, "StateMachine", { enumerable: true, get: function () { return schema_1.StateMachine; } });
+Object.defineProperty(exports, "TemplateConfig", { enumerable: true, get: function () { return schema_1.TemplateConfig; } });
+var state_machine_1 = require("./state-machine");
+Object.defineProperty(exports, "ARCHIVED_STATUSES", { enumerable: true, get: function () { return state_machine_1.ARCHIVED_STATUSES; } });
+Object.defineProperty(exports, "DEFAULT_STATE_MACHINE", { enumerable: true, get: function () { return state_machine_1.DEFAULT_STATE_MACHINE; } });
+Object.defineProperty(exports, "DEPRECATED_STATE", { enumerable: true, get: function () { return state_machine_1.DEPRECATED_STATE; } });
+Object.defineProperty(exports, "E_INVALID_STATE", { enumerable: true, get: function () { return state_machine_1.E_INVALID_STATE; } });
+Object.defineProperty(exports, "E_INVALID_TRANSITION", { enumerable: true, get: function () { return state_machine_1.E_INVALID_TRANSITION; } });
+Object.defineProperty(exports, "isArchivedStatus", { enumerable: true, get: function () { return state_machine_1.isArchivedStatus; } });
+Object.defineProperty(exports, "resolveStateMachine", { enumerable: true, get: function () { return state_machine_1.resolveStateMachine; } });
+Object.defineProperty(exports, "resolveTransitionTarget", { enumerable: true, get: function () { return state_machine_1.resolveTransitionTarget; } });
+Object.defineProperty(exports, "resolveTypeTransition", { enumerable: true, get: function () { return state_machine_1.resolveTypeTransition; } });
+Object.defineProperty(exports, "SUPERSEDED_STATE", { enumerable: true, get: function () { return state_machine_1.SUPERSEDED_STATE; } });
+Object.defineProperty(exports, "validateFrontmatterState", { enumerable: true, get: function () { return state_machine_1.validateFrontmatterState; } });
+var query_1 = require("./query");
+Object.defineProperty(exports, "computeMemoryContentRoots", { enumerable: true, get: function () { return query_1.computeMemoryContentRoots; } });
+Object.defineProperty(exports, "E_EMPTY_SEARCH_QUERY", { enumerable: true, get: function () { return query_1.E_EMPTY_SEARCH_QUERY; } });
+Object.defineProperty(exports, "findMemoryDocumentById", { enumerable: true, get: function () { return query_1.findMemoryDocumentById; } });
+Object.defineProperty(exports, "findMemoryDocumentByTypeAndId", { enumerable: true, get: function () { return query_1.findMemoryDocumentByTypeAndId; } });
+Object.defineProperty(exports, "listMemoryDocumentPaths", { enumerable: true, get: function () { return query_1.listMemoryDocumentPaths; } });
+Object.defineProperty(exports, "listMemoryDocumentsByType", { enumerable: true, get: function () { return query_1.listMemoryDocumentsByType; } });
+Object.defineProperty(exports, "loadMemoryDocumentSummary", { enumerable: true, get: function () { return query_1.loadMemoryDocumentSummary; } });
+Object.defineProperty(exports, "searchMemoryDocuments", { enumerable: true, get: function () { return query_1.searchMemoryDocuments; } });
+Object.defineProperty(exports, "validateSearchQuery", { enumerable: true, get: function () { return query_1.validateSearchQuery; } });
+var history_1 = require("./history");
+Object.defineProperty(exports, "getMemoryHistory", { enumerable: true, get: function () { return history_1.getMemoryHistory; } });
+var entry_1 = require("./entry");
+Object.defineProperty(exports, "writeMemoryEntry", { enumerable: true, get: function () { return entry_1.writeMemoryEntry; } });
+var add_1 = require("./add");
+Object.defineProperty(exports, "hasNumericToken", { enumerable: true, get: function () { return add_1.hasNumericToken; } });
+Object.defineProperty(exports, "nextSequenceNumber", { enumerable: true, get: function () { return add_1.nextSequenceNumber; } });
+Object.defineProperty(exports, "parseTags", { enumerable: true, get: function () { return add_1.parseTags; } });
+Object.defineProperty(exports, "renderAddDocument", { enumerable: true, get: function () { return add_1.renderAddDocument; } });
+Object.defineProperty(exports, "resolveTypeDirectory", { enumerable: true, get: function () { return add_1.resolveTypeDirectory; } });
+Object.defineProperty(exports, "slugifyTitle", { enumerable: true, get: function () { return add_1.slugifyTitle; } });
+var commit_message_1 = require("./commit-message");
+Object.defineProperty(exports, "formatMemoryCommitMessage", { enumerable: true, get: function () { return commit_message_1.formatMemoryCommitMessage; } });
+Object.defineProperty(exports, "normalizeReason", { enumerable: true, get: function () { return commit_message_1.normalizeReason; } });
+Object.defineProperty(exports, "parseApproverTrailerLine", { enumerable: true, get: function () { return commit_message_1.parseApproverTrailerLine; } });
+Object.defineProperty(exports, "parseReasonBlock", { enumerable: true, get: function () { return commit_message_1.parseReasonBlock; } });
+Object.defineProperty(exports, "reasonDefect", { enumerable: true, get: function () { return commit_message_1.reasonDefect; } });
+Object.defineProperty(exports, "reasonDefectMessage", { enumerable: true, get: function () { return commit_message_1.reasonDefectMessage; } });
+var frontmatter_edit_1 = require("./frontmatter-edit");
+Object.defineProperty(exports, "describeDocumentChanges", { enumerable: true, get: function () { return frontmatter_edit_1.describeDocumentChanges; } });
+Object.defineProperty(exports, "removeFrontmatterField", { enumerable: true, get: function () { return frontmatter_edit_1.removeFrontmatterField; } });
+Object.defineProperty(exports, "setFrontmatterField", { enumerable: true, get: function () { return frontmatter_edit_1.setFrontmatterField; } });
+Object.defineProperty(exports, "verifyDocumentEdit", { enumerable: true, get: function () { return frontmatter_edit_1.verifyDocumentEdit; } });
+Object.defineProperty(exports, "verifyFrontmatterEdit", { enumerable: true, get: function () { return frontmatter_edit_1.verifyFrontmatterEdit; } });
+var submit_1 = require("./submit");
+Object.defineProperty(exports, "missingRequiredFields", { enumerable: true, get: function () { return submit_1.missingRequiredFields; } });
+Object.defineProperty(exports, "REJECTION_REASON_FIELD", { enumerable: true, get: function () { return submit_1.REJECTION_REASON_FIELD; } });
+Object.defineProperty(exports, "renderSubmitDocument", { enumerable: true, get: function () { return submit_1.renderSubmitDocument; } });
+var reject_1 = require("./reject");
+Object.defineProperty(exports, "renderRejectDocument", { enumerable: true, get: function () { return reject_1.renderRejectDocument; } });
+var audit_1 = require("./audit");
+Object.defineProperty(exports, "auditAttribution", { enumerable: true, get: function () { return audit_1.auditAttribution; } });
+Object.defineProperty(exports, "isValidAttribution", { enumerable: true, get: function () { return audit_1.isValidAttribution; } });
+Object.defineProperty(exports, "parseApprovalMetadata", { enumerable: true, get: function () { return audit_1.parseApprovalMetadata; } });
+Object.defineProperty(exports, "parseCommitReason", { enumerable: true, get: function () { return audit_1.parseCommitReason; } });
+Object.defineProperty(exports, "reconstructMemoryTransitions", { enumerable: true, get: function () { return audit_1.reconstructMemoryTransitions; } });
+Object.defineProperty(exports, "verifyTransitionConsistency", { enumerable: true, get: function () { return audit_1.verifyTransitionConsistency; } });
+//# sourceMappingURL=index.js.map

package/dist/memory/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/memory/index.ts"],"names":[],"mappings":";;;;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACU,QAAA,WAAW,GAAG,QAAiB,CAAC;AAE7C,mCAAqF;AAA5E,oGAAA,UAAU,OAAA;AAAE,yGAAA,eAAe,OAAA;AAAE,sGAAA,YAAY,OAAA;AAAE,wGAAA,cAAc,OAAA;AAClE,iDAYyB;AAXvB,kHAAA,iBAAiB,OAAA;AACjB,sHAAA,qBAAqB,OAAA;AACrB,iHAAA,gBAAgB,OAAA;AAChB,gHAAA,eAAe,OAAA;AACf,qHAAA,oBAAoB,OAAA;AACpB,iHAAA,gBAAgB,OAAA;AAChB,oHAAA,mBAAmB,OAAA;AACnB,wHAAA,uBAAuB,OAAA;AACvB,sHAAA,qBAAqB,OAAA;AACrB,iHAAA,gBAAgB,OAAA;AAChB,yHAAA,wBAAwB,OAAA;AAG1B,iCAUiB;AATf,kHAAA,yBAAyB,OAAA;AACzB,6GAAA,oBAAoB,OAAA;AACpB,+GAAA,sBAAsB,OAAA;AACtB,sHAAA,6BAA6B,OAAA;AAC7B,gHAAA,uBAAuB,OAAA;AACvB,kHAAA,yBAAyB,OAAA;AACzB,kHAAA,yBAAyB,OAAA;AACzB,8GAAA,qBAAqB,OAAA;AACrB,4GAAA,mBAAmB,OAAA;AAQrB,qCAA6C;AAApC,2GAAA,gBAAgB,OAAA;AAEzB,iCAA2C;AAAlC,yGAAA,gBAAgB,OAAA;AAEzB,6BAOe;AANb,sGAAA,eAAe,OAAA;AACf,yGAAA,kBAAkB,OAAA;AAClB,gGAAA,SAAS,OAAA;AACT,wGAAA,iBAAiB,OAAA;AACjB,2GAAA,oBAAoB,OAAA;AACpB,mGAAA,YAAY,OAAA;AAGd,mDAO0B;AANxB,2HAAA,yBAAyB,OAAA;AACzB,iHAAA,eAAe,OAAA;AACf,0HAAA,wBAAwB,OAAA;AACxB,kHAAA,gBAAgB,OAAA;AAChB,8GAAA,YAAY,OAAA;AACZ,qHAAA,mBAAmB,OAAA;AAGrB,uDAM4B;AAL1B,2HAAA,uBAAuB,OAAA;AACvB,0HAAA,sBAAsB,OAAA;AACtB,uHAAA,mBAAmB,OAAA;AACnB,sHAAA,kBAAkB,OAAA;AAClB,yHAAA,qBAAqB,OAAA;AAGvB,mCAA+F;AAAtF,+GAAA,qBAAqB,OAAA;AAAE,gHAAA,sBAAsB,OAAA;AAAE,8GAAA,oBAAoB,OAAA;AAC5E,mCAAgD;AAAvC,8GAAA,oBAAoB,OAAA;AAC7B,iCAOiB;AANf,yGAAA,gBAAgB,OAAA;AAChB,2GAAA,kBAAkB,OAAA;AAClB,8GAAA,qBAAqB,OAAA;AACrB,0GAAA,iBAAiB,OAAA;AACjB,qHAAA,4BAA4B,OAAA;AAC5B,oHAAA,2BAA2B,OAAA"}

package/dist/memory/query.d.ts

@@ -0,0 +1,150 @@
+import type { MemoryYaml } from './schema';
+/**
+ * Derive the minimal set of root-relative directories a scan needs to walk to see every Memory
+ * document declared by `memoryYaml`'s types (spec-011: path-pattern predictability, not a full-repo
+ * walk). A directory already covered by another (shorter) directory in the set is dropped, so the
+ * result never contains redundant, nested roots.
+ */
+export declare function computeMemoryContentRoots(memoryYaml: MemoryYaml): string[];
+/**
+ * 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.
+ */
+export declare function listMemoryDocumentPaths(root: string, memoryYaml: MemoryYaml): string[];
+/** A Memory document's parsed frontmatter (loose — no Zod schema validation, see module doc) + body. */
+export interface MemoryDocumentSummary {
+    readonly path: string;
+    readonly frontmatter: Record<string, unknown>;
+    readonly body: string;
+}
+/**
+ * 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.
+ */
+export declare function loadMemoryDocumentSummary(root: string, relativePath: string): MemoryDocumentSummary;
+/**
+ * Resolve a single Memory document by its `id` frontmatter value alone — REQ-PERF-04 /
+ * task-009-mcp-resource-fetch-latency's Acceptance Criteria, which name a `wingfoil://memory/{id}`
+ * benchmark fetch. This is NOT spec-004-mcp-surface-contract §2.1's Resource addressing: spec-004's
+ * actual scheme is `wingfoil://memory/{type}` (collection listing) and `wingfoil://memory/{type}/{id}`
+ * (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.
+ *
+ * A linear scan over every document {@link listMemoryDocumentPaths} returns, in its
+ * already-deterministic sorted 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.
+ */
+export declare function findMemoryDocumentById(root: string, memoryYaml: MemoryYaml, id: string): MemoryDocumentSummary | undefined;
+/** A Memory document's frontmatter-only summary — spec-004 §2.1's collection-listing shape
+ * (id, title, status, tags), deliberately omitting body content to keep listing calls cheap. */
+export interface MemoryDocumentFrontmatterSummary {
+    readonly path: string;
+    readonly id?: string;
+    readonly title?: string;
+    readonly status?: string;
+    readonly tags: readonly string[];
+}
+/**
+ * List every Memory document whose frontmatter `type:` field equals `type` (a `memory.yaml` `types:`
+ * key), as frontmatter-only summaries — spec-004 §2.1's `wingfoil://memory/{type}` collection
+ * addressing (task-011-mcp-resources-read-only, REQ-INT-01). Sorted by `id` (falling back to `path`
+ * when a document has no `id`) ascending (REQ-SYS-07 — deterministic, no unordered iteration).
+ *
+ * Membership is decided by each document's own frontmatter `type:` field, not by which directory it
+ * lives in: several types' `path` patterns collapse to the *same* static directory prefix (e.g.
+ * `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.
+ */
+export declare function listMemoryDocumentsByType(root: string, memoryYaml: MemoryYaml, type: string): MemoryDocumentFrontmatterSummary[];
+/**
+ * Resolve a single Memory document by (`type`, `id`) — spec-004 §2.1's `wingfoil://memory/{type}/{id}`
+ * single-document addressing (task-011-mcp-resources-read-only, REQ-INT-01), the conformant
+ * replacement for task-009's bare-`{id}` `findMemoryDocumentById` Resource usage. Both `type` and `id`
+ * must match a document's own frontmatter — same directory-collision reasoning as
+ * {@link listMemoryDocumentsByType} — so this never returns a document of a *different* type merely
+ * 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.
+ */
+export declare function findMemoryDocumentByTypeAndId(root: string, memoryYaml: MemoryYaml, type: string, id: string): MemoryDocumentSummary | undefined;
+/** Optional filters/refinements for {@link searchMemoryDocuments}. */
+export interface MemorySearchOptions {
+    /** Only include documents whose `tags:` frontmatter contains this exact tag. */
+    readonly tag?: string;
+    /**
+     * Opt back into archived documents (`status: deprecated` or `superseded` — `ARCHIVED_STATUSES`,
+     * ratified by `dl-028-archived-states-excluded-from-context`) appearing in the result.
+     * REQ-STATE-06 excludes them by default — "default … results" in the Fit Criterion. Set this only
+     * for an explicit, intentional request to see archived documents (e.g. an `--status deprecated` or
+     * `--status superseded` narrow); never as the default for a general keyword/tag search.
+     * Defaults to `false`.
+     */
+    readonly includeArchived?: boolean;
+}
+/** One ranked search result — enough for a future CLI/MCP surface to render without re-reading the file. */
+export interface MemorySearchMatch {
+    readonly path: string;
+    readonly id?: string;
+    readonly title?: string;
+    readonly tags: readonly string[];
+    readonly status?: string;
+    /** The document's frontmatter `type:` field (spec-010-memory-frontmatter-schema base field) —
+     * projected here (task-021-implement-memory-search) alongside `status`/`tags` so `memorySearch`'s
+     * `--type` filter can narrow an already-ranked result without a second file read per match. */
+    readonly type?: string;
+    /** Query matched the title, id, or a tag (P1.12: ranks above a body-only match). */
+    readonly metadataMatch: boolean;
+    /** Query matched somewhere in the document body. */
+    readonly bodyMatch: boolean;
+}
+/** `E_EMPTY_SEARCH_QUERY` field-level code (spec-009-validation-strategy §3) for a rejected empty
+ * or whitespace-only `wingfoil memory search` query. */
+export declare const E_EMPTY_SEARCH_QUERY = "E_EMPTY_SEARCH_QUERY";
+/**
+ * Reject an empty or whitespace-only search query (P1.12 BDD Scenario "Error - empty query string":
+ * "no search is performed" and exit code 2, message "empty search query"). Mirrors
+ * `resolveTransitionTarget`'s `ValidationError.semantic` pattern (`./state-machine.ts`) so the shared
+ * exit-code mapping (spec-009 §3) surfaces this as exit 2 without a bespoke error path; task-021's
+ * `wingfoil memory search` CLI/MCP surface calls this on the user-supplied query string before it
+ * ever reaches {@link searchMemoryDocuments}.
+ *
+ * Deliberately a separate guard, not a change to `searchMemoryDocuments`'s own signature/behavior:
+ * `searchMemoryDocuments(root, memoryYaml, '', { tag })` remains a legitimate "browse by tag alone,
+ * no keyword" call (task-008's own characterization test) — the empty-query rejection is this task's
+ * (P1.12's) algorithm-level validation concern, applied at the point a *user-facing* query string is
+ * about to be searched, not baked into the lower-level scan primitive that also serves tag-only
+ * listing.
+ */
+export declare function validateSearchQuery(query: string): void;
+/**
+ * Deterministic keyword/frontmatter search over every Memory document `memoryYaml` declares
+ * (P1.5/P1.12): case-insensitive substring matching against title/id/tags (metadata) and body text,
+ * optionally narrowed to one exact `tag`. A query that matches nothing returns `[]` — a successful,
+ * empty result, never a thrown error (that "no documents matched" outcome is a CLI/MCP-surface
+ * 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.
+ *
+ * **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
+ * `memory search` results", matching the Fit Criterion verbatim, while the file itself is untouched on
+ * disk and in git history (`memory deprecate`, P1.9, never deletes it; `superseded` is reached by an
+ * ordinary `approve`). Pass `options.includeArchived: true` for the one legitimate exception: an
+ * explicit, intentional request to see archived documents too. `draft` documents are NOT excluded
+ * here — see this module's header for why the search set and the context set differ.
+ */
+export declare function searchMemoryDocuments(root: string, memoryYaml: MemoryYaml, query: string, options?: MemorySearchOptions): MemorySearchMatch[];
+//# sourceMappingURL=query.d.ts.map

package/dist/memory/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/memory/query.ts"],"names":[],"mappings":"AAkDA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAkB3C;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,UAAU,GAAG,MAAM,EAAE,CAQ1E;AAuBD;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,MAAM,EAAE,CAMtF;AAED,wGAAwG;AACxG,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,qBAAqB,CAYnG;AAUD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,UAAU,EACtB,EAAE,EAAE,MAAM,GACT,qBAAqB,GAAG,SAAS,CAMnC;AAED;gGACgG;AAChG,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,UAAU,EACtB,IAAI,EAAE,MAAM,GACX,gCAAgC,EAAE,CAkBpC;AAED;;;;;;;;;GASG;AACH,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,UAAU,EACtB,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,GACT,qBAAqB,GAAG,SAAS,CAMnC;AAED,sEAAsE;AACtE,MAAM,WAAW,mBAAmB;IAClC,gFAAgF;IAChF,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;OAOG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;CACpC;AAED,4GAA4G;AAC5G,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;mGAE+F;IAC/F,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,oFAAoF;IACpF,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,oDAAoD;IACpD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED;wDACwD;AACxD,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAE3D;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAMvD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,UAAU,EACtB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,mBAAwB,GAChC,iBAAiB,EAAE,CAqCrB"}