oh-my-second-brain 0.1.8 → 0.2.0

package/dist/capture/safe.js

@@ -1,8 +1,10 @@
-import { mkdir, readFile, writeFile, appendFile } from "node:fs/promises";
+import { access, appendFile, mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { stringify as yamlStringify } from "yaml";
-import { validateFrontmatter } from "../conventions/validate.js";
-import { resolveConcept } from "../ontology/resolver.js";
+import { parseNote } from "../conventions/frontmatter.js";
+import { evaluateWriteContract, routingLawStrictFolders, writeFieldDescriptors, } from "../conventions/write-contract.js";
+import { rejection, } from "../conventions/write-protocol.js";
+import { resolveConcept } from "../core/ontology/resolver.js";
 function slugify(value) {
     const slug = value
         .toLowerCase()
@@ -26,12 +28,84 @@ function defaultInboxFolder(ontology) {
     const inboxConcept = ontology.concepts.get("inbox");
     return inboxConcept?.folder ?? "inbox";
 }
-function requiredMissing(concept, frontmatter) {
-    if (!concept)
-        return [];
-    return validateFrontmatter(frontmatter, concept).violations
-        .filter((violation) => violation.rule === "required")
-        .map((violation) => violation.field);
+function mergeFrontmatter(base, patch) {
+    return { ...base, ...patch };
+}
+function emptyWriteFields() {
+    return [];
+}
+function contractFields(concept) {
+    return concept ? writeFieldDescriptors(concept) : emptyWriteFields();
+}
+function writeResult(partial) {
+    return partial;
+}
+function inboxResult(mode, ontology, filename, frontmatter, reason) {
+    const inbox = defaultInboxFolder(ontology);
+    const inboxConcept = findConcept(ontology, "inbox");
+    return writeResult({
+        status: "inbox",
+        mode,
+        notePath: `${inbox}/${filename}`,
+        concept: "inbox",
+        folder: inbox,
+        fields: contractFields(inboxConcept),
+        frontmatter,
+        missingFields: [],
+        violations: [],
+        reason,
+    });
+}
+function pathUnsafeRejection(reason) {
+    return rejection("admission", "path-unsafe", reason, "pass a vault-relative `notePath` ending in .md that stays inside the vault and avoids hidden or internal folders");
+}
+function conceptUnboundRejection() {
+    return rejection("admission", "concept-unbound", "Cannot commit capture: notePath does not resolve to a concept binding", "move the note into a folder bound to a concept in taxonomy.yaml, or target an existing bound note");
+}
+function rejectedResult(mode, notePath, concept, frontmatter, violations, reason, rejectionPayload) {
+    return writeResult({
+        status: "rejected",
+        mode,
+        notePath,
+        concept: concept?.concept ?? null,
+        folder: notePath.split("/")[0] ?? "",
+        fields: contractFields(concept),
+        frontmatter,
+        missingFields: violations.map((violation) => violation.field),
+        violations,
+        reason,
+        ...(rejectionPayload ? { rejection: rejectionPayload } : {}),
+    });
+}
+function askResult(mode, notePath, concept, frontmatter, violations) {
+    return writeResult({
+        status: "ask",
+        mode,
+        notePath,
+        concept: concept.concept,
+        folder: notePath.split("/")[0] ?? concept.folder,
+        fields: contractFields(concept),
+        frontmatter,
+        missingFields: violations.map((violation) => violation.field),
+        violations,
+        rejection: rejection("admission", "contract-violation", "Capture does not satisfy the concept contract yet", `provide or correct these fields, then retry: ${violations
+            .map((violation) => violation.field)
+            .join(", ")}`),
+    });
+}
+function writtenResult(mode, notePath, concept, frontmatter, receipt) {
+    return writeResult({
+        status: "written",
+        mode,
+        notePath,
+        concept: concept?.concept ?? null,
+        folder: notePath.split("/")[0] ?? "",
+        fields: contractFields(concept),
+        frontmatter,
+        missingFields: [],
+        violations: [],
+        ...(receipt ? { receipt } : {}),
+    });
 }
 export function safeVaultNotePath(vault, notePath) {
     if (path.isAbsolute(notePath)) {
@@ -55,6 +129,22 @@ export function safeVaultNotePath(vault, notePath) {
     }
     return resolved;
 }
+function trySafeNotePath(vault, notePath) {
+    try {
+        const fullPath = safeVaultNotePath(vault, notePath);
+        return {
+            ok: true,
+            fullPath,
+            normalized: path.relative(vault, fullPath).replace(/\\/g, "/"),
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
 function safeCaptureFilename(requested, title) {
     if (!requested) {
         return {
@@ -72,96 +162,429 @@ function safeCaptureFilename(requested, title) {
         safe,
     };
 }
-export function prepareCapture(input) {
-    const frontmatter = input.frontmatter ?? {};
-    const requestedConcept = findConcept(input.ontology, input.concept);
-    const folder = input.folder ?? requestedConcept?.folder ?? defaultInboxFolder(input.ontology);
-    const folderConcepts = conceptsForFolder(input.ontology, folder);
-    const resolvedConcept = requestedConcept ?? findConcept(input.ontology, folderConcepts[0]);
+function planCreatePlacement(ontology, conceptName, folderName, filename, frontmatter) {
+    const requestedConcept = findConcept(ontology, conceptName);
+    const folder = folderName ?? requestedConcept?.folder ?? defaultInboxFolder(ontology);
+    const folderConcepts = conceptsForFolder(ontology, folder);
+    const resolvedConcept = requestedConcept ?? findConcept(ontology, folderConcepts[0]);
     const titleValue = frontmatter["title"];
     const title = typeof titleValue === "string" ? titleValue : "untitled";
-    const filenamePlan = safeCaptureFilename(input.filename, title);
-    const filename = filenamePlan.filename;
-    const notePath = `${folder}/${filename}`;
+    const filenamePlan = safeCaptureFilename(filename, title);
     if (!filenamePlan.safe) {
-        const inbox = defaultInboxFolder(input.ontology);
+        return {
+            kind: "inbox",
+            notePath: `${defaultInboxFolder(ontology)}/${filenamePlan.filename}`,
+            concept: findConcept(ontology, "inbox"),
+            folder: defaultInboxFolder(ontology),
+            filename: filenamePlan.filename,
+            reason: "Requested filename was unsafe; planned a safe inbox capture path.",
+        };
+    }
+    if (!resolvedConcept || !folderConcepts.includes(resolvedConcept.concept)) {
+        return {
+            kind: "inbox",
+            notePath: `${defaultInboxFolder(ontology)}/${filenamePlan.filename}`,
+            concept: findConcept(ontology, "inbox"),
+            folder: defaultInboxFolder(ontology),
+            filename: filenamePlan.filename,
+            reason: "No safe folder/concept binding matched the requested capture.",
+        };
+    }
+    return {
+        kind: "bound",
+        notePath: `${folder}/${filenamePlan.filename}`,
+        concept: resolvedConcept,
+        folder,
+        filename: filenamePlan.filename,
+    };
+}
+function formatNote(frontmatter, body) {
+    return `---\n${yamlStringify(frontmatter).trimEnd()}\n---\n\n${body.trim()}\n`;
+}
+function hasErrorCode(error, code) {
+    return error instanceof Error && "code" in error && error.code === code;
+}
+async function fileExists(fullPath) {
+    try {
+        await access(fullPath);
+        return true;
+    }
+    catch (error) {
+        if (hasErrorCode(error, "ENOENT")) {
+            return false;
+        }
+        throw error;
+    }
+}
+async function isDirectory(fullPath) {
+    try {
+        return (await stat(fullPath)).isDirectory();
+    }
+    catch (error) {
+        if (hasErrorCode(error, "ENOENT") || hasErrorCode(error, "ENOTDIR")) {
+            return false;
+        }
+        throw error;
+    }
+}
+export function prepareCapture(input) {
+    const frontmatter = input.frontmatter ?? {};
+    const planned = planCreatePlacement(input.ontology, input.concept, input.folder, input.filename, frontmatter);
+    if (planned.kind === "inbox") {
         return {
             action: "route-to-inbox",
             concept: "inbox",
-            folder: inbox,
-            notePath: `${inbox}/${filename}`,
+            folder: planned.folder,
+            notePath: planned.notePath,
             missingFields: [],
             frontmatter,
-            reason: "Requested filename was unsafe; planned a safe inbox capture path.",
+            fields: contractFields(planned.concept),
+            violations: [],
+            reason: planned.reason,
         };
     }
-    if (!resolvedConcept || !folderConcepts.includes(resolvedConcept.concept)) {
-        const inbox = defaultInboxFolder(input.ontology);
+    const concept = planned.concept;
+    if (!concept) {
         return {
             action: "route-to-inbox",
             concept: "inbox",
-            folder: inbox,
-            notePath: `${inbox}/${filename}`,
+            folder: defaultInboxFolder(input.ontology),
+            notePath: planned.notePath,
             missingFields: [],
             frontmatter,
+            fields: [],
+            violations: [],
             reason: "No safe folder/concept binding matched the requested capture.",
         };
     }
-    const missingFields = requiredMissing(resolvedConcept, frontmatter);
+    const contract = evaluateWriteContract(frontmatter, concept, planned.notePath, routingLawStrictFolders(input.ontology));
     return {
-        action: missingFields.length > 0 ? "ask-missing-fields" : "ready",
-        concept: resolvedConcept.concept,
-        folder,
-        notePath,
-        missingFields,
+        action: contract.valid ? "ready" : "ask-missing-fields",
+        concept: concept.concept,
+        folder: planned.folder,
+        notePath: planned.notePath,
+        missingFields: contract.violations.map((violation) => violation.field),
         frontmatter,
+        fields: contractFields(concept),
+        violations: contract.violations,
     };
 }
-function formatNote(frontmatter, body) {
-    return `---\n${yamlStringify(frontmatter).trimEnd()}\n---\n\n${body.trim()}\n`;
+/**
+ * Admission Rules - target verification.
+ *
+ * Runs before ANY disk mutation. `cwd` resolution is unverified for the write
+ * surface (the process may have booted anywhere). A `global` registry pointer
+ * must still point at a real `.oms` ontology; every other source is trusted
+ * without an ontology presence check so the bundled-ontology fallback keeps
+ * working.
+ */
+async function admitTarget(target) {
+    if (target.source === "cwd") {
+        return rejection("admission", "target-unverified", `Refusing to write: the target vault was inferred from the current directory (${target.vault}), which is not a verified Oh My Second Brain vault`, "run `oms setup` in your Obsidian vault (or set OMS_VAULT / register the vault in ~/.oms/config.yaml), then retry");
+    }
+    if (target.source === "global") {
+        const hasOntology = (await isDirectory(path.join(target.vault, ".oms", "concepts"))) ||
+            (await fileExists(path.join(target.vault, ".oms", "taxonomy.yaml")));
+        if (!hasOntology) {
+            return rejection("admission", "target-invalid", `Refusing to write: the registered global vault target has no .oms ontology: ${target.vault}`, "update ~/.oms/config.yaml to point at your vault, or run `oms setup` in that vault, then retry");
+        }
+    }
+    return undefined;
 }
-function hasErrorCode(error, code) {
-    return error instanceof Error && "code" in error && error.code === code;
+function targetRejectedResult(mode, input, frontmatter, rejectionPayload) {
+    return rejectedResult(mode, input.notePath ?? "", undefined, frontmatter, [], rejectionPayload.message, rejectionPayload);
 }
-export async function commitCapture(input) {
-    const fullPath = safeVaultNotePath(input.vault, input.notePath);
-    const normalizedNotePath = path.relative(input.vault, fullPath).replace(/\\/g, "/");
-    const concept = resolveConcept(input.ontology, normalizedNotePath);
-    if (!concept) {
-        throw new Error("Cannot commit capture: notePath does not resolve to a concept binding");
+/**
+ * Acceptance Criteria - staged evaluation (pre-persist).
+ *
+ * Parses the note content that is ABOUT to be written and re-runs the kernel
+ * write contract against the RENDERED frontmatter. This catches divergence
+ * between the caller-supplied frontmatter and what actually lands on disk
+ * (yaml round-trip artifacts such as `NaN` rendering as `.nan` and parsing
+ * back as `null`).
+ */
+export function evaluateStagedNote(stagedContent, concept, notePath, strictZones) {
+    const parsed = parseNote(stagedContent);
+    const contract = evaluateWriteContract(parsed.frontmatter, concept, notePath, strictZones);
+    return {
+        ok: contract.valid,
+        violations: contract.violations,
+        frontmatter: parsed.frontmatter,
+        body: parsed.body,
+    };
+}
+function sameViolationSet(left, right) {
+    if (left.length !== right.length) {
+        return false;
     }
-    const validation = validateFrontmatter(input.frontmatter, concept);
-    if (!validation.valid) {
-        const fields = validation.violations.map((violation) => violation.field).join(", ");
-        throw new Error(`Cannot commit capture: frontmatter violates the concept contract (${fields})`);
+    const key = (violation) => `${violation.field}\u0000${violation.rule}\u0000${violation.message}`;
+    const leftKeys = left.map(key).sort();
+    const rightKeys = right.map(key).sort();
+    return leftKeys.every((entry, index) => entry === rightKeys[index]);
+}
+/**
+ * Acceptance rejection for a staged render that diverges from the (already
+ * passing) input evaluation. Callers only reach this when the input-level
+ * contract check passed, so the violation is a genuine render divergence.
+ */
+function stagedRejectedResult(mode, notePath, concept, frontmatter, violations) {
+    const fields = violations.map((violation) => violation.field).join(", ");
+    return rejectedResult(mode, notePath, concept, frontmatter, violations, "Cannot write: the rendered note violates the concept contract", rejection("acceptance", "contract-violation", `Staged note render violates the concept contract (${fields})`, `these values do not survive the note render unchanged - correct them, then retry: ${fields}`));
+}
+function stagedBodyMissingResult(mode, notePath, concept, frontmatter) {
+    return rejectedResult(mode, notePath, concept, frontmatter, [], "create requires a body", rejection("acceptance", "body-missing", "Staged note render carries no body content", "pass a non-empty `body` for the note, then retry"));
+}
+function postconditionRejectedResult(mode, notePath, fullPath, concept, frontmatter, violations, detail) {
+    return rejectedResult(mode, notePath, concept, frontmatter, violations, `Postcondition failed after writing ${notePath}: ${detail}`, rejection("acceptance", "postcondition-failed", `Postcondition failed after writing ${notePath}: ${detail}`, `inspect the persisted file at ${fullPath} (it was NOT removed) and repair or delete it before retrying`));
+}
+function receiptFor(input, mode, notePath, concept) {
+    return {
+        resolvedVault: input.target.vault,
+        resolutionSource: input.target.source,
+        notePath,
+        mode,
+        concept: concept?.concept ?? null,
+        postconditionVerified: true,
+    };
+}
+function normalizeBody(body) {
+    return body.replace(/\s+$/, "");
+}
+/**
+ * Acceptance Criteria - postcondition (post-persist).
+ *
+ * Re-reads the persisted note through the `readBack` seam, re-runs the write
+ * contract on what is actually on disk, and asserts the intended body content
+ * landed. The persisted file is never auto-deleted on failure.
+ */
+async function verifyPostcondition(input, fullPath, notePath, concept, strictZones, expectation) {
+    const read = input.readBack ?? ((target) => readFile(target, "utf-8"));
+    const persisted = await read(fullPath);
+    const parsed = parseNote(persisted);
+    const contract = evaluateWriteContract(parsed.frontmatter, concept, notePath, strictZones);
+    if (!contract.valid) {
+        return {
+            ok: false,
+            violations: contract.violations,
+            detail: `persisted frontmatter violates the concept contract (${contract.violations
+                .map((violation) => violation.field)
+                .join(", ")})`,
+        };
+    }
+    const bodyOk = expectation.kind === "full"
+        ? normalizeBody(parsed.body) === normalizeBody(expectation.body)
+        : normalizeBody(persisted).endsWith(expectation.body.trim());
+    if (!bodyOk) {
+        return { ok: false, violations: [], detail: "persisted body does not match the staged content" };
+    }
+    return { ok: true, violations: [], detail: "" };
+}
+export async function writeNote(input) {
+    const frontmatter = input.frontmatter ?? {};
+    const strictZones = routingLawStrictFolders(input.ontology);
+    const targetRejection = await admitTarget(input.target);
+    if (targetRejection) {
+        return targetRejectedResult(input.mode, input, frontmatter, targetRejection);
+    }
+    if (input.mode === "update") {
+        return writeUpdate(input, frontmatter, strictZones);
     }
-    await mkdir(path.dirname(fullPath), { recursive: true });
     if (input.mode === "append") {
-        try {
-            await readFile(fullPath, "utf-8");
-            await appendFile(fullPath, `\n\n${input.body.trim()}\n`, "utf-8");
+        return writeAppend(input, frontmatter, strictZones);
+    }
+    return writeCreate(input, frontmatter, strictZones);
+}
+async function writeCreate(input, frontmatter, strictZones) {
+    let notePath;
+    let concept;
+    if (input.notePath) {
+        const safe = trySafeNotePath(input.target.vault, input.notePath);
+        if (!safe.ok) {
+            return rejectedResult("create", input.notePath, undefined, frontmatter, [], safe.reason, pathUnsafeRejection(safe.reason));
         }
-        catch (error) {
-            if (!hasErrorCode(error, "ENOENT")) {
-                throw error;
-            }
-            await writeFile(fullPath, formatNote(input.frontmatter, input.body), "utf-8");
+        notePath = safe.normalized;
+        concept = resolveConcept(input.ontology, notePath);
+        if (!concept) {
+            const filename = path.posix.basename(notePath);
+            return inboxResult("create", input.ontology, filename, frontmatter, "No safe folder/concept binding matched the requested capture.");
         }
     }
     else {
-        try {
-            await writeFile(fullPath, formatNote(input.frontmatter, input.body), {
-                encoding: "utf-8",
-                flag: "wx",
-            });
+        const planned = planCreatePlacement(input.ontology, input.concept, input.folder, input.filename, frontmatter);
+        if (planned.kind === "inbox") {
+            return inboxResult("create", input.ontology, planned.filename, frontmatter, planned.reason ?? "No safe folder/concept binding matched the requested capture.");
         }
-        catch (error) {
-            if (hasErrorCode(error, "EEXIST")) {
-                throw new Error("Cannot create capture: target note already exists");
-            }
-            throw error;
+        notePath = planned.notePath;
+        concept = planned.concept;
+    }
+    if (!concept) {
+        return inboxResult("create", input.ontology, path.posix.basename(notePath), frontmatter, "No safe folder/concept binding matched the requested capture.");
+    }
+    const contract = evaluateWriteContract(frontmatter, concept, notePath, strictZones);
+    if (!contract.valid) {
+        return askResult("create", notePath, concept, frontmatter, contract.violations);
+    }
+    if (input.body === undefined) {
+        return rejectedResult("create", notePath, concept, frontmatter, [], "create requires a body", rejection("admission", "body-missing", "create requires a body", "pass a non-empty `body` for the note, then retry"));
+    }
+    const safe = trySafeNotePath(input.target.vault, notePath);
+    if (!safe.ok) {
+        return rejectedResult("create", notePath, concept, frontmatter, [], safe.reason, pathUnsafeRejection(safe.reason));
+    }
+    if (await fileExists(safe.fullPath)) {
+        return rejectedResult("create", notePath, concept, frontmatter, [], "Cannot create capture: target note already exists", rejection("admission", "note-exists", "Cannot create capture: target note already exists", "use mode `append` or `update` for an existing note, or choose a different filename"));
+    }
+    // Write Attempt: build the staged note in memory.
+    const staged = formatNote(frontmatter, input.body);
+    // Evaluation (pre-persist): the staged render is a second gate that only
+    // fires on divergence from the input evaluation, which already passed above.
+    const stagedEvaluation = evaluateStagedNote(staged, concept, notePath, strictZones);
+    if (!stagedEvaluation.ok && !sameViolationSet(stagedEvaluation.violations, contract.violations)) {
+        return stagedRejectedResult("create", notePath, concept, frontmatter, stagedEvaluation.violations);
+    }
+    if (stagedEvaluation.body.trim() === "") {
+        return stagedBodyMissingResult("create", notePath, concept, frontmatter);
+    }
+    if (input.dryRun) {
+        return writtenResult("create", notePath, concept, frontmatter);
+    }
+    // Persist.
+    await mkdir(path.dirname(safe.fullPath), { recursive: true });
+    await writeFile(safe.fullPath, staged, {
+        encoding: "utf-8",
+        flag: "wx",
+    });
+    // Postcondition.
+    const postcondition = await verifyPostcondition(input, safe.fullPath, notePath, concept, strictZones, { kind: "full", body: stagedEvaluation.body });
+    if (!postcondition.ok) {
+        return postconditionRejectedResult("create", notePath, safe.fullPath, concept, frontmatter, postcondition.violations, postcondition.detail);
+    }
+    return writtenResult("create", notePath, concept, frontmatter, receiptFor(input, "create", notePath, concept));
+}
+async function writeAppend(input, frontmatter, strictZones) {
+    if (!input.notePath) {
+        return rejectedResult("append", "", undefined, frontmatter, [], "append requires notePath", rejection("admission", "args-invalid", "append requires notePath", "pass the vault-relative `notePath` of the note to append to, then retry"));
+    }
+    if (input.body === undefined) {
+        return rejectedResult("append", input.notePath, undefined, frontmatter, [], "append requires a body", rejection("admission", "body-missing", "append requires a body", "pass a non-empty `body` to append, then retry"));
+    }
+    const safe = trySafeNotePath(input.target.vault, input.notePath);
+    if (!safe.ok) {
+        return rejectedResult("append", input.notePath, undefined, frontmatter, [], safe.reason, pathUnsafeRejection(safe.reason));
+    }
+    const exists = await fileExists(safe.fullPath);
+    if (!exists) {
+        const created = await writeCreate({
+            target: input.target,
+            ontology: input.ontology,
+            mode: "create",
+            dryRun: input.dryRun,
+            notePath: safe.normalized,
+            frontmatter,
+            body: input.body,
+        }, frontmatter, strictZones);
+        if (created.status !== "written") {
+            return created;
         }
+        return writeResult({
+            ...created,
+            mode: "append",
+            ...(created.receipt ? { receipt: { ...created.receipt, mode: "append" } } : {}),
+        });
+    }
+    const raw = await readFile(safe.fullPath, "utf-8");
+    const parsed = parseNote(raw);
+    const concept = resolveConcept(input.ontology, safe.normalized);
+    if (!concept) {
+        return rejectedResult("append", safe.normalized, undefined, parsed.frontmatter, [], "Cannot commit capture: notePath does not resolve to a concept binding", conceptUnboundRejection());
+    }
+    const contract = evaluateWriteContract(parsed.frontmatter, concept, safe.normalized, strictZones);
+    if (!contract.valid) {
+        return rejectedResult("append", safe.normalized, concept, parsed.frontmatter, contract.violations, "Cannot append: existing frontmatter violates the concept contract");
+    }
+    // Write Attempt: the staged note is exactly what the file will hold after the
+    // append (current content + the appended block).
+    const appended = `\n\n${input.body.trim()}\n`;
+    const staged = `${raw}${appended}`;
+    // Evaluation (pre-persist).
+    const stagedEvaluation = evaluateStagedNote(staged, concept, safe.normalized, strictZones);
+    if (!stagedEvaluation.ok && !sameViolationSet(stagedEvaluation.violations, contract.violations)) {
+        return stagedRejectedResult("append", safe.normalized, concept, parsed.frontmatter, stagedEvaluation.violations);
+    }
+    if (input.dryRun) {
+        return writtenResult("append", safe.normalized, concept, parsed.frontmatter);
+    }
+    // Persist.
+    await appendFile(safe.fullPath, appended, "utf-8");
+    // Postcondition.
+    const postcondition = await verifyPostcondition(input, safe.fullPath, safe.normalized, concept, strictZones, { kind: "suffix", body: input.body });
+    if (!postcondition.ok) {
+        return postconditionRejectedResult("append", safe.normalized, safe.fullPath, concept, parsed.frontmatter, postcondition.violations, postcondition.detail);
+    }
+    return writtenResult("append", safe.normalized, concept, parsed.frontmatter, receiptFor(input, "append", safe.normalized, concept));
+}
+async function writeUpdate(input, frontmatter, strictZones) {
+    if (!input.notePath) {
+        return rejectedResult("update", "", undefined, frontmatter, [], "update requires notePath", rejection("admission", "args-invalid", "update requires notePath", "pass the vault-relative `notePath` of the note to update, then retry"));
+    }
+    if (input.frontmatter === undefined && input.body === undefined) {
+        return rejectedResult("update", input.notePath, undefined, frontmatter, [], "update requires frontmatter or body", rejection("admission", "args-invalid", "update requires frontmatter or body", "pass `frontmatter`, `body`, or both, then retry"));
+    }
+    const safe = trySafeNotePath(input.target.vault, input.notePath);
+    if (!safe.ok) {
+        return rejectedResult("update", input.notePath, undefined, frontmatter, [], safe.reason, pathUnsafeRejection(safe.reason));
+    }
+    if (!(await fileExists(safe.fullPath))) {
+        return rejectedResult("update", safe.normalized, undefined, frontmatter, [], "Cannot update capture: target note does not exist", rejection("admission", "note-missing", "Cannot update capture: target note does not exist", "create the note first (mode `create`) or correct `notePath`, then retry"));
+    }
+    const raw = await readFile(safe.fullPath, "utf-8");
+    const parsed = parseNote(raw);
+    const merged = input.frontmatter === undefined ? parsed.frontmatter : mergeFrontmatter(parsed.frontmatter, frontmatter);
+    const body = input.body === undefined ? parsed.body : input.body;
+    const concept = resolveConcept(input.ontology, safe.normalized);
+    if (!concept) {
+        return rejectedResult("update", safe.normalized, undefined, merged, [], "Cannot commit capture: notePath does not resolve to a concept binding", conceptUnboundRejection());
+    }
+    const contract = evaluateWriteContract(merged, concept, safe.normalized, strictZones);
+    if (!contract.valid) {
+        return rejectedResult("update", safe.normalized, concept, merged, contract.violations, "Cannot update capture: resulting frontmatter violates the concept contract");
+    }
+    // Write Attempt: build the staged note in memory.
+    const staged = formatNote(merged, body);
+    // Evaluation (pre-persist).
+    const stagedEvaluation = evaluateStagedNote(staged, concept, safe.normalized, strictZones);
+    if (!stagedEvaluation.ok && !sameViolationSet(stagedEvaluation.violations, contract.violations)) {
+        return stagedRejectedResult("update", safe.normalized, concept, merged, stagedEvaluation.violations);
+    }
+    if (input.dryRun) {
+        return writtenResult("update", safe.normalized, concept, merged);
+    }
+    // Persist.
+    await writeFile(safe.fullPath, staged, "utf-8");
+    // Postcondition.
+    const postcondition = await verifyPostcondition(input, safe.fullPath, safe.normalized, concept, strictZones, { kind: "full", body: stagedEvaluation.body });
+    if (!postcondition.ok) {
+        return postconditionRejectedResult("update", safe.normalized, safe.fullPath, concept, merged, postcondition.violations, postcondition.detail);
+    }
+    return writtenResult("update", safe.normalized, concept, merged, receiptFor(input, "update", safe.normalized, concept));
+}
+export async function commitCapture(input) {
+    const result = await writeNote({
+        target: { vault: input.vault, source: input.source },
+        ontology: input.ontology,
+        mode: input.mode,
+        dryRun: false,
+        notePath: input.notePath,
+        frontmatter: input.frontmatter,
+        body: input.body,
+    });
+    if (result.status === "written") {
+        return { written: true, mode: input.mode, notePath: result.notePath };
+    }
+    if (result.violations.length > 0) {
+        const fields = result.violations.map((violation) => violation.field).join(", ");
+        throw new Error(`Cannot commit capture: frontmatter violates the concept contract (${fields})`);
     }
-    return { written: true, mode: input.mode, notePath: normalizedNotePath };
+    throw new Error(result.reason ?? "Cannot commit capture");
 }
 //# sourceMappingURL=safe.js.map