@plurnk/plurnk-service 1.3.12 → 1.5.0

package/dist/core/git-membership.js

@@ -1,9 +1,9 @@
-// SPEC §membership D4 — git-ls-files workspace membership. §membership-git-membership
+// SPEC {§membership} D4 — git-ls-files workspace membership. {§membership-git-membership}
 //
 // When a workspace's `project_root` is a git working tree, the git-tracked
 // files (`git ls-files`) are workspace MEMBERS without any explicit client
 // `pick`. This module resolves that membership and (when token accounting is
-// available) materializes active members' disk content into a body channel,
+// available) materializes active members' model-readable representation into a body channel,
 // so they appear in the entry catalog (FIND-served) and are READ-able.
 //
 // Decisions realized here:
@@ -17,25 +17,54 @@
 //        `(ls-files ∪ pick) − hide`; view is enforced at the File edit gate.
 //   D5 — coverage is exhaustive, work is change-gated: every member is stat'd each
 //        turn, but only one whose mtime:size signature changed is re-read,
-//        re-tokenized, and rewritten; an unchanged member is a no-op, and the EMI
-//        divergence rides that same pass. {§membership-change-gated-sync}
+//        re-tokenized, and rewritten. A binary source also compares the installed
+//        projection identity without reacquiring bytes. EMI divergence rides the
+//        same pass. {§membership-change-gated-sync}
 //
-// git resolution is in-process by default (GitIso / isomorphic-git, #461) — portable,
-// sandbox-safe, hermetic by construction. PLURNK_SERVICE_GIT_NATIVE=1 routes to system git
-// (subprocess + hermeticGitEnv, AbortSignal-respecting) — the in-process membership pass
-// measures ~8x native (~130ms at 20k files), so a large-repo host can buy the hot path back.
+// Git resolution uses native Git by default (subprocess + hermeticGitEnv,
+// AbortSignal-respecting). PLURNK_SERVICE_GIT_ISO=1 explicitly selects the
+// slower in-process portability backend for a deployment that cannot spawn Git.
 import { execFile } from "node:child_process";
-import { hermeticGitEnv } from "./git-env.js";
+import { gitOutputMaxBytes, hermeticGitEnv, isomorphicGitEnabled } from "./git-env.js";
 import GitIso from "./git-iso.js";
 import { promisify } from "node:util";
 import { readFile, glob, stat } from "node:fs/promises";
-import { resolve, relative, join, matchesGlob } from "node:path";
+import { resolve, join, matchesGlob } from "node:path";
+import { MimetypeInputLimitError, } from "@plurnk/plurnk-mimetypes";
 import { MimetypeBinary } from "../content/index.js";
 import Owner from "./Owner.js";
 import EntryCrud from "../schemes/_entry-crud.js";
 import WorkspaceSettings from "./workspace-settings.js";
