@fingerskier/augment 0.3.1 → 0.4.0

package/dist/proposals.js

@@ -0,0 +1,179 @@
+import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import matter from "gray-matter";
+import { normalizeKind, normalizeLinkType } from "./memory/files.js";
+import { safeSegment } from "./memory/project.js";
+/** sleep -> `<stateDir>/sleeps`; dream-memory | dream-link -> `<stateDir>/dreams`. */
+export function proposalsDir(stateDir, type) {
+    return path.join(stateDir, type === "sleep" ? "sleeps" : "dreams");
+}
+export async function writeProposal(stateDir, fm, body) {
+    const dir = proposalsDir(stateDir, fm.type);
+    await mkdir(dir, { recursive: true });
+    const now = new Date().toISOString();
+    // Conditionally spread optional keys so an unset field is omitted from the
+    // object entirely (and thus from the written YAML) instead of being
+    // written as an explicit `null` -- mirrors normalizeFrontmatter's
+    // consolidated_into/derived_from handling in memory/files.ts.
+    const frontmatter = {
+        type: fm.type,
+        project: fm.project,
+        status: "proposed",
+        ...(fm.kind !== undefined ? { kind: fm.kind } : {}),
+        ...(fm.name !== undefined ? { name: fm.name } : {}),
+        derived_from: fm.derived_from,
+        ...(fm.link !== undefined ? { link: fm.link } : {}),
+        ...(fm.rationale !== undefined ? { rationale: fm.rationale } : {}),
+        created_at: now,
+        updated_at: now,
+    };
+    const stamp = timestampSegment(new Date());
+    const base = `${stamp}-${safeSegment(fm.name ?? "link")}`;
+    const filename = await uniqueFilename(dir, base);
+    const trimmedBody = body.trim();
+    await writeFile(path.join(dir, filename), matter.stringify(`${trimmedBody}\n`, frontmatter), "utf8");
+    return { frontmatter, body: trimmedBody, filename };
+}
+export async function readProposal(stateDir, type, filename) {
+    assertSafeFilename(filename);
+    const dir = proposalsDir(stateDir, type);
+    const raw = await readFile(path.join(dir, filename), "utf8");
+    const parsed = matter(raw);
+    return {
+        frontmatter: normalizeProposalFrontmatter(parsed.data),
+        body: parsed.content.trim(),
+        filename,
+    };
+}
+export async function listProposals(stateDir, type, status) {
+    const dir = proposalsDir(stateDir, type);
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return [];
+        }
+        throw error;
+    }
+    const filenames = entries.filter((entry) => entry.endsWith(".md")).sort();
+    const proposals = [];
+    for (const filename of filenames) {
+        try {
+            const proposal = await readProposal(stateDir, type, filename);
+            if (!status || proposal.frontmatter.status === status) {
+                proposals.push(proposal);
+            }
+        }
+        catch (error) {
+            console.warn(`Skipping unparseable proposal ${path.join(dir, filename)}: ${error.message}`);
+        }
+    }
+    return proposals;
+}
+export async function setProposalStatus(stateDir, type, filename, status) {
+    const existing = await readProposal(stateDir, type, filename);
+    const frontmatter = {
+        ...existing.frontmatter,
+        status,
+        updated_at: new Date().toISOString(),
+    };
+    const dir = proposalsDir(stateDir, type);
+    await writeFile(path.join(dir, filename), matter.stringify(`${existing.body}\n`, frontmatter), "utf8");
+    return { frontmatter, body: existing.body, filename };
+}
+export function renderProposalsText(proposals, type) {
+    if (proposals.length === 0) {
+        return `No ${type} proposals.\n`;
+    }
+    let out = `${type} proposals (${proposals.length}):\n`;
+    proposals.forEach((proposal, index) => {
+        const fm = proposal.frontmatter;
+        const subject = fm.link
+            ? `link ${fm.link.from} -> ${fm.link.to} (${fm.link.type})`
+            : `${fm.kind ?? "?"} ${fm.name ?? "?"}`;
+        out += `\n[${index + 1}] ${proposal.filename} status:${fm.status} project:${fm.project}\n`;
+        out += `  ${subject}\n`;
+        out += `  derived_from: ${fm.derived_from.length > 0 ? fm.derived_from.join(", ") : "(none)"}\n`;
+        if (fm.rationale) {
+            out += `  rationale: ${fm.rationale}\n`;
+        }
+    });
+    return out;
+}
+// yyyymmdd-hhmmss in UTC, so lexical filename sort matches chronological order
+// regardless of the host machine's local timezone.
+function timestampSegment(date) {
+    const pad = (value) => String(value).padStart(2, "0");
+    const y = date.getUTCFullYear();
+    const mo = pad(date.getUTCMonth() + 1);
+    const d = pad(date.getUTCDate());
+    const h = pad(date.getUTCHours());
+    const mi = pad(date.getUTCMinutes());
+    const s = pad(date.getUTCSeconds());
+    return `${y}${mo}${d}-${h}${mi}${s}`;
+}
+async function uniqueFilename(dir, base) {
+    let candidate = `${base}.md`;
+    let attempt = 2;
+    while (await pathExists(path.join(dir, candidate))) {
+        candidate = `${base}-${attempt}.md`;
+        attempt += 1;
+    }
+    return candidate;
+}
+async function pathExists(absolutePath) {
+    try {
+        await stat(absolutePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// Security: filenames come from callers (including MCP tool args in later
+// tasks) and are joined directly onto proposalsDir(). Reject anything that
+// could escape that directory -- a path separator (either slash, since this
+// repo runs on Windows too) or a bare "." / ".." segment.
+function assertSafeFilename(filename) {
+    if (!filename || /[\\/]/.test(filename) || filename === "." || filename === "..") {
+        throw new Error(`Invalid proposal filename: ${filename}`);
+    }
+}
+// Defensive re-parse of raw YAML frontmatter data. Proposals are
+// user-editable on disk, and gray-matter's underlying YAML parser will turn
+// an unquoted ISO-looking date into a native Date object rather than a
+// string -- coerce dates back to strings the same way
+// memory/files.ts#normalizeFrontmatter does. kind/link.type are revalidated
+// through the existing normalizeKind/normalizeLinkType so a hand-edited typo
+// fails loudly instead of silently corrupting the frontmatter.
+function normalizeProposalFrontmatter(data) {
+    const frontmatter = {
+        type: data.type,
+        project: String(data.project ?? ""),
+        status: data.status,
+        derived_from: Array.isArray(data.derived_from) ? data.derived_from.map(String) : [],
+        created_at: String(data.created_at ?? ""),
+        updated_at: String(data.updated_at ?? ""),
+    };
+    if (data.kind !== undefined) {
+        frontmatter.kind = normalizeKind(String(data.kind));
+    }
+    if (data.name !== undefined) {
+        frontmatter.name = String(data.name);
+    }
+    if (data.link && typeof data.link === "object") {
+        const link = data.link;
+        frontmatter.link = {
+            from: String(link.from ?? ""),
+            to: String(link.to ?? ""),
+            type: normalizeLinkType(String(link.type)),
+        };
+    }
+    if (data.rationale !== undefined) {
+        frontmatter.rationale = String(data.rationale);
+    }
+    return frontmatter;
+}
+//# sourceMappingURL=proposals.js.map

package/dist/proposals.js.map

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

package/dist/recall-log.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Passive per-search recall log. Successor to the Phase-2 dogfood tally
+ * (removed per GH issue #3): the human-rating surface is gone, but the
+ * per-search event log stays — it is the instrument that caught the
+ * 2026-07-10 memoryRoot split-brain. Best-effort by design: a failed append
+ * must never fail the search that triggered it.
+ */
+export declare const RECALL_LOG_MAX_BYTES = 5000000;
+/** One automatically-logged injection event (what search actually returned). */
+export interface RecallEvent {
+    ts: string;
+    surface: string;
+    project?: string;
+    query: string;
+    abstained: boolean;
+    result_count: number;
+    top_score?: number;
+    paths: string[];
+}
+export declare function eventsPath(stateDir: string): string;
+export declare function appendRecallEvent(stateDir: string, event: RecallEvent): Promise<void>;

package/dist/recall-log.js

@@ -0,0 +1,24 @@
+import { appendFile, mkdir, rename, stat } from "node:fs/promises";
+import path from "node:path";
+/**
+ * Passive per-search recall log. Successor to the Phase-2 dogfood tally
+ * (removed per GH issue #3): the human-rating surface is gone, but the
+ * per-search event log stays — it is the instrument that caught the
+ * 2026-07-10 memoryRoot split-brain. Best-effort by design: a failed append
+ * must never fail the search that triggered it.
+ */
+export const RECALL_LOG_MAX_BYTES = 5_000_000;
+export function eventsPath(stateDir) {
+    return path.join(stateDir, "recall", "events.jsonl");
+}
+export async function appendRecallEvent(stateDir, event) {
+    const file = eventsPath(stateDir);
+    await mkdir(path.dirname(file), { recursive: true });
+    // Single-slot rotation: the log is diagnostic, not a record of account.
+    const size = await stat(file).then((s) => s.size).catch(() => 0);
+    if (size > RECALL_LOG_MAX_BYTES) {
+        await rename(file, `${file}.1`).catch(() => { });
+    }
+    await appendFile(file, `${JSON.stringify(event)}\n`, "utf8");
+}
+//# sourceMappingURL=recall-log.js.map

package/dist/recall-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recall-log.js","sourceRoot":"","sources":["../src/recall-log.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACnE,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B;;;;;;GAMG;AAEH,MAAM,CAAC,MAAM,oBAAoB,GAAG,SAAS,CAAC;AAc9C,MAAM,UAAU,UAAU,CAAC,QAAgB;IACzC,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,EAAE,cAAc,CAAC,CAAC;AACvD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,QAAgB,EAAE,KAAkB;IAC1E,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;IAClC,MAAM,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACrD,wEAAwE;IACxE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC;IACjE,IAAI,IAAI,GAAG,oBAAoB,EAAE,CAAC;QAChC,MAAM,MAAM,CAAC,IAAI,EAAE,GAAG,IAAI,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IAClD,CAAC;IACD,MAAM,UAAU,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AAC/D,CAAC"}

package/dist/recall.d.ts

@@ -11,7 +11,7 @@ export interface RecallOptions {
     maxChars?: number;
     /** Minimum relevance score (0..1); 0 disables the floor. */
     minScore?: number;
-    /** Injection surface tag for the dogfood tally (see src/tally.ts). */
+    /** Injection surface tag recorded in the per-search recall log (see src/recall-log.ts). */
     surface?: string;
 }
 /** The slice of the daemon client `recall` depends on — kept narrow so tests can inject a fake. */

package/dist/service.d.ts

@@ -1,6 +1,7 @@
 import type { AugmentConfig } from "./config.js";
 import { AugmentDatabase } from "./db.js";
 import type { EmbeddingProvider } from "./embeddings.js";
+import { type Proposal, type ProposalStatus } from "./proposals.js";
 import { type SleepCluster } from "./sleep.js";
 import type { LinkRecord, MemoryRecord, ProjectGraph, ProjectRecord, SearchInput, SearchResult, UpsertInput } from "./types.js";
 export interface InitProjectInput {
@@ -28,6 +29,26 @@ export interface SleepCandidatesOutput {
     clusters: SleepCluster[];
     eligible: number;
 }
+/** Draft a sleep consolidation: >=2 WORK sources fold into one new SPEC/ARCH.
+ * The proposal is written OUTSIDE the corpus for review; nothing is consolidated
+ * until {@link AugmentService.sleepApply}. */
+export interface SleepProposeInput {
+    project_name: string;
+    kind: "SPEC" | "ARCH";
+    name: string;
+    content: string;
+    derived_from: string[];
+    rationale?: string;
+}
+export interface SleepApplyInput {
+    filename: string;
+}
+export interface SleepApplyOutput {
+    memory: MemoryRecord;
+    archived: string[];
+    proposal: Proposal;
+    text: string;
+}
 export declare class AugmentService {
     private readonly config;
     private readonly embeddingProvider;
@@ -112,6 +133,48 @@ export declare class AugmentService {
      * behind the Phase-2 go/no-go and does not exist.
      */
     sleepCandidates(input?: SleepCandidatesInput, now?: number): Promise<SleepCandidatesOutput>;
+    /**
+     * Draft a sleep consolidation as a review artifact OUTSIDE the corpus. Writes
+     * nothing to the memory store: the corpus is only mutated by {@link sleepApply}
+     * on an explicitly approved proposal. Validates the sources up front (same
+     * checks apply re-runs against the live corpus) so an impossible proposal fails
+     * loudly at draft time.
+     */
+    sleepPropose(input: SleepProposeInput): Promise<{
+        proposal: Proposal;
+        text: string;
+    }>;
+    sleepProposals(status?: ProposalStatus): Promise<{
+        proposals: Proposal[];
+        text: string;
+    }>;
+    /**
+     * Apply an approved sleep proposal — the ONLY corpus mutation in the flow. The
+     * sequence is a contract: read the proposal fresh from disk (user edits count),
+     * require it still be `proposed`, re-validate against the LIVE corpus (drafts
+     * sit while the corpus moves underneath them), upsert the consolidated record
+     * (provenance threaded into frontmatter), archive each source in place (body
+     * untouched, verbatim), then flip the proposal to `applied`. Does NOT commit
+     * git: the route commits the whole pass as one revertible commit.
+     */
+    sleepApply(input: SleepApplyInput): Promise<SleepApplyOutput>;
+    private sleepApplyCore;
+    sleepReject(filename: string): Promise<{
+        proposal: Proposal;
+        text: string;
+    }>;
+    /**
+     * Shared sleep validation, run at propose time and re-run against the live
+     * corpus at apply time. Every source must resolve, be a WORK memory in
+     * `projectName` (single-project constraint), and be unarchived; there must be
+     * >=2 of them; and the consolidation target must not already exist. Every
+     * violation names the offending path.
+     */
+    private validateSleepSources;
+    /** Rewrite one source's frontmatter to archived + consolidated_into, leaving
+     * the body verbatim, and reindex it. Mirrors {@link scrubInboundLinks}. Returns
+     * the source's relative path. */
+    private archiveSource;
     private findSimilarMemory;
     private ensureEmbedding;
 }

package/dist/service.js

@@ -1,12 +1,13 @@
 import { stat } from "node:fs/promises";
 import path from "node:path";
-import { DEFAULT_MEMORY_HARD_LIMIT_CHARS, DEFAULT_SEARCH_LIMIT, DEFAULT_SEARCH_MAX_CHARS, DEFAULT_SEARCH_MIN_SCORE, SEMANTIC_COSINE_BASELINE, SEMANTIC_COSINE_MATCH, SLEEP_MAX_CLUSTERS, SLEEP_MIN_AGE_DAYS, SLEEP_MIN_COSINE, } from "./constants.js";
+import { ARCHIVED_SEARCH_WEIGHT, DEFAULT_MEMORY_HARD_LIMIT_CHARS, DEFAULT_SEARCH_LIMIT, DEFAULT_SEARCH_MAX_CHARS, DEFAULT_SEARCH_MIN_SCORE, SEMANTIC_COSINE_BASELINE, SEMANTIC_COSINE_MATCH, SLEEP_MAX_CLUSTERS, SLEEP_MIN_AGE_DAYS, SLEEP_MIN_COSINE, } from "./constants.js";
 import { ensureConfigDirs } from "./config.js";
 import { AugmentDatabase } from "./db.js";
 import { TransformersEmbeddingProvider } from "./embeddings.js";
 import { deleteMemoryFile, normalizeKind, normalizeLinkType, normalizeRelativePath, memoryRelativePath, readMemory, writeMemory } from "./memory/files.js";
 import { inferProjectName } from "./memory/project.js";
 import { findMemoryFiles } from "./memory/scan.js";
+import { listProposals, readProposal, renderProposalsText, setProposalStatus, writeProposal, } from "./proposals.js";
 import { clusterSleepCandidates, renderSleepCandidatesText } from "./sleep.js";
 import { clamp01, cosineSimilarity, lexicalScoreWith, tokens } from "./util/text.js";
 /** How long a self-write marker stays claimable. Long enough to cover the watcher's
@@ -204,7 +205,9 @@ export class AugmentService {
                 // memory at its deterministic path instead. Both versions stay
                 // recoverable from the store and the prior body never pollutes the new
                 // memory's embedding/lexical document.
-                if (similar && lexicalScoreWith(new Set(tokens(similar.body)), input.content) >= 1) {
+                if (!input.skip_similarity_fold &&
+                    similar &&
+                    lexicalScoreWith(new Set(tokens(similar.body)), input.content) >= 1) {
                     existing = similar;
                     relativePath = similar.relative_path;
                     action = "similar-updated";
@@ -220,6 +223,9 @@ export class AugmentService {
                 links: existing.links,
                 created_at: existing.created_at,
                 updated_at: now,
+                archived: existing.archived,
+                consolidated_into: existing.consolidated_into,
+                derived_from: input.derived_from ?? existing.derived_from,
             }
             : {
                 project: project.name,
@@ -229,6 +235,7 @@ export class AugmentService {
                 links: [],
                 created_at: now,
                 updated_at: now,
+                derived_from: input.derived_from,
             };
         await writeMemory(this.config.memoryRoot, relativePath, normalizeMemoryFrontmatter(metadata), input.content);
         this.recordSelfWrite(relativePath);
@@ -306,6 +313,9 @@ export class AugmentService {
                 links: memory.links.filter((link) => link.to !== targetPath),
                 created_at: memory.created_at,
                 updated_at: new Date().toISOString(),
+                archived: memory.archived,
+                consolidated_into: memory.consolidated_into,
+                derived_from: memory.derived_from,
             });
             await writeMemory(this.config.memoryRoot, memory.relative_path, frontmatter, memory.body);
             this.recordSelfWrite(memory.relative_path);
@@ -353,6 +363,9 @@ export class AugmentService {
             links: mergeFrontmatterLink(from.links, { to: to.relative_path, type }),
             created_at: from.created_at,
             updated_at: new Date().toISOString(),
+            archived: from.archived,
+            consolidated_into: from.consolidated_into,
+            derived_from: from.derived_from,
         });
         await writeMemory(this.config.memoryRoot, from.relative_path, frontmatter, from.body);
         this.recordSelfWrite(from.relative_path);
@@ -396,6 +409,9 @@ export class AugmentService {
             links: from.links.filter((candidate) => !(candidate.to === link.to_relative_path && candidate.type === link.type)),
             created_at: from.created_at,
             updated_at: new Date().toISOString(),
+            archived: from.archived,
+            consolidated_into: from.consolidated_into,
+            derived_from: from.derived_from,
         });
         await writeMemory(this.config.memoryRoot, from.relative_path, frontmatter, from.body);
         this.recordSelfWrite(from.relative_path);
@@ -462,7 +478,15 @@ export class AugmentService {
             const semanticScore = queryEmbedding ? normalizedCosine(queryEmbedding, embeddings.get(memory.id)) : 0;
             const lexScore = lexicalScoreWith(queryTokens, searchDocument(memory));
             const metadataScore = metadataScoreFor(input.project_name, memory);
-            const score = clamp01(semanticScore * 0.55 + lexScore * 0.25 + metadataScore * 0.1);
+            let score = clamp01(semanticScore * 0.55 + lexScore * 0.25 + metadataScore * 0.1);
+            // Down-weight (never exclude) an archived memory's own relevance, after
+            // the blend and before the relevance floor below -- so a down-weighted
+            // score CAN fall under the floor and be abstained on, but read() still
+            // returns its full body verbatim (archival is a search-time concern
+            // only). See ARCHIVED_SEARCH_WEIGHT in constants.ts.
+            if (memory.archived) {
+                score = clamp01(score * ARCHIVED_SEARCH_WEIGHT);
+            }
             direct.set(memory.id, {
                 memory,
                 score,
@@ -513,6 +537,7 @@ export class AugmentService {
         const snapshot = await this.corpus();
         const cutoff = now - minAgeDays * 86_400_000;
         const eligible = snapshot.memories.filter((memory) => memory.kind === "WORK" &&
+            !memory.archived && // a consolidated source shouldn't be re-consolidated
             (!input.project_name || memory.project_name === input.project_name) &&
             Date.parse(memory.updated_at) <= cutoff);
         const clusters = clusterSleepCandidates({
@@ -527,6 +552,169 @@ export class AugmentService {
             text: renderSleepCandidatesText(clusters, eligible.length, minCosine, minAgeDays),
         };
     }
+    /**
+     * Draft a sleep consolidation as a review artifact OUTSIDE the corpus. Writes
+     * nothing to the memory store: the corpus is only mutated by {@link sleepApply}
+     * on an explicitly approved proposal. Validates the sources up front (same
+     * checks apply re-runs against the live corpus) so an impossible proposal fails
+     * loudly at draft time.
+     */
+    async sleepPropose(input) {
+        await this.init();
+        const kind = normalizeKind(input.kind);
+        await this.validateSleepSources(input.project_name, kind, input.name, input.derived_from);
+        const proposal = await writeProposal(this.config.stateDir, {
+            type: "sleep",
+            project: input.project_name,
+            kind,
+            name: input.name,
+            derived_from: input.derived_from,
+            ...(input.rationale !== undefined ? { rationale: input.rationale } : {}),
+        }, input.content);
+        return { proposal, text: renderProposalsText([proposal], "sleep") };
+    }
+    async sleepProposals(status) {
+        await this.init();
+        const proposals = await listProposals(this.config.stateDir, "sleep", status);
+        return { proposals, text: renderProposalsText(proposals, "sleep") };
+    }
+    /**
+     * Apply an approved sleep proposal — the ONLY corpus mutation in the flow. The
+     * sequence is a contract: read the proposal fresh from disk (user edits count),
+     * require it still be `proposed`, re-validate against the LIVE corpus (drafts
+     * sit while the corpus moves underneath them), upsert the consolidated record
+     * (provenance threaded into frontmatter), archive each source in place (body
+     * untouched, verbatim), then flip the proposal to `applied`. Does NOT commit
+     * git: the route commits the whole pass as one revertible commit.
+     */
+    async sleepApply(input) {
+        try {
+            return await this.sleepApplyCore(input);
+        }
+        finally {
+            this.invalidateCorpusSnapshot();
+        }
+    }
+    async sleepApplyCore(input) {
+        await this.init();
+        // 1. Read the proposal fresh from disk so hand-edits (body, sources) count.
+        const proposal = await readProposal(this.config.stateDir, "sleep", input.filename);
+        const fm = proposal.frontmatter;
+        // 2. Only a still-proposed draft may apply; a second apply is rejected here.
+        if (fm.status !== "proposed") {
+            throw new Error(`Sleep proposal ${input.filename} is already ${fm.status}, not proposed (already applied?)`);
+        }
+        if (!fm.kind) {
+            throw new Error(`Sleep proposal ${input.filename} is missing a target kind`);
+        }
+        if (!fm.name) {
+            throw new Error(`Sleep proposal ${input.filename} is missing a target name`);
+        }
+        const kind = normalizeKind(fm.kind);
+        const name = fm.name;
+        const projectName = fm.project;
+        const derivedFrom = fm.derived_from;
+        // 3. Re-validate against the live corpus (sources may have moved since draft).
+        await this.validateSleepSources(projectName, kind, name, derivedFrom);
+        const project = await this.db.getProjectByName(projectName);
+        if (!project) {
+            throw new Error(`Sleep proposal project not found in corpus: ${projectName}`);
+        }
+        // 4. Write the consolidated record through the public upsert (snapshot
+        // invalidation + provenance handled there). skip_similarity_fold pins the
+        // write to the approved target's deterministic path: the user approved
+        // THIS identity (validateSleepSources above already guaranteed it's
+        // free), so upsertCore must not divert it into some other lexically-
+        // similar same-kind record it happens to subsume.
+        const upserted = await this.upsert({
+            project_id: project.id,
+            kind,
+            name,
+            content: proposal.body,
+            derived_from: derivedFrom,
+            skip_similarity_fold: true,
+        });
+        const expectedTargetPath = memoryRelativePath(projectName, kind, name);
+        if (upserted.memory.relative_path !== expectedTargetPath) {
+            throw new Error(`Sleep apply diverted from the approved target ${expectedTargetPath} to ${upserted.memory.relative_path}; aborting before archiving any source`);
+        }
+        const consolidatedInto = upserted.memory.relative_path;
+        // 5. Archive each source in place, pointing it at the consolidated record.
+        const archived = [];
+        for (const sourcePath of derivedFrom) {
+            archived.push(await this.archiveSource(sourcePath, consolidatedInto));
+        }
+        // 6. Flip the proposal to applied (outside the corpus).
+        const appliedProposal = await setProposalStatus(this.config.stateDir, "sleep", input.filename, "applied");
+        return {
+            memory: upserted.memory,
+            archived,
+            proposal: appliedProposal,
+            text: `applied sleep ${input.filename}: ${derivedFrom.length} WORK -> ${kind}/${name} (${projectName})`,
+        };
+    }
+    async sleepReject(filename) {
+        await this.init();
+        const proposal = await setProposalStatus(this.config.stateDir, "sleep", filename, "rejected");
+        return { proposal, text: renderProposalsText([proposal], "sleep") };
+    }
+    /**
+     * Shared sleep validation, run at propose time and re-run against the live
+     * corpus at apply time. Every source must resolve, be a WORK memory in
+     * `projectName` (single-project constraint), and be unarchived; there must be
+     * >=2 of them; and the consolidation target must not already exist. Every
+     * violation names the offending path.
+     */
+    async validateSleepSources(projectName, kind, name, derivedFrom) {
+        if (derivedFrom.length < 2) {
+            throw new Error(`A sleep consolidation needs at least 2 WORK sources; got ${derivedFrom.length}`);
+        }
+        for (const sourcePath of derivedFrom) {
+            const source = await this.db.getMemoryByPath(normalizeRelativePath(sourcePath));
+            if (!source) {
+                throw new Error(`Sleep source not found in corpus: ${sourcePath}`);
+            }
+            if (source.kind !== "WORK") {
+                throw new Error(`Sleep source must be a WORK memory: ${sourcePath} is ${source.kind}`);
+            }
+            if (source.project_name !== projectName) {
+                throw new Error(`Sleep source ${sourcePath} belongs to ${source.project_name}, not ${projectName}`);
+            }
+            if (source.archived) {
+                throw new Error(`Sleep source is already archived: ${sourcePath}`);
+            }
+        }
+        const targetPath = memoryRelativePath(projectName, kind, name);
+        if (await this.db.getMemoryByPath(targetPath)) {
+            throw new Error(`Sleep target already exists in corpus: ${targetPath}`);
+        }
+    }
+    /** Rewrite one source's frontmatter to archived + consolidated_into, leaving
+     * the body verbatim, and reindex it. Mirrors {@link scrubInboundLinks}. Returns
+     * the source's relative path. */
+    async archiveSource(sourcePath, consolidatedInto) {
+        const memory = await this.db.getMemoryByPath(normalizeRelativePath(sourcePath));
+        if (!memory) {
+            throw new Error(`Sleep source not found in corpus: ${sourcePath}`);
+        }
+        const frontmatter = normalizeMemoryFrontmatter({
+            project: memory.project_name,
+            kind: memory.kind,
+            name: memory.name,
+            tags: memory.tags,
+            links: memory.links,
+            created_at: memory.created_at,
+            updated_at: new Date().toISOString(),
+            archived: true,
+            consolidated_into: consolidatedInto,
+            derived_from: memory.derived_from,
+        });
+        await writeMemory(this.config.memoryRoot, memory.relative_path, frontmatter, memory.body);
+        this.recordSelfWrite(memory.relative_path);
+        const parsed = await readMemory(this.config.memoryRoot, memory.relative_path);
+        await this.db.upsertMemory(parsed);
+        return memory.relative_path;
+    }
     async findSimilarMemory(projectId, kind, content) {
         const candidates = await this.db.listMemoriesForProject(projectId, kind);
         const contentTokens = new Set(tokens(content));
@@ -557,6 +745,19 @@ function normalizeMemoryFrontmatter(input) {
         links: input.links ?? [],
         created_at: input.created_at,
         updated_at: input.updated_at,
+        // Every corpus-mutating write reconstructs frontmatter through this
+        // function. Keys are included ONLY when set so an ordinary (never
+        // archived) memory never gains "archived: false" churn -- but every
+        // caller MUST thread archived/consolidated_into/derived_from through from
+        // the existing record, or a write that has nothing to do with archival
+        // state (link/unlink/scrub) would silently strip it.
+        ...(input.archived === true ? { archived: true } : {}),
+        ...(typeof input.consolidated_into === "string"
+            ? { consolidated_into: normalizeRelativePath(input.consolidated_into) }
+            : {}),
+        ...(Array.isArray(input.derived_from)
+            ? { derived_from: input.derived_from.map((entry) => normalizeRelativePath(entry)) }
+            : {}),
     };
 }
 function mergeFrontmatterLink(links, link) {