akm-cli 0.9.0-rc.0 → 0.9.0-rc.13

package/dist/core/write-source.js

@@ -13,7 +13,7 @@
  * commit behaviour — they only ever touch the filesystem. Git-backed targets
  * are committed in a SINGLE batch at the operation boundary via
  * {@link commitWriteTargetBoundary} (which delegates to `saveGitStash`). This
- * stages `.akm/` + sibling assets together as one complete commit instead of
+ * commits only operation-owned exact paths as one complete commit instead of
  * one noisy, incomplete commit per asset.
  *
  * This module is still the **single dispatch point** for write/delete: callers
@@ -24,12 +24,19 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { getCachePaths, parseGitRepoUrl, saveGitStash } from "../sources/providers/git.js";
-import { makeAssetRef } from "./asset/asset-ref.js";
-import { resolveAssetPathFromName, TYPE_DIRS } from "./asset/asset-spec.js";
+import { withAssetMutationLeaseSync } from "../indexer/index-writer-lock.js";
+import { lockContentRootFor } from "../integrations/lockfile.js";
+import { GitStashPushError, getCachePaths, inspectGitUpstream, isGitBackedStash, parseGitRepoUrl, runGit, saveGitStash, } from "../sources/providers/git.js";
+import { assertGitExactPathsClean, assertNoIgnoredExactPaths, listIgnoredExactPaths, reconcileGitExactPathIndex, } from "../sources/providers/git-stash.js";
+import { detectAdapterId } from "./adapter/detect-adapter.js";
+import { ensureAkmMarkdownType } from "./asset/akm-markdown.js";
+import { assetPathForName, stashDirFor } from "./asset/asset-placement.js";
+import { conceptIdFromTypeName, displayRef } from "./asset/resolve-ref.js";
+import { deriveBundleId } from "./bundle-id.js";
 import { isWithin, resolveStashDir } from "./common.js";
 import { resolveConfiguredSources } from "./config/config.js";
 import { ConfigError, UsageError } from "./errors.js";
+import { sanitizeCommitMessage } from "./git-message.js";
 import { warn } from "./warn.js";
 /**
  * Source kinds that the loader is allowed to mark `writable: true`. Anything
@@ -37,49 +44,210 @@ import { warn } from "./warn.js";
  * {@link assertWritableAllowedForKind}.
  */
 const REJECTED_WRITABLE_KINDS = new Set(["website", "npm"]);