-// Feature-flag convention: `=== "1"` exactly. Default (unset/0) = the in-process GitIso backend.
-const nativeGit = () => process.env.PLURNK_SERVICE_GIT_NATIVE === "1";
+import Namespace from "./namespace.js";
+const ABSENT_SIG = "absent";
+const sourceProjectionFrom = (encoded) => {
+    const attributes = JSON.parse(encoded);
+    if (attributes === null || typeof attributes !== "object" || Array.isArray(attributes)) {
+        throw new TypeError("GitMembership: entry attributes must be a JSON object");
+    }
+    const candidate = attributes.sourceProjection;
+    if (candidate === undefined)
+        return null;
+    if (candidate === null || typeof candidate !== "object" || Array.isArray(candidate)) {
+        throw new TypeError("GitMembership: sourceProjection must be a JSON object");
+    }
+    const projection = candidate;
+    if (typeof projection.mimetype !== "string"
+        || projection.mimetype.length === 0
+        || typeof projection.identity !== "string"
+        || projection.identity.length === 0
+        || !["projected", "unavailable", "input-limit"].includes(projection.disposition ?? "")) {
+        throw new TypeError("GitMembership: sourceProjection metadata is malformed");
+    }
+    const hasLimit = Number.isSafeInteger(projection.maximumBytes)
+        && (projection.maximumBytes ?? 0) > 0
+        && Number.isSafeInteger(projection.observedBytes)
+        && (projection.observedBytes ?? 0) > (projection.maximumBytes ?? 0);
+    if ((projection.disposition === "input-limit") !== hasLimit) {
+        throw new TypeError("GitMembership: sourceProjection input-limit evidence is malformed");
+    }
+    return projection;
+};
 export default class GitMembership {
     // Workspace creation starts a background warm while the first model turn
     // performs its own eager membership refresh. Both are legitimate callers,
@@ -46,7 +75,8 @@ export default class GitMembership {
     static #execFileP = promisify(execFile);
     // {§fs-write-surface} — the blind-write closure git half: would git ADMIT a create at
     // key (untracked-not-ignored)? check-ignore exit 0 = ignored (refuse), 1 = clean
-    // (admit via auto-add), anything else (128, no repo) = git grants nothing here.
+    // (automatic membership admission, never `git add`), anything else (128, no
+    // repo) = git grants nothing here.
     static async wouldGitAdmit(root, key, signal) {
         try {
             await GitMembership.#execFileP("git", ["check-ignore", "-q", "--", key], { cwd: root, signal, env: hermeticGitEnv() });
@@ -56,21 +86,33 @@ export default class GitMembership {
             return err.code === 1;
         }
     }
+    static async stageFile(root, key, signal) {
+        try {
+            if (isomorphicGitEnabled()) {
+                await GitIso.add(root, key);
+            }
+            else {
+                await GitMembership.#execFileP("git", ["add", "--", key], { cwd: root, signal, env: hermeticGitEnv() });
+            }
+        }
+        catch {
+            // Ignore staging errors if root is not a git repo
+        }
+    }
     // project_root for a workspace. NULL = headless (no membership). Read once per
     // resolution; the File scheme reads the same column for its own root.
     static async #loadWorkspaceRoot(db, workspaceId) {
         const row = await db.envelope_get_workspace.get({ id: workspaceId });
         return row?.project_root ?? null;
     }
-    // Tracked files of one repo, workspace-relative — GitIso.trackedFiles (walk STAGE, blob
-    // entries only) or `git ls-files --stage -z` under the native flag. Either way gitlinks
-    // are filtered: a submodule (mode 160000, a commit pointer — a directory on disk, not a
-    // file) is a separate declared repo, never a member of its superproject. Empty → [].
+    // Tracked files of one repo, workspace-relative - GitIso.trackedFiles (walk STAGE, blob
+    // entries only) or native `git ls-files --stage -z`. Either way gitlinks
+    // are filtered: a submodule is a repository boundary, not a file member. Empty → [].
     static async #gitTrackedFiles(root, signal, cache) {
-        if (!nativeGit())
+        if (isomorphicGitEnabled())
             return GitIso.trackedFiles(root, cache);
         // NUL-delimited so paths with spaces/newlines survive.
-        const { stdout } = await GitMembership.#execFileP("git", ["ls-files", "--stage", "-z"], { cwd: root, signal, maxBuffer: 64 * 1024 * 1024, env: hermeticGitEnv() });
+        const { stdout } = await GitMembership.#execFileP("git", ["ls-files", "--stage", "-z"], { cwd: root, signal, maxBuffer: gitOutputMaxBytes(), env: hermeticGitEnv() });
         const files = [];
         for (const entry of stdout.split("\0")) {
             if (entry.length === 0)
@@ -84,22 +126,19 @@ export default class GitMembership {
         }
         return files;
     }
-    // Untracked-but-not-ignored files of one repo (SPEC §membership-auto-add) —
-    // GitIso.untrackedFiles (the differential-gated pruning ignore-walk) or `git ls-files
-    // --others --exclude-standard -z` under the native flag. A model-created file is a repo
+    // Untracked-but-not-ignored members of one repo ({§membership-auto-add}) —
+    // GitIso.untrackedFiles (the differential-gated pruning ignore-walk) or native `git ls-files
+    // --others --exclude-standard -z`. A model-created file is a repo
     // member the moment it exists — no git-stage required — while `.gitignore` still filters it.
     static async #gitUntrackedFiles(root, signal, cache) {
-        if (!nativeGit())
+        if (isomorphicGitEnabled())
             return GitIso.untrackedFiles(root, cache);
-        const { stdout } = await GitMembership.#execFileP("git", ["ls-files", "--others", "--exclude-standard", "-z"], { cwd: root, signal, maxBuffer: 64 * 1024 * 1024, env: hermeticGitEnv() });
+        const { stdout } = await GitMembership.#execFileP("git", ["ls-files", "--others", "--exclude-standard", "-z"], { cwd: root, signal, maxBuffer: gitOutputMaxBytes(), env: hermeticGitEnv() });
         return stdout.split("\0").filter((e) => e.length > 0);
     }
-    // Resolve a declared repo folder to its git toplevel (the repo root containing it), or
-    // null if it isn't inside a git tree. GitIso.repoToplevel (findRoot) or `rev-parse
-    // --show-toplevel` under the native flag — both handle plain repos, linked worktrees
-    // (`.git` is a gitdir: file), and submodules alike.
+    // Resolve a directory to the containing Git repository, or null when absent.
     static async #repoToplevel(dir, signal) {
-        if (!nativeGit())
+        if (isomorphicGitEnabled())
             return GitIso.repoToplevel(dir);
         try {
             const { stdout } = await GitMembership.#execFileP("git", ["rev-parse", "--show-toplevel"], { cwd: dir, signal, env: hermeticGitEnv() });
@@ -109,84 +148,50 @@ export default class GitMembership {
             return null; // not a git tree (or the dir is gone) — contributes nothing
         }
     }
-    // The forest (SPEC §membership, §membership-forest): union every declared repo's MEMBERS —
-    // tracked files PLUS untracked-but-not-ignored ones (§membership-auto-add) — each
-    // path-prefixed by the repo's location relative to the workspace root (empty prefix when
-    // the repo IS the root). Repos that don't resolve are skipped.
-    static async #forestMembers(root, repoDirs, signal) {
-        // Resolve every declared entry to its git toplevel, deduped: a glob (`*`) and an
-        // explicit declaration can name the same repo, and resolving one repo twice is
-        // wasted git work. {§membership-forest}
-        const repoRoots = new Set();
-        for (const dir of repoDirs) {
-            for (const candidate of await GitMembership.#expandRepoDirs(root, dir, signal)) {
-                const repoRoot = await GitMembership.#repoToplevel(resolve(root, candidate), signal);
-                if (repoRoot !== null)
-                    repoRoots.add(repoRoot);
-            }
-        }
+    // A workspace owns exactly the repository containing project_root. Packages and
+    // projects inside that repository share its Git state; unrelated repositories
+    // belong to unrelated workspaces.
+    static async projectRepository(db, workspaceId, signal) {
+        const root = await GitMembership.#loadWorkspaceRoot(db, workspaceId);
+        if (root === null || process.env.PLURNK_SERVICE_GIT_ALLOWED !== "1")
+            return null;
+        if ((await WorkspaceSettings.read(db, workspaceId)).git === false)
+            return null;
+        return GitMembership.#repoToplevel(root, signal);
+    }
+    static async #projectMembers(root, repoRoot, signal) {
         const members = new Set();
-        // One iso-git cache per PASS: pack/index parses are reused across this resolve's repos
-        // and reads, then discarded — never carried across turns, so a rewritten index or
-        // repacked store can't serve stale.
         const cache = {};
-        for (const repoRoot of repoRoots) {
-            // project_root is no boundary — only the relative-address base. EVERY member is
-            // addressed relative to the root, a repo outside it included (a `..`-prefixed
-            // path) — so the universal `join(root, pathname)` disk-resolver works unchanged;
-            // an absolute pathname would nest UNDER root and never materialize. {§membership-overlay-repo}
-            const prefix = relative(root, repoRoot);
-            const tracked = await GitMembership.#gitTrackedFiles(repoRoot, signal, cache);
-            const untracked = await GitMembership.#gitUntrackedFiles(repoRoot, signal, cache);
-            for (const f of [...tracked, ...untracked]) {
-                members.add(join(prefix, f));
-            }
+        const tracked = await GitMembership.#gitTrackedFiles(repoRoot, signal, cache);
+        const untracked = await GitMembership.#gitUntrackedFiles(repoRoot, signal, cache);
+        for (const file of [...tracked, ...untracked]) {
+            members.add(Namespace.fromRepositoryPath(file, root, repoRoot));
         }
         return [...members];
     }
-    // A declared repo entry → the candidate directories it names. A literal path (no glob
-    // magic) passes through untouched — preserving the "declare a repo ANYWHERE, including
-    // OUTSIDE the root via `..` or an absolute path" contract that glob can't address upward.
-    // A glob pattern is directory-expanded under the root via node:fs glob — `*` matches each
-    // immediate child (one level), `**` recurses — dropping file matches, since only a
-    // directory can be a repo; #repoToplevel then filters the non-git matches. {§membership-overlay-repo}
-    static async #expandRepoDirs(root, dir, signal) {
-        if (!GitMembership.#isGlobPattern(dir))
-            return [dir];
-        const dirs = [];
-        for await (const rel of glob(dir, { cwd: root })) {
-            if (signal?.aborted)
-                return dirs;
-            try {
-                if ((await stat(resolve(root, rel))).isDirectory())
-                    dirs.push(rel);
-            }
-            catch {
-                // raced away between glob and stat — not a candidate
-            }
-        }
-        return dirs;
-    }
-    // Does this declared repo entry carry glob magic (directory-expand it), or is it a
-    // literal path (declared as-is)? The metacharacters node:fs glob honors.
-    static #isGlobPattern(s) {
-        return /[*?[\]{}]/.test(s);
-    }
-    // Detect a tracked file's mimetype (mirrors File.detectFileMimetype): route
-    // through the Mimetypes service when present, normalizing the auto-text result
-    // to the text primitive (plurnk-service never auto-derives text/plain). No
-    // service → text primitive.
+    // Detect a tracked file's mimetype (mirrors File.detectFileMimetype) through
+    // the configured registry, normalizing auto-derived text/plain to the text
+    // primitive.
     static async #detectMimetype(canonical, mimetypes) {
