@fingerskier/augment 0.4.0 → 0.5.0

package/dist/service.js

@@ -3,9 +3,10 @@ import path from "node:path";
 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";
@@ -33,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;
@@ -71,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);
@@ -114,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();
@@ -154,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) {
@@ -276,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();
@@ -343,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();
@@ -387,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();
@@ -423,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 () => ({
@@ -463,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);
@@ -477,7 +526,7 @@ 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 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
@@ -521,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();
@@ -588,12 +867,15 @@ export class AugmentService {
      * git: the route commits the whole pass as one revertible commit.
      */
     async sleepApply(input) {
-        try {
-            return await this.sleepApplyCore(input);
-        }
-        finally {
-            this.invalidateCorpusSnapshot();
-        }
+        await this.init();
+        return this.serializeMutation(async () => {
+            try {
+                return await this.sleepApplyCore(input);
+            }
+            finally {
+                this.invalidateCorpusSnapshot();
+            }
+        });
     }
     async sleepApplyCore(input) {
         await this.init();
@@ -620,13 +902,13 @@ export class AugmentService {
         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
+        // 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.upsert({
+        const upserted = await this.upsertCore({
             project_id: project.id,
             kind,
             name,
@@ -655,8 +937,207 @@ export class AugmentService {
     }
     async sleepReject(filename) {
         await this.init();
-        const proposal = await setProposalStatus(this.config.stateDir, "sleep", filename, "rejected");
-        return { proposal, text: renderProposalsText([proposal], "sleep") };
+        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
@@ -685,7 +1166,7 @@ export class AugmentService {
             }
         }
         const targetPath = memoryRelativePath(projectName, kind, name);
-        if (await this.db.getMemoryByPath(targetPath)) {
+        if ((await this.db.getMemoryByPath(targetPath)) || (await this.memoryFileExists(targetPath))) {
             throw new Error(`Sleep target already exists in corpus: ${targetPath}`);
         }
     }
@@ -766,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,