@plurnk/plurnk-service 3.1.0 → 3.2.0

package/dist/schemes/File.js

@@ -1,14 +1,15 @@
 var _a;
-import { lstat, mkdir, readFile, realpath, rm, stat, writeFile } from "node:fs/promises";
+import { lstat, realpath, rm, stat } from "node:fs/promises";
 import Namespace from "../core/namespace.js";
-import { fileMissRecovery, missDetail, missExtensions } from "../core/plurnk-uri.js";
-import { basename, dirname, relative, isAbsolute, join } from "node:path";
+import FileAddress from "../core/FileAddress.js";
+import { entryAddress, fileMissRecovery, missDetail, missExtensions } from "../core/plurnk-uri.js";
+import { relative, isAbsolute, join } from "node:path";
 import { createPatch } from "diff";
 import { PlurnkParser } from "@plurnk/plurnk-parser";
-import { PathSyntax } from "@plurnk/plurnk-contracts";
 import EntryManifest from "./_entry-manifest.js";
 import GitMembership from "../core/git-membership.js";
-import EntryFind from "./_entry-find.js";
+import EntryFind, { emptyFindFields } from "./_entry-find.js";
+import { pathScope } from "./_path-scope.js";
 import EntryCrud from "./_entry-crud.js";
 import { CoreSchemeAdapterBase } from "../core/CoreSchemeServices.js";
 import ErrorDetail from "../core/ErrorDetail.js";
@@ -18,34 +19,8 @@ import { FileByteSource, InvalidOperationResultError, } from "@plurnk/plurnk-sch
 import { LineMarkerOps, LineAnchors, EditCollision, EDIT_NOOP_DETAIL, MimetypeBinary, editReceipt, projectEditReceipt, reviewerReplacementReceipt, withEditReceiptParseIssues, } from "../content/index.js";
 import DbProjectionCaps from "../core/caps/DbProjectionCaps.js";
 import FileMaterialization from "../core/file-materialization.js";
-// Workspace root for file ops is sourced from `workspaces.project_root`,
-// supplied at {§methods-workspace-create}. Under {§fs-namespace}, core never
-// guesses a root: headless workspaces fail file operations at 400.
-const loadWorkspaceRoot = async (db, workspaceId) => {
-    const row = await db.envelope_get_workspace.get({ id: workspaceId });
-    return row?.project_root ?? null;
-};
-// Resolve the nearest existing ancestor, then append the still-absent tail. This
-// gives a proposed create the same physical containment check as an existing path:
-// an in-root symlinked parent cannot smuggle a root-scoped write outside the namespace.
-const prospectiveRealpath = async (requested) => {
-    const tail = [basename(requested)];
-    let cursor = dirname(requested);
-    while (true) {
-        try {
-            return join(await realpath(cursor), ...tail);
-        }
-        catch (cause) {
-            if (cause.code !== "ENOENT")
-                throw cause;
-        }
-        const parent = dirname(cursor);
-        if (parent === cursor)
-            throw new Error(`No existing ancestor contains '${requested}'.`);
-        tail.unshift(basename(cursor));
-        cursor = parent;
-    }
-};
+import FileSnapshot from "../core/FileSnapshot.js";
+import FilePublication from "../core/FilePublication.js";
 // Detect mimetype from a file's path through the configured registry. The
 // `MimetypeBinary.normalizeAutoTextMimetype` wrapper ensures text/plain returned by the
 // service is normalized to text/markdown — plurnk-service never auto-
@@ -62,10 +37,9 @@ const detectFileMimetype = async (canonical, ctx) => {
 class File extends CoreSchemeAdapterBase {
     static manifest = {
         name: "file",
-        storedScheme: "file", // {§entry-identity-no-null} — durable identity; file addresses still render as bare paths
-        // body's real mimetype is detected per file path; the declared type is only the
-        // extension-less fallback. readable: the derived projection ({§readable-channel}).
-        channels: { body: "text/markdown", readable: "text/markdown" },
+        storedScheme: "file", // {§entry-identity-no-null} — durable identity, independent of displayed spelling
+        // The body is typed per resource; readable is its derived projection ({§readable-channel}).
+        channels: { readable: "text/markdown" },
         defaultChannel: "body",
         category: "data",
         writableBy: ["model", "client", "_plurnk"],
@@ -80,37 +54,21 @@ class File extends CoreSchemeAdapterBase {
             "A scoped EDIT replaces the addressed lines; put the replacement text in its body.",
         ].join("\n\n"),
     };
-    // {§fs-namei} Resolve FIND's address before selecting member candidates.
-    static async #canonTarget(statement, root) {
-        const t = statement.target;
-        if (t === null)
-            return statement;
-        if (t.kind === "url") {
-            const key = await _a.#canonSpelling(t.pathname, root);
-            if (key === null)
-                return null;
-            return key === t.pathname ? statement : { ...statement, target: { ...t, pathname: key } };
-        }
-        if (t.kind === "local") {
-            const key = await _a.#canonSpelling(t.raw, root);
-            if (key === null)
-                return null;
-            return key === t.raw ? statement : { ...statement, target: { ...t, raw: key } };
-        }
-        return statement; // regex — not a path
-    }
     // {§file-find-directory}: a directory's canonical collection address does not depend on
     // whether its authored spelling included the slash. Membership still owns its contents.
-    static async #canonSpelling(raw, root) {
+    static async #canonSpelling(raw, root, pattern = false) {
         const key = Namespace.canonicalizeSpelling(raw, root);
         if (root === null || key === null || key.length === 0
-            || key.endsWith("/") || key.startsWith("../") || PathSyntax.hasGlob(key))
+            || key.endsWith("/") || key.startsWith("../") || pattern)
             return key;
-        return (await _a.#occupant(root, PathSyntax.decodeParens(key)))?.isDirectory() === true ? `${key}/` : key;
+        return (await _a.#occupant(root, key))?.isDirectory() === true ? `${key}/` : key;
     }
     async resolveEntryAddress(target, ctx, access = "read") {
         const core = this.coreContext(ctx);
-        const pathname = await _a.#canonSpelling(target.kind === "url" ? target.pathname : target.raw, await loadWorkspaceRoot(core.db, core.workspaceId));
+        const spelling = FileAddress.pathname(target);
+        if (typeof spelling !== "string")
+            return spelling;
+        const pathname = await _a.#canonSpelling(spelling, await FileAddress.projectRoot(core), FileAddress.isPattern(target));
         if (pathname === null)
             return null;
         if (access === "write") {
@@ -135,9 +93,28 @@ class File extends CoreSchemeAdapterBase {
     async find(statement, ctx) {
         const core = this.coreContext(ctx);
         // {§fs-namei} Exact paths, folders and globs share the filesystem base.
-        const root = await loadWorkspaceRoot(core.db, core.workspaceId);
-        const canon = await _a.#canonTarget(statement, root);
-        return EntryFind.findWorkspaceEntries(canon ?? statement, core, _a.manifest, {
+        const root = await FileAddress.projectRoot(core);
+        const spelling = statement.target === null ? "" : FileAddress.selector(statement.target, root);
+        if (typeof spelling !== "string")
+            return { ...emptyFindFields(), ...spelling };
+        const pattern = FileAddress.isPattern(statement.target);
+        const key = await _a.#canonSpelling(spelling, root, pattern);
+        let scope = key === null ? undefined : !pattern && key !== "" && !key.endsWith("/")
+            ? { kind: "exact", pathname: key, candidatePrefix: key }
+            : pathScope(key, true);
+        if (scope?.kind === "glob" && statement.target?.kind === "url") {
+            const authored = pathScope(statement.target.pathname, true);
+            // Structural catalogs use a literal prefix, even when its URL needs quoting.
+            if (authored.kind === "glob" && (authored.shallowPrefix !== null || authored.recursivePrefix !== null)) {
+                const literal = Namespace.canonicalizeSpelling(FileAddress.pathname(statement.target), root);
+                const prefix = literal.slice(0, authored.shallowPrefix !== null ? -1 : -2);
+                scope = { ...scope, candidatePrefix: prefix,
+                    shallowPrefix: authored.shallowPrefix === null ? null : prefix,
+                    recursivePrefix: authored.recursivePrefix === null ? null : prefix };
+            }
+        }
+        return EntryFind.findWorkspaceEntries(statement, core, _a.manifest, {
+            ...(scope === undefined ? {} : { scope }),
             ...(root === null ? {} : { pathBase: root }),
             bytes: (pathname) => this.byteSource({ authority: "", pathname }, core),
         });
@@ -146,7 +123,7 @@ class File extends CoreSchemeAdapterBase {
     async readEntry(pathname, ctx) {
         const core = this.coreContext(ctx);
         // {§scheme-address} {§fs-namei} All read paths resolve the same member key.
-        const root = await loadWorkspaceRoot(core.db, core.workspaceId);
+        const root = await FileAddress.projectRoot(core);
         const key = root === null ? pathname : Namespace.canonicalize(pathname, root);
         const canonical = key ?? pathname;
         const result = "entries" in ctx
@@ -161,7 +138,7 @@ class File extends CoreSchemeAdapterBase {
     byteSource({ pathname }, ctx) {
         const core = this.coreContext(ctx);
         const locate = async () => {
-            const root = await loadWorkspaceRoot(core.db, core.workspaceId);
+            const root = await FileAddress.projectRoot(core);
             if (root === null)
                 return null;
             const key = Namespace.canonicalize(pathname, root);
@@ -174,7 +151,7 @@ class File extends CoreSchemeAdapterBase {
     // and an occupied path says so. Beyond it the disk stays dark: nothing is looked at, and the
     // sentence is true whether or not a file is there — it neither claims absence nor hints at presence.
     async missRefusal(pathname, core, fields) {
-        const root = await loadWorkspaceRoot(core.db, core.workspaceId);
+        const root = await FileAddress.projectRoot(core);
         if (root === null)
             return null;
         const key = Namespace.canonicalize(pathname, root);
@@ -182,7 +159,7 @@ class File extends CoreSchemeAdapterBase {
             return null;
         const occupant = key.startsWith("../") ? null : await _a.#occupant(root, key);
         if (occupant?.isDirectory() === true) {
-            const { code, detail, extensions } = _a.#directoryFacts(key, "READ");
+            const { code, detail, extensions } = _a.#directoryFacts(key, "READ", root);
             return Results.failure("scheme:file", code, 404, detail, fields, extensions);
         }
         const occupied = occupant !== null;
@@ -192,7 +169,7 @@ class File extends CoreSchemeAdapterBase {
         return Results.failure("scheme:file", occupied ? "entry-not-member" : "entry-not-found", 404, occupied
             ? `'${key}' exists on disk but is not a member of this workspace.`
             : missDetail("file", key), fields, {
-            target: key,
+            target: entryAddress("file", "", key, root),
             recovery: occupied
                 ? ignored
                     ? "The repository ignores it: a client or operator members definition can include it, a model definition cannot."
@@ -214,14 +191,15 @@ class File extends CoreSchemeAdapterBase {
     }
     // {§file-directory-target} — a directory inside the root is named as one, never as a missing or non-member
     // file; a READ or KILL of it carries the listing that shows its files ({§diagnostic-observation}).
-    static #directoryFacts(key, op) {
-        const listing = `\`FIND (${key}/)\` lists its files.`;
+    static #directoryFacts(key, op, root) {
+        const target = entryAddress("file", "", key, root);
+        const listing = `\`FIND (${target}/)\` lists its files.`;
         const { detail, recovery } = {
             READ: { detail: `'${key}' is a directory, not a file; READ reads one file.`, recovery: listing },
             EDIT: { detail: `'${key}' is a directory, not a file; EDIT writes one file.`, recovery: undefined },
             KILL: { detail: `'${key}' is a directory, not a file; KILL removes one file.`, recovery: listing },
         }[op];
-        return { code: "path-is-directory", detail, extensions: { target: key, ...(recovery === undefined ? {} : { recovery }), retryable: false } };
+        return { code: "path-is-directory", detail, extensions: { target, ...(recovery === undefined ? {} : { recovery }), retryable: false } };
     }
     // {§membership} disk-write gate, shared by edit() and writeEntry() (the COPY/MOVE
     // dest). Resolves the canonical path; enforces containment (traversal → 403),
@@ -231,7 +209,7 @@ class File extends CoreSchemeAdapterBase {
     // and a copy into file:/// are the same disk write under the same review.
     // {§membership-edit-membership-gate} — membership/containment/read-only/binary gate before any disk write
     async #resolveWriteTarget(pathname, ctx, bytesMode = false) {
-        const root = await loadWorkspaceRoot(ctx.db, ctx.workspaceId);
+        const root = await FileAddress.projectRoot(ctx);
         if (root === null) {
             return {
                 ok: false,
@@ -290,7 +268,7 @@ class File extends CoreSchemeAdapterBase {
                 if (occupancyCause.code !== "ENOENT")
                     throw occupancyCause;
             }
-            canonical = await prospectiveRealpath(requested);
+            canonical = await FileSnapshot.prospectivePath(requested);
             fileExists = false;
         }
         if (!isMount) {
@@ -315,13 +293,14 @@ class File extends CoreSchemeAdapterBase {
         const rel = key; // the bare canonical member key ({§fs-canonical-name}) — storage ≡ wire
         let original = "";
         let baseSig = null; // the snapshot signature the proposal is computed against; null = create (assumed-absent)
+        let sourceMimetype = null;
         let creationAdmission = null;
         if (fileExists) {
-            const member = await ctx.db.crud_get_member_sig.get({ workspace_id: ctx.workspaceId, scheme: "file", authority: "", pathname: rel });
+            const member = await ctx.db.crud_read_file_snapshot.get({ workspace_id: ctx.workspaceId, pathname: rel });
             // {§fs-errno} — the occupancy fact (POSIX O_EXCL precedent): something invisible
             // occupies the path; existence leaks, content stays dark. The model picks another name.
             if (member === undefined && !isMount && (await lstat(requested)).isDirectory()) {
-                return { ok: false, status: 403, ..._a.#directoryFacts(rel, "EDIT") };
+                return { ok: false, status: 403, ..._a.#directoryFacts(rel, "EDIT", root) };
             }
             if (member === undefined) {
                 return {
@@ -343,10 +322,15 @@ class File extends CoreSchemeAdapterBase {
             if (currentMaterialization.disposition === "input-limit") {
                 return { ok: false, ...FileMaterialization.rejection(rel, currentMaterialization) };
             }
-            // {§membership-edit-write-cas}: diff against the READ snapshot; CAS protects the disk landing.
-            const snapshot = await ctx.db.ops_read_channel.get({ workspace_id: ctx.workspaceId, scheme: "file", authority: "", pathname: rel, channel: "body" });
-            original = snapshot?.content ?? "";
+            // {§membership-edit-write-revision}: retain the materialized baseline through approval.
+            const revision = FileSnapshot.decode(member.synced_sig);
+            if (revision === null || revision.hash === null || member.content === null || member.source_mimetype === null) {
+                const conflict = EditCollision.result(rel);
+                return { ok: false, code: "edit-collision", status: conflict.status, detail: conflict.problem.detail };
+            }
+            original = member.content;
             baseSig = member.synced_sig;
+            sourceMimetype = member.source_mimetype;
         }
         else {
             const admission = await GitMembership.planCreation(ctx.db, ctx.workspaceId, rel, ctx.signal);
@@ -354,7 +338,7 @@ class File extends CoreSchemeAdapterBase {
                 return admission;
             creationAdmission = admission;
         }
-        const mimetype = await detectFileMimetype(canonical, ctx);
+        const mimetype = sourceMimetype ?? await detectFileMimetype(canonical, ctx);
         // {§binary-parity} — a text EDIT still cannot author bytes into a binary file (a text body is
         // not bytes). A whole-resource or byte-range TRANSFER passes bytesMode: it writes the source's
         // bytes verbatim, so the binary mimetype is the point, not an error.
@@ -372,7 +356,7 @@ class File extends CoreSchemeAdapterBase {
         }
         return { ok: true, canonical, rel, fileExists, original, mimetype, baseSig, creationAdmission };
     }
-    // {§membership-edit-write-cas}, {§proposal-202-pauses}: return status=202
+    // {§membership-edit-write-revision}, {§proposal-202-pauses}: return status=202
     // with a udiff body for client review and attrs carrying the full patched
     // content. Engine pauses dispatch and calls applyResolution() after accept.
     async editBatch(statements, ctx) {
@@ -392,11 +376,16 @@ class File extends CoreSchemeAdapterBase {
                 retryable: false,
             });
         }
-        const pathname = PathSyntax.decodeParens(statement.target.kind === "url" ? statement.target.pathname : statement.target.raw); // {§path-parentheses}
-        const target = await this.#resolveWriteTarget(pathname, core);
+        const pathname = FileAddress.pathname(statement.target);
+        if (typeof pathname !== "string")
+            return pathname;
+        const target = await this.#resolveWriteTarget(Namespace.expandHome(pathname), core);
         if (!target.ok)
             return failure(target.code, target.status, target.detail, target.extensions);
         const { canonical, rel, fileExists, original, mimetype, baseSig } = target;
+        const selectedRevision = SchemeCtxImpl.fileRevisionOf(ctx);
+        if (selectedRevision !== undefined && selectedRevision !== baseSig)
+            return EditCollision.result(rel);
         for (const candidate of statements.slice(1)) {
             if (candidate.target === null) {
                 return failure("edit-batch-mismatch", 400, "The EDIT batch spans multiple resources.", {
@@ -404,8 +393,10 @@ class File extends CoreSchemeAdapterBase {
                     retryable: false,
                 });
             }
-            const candidatePathname = PathSyntax.decodeParens(candidate.target.kind === "url" ? candidate.target.pathname : candidate.target.raw);
-            const candidateTarget = await this.#resolveWriteTarget(candidatePathname, core);
+            const candidatePathname = FileAddress.pathname(candidate.target);
+            if (typeof candidatePathname !== "string")
+                return candidatePathname;
+            const candidateTarget = await this.#resolveWriteTarget(Namespace.expandHome(candidatePathname), core);
             if (!candidateTarget.ok || candidateTarget.rel !== rel) {
                 return failure("edit-batch-mismatch", 400, "The EDIT batch spans multiple resources.", {
                     recovery: "Submit a separate EDIT batch for each resource.",
@@ -458,14 +449,14 @@ class File extends CoreSchemeAdapterBase {
         const receiptEdits = fileExists
             ? (appliedEdits ?? statements.map((candidate) => ({ marker: candidate.lineMarker, body: candidate.body ?? "" })))
             : [{ marker: { marks: [1, -1] }, body: patched }];
-        const batchReceipt = editReceipt(original, patched, receiptEdits, undefined, EntryManifest.toPath("file", "", rel));
+        const batchReceipt = editReceipt(original, patched, receiptEdits, undefined, EntryManifest.toPath("file", "", rel, await FileAddress.projectRoot(core)));
         return {
             status: 202,
             body: patch,
             editReceipt: batchReceipt,
             ...(scopeNormalizations === undefined ? {} : { scopeNormalizations }),
             ...(merges === undefined ? {} : { merges }),
-            attrs: { path: rel, canonical, patch, patched, mimetype, editReceipt: batchReceipt, baseSig, existed: fileExists },
+            attrs: { path: rel, canonical, original, patch, patched, mimetype, editReceipt: batchReceipt, baseSig, existed: fileExists },
         };
     }
     async edit(statement, ctx) {
@@ -491,15 +482,22 @@ class File extends CoreSchemeAdapterBase {
         if (!target.ok) {
             return Results.failure("scheme:file", target.code, target.status, target.detail, { created: false, entryId: null }, target.extensions);
         }
-        const { canonical, rel, fileExists, original, mimetype, baseSig } = target;
+        const { canonical, rel, fileExists, original, baseSig } = target;
+        // {§copy-destination-mimetype}: retain the admitted per-call type on creation.
+        const mimetype = fileExists ? target.mimetype : bodyChannel.mimetype;
+        const selectedRevision = SchemeCtxImpl.fileRevisionOf(ctx);
+        if (selectedRevision !== undefined && selectedRevision !== baseSig)
+            return {
+                ...EditCollision.result(rel), created: false, entryId: null,
+            };
         if (bytes !== undefined) {
             // {§binary-parity} — a byte write carries no text diff; the receipt is the byte count and
             // the bytes ride attrs.patchedBytes to applyResolution, which writes them verbatim to disk.
-            return { status: 202, created: !fileExists, entryId: null, body: `${bytes.length} bytes`, attrs: { path: rel, canonical, patchedBytes: bytes, patched: "", mimetype, baseSig, existed: fileExists } };
+            return { status: 202, created: !fileExists, entryId: null, body: `${bytes.length} bytes`, attrs: { path: rel, canonical, original, patchedBytes: bytes, patched: "", mimetype, baseSig, existed: fileExists } };
         }
         const patched = bodyChannel.content;
         const patch = createPatch(rel, original, patched, "current", "proposed");
-        return { status: 202, created: !fileExists, entryId: null, body: patch, attrs: { path: rel, canonical, patch, patched, mimetype, baseSig, existed: fileExists } };
+        return { status: 202, created: !fileExists, entryId: null, body: patch, attrs: { path: rel, canonical, original, patch, patched, mimetype, baseSig, existed: fileExists } };
     }
     // applyResolution — called by Engine.dispatch after a proposed log
     // entry resolves with decision=accept. Two responsibilities:
@@ -511,37 +509,9 @@ class File extends CoreSchemeAdapterBase {
     async applyResolution(args, ctx) {
         const core = this.coreContext(ctx);
         const { attrs, body } = args;
-        // Delete-apply (deferred behind review — the KILL proposal, or the MOVE source-delete gated by
-        // its dest proposal): unlink the host file + deregister the entry on accept. A real unlink
-        // failure surfaces as 500, never a silent noop; ENOENT ⇒ file already gone, still deregister.
-        if (typeof attrs.deletePath === "string") {
-            const root = await loadWorkspaceRoot(core.db, core.workspaceId);
-            if (root === null) {
-                throw new InvalidOperationResultError("An accepted file deletion has no workspace project root.");
-            }
-            try {
-                await rm(join(root, attrs.deletePath));
-            }
-            catch (err) {
-                if (err.code !== "ENOENT") {
-                    console.error(`File deletion failed for '${attrs.deletePath}':`, err);
-                    return Results.failure("scheme:file", "delete-failed", 500, `The file could not be deleted: ${ErrorDetail.preview(err)}`, {
-                        outcome: "delete_failed",
-                    }, {
-                        path: attrs.deletePath,
-                        stage: "filesystem-delete",
-                    });
-                }
-            }
-            if ("entries" in ctx)
-                await ctx.entries.delete(attrs.deletePath);
-            else {
-                await EntryCrud.deleteEntry({ authority: "", pathname: attrs.deletePath }, core, "file");
-            }
-            await GitMembership.removeCreationRecord(core.db, core.workspaceId, attrs.deletePath);
-            return { status: 200 };
-        }
-        let canonical = attrs.canonical;
+        if (typeof attrs.deletePath === "string")
+            return this.#applyDelete(attrs.deletePath, attrs.baseSig ?? null, core);
+        const canonical = attrs.canonical;
         const relPath = attrs.path;
         const patched = body ?? attrs.patched;
         // {§binary-parity} — a byte write (COPY/MOVE of a binary) carries its bytes here; the disk
@@ -560,51 +530,12 @@ class File extends CoreSchemeAdapterBase {
         if (typeof mimetype !== "string" || mimetype.length === 0) {
             throw new InvalidOperationResultError("The accepted file proposal is missing attrs.mimetype.");
         }
-        const existed = args.attrs.existed === true; // proposal targeted an existing member (edit) vs a fresh create
-        let creationAdmission = null;
-        if (!existed) {
-            // {§file-create-transaction}: approval is a fresh admission boundary. Re-resolve
-            // the physical target so a parent symlink swapped while review was pending cannot
-            // redirect an accepted root-scoped create outside the workspace.
-            const acceptedTarget = await this.#resolveWriteTarget(relPath, core, patchedBytes !== undefined);
-            if (!acceptedTarget.ok) {
-                return Results.failure("scheme:file", acceptedTarget.code, acceptedTarget.status, acceptedTarget.detail, { outcome: "create_refused" }, acceptedTarget.extensions);
-            }
-            if (acceptedTarget.fileExists) {
-                return EditCollision.result(relPath, { outcome: "edit_collision" });
-            }
-            canonical = acceptedTarget.canonical;
-            creationAdmission = acceptedTarget.creationAdmission;
-            if (creationAdmission === null) {
-                throw new InvalidOperationResultError("A revalidated file creation is missing its admission decision.");
-            }
-        }
-        // CAS — the write-side twin of #materializeMember's read-gate (synced_sig === sig). The
-        // proposal was computed against the snapshot (body + baseSig); if disk drifted out-of-band
-        // since propose, the full-blob write would clobber it. Refuse and surface the same neutral
-        // edit collision as an entry compare-and-swap —
-        // the next reconcile narrates disk truth via FsDivergence; the model re-reads + re-proposes.
-        // No clever re-diff, no clobber. {§membership-edit-write-cas}
-        const baseSig = (args.attrs.baseSig ?? null);
-        let currentSig = null;
-        try {
-            const st = await stat(canonical);
-            currentSig = `${st.mtimeMs}:${st.size}`;
-        }
-        catch (err) {
-            if (err.code !== "ENOENT")
-                throw err;
-        }
-        // Edit → CAS on the snapshot signature (a null baseSig is an un-materialized member with no
-        // recorded snapshot — no baseline to guard, so the write proceeds). Create → the proposal
-        // assumed an absent path, so any file present now is the conflict.
-        const conflict = existed ? (baseSig !== null && currentSig !== baseSig) : (currentSig !== null);
-        if (conflict) {
+        const existed = args.attrs.existed === true;
+        const baseline = FileSnapshot.decode(attrs.baseSig ?? null);
+        if (existed && (baseline === null || baseline.hash === null))
             return EditCollision.result(relPath, { outcome: "edit_collision" });
-        }
         let receipt = attrs.editReceipt;
-        const needsOriginal = receipt !== undefined || (body !== undefined && body !== attrs.patched);
-        const original = needsOriginal ? (existed ? await readFile(canonical, "utf8") : "") : null;
+        const original = attrs.original ?? (existed ? null : "");
         if (body !== undefined && body !== attrs.patched) {
             if (original === null) {
                 throw new InvalidOperationResultError("A reviewer-modified file proposal is missing its original content.");
@@ -613,126 +544,149 @@ class File extends CoreSchemeAdapterBase {
                 if (typeof attrs.patched !== "string") {
                     throw new InvalidOperationResultError("The reviewer-modified file proposal is missing its proposed content.");
                 }
-                receipt = editReceipt(original, attrs.patched, [{ marker: { marks: [1, -1] }, body: attrs.patched }], undefined, EntryManifest.toPath("file", "", relPath));
+                receipt = editReceipt(original, attrs.patched, [{ marker: { marks: [1, -1] }, body: attrs.patched }], undefined, EntryManifest.toPath("file", "", relPath, await FileAddress.projectRoot(core)));
             }
-            receipt = reviewerReplacementReceipt(original, patched, receipt, undefined, EntryManifest.toPath("file", "", relPath));
+            receipt = reviewerReplacementReceipt(original, patched, receipt, undefined, EntryManifest.toPath("file", "", relPath, await FileAddress.projectRoot(core)));
         }
         if (receipt !== undefined) {
             const parseIssues = await new DbProjectionCaps(core).parseIssueTransition(existed ? original : null, patched, mimetype);
             receipt = withEditReceiptParseIssues(receipt, parseIssues);
         }
-        try {
-            // A write into a not-yet-existing subtree creates it — an accepted proposal must not
-            // die on a missing parent dir (the fan-out digest: tasks/… write_failed on ENOENT).
-            await mkdir(dirname(canonical), { recursive: true });
-            if (patchedBytes !== undefined) {
-                await writeFile(canonical, Buffer.from(patchedBytes), { flag: existed ? "w" : "wx" });
-            }
-            else {
-                await writeFile(canonical, patched, { encoding: "utf8", flag: existed ? "w" : "wx" });
-            }
-        }
-        catch (err) {
-            if (!existed && err.code === "EEXIST") {
+        return FileSnapshot.serialize(canonical, async () => {
+            const acceptedTarget = await this.#resolveWriteTarget(relPath, core, patchedBytes !== undefined);
+            if (!acceptedTarget.ok)
+                return Results.failure("scheme:file", acceptedTarget.code, acceptedTarget.status, acceptedTarget.detail, {}, acceptedTarget.extensions);
+            if (acceptedTarget.canonical !== canonical || acceptedTarget.fileExists !== existed)
                 return EditCollision.result(relPath, { outcome: "edit_collision" });
+            const creationAdmission = acceptedTarget.creationAdmission;
+            const root = await FileAddress.projectRoot(core);
+            if (root === null)
+                throw new InvalidOperationResultError("An accepted file write has no workspace project root.");
+            const publication = await FilePublication.write(join(root, relPath), canonical, baseline, patchedBytes ?? Buffer.from(patched));
+            if (publication.status === "conflict")
+                return EditCollision.result(relPath, { outcome: "edit_collision" });
+            if (publication.status === "failed") {
+                console.error(`File publication failed for '${relPath}':`, publication.cause);
+                return Results.failure("scheme:file", "write-failed", 500, `${publication.published ? "The file was published, but settlement failed" : "The file was not published"}: ${ErrorDetail.preview(publication.cause)}`, { outcome: "write_failed", ...(publication.published ? { effects: [{ target: relPath, action: existed ? "update" : "create" }] } : {}) }, {
+                    path: relPath,
+                    stage: "filesystem-publication",
+                    published: publication.published,
+                });
             }
-            console.error(`File write failed for '${relPath}':`, err);
-            return Results.failure("scheme:file", "write-failed", 500, `The file could not be written: ${ErrorDetail.preview(err)}`, { outcome: "write_failed" }, {
-                path: relPath,
-                stage: "filesystem-write",
-            });
-        }
-        // Register the exact mimetype resolved at proposal time, then complete the
-        // membership-owned incorporation transaction. No fallible receipt work follows.
-        try {
-            // {§entry-identity-no-null} — file members persist under the reserved
-            // `file` identity; bare-path rendering is a projection of that row.
-            // {§binary-parity} — a binary member registers with empty text content: its bytes live on
-            // disk and READ serves them through byteSource; the next membership reconcile materializes
-            // the facts line and source projection the way a git-tracked binary member gets them.
-            const registerContent = patchedBytes !== undefined ? "" : patched;
-            const write = "entries" in ctx
-                ? await ctx.entries.write(relPath, {
-                    channels: { body: { content: registerContent, mimetype } },
-                })
-                : await EntryCrud.writeEntry({ authority: "", pathname: relPath }, {
+            // Register the exact mimetype resolved at proposal time, then complete the
+            // membership-owned incorporation transaction. No fallible receipt work follows.
+            try {
+                // {§entry-identity-no-null} — file members persist under the reserved
+                // `file` identity; bare-path rendering is a projection of that row.
+                // {§binary-parity} — a binary member registers with empty text content: its bytes live on
+                // disk and READ serves them through byteSource; the next membership reconcile materializes
+                // the facts line and source projection the way a git-tracked binary member gets them.
+                const registerContent = patchedBytes !== undefined ? "" : patched;
+                const write = await EntryCrud.writeEntry({ authority: "", pathname: relPath }, {
                     channels: { body: { content: registerContent, mimetype } },
-                }, core, "file");
-            const { entryId } = write;
-            // Restamp synced_sig to the landed write so the next reconcile recognizes our own
-            // write as the synced state — not an FsDivergence narrated back at the model.
-            if (entryId !== null) {
-                const landed = await stat(canonical);
-                await core.db.crud_set_synced_sig.run({ entry_id: entryId, synced_sig: `${landed.mtimeMs}:${landed.size}` });
-            }
-            if (!existed) {
-                if (entryId === null || creationAdmission === null || !creationAdmission.ok) {
-                    throw new InvalidOperationResultError("A created file is missing its entry or admission decision.");
-                }
-                const root = await loadWorkspaceRoot(core.db, core.workspaceId);
-                if (root === null) {
-                    throw new InvalidOperationResultError("A created file lost its workspace project root.");
+                    attributes: patchedBytes === undefined
+                        ? FileMaterialization.attributes(FileMaterialization.classify(Buffer.byteLength(patched)))
+                        : {},
+                }, core, "file", { syncedSig: JSON.stringify(publication.revision) });
+                const { entryId } = write;
+                if (!existed) {
+                    if (entryId === null || creationAdmission === null || !creationAdmission.ok) {
+                        throw new InvalidOperationResultError("A created file is missing its entry or admission decision.");
+                    }
+                    await GitMembership.incorporateCreation(core.db, core.workspaceId, entryId, relPath, creationAdmission);
                 }
-                await GitMembership.incorporateCreation(core.db, core.workspaceId, entryId, relPath, creationAdmission);
             }
-        }
-        catch (err) {
-            if (!existed) {
-                const rollbackErrors = [];
-                try {
-                    const row = await core.db.crud_find_workspace_entry.get({
-                        workspace_id: core.workspaceId,
-                        scheme: "file",
-                        authority: "",
-                        pathname: relPath,
-                    });
-                    if (row !== undefined)
-                        await core.db.crud_delete_entry.run({ entry_id: row.id });
-                }
-                catch (rollbackCause) {
-                    rollbackErrors.push(rollbackCause);
-                }
-                try {
-                    await rm(canonical);
-                }
-                catch (rollbackCause) {
-                    if (rollbackCause.code !== "ENOENT") {
+            catch (err) {
+                if (!existed) {
+                    const rollbackErrors = [];
+                    try {
+                        const row = await core.db.crud_find_workspace_entry.get({
+                            workspace_id: core.workspaceId,
+                            scheme: "file",
+                            authority: "",
+                            pathname: relPath,
+                        });
+                        if (row !== undefined)
+                            await core.db.crud_delete_entry.run({ entry_id: row.id });
+                    }
+                    catch (rollbackCause) {
                         rollbackErrors.push(rollbackCause);
                     }
-                }
-                if (rollbackErrors.length > 0) {
-                    const rollback = new AggregateError(rollbackErrors, `Creation rollback failed for '${relPath}'.`);
-                    console.error(`File creation failed and rollback was incomplete for '${relPath}':`, err, rollback);
-                    return Results.failure("scheme:file", "creation-rollback-failed", 500, `The file could not be incorporated and rollback was incomplete: ${ErrorDetail.preview(rollback)}`, { outcome: "creation_rollback_failed" }, {
+                    try {
+                        const current = await FileSnapshot.acquire(publication.revision.canonical, null);
+                        if (current === null && await FileSnapshot.observe(publication.revision.canonical) !== null) {
+                            throw new Error("The created path changed during rollback validation; it was preserved.");
+                        }
+                        if (current !== null && !FileSnapshot.matches(publication.revision, current.revision)) {
+                            throw new Error("The created path changed; its replacement was preserved.");
+                        }
+                        if (current !== null)
+                            await rm(publication.revision.canonical);
+                    }
+                    catch (rollbackCause) {
+                        if (rollbackCause.code !== "ENOENT") {
+                            rollbackErrors.push(rollbackCause);
+                        }
+                    }
+                    if (rollbackErrors.length > 0) {
+                        const rollback = new AggregateError(rollbackErrors, `Creation rollback failed for '${relPath}'.`);
+                        console.error(`File creation failed and rollback was incomplete for '${relPath}':`, err, rollback);
+                        return Results.failure("scheme:file", "creation-rollback-failed", 500, `The file could not be incorporated and rollback was incomplete: ${ErrorDetail.preview(rollback)}`, { outcome: "creation_rollback_failed", effects: [{ target: relPath, action: "create" }] }, {
+                            path: relPath,
+                            stage: "creation-rollback",
+                            cause: ErrorDetail.preview(err),
+                            retryable: false,
+                        });
+                    }
+                    console.error(`File creation incorporation failed for '${relPath}':`, err);
+                    return Results.failure("scheme:file", "creation-incorporation-failed", 500, `The file could not be incorporated, so its exclusive creation was rolled back: ${ErrorDetail.preview(err)}`, { outcome: "creation_rolled_back" }, {
                         path: relPath,
-                        stage: "creation-rollback",
-                        cause: ErrorDetail.preview(err),
+                        stage: "membership-incorporation",
                         retryable: false,
                     });
                 }
-                console.error(`File creation incorporation failed for '${relPath}':`, err);
-                return Results.failure("scheme:file", "creation-incorporation-failed", 500, `The file could not be incorporated, so its exclusive creation was rolled back: ${ErrorDetail.preview(err)}`, { outcome: "creation_rolled_back" }, {
+                // An existing-file write has already changed disk. Surface the partial
+                // failure rather than pretending the addressable entry followed it.
+                console.error(`File registration failed for '${relPath}':`, err);
+                return Results.failure("scheme:file", "materialization-failed", 500, `The file was written to disk but could not be registered: ${ErrorDetail.preview(err)}`, { outcome: "materialize_failed", effects: [{ target: relPath, action: "update" }] }, {
                     path: relPath,
-                    stage: "membership-incorporation",
+                    stage: "entry-registration",
                     retryable: false,
                 });
             }
-            // An existing-file write has already changed disk. Surface the partial
-            // failure rather than pretending the addressable entry followed it.
-            console.error(`File registration failed for '${relPath}':`, err);
-            return Results.failure("scheme:file", "materialization-failed", 500, `The file was written to disk but could not be registered: ${ErrorDetail.preview(err)}`, { outcome: "materialize_failed" }, {
-                path: relPath,
-                stage: "entry-registration",
-                retryable: false,
-            });
-        }
-        if (receipt === undefined)
-            return { status: 200 };
-        return {
-            status: 200,
-            editReceipt: receipt,
-            result: { receipt: projectEditReceipt(receipt, 0) },
-        };
+            if (receipt === undefined)
+                return { status: 200 };
+            return {
+                status: 200,
+                editReceipt: receipt,
+                result: { receipt: projectEditReceipt(receipt, 0) },
+            };
+        });
+    }
+    async #applyDelete(pathname, baseSig, core) {
+        const baseline = FileSnapshot.decode(baseSig);
+        if (baseline === null || baseline.hash === null)
+            return EditCollision.result(pathname);
+        const root = await FileAddress.projectRoot(core);
+        if (root === null)
+            throw new InvalidOperationResultError("An accepted file deletion has no workspace project root.");
+        const requested = join(root, pathname);
+        return FileSnapshot.serialize(baseline.canonical, async () => {
+            const current = await FileSnapshot.acquire(requested, null);
+            if (current === null || !FileSnapshot.matches(baseline, current.revision))
+                return EditCollision.result(pathname);
+            let deleted = false;
+            try {
+                await rm(requested);
+                deleted = true;
+                await EntryCrud.deleteEntry({ authority: "", pathname }, core, "file");
+                await GitMembership.removeCreationRecord(core.db, core.workspaceId, pathname);
+                return { status: 200 };
+            }
+            catch (cause) {
+                return Results.failure("scheme:file", "delete-failed", 500, `${deleted ? "The file was deleted, but projection settlement failed" : "The file could not be deleted"}: ${ErrorDetail.preview(cause)}`, { outcome: "delete_failed", ...(deleted ? { effects: [{ target: pathname, action: "delete" }] } : {}) }, { path: pathname, stage: deleted ? "entry-deletion" : "filesystem-delete", deleted });
+            }
+        });
     }
     // deleteEntry — the KILL / MOVE-source counterpart of writeEntry. Deleting a host file is
     // DESTRUCTIVE, so it PROPOSES for review (202), exactly as edit() does — never an ungated unlink.
@@ -740,21 +694,32 @@ class File extends CoreSchemeAdapterBase {
     // disk is never probed or touched. applyResolution unlinks + deregisters on accept.
     async deleteEntry(pathname, ctx) {
         const core = this.coreContext(ctx);
-        const root = await loadWorkspaceRoot(core.db, core.workspaceId);
+        const root = await FileAddress.projectRoot(core);
         if (root === null) {
             return Results.failure("scheme:file", "project-root-required", 400, "File deletion requires a workspace project root.", {}, { retryable: false });
         }
         const rel = Namespace.canonicalize(pathname, root);
         if (rel === null)
-            return Results.failure("scheme:file", "entry-not-found", 404, missDetail("file", pathname), {}, missExtensions("file", pathname));
-        const member = await core.db.crud_find_workspace_entry.get({ workspace_id: core.workspaceId, scheme: "file", authority: "", pathname: rel });
+            return Results.failure("scheme:file", "entry-not-found", 404, missDetail("file", pathname), {}, missExtensions("file", entryAddress("file", "", pathname, root)));
+        const member = await core.db.crud_get_member_sig.get({ workspace_id: core.workspaceId, scheme: "file", authority: "", pathname: rel });
         if (member === undefined && !rel.startsWith("../") && (await _a.#occupant(root, rel))?.isDirectory() === true) {
-            const { code, detail, extensions } = _a.#directoryFacts(rel, "KILL");
+            const { code, detail, extensions } = _a.#directoryFacts(rel, "KILL", root);
             return Results.failure("scheme:file", code, 404, detail, {}, extensions);
         }
         if (member === undefined)
-            return Results.failure("scheme:file", "entry-not-found", 404, missDetail("file", rel), {}, missExtensions("file", rel));
-        return { status: 202, attrs: { deletePath: rel } };
+            return Results.failure("scheme:file", "entry-not-found", 404, missDetail("file", rel), {}, missExtensions("file", entryAddress("file", "", rel, root)));
+        const selectedRevision = SchemeCtxImpl.fileRevisionOf(ctx);
+        if (selectedRevision !== undefined && selectedRevision !== member.synced_sig)
+            return EditCollision.result(rel);
+        const baseline = FileSnapshot.decode(member.synced_sig);
+        if (baseline === null)
+            return EditCollision.result(rel);
+        // {§file-delete-revision}: an oversized marker has no body; deletion still captures exact bytes.
+        const acquired = baseline.hash === null ? await FileSnapshot.acquire(join(root, rel), null) : null;
+        if (baseline.hash === null && (acquired === null || !FileSnapshot.matches(baseline, acquired.revision))) {
+            return EditCollision.result(rel);
+        }
+        return { status: 202, attrs: { deletePath: rel, baseSig: acquired === null ? member.synced_sig : JSON.stringify(acquired.revision) } };
     }
     async deleteChannel(pathname, channel, ctx) {
         if (channel !== _a.manifest.defaultChannel) {