-/**
- * Maximum length of a sanitized git commit message. Git itself imposes no
- * fixed limit, but message strings come from refs and `--message` flags that
- * can be supplied by users or upstream config. A 4096-char clamp keeps audit
- * trails readable and prevents pathological payloads from bloating the log
- * stream a downstream consumer parses.
- */
-const COMMIT_MESSAGE_MAX_LENGTH = 4096;
-/**
- * Sanitize a string before passing it as `git commit -m <message>`.
- *
- * Defenses, in order:
- *   1. Strip NUL bytes (`\0`) — git rejects them anyway, but we never want
- *      them in argv.
- *   2. Replace any CR/LF (`\r`, `\n`) and other ASCII control chars with a
- *      single space. This collapses newline-injection attempts that would
- *      otherwise turn a single-line commit subject into a forged trailer
- *      block.
- *   3. Collapse runs of whitespace into a single space and trim.
- *   4. Clamp to {@link COMMIT_MESSAGE_MAX_LENGTH} characters.
- *
- * If the result is empty after sanitization the caller should substitute a
- * default — this helper returns `""` rather than throwing because not every
- * callsite has a sensible "invalid input" exit code, and "empty" is a
- * recoverable signal.
- */
-export function sanitizeCommitMessage(input) {
-    if (typeof input !== "string")
-        return "";
-    // 1. Strip NULs outright.
-    let out = input.replace(/\0/g, "");
-    // 2. Replace CR/LF + other C0 control characters (0x00-0x1F, 0x7F) with a
-    //    space. Tab (0x09) is included intentionally — commit subjects should
-    //    be a single visual line.
-    // biome-ignore lint/suspicious/noControlCharactersInRegex: intentional sanitization
-    out = out.replace(/[\x00-\x1F\x7F]/g, " ");
-    // 3. Collapse whitespace runs and trim.
-    out = out.replace(/\s+/g, " ").trim();
-    // 4. Clamp length.
-    if (out.length > COMMIT_MESSAGE_MAX_LENGTH) {
-        out = out.slice(0, COMMIT_MESSAGE_MAX_LENGTH).trimEnd();
-    }
-    return out;
+const pendingGitMutations = new Map();
+const EMPTY_GIT_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+const GIT_PUSH_TIMEOUT_MS = 120_000;
+function gitTargetKey(source) {
+    return `${path.resolve(source.repoPath ?? source.path)}\0${path.resolve(source.path)}`;
+}
+/** Record the exact post-mutation blob for the target's boundary commit. */
+export function recordWriteTargetPath(source, filePath) {
+    if (source.kind !== "git")
+        return;
+    const repoDir = path.resolve(source.repoPath ?? source.path);
+    if (!isGitBackedStash(repoDir))
+        return;
+    const key = gitTargetKey(source);
+    const pending = pendingGitMutations.get(key) ?? {
+        baseHead: readOptionalGitHead(repoDir),
+        snapshots: {},
+    };
+    const snapshot = captureGitPathSnapshot({ source, config: { type: "git" } }, filePath);
+    pending.snapshots[snapshot.path] = snapshot.state;
+    pendingGitMutations.set(key, pending);
+}
+function repoRelativeGitPath(source, filePath) {
+    const repoDir = path.resolve(source.repoPath ?? source.path);
+    const absolutePath = path.resolve(filePath);
+    const [relativePath] = normalizePublicationPaths([path.relative(repoDir, absolutePath).replaceAll(path.sep, "/")]);
+    return relativePath;
+}
+/** Reject dirty or ignored exact paths before a direct transaction mutation. */
+export function assertWriteTargetPathsClean(source, filePaths) {
+    if (source.kind !== "git")
+        return;
+    const repoDir = path.resolve(source.repoPath ?? source.path);
+    if (!isGitBackedStash(repoDir))
+        return;
+    const key = gitTargetKey(source);
+    const pending = pendingGitMutations.get(key);
+    for (const filePath of filePaths) {
+        const relativePath = repoRelativeGitPath(source, filePath);
+        if (pending && Object.hasOwn(pending.snapshots, relativePath)) {
+            preflightGitPathMutation(source, filePath);
+        }
+        else {
+            assertGitExactPathsClean(repoDir, [relativePath]);
+        }
+    }
+}
+/** Preflight one operation's complete exact-path set before its first mutation. */
+export function planWriteTargetPublication(target, filePaths, options) {
+    const paths = [...new Set(filePaths.map((filePath) => path.resolve(filePath)))];
+    assertNoWritePathDescendantSymlinks(target.source, paths);
+    if (target.source.kind !== "git")
+        return { target, paths, publish: false };
+    const repoDir = path.resolve(target.source.repoPath ?? target.source.path);
+    if (!isGitBackedStash(repoDir))
+        return { target, paths, publish: false };
+    const expectedBaseHead = readOptionalGitHead(repoDir);
+    const relativePaths = paths.map((filePath) => repoRelativeGitPath(target.source, filePath));
+    const ignored = new Set(listIgnoredExactPaths(repoDir, relativePaths));
+    if (ignored.size > 0) {
+        if (options.ignored === "reject") {
+            throw new UsageError(`Exact Git publication path is ignored: ${[...ignored][0]}. Update .gitignore or choose a tracked destination before writing.`);
+        }
+    }
+    const unignoredPaths = paths.filter((_, index) => !ignored.has(relativePaths[index]));
+    assertWriteTargetPathsClean(target.source, unignoredPaths);
+    assertWriteTargetPlanBase(target, expectedBaseHead);
+    return { target, paths, publish: ignored.size === 0, expectedBaseHead };
+}
+function assertNoWritePathDescendantSymlinks(source, filePaths) {
+    const lexicalRoot = path.resolve(source.path);
+    const canonicalRoot = fs.realpathSync(lexicalRoot);
+    for (const filePath of filePaths) {
+        const relative = path.relative(lexicalRoot, filePath);
+        if (!relative || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+            throw new UsageError(`Write path resolves outside source "${source.name}".`, "PATH_ESCAPE_VIOLATION");
+        }
+        let current = canonicalRoot;
+        for (const segment of relative.split(path.sep)) {
+            current = path.join(current, segment);
+            try {
+                if (fs.lstatSync(current).isSymbolicLink()) {
+                    throw new UsageError(`Write path contains a symbolic link below source "${source.name}": ${relative}`);
+                }
+            }
+            catch (error) {
+                if (error.code === "ENOENT")
+                    break;
+                throw error;
+            }
+        }
+    }
+}
+function assertWriteTargetPlanBase(target, expectedBaseHead) {
+    const repoDir = path.resolve(target.source.repoPath ?? target.source.path);
+    if (readOptionalGitHead(repoDir) !== expectedBaseHead) {
+        throw new UsageError(`Git target "${target.source.name}" advanced after exact-path preflight.`);
+    }
+}
+/** Revalidate a publication plan immediately before its first mutation. */
+export function beginWriteTargetMutation(plan) {
+    if (plan.expectedBaseHead === undefined)
+        return;
+    assertWriteTargetPlanBase(plan.target, plan.expectedBaseHead);
+}
+/** Publish exactly the paths bound by {@link planWriteTargetPublication}. */
+export function publishWriteTargetPlan(plan, message, expectedSnapshots) {
+    if (!plan.publish)
+        return;
+    if (plan.expectedBaseHead === undefined) {
+        throw new UsageError(`Git publication plan for "${plan.target.source.name}" has no preflight base.`);
+    }
+    assertWriteTargetPlanBase(plan.target, plan.expectedBaseHead);
+    for (const filePath of plan.paths)
+        recordWriteTargetPath(plan.target.source, filePath);
+    commitWriteTargetBoundary(plan.target, message, {
+        paths: [...plan.paths],
+        expectedBaseHead: plan.expectedBaseHead,
+        ...(expectedSnapshots ? { expectedSnapshots } : {}),
+    });
+}
+/** Hold the shared asset lease from exact-path preflight through publication. */
+export function withWriteTargetMutation(target, paths, options, mutate) {
+    return withAssetMutationLeaseSync(options.purpose, () => {
+        const plan = planWriteTargetPublication(target, paths, { ignored: options.ignored });
+        beginWriteTargetMutation(plan);
+        const result = mutate();
+        const expectedSnapshots = captureIntendedWriteTargetState(plan);
+        publishWriteTargetPlan(plan, options.message, expectedSnapshots);
+        return result;
+    });
+}
+function captureIntendedWriteTargetState(plan) {
+    if (plan.expectedBaseHead === undefined)
+        return undefined;
+    const snapshots = {};
+    for (const filePath of plan.paths) {
+        const snapshot = captureGitPathSnapshot(plan.target, filePath);
+        snapshots[snapshot.path] = snapshot.state;
+    }
+    return snapshots;
+}
+function readOptionalGitHead(repoDir) {
+    const result = runGit(["-C", repoDir, "rev-parse", "--verify", "HEAD"]);
+    return result.status === 0 && result.stdout.trim() ? result.stdout.trim() : null;
+}
+function preflightGitPathMutation(source, filePath) {
+    if (source.kind !== "git")
+        return undefined;
+    const repoDir = path.resolve(source.repoPath ?? source.path);
+    if (!isGitBackedStash(repoDir))
+        return undefined;
+    const relativePath = repoRelativeGitPath(source, filePath);
+    const key = gitTargetKey(source);
+    let pending = pendingGitMutations.get(key);
+    const created = pending === undefined;
+    if (!pending) {
+        pending = { baseHead: readOptionalGitHead(repoDir), snapshots: {} };
+        pendingGitMutations.set(key, pending);
+    }
+    try {
+        if (readOptionalGitHead(repoDir) !== pending.baseHead) {
+            throw new UsageError(`Git target "${source.name}" advanced before its exact-path mutation.`);
+        }
+        if (!Object.hasOwn(pending.snapshots, relativePath)) {
+            assertGitExactPathsClean(repoDir, [relativePath]);
+            return { key, created };
+        }
+        assertNoIgnoredExactPaths(repoDir, [relativePath]);
+        const index = runGit([
+            "--literal-pathspecs",
+            "-C",
+            repoDir,
+            "diff",
+            "--cached",
+            "--quiet",
+            pending.baseHead ?? EMPTY_GIT_TREE,
+            "--",
+            relativePath,
+        ]);
+        if (index.status === 1) {
+            throw new UsageError(`Exact Git operation path has staged work: ${relativePath}. Commit, stash, or discard that path before retrying.`);
+        }
+        if (index.status !== 0) {
+            throw new Error(`Cannot inspect Git index for exact operation path ${relativePath}: ${index.stderr.trim()}`);
+        }
+        const current = captureGitPathSnapshot({ source, config: { type: "git" } }, filePath);
+        if (!sameGitPathState(current.state, pending.snapshots[relativePath] ?? null)) {
+            throw new UsageError(`Exact Git operation path changed after AKM wrote it: ${relativePath}. Commit, stash, or discard that path before retrying.`);
+        }
+        return { key, created };
+    }
+    catch (error) {
+        if (created && Object.keys(pending.snapshots).length === 0)
+            pendingGitMutations.delete(key);
+        throw error;
+    }
+}
+function discardEmptyGitPreflight(preflight) {
+    if (!preflight?.created)
+        return;
+    const pending = pendingGitMutations.get(preflight.key);
+    if (pending && Object.keys(pending.snapshots).length === 0)
+        pendingGitMutations.delete(preflight.key);
 }
 // ── Portability advisory (review 13, D1) ────────────────────────────────────
 /**
@@ -157,10 +325,20 @@ export function assertWritableAllowedForKind(entry) {
 export async function writeAssetToSource(source, config, ref, content) {
     ensureWritable(source, config);
     assertSupportedKind(source);
+    assertAkmAssetWrite(source);
     const filePath = resolveAssetFilePath(source, ref);
-    fs.mkdirSync(path.dirname(filePath), { recursive: true });
-    const normalized = content.endsWith("\n") ? content : `${content}\n`;
-    fs.writeFileSync(filePath, normalized, "utf8");
+    const authored = filePath.toLowerCase().endsWith(".md") ? ensureAkmMarkdownType(content, ref.type) : content;
+    const normalized = authored.endsWith("\n") ? authored : `${authored}\n`;
+    const preflight = preflightGitPathMutation(source, filePath);
+    try {
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.writeFileSync(filePath, normalized, "utf8");
+        recordWriteTargetPath(source, filePath);
+    }
+    catch (error) {
+        discardEmptyGitPreflight(preflight);
+        throw error;
+    }
     // Non-fatal portability advisory (review 13, D1): flag absolute host home
     // paths in the written content. These make the stash non-portable and leak
     // the local username. We warn AFTER the write so the advisory never blocks it.
@@ -169,7 +347,7 @@ export async function writeAssetToSource(source, config, ref, content) {
         warn(`warning: asset "${formatRefForMessage(ref)}" embeds absolute host path(s): ${hostPaths.join(", ")}. ` +
             "These make the stash non-portable and leak the local username — prefer $HOME or ~ relative references.");
     }
-    return { path: filePath, ref: makeAssetRef(ref.type, ref.name, ref.origin) };
+    return { path: filePath, ref: displayRef({ type: ref.type, name: ref.name, bundleId: ref.origin }) };
 }
 /**
  * Delete the asset at `ref` from `source`. Symmetric to
@@ -180,12 +358,21 @@ export async function writeAssetToSource(source, config, ref, content) {
 export async function deleteAssetFromSource(source, config, ref) {
     ensureWritable(source, config);
     assertSupportedKind(source);
+    assertAkmAssetWrite(source);
     const filePath = resolveAssetFilePath(source, ref);
     if (!fs.existsSync(filePath)) {
         throw new UsageError(`Asset "${formatRefForMessage(ref)}" not found in source "${source.name}" (expected at ${filePath}).`, "MISSING_REQUIRED_ARGUMENT");
     }
-    fs.unlinkSync(filePath);
-    return { path: filePath, ref: makeAssetRef(ref.type, ref.name, ref.origin) };
+    const preflight = preflightGitPathMutation(source, filePath);
+    try {
+        fs.unlinkSync(filePath);
+        recordWriteTargetPath(source, filePath);
+    }
+    catch (error) {
+        discardEmptyGitPreflight(preflight);
+        throw error;
+    }
+    return { path: filePath, ref: displayRef({ type: ref.type, name: ref.name, bundleId: ref.origin }) };
 }
 /**
  * Fire the one-shot batch-at-boundary commit for a resolved write target.
@@ -196,67 +383,542 @@ export async function deleteAssetFromSource(source, config, ref) {
  * primary stash stay non-committing here — the primary stash is committed by
  * the existing improve auto-sync boundary).
  *
- * For a git target it delegates to `saveGitStash(name, message, writable, …)`,
- * which stages `.akm/` + sibling assets together (`git add -A`), commits once,
- * and pushes when the target is writable, has a remote, and `push !== false`.
+ * For a git target it delegates to `saveGitStash(name, message, writable, …)`
+ * with the exact paths recorded by the write/delete helpers (plus any explicit
+ * caller paths), commits once, and pushes when the target is writable, has a
+ * remote, and `push !== false`.
  *
- * The push intent honours a deprecated `options.pushOnCommit` on the source
- * config (mapped onto the batch push gate) when `push` is not explicitly set.
  */
 export function commitWriteTargetBoundary(target, message, options) {
     if (target.source.kind !== "git")
         return;
-    warnIfPushOnCommit(target.config);
-    // Map the deprecated per-asset `pushOnCommit` intent onto the batch push gate
-    // when the caller did not pass an explicit push toggle. `saveGitStash` still
-    // gates the actual push on writable + remote, so this only ever opts *in*.
-    const push = options?.push ?? (target.config.options?.pushOnCommit === true ? true : undefined);
+    const push = options?.push;
     const writable = resolveWritable(target.config);
-    // Commit against the already-resolved repo directory (target.source.path)
-    // rather than re-resolving the stash by name through config. The write helper
-    // resolved this exact path; the boundary commit must operate on the SAME
-    // directory so the staged batch matches what was just written.
-    saveGitStash(undefined, message, writable, {
-        repoDir: target.source.path,
-        ...(push === undefined ? {} : { push }),
+    const repoDir = path.resolve(target.source.repoPath ?? target.source.path);
+    const key = gitTargetKey(target.source);
+    const pending = pendingGitMutations.get(key);
+    const expectedBaseHead = options?.expectedBaseHead !== undefined
+        ? options.expectedBaseHead
+        : pending
+            ? pending.baseHead
+            : readOptionalGitHead(repoDir);
+    const normalizeBoundaryPath = (filePath) => {
+        const relativePath = path.isAbsolute(filePath)
+            ? path.relative(repoDir, path.resolve(filePath)).replaceAll(path.sep, "/")
+            : filePath.replaceAll(path.sep, "/");
+        return normalizePublicationPaths([relativePath])[0];
+    };
+    const providedSnapshots = new Map(Object.entries(options?.expectedSnapshots ?? {}).map(([filePath, state]) => [
+        normalizeBoundaryPath(filePath),
+        state,
+    ]));
+    const paths = normalizePublicationPaths([
+        ...(options?.paths ?? []).map(normalizeBoundaryPath),
+        ...Object.keys(pending?.snapshots ?? {}),
+    ]);
+    const expectedSnapshots = {};
+    for (const filePath of paths) {
+        if (providedSnapshots.has(filePath)) {
+            expectedSnapshots[filePath] = providedSnapshots.get(filePath) ?? null;
+        }
+        else if (pending && Object.hasOwn(pending.snapshots, filePath)) {
+            expectedSnapshots[filePath] = pending.snapshots[filePath] ?? null;
+        }
+        else {
+            expectedSnapshots[filePath] = captureGitPathSnapshot(target, path.join(repoDir, filePath)).state;
+        }
+    }
+    if (options?.expectedBaseHead !== undefined &&
+        pending !== undefined &&
+        options.expectedBaseHead !== pending.baseHead) {
+        throw new Error(`Git boundary base does not match the recorded exact-path mutation base.`);
+    }
+    // Assets may live under <repo>/content, but git synchronization always runs
+    // against the repository root.
+    try {
+        saveGitStash(undefined, message, writable, {
+            repoDir,
+            paths,
+            expectedSnapshots,
+            expectedBaseHead,
+            ...(push === undefined ? {} : { push }),
+            ...(options?.transactionId === undefined ? {} : { transactionId: options.transactionId }),
+        });
+        pendingGitMutations.delete(key);
+    }
+    catch (error) {
+        const currentHead = readOptionalGitHead(repoDir);
+        if (pending && currentHead !== pending.baseHead)
+            pendingGitMutations.delete(key);
+        if (error instanceof GitStashPushError) {
+            throw new Error(`Changes were committed as ${error.commit}, but publication failed: ${error.message}`, {
+                cause: error,
+            });
+        }
+        throw error;
+    }
+}
+function sameGitPathState(left, right) {
+    return left === null ? right === null : right !== null && left.oid === right.oid && left.mode === right.mode;
+}
+/** Capture the exact checkout/upstream identity before a durable mutation starts. */
+export function captureGitPublication(target) {
+    if (target.source.kind !== "git")
+        return undefined;
+    const identity = readGitPublicationIdentity(target);
+    const head = runGit(["-C", identity.repoPath, "rev-parse", "HEAD"]);
+    if (head.status !== 0 || !head.stdout.trim()) {
+        throw new Error(`Cannot read Git HEAD for target "${target.source.name}".`);
+    }
+    const baseHead = head.stdout.trim();
+    let upstreamHead;
+    if (identity.upstream) {
+        const upstream = runGit(["-C", identity.repoPath, "rev-parse", identity.upstream]);
+        if (upstream.status !== 0 || !upstream.stdout.trim()) {
+            throw new Error(`Cannot read Git upstream for target "${target.source.name}".`);
+        }
+        upstreamHead = upstream.stdout.trim();
+        if (baseHead !== upstreamHead) {
+            throw new Error(`Writable Git target "${target.source.name}" changed after mutation preflight.`);
+        }
+    }
+    return { ...identity, baseHead, ...(upstreamHead ? { upstreamHead } : {}) };
+}
+/** Capture one repo-relative path exactly as Git will stage it. */
+export function captureGitPathSnapshot(target, filePath) {
+    if (target.source.kind !== "git")
+        throw new Error(`Target "${target.source.name}" is not Git-backed.`);
+    const repoPath = path.resolve(target.source.repoPath ?? target.source.path);
+    const absolutePath = path.resolve(filePath);
+    const relativePath = path.relative(repoPath, absolutePath).replaceAll(path.sep, "/");
+    const [normalizedPath] = normalizePublicationPaths([relativePath]);
+    return {
+        path: normalizedPath,
+        state: captureGitPathState(repoPath, absolutePath, normalizedPath),
+    };
+}
+function captureGitPathState(repoPath, absolutePath, relativePath) {
+    let stat;
+    try {
+        stat = fs.lstatSync(absolutePath);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    let mode;
+    let oidResult;
+    if (stat.isSymbolicLink()) {
+        mode = "120000";
+        oidResult = runGit(["-C", repoPath, "hash-object", "--stdin"], { input: fs.readlinkSync(absolutePath) });
+    }
+    else if (stat.isFile()) {
+        mode = stat.mode & 0o111 ? "100755" : "100644";
+        oidResult = runGit(["-C", repoPath, "hash-object", `--path=${relativePath}`, "--", absolutePath]);
+    }
+    else {
+        throw new Error(`Git publication path is not a file: ${relativePath}`);
+    }
+    if (oidResult.status !== 0 || !oidResult.stdout.trim()) {
+        throw new Error(`Cannot snapshot Git publication path: ${relativePath}`);
+    }
+    return { oid: oidResult.stdout.trim(), mode };
+}
+/** Create or recover the one transaction-owned commit without pushing it. */
+export function ensureGitTransactionCommit(target, publication, options) {
+    assertGitPublicationIdentity(target, publication);
+    const paths = normalizePublicationPaths(options.paths);
+    validateGitWorktreeSnapshots(target, paths, options.snapshots);
+    if (publication.commit !== undefined) {
+        if (publication.commit !== null) {
+            validateGitTransactionCommit(target, publication, publication.commit, options.transactionId, paths, options.snapshots);
+            reconcileGitExactPathIndex(publication.repoPath, publication.baseHead, publication.commit, paths);
+        }
+        return publication.commit;
+    }
+    const existing = findGitTransactionCommit(publication.repoPath, publication.baseHead, options.transactionId);
+    if (existing) {
+        validateGitTransactionCommit(target, publication, existing, options.transactionId, paths, options.snapshots);
+        reconcileGitExactPathIndex(publication.repoPath, publication.baseHead, existing, paths);
+        return existing;
+    }
+    const head = readGitHead(publication.repoPath, target.source.name);
+    if (head !== publication.baseHead) {
+        throw new Error(`Cannot publish Git transaction ${options.transactionId}: target "${target.source.name}" advanced before its commit was recorded.`);
+    }
+    commitWriteTargetBoundary(target, options.message, {
+        paths,
+        push: false,
+        transactionId: options.transactionId,
+        expectedBaseHead: publication.baseHead,
+        expectedSnapshots: options.snapshots,
     });
+    const committed = findGitTransactionCommit(publication.repoPath, publication.baseHead, options.transactionId);
+    if (!committed) {
+        if (readGitHead(publication.repoPath, target.source.name) === publication.baseHead) {
+            validateGitCommitSnapshots(publication.repoPath, publication.baseHead, paths, options.snapshots);
+            return null;
+        }
+        throw new Error(`Cannot identify the Git commit for transaction ${options.transactionId}.`);
+    }
+    validateGitTransactionCommit(target, publication, committed, options.transactionId, paths, options.snapshots);
+    reconcileGitExactPathIndex(publication.repoPath, publication.baseHead, committed, paths);
+    return committed;
+}
+/**
+ * Kind-neutral snapshot capture for one mutated path.
+ *
+ * Returns `undefined` for kinds with no publication model, so command layers
+ * never branch on `source.kind` themselves — the same fail-soft contract
+ * {@link captureGitPublication} and {@link commitWriteTargetBoundary} already
+ * use. `captureGitPathSnapshot` throws for non-git targets, which is what
+ * forced callers to guard; this absorbs that guard.
+ */
+export function captureWriteTargetPathSnapshot(target, filePath) {
+    if (target.source.kind !== "git")
+        return undefined;
+    return captureGitPathSnapshot(target, filePath);
 }
 /**
- * Emit a one-time deprecation warning the first time a source config carrying
- * `options.pushOnCommit` is encountered. The field still parses (for old
- * configs) but its per-asset push-on-commit behaviour is retired; its intent is
- * now honoured via the batch push gate (writable + remote + push toggle).
+ * Kind-neutral commit + publish for one transaction boundary.
+ *
+ * A no-op (returns `undefined`) for kinds with no publication model. For a
+ * publication-backed target this absorbs BOTH the kind test and the
+ * "transaction lacks durable publication identity" invariant, so callers hold
+ * no provider knowledge. `onCommitRecorded` fires between the ensure and the
+ * push, letting a caller persist the commit and advance its own journal phase
+ * without inspecting the target.
+ *
+ * `missingPublicationError` lets a caller keep its own error CLASS for the
+ * missing-identity case. The two call sites disagreed historically —
+ * consolidate threw `ConfigError` (exit 78), proposal a plain `Error`
+ * (exit 70) — and collapsing them here would silently change one command's
+ * exit code. The guard moves; the classification stays with the caller.
  */
-let pushOnCommitWarned = false;
-function warnIfPushOnCommit(config) {
-    if (config.options?.pushOnCommit === undefined)
+export function publishWriteTargetTransaction(target, publication, options) {
+    if (target.source.kind !== "git")
+        return undefined;
+    if (!publication) {
+        throw (options.missingPublicationError?.(target.source.name) ??
+            new Error(`Proposal transaction ${options.transactionId} has no Git publication identity.`));
+    }
+    const commit = ensureGitTransactionCommit(target, publication, {
+        transactionId: options.transactionId,
+        message: options.message,
+        paths: options.paths,
+        snapshots: options.snapshots,
+    });
+    options.onCommitRecorded?.(commit);
+    publishGitTransactionCommit(target, publication, options.transactionId, options.paths, options.snapshots);
+    return { commit };
+}
+/** Push only the recorded transaction commit, never later local descendants. */
+export function publishGitTransactionCommit(target, publication, transactionId, paths, snapshots) {
+    assertGitPublicationIdentity(target, publication);
+    if (publication.commit === undefined) {
+        throw new Error(`Git transaction ${transactionId} has no recorded publication decision.`);
+    }
+    if (publication.commit === null)
+        return;
+    validateGitTransactionCommit(target, publication, publication.commit, transactionId, normalizePublicationPaths(paths), snapshots);
+    if (!publication.remote || !publication.mergeRef)
         return;
-    if (pushOnCommitWarned)
+    if (!publication.upstream)
+        throw new Error(`Git transaction ${transactionId} has no recorded upstream.`);
+    if (runGit(["-C", publication.repoPath, "merge-base", "--is-ancestor", publication.commit, publication.upstream])
+        .status === 0) {
         return;
-    pushOnCommitWarned = true;
-    const label = config.name ? ` on source "${config.name}"` : "";
-    process.stderr.write(`warning: \`options.pushOnCommit\`${label} is deprecated (0.9.0) and no longer commits per asset. ` +
-        "akm now commits writes in a single batch at the operation boundary and pushes when the target is " +
-        "writable with a remote. Remove the option or rely on sync push instead.\n");
+    }
+    if (runGit(["-C", publication.repoPath, "merge-base", "--is-ancestor", publication.upstream, publication.commit])
+        .status !== 0) {
+        throw new Error(`Cannot publish Git transaction ${transactionId}: upstream history diverged.`);
+    }
+    if (!publication.upstreamHead) {
+        throw new Error(`Git transaction ${transactionId} has no recorded upstream lease.`);
+    }
+    const pushed = runGit([
+        "-C",
+        publication.repoPath,
+        "push",
+        `--force-with-lease=${publication.mergeRef}:${publication.upstreamHead}`,
+        publication.remote,
+        `${publication.commit}:${publication.mergeRef}`,
+    ], { timeout: GIT_PUSH_TIMEOUT_MS });
+    if (pushed.status !== 0) {
+        throw new Error(`git push failed for target "${target.source.name}": ${pushed.stderr.trim()}`);
+    }
+}
+function readGitPublicationIdentity(target) {
+    const repoPath = path.resolve(target.source.repoPath ?? target.source.path);
+    const branchResult = runGit(["-C", repoPath, "symbolic-ref", "--quiet", "--short", "HEAD"]);
+    const branch = branchResult.status === 0 ? branchResult.stdout.trim() : undefined;
+    const remotes = runGit(["-C", repoPath, "remote"]);
+    if (remotes.status !== 0)
+        throw new Error(`Cannot inspect Git remotes for target "${target.source.name}".`);
+    if (!remotes.stdout.trim())
+        return { repoPath, ...(branch ? { branch } : {}) };
+    if (!branch)
+        throw new Error(`Writable Git target "${target.source.name}" is detached from a branch.`);
+    const remoteResult = runGit(["-C", repoPath, "config", "--get", `branch.${branch}.remote`]);
+    const mergeResult = runGit(["-C", repoPath, "config", "--get", `branch.${branch}.merge`]);
+    if (remoteResult.status !== 0 || mergeResult.status !== 0) {
+        throw new Error(`Writable Git target "${target.source.name}" has no configured upstream branch.`);
+    }
+    const remote = remoteResult.stdout.trim();
+    const mergeRef = mergeResult.stdout.trim();
+    const upstreamResult = runGit(["-C", repoPath, "rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"]);
+    if (upstreamResult.status !== 0 || !upstreamResult.stdout.trim()) {
+        throw new Error(`Cannot read Git upstream for target "${target.source.name}".`);
+    }
+    const urlResult = runGit(["-C", repoPath, "remote", "get-url", remote]);
+    if (urlResult.status !== 0 || !urlResult.stdout.trim()) {
+        throw new Error(`Cannot read Git remote "${remote}" for target "${target.source.name}".`);
+    }
+    const pushUrlsResult = runGit(["-C", repoPath, "remote", "get-url", "--push", "--all", remote]);
+    if (pushUrlsResult.status !== 0 || !pushUrlsResult.stdout.trim()) {
+        throw new Error(`Cannot read Git push URL for target "${target.source.name}".`);
+    }
+    return {
+        repoPath,
+        branch,
+        remote,
+        mergeRef,
+        remoteUrl: urlResult.stdout.trim(),
+        pushUrls: pushUrlsResult.stdout
+            .split("\n")
+            .map((value) => value.trim())
+            .filter(Boolean),
+        upstream: upstreamResult.stdout.trim(),
+    };
+}
+function assertGitPublicationIdentity(target, publication) {
+    if (target.source.kind !== "git") {
+        throw new Error(`Git publication is bound to non-Git target "${target.source.name}".`);
+    }
+    const current = readGitPublicationIdentity(target);
+    for (const key of ["repoPath", "branch", "remote", "mergeRef", "remoteUrl", "upstream"]) {
+        if (current[key] !== publication[key]) {
+            throw new Error(`Git publication target identity changed at ${key} for "${target.source.name}".`);
+        }
+    }
+    if (JSON.stringify(current.pushUrls ?? []) !== JSON.stringify(publication.pushUrls ?? [])) {
+        throw new Error(`Git publication target identity changed at pushUrls for "${target.source.name}".`);
+    }
+}
+function normalizePublicationPaths(paths) {
+    const normalized = new Set();
+    for (const filePath of paths) {
+        const candidate = filePath.replaceAll(path.sep, "/");
+        if (!candidate ||
+            candidate.includes("\0") ||
+            path.isAbsolute(filePath) ||
+            path.posix.isAbsolute(candidate) ||
+            candidate === "." ||
+            candidate === ".." ||
+            candidate.startsWith("../") ||
+            path.posix.normalize(candidate) !== candidate) {
+            throw new Error("Git publication contains an unsafe path.");
+        }
+        normalized.add(candidate);
+    }
+    return [...normalized];
+}
+function readGitHead(repoPath, targetName) {
+    const result = runGit(["-C", repoPath, "rev-parse", "HEAD"]);
+    if (result.status !== 0 || !result.stdout.trim())
+        throw new Error(`Cannot read Git HEAD for target "${targetName}".`);
+    return result.stdout.trim();
+}
+function findGitTransactionCommit(repoPath, baseHead, transactionId) {
+    const result = runGit([
+        "-C",
+        repoPath,
+        "log",
+        "--format=%H",
+        "--fixed-strings",
+        `--grep=AKM-Transaction: ${transactionId}`,
+        `${baseHead}..HEAD`,
+    ]);
+    if (result.status !== 0)
+        throw new Error(`Cannot inspect Git transaction ${transactionId}.`);
+    const matches = result.stdout
+        .split("\n")
+        .map((value) => value.trim())
+        .filter(Boolean);
+    if (matches.length > 1)
+        throw new Error(`Git transaction ${transactionId} has multiple candidate commits.`);
+    return matches[0];
+}
+function validateGitTransactionCommit(target, publication, commit, transactionId, expectedPaths, snapshots) {
+    const parent = runGit(["-C", publication.repoPath, "rev-list", "--parents", "-n", "1", commit]);
+    const ancestry = parent.stdout.trim().split(/\s+/);
+    if (parent.status !== 0 || ancestry.length !== 2 || ancestry[1] !== publication.baseHead) {
+        throw new Error(`Git commit ${commit} is not the direct transaction commit for "${target.source.name}".`);
+    }
+    const message = runGit(["-C", publication.repoPath, "show", "-s", "--format=%B", commit]);
+    if (message.status !== 0 ||
+        !message.stdout.split(/\r?\n/).some((line) => line.trim() === `AKM-Transaction: ${transactionId}`)) {
+        throw new Error(`Git commit ${commit} is not owned by transaction ${transactionId}.`);
+    }
+    const changed = runGit([
+        "-C",
+        publication.repoPath,
+        "diff-tree",
+        "--no-commit-id",
+        "--name-only",
+        "-z",
+        "--no-renames",
+        "-r",
+        commit,
+    ]);
+    const expected = new Set(expectedPaths);
+    const changedPaths = changed.stdout.split("\0").filter(Boolean);
+    if (changed.status !== 0 || changedPaths.length === 0 || changedPaths.some((filePath) => !expected.has(filePath))) {
+        throw new Error(`Git commit ${commit} contains paths outside transaction ${transactionId}.`);
+    }
+    validateGitCommitSnapshots(publication.repoPath, commit, expectedPaths, snapshots);
+    if (runGit(["-C", publication.repoPath, "merge-base", "--is-ancestor", commit, "HEAD"]).status !== 0) {
+        throw new Error(`Git commit ${commit} is no longer on the target branch.`);
+    }
+}
+function validateGitWorktreeSnapshots(target, expectedPaths, snapshots) {
+    for (const expectedPath of expectedPaths) {
+        if (!Object.hasOwn(snapshots, expectedPath)) {
+            throw new Error(`Git publication lacks a snapshot for ${expectedPath}.`);
+        }
+        const current = captureGitPathSnapshot(target, path.join(target.source.repoPath ?? target.source.path, expectedPath));
+        if (!sameGitPathState(current.state, snapshots[expectedPath] ?? null)) {
+            throw new Error(`Git publication path diverged after mutation: ${expectedPath}.`);
+        }
+    }
+}
+function validateGitCommitSnapshots(repoPath, commit, expectedPaths, snapshots) {
+    for (const expectedPath of expectedPaths) {
+        if (!Object.hasOwn(snapshots, expectedPath)) {
+            throw new Error(`Git publication lacks a snapshot for ${expectedPath}.`);
+        }
+        const expected = snapshots[expectedPath];
+        const tree = runGit(["-C", repoPath, "ls-tree", commit, "--", expectedPath]);
+        if (tree.status !== 0)
+            throw new Error(`Cannot inspect committed Git path: ${expectedPath}.`);
+        const match = tree.stdout.trim().match(/^(\d+)\s+blob\s+([0-9a-f]+)\t/);
+        if (expected === null) {
+            if (tree.stdout.trim())
+                throw new Error(`Git transaction unexpectedly retained ${expectedPath}.`);
+        }
+        else if (expected === undefined || !match || match[1] !== expected.mode || match[2] !== expected.oid) {
+            throw new Error(`Git transaction committed unexpected content for ${expectedPath}.`);
+        }
+    }
+}
+/**
+ * Validate and normalize a write target before a command mutates it.
+ *
+ * Git bundle locks record the materialized content root, which can be a
+ * subdirectory of the checkout. Resolve the actual repository boundary from
+ * that root so scoped commits use repository-relative paths. Extracted or
+ * unmaterialized Git caches are not writable checkouts and must fail before a
+ * command writes files into them.
+ */
+export function prepareWriteTargetForMutation(target, options = {}) {
+    assertAkmAssetWrite(target.source, options.allowedAdapters);
+    if (target.source.kind !== "git")
+        return target;
+    const contentRoot = path.resolve(target.source.path);
+    let stat;
+    try {
+        stat = fs.statSync(contentRoot);
+    }
+    catch {
+        throw gitTargetNotMaterialized(target, contentRoot);
+    }
+    if (!stat.isDirectory())
+        throw gitTargetNotMaterialized(target, contentRoot);
+    const rootResult = runGit(["-C", contentRoot, "rev-parse", "--show-toplevel"]);
+    if (rootResult.status !== 0 || !rootResult.stdout.trim()) {
+        throw gitTargetNotMaterialized(target, contentRoot);
+    }
+    const repoPath = path.resolve(rootResult.stdout.trim());
+    const gitDirResult = runGit(["-C", repoPath, "rev-parse", "--git-dir"]);
+    if (gitDirResult.status !== 0 || !gitDirResult.stdout.trim()) {
+        throw gitTargetNotMaterialized(target, contentRoot);
+    }
+    const gitDir = path.resolve(repoPath, gitDirResult.stdout.trim());
+    let realContentRoot;
+    let realRepoPath;
+    try {
+        realContentRoot = fs.realpathSync(contentRoot);
+        realRepoPath = fs.realpathSync(repoPath);
+        fs.accessSync(realContentRoot, fs.constants.W_OK);
+        fs.accessSync(gitDir, fs.constants.W_OK);
+    }
+    catch {
+        throw new ConfigError(`Writable Git target "${target.source.name}" is not writable at ${contentRoot}.`, "INVALID_CONFIG_FILE", `Fix the checkout permissions or choose a different --target.`);
+    }
+    if (!isWithin(realContentRoot, realRepoPath)) {
+        throw new ConfigError(`Writable Git target "${target.source.name}" resolves outside its checkout: ${contentRoot}.`, "INVALID_CONFIG_FILE");
+    }
+    const statusResult = runGit(["-C", repoPath, "status", "--porcelain"]);
+    if (statusResult.status !== 0 || statusResult.error) {
+        throw gitTargetNotMaterialized(target, contentRoot);
+    }
+    const branchResult = runGit(["-C", repoPath, "symbolic-ref", "--quiet", "HEAD"]);
+    if (branchResult.status !== 0 || !branchResult.stdout.trim()) {
+        throw new UsageError(`Writable Git target "${target.source.name}" is detached from a branch.`, "INVALID_FLAG_VALUE");
+    }
+    const upstream = inspectGitUpstream(repoPath);
+    if (upstream.behind > 0) {
+        throw new UsageError(`Writable Git target "${target.source.name}" is behind ${upstream.upstream}; run \`akm bundle update ${target.source.name}\` before writing.`, "INVALID_FLAG_VALUE");
+    }
+    if (upstream.ahead > 0 && options.allowAhead !== true) {
+        throw new UsageError(`Writable Git target "${target.source.name}" has unpushed commits; push or reconcile them before AKM writes another commit.`, "INVALID_FLAG_VALUE");
+    }
+    return {
+        ...target,
+        source: { ...target.source, path: contentRoot, repoPath },
+    };
+}
+function gitTargetNotMaterialized(target, contentRoot) {
+    return new ConfigError(`Writable Git target "${target.source.name}" is not materialized as a Git checkout at ${contentRoot}; refusing to write without a commit boundary.`, "INVALID_CONFIG_FILE", `Run \`akm bundle update ${target.source.name}\` to materialize it, or point the bundle at a writable Git checkout.`);
+}
+/** Enumerate enabled writable targets, deduplicated by materialized content root. */
+export function resolveWritableTargets(akmConfig) {
+    const byRoot = new Map();
+    for (const runtime of resolveConfiguredSources(akmConfig)) {
+        if (runtime.enabled === false || !resolveWritable({ type: runtime.type, writable: runtime.writable }))
+            continue;
+        const target = adaptConfiguredSource(runtime);
+        const root = path.resolve(target.source.path);
+        const existing = byRoot.get(root);
+        if (!existing || target.source.name === akmConfig.defaultWriteTarget)
+            byRoot.set(root, target);
+    }
+    if (process.env.AKM_BUNDLE_DIR?.trim()) {
+        const target = resolveWorkingStashTarget(akmConfig);
+        byRoot.set(path.resolve(target.source.path), target);
+    }
+    return [...byRoot.values()];
 }
 /**
  * Resolve the destination for a write per locked decision 3:
  *
  *   1. Explicit `--target <name>` (when supplied)
  *   2. `config.defaultWriteTarget`
- *   3. `config.stashDir` (the working stash created by `akm init`)
- *   4. `ConfigError("no writable source configured; run `akm init`")`
+ *   3. `config.defaultBundle`'s path (the working stash created by `akm bundle create`)
+ *   4. `ConfigError("no writable source configured; run `akm bundle create`")`
  *
  * The legacy `first-writable-in-source-array-order` fallback is *not* used —
  * see plan §6 decision 3 for the rationale.
  */
-export function resolveWriteTarget(akmConfig, explicitTarget) {
+export function resolveWriteTarget(akmConfig, explicitTarget, options = {}) {
     const configuredSources = resolveConfiguredSources(akmConfig);
+    const requireWritable = options.requireWritable !== false;
     // 1. Explicit --target wins.
     if (explicitTarget) {
         const match = configuredSources.find((s) => s.name === explicitTarget);
         if (!match) {
-            throw new UsageError(`--target must reference a source name from your config. No source named "${explicitTarget}" is configured. Run \`akm list\` to see available sources.`, "INVALID_FLAG_VALUE");
+            throw new UsageError(`--target must reference a source name from your config. No source named "${explicitTarget}" is configured. Run \`akm bundle list\` to see available sources.`, "INVALID_FLAG_VALUE");
         }
         // Up-front writable check so an explicit --target fails fast with a
         // ConfigError (rather than the generic UsageError ensureWritable would
@@ -264,7 +926,7 @@ export function resolveWriteTarget(akmConfig, explicitTarget) {
         // effective writable flag (filesystem defaults to true; everything else
         // defaults to false) so unset values are interpreted correctly.
         const effectiveWritable = resolveWritable({ type: match.type, writable: match.writable });
-        if (!effectiveWritable) {
+        if (requireWritable && !effectiveWritable) {
             throw new ConfigError(`source ${explicitTarget} is not writable`, "INVALID_CONFIG_FILE", `Set \`writable: true\` on the "${explicitTarget}" source in your config, or pass --target to a different source.`);
         }
         return adaptConfiguredSource(match);
@@ -279,34 +941,51 @@ export function resolveWriteTarget(akmConfig, explicitTarget) {
             // ConfigError, rather than surfacing as a generic UsageError after
             // path-building has already begun.
             const effectiveWritable = resolveWritable({ type: match.type, writable: match.writable });
-            if (!effectiveWritable) {
+            if (requireWritable && !effectiveWritable) {
                 throw new ConfigError(`defaultWriteTarget "${akmConfig.defaultWriteTarget}" is not writable`, "INVALID_CONFIG_FILE", `Set \`writable: true\` on the "${akmConfig.defaultWriteTarget}" source in your config, or change \`defaultWriteTarget\` to a writable source.`);
             }
             return adaptConfiguredSource(match);
         }
         // Fall through if the named target no longer exists — surface a clear error.
-        throw new ConfigError(`defaultWriteTarget "${akmConfig.defaultWriteTarget}" does not match any configured source.`, "INVALID_CONFIG_FILE", "Update `defaultWriteTarget` in your config (run `akm config get defaultWriteTarget`) or run `akm list` to see configured sources.");
-    }
-    // 3. Working stash (config.stashDir / resolveStashDir()).
-    //
-    // The primary stash stays `kind: "filesystem"` on purpose, even when it is a
-    // git repo on disk (recognized elsewhere via isGitBackedStash). Returning
-    // `kind: "git"` here would fire the boundary commit on every write through
-    // this resolver, double-committing the primary stash which is already
-    // committed in a single batch at operation boundaries (e.g. the end-of-run
-    // improve auto-sync via saveGitStash). Per-write stays non-committing.
-    try {
-        const stashDir = resolveStashDir({ readOnly: true });
+        throw new ConfigError(`defaultWriteTarget "${akmConfig.defaultWriteTarget}" does not match any configured source.`, "INVALID_CONFIG_FILE", "Update `defaultWriteTarget` in your config (run `akm config get defaultWriteTarget`) or run `akm bundle list` to see configured sources.");
+    }
+    // 3. Configured default bundle.
+    return resolveWorkingStashTarget(akmConfig, options);
+}
+/** Resolve the implicit working stash without consulting `defaultWriteTarget`. */
+export function resolveWorkingStashTarget(akmConfig, options = {}) {
+    const configuredSources = resolveConfiguredSources(akmConfig);
+    const requireWritable = options.requireWritable !== false;
+    if (process.env.AKM_BUNDLE_DIR?.trim()) {
+        const stashDir = resolveStashDir();
+        const configured = configuredSources.find((source) => {
+            const sourcePath = source.source.type === "filesystem" ? source.source.path : undefined;
+            return sourcePath !== undefined && path.resolve(sourcePath) === path.resolve(stashDir);
+        });
+        if (configured) {
+            const target = adaptConfiguredSource(configured);
+            if (requireWritable && !resolveWritable(target.config)) {
+                throw new ConfigError(`Bundle "${configured.name}" is not writable.`, "INVALID_CONFIG_FILE");
+            }
+            return { ...target, selector: undefined };
+        }
+        const bundleId = deriveBundleId(undefined, stashDir, new Set(Object.keys(akmConfig.bundles ?? {})));
         return {
-            source: { kind: "filesystem", name: "stash", path: stashDir },
-            config: { type: "filesystem", path: stashDir, name: "stash", writable: true },
+            source: { kind: "filesystem", name: bundleId, path: stashDir, adapterId: detectAdapterId(stashDir) },
+            config: { type: "filesystem", name: bundleId, path: stashDir, writable: true },
         };
     }
-    catch {
-        // Fall through to the final ConfigError below.
+    const defaultBundleSource = akmConfig.defaultBundle
+        ? configuredSources.find((source) => source.name === akmConfig.defaultBundle)
+        : undefined;
+    if (!defaultBundleSource || !akmConfig.defaultBundle) {
+        throw new ConfigError("No default bundle is configured.", "INVALID_CONFIG_FILE");
+    }
+    const target = adaptConfiguredSource(defaultBundleSource);
+    if (requireWritable && !resolveWritable(target.config)) {
+        throw new ConfigError(`defaultBundle "${akmConfig.defaultBundle}" is not writable`, "INVALID_CONFIG_FILE", `Set \`writable: true\` on the "${akmConfig.defaultBundle}" bundle, or set \`defaultWriteTarget\` to a writable source.`);
     }
-    // 4. Nothing usable.
-    throw new ConfigError("no writable source configured; run `akm init`", "STASH_DIR_NOT_FOUND", "Run `akm init` to create a working stash, or set `defaultWriteTarget` in your config.");
+    return { ...target, selector: undefined };
 }
 // ── Internals ───────────────────────────────────────────────────────────────
 function ensureWritable(source, config) {
@@ -318,17 +997,26 @@ function ensureWritable(source, config) {
     }
 }
 function resolveAssetFilePath(source, ref) {
-    const typeDir = TYPE_DIRS[ref.type];
+    const basename = path.posix.basename(ref.name.replaceAll("\\", "/")).replace(/\.md$/i, "").toLowerCase();
+    if (basename === "index" || basename === "log") {
+        throw new UsageError(`Reserved concept name "${basename}" cannot be written.`, "INVALID_FLAG_VALUE");
+    }
+    const typeDir = stashDirFor(ref.type);
     if (!typeDir) {
         throw new UsageError(`Unknown asset type "${ref.type}". Cannot resolve a write path.`, "INVALID_FLAG_VALUE");
     }
     const typeRoot = path.join(source.path, typeDir);
-    const assetPath = resolveAssetPathFromName(ref.type, typeRoot, ref.name);
+    const assetPath = assetPathForName(ref.type, typeRoot, ref.name);
     if (!isWithin(assetPath, typeRoot)) {
         throw new UsageError(`Resolved asset path escapes its source: "${ref.name}" in source "${source.name}".`, "PATH_ESCAPE_VIOLATION");
     }
     return assetPath;
 }
+export function assertAkmAssetWrite(source, allowedAdapters = ["akm"]) {
+    if (!source.adapterId || allowedAdapters.includes(source.adapterId))
+        return;
+    throw new UsageError(`Bundle "${source.name}" uses adapter "${source.adapterId}", which does not support AKM asset writes.`, "INVALID_FLAG_VALUE");
+}
 /**
  * Reject any kind reaching the write/delete helpers other than the two
  * supported writable kinds. The config loader is the first line of defence
@@ -351,7 +1039,12 @@ export function formatRefForMessage(ref) {
     const origin = ref.origin ? sanitizeCommitMessage(ref.origin) : "";
     const type = sanitizeCommitMessage(ref.type);
     const name = sanitizeCommitMessage(ref.name);
-    return origin ? `${origin}//${type}:${name}` : `${type}:${name}`;
+    // 0.9.0 (Q-02): the retired `type:name` colon grammar is gone — emit the
+    // slash conceptId (`workflows/name`), qualified with `origin//` when the
+    // ref carries one. Mirrors the `displayRef`/`conceptIdFromTypeName` rule
+    // used elsewhere in this file (see `resolveAssetFilePath` callers above).
+    const conceptId = conceptIdFromTypeName(type, name);
+    return origin ? `${origin}//${conceptId}` : conceptId;
 }
 /**
  * Derive a {@link WriteTargetSource} + persisted {@link SourceConfigEntry}
@@ -362,14 +1055,8 @@ export function formatRefForMessage(ref) {
  *   ConfiguredSource.name     → WriteTargetSource.name
  *   ConfiguredSource.source.* → WriteTargetSource.path  (via parseSourceSpec)
  *
- * Legacy aliases (`context-hub`, `github`) have already been normalised to
- * `git` by the config loader, so this mapping is straightforward.
  */
 function adaptConfiguredSource(runtime) {
-    const writePath = pathFromConfiguredSource(runtime);
-    if (!writePath) {
-        throw new ConfigError(`Source "${runtime.name}" has no resolvable on-disk path; writes are unsupported for this entry.`, "INVALID_CONFIG_FILE");
-    }
     // Map the runtime kind to the write helper's `kind` discriminator. Only
     // filesystem and git produce writable sources at v1; any other kind
     // reaching this point is a config-loader bug (assertWritableAllowedForKind
@@ -380,18 +1067,47 @@ function adaptConfiguredSource(runtime) {
             "Writes are only defined for `filesystem` and `git` sources.", "INVALID_CONFIG_FILE", 'Use `kind: "filesystem"` or `kind: "git"` for writable sources.');
     }
     const kind = runtime.type;
+    // §10.2 lock-first (BEHAVIOR FIX): a managed git bundle's resolved content
+    // root lives in the lock (`localRoot`), NOT the desired config. Resolve there
+    // FIRST — via the SAME shared resolver the indexer READ path uses — so a write
+    // lands in exactly the directory a read walks; git sync/commit then runs
+    // against that same root. Before the first lock row exists, fall back to the
+    // derived cache repoDir + content/-subdir convention used by the read path.
+    const lockRoot = kind === "git" ? lockContentRootFor(runtime.name, runtime.type) : undefined;
+    const repoPath = lockRoot ?? pathFromConfiguredSource(runtime);
+    if (!repoPath) {
+        throw new ConfigError(`Source "${runtime.name}" has no resolvable on-disk path; writes are unsupported for this entry.`, "INVALID_CONFIG_FILE");
+    }
+    const contentRoot = kind === "git" ? (lockRoot ?? resolveGitContentRoot(repoPath)) : repoPath;
+    const componentRoot = path.resolve(contentRoot, runtime.componentRoot ?? ".");
+    if (!isWithin(componentRoot, contentRoot)) {
+        throw new ConfigError(`Component root "${runtime.componentRoot}" escapes bundle "${runtime.name}".`, "INVALID_CONFIG_FILE");
+    }
+    const adapterId = runtime.adapterId ?? detectAdapterId(componentRoot);
     const config = {
         type: runtime.type,
         name: runtime.name,
-        ...(writePath !== undefined ? { path: writePath } : {}),
+        path: componentRoot,
         ...(runtime.writable !== undefined ? { writable: runtime.writable } : {}),
         ...(runtime.options ? { options: runtime.options } : {}),
     };
     return {
-        source: { kind, name: runtime.name, path: writePath },
+        selector: runtime.name,
+        source: {
+            kind,
+            name: runtime.name,
+            path: componentRoot,
+            adapterId,
+            ...(kind === "git" ? { repoPath } : {}),
+        },
         config,
     };
 }
+/** Resolve the asset root inside a git checkout while preserving root-layout repos. */
+export function resolveGitContentRoot(repoPath) {
+    const contentPath = path.join(repoPath, "content");
+    return fs.existsSync(contentPath) && fs.statSync(contentPath).isDirectory() ? contentPath : repoPath;
+}
 function pathFromConfiguredSource(runtime) {
     // ConfiguredSource.source is the parsed SourceSpec (filesystem|git|website|npm).
     // For writable kinds we only ever care about a local on-disk path: filesystem