-        if (mimetypes !== undefined) {
-            const detected = await mimetypes.detect({ path: canonical });
-            return MimetypeBinary.normalizeAutoTextMimetype(detected);
+        if (mimetypes === undefined)
+            throw new Error("GitMembership: configured mimetype registry is required");
+        const detected = await mimetypes.detect({ path: canonical });
+        return MimetypeBinary.normalizeAutoTextMimetype(detected);
+    }
+    static #projectionIdentity(mimetype, mimetypes, identities) {
+        if (mimetypes === undefined)
+            throw new Error("GitMembership: configured mimetype registry is required");
+        let identity = identities.get(mimetype);
+        if (identity === undefined) {
+            identity = mimetypes.projectionIdentity(mimetype);
+            identities.set(mimetype, identity);
         }
-        return MimetypeBinary.TEXT_PRIMITIVE_MIMETYPE;
+        return identity;
     }
     // Shared overlay inputs — the candidate sets (git tracked+untracked union, pick scan) and
     // the overlay globs, before composition. Single-sources the (git ∪ pick) derivation + the
     // glob sets for resolveGitMembership (compose + reconcile) and resolveMembershipEffects
-    // (derive per-file effect for clients, #243). Headless (no project_root) → null.
+    // (derive per-file effect for clients, {§membership-resolved-effects}). Headless → null.
     static async #resolveOverlayInputs(db, workspaceId, signal) {
         const root = await GitMembership.#loadWorkspaceRoot(db, workspaceId);
         if (root === null)
@@ -195,38 +200,39 @@ export default class GitMembership {
         const hideGlobs = constraints.filter((c) => c.effect === "hide").map((c) => c.glob);
         const pickGlobs = constraints.filter((c) => c.effect === "pick").map((c) => c.glob);
         const viewGlobs = constraints.filter((c) => c.effect === "view").map((c) => c.glob);
-        // git substrate — the union of the workspace's DECLARED repos' MEMBERS: tracked files
-        // plus untracked-but-not-ignored ones (§membership-auto-add). PLURNK_SERVICE_GIT_ALLOWED=0 is
-        // the hard ceiling (deny all git membership); PLURNK_SERVICE_GIT_AUTO=1 declares project_root
-        // as an implicit repo. Empty when git is denied or no declared repo resolves, so
-        // `pick` is then the sole source. No early-return on non-git.
-        const repoDirs = constraints.filter((c) => c.effect === "repo").map((c) => c.glob); // a declared repo's ls-files join membership, path-prefixed — §membership-overlay-repo
-        if (process.env.PLURNK_SERVICE_GIT_AUTO === "1")
-            repoDirs.push(root); // ALLOWED ceiling gates the AUTO default — §membership-git-flags
-        // #232 — git:false is a workspace-level tighten of the env ALLOWED ceiling (env AND workspace).
+        // The repository containing project_root is the sole Git substrate.
+        // PLURNK_SERVICE_GIT_ALLOWED=0 is the hard service ceiling and
+        // PLURNK_SERVICE_GIT_AUTO=0 disables automatic Git membership.
+        // {§operator-config-workspace-git} — git:false tightens the env ALLOWED ceiling.
         const workspaceGit = (await WorkspaceSettings.read(db, workspaceId)).git;
-        const gitMembers = process.env.PLURNK_SERVICE_GIT_ALLOWED === "1" && workspaceGit !== false
-            ? await GitMembership.#forestMembers(root, repoDirs, signal)
-            : [];
+        let gitMembers = [];
+        if (process.env.PLURNK_SERVICE_GIT_ALLOWED === "1"
+            && process.env.PLURNK_SERVICE_GIT_AUTO === "1"
+            && workspaceGit !== false) {
+            const repository = await GitMembership.#repoToplevel(root, signal);
+            if (repository !== null) {
+                gitMembers = await GitMembership.#projectMembers(root, repository, signal);
+            }
+        }
         // `pick` overlay — a targeted, client-dictated scan for untracked matches
         // (node:fs glob over the client's pattern, never a blind walk).
-        const picked = pickGlobs.length === 0 ? [] : await GitMembership.#scanPickMembers(root, pickGlobs, signal); // §membership-overlay-pick
+        const picked = pickGlobs.length === 0 ? [] : await GitMembership.#scanPickMembers(root, pickGlobs, signal); // {§membership-overlay-pick}
         return { root, gitMembers, picked, hideGlobs, viewGlobs };
     }
     // Resolve a workspace's file membership: the desired set is (git ls-files ∪ pick
-    // globs) − hide globs (SPEC §membership overlay), reconciled against the registered
+    // globs) − hide globs (SPEC {§membership} overlay), reconciled against the registered
     // overlay-owned members so entries == members. Channel-less rows — disk is the
     // truth (D3); the row is the membership marker File.read gates on. Returns the
     // desired pathnames so the caller can materialize them through writeEntry.
     //
     // signal-respecting: git shell-outs + the pick scan honor `signal`. Headless
     // (no project_root) yields nothing; a non-git root with pick-globs still resolves.
-    static async resolveGitMembership(db, workspaceId, signal) {
+    static async #reconcileGitMembership(db, workspaceId, signal) {
         const inputs = await GitMembership.#resolveOverlayInputs(db, workspaceId, signal);
         if (inputs === null)
-            return []; // headless — no disk surface to resolve
+            return { members: [], removed: [] }; // headless — no disk surface to resolve
         const { gitMembers: members, picked, hideGlobs } = inputs;
-        // Compose: (git ∪ pick) − hide (§membership-overlay-hide), tracking origin for reconciliation — a path
+        // Compose: (git ∪ pick) − hide ({§membership-overlay-hide}), tracking origin for reconciliation — a path
         // in `members` is 'git', a pick-only match is 'constraint'.
         const memberSet = new Set(members);
         const passesHide = (p) => hideGlobs.length === 0 || !hideGlobs.some((g) => matchesGlob(p, g));
@@ -237,6 +243,7 @@ export default class GitMembership {
         // so they match the parser's pathname the shared read helper queries by.
         const desired = [...desiredGit, ...desiredPick]; // bare canon keys ({§fs-canonical-name}) — ls-files output IS the canon
         const desiredSet = new Set(desired);
+        const candidateSet = new Set([...members, ...picked]);
         // Reconcile so entries == members (the constitutive invariant): register the
         // desired with their origin, then un-register any overlay-owned member ('git'
         // or 'constraint') no longer desired — untracked, unmatched, or newly hidden.
@@ -249,18 +256,43 @@ export default class GitMembership {
             await db.crud_register_workspace_member.get({ workspace_id: workspaceId, owner_id: commonsId, scheme: "file", pathname, membership_origin: "constraint" });
         }
         const registered = await db.crud_list_reconcilable_members.all({ workspace_id: workspaceId });
+        const removed = [];
         for (const m of registered) {
             if (!desiredSet.has(m.pathname)) {
+                // A path that left Git/pick membership also left disk truth (for
+                // example an untracked deletion or staged rename). A hide overlay
+                // is policy, not a filesystem occurrence, and is therefore silent.
+                if (!candidateSet.has(m.pathname)) {
+                    const prior = await db.ops_read_channel.get({
+                        workspace_id: workspaceId,
+                        owner_id: commonsId,
+                        scheme: "file",
+                        pathname: m.pathname,
+                        channel: "body",
+                    });
+                    if (prior !== undefined) {
+                        removed.push({
+                            pathname: m.pathname,
+                            entryId: m.id,
+                            channel: "body",
+                            before: prior.content,
+                            after: "",
+                        });
+                    }
+                }
                 await db.crud_delete_entry.run({ entry_id: m.id });
             }
         }
-        return desired;
+        return { members: desired, removed };
     }
-    // Resolve each candidate's membership EFFECT without mutating — a read for clients (#243,
-    // plurnk.nvim gutter signs): the same (git ∪ pick) / hide / view resolution resolveGitMembership
+    static async resolveGitMembership(db, workspaceId, signal) {
+        return (await GitMembership.#reconcileGitMembership(db, workspaceId, signal)).members;
+    }
+    // Resolve each candidate's membership effect without mutating — a read for clients
+    // ({§membership-resolved-effects}): the same (git ∪ pick) / hide / view resolution resolveGitMembership
     // composes, surfaced per-file so a client signs member/view/hidden with ZERO glob-matching of
     // its own. `members` are (git ∪ pick) − hide, each tagged `view` (read-only, refused at the
-    // File edit gate §membership-overlay-view) or plain `member`; `hidden` are candidates a `hide`
+    // File edit gate {§membership-overlay-view}) or plain `member`; `hidden` are candidates a `hide`
     // glob excludes (project files absent from the manifest). Paths namespace-absolute, matching
     // the manifest + storage. Headless → empty. {§membership-resolved-effects}
     static async resolveMembershipEffects(db, workspaceId, signal) {
@@ -285,7 +317,7 @@ export default class GitMembership {
         hidden.sort();
         return { members, hidden };
     }
-    // Targeted client-dictated scan (SPEC §membership `pick`) — enumerate disk files
+    // Targeted client-dictated scan (SPEC {§membership} `pick`) — enumerate disk files
     // matching the client's pick-globs via node:fs glob (the pattern bounds the
     // traversal; never a blind fs-walk). Files only — directories aren't members.
     // Workspace-relative paths, the same shape as git ls-files.
@@ -306,18 +338,22 @@ export default class GitMembership {
         }
         return [...matches];
     }
-    // Materialize a member's disk content into a body channel via writeEntry (the
+    // Materialize a member's model-readable snapshot into a body channel via writeEntry (the
     // entry-write paradigm) — so it appears in the manifest catalog and is READ-able
-    // (D4/D5). Change-gated: a member whose mtime:size signature is unchanged since its
-    // last sync is a no-op (the stat-gate below) — re-read + rewrite only on change.
-    // Binary members materialize as an EMPTY body
-    // channel stamped with their binary mimetype (#186 — visible in the manifest
-    // and READ-415 via the one isBinaryMimetype gate, not a 404 ghost).
-    // Missing-on-disk (tracked but deleted in the working tree) is
-    // skipped — membership stands, no channel.
-    static async #materializeMember(pathname, root, ctx) {
+    // (D4/D5). Change-gated: text changes with mtime:size; binary projections also
+    // change when their opaque reader identity changes. A binary source persists
+    // only derived Unicode when its installed handler provides it, otherwise an
+    // empty typed marker ({§membership-source-projection}).
+    // A tracked path missing on disk retains membership but loses its stale
+    // readable channels; its explicit absent signature makes a later
+    // reappearance another observable divergence.
+    static async #materializeMember(pathname, root, ctx, identities) {
         const canonical = join(root, pathname); // pathname is namespace-absolute (`/src/foo.ts`); join roots it at the workspace
-        // SPEC §membership-change-gated-sync — the cheap detect is a stat (mtime:size),
+        const commonsId = await Owner.commonsId(ctx.db, ctx.workspaceId);
+        const known = await ctx.db.crud_get_member_sig.get({
+            workspace_id: ctx.workspaceId, owner_id: commonsId, scheme: "file", pathname,
+        });
+        // SPEC {§membership-change-gated-sync} — the cheap detect is a stat (mtime:size),
         // never a content read: a member whose signature matches its last sync is a
         // no-op (not re-read, re-tokenized, or rewritten). Coverage stays exhaustive
         // (every member is stat'd); work is proportional to change.
@@ -332,24 +368,39 @@ export default class GitMembership {
             sig = `${st.mtimeMs}:${st.size}`;
         }
         catch (err) {
-            if (err.code === "ENOENT")
-                return null;
+            if (err.code === "ENOENT") {
+                if (known === undefined || known.synced_sig === ABSENT_SIG)
+                    return null;
+                const prior = await ctx.db.ops_read_channel.get({
+                    workspace_id: ctx.workspaceId,
+                    owner_id: commonsId,
+                    scheme: "file",
+                    pathname,
+                    channel: "body",
+                });
+                await ctx.db.crud_delete_channels.run({ entry_id: known.id });
+                await ctx.db.crud_mark_member_absent.run({ entry_id: known.id });
+                return prior === undefined ? null : {
+                    pathname,
+                    entryId: known.id,
+                    channel: "body",
+                    before: prior.content,
+                    after: "",
+                };
+            }
             throw err;
         }
-        const known = await ctx.db.crud_get_member_sig.get({
-            workspace_id: ctx.workspaceId, owner_id: await Owner.commonsId(ctx.db, ctx.workspaceId), scheme: "file", pathname,
-        });
-        if (known !== undefined && known.synced_sig === sig)
-            return null; // unchanged — the change-gate
+        if (known !== undefined && known.synced_sig === sig) {
+            const sourceProjection = sourceProjectionFrom(known.attributes);
+            if (sourceProjection === null)
+                return null;
+            const currentIdentity = await GitMembership.#projectionIdentity(sourceProjection.mimetype, ctx.mimetypes, identities);
+            if (currentIdentity === sourceProjection.identity)
+                return null;
+        }
         const mimetype = await GitMembership.#detectMimetype(canonical, ctx.mimetypes);
-        if (MimetypeBinary.isBinaryMimetype(mimetype)) {
-            // Empty body channel stamped with the real binary mimetype — a first-
-            // class entry that READ-415s through readWorkspaceEntry's isBinaryMimetype
-            // gate (#186), not a channel-less row that would read as 404.
-            const r = await EntryCrud.writeEntry(pathname, { channels: { body: { content: "", mimetype } }, tags: [] }, ctx, "file");
-            if (r.entryId !== null)
-                await ctx.db.crud_set_synced_sig.run({ entry_id: r.entryId, synced_sig: sig });
-            return null; // binary bodies are empty markers — no text divergence to narrate
+        if (await MimetypeBinary.isBinaryMimetype(mimetype, ctx.mimetypes)) {
+            return GitMembership.#materializeBinary(pathname, { path: canonical }, mimetype, sig, known?.synced_sig !== sig, known?.synced_sig === ABSENT_SIG, ctx, identities);
         }
         let buf;
         try {
@@ -360,34 +411,96 @@ export default class GitMembership {
                 return null;
             throw err;
         }
-        // §membership-binary-sniff (#320) — the extension map can lie (.wasm fell through to
+        // {§membership-binary-sniff} — the extension map can lie (.wasm fell through to
         // the markdown DEFAULT and a 3.3MB blob entered the corpus as prose, three copies,
         // ~10M tokens). NUL bytes in the head are binary truth regardless of the label:
-        // re-stamp octet-stream and take the binary arm (empty body, READ-415, never
-        // FTS'd/embedded/tokenized as text).
+        // re-stamp octet-stream and take the same bounded projection-or-marker arm.
         if (buf.subarray(0, 8192).includes(0)) {
-            const r = await EntryCrud.writeEntry(pathname, { channels: { body: { content: "", mimetype: "application/octet-stream" } }, tags: [] }, ctx, "file");
-            if (r.entryId !== null)
-                await ctx.db.crud_set_synced_sig.run({ entry_id: r.entryId, synced_sig: sig });
-            return null;
+            return GitMembership.#materializeBinary(pathname, { content: buf, hint: "application/octet-stream" }, "application/octet-stream", sig, known?.synced_sig !== sig, known?.synced_sig === ABSENT_SIG, ctx, identities);
         }
         const content = buf.toString("utf8");
-        // §env-delta — capture an out-of-band disk change BEFORE the refresh overwrites
-        // the entry: an existing body channel whose content differs from disk is an
-        // ambient divergence (D5). writeEntry then refreshes the entry to disk truth.
+        // {§env-delta-filesystem-narration} — capture the prior snapshot before
+        // materialization replaces it, then journal the resulting net span.
         const prior = await ctx.db.ops_read_channel.get({
-            workspace_id: ctx.workspaceId, owner_id: await Owner.commonsId(ctx.db, ctx.workspaceId), scheme: "file", pathname, channel: "body",
+            workspace_id: ctx.workspaceId, owner_id: commonsId, scheme: "file", pathname, channel: "body",
         });
-        const result = await EntryCrud.writeEntry(pathname, { channels: { body: { content, mimetype } }, tags: [] }, ctx, "file");
+        const result = await EntryCrud.writeEntry(pathname, { channels: { body: { content, mimetype } }, tags: [], attributes: {} }, ctx, "file");
         if (result.entryId !== null)
             await ctx.db.crud_set_synced_sig.run({ entry_id: result.entryId, synced_sig: sig });
-        if (prior !== undefined && prior.content !== content && result.entryId !== null) {
-            return { pathname, scheme: "file", entryId: result.entryId, channel: "body", before: prior.content, after: content };
+        const changed = prior !== undefined && prior.content !== content;
+        if ((changed || known?.synced_sig === ABSENT_SIG) && result.entryId !== null) {
+            return { pathname, entryId: result.entryId, channel: "body", before: prior?.content ?? "", after: content };
+        }
+        return null;
+    }
+    static async #materializeBinary(pathname, input, mimetype, sig, diskChanged, previouslyAbsent, ctx, identities) {
+        const mimetypes = ctx.mimetypes;
+        if (mimetypes === undefined)
+            throw new Error("GitMembership: configured mimetype registry is required");
+        let content = "";
+        let outputMimetype = mimetype;
+        let metadata;
+        try {
+            const projected = await mimetypes.projectReadable(input);
+            if (projected === null) {
+                metadata = {
+                    mimetype,
+                    identity: await GitMembership.#projectionIdentity(mimetype, mimetypes, identities),
+                    disposition: "unavailable",
+                };
+            }
+            else {
+                content = projected.content;
+                outputMimetype = "text/markdown";
+                metadata = {
+                    mimetype: projected.sourceMimetype,
+                    identity: projected.projectionIdentity,
+                    disposition: "projected",
+                };
+            }
+        }
+        catch (cause) {
+            if (!(cause instanceof MimetypeInputLimitError))
+                throw cause;
+            metadata = {
+                mimetype,
+                identity: await GitMembership.#projectionIdentity(mimetype, mimetypes, identities),
+                disposition: "input-limit",
+                maximumBytes: cause.maximumBytes,
+                observedBytes: cause.observedBytes,
+            };
+        }
+        const prior = diskChanged && metadata.disposition === "projected"
+            ? await ctx.db.ops_read_channel.get({
+                workspace_id: ctx.workspaceId,
+                owner_id: await Owner.commonsId(ctx.db, ctx.workspaceId),
+                scheme: "file",
+                pathname,
+                channel: "body",
+            })
+            : undefined;
+        const result = await EntryCrud.writeEntry(pathname, {
+            channels: { body: { content, mimetype: outputMimetype } },
+            tags: [],
+            attributes: { sourceProjection: metadata },
+        }, ctx, "file");
+        if (result.entryId !== null) {
+            await ctx.db.crud_set_synced_sig.run({ entry_id: result.entryId, synced_sig: sig });
+        }
+        const changed = prior !== undefined && prior.content !== content;
+        if ((changed || previouslyAbsent) && result.entryId !== null) {
+            return {
+                pathname,
+                entryId: result.entryId,
+                channel: "body",
+                before: prior?.content ?? "",
+                after: content,
+            };
         }
         return null;
     }
     // Full membership + materialization pass for a worker. Registers git members,
-    // then materializes each active (on-disk, non-binary) member as an entry
+    // then materializes each active on-disk member as an entry
     // through writeEntry. Called at packet-composition time (Engine.runTurn) per
     // D5. No-ops on headless / non-git workspaces.
     static async indexGitMembership(ctx) {
@@ -411,10 +524,11 @@ export default class GitMembership {
         const root = await GitMembership.#loadWorkspaceRoot(ctx.db, ctx.workspaceId);
         if (root === null)
             return [];
-        const tracked = await GitMembership.resolveGitMembership(ctx.db, ctx.workspaceId, ctx.signal);
-        const divergences = [];
-        for (const pathname of tracked) {
-            const divergence = await GitMembership.#materializeMember(pathname, root, ctx);
+        const resolution = await GitMembership.#reconcileGitMembership(ctx.db, ctx.workspaceId, ctx.signal);
+        const divergences = [...resolution.removed];
+        const identities = new Map();
+        for (const pathname of resolution.members) {
+            const divergence = await GitMembership.#materializeMember(pathname, root, ctx, identities);
             if (divergence !== null)
                 divergences.push(divergence);
         }