@fingerskier/augment 0.3.1 → 0.5.0

package/dist/service.js

@@ -1,12 +1,14 @@
 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 { discoverDecoctionCandidates, } from "./decoction.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 { GENERIC_PROJECT_NAME, inferProjectName, isGenericProjectName } 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
@@ -32,6 +34,10 @@ export class AugmentService {
      * searches. */
     corpusPromise;
     queryEmbeddingCache = new Map();
+    /** FIFO critical section for every corpus mutation. Compound operations use
+     * their private `*Core` helpers while holding this lock so their validation,
+     * frontmatter rewrites, and deletes cannot interleave with another request. */
+    mutationTail = Promise.resolve();
     constructor(config, embeddingProvider = new TransformersEmbeddingProvider()) {
         this.config = config;
         this.embeddingProvider = embeddingProvider;
@@ -70,12 +76,14 @@ export class AugmentService {
         return this.db.listProjects(name);
     }
     async rebuildIndex() {
-        try {
-            return await this.rebuildIndexCore();
-        }
-        finally {
-            this.invalidateCorpusSnapshot();
-        }
+        return this.serializeMutation(async () => {
+            try {
+                return await this.rebuildIndexCore();
+            }
+            finally {
+                this.invalidateCorpusSnapshot();
+            }
+        });
     }
     async rebuildIndexCore() {
         await ensureConfigDirs(this.config);
@@ -113,12 +121,15 @@ export class AugmentService {
      * deletion is not authorization to rewrite other files (unlike {@link deleteMemory}).
      */
     async indexPath(relativePath) {
-        try {
-            await this.indexPathCore(relativePath);
-        }
-        finally {
-            this.invalidateCorpusSnapshot();
-        }
+        await this.init();
+        return this.serializeMutation(async () => {
+            try {
+                await this.indexPathCore(relativePath);
+            }
+            finally {
+                this.invalidateCorpusSnapshot();
+            }
+        });
     }
     async indexPathCore(relativePath) {
         await this.init();
@@ -153,14 +164,32 @@ export class AugmentService {
     recordSelfWrite(relativePath) {
         this.selfWrites.set(normalizeRelativePath(relativePath), Date.now());
     }
-    async upsert(input) {
+    async memoryFileExists(relativePath) {
         try {
-            return await this.upsertCore(input);
+            await stat(path.join(this.config.memoryRoot, normalizeRelativePath(relativePath)));
+            return true;
         }
-        finally {
-            this.invalidateCorpusSnapshot();
+        catch (error) {
+            if (typeof error === "object" &&
+                error !== null &&
+                "code" in error &&
+                error.code === "ENOENT") {
+                return false;
+            }
+            throw error;
         }
     }
+    async upsert(input) {
+        await this.init();
+        return this.serializeMutation(async () => {
+            try {
+                return await this.upsertCore(input);
+            }
+            finally {
+                this.invalidateCorpusSnapshot();
+            }
+        });
+    }
     async upsertCore(input) {
         await this.init();
         if (input.content.length > DEFAULT_MEMORY_HARD_LIMIT_CHARS) {
@@ -204,7 +233,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 +251,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 +263,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);
@@ -269,12 +304,15 @@ export class AugmentService {
         return { project, memories, links };
     }
     async deleteMemory(id) {
-        try {
-            return await this.deleteMemoryCore(id);
-        }
-        finally {
-            this.invalidateCorpusSnapshot();
-        }
+        await this.init();
+        return this.serializeMutation(async () => {
+            try {
+                return await this.deleteMemoryCore(id);
+            }
+            finally {
+                this.invalidateCorpusSnapshot();
+            }
+        });
     }
     async deleteMemoryCore(id) {
         await this.init();
@@ -306,6 +344,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);
@@ -333,12 +374,15 @@ export class AugmentService {
         return memory;
     }
     async link(fromRef, toRef, typeInput) {
-        try {
-            return await this.linkCore(fromRef, toRef, typeInput);
-        }
-        finally {
-            this.invalidateCorpusSnapshot();
-        }
+        await this.init();
+        return this.serializeMutation(async () => {
+            try {
+                return await this.linkCore(fromRef, toRef, typeInput);
+            }
+            finally {
+                this.invalidateCorpusSnapshot();
+            }
+        });
     }
     async linkCore(fromRef, toRef, typeInput) {
         await this.init();
@@ -353,6 +397,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);
@@ -374,12 +421,15 @@ export class AugmentService {
         return this.db.listLinks(memoryId);
     }
     async unlink(linkId) {
-        try {
-            return await this.unlinkCore(linkId);
-        }
-        finally {
-            this.invalidateCorpusSnapshot();
-        }
+        await this.init();
+        return this.serializeMutation(async () => {
+            try {
+                return await this.unlinkCore(linkId);
+            }
+            finally {
+                this.invalidateCorpusSnapshot();
+            }
+        });
     }
     async unlinkCore(linkId) {
         await this.init();
@@ -396,6 +446,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);
@@ -407,6 +460,14 @@ export class AugmentService {
     invalidateCorpusSnapshot() {
         this.corpusPromise = undefined;
     }
+    /** Queue one corpus mutation after the previous request, keeping the queue
+     * usable after failures. Assignment happens synchronously before any caller
+     * can enqueue the next request. */
+    serializeMutation(mutation) {
+        const result = this.mutationTail.then(mutation);
+        this.mutationTail = result.then(() => undefined, () => undefined);
+        return result;
+    }
     corpus() {
         if (!this.corpusPromise) {
             const build = (async () => ({
@@ -447,6 +508,10 @@ export class AugmentService {
     }
     async search(input) {
         await this.init();
+        // `.generic` is a storage pseudo-project, never an active/current project.
+        // Explicit generic CRUD remains valid, but search must not grant generics
+        // exact-project priority when a caller passes the reserved name.
+        const activeProjectName = input.project_name && isGenericProjectName(input.project_name) ? undefined : input.project_name;
         const limit = input.limit ?? DEFAULT_SEARCH_LIMIT;
         const maxChars = input.max_chars ?? DEFAULT_SEARCH_MAX_CHARS;
         const minScore = clamp01(input.min_score ?? DEFAULT_SEARCH_MIN_SCORE);
@@ -461,8 +526,16 @@ export class AugmentService {
         for (const memory of memories) {
             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);
+            const metadataScore = metadataScoreFor(activeProjectName, memory);
+            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,
@@ -497,13 +570,243 @@ export class AugmentService {
             .slice(0, limit);
         return {
             results,
-            text: renderSearchText(input.query, input.project_name, results, maxChars),
+            text: renderSearchText(input.query, activeProjectName, results, maxChars),
+        };
+    }
+    async decoctionGlean(input) {
+        await this.init();
+        if (input.action === "discover") {
+            const limit = input.limit ?? 20;
+            if (!Number.isInteger(limit) || limit < 1 || limit > 50) {
+                throw new RangeError("Decoction discovery limit must be an integer between 1 and 50");
+            }
+            const snapshot = await this.corpus();
+            const discovered = discoverDecoctionCandidates({
+                memories: snapshot.memories,
+                embeddings: snapshot.embeddings,
+                ...(input.min_cosine !== undefined ? { minCosine: input.min_cosine } : {}),
+            });
+            const clusters = discovered.clusters.slice(0, limit);
+            return {
+                action: "discover",
+                ...discovered,
+                clusters,
+                text: renderDecoctionDiscoveryText(clusters, discovered.eligible, discovered.min_cosine),
+            };
+        }
+        if (input.action !== "write") {
+            throw new Error(`Unsupported decoction glean action: ${String(input.action)}`);
+        }
+        return this.serializeMutation(async () => {
+            try {
+                return await this.decoctionGleanWrite(input);
+            }
+            finally {
+                this.invalidateCorpusSnapshot();
+            }
+        });
+    }
+    async decoctionGleanWrite(input) {
+        const kind = normalizeKind(input.kind);
+        if (kind !== "SPEC" && kind !== "ARCH") {
+            throw new Error(`A generic memory created by glean must be SPEC or ARCH, not ${kind}`);
+        }
+        if (!input.name.trim()) {
+            throw new Error("A generic memory requires a non-empty name");
+        }
+        if (!Array.isArray(input.derived_from)) {
+            throw new Error("A generic memory requires derived_from evidence paths");
+        }
+        const sourcePaths = input.derived_from.map((sourcePath) => normalizeRelativePath(sourcePath));
+        if (new Set(sourcePaths).size !== sourcePaths.length) {
+            throw new Error("Generic memory evidence paths must be unique");
+        }
+        const sources = [];
+        for (const sourcePath of sourcePaths) {
+            const source = await this.db.getMemoryByPath(sourcePath);
+            if (!source) {
+                throw new Error(`Decoction evidence source not found in corpus: ${sourcePath}`);
+            }
+            if (isGenericProjectName(source.project_name) || source.relative_path.startsWith(`${GENERIC_PROJECT_NAME}/`)) {
+                throw new Error(`A generic memory cannot be used as original decoction evidence: ${sourcePath}`);
+            }
+            if (source.archived) {
+                throw new Error(`Archived memory cannot be used as decoction evidence: ${sourcePath}`);
+            }
+            if (!["WORK", "ISSUE", "SPEC", "ARCH"].includes(source.kind)) {
+                throw new Error(`Unsupported decoction evidence kind ${source.kind}: ${sourcePath}`);
+            }
+            const excludedTag = source.tags.find((tag) => ["private", "no-generalize"].includes(tag.trim().toLowerCase()));
+            if (excludedTag) {
+                throw new Error(`Memory tagged ${excludedTag} cannot be used as decoction evidence: ${sourcePath}`);
+            }
+            sources.push(source);
+        }
+        const distinctProjects = new Set(sources.map((source) => source.project_name));
+        if (distinctProjects.size < 4) {
+            throw new Error(`Generic memory evidence must span at least 4 distinct projects; received ${distinctProjects.size}`);
+        }
+        const sourcePathSet = new Set(sourcePaths);
+        const suggestedRemovals = (input.suggested_removals ?? []).map((suggestion) => {
+            const normalizedPath = normalizeRelativePath(suggestion.path);
+            if (!sourcePathSet.has(normalizedPath)) {
+                throw new Error(`Suggested removal must also be a derived_from evidence source: ${suggestion.path}`);
+            }
+            const reason = suggestion.reason.trim();
+            if (!reason) {
+                throw new Error(`Suggested removal requires a reason: ${suggestion.path}`);
+            }
+            return { path: normalizedPath, reason };
+        });
+        if (new Set(suggestedRemovals.map((suggestion) => suggestion.path)).size !== suggestedRemovals.length) {
+            throw new Error("Suggested removal paths must be unique");
+        }
+        const genericProject = await this.db.upsertProject(GENERIC_PROJECT_NAME);
+        const targetPath = memoryRelativePath(GENERIC_PROJECT_NAME, kind, input.name);
+        let existing = await this.db.getMemoryByPath(targetPath);
+        let liveTarget;
+        try {
+            liveTarget = await readMemory(this.config.memoryRoot, targetPath);
+        }
+        catch (error) {
+            if (typeof error !== "object" ||
+                error === null ||
+                !("code" in error) ||
+                error.code !== "ENOENT") {
+                throw error;
+            }
+        }
+        const hasExpectedContent = input.expected_content_hash !== undefined;
+        const hasExpectedFrontmatter = input.expected_frontmatter_hash !== undefined;
+        if (liveTarget) {
+            if (!hasExpectedContent || !hasExpectedFrontmatter) {
+                throw new Error(`Generic memory ${targetPath} already exists; expected_content_hash and expected_frontmatter_hash are required for compare-and-swap update`);
+            }
+            if (liveTarget.contentHash !== input.expected_content_hash ||
+                liveTarget.frontmatterHash !== input.expected_frontmatter_hash) {
+                throw new Error(`Generic memory ${targetPath} changed since it was read; expected hashes are stale`);
+            }
+            // The filesystem is canonical. If a matching live file has not reached
+            // the watcher/index yet, bring its metadata into the DB before upsertCore
+            // preserves tags, links, timestamps, and identity from the existing row.
+            if (!existing ||
+                existing.content_hash !== liveTarget.contentHash ||
+                existing.frontmatter_hash !== liveTarget.frontmatterHash) {
+                existing = await this.db.upsertMemory(liveTarget);
+            }
+        }
+        else if (existing) {
+            throw new Error(`Generic memory ${targetPath} changed since it was read; the live target file is missing`);
+        }
+        else if (hasExpectedContent || hasExpectedFrontmatter) {
+            throw new Error(`Generic memory ${targetPath} does not exist; expected hashes are only valid for updates`);
+        }
+        const upserted = await this.upsertCore({
+            project_id: genericProject.id,
+            ...(existing ? { memory_id: existing.id } : {}),
+            kind,
+            name: input.name,
+            content: input.content,
+            tags: input.tags,
+            derived_from: sourcePaths,
+            skip_similarity_fold: true,
+        });
+        if (upserted.memory.relative_path !== targetPath) {
+            throw new Error(`Decoction write diverted from ${targetPath} to ${upserted.memory.relative_path}`);
+        }
+        const warnings = [
+            ...credentialWarnings(input.content, "generic draft"),
+            ...sources.flatMap((source) => credentialWarnings(source.body, `evidence ${source.relative_path}`)),
+        ];
+        return {
+            action: "write",
+            memory: upserted.memory,
+            upsert_action: upserted.action,
+            suggested_removals: suggestedRemovals,
+            warnings,
+            text: renderDecoctionWriteText(upserted.memory, suggestedRemovals, warnings),
+        };
+    }
+    async decoctionCleanup(input) {
+        await this.init();
+        return this.serializeMutation(async () => {
+            try {
+                return await this.decoctionCleanupCore(input);
+            }
+            finally {
+                this.invalidateCorpusSnapshot();
+            }
+        });
+    }
+    async decoctionCleanupCore(input) {
+        await this.init();
+        const genericPath = normalizeRelativePath(input.generic_path);
+        const generic = await this.db.getMemoryByPath(genericPath);
+        if (!generic) {
+            throw new Error(`Generic memory not found in corpus: ${input.generic_path}`);
+        }
+        if (!isGenericProjectName(generic.project_name) || !generic.relative_path.startsWith(`${GENERIC_PROJECT_NAME}/`)) {
+            throw new Error(`Decoction cleanup target must be a generic memory: ${input.generic_path}`);
+        }
+        if (!Array.isArray(input.source_paths) || input.source_paths.length === 0) {
+            throw new Error("Decoction cleanup requires at least one source path");
+        }
+        const sourcePaths = input.source_paths.map((sourcePath) => normalizeRelativePath(sourcePath));
+        if (new Set(sourcePaths).size !== sourcePaths.length) {
+            throw new Error("Decoction cleanup source paths must be unique");
+        }
+        const sources = [];
+        for (const sourcePath of sourcePaths) {
+            const source = await this.db.getMemoryByPath(sourcePath);
+            if (!source) {
+                throw new Error(`Unknown memory path: ${sourcePath}`);
+            }
+            if (isGenericProjectName(source.project_name) || source.relative_path.startsWith(`${GENERIC_PROJECT_NAME}/`)) {
+                throw new Error(`A generic memory cannot be a decoction cleanup source: ${sourcePath}`);
+            }
+            sources.push(source);
+        }
+        const results = [];
+        for (const source of sources) {
+            let retargetedLinks = 0;
+            try {
+                const inboundLinks = (await this.db.listLinks(source.id)).filter((link) => link.to_memory_id === source.id && link.from_memory_id !== generic.id);
+                for (const inbound of inboundLinks) {
+                    await this.linkCore(inbound.from_memory_id, generic.id, inbound.type);
+                    retargetedLinks += 1;
+                }
+                await this.deleteMemoryCore(source.id);
+                results.push({
+                    source_path: source.relative_path,
+                    status: "deleted",
+                    retargeted_links: retargetedLinks,
+                });
+            }
+            catch (error) {
+                results.push({
+                    source_path: source.relative_path,
+                    status: "failed",
+                    retargeted_links: retargetedLinks,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        const deleted = results.filter((result) => result.status === "deleted").length;
+        const failed = results.length - deleted;
+        return {
+            generic_path: generic.relative_path,
+            results,
+            text: [
+                `decoction cleanup for ${generic.relative_path}: ${deleted} deleted, ${failed} failed`,
+                ...results.map((result) => `- ${result.source_path}: status=${result.status}; retargeted_links=${result.retargeted_links}` +
+                    (result.error ? `; error=${result.error}` : "")),
+            ].join("\n"),
         };
     }
     /**
      * READ-ONLY sleep preview: which settled WORK memories WOULD consolidate.
-     * Performs zero writes — the actual write-back (`sleep_apply`) is deferred
-     * behind the Phase-2 go/no-go and does not exist.
+     * Performs zero writes; an agent must draft a proposal and receive explicit
+     * user approval before `sleep_apply` changes the corpus.
      */
     async sleepCandidates(input = {}, now = Date.now()) {
         await this.init();
@@ -513,6 +816,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 +831,371 @@ 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) {
+        await this.init();
+        return this.serializeMutation(async () => {
+            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 inside this compound mutation's critical
+        // section. 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.upsertCore({
+            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();
+        return this.serializeMutation(async () => {
+            const existing = await readProposal(this.config.stateDir, "sleep", filename);
+            if (existing.frontmatter.status !== "proposed") {
+                throw new Error(`Sleep proposal ${filename} is already ${existing.frontmatter.status}, not proposed`);
+            }
+            const proposal = await setProposalStatus(this.config.stateDir, "sleep", filename, "rejected");
+            return { proposal, text: renderProposalsText([proposal], "sleep") };
+        });
+    }
+    /**
+     * Draft one speculative memory or link outside the corpus. The daemon never
+     * synthesizes a dream: an agent supplies the complete candidate and this
+     * method only validates its live references and writes a review artifact.
+     */
+    async dreamPropose(input) {
+        await this.init();
+        const rawInput = input;
+        const hasLinkForm = rawInput.link !== undefined;
+        const hasMemoryForm = ["kind", "name", "content", "derived_from"].some((key) => rawInput[key] !== undefined);
+        if (hasLinkForm && hasMemoryForm) {
+            throw new Error("A dream proposal requires exactly one form: dream-memory or dream-link");
+        }
+        if (hasLinkForm) {
+            if (!rawInput.link || typeof rawInput.link !== "object") {
+                throw new Error("A dream-link proposal requires link endpoints");
+            }
+            const inputLink = rawInput.link;
+            const link = {
+                from: String(inputLink.from ?? ""),
+                to: String(inputLink.to ?? ""),
+                type: normalizeLinkType(String(inputLink.type ?? "")),
+            };
+            await this.validateDreamLink(input.project_name, link);
+            const proposal = await writeProposal(this.config.stateDir, {
+                type: "dream-link",
+                project: input.project_name,
+                derived_from: [],
+                link,
+                ...(input.rationale !== undefined ? { rationale: input.rationale } : {}),
+            }, "");
+            return { proposal, text: renderDreamProposalsText([proposal]) };
+        }
+        const memoryInput = input;
+        if (typeof memoryInput.name !== "string" || !memoryInput.name.trim()) {
+            throw new Error("A dream-memory proposal requires a target name");
+        }
+        if (typeof memoryInput.content !== "string") {
+            throw new Error("A dream-memory proposal requires content");
+        }
+        if (!Array.isArray(memoryInput.derived_from)) {
+            throw new Error("A dream-memory proposal requires derived_from inspiration paths");
+        }
+        if (typeof memoryInput.kind !== "string") {
+            throw new Error("A dream-memory proposal requires a target kind");
+        }
+        const kind = normalizeKind(memoryInput.kind);
+        await this.validateDreamMemory(memoryInput.project_name, kind, memoryInput.name, memoryInput.derived_from);
+        const proposal = await writeProposal(this.config.stateDir, {
+            type: "dream-memory",
+            project: memoryInput.project_name,
+            kind,
+            name: memoryInput.name,
+            derived_from: memoryInput.derived_from,
+            ...(memoryInput.rationale !== undefined ? { rationale: memoryInput.rationale } : {}),
+        }, memoryInput.content);
+        return { proposal, text: renderDreamProposalsText([proposal]) };
+    }
+    /** List the whole dreams/ proposal family, including both dream-memory and
+     * dream-link records. `dream-memory` is intentionally only the directory
+     * selector used by the shared proposal store. */
+    async dreamProposals(status) {
+        await this.init();
+        const proposals = await listProposals(this.config.stateDir, "dream-memory", status);
+        return { proposals, text: renderDreamProposalsText(proposals) };
+    }
+    /** Apply the explicitly approved proposal after re-reading and re-validating
+     * it against the live corpus. The HTTP route owns the single git commit. */
+    async dreamApply(input) {
+        await this.init();
+        return this.serializeMutation(async () => {
+            try {
+                return await this.dreamApplyCore(input);
+            }
+            finally {
+                this.invalidateCorpusSnapshot();
+            }
+        });
+    }
+    async dreamApplyCore(input) {
+        await this.init();
+        const proposal = await readProposal(this.config.stateDir, "dream-memory", input.filename);
+        const fm = proposal.frontmatter;
+        if (fm.status !== "proposed") {
+            throw new Error(`Dream proposal ${input.filename} is already ${fm.status}, not proposed`);
+        }
+        if (fm.type === "dream-memory") {
+            if (!fm.kind) {
+                throw new Error(`Dream proposal ${input.filename} is missing a target kind`);
+            }
+            if (!fm.name) {
+                throw new Error(`Dream proposal ${input.filename} is missing a target name`);
+            }
+            const kind = normalizeKind(fm.kind);
+            await this.validateDreamMemory(fm.project, kind, fm.name, fm.derived_from);
+            const project = await this.db.getProjectByName(fm.project);
+            if (!project) {
+                throw new Error(`Dream proposal project not found in corpus: ${fm.project}`);
+            }
+            const upserted = await this.upsertCore({
+                project_id: project.id,
+                kind,
+                name: fm.name,
+                content: proposal.body,
+                tags: ["dream"],
+                derived_from: fm.derived_from,
+                skip_similarity_fold: true,
+            });
+            const expectedTargetPath = memoryRelativePath(fm.project, kind, fm.name);
+            if (upserted.memory.relative_path !== expectedTargetPath) {
+                throw new Error(`Dream apply diverted from the approved target ${expectedTargetPath} to ${upserted.memory.relative_path}`);
+            }
+            const appliedProposal = await setProposalStatus(this.config.stateDir, "dream-memory", input.filename, "applied");
+            return {
+                type: "dream-memory",
+                proposal: appliedProposal,
+                memory: upserted.memory,
+                text: `applied dream memory ${kind}/${fm.name} (${fm.project})`,
+            };
+        }
+        if (fm.type === "dream-link") {
+            if (!fm.link) {
+                throw new Error(`Dream proposal ${input.filename} is missing link endpoints`);
+            }
+            const validated = await this.validateDreamLink(fm.project, fm.link);
+            const linked = await this.linkCore(validated.from.relative_path, validated.to.relative_path, validated.type);
+            const appliedProposal = await setProposalStatus(this.config.stateDir, "dream-memory", input.filename, "applied");
+            return {
+                type: "dream-link",
+                proposal: appliedProposal,
+                link: linked.link,
+                text: `applied dream link ${validated.from.relative_path} -> ${validated.to.relative_path} (${validated.type})`,
+            };
+        }
+        throw new Error(`Unsupported dream proposal type in ${input.filename}: ${String(fm.type)}`);
+    }
+    async dreamReject(filename) {
+        await this.init();
+        return this.serializeMutation(async () => {
+            const existing = await readProposal(this.config.stateDir, "dream-memory", filename);
+            if (existing.frontmatter.status !== "proposed") {
+                throw new Error(`Dream proposal ${filename} is already ${existing.frontmatter.status}, not proposed`);
+            }
+            const proposal = await setProposalStatus(this.config.stateDir, "dream-memory", filename, "rejected");
+            return { proposal, text: renderDreamProposalsText([proposal]) };
+        });
+    }
+    async validateDreamMemory(projectName, kind, name, derivedFrom) {
+        if (!projectName) {
+            throw new Error("A dream-memory proposal requires project_name");
+        }
+        if (isGenericProjectName(projectName)) {
+            throw new Error("The generic pseudo-project cannot be a dream active project");
+        }
+        if (derivedFrom.length < 1) {
+            throw new Error("A dream-memory proposal needs at least 1 inspiration source");
+        }
+        if (!(await this.db.getProjectByName(projectName))) {
+            throw new Error(`Dream proposal project not found in corpus: ${projectName}`);
+        }
+        for (const sourcePath of derivedFrom) {
+            const source = await this.db.getMemoryByPath(normalizeRelativePath(sourcePath));
+            if (!source) {
+                throw new Error(`Dream source not found in corpus: ${sourcePath}`);
+            }
+            // There is deliberately no project check here. Normal global search may
+            // inspire dreams from the current, generic, or any foreign project.
+        }
+        const targetPath = memoryRelativePath(projectName, kind, name);
+        if ((await this.db.getMemoryByPath(targetPath)) || (await this.memoryFileExists(targetPath))) {
+            throw new Error(`Dream target already exists in corpus: ${targetPath}`);
+        }
+    }
+    async validateDreamLink(projectName, link) {
+        if (!projectName) {
+            throw new Error("A dream-link proposal requires project_name");
+        }
+        if (isGenericProjectName(projectName)) {
+            throw new Error("The generic pseudo-project cannot be a dream active project");
+        }
+        const from = await this.db.getMemoryByPath(normalizeRelativePath(link.from));
+        if (!from) {
+            throw new Error(`Dream link source not found in corpus: ${link.from}`);
+        }
+        if (from.project_name !== projectName) {
+            throw new Error(`Dream link source ${link.from} belongs to ${from.project_name}, not ${projectName}`);
+        }
+        const to = await this.db.getMemoryByPath(normalizeRelativePath(link.to));
+        if (!to) {
+            throw new Error(`Dream link target not found in corpus: ${link.to}`);
+        }
+        return { from, to, type: normalizeLinkType(link.type) };
+    }
+    /**
+     * 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)) || (await this.memoryFileExists(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 +1226,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) {
@@ -565,6 +1247,52 @@ function mergeFrontmatterLink(links, link) {
     }
     return [...links, link];
 }
+function renderDecoctionDiscoveryText(clusters, eligible, minCosine) {
+    if (clusters.length === 0) {
+        return `No decoction candidates found among ${eligible} eligible memories at complete-link cosine ${minCosine.toFixed(2)}. Discovery is READ-ONLY.`;
+    }
+    const lines = [
+        `Decoction discovery is READ-ONLY: ${clusters.length} candidate cluster(s) among ${eligible} eligible memories.`,
+    ];
+    clusters.forEach((cluster, index) => {
+        lines.push(`\n${index + 1}. ${cluster.distinct_projects} projects, ${cluster.sources.length} sources, minimum pairwise cosine ${cluster.min_pairwise_cosine.toFixed(3)}`);
+        for (const source of cluster.sources) {
+            lines.push(`   - ${source.relative_path} [${source.kind}; project ${source.project_name}; id ${source.id}]`);
+        }
+    });
+    return lines.join("\n");
+}
+function renderDecoctionWriteText(memory, suggestions, warnings) {
+    const lines = [`wrote generic memory ${memory.id} at ${memory.relative_path}`];
+    if (suggestions.length > 0) {
+        lines.push("Suggested removals (not yet deleted):");
+        for (const suggestion of suggestions) {
+            lines.push(`- ${suggestion.path}: ${suggestion.reason}`);
+        }
+    }
+    else {
+        lines.push("No source removals suggested.");
+    }
+    if (warnings.length > 0) {
+        lines.push("Warnings (write allowed):", ...warnings.map((warning) => `- ${warning}`));
+    }
+    return lines.join("\n");
+}
+function credentialWarnings(content, location) {
+    const patterns = [
+        { name: "AWS access-key-shaped credential", pattern: /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/ },
+        { name: "GitHub-token-shaped credential", pattern: /\bgh[pousr]_[A-Za-z0-9]{20,}\b/ },
+        { name: "API-key-shaped credential", pattern: /\bsk-[A-Za-z0-9]{20,}\b/ },
+        { name: "private-key material", pattern: /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/ },
+    ];
+    return patterns
+        .filter(({ pattern }) => pattern.test(content))
+        .map(({ name }) => `Potential ${name} in ${location}; review before cleanup.`);
+}
+function renderDreamProposalsText(proposals) {
+    const rendered = renderProposalsText(proposals, "dream-memory");
+    return rendered.replace(/^No dream-memory proposals\./, "No dream proposals.").replace(/^dream-memory proposals/, "dream proposals");
+}
 function searchDocument(memory) {
     return [
         memory.project_name,