@amoree-code/ocean 0.0.0-stage → 1.1.0

package/node_modules/@ocean/brain/dist/memory/memory-review.js

@@ -0,0 +1,278 @@
+import { mkdir, readdir, readFile, rename } from "node:fs/promises";
+import path from "node:path";
+import { MemoryContractError } from "@ocean/core/domain/mcp/memory-contract.js";
+import { atomicWrite, withFileLock } from "@ocean/core/shared/fs-utils.js";
+import { localDate } from "@ocean/core/shared/local-date.js";
+import { oceanPath, PROJECTS_DIR, projectDir, } from "@ocean/core/shared/paths.js";
+import { findProject, readClaudeProjects, registerNamedProject, } from "@ocean/core/shared/project-resolution.js";
+import { appendAudit, memorySettings, newId, sha256, writeDurable, } from "./memory-audit.js";
+import { assertNoLinks, candidatesRoot, storedCopy } from "./memory-paths.js";
+import { checkContent, proposeMemory, readMemoryRecord, writeMemoryRecord, } from "./memory-write.js";
+function parse(text) {
+    const match = /^---\n([\s\S]*?)\n---\n\n?/.exec(text);
+    if (!match)
+        return null;
+    const fields = {};
+    for (const line of match[1].split("\n")) {
+        const index = line.indexOf(":");
+        if (index < 0)
+            continue;
+        const raw = line.slice(index + 1).trim();
+        let value = raw;
+        try {
+            value =
+                /^["[]/.test(raw) || raw === "true" || raw === "false"
+                    ? JSON.parse(raw)
+                    : raw;
+        }
+        catch {
+            // a hand-edited value stays as written
+        }
+        fields[line.slice(0, index).trim()] = value;
+    }
+    const known = [
+        "candidate",
+        "origin",
+        "source",
+        "target",
+        "reason",
+        "created",
+    ];
+    const field = (key) => typeof fields[key] === "string" ? fields[key] : "";
+    return {
+        origin: field("origin"),
+        source: field("source"),
+        target: field("target"),
+        reason: field("reason"),
+        created: field("created"),
+        meta: Object.fromEntries(Object.entries(fields).filter(([key]) => !known.includes(key))),
+        content: text.slice(match[0].length),
+    };
+}
+export async function listCandidates() {
+    const root = candidatesRoot();
+    const found = [];
+    const days = await readdir(root, { withFileTypes: true }).catch(() => []);
+    for (const day of days.filter((entry) => entry.isDirectory()).sort()) {
+        for (const name of (await readdir(path.join(root, day.name))).sort()) {
+            if (!name.endsWith(".md"))
+                continue;
+            const file = path.join(root, day.name, name);
+            const parsed = parse(await readFile(file, "utf8"));
+            if (!parsed)
+                continue;
+            found.push({
+                id: name.slice(0, -3),
+                file: path.relative(oceanPath(), file).split(path.sep).join("/"),
+                day: day.name,
+                ...parsed,
+            });
+        }
+    }
+    return found;
+}
+async function candidate(id) {
+    const found = (await listCandidates()).find((item) => item.id === id);
+    if (!found)
+        throw new MemoryContractError("MISSING", `no candidate '${id}' to review`);
+    return found;
+}
+async function retire(item, action, source = "owner-review") {
+    const id = newId();
+    const copy = storedCopy("trash", id, item.file);
+    await mkdir(path.dirname(copy), { recursive: true, mode: 0o700 });
+    const text = await readFile(oceanPath(item.file), "utf8");
+    await rename(oceanPath(item.file), copy);
+    await appendAudit({
+        id,
+        action,
+        path: item.file,
+        source,
+        origin: item.origin === "imported" ? "imported" : "inferred",
+        beforeSha: sha256(text),
+        afterSha: null,
+        copy: path.relative(oceanPath(), copy).split(path.sep).join("/"),
+    });
+    return id;
+}
+// Writes the candidate's content to `to` (default: its proposed target). A new record is
+// created; an existing one gets the content appended, guarded by its current hash — unless
+// `createOnly` (an approval nobody looked at), which leaves that one to the owner's review.
+export async function approveCandidate(options) {
+    const source = options.source ?? "owner-review";
+    const item = await candidate(options.id);
+    const provenance = {
+        origin: item.origin === "imported" ? "imported" : "inferred",
+        candidate: options.id,
+    };
+    if (item.meta.kind === "todo" && !options.to)
+        return approveTodo(item, source);
+    const target = options.to ?? item.target;
+    if (!target)
+        throw new MemoryContractError("INVALID", "the candidate names no target; pass --to <record path>");
+    // A project doc is only ever created: an existing one stays the owner's (T-307).
+    if (/^04-projects\/[^/]+\/docs\//.test(target)) {
+        const written = await writeMemoryRecord({
+            path: target,
+            content: item.content,
+            mode: "create",
+            source,
+            provenance,
+            document: true,
+        });
+        await retire(item, "approve", source);
+        return { path: written.path, mode: "create", auditId: written.auditId };
+    }
+    const existing = await readMemoryRecord(target).catch((error) => {
+        if (error instanceof MemoryContractError && error.code === "MISSING")
+            return null;
+        throw error;
+    });
+    if (existing && options.createOnly)
+        throw new MemoryContractError("CONFLICT", `${target} exists; adding to it needs review`);
+    const written = existing
+        ? await writeMemoryRecord({
+            path: target,
+            content: `${existing.content.replace(/\n*$/, "\n\n")}${item.content}`,
+            mode: "update",
+            expectedHash: existing.sha256,
+            source,
+            provenance,
+        })
+        : await writeMemoryRecord({
+            path: target,
+            content: item.content,
+            mode: "create",
+            source,
+            provenance,
+        });
+    await retire(item, "approve", source);
+    return {
+        path: written.path,
+        mode: written.mode,
+        auditId: written.auditId,
+    };
+}
+const BACKLOG = `${PROJECTS_DIR}/backlog.md`;
+// An approved todo is one line under the backlog's "## Open" heading, never a task folder:
+// a task is opened only at the owner's request. The backlog before the change is kept in
+// versions/ and the audit names the candidate it came from.
+async function approveTodo(item, source) {
+    checkContent(item.content);
+    const project = typeof item.meta.project === "string" ? item.meta.project : "workspace";
+    const text = item.content.replace(/\s+/g, " ").trim().slice(0, 300);
+    const line = `- [TODO] (P2) ${project} — ${text} {${localDate()}}`;
+    const file = oceanPath(BACKLOG);
+    assertNoLinks(oceanPath(), file);
+    const id = newId();
+    const { before, after, copy } = await withFileLock(file, async () => {
+        const current = await readFile(file, "utf8").catch((error) => {
+            if (error.code === "ENOENT")
+                return null;
+            throw error;
+        });
+        const base = current ?? "# Backlog\n\n## Open\n\n";
+        const open = "## Open\n\n";
+        const at = base.indexOf(open);
+        const next = at < 0
+            ? `${base.replace(/\n*$/, "\n\n")}${line}\n`
+            : `${base.slice(0, at + open.length)}${line}\n${base.slice(at + open.length)}`;
+        let copy;
+        if (current !== null) {
+            const stored = storedCopy("versions", id, BACKLOG);
+            await writeDurable(stored, current);
+            copy = path.relative(oceanPath(), stored).split(path.sep).join("/");
+        }
+        await atomicWrite(file, next);
+        return { before: current, after: next, copy };
+    });
+    await appendAudit({
+        id,
+        action: before === null ? "create" : "update",
+        path: BACKLOG,
+        source,
+        origin: item.origin === "imported" ? "imported" : "inferred",
+        candidate: item.id,
+        beforeSha: before === null ? null : sha256(before),
+        afterSha: sha256(after),
+        copy,
+    });
+    await retire(item, "approve", source);
+    return { path: BACKLOG, mode: "update", auditId: id };
+}
+const KINDS = ["fact", "doc", "todo"];
+const NAME = /^[a-z0-9][a-z0-9-]{0,59}$/;
+// A client's proposal made inside a project (T-307). The project is named by its Ocean id or its
+// name (`LetSpeak` finds `letspeak`). Ocean, not the client, picks the place from the kind: a
+// fact goes to the project's memory/ and a doc to its docs/, each as the new file `<name>.md`; a
+// todo waits for review and becomes one backlog line. With proposeAutoApprove on, a fact or doc
+// for an existing project is written at once — never over or into an existing file — and keeps
+// its origin and candidate in the audit; a name Ocean does not know is registered as a project
+// only when it is one of the owner's Claude projects this machine has seen, never for a topic a
+// client calls a project. Everything else stays a candidate.
+export async function fileProposal(options) {
+    if (!KINDS.includes(options.kind))
+        throw new MemoryContractError("INVALID", "kind must be fact, doc or todo");
+    const ref = typeof options.project === "string" ? options.project.trim() : "";
+    if (!ref || ref.length > 64 || /[\r\n/\\]/.test(ref))
+        throw new MemoryContractError("INVALID", "project must be a project id or name of at most 64 characters");
+    if (options.kind !== "todo" &&
+        (typeof options.name !== "string" || !NAME.test(options.name)))
+        throw new MemoryContractError("INVALID", "name must be lowercase kebab-case, at most 60 characters");
+    const auto = (await memorySettings()).proposeAutoApprove;
+    let project = await findProject(ref);
+    let registered;
+    if (!project &&
+        auto &&
+        (await readClaudeProjects()).some((name) => name.trim().toLowerCase() === ref.toLowerCase())) {
+        try {
+            project = (await registerNamedProject(ref, ["claude.ai"])).id;
+            registered = project;
+        }
+        catch {
+            // an id that cannot be made, or a folder without a manifest: the owner decides
+        }
+    }
+    const folder = options.kind === "fact" ? "memory" : "docs";
+    const target = project && options.kind !== "todo"
+        ? `${projectDir(project)}/${folder}/${options.name}.md`
+        : undefined;
+    const proposed = await proposeMemory({
+        content: options.content,
+        origin: options.origin,
+        target,
+        reason: options.reason,
+        source: options.source,
+        meta: { kind: options.kind, project: project ?? ref },
+    });
+    const result = { ...proposed, ...(registered ? { registered } : {}) };
+    if (!project)
+        return {
+            ...result,
+            review: `'${ref}' is neither an Ocean project nor a Claude project this machine has seen; waits for review`,
+        };
+    if (!target)
+        return { ...result, review: "a todo waits for review" };
+    if (!auto)
+        return {
+            ...result,
+            review: "proposeAutoApprove is off; waits for review",
+        };
+    try {
+        const written = await approveCandidate({
+            id: path.basename(proposed.candidate, ".md"),
+            createOnly: true,
+            source: "propose-auto-approve",
+        });
+        return { ...result, filed: written.path };
+    }
+    catch (error) {
+        if (!(error instanceof MemoryContractError))
+            throw error;
+        return { ...result, review: `${error.message}; waits for review` };
+    }
+}
+export async function rejectCandidate(id) {
+    return { id, auditId: await retire(await candidate(id), "reject") };
+}
+//# sourceMappingURL=memory-review.js.map

package/node_modules/@ocean/brain/dist/memory/memory-trash.js

@@ -0,0 +1,152 @@
+import { readdir, readFile, rm } from "node:fs/promises";
+import path from "node:path";
+import { MemoryContractError } from "@ocean/core/domain/mcp/memory-contract.js";
+import { atomicWrite, withFileLock } from "@ocean/core/shared/fs-utils.js";
+import { oceanPath, resolveWithin, withoutProjectCategory, } from "@ocean/core/shared/paths.js";
+import { syncMemoryIndexes } from "./index-sync.js";
+import { appendAudit, idTime, memorySettings, newId, readAudit, sha256, writeDurable, } from "./memory-audit.js";
+import { permanentRecord, storedCopy, trashRoot, versionsRoot, } from "./memory-paths.js";
+import { checkContent } from "./memory-write.js";
+// Soft delete, history, restore and purge (T-296). Nothing over MCP removes content for good:
+// a delete moves the record to trash/, an update keeps the old content in versions/, and only
+// `ocean memory purge --yes` (CLI) drops copies older than the retention period.
+const relativeToWorkspace = (file) => path.relative(oceanPath(), file).split(path.sep).join("/");
+export async function deleteMemoryRecord(options) {
+    const record = permanentRecord(options.path);
+    const id = newId();
+    const { before, trash } = await withFileLock(record.file, async () => {
+        let current;
+        try {
+            current = await readFile(record.file, "utf8");
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                throw new MemoryContractError("MISSING", `${record.relative} not found`);
+            throw error;
+        }
+        if (options.expectedHash !== sha256(current))
+            throw new MemoryContractError("CONFLICT", "expectedHash does not match the record; read it again before deleting", { sha256: sha256(current) });
+        const stored = storedCopy("trash", id, record.relative);
+        await writeDurable(stored, current);
+        await rm(record.file);
+        return { before: current, trash: relativeToWorkspace(stored) };
+    });
+    await appendAudit({
+        id,
+        action: "delete",
+        path: record.relative,
+        source: options.source ?? "unknown",
+        beforeSha: sha256(before),
+        afterSha: null,
+        copy: trash,
+    });
+    if (record.personal)
+        await syncMemoryIndexes(true);
+    return { path: record.relative, auditId: id, trash };
+}
+export async function memoryHistory(options = {}) {
+    // Either layout names the same record: an entry written before its project moved into a
+    // category folder still answers to the new path, and the reverse (T-311).
+    const wanted = options.path
+        ? withoutProjectCategory(options.path.split("\\").join("/"))
+        : undefined;
+    const entries = (await readAudit()).filter((entry) => !wanted || withoutProjectCategory(entry.path) === wanted);
+    const limit = Math.min(100, Math.max(1, options.limit ?? 20));
+    return { entries: entries.slice(-limit).reverse() };
+}
+// Puts back the content an audit entry preserved: a deleted record (only while its path is
+// free) or an earlier version (the current content is versioned first, and the caller must
+// name it by hash, as for an update).
+export async function restoreMemory(options) {
+    const entry = (await readAudit()).find((item) => item.id === options.id && item.copy);
+    if (!entry?.copy)
+        throw new MemoryContractError("MISSING", `no stored copy for audit entry ${options.id}`);
+    const copyFile = resolveCopy(entry.copy);
+    let content;
+    try {
+        content = await readFile(copyFile, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            throw new MemoryContractError("MISSING", `stored copy ${entry.copy} was purged`);
+        throw error;
+    }
+    checkContent(content);
+    const record = permanentRecord(entry.path);
+    const id = newId();
+    const replaced = await withFileLock(record.file, async () => {
+        let current = null;
+        try {
+            current = await readFile(record.file, "utf8");
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        let copy;
+        if (current !== null) {
+            if (entry.action === "delete")
+                throw new MemoryContractError("EXISTS", `${record.relative} was recreated after the delete; restore an earlier version instead`);
+            if (options.expectedHash !== sha256(current))
+                throw new MemoryContractError("CONFLICT", "expectedHash does not match the record; read it again before restoring", { sha256: sha256(current) });
+            const stored = storedCopy("versions", id, record.relative);
+            await writeDurable(stored, current);
+            copy = relativeToWorkspace(stored);
+        }
+        await atomicWrite(record.file, content);
+        return { before: current, copy };
+    });
+    await appendAudit({
+        id,
+        action: "restore",
+        path: record.relative,
+        source: options.source ?? "unknown",
+        beforeSha: replaced.before === null ? null : sha256(replaced.before),
+        afterSha: sha256(content),
+        copy: replaced.copy,
+        restoredFrom: entry.id,
+    });
+    if (record.personal)
+        await syncMemoryIndexes(true);
+    return { path: record.relative, auditId: id, sha256: sha256(content) };
+}
+// An audit entry's copy must still name a file under versions/ or trash/.
+function resolveCopy(copy) {
+    const file = oceanPath(...copy.split("/"));
+    for (const root of [versionsRoot(), trashRoot()]) {
+        try {
+            return resolveWithin(root, path.relative(root, file));
+        }
+        catch { }
+    }
+    throw new MemoryContractError("OUT_OF_ROOT", `stored copy ${copy} is outside versions/ and trash/`);
+}
+// CLI only. Lists stored copies older than the retention period; removes them only with apply.
+export async function purgeMemoryCopies(options) {
+    const days = options.days ?? (await memorySettings()).retentionDays;
+    if (!Number.isInteger(days) || days < 1)
+        throw new MemoryContractError("INVALID", "days must be a whole number ≥ 1");
+    const cutoff = new Date((options.now ?? new Date()).getTime() - days * 86_400_000);
+    const copies = [];
+    for (const root of [versionsRoot(), trashRoot()]) {
+        const ids = await readdir(root).catch(() => []);
+        for (const id of ids.sort()) {
+            const time = idTime(id);
+            if (time && time < cutoff)
+                copies.push(relativeToWorkspace(path.join(root, id)));
+        }
+    }
+    if (options.apply)
+        for (const copy of copies) {
+            await rm(oceanPath(...copy.split("/")), { recursive: true, force: true });
+            await appendAudit({
+                action: "purge",
+                path: copy,
+                source: "cli",
+                beforeSha: null,
+                afterSha: null,
+            });
+        }
+    return { cutoff: cutoff.toISOString(), copies, applied: options.apply };
+}
+//# sourceMappingURL=memory-trash.js.map

package/node_modules/@ocean/brain/dist/memory/memory-write.js

@@ -0,0 +1,216 @@
+import { mkdir, readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { MemoryContractError } from "@ocean/core/domain/mcp/memory-contract.js";
+import { containsKnownSecret } from "@ocean/core/domain/redaction/redaction.js";
+import { atomicWrite, withFileLock } from "@ocean/core/shared/fs-utils.js";
+import { localDate } from "@ocean/core/shared/local-date.js";
+import { listProjectDirs, oceanPath, PERSONAL_DIR, } from "@ocean/core/shared/paths.js";
+import { syncMemoryIndexes } from "./index-sync.js";
+import { appendAudit, newId, sha256, writeDurable } from "./memory-audit.js";
+import { assertNoLinks, candidateFile, candidatesRoot, permanentRecord, projectDocument, storedCopy, } from "./memory-paths.js";
+const maxRecordBytes = 32_000;
+export function checkContent(content) {
+    if (typeof content !== "string" || !content.trim())
+        throw new MemoryContractError("INVALID", "content is empty");
+    if (Buffer.byteLength(content) > maxRecordBytes)
+        throw new MemoryContractError("TOO_LARGE", `content exceeds ${maxRecordBytes} bytes`);
+    if (containsKnownSecret(content))
+        throw new MemoryContractError("SECRET", "content holds a secret; memory never stores one");
+}
+async function readIfPresent(file) {
+    try {
+        return await readFile(file, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+function withNewline(content) {
+    return content.endsWith("\n") ? content : `${content}\n`;
+}
+export async function readMemoryRecord(relative) {
+    const record = permanentRecord(relative);
+    const content = await readIfPresent(record.file);
+    if (content === null)
+        throw new MemoryContractError("MISSING", `${record.relative} not found`);
+    return { path: record.relative, content, sha256: sha256(content) };
+}
+async function markdownFiles(directory) {
+    let entries;
+    try {
+        entries = await readdir(directory, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    const files = [];
+    for (const entry of entries) {
+        if (entry.name.startsWith("."))
+            continue;
+        const full = path.join(directory, entry.name);
+        if (entry.isDirectory())
+            files.push(...(await markdownFiles(full)));
+        else if (entry.isFile() && entry.name.endsWith(".md"))
+            files.push(full);
+    }
+    return files;
+}
+const normalize = (value) => value
+    .toLowerCase()
+    .replace(/\.md$/, "")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-|-$/g, "");
+function title(content) {
+    const frontmatter = /^---\n([\s\S]*?)\n---/.exec(content)?.[1] ?? "";
+    return (/^(?:name|title):\s*["']?(.+?)["']?\s*$/m.exec(frontmatter)?.[1] ??
+        /^#\s+(.+)$/m.exec(content)?.[1] ??
+        "");
+}
+// A new record whose file name or title matches an existing one is probably the same fact:
+// the caller must update that record, or say it is a different one (allowSimilar).
+async function similarRecords(file, content) {
+    const roots = [
+        oceanPath(PERSONAL_DIR),
+        ...listProjectDirs().map(({ dir }) => oceanPath(dir, "memory")),
+    ];
+    const name = normalize(path.basename(file));
+    const heading = normalize(title(content));
+    const matches = [];
+    for (const root of roots)
+        for (const existing of await markdownFiles(root)) {
+            // The target itself is not "similar": an exact existing path is EXISTS.
+            if (existing === file ||
+                path.basename(existing).toLowerCase() === "memory.md")
+                continue;
+            const sameName = normalize(path.basename(existing)) === name;
+            const sameTitle = heading !== "" &&
+                normalize(title(await readFile(existing, "utf8"))) === heading;
+            if (sameName || sameTitle)
+                matches.push(path.relative(oceanPath(), existing).split(path.sep).join("/"));
+        }
+    return matches;
+}
+// An explicit save. Search-first is enforced by mode: `create` refuses an existing or similar
+// record, `update` needs the sha256 the caller read, so a stale or blind write cannot clobber.
+// The replaced content is kept in versions/ before the record changes.
+export async function writeMemoryRecord(options) {
+    const record = options.document
+        ? projectDocument(options.path)
+        : permanentRecord(options.path);
+    checkContent(options.content);
+    if (options.mode !== "create" && options.mode !== "update")
+        throw new MemoryContractError("INVALID", "mode must be create or update");
+    if (options.document && options.mode !== "create")
+        throw new MemoryContractError("INVALID", "a doc is only ever created");
+    if (options.mode === "create" && !options.allowSimilar && !options.document) {
+        const similar = await similarRecords(record.file, options.content);
+        if (similar.length)
+            throw new MemoryContractError("EXISTS_SIMILAR", "a record with the same name or title exists; update it, or pass allowSimilar if this is a different fact", { paths: similar });
+    }
+    const content = withNewline(options.content);
+    const id = newId();
+    await mkdir(path.dirname(record.file), { recursive: true });
+    assertNoLinks(record.root, record.file);
+    const { before, copy } = await withFileLock(record.file, async () => {
+        const current = await readIfPresent(record.file);
+        if (options.mode === "create" && current !== null)
+            throw new MemoryContractError("EXISTS", "record already exists; read it and write it back with mode update");
+        if (options.mode === "update") {
+            if (current === null)
+                throw new MemoryContractError("MISSING", "record does not exist; use mode create");
+            if (options.expectedHash !== sha256(current))
+                throw new MemoryContractError("CONFLICT", "expectedHash does not match the record; read it again before updating", { sha256: sha256(current) });
+        }
+        let copy;
+        if (current !== null) {
+            const stored = storedCopy("versions", id, record.relative);
+            await writeDurable(stored, current);
+            copy = path.relative(oceanPath(), stored).split(path.sep).join("/");
+        }
+        await atomicWrite(record.file, content);
+        return { before: current, copy };
+    });
+    await appendAudit({
+        id,
+        action: options.mode,
+        path: record.relative,
+        source: options.source ?? "unknown",
+        origin: options.provenance?.origin ?? "explicit",
+        ...(options.provenance ? { candidate: options.provenance.candidate } : {}),
+        beforeSha: before === null ? null : sha256(before),
+        afterSha: sha256(content),
+        copy,
+    });
+    if (record.personal)
+        await syncMemoryIndexes(true);
+    return {
+        path: record.relative,
+        mode: options.mode,
+        sha256: sha256(content),
+        auditId: id,
+        indexed: record.personal,
+    };
+}
+const singleLine = (value, field) => {
+    if (value === undefined)
+        return "";
+    if (typeof value !== "string" || /[\r\n]/.test(value) || value.length > 200)
+        throw new MemoryContractError("INVALID", `${field} must be one line of at most 200 characters`);
+    return value;
+};
+const RESERVED = new Set([
+    "candidate",
+    "origin",
+    "source",
+    "target",
+    "reason",
+    "created",
+]);
+function metaLines(meta) {
+    let lines = "";
+    for (const [key, value] of Object.entries(meta ?? {})) {
+        const rendered = JSON.stringify(value);
+        if (!/^[a-z][a-z_]{0,30}$/.test(key) ||
+            RESERVED.has(key) ||
+            rendered.length > 600)
+            throw new MemoryContractError("INVALID", `bad candidate field '${key}'`);
+        lines += `${key}: ${rendered}\n`;
+    }
+    return lines;
+}
+// An inferred or imported fact waits in candidates/ for the owner's review. The server names
+// the file; a proposed target is validated as a record path but never written here.
+export async function proposeMemory(options) {
+    checkContent(options.content);
+    const extra = metaLines(options.meta);
+    if (options.origin !== "inferred" && options.origin !== "imported")
+        throw new MemoryContractError("INVALID", "origin must be inferred or imported");
+    const target = !options.target
+        ? ""
+        : options.meta?.kind === "doc"
+            ? projectDocument(options.target).relative
+            : permanentRecord(options.target).relative;
+    const reason = singleLine(options.reason, "reason");
+    const source = singleLine(options.source, "source") || "unknown";
+    const id = newId();
+    const file = candidateFile(localDate(), id);
+    assertNoLinks(candidatesRoot(), file);
+    const body = `---\ncandidate: ${id}\norigin: ${options.origin}\nsource: ${JSON.stringify(source)}\ntarget: ${JSON.stringify(target)}\nreason: ${JSON.stringify(reason)}\ncreated: ${new Date().toISOString()}\n${extra}---\n\n${withNewline(options.content)}`;
+    await writeDurable(file, body);
+    const candidate = path.relative(oceanPath(), file).split(path.sep).join("/");
+    await appendAudit({
+        id,
+        action: "propose",
+        path: candidate,
+        source,
+        origin: options.origin,
+        beforeSha: null,
+        afterSha: sha256(body),
+    });
+    return { candidate, auditId: id };
+}
+//# sourceMappingURL=memory-write.js.map