@glw907/cairn-cms 0.68.0 → 0.76.0

package/dist/sveltekit/content-routes.js

@@ -5,17 +5,16 @@
 import { redirect, error, fail } from '@sveltejs/kit';
 import { findConcept } from '../content/concepts.js';
 import { extractCairnLinks, formatCairnToken, rewriteCairnLink } from '../content/links.js';
-import { frontmatterFromForm, parseMarkdown, dateInputValue, serializeMarkdown } from '../content/frontmatter.js';
+import { extractReferenceEdges, rewriteFrontmatterReference } from '../content/references.js';
+import { buildReferenceIndex } from '../content/reference-index.js';
+import { frontmatterFromForm, formValues, parseMarkdown, dateInputValue, serializeMarkdown } from '../content/frontmatter.js';
+import { initialValues } from '../content/fieldset.js';
 import { deriveExcerpt } from '../content/excerpt.js';
 import { asString, entryIdentity } from '../content/identity.js';
 import { buildAddressIndex, mainAddressIndex, addressCollision } from '../content/advisories.js';
 import { isValidId, slugify, filenameFromId, composeDatedId, slugFromId, renameId } from '../content/ids.js';
-import { appCredentials } from '../github/credentials.js';
-import { listMarkdown, readRaw, commitFile, commitFiles } from '../github/repo.js';
-import { branchHeadSha, createBranch, deleteBranch, listBranches } from '../github/branches.js';
 import { PENDING_PREFIX, pendingBranch, parsePendingBranch } from '../content/pending.js';
-import { cachedInstallationToken } from '../github/signing.js';
-import { emptyManifest, manifestEntryFromFile, parseManifest, serializeManifest, upsertEntry, removeEntry, inboundLinks } from '../content/manifest.js';
+import { emptyManifest, manifestEntryFromFile, parseManifest, serializeManifest, upsertEntry, removeEntry, inboundLinks, inboundReferences } from '../content/manifest.js';
 import { deriveGettingStarted } from '../content/getting-started.js';
 import { markdownReference } from '../components/markdown-reference.js';
 import { isConflict } from '../github/types.js';
@@ -103,7 +102,15 @@ function conceptOf(runtime, params) {
  *
  */
 export function createContentRoutes(runtime, deps = {}) {
-    const mintToken = deps.mintToken ?? ((env) => cachedInstallationToken(appCredentials(runtime.backend, env)));
+    /**
+     * Resolve the live content backend for one request. A test seam (`deps.backend`) wins, then the
+     *  dev double's `event.locals.backend`, then the production `runtime.backend.connect(env)`. The
+     *  GitHub provider mints and caches its installation token lazily behind `connect`, so a
+     *  per-request resolve re-signs only on a cache miss.
+     */
+    function resolveBackend(event) {
+        return deps.backend ?? event.locals.backend ?? runtime.backend.connect(event.platform?.env ?? {});
+    }
     // The default Anthropic factory builds the real SDK client from the resolved key. Tests inject a fake
     // (deps.anthropic) so messages.create is stubbed and no network call or real key is ever needed. The
     // SDK client satisfies TidyClient structurally; the cast names that to the compiler.
@@ -113,8 +120,8 @@ export function createContentRoutes(runtime, deps = {}) {
      * Main's manifest, parsed. A missing file starts empty (a fresh repo before the first commit).
      *  Always read from main: pending branches carry no manifest copy.
      */
-    async function readManifest(token) {
-        const raw = await readRaw(runtime.backend, runtime.manifestPath, token);
+    async function readManifest(backend) {
+        const raw = await backend.readFile(runtime.manifestPath, backend.defaultBranch);
         return raw === null ? emptyManifest() : parseManifest(raw);
     }
     /**
@@ -162,8 +169,8 @@ export function createContentRoutes(runtime, deps = {}) {
         // than failing the whole admin shell or showing a wrong publish-all count.
         let pendingEntries = null;
         try {
-            const token = await mintToken(event.platform?.env ?? {});
-            const names = await listBranches(runtime.backend, PENDING_PREFIX, token);
+            const backend = resolveBackend(event);
+            const names = await backend.listBranches(PENDING_PREFIX);
             pendingEntries = names.flatMap((name) => {
                 const entry = pendingEntryOf(name);
                 return entry ? [{ concept: entry.concept.id, id: entry.id }] : [];
@@ -196,9 +203,9 @@ export function createContentRoutes(runtime, deps = {}) {
         let manifest = emptyManifest();
         let pending = [];
         try {
-            const token = await mintToken(event.platform?.env ?? {});
-            manifest = await readManifest(token);
-            const names = await listBranches(runtime.backend, PENDING_PREFIX, token);
+            const backend = resolveBackend(event);
+            manifest = await readManifest(backend);
+            const names = await backend.listBranches(PENDING_PREFIX);
             pending = names.flatMap((name) => {
                 const entry = pendingEntryOf(name);
                 return entry ? [{ concept: entry.concept.id, id: entry.id }] : [];
@@ -224,9 +231,9 @@ export function createContentRoutes(runtime, deps = {}) {
      * Read a file's frontmatter for its list row, degrading to the id on any read failure. The
      *  repo defaults to main; a pending entry (edited or branch-only) passes its pending branch.
      */
-    async function summarize(file, token, status, repo = runtime.backend) {
+    async function summarize(file, backend, status, ref = backend.defaultBranch) {
         try {
-            const raw = await readRaw(repo, file.path, token);
+            const raw = await backend.readFile(file.path, ref);
             if (raw === null)
                 return { id: file.id, title: file.id, date: null, draft: false, status, summary: null };
             const { frontmatter, body } = parseMarkdown(raw);
@@ -246,22 +253,19 @@ export function createContentRoutes(runtime, deps = {}) {
      *  in the list instead of reading as a lost save. summarize degrades a failed or empty read to
      *  an id-only row, so a ghost ref still lists.
      */
-    function pendingRow(concept, id, status, token) {
-        return summarize({ id, path: `${concept.dir}/${filenameFromId(id)}` }, token, status, {
-            ...runtime.backend,
-            branch: pendingBranch(concept.id, id),
-        });
+    function pendingRow(concept, id, status, backend) {
+        return summarize({ id, path: `${concept.dir}/${filenameFromId(id)}` }, backend, status, pendingBranch(concept.id, id));
     }
     /**
      * The per-file crawl, kept only for a repo with no committed manifest yet: list main's files
      *  and read each one for its row, with edited and new rows reading branch-first.
      */
-    async function crawlEntries(concept, pendingIds, token) {
-        const files = await listMarkdown(runtime.backend, concept.dir, token);
-        const entries = await Promise.all(files.map((f) => (pendingIds.has(f.id) ? pendingRow(concept, f.id, 'edited', token) : summarize(f, token, 'published'))));
+    async function crawlEntries(concept, pendingIds, backend) {
+        const files = await backend.readEntries(concept.dir, backend.defaultBranch);
+        const entries = await Promise.all(files.map((f) => (pendingIds.has(f.id) ? pendingRow(concept, f.id, 'edited', backend) : summarize(f, backend, 'published'))));
         // A ref with no main file is a never-published entry; its row reads from its branch.
         const listed = new Set(files.map((f) => f.id));
-        const newRows = await Promise.all([...pendingIds].filter((id) => !listed.has(id)).map((id) => pendingRow(concept, id, 'new', token)));
+        const newRows = await Promise.all([...pendingIds].filter((id) => !listed.has(id)).map((id) => pendingRow(concept, id, 'new', backend)));
         return [...entries, ...newRows];
     }
     /**
@@ -279,17 +283,11 @@ export function createContentRoutes(runtime, deps = {}) {
         const publishedAllRaw = event.url.searchParams.get('publishedAll');
         const publishedAll = publishedAllRaw !== null && /^\d+$/.test(publishedAllRaw) ? Number(publishedAllRaw) : null;
         const base = { conceptId: concept.id, label: concept.label, singular: concept.singular, dated: concept.routing.dated, formError, publishedAll };
-        let token;
-        try {
-            token = await mintToken(event.platform?.env ?? {});
-        }
-        catch {
-            return { ...base, entries: [], error: 'Could not authenticate with GitHub.' };
-        }
+        const backend = resolveBackend(event);
         try {
             const [manifestRaw, refs] = await Promise.all([
-                readRaw(runtime.backend, runtime.manifestPath, token),
-                listBranches(runtime.backend, `${PENDING_PREFIX}${concept.id}/`, token),
+                backend.readFile(runtime.manifestPath, backend.defaultBranch),
+                backend.listBranches(`${PENDING_PREFIX}${concept.id}/`),
             ]);
             const pendingIds = new Set(refs.flatMap((name) => {
                 const entry = pendingEntryOf(name);
@@ -298,17 +296,17 @@ export function createContentRoutes(runtime, deps = {}) {
             // A repo with no committed manifest yet (a fresh site before its first publish) falls back
             // to the crawl; a manifest that parses but is empty is trusted as-is.
             if (manifestRaw === null) {
-                return { ...base, entries: await crawlEntries(concept, pendingIds, token), error: null };
+                return { ...base, entries: await crawlEntries(concept, pendingIds, backend), error: null };
             }
             // Newest id first, the same order the crawl's file listing produced.
             const rows = parseManifest(manifestRaw)
                 .entries.filter((e) => e.concept === concept.id)
                 .sort((a, b) => b.id.localeCompare(a.id));
             const entries = await Promise.all(rows.map((e) => pendingIds.has(e.id)
-                ? pendingRow(concept, e.id, 'edited', token)
+                ? pendingRow(concept, e.id, 'edited', backend)
                 : { id: e.id, title: e.title, date: e.date ?? null, draft: e.draft, status: 'published', summary: e.summary ?? null }));
             const listed = new Set(rows.map((e) => e.id));
-            const newRows = await Promise.all([...pendingIds].filter((id) => !listed.has(id)).map((id) => pendingRow(concept, id, 'new', token)));
+            const newRows = await Promise.all([...pendingIds].filter((id) => !listed.has(id)).map((id) => pendingRow(concept, id, 'new', backend)));
             return { ...base, entries: [...entries, ...newRows], error: null };
         }
         catch {
@@ -342,28 +340,24 @@ export function createContentRoutes(runtime, deps = {}) {
         else if (event.url.searchParams.get('orphansPurged') === '1')
             flash = 'orphansPurged';
         const flashError = event.url.searchParams.get('error');
-        let token;
-        try {
-            token = await mintToken(event.platform?.env ?? {});
-        }
-        catch {
-            return { assets: [], usage: {}, error: 'Could not authenticate with GitHub.', flash, flashError };
-        }
+        const backend = resolveBackend(event);
         // Union the media manifest by hash: main's rows first, then any branch hash not already present.
         // Identical bytes share one row, so a hash on both branches prefers main's row. A failed or
         // absent branch read degrades to no rows for that branch (the tolerant parse yields {} on null).
         // The branch list is taken ONCE here and handed to buildUsageIndex below, so the load path does
         // not enumerate the open branches twice (the per-page subrequest budget is tight at ~25+ branches).
+        // The token mint is now lazy inside the first read, so a token or a network failure both land in
+        // this one degrade rather than the old separate could-not-authenticate tier.
         const union = new Map();
         let branchNames = [];
         try {
-            const mediaRaw = await readRaw(runtime.backend, runtime.mediaManifestPath, token);
+            const mediaRaw = await backend.readFile(runtime.mediaManifestPath, backend.defaultBranch);
             for (const [hash, e] of Object.entries(parseMediaManifest(parseMediaJson(mediaRaw)))) {
                 union.set(hash, e);
             }
-            const names = await listBranches(runtime.backend, PENDING_PREFIX, token);
+            const names = await backend.listBranches(PENDING_PREFIX);
             branchNames = names;
-            const branchManifests = await Promise.all(names.map((name) => readRaw({ ...runtime.backend, branch: name }, runtime.mediaManifestPath, token)
+            const branchManifests = await Promise.all(names.map((name) => backend.readFile(runtime.mediaManifestPath, name)
                 .then((raw) => parseMediaManifest(parseMediaJson(raw)))
                 .catch(() => ({}))));
             for (const manifest of branchManifests) {
@@ -383,11 +377,11 @@ export function createContentRoutes(runtime, deps = {}) {
         // here keeps the asset list intact with an empty overlay, since the screen still lists assets.
         let usage = {};
         try {
-            const manifestRaw = await readRaw(runtime.backend, runtime.manifestPath, token);
+            const manifestRaw = await backend.readFile(runtime.manifestPath, backend.defaultBranch);
             const manifest = manifestRaw === null ? emptyManifest() : parseManifest(manifestRaw);
             // Reuse the branch list from the media-union above; the Library DISPLAY keeps the default
             // best-effort behavior (a failed branch read degrades that one branch, not the screen).
-            const index = await buildUsageIndex(runtime.backend, token, runtime.concepts, manifest, { branches: branchNames });
+            const index = await buildUsageIndex(backend, runtime.concepts, manifest, { branches: branchNames });
             for (const [hash, entries] of index) {
                 usage[hash] = { count: distinctEntryCount(entries), entries };
             }
@@ -418,36 +412,16 @@ export function createContentRoutes(runtime, deps = {}) {
             }
             id = composeDatedId(date, slug, concept.datePrefix);
         }
-        const token = await mintToken(event.platform?.env ?? {});
-        const existing = await readRaw(runtime.backend, `${concept.dir}/${filenameFromId(id)}`, token);
+        const backend = resolveBackend(event);
+        const existing = await backend.readFile(`${concept.dir}/${filenameFromId(id)}`, backend.defaultBranch);
         if (existing !== null)
             return bounce('An entry with that slug already exists.');
         // A pending branch is an entry too (saved but not yet published); refuse to clobber it.
-        if ((await branchHeadSha(runtime.backend, pendingBranch(concept.id, id), token)) !== null) {
+        if ((await backend.branchHead(pendingBranch(concept.id, id))) !== null) {
             return bounce('An unpublished entry with that slug already exists.');
         }
         throw redirect(303, `/admin/${concept.id}/${id}?new=1`);
     }
-    /** Coerce parsed frontmatter to the form-ready values the editor inputs expect. */
-    function formValues(fields, frontmatter) {
-        const out = {};
-        for (const field of fields) {
-            const value = frontmatter[field.name];
-            if (field.type === 'date')
-                out[field.name] = dateInputValue(value);
-            else if (field.type === 'boolean')
-                out[field.name] = value === true;
-            else if (field.type === 'tags' || field.type === 'freetags')
-                out[field.name] = Array.isArray(value) ? value.map(String) : [];
-            // A hero is a nested object; the default String() arm would corrupt it to '[object Object]'.
-            // Hand the stored object back as-is so the editor reads .src/.alt/.caption on open.
-            else if (field.type === 'image')
-                out[field.name] = value !== null && typeof value === 'object' ? value : undefined;
-            else
-                out[field.name] = typeof value === 'string' ? value : value == null ? '' : String(value);
-        }
-        return out;
-    }
     /** Open a file for editing. A `?new=1` miss yields a blank document; any other miss is a 404. */
     async function editLoad(event) {
         requireSession(event);
@@ -456,7 +430,7 @@ export function createContentRoutes(runtime, deps = {}) {
         if (!isValidId(id))
             throw error(400, 'Invalid entry id');
         const isNew = event.url.searchParams.get('new') === '1';
-        const token = await mintToken(event.platform?.env ?? {});
+        const backend = resolveBackend(event);
         const datePrefix = concept.routing.dated ? concept.datePrefix : null;
         const path = `${concept.dir}/${filenameFromId(id)}`;
         // A pending entry reads branch-first: the editor shows the unpublished edits. The manifest
@@ -473,20 +447,25 @@ export function createContentRoutes(runtime, deps = {}) {
         // rejected read degrades to null so the edit never throws on a missing or unreadable dictionary;
         // the projection below treats null as an empty word list (the editor falls back to dialect-only).
         const [headSha, mainRaw, manifestRaw, mediaRaw, dictionaryRaw] = await Promise.all([
-            branchHeadSha(runtime.backend, branch, token),
-            readRaw(runtime.backend, path, token),
-            readRaw(runtime.backend, runtime.manifestPath, token),
+            backend.branchHead(branch),
+            backend.readFile(path, backend.defaultBranch),
+            backend.readFile(runtime.manifestPath, backend.defaultBranch),
             runtime.resolvedAssets.enabled
-                ? readRaw(runtime.backend, runtime.mediaManifestPath, token).catch(() => null)
+                ? backend.readFile(runtime.mediaManifestPath, backend.defaultBranch).catch(() => null)
                 : Promise.resolve(null),
-            readRaw(runtime.backend, dictionaryFilePath(), token).catch(() => null),
+            backend.readFile(dictionaryFilePath(), backend.defaultBranch).catch(() => null),
         ]);
         const pending = headSha !== null;
-        const raw = pending ? await readRaw({ ...runtime.backend, branch }, path, token) : mainRaw;
+        const raw = pending ? await backend.readFile(path, branch) : mainRaw;
         if (raw === null && !isNew)
             throw error(404, 'Entry not found');
         const published = mainRaw !== null;
         const parsed = raw === null ? { frontmatter: {}, body: '' } : parseMarkdown(raw);
+        // A fresh entry opens prefilled from each field's `default`, resolving a `'today'` date against a
+        // request-time clock. The defaults sit under the empty parsed frontmatter, never over a real read.
+        const loadFrontmatter = isNew
+            ? { ...initialValues(concept.schema, new Date()), ...parsed.frontmatter }
+            : parsed.frontmatter;
         const title = typeof parsed.frontmatter.title === 'string' && parsed.frontmatter.title.trim() ? parsed.frontmatter.title : id;
         const manifest = manifestRaw !== null ? parseManifest(manifestRaw) : null;
         let linkTargets = [];
@@ -544,7 +523,7 @@ export function createContentRoutes(runtime, deps = {}) {
             id,
             label: concept.label,
             fields: concept.fields,
-            frontmatter: formValues(concept.fields, parsed.frontmatter),
+            frontmatter: formValues(concept.fields, loadFrontmatter),
             body: parsed.body,
             title,
             isNew,
@@ -630,7 +609,7 @@ export function createContentRoutes(runtime, deps = {}) {
             throw redirect(303, `/admin/${concept.id}/${id}?error=${encodeURIComponent(message)}${suffix}`);
         }
         const markdown = serializeMarkdown(result.data, body);
-        const token = await mintToken(event.platform?.env ?? {});
+        const backend = resolveBackend(event);
         // Merge the editor's optimistic media records into the media manifest, gated on media being on
         // and at least one valid record posted. The base is read from the default branch (never the
         // pending branch), so each save's union starts from main's committed rows, and decision 1's
@@ -641,7 +620,7 @@ export function createContentRoutes(runtime, deps = {}) {
         if (runtime.resolvedAssets.enabled) {
             const records = parseMediaEntries(form.get('media'));
             if (records.length > 0) {
-                const baseRaw = await readRaw(runtime.backend, runtime.mediaManifestPath, token);
+                const baseRaw = await backend.readFile(runtime.mediaManifestPath, backend.defaultBranch);
                 let mediaManifest = parseMediaManifest(parseMediaJson(baseRaw));
                 for (const record of records) {
                     mediaManifest = upsertMediaEntry(mediaManifest, record);
@@ -651,7 +630,7 @@ export function createContentRoutes(runtime, deps = {}) {
         }
         // Upsert this entry's row into main's manifest in memory, for the link guard here and for
         // the publish commit. The save commits no manifest change; publish lands the upsert on main.
-        const manifest = await readManifest(token);
+        const manifest = await readManifest(backend);
         const row = manifestEntryFromFile(concept, { path, raw: markdown });
         const upserted = upsertEntry(manifest, row);
         // Save guard: resolve the body's cairn links against main's manifest with this entry upserted,
@@ -681,26 +660,41 @@ export function createContentRoutes(runtime, deps = {}) {
                 body,
             });
         }
+        // Frontmatter reference warning: classify each typed reference edge against the same upserted
+        // manifest. This is best-effort against the committed (possibly stale) main manifest and advisory
+        // like draftLinks, NEVER the integrity guarantee; references have no prerender re-resolve backstop,
+        // so verifyReferences at the build is the only authority. A reference NEVER blocks the save: unlike
+        // a body link, an absent or draft target only warns, since the build gate fails a true dangling.
+        const referenceWarnings = [];
+        for (const edge of extractReferenceEdges(result.data, concept.fields)) {
+            if (edge.concept === concept.id && edge.id === id)
+                continue;
+            const target = byKey.get(`${edge.concept}/${edge.id}`);
+            if (!target || target.draft)
+                referenceWarnings.push(`${edge.concept}/${edge.id}`);
+        }
         // Ensure the entry's pending branch exists (cut lazily from main's head on first save), then
         // commit only the entry file there. Main stays untouched until publish, so the branch differs
         // from main at exactly this entry's path.
         const branch = pendingBranch(concept.id, id);
-        if ((await branchHeadSha(runtime.backend, branch, token)) === null) {
-            const mainHead = await branchHeadSha(runtime.backend, runtime.backend.branch, token);
+        if ((await backend.branchHead(branch)) === null) {
+            // The default-branch head read distinguishes a first save from a re-save; a null is the
+            // unreadable-default-branch case the create cannot recover from, so fail with the 500.
+            const mainHead = await backend.branchHead(backend.defaultBranch);
             if (mainHead === null)
                 throw error(500, 'Cannot read the default branch');
-            await createBranch(runtime.backend, branch, mainHead, token);
+            await backend.createBranch(branch, backend.defaultBranch);
         }
         const commitFields = { concept: concept.id, id, editor: editor.email, branch };
         let branchSha;
         try {
-            branchSha = await commitFiles({ ...runtime.backend, branch }, mediaChange ? [{ path, content: markdown }, mediaChange] : [{ path, content: markdown }], { message: `Update ${concept.label.toLowerCase()}: ${id}`, author: { name: editor.displayName, email: editor.email } }, token);
+            branchSha = await backend.commit(branch, mediaChange ? [{ path, content: markdown }, mediaChange] : [{ path, content: markdown }], { name: editor.displayName, email: editor.email }, `Update ${concept.label.toLowerCase()}: ${id}`);
             log.info('commit.succeeded', commitFields);
         }
         catch (err) {
             commitFailure(commitFields, err, `/admin/${concept.id}/${id}`, 'This file changed since you opened it. Reload and reapply your edits.', { query: suffix });
         }
-        return { path, markdown, branch, branchSha, manifest: upserted, draftLinks, token, mediaChange };
+        return { path, markdown, branch, branchSha, manifest: upserted, draftLinks, referenceWarnings, backend, mediaChange };
     }
     /**
      * Save an edit: validate, then commit to the entry's pending branch with the session editor
@@ -717,9 +711,11 @@ export function createContentRoutes(runtime, deps = {}) {
         const held = await saveToBranch(event, editor, concept, id);
         if (!('branchSha' in held))
             return held;
-        const savedQuery = held.draftLinks.length
+        let savedQuery = held.draftLinks.length
             ? `saved=1&drafts=${encodeURIComponent(held.draftLinks.join(','))}`
             : 'saved=1';
+        if (held.referenceWarnings.length)
+            savedQuery += `&refs=${encodeURIComponent(held.referenceWarnings.join(','))}`;
         throw redirect(303, `/admin/${concept.id}/${id}?${savedQuery}`);
     }
     /**
@@ -739,7 +735,7 @@ export function createContentRoutes(runtime, deps = {}) {
         const held = await saveToBranch(event, editor, concept, id);
         if (!('branchSha' in held))
             return held;
-        const { path, markdown, branch, branchSha, manifest, token, mediaChange } = held;
+        const { path, markdown, branch, branchSha, manifest, backend, mediaChange } = held;
         // The publish commit reuses the exact merged media.json saveToBranch already built (decision 1:
         // no re-read or re-merge here). Promote it to main alongside the body and the content manifest
         // in one atomic commit, or commit those two alone when the save touched no media.
@@ -758,7 +754,7 @@ export function createContentRoutes(runtime, deps = {}) {
         try {
             const { frontmatter } = parseMarkdown(markdown);
             address = entryIdentity(concept, path, frontmatter).permalink;
-            const addressIndex = await buildAddressIndex(runtime.backend, token, runtime.concepts, manifest);
+            const addressIndex = await buildAddressIndex(backend, runtime.concepts, manifest);
             collision = addressCollision(addressIndex, { concept: concept.id, id }, address);
         }
         catch (err) {
@@ -769,7 +765,7 @@ export function createContentRoutes(runtime, deps = {}) {
         }
         const commitFields = { concept: concept.id, id, editor: editor.email };
         try {
-            await commitFiles(runtime.backend, changes, { message: `Publish ${concept.label.toLowerCase()}: ${id}`, author: { name: editor.displayName, email: editor.email } }, token);
+            await backend.commit(backend.defaultBranch, changes, { name: editor.displayName, email: editor.email }, `Publish ${concept.label.toLowerCase()}: ${id}`);
             log.info('entry.published', { ...commitFields, batch: false });
             // Only after the publish lands: a diagnostic that a live address now has a new owner.
             if (collision) {
@@ -788,8 +784,8 @@ export function createContentRoutes(runtime, deps = {}) {
         // Only after the main commit lands, and only when the branch head is still the commit this
         // action made: a head that moved is a concurrent save, and deleting it would destroy edits.
         // No log event for the skip; the pending badge is the surface.
-        if ((await branchHeadSha(runtime.backend, branch, token)) === branchSha) {
-            await deleteBranch(runtime.backend, branch, token);
+        if ((await backend.branchHead(branch)) === branchSha) {
+            await backend.deleteBranch(branch);
         }
         throw redirect(303, `/admin/${concept.id}/${id}?published=1`);
     }
@@ -804,11 +800,11 @@ export function createContentRoutes(runtime, deps = {}) {
         const first = runtime.concepts[0];
         if (!first)
             throw error(404, 'No content types configured');
-        const token = await mintToken(event.platform?.env ?? {});
+        const backend = resolveBackend(event);
         const listPage = `/admin/${first.id}`;
         // Each cairn/ ref names a pending entry; the shared predicate skips a stray ref rather
         // than failing the whole batch on it.
-        const names = await listBranches(runtime.backend, PENDING_PREFIX, token);
+        const names = await backend.listBranches(PENDING_PREFIX);
         const pending = names.flatMap((name) => {
             const entry = pendingEntryOf(name);
             return entry ? [{ ...entry, branch: name, path: `${entry.concept.dir}/${filenameFromId(entry.id)}` }] : [];
@@ -819,13 +815,13 @@ export function createContentRoutes(runtime, deps = {}) {
         // entry stays pending). A ghost ref whose entry file is missing is skipped (discard can
         // clean it up); it carries nothing to publish.
         const reads = await Promise.all(pending.map(async (entry) => {
-            const sha = await branchHeadSha(runtime.backend, entry.branch, token);
-            const raw = await readRaw({ ...runtime.backend, branch: entry.branch }, entry.path, token);
+            const sha = await backend.branchHead(entry.branch);
+            const raw = await backend.readFile(entry.path, entry.branch);
             return { ...entry, sha, raw };
         }));
         // Fold main's manifest once over every row, so the batch lands content and index together,
         // the same shape as a single publish.
-        let next = await readManifest(token);
+        let next = await readManifest(backend);
         const changes = [];
         const published = [];
         for (const entry of reads) {
@@ -842,7 +838,7 @@ export function createContentRoutes(runtime, deps = {}) {
         changes.push({ path: runtime.manifestPath, content: serializeManifest(next) });
         const noun = published.length === 1 ? 'entry' : 'entries';
         try {
-            await commitFiles(runtime.backend, changes, { message: `Publish ${published.length} ${noun}`, author: { name: editor.displayName, email: editor.email } }, token);
+            await backend.commit(backend.defaultBranch, changes, { name: editor.displayName, email: editor.email }, `Publish ${published.length} ${noun}`);
             for (const entry of published) {
                 log.info('entry.published', { concept: entry.concept, id: entry.id, editor: editor.email, batch: true });
             }
@@ -866,8 +862,8 @@ export function createContentRoutes(runtime, deps = {}) {
         // abort the remaining deletes.
         for (const entry of published) {
             try {
-                if ((await branchHeadSha(runtime.backend, entry.branch, token)) === entry.sha) {
-                    await deleteBranch(runtime.backend, entry.branch, token);
+                if ((await backend.branchHead(entry.branch)) === entry.sha) {
+                    await backend.deleteBranch(entry.branch);
                 }
             }
             catch {
@@ -886,10 +882,10 @@ export function createContentRoutes(runtime, deps = {}) {
         const id = event.params.id ?? '';
         if (!isValidId(id))
             throw error(400, 'Invalid entry id');
-        const token = await mintToken(event.platform?.env ?? {});
-        await deleteBranch(runtime.backend, pendingBranch(concept.id, id), token);
+        const backend = resolveBackend(event);
+        await backend.deleteBranch(pendingBranch(concept.id, id));
         log.info('entry.discarded', { concept: concept.id, id, editor: editor.email });
-        const onMain = await readRaw(runtime.backend, `${concept.dir}/${filenameFromId(id)}`, token);
+        const onMain = await backend.readFile(`${concept.dir}/${filenameFromId(id)}`, backend.defaultBranch);
         if (onMain !== null)
             throw redirect(303, `/admin/${concept.id}/${id}?discarded=1`);
         throw redirect(303, `/admin/${concept.id}`);
@@ -903,10 +899,10 @@ export function createContentRoutes(runtime, deps = {}) {
      */
     async function deleteEntry(event, concept, id, editor) {
         const path = `${concept.dir}/${filenameFromId(id)}`;
-        const token = await mintToken(event.platform?.env ?? {});
+        const backend = resolveBackend(event);
         // An absent manifest degrades the inbound gate to "allow": with no manifest there is nothing to
         // check, and the build's cairn: backstop still catches any dangling token, mirroring saveAction.
-        const manifest = await readManifest(token);
+        const manifest = await readManifest(backend);
         const inbound = inboundLinks(manifest, concept.id, id);
         if (inbound.length) {
             return fail(409, {
@@ -915,22 +911,55 @@ export function createContentRoutes(runtime, deps = {}) {
                 id,
             });
         }
+        // Cross-branch reference gate (fail-closed). A strict reference index unions main's published edges
+        // and every open cairn/* branch; unlike the main-only body-link gate above, it does NOT degrade to
+        // allow when it cannot read, because the build's verifyReferences backstop only sees main. A
+        // transient branch-read failure that looked like "no references" would let a delete strand an
+        // inbound edge held in an unpublished draft, so refuse with a 503 rather than proceed.
+        let refIndex;
+        try {
+            refIndex = await buildReferenceIndex(backend, runtime.concepts, manifest, { strict: true });
+        }
+        catch {
+            return fail(503, {
+                error: 'Could not verify where this entry is referenced. Try again.',
+                inboundLinks: [],
+                id,
+            });
+        }
+        const refRows = refIndex.get(`${concept.id}/${id}`) ?? [];
+        if (refRows.length > 0) {
+            // Carry each referencing entry into the InboundLink shape the blockers list renders. A branch row
+            // has no permalink (the edit is unpublished), so default it to empty.
+            const referencingEntries = refRows.map((row) => ({
+                concept: row.concept,
+                id: row.id,
+                title: row.title,
+                permalink: row.permalink ?? '',
+            }));
+            const n = referencingEntries.length;
+            return fail(409, {
+                error: `Cannot delete ${id}: ${n} ${n === 1 ? 'entry references' : 'entries reference'} it.`,
+                inboundLinks: referencingEntries,
+                id,
+            });
+        }
         // When the entry was never published (absent from main), the branch delete is the whole
         // operation; main has nothing to commit, so the only honest log record is the discard of
         // the pending edits.
-        const onMain = await readRaw(runtime.backend, path, token);
+        const onMain = await backend.readFile(path, backend.defaultBranch);
         if (onMain === null) {
-            await deleteBranch(runtime.backend, pendingBranch(concept.id, id), token);
+            await backend.deleteBranch(pendingBranch(concept.id, id));
             log.info('entry.discarded', { concept: concept.id, id, editor: editor.email });
             throw redirect(303, `/admin/${concept.id}`);
         }
         const nextManifest = serializeManifest(removeEntry(manifest, concept.id, id));
         const commitFields = { concept: concept.id, id, editor: editor.email };
         try {
-            await commitFiles(runtime.backend, [
+            await backend.commit(backend.defaultBranch, [
                 { path, content: null },
                 { path: runtime.manifestPath, content: nextManifest },
-            ], { message: `Delete ${concept.label.toLowerCase()}: ${id}`, author: { name: editor.displayName, email: editor.email } }, token);
+            ], { name: editor.displayName, email: editor.email }, `Delete ${concept.label.toLowerCase()}: ${id}`);
             log.info('commit.succeeded', commitFields);
         }
         catch (err) {
@@ -941,7 +970,7 @@ export function createContentRoutes(runtime, deps = {}) {
         // recoverable (it lists as a never-published row a discard can clean up), matching
         // publish's posture, so the entry's deletion still completes.
         try {
-            await deleteBranch(runtime.backend, pendingBranch(concept.id, id), token);
+            await backend.deleteBranch(pendingBranch(concept.id, id));
         }
         catch {
             // The entry is gone from main; the straggler shows as a pending row until discarded.
@@ -979,10 +1008,10 @@ export function createContentRoutes(runtime, deps = {}) {
         const id = event.params.id ?? '';
         if (!isValidId(id))
             throw error(400, 'Invalid entry id');
-        const token = await mintToken(event.platform?.env ?? {});
+        const backend = resolveBackend(event);
         // Pending edits on the branch are keyed to the old id; renaming underneath them would strand
         // them, so refuse until the editor publishes or discards.
-        if ((await branchHeadSha(runtime.backend, pendingBranch(concept.id, id), token)) !== null) {
+        if ((await backend.branchHead(pendingBranch(concept.id, id))) !== null) {
             return fail(409, { error: 'This entry has unpublished edits. Publish or discard them, then rename.' });
         }
         const form = await event.request.formData();
@@ -1003,45 +1032,103 @@ export function createContentRoutes(runtime, deps = {}) {
         // Collision guard: refuse if a file already exists at the new path. This 409 covers two cases a
         // single readRaw cannot tell apart: a static collision with an existing entry, and a
         // concurrent-rename race where another editor renamed onto this path between load and submit.
-        const clobber = await readRaw(runtime.backend, newPath, token);
+        const clobber = await backend.readFile(newPath, backend.defaultBranch);
         if (clobber !== null) {
             return fail(409, { error: 'An entry with that slug already exists.' });
         }
         const [entryRaw, manifest] = await Promise.all([
-            readRaw(runtime.backend, oldPath, token),
-            readManifest(token),
+            backend.readFile(oldPath, backend.defaultBranch),
+            readManifest(backend),
         ]);
         if (entryRaw === null)
             throw error(404, 'Entry not found');
+        // Cross-branch reference gate (fail-closed). A reference index unions main's published edges and
+        // every open cairn/* branch; if it cannot be built (a transient branch read failure), refuse
+        // rather than rename a still-referenced target and strand the inbound edge.
+        let refIndex;
+        try {
+            refIndex = await buildReferenceIndex(backend, runtime.concepts, manifest, { strict: true });
+        }
+        catch {
+            return fail(409, { error: 'Could not verify references. Try again.' });
+        }
+        // Refuse when a THIRD-PARTY open branch holds an inbound reference (symmetric with the pending-edits
+        // guard). The strict index unions main and every branch, so filter before refusing: gate
+        // origin.kind === 'branch' FIRST (a published row has no .branch, so a bare branch-name compare would
+        // trip on every main-side inbound and over-refuse), then exclude the entry's OWN pending branch
+        // (already refused above and absent by construction here). Published (main) inbound rows are NOT
+        // refused; they are repointed below.
+        const ownBranch = pendingBranch(concept.id, id);
+        const conflictBranches = (refIndex.get(`${concept.id}/${id}`) ?? [])
+            .filter((row) => row.origin.kind === 'branch' && row.origin.branch !== ownBranch)
+            .map((row) => `${row.concept}/${row.id}`);
+        if (conflictBranches.length > 0) {
+            const names = [...new Set(conflictBranches)].join(', ');
+            return fail(409, { error: `Another editor has unpublished edits referencing this entry: ${names}. Ask them to publish or discard, then rename.` });
+        }
         const oldHref = formatCairnToken({ concept: concept.id, id });
         const newHref = formatCairnToken({ concept: concept.id, id: newId });
-        // The moved file keeps its content, except a self-token rewrite. Re-derive its manifest row from
-        // the new path so the row carries the new id and permalink by construction.
-        const movedRaw = rewriteCairnLink(entryRaw, oldHref, newHref);
+        // The moved file keeps its content, except a self-token rewrite and a self-reference rewrite.
+        let movedRaw = rewriteCairnLink(entryRaw, oldHref, newHref);
+        // The moved entry is excluded from inboundReferences, so it must repoint its OWN frontmatter
+        // self-references (e.g. `related` listing its own old id), or the re-derived row would carry the
+        // old id and verifyReferences would flag a dangling edge at the deploy gate.
+        for (const f of concept.fields) {
+            if (f.type === 'reference' || (f.type === 'array' && f.item.type === 'reference')) {
+                movedRaw = rewriteFrontmatterReference(movedRaw, f.name, id, newId);
+            }
+        }
+        // Re-derive its manifest row from the new path so the row carries the new id and permalink by
+        // construction (and the rewritten self-reference edge at the new id).
         const changes = [
             { path: oldPath, content: null },
             { path: newPath, content: movedRaw },
         ];
         let next = removeEntry(manifest, concept.id, id);
         next = upsertEntry(next, manifestEntryFromFile(concept, { path: newPath, raw: movedRaw }));
-        // Rewrite every inbound linker's body and re-derive its row, so its outbound edge points at the
-        // new id. A linker missing from the repo is skipped; the build backstop catches any drift.
+        const repoints = new Map();
+        const linkerPathFor = (linkerConcept, linkerId) => `${linkerConcept.dir}/${filenameFromId(linkerId)}`;
         for (const linker of inboundLinks(manifest, concept.id, id)) {
             const linkerConcept = findConcept(runtime.concepts, linker.concept);
             if (!linkerConcept)
                 continue;
-            const linkerPath = `${linkerConcept.dir}/${filenameFromId(linker.id)}`;
-            const linkerRaw = await readRaw(runtime.backend, linkerPath, token);
+            const path = linkerPathFor(linkerConcept, linker.id);
+            const existing = repoints.get(path);
+            if (existing)
+                existing.hasLink = true;
+            else
+                repoints.set(path, { concept: linker.concept, id: linker.id, hasLink: true, fields: [] });
+        }
+        for (const linker of inboundReferences(manifest, concept.id, id)) {
+            const linkerConcept = findConcept(runtime.concepts, linker.concept);
+            if (!linkerConcept)
+                continue;
+            const path = linkerPathFor(linkerConcept, linker.id);
+            const existing = repoints.get(path);
+            if (existing)
+                existing.fields = [...new Set([...existing.fields, ...linker.fields])];
+            else
+                repoints.set(path, { concept: linker.concept, id: linker.id, hasLink: false, fields: linker.fields });
+        }
+        for (const [linkerPath, repoint] of repoints) {
+            const linkerConcept = findConcept(runtime.concepts, repoint.concept);
+            if (!linkerConcept)
+                continue;
+            let linkerRaw = await backend.readFile(linkerPath, backend.defaultBranch);
             if (linkerRaw === null)
                 continue;
-            const rewritten = rewriteCairnLink(linkerRaw, oldHref, newHref);
-            changes.push({ path: linkerPath, content: rewritten });
-            next = upsertEntry(next, manifestEntryFromFile(linkerConcept, { path: linkerPath, raw: rewritten }));
+            if (repoint.hasLink)
+                linkerRaw = rewriteCairnLink(linkerRaw, oldHref, newHref);
+            for (const field of repoint.fields) {
+                linkerRaw = rewriteFrontmatterReference(linkerRaw, field, id, newId);
+            }
+            changes.push({ path: linkerPath, content: linkerRaw });
+            next = upsertEntry(next, manifestEntryFromFile(linkerConcept, { path: linkerPath, raw: linkerRaw }));
         }
         changes.push({ path: runtime.manifestPath, content: serializeManifest(next) });
         const commitFields = { concept: concept.id, id: newId, editor: editor.email };
         try {
-            await commitFiles(runtime.backend, changes, { message: `Rename ${concept.label.toLowerCase()}: ${id} to ${newId}`, author: { name: editor.displayName, email: editor.email } }, token);
+            await backend.commit(backend.defaultBranch, changes, { name: editor.displayName, email: editor.email }, `Rename ${concept.label.toLowerCase()}: ${id} to ${newId}`);
             log.info('commit.succeeded', commitFields);
         }
         catch (err) {
@@ -1201,14 +1288,14 @@ export function createContentRoutes(runtime, deps = {}) {
      */
     async function mediaDeleteAction(event) {
         const editor = requireSession(event);
-        const token = await mintToken(event.platform?.env ?? {});
+        const backend = resolveBackend(event);
         const form = await event.request.formData();
         const hash = String(form.get('hash') ?? '');
         if (!MEDIA_HASH_RE.test(hash))
             throw error(400, 'Invalid media hash');
         // The asset must be committed on the default branch to be deletable here. A branch-only upload
         // (the common 2b case before publish) has no main row; removing it is a discard of the draft.
-        const manifest = parseMediaManifest(parseMediaJson(await readRaw(runtime.backend, runtime.mediaManifestPath, token)));
+        const manifest = parseMediaManifest(parseMediaJson(await backend.readFile(runtime.mediaManifestPath, backend.defaultBranch)));
         const row = manifest[hash];
         if (!row) {
             return fail(404, {
@@ -1224,7 +1311,7 @@ export function createContentRoutes(runtime, deps = {}) {
         // make a still-referenced asset look orphaned and skip the typed-slug confirm.
         let index;
         try {
-            index = await buildUsageIndex(runtime.backend, token, runtime.concepts, await readManifest(token), { strict: true });
+            index = await buildUsageIndex(backend, runtime.concepts, await readManifest(backend), { strict: true });
         }
         catch {
             // Fail closed: we could not verify every place the asset is used, so refuse rather than risk
@@ -1272,7 +1359,7 @@ export function createContentRoutes(runtime, deps = {}) {
         // Commit the manifest row removal FIRST. The order is load-bearing (see the docstring).
         const commitFields = { concept: 'media', id: hash, editor: editor.email };
         try {
-            await commitFiles(runtime.backend, [{ path: runtime.mediaManifestPath, content: serializeMediaManifest(removeMediaEntry(manifest, hash)) }], { message: `Delete media: ${row.slug}`, author: { name: editor.displayName, email: editor.email } }, token);
+            await backend.commit(backend.defaultBranch, [{ path: runtime.mediaManifestPath, content: serializeMediaManifest(removeMediaEntry(manifest, hash)) }], { name: editor.displayName, email: editor.email }, `Delete media: ${row.slug}`);
             log.info('commit.succeeded', commitFields);
         }
         catch (err) {
@@ -1306,7 +1393,7 @@ export function createContentRoutes(runtime, deps = {}) {
      */
     async function mediaBulkDelete(event) {
         const editor = requireSession(event);
-        const token = await mintToken(event.platform?.env ?? {});
+        const backend = resolveBackend(event);
         // Read the selected hashes from the form. Accept the repeated `hash` field, falling back to a JSON
         // `hashes` array. Each value must match the 16-hex content-hash grammar; a malformed value is
         // dropped silently rather than surfaced as a skip (it was never a real selection).
@@ -1327,7 +1414,7 @@ export function createContentRoutes(runtime, deps = {}) {
         }
         const selected = raw.filter((h) => MEDIA_HASH_RE.test(h));
         // Read the fresh media manifest (the deletable rows come from here, by hash).
-        const manifest = parseMediaManifest(parseMediaJson(await readRaw(runtime.backend, runtime.mediaManifestPath, token)));
+        const manifest = parseMediaManifest(parseMediaJson(await backend.readFile(runtime.mediaManifestPath, backend.defaultBranch)));
         // Resolve the R2 bucket before any write, so a media-off site or a missing binding refuses before
         // the commit, exactly like single delete.
         const resolved = runtime.resolvedAssets;
@@ -1345,7 +1432,7 @@ export function createContentRoutes(runtime, deps = {}) {
         // mistaking a still-referenced asset for an orphan. Build exactly one index, never one per item.
         let index;
         try {
-            index = await buildUsageIndex(runtime.backend, token, runtime.concepts, await readManifest(token), { strict: true });
+            index = await buildUsageIndex(backend, runtime.concepts, await readManifest(backend), { strict: true });
         }
         catch {
             return fail(503, { error: 'Could not verify where these assets are used. Try again.' });
@@ -1362,7 +1449,7 @@ export function createContentRoutes(runtime, deps = {}) {
             next = removeMediaEntry(next, hash);
         const commitFields = { concept: 'media', id: 'bulk', editor: editor.email };
         try {
-            await commitFiles(runtime.backend, [{ path: runtime.mediaManifestPath, content: serializeMediaManifest(next) }], { message: `Delete ${plan.deletable.length} media assets`, author: { name: editor.displayName, email: editor.email } }, token);
+            await backend.commit(backend.defaultBranch, [{ path: runtime.mediaManifestPath, content: serializeMediaManifest(next) }], { name: editor.displayName, email: editor.email }, `Delete ${plan.deletable.length} media assets`);
             log.info('commit.succeeded', commitFields);
         }
         catch (err) {
@@ -1405,7 +1492,7 @@ export function createContentRoutes(runtime, deps = {}) {
      */
     async function mediaOrphanScan(event) {
         requireSession(event);
-        const token = await mintToken(event.platform?.env ?? {});
+        const backend = resolveBackend(event);
         // Resolve the R2 binding. The reconcile lists the raw bucket directly, so keep the raw binding;
         // the MediaStore seam carries no list. A media-off site or a missing binding refuses the scan.
         const resolved = runtime.resolvedAssets;
@@ -1418,7 +1505,7 @@ export function createContentRoutes(runtime, deps = {}) {
             return fail(503, { error: 'The media bucket is not bound.' });
         }
         // Read the fresh media manifest for the reconcile's manifest side.
-        const manifest = parseMediaManifest(parseMediaJson(await readRaw(runtime.backend, runtime.mediaManifestPath, token)));
+        const manifest = parseMediaManifest(parseMediaJson(await backend.readFile(runtime.mediaManifestPath, backend.defaultBranch)));
         // THE detection-time fail-closed surface. The reconcile (an R2 list that must complete in full)
         // and the strict usage build (a branch read that must complete in full) are both unsafe to use
         // partially, so either throwing refuses the scan. A wrong orphan verdict from a partial read here
@@ -1427,7 +1514,7 @@ export function createContentRoutes(runtime, deps = {}) {
         let index;
         try {
             reconcile = await runReconcile(rawBucket, manifest);
-            index = await buildUsageIndex(runtime.backend, token, runtime.concepts, await readManifest(token), { strict: true });
+            index = await buildUsageIndex(backend, runtime.concepts, await readManifest(backend), { strict: true });
         }
         catch {
             return fail(503, { error: 'Could not check where files are used, so the scan was not run. Try again.' });
@@ -1463,7 +1550,7 @@ export function createContentRoutes(runtime, deps = {}) {
      */
     async function mediaPurgeOrphans(event) {
         const editor = requireSession(event);
-        const token = await mintToken(event.platform?.env ?? {});
+        const backend = resolveBackend(event);
         // Resolve the R2 binding, the same media-off / missing-binding refusals as the scan. The purge
         // deletes through the MediaStore seam, so wrap the raw binding.
         const resolved = runtime.resolvedAssets;
@@ -1486,14 +1573,14 @@ export function createContentRoutes(runtime, deps = {}) {
             return fail(400, { error: 'Type the number of files to confirm the purge.' });
         }
         // Re-derive fresh against the current manifest, so a key claimed since the scan is never purged.
-        const manifest = parseMediaManifest(parseMediaJson(await readRaw(runtime.backend, runtime.mediaManifestPath, token)));
+        const manifest = parseMediaManifest(parseMediaJson(await backend.readFile(runtime.mediaManifestPath, backend.defaultBranch)));
         // THE fail-closed gate for the whole batch: one shared strict cross-branch usage index, symmetric
         // with the scan and the bulk delete. STRICT mode rethrows a branch-read failure, so a transient
         // branch read refuses the irreversible purge rather than letting a possibly-referenced byte be
         // treated as a true orphan. Build exactly one index, never one per key.
         let index;
         try {
-            index = await buildUsageIndex(runtime.backend, token, runtime.concepts, await readManifest(token), { strict: true });
+            index = await buildUsageIndex(backend, runtime.concepts, await readManifest(backend), { strict: true });
         }
         catch {
             return fail(503, { error: 'Could not verify where these files are used. Try again.' });
@@ -1536,12 +1623,12 @@ export function createContentRoutes(runtime, deps = {}) {
      */
     async function mediaUpdateAction(event) {
         const editor = requireSession(event);
-        const token = await mintToken(event.platform?.env ?? {});
+        const backend = resolveBackend(event);
         const form = await event.request.formData();
         const hash = String(form.get('hash') ?? '');
         if (!MEDIA_HASH_RE.test(hash))
             throw error(400, 'Invalid media hash');
-        const manifest = parseMediaManifest(parseMediaJson(await readRaw(runtime.backend, runtime.mediaManifestPath, token)));
+        const manifest = parseMediaManifest(parseMediaJson(await backend.readFile(runtime.mediaManifestPath, backend.defaultBranch)));
         const row = manifest[hash];
         if (!row) {
             return fail(404, { error: 'That asset is not committed.' });
@@ -1555,7 +1642,7 @@ export function createContentRoutes(runtime, deps = {}) {
         const edited = { ...row, displayName: displayName || slug, slug, alt };
         const commitFields = { concept: 'media', id: hash, editor: editor.email };
         try {
-            await commitFiles(runtime.backend, [{ path: runtime.mediaManifestPath, content: serializeMediaManifest(upsertMediaEntry(manifest, edited)) }], { message: `Update media: ${edited.slug}`, author: { name: editor.displayName, email: editor.email } }, token);
+            await backend.commit(backend.defaultBranch, [{ path: runtime.mediaManifestPath, content: serializeMediaManifest(upsertMediaEntry(manifest, edited)) }], { name: editor.displayName, email: editor.email }, `Update media: ${edited.slug}`);
             log.info('commit.succeeded', commitFields);
         }
         catch (err) {
@@ -1608,8 +1695,8 @@ export function createContentRoutes(runtime, deps = {}) {
         if (!MEDIA_HASH_RE.test(oldHash) || !MEDIA_HASH_RE.test(newHash)) {
             return fail(400, { error: 'Invalid media hash.', hash: oldHash, usage: [], foundIn: 0 });
         }
-        const token = await mintToken(event.platform?.env ?? {});
-        const contentManifest = await readManifest(token);
+        const backend = resolveBackend(event);
+        const contentManifest = await readManifest(backend);
         const newToken = replacementToken(slug, newHash);
         // Plan the rewrite. The planner runs buildUsageIndex in STRICT mode, so an unverifiable branch read
         // throws out of here rather than degrading to an absent reference; catch it and fail closed, the
@@ -1617,8 +1704,7 @@ export function createContentRoutes(runtime, deps = {}) {
         let plan;
         try {
             plan = await planMediaRewrite({
-                backend: runtime.backend,
-                token,
+                backend,
                 concepts: runtime.concepts,
                 contentManifest,
                 hash: oldHash,
@@ -1665,7 +1751,7 @@ export function createContentRoutes(runtime, deps = {}) {
      */
     async function mediaReplaceApply(event) {
         const editor = requireSession(event);
-        const token = await mintToken(event.platform?.env ?? {});
+        const backend = resolveBackend(event);
         const form = await event.request.formData();
         const oldHash = String(form.get('oldHash') ?? '');
         const newHash = String(form.get('newHash') ?? '');
@@ -1685,7 +1771,7 @@ export function createContentRoutes(runtime, deps = {}) {
         }
         // The old asset must be committed on main to be replaceable here. A branch-only upload has no main
         // row; it is replaced by editing its draft, not here.
-        const manifest = parseMediaManifest(parseMediaJson(await readRaw(runtime.backend, runtime.mediaManifestPath, token)));
+        const manifest = parseMediaManifest(parseMediaJson(await backend.readFile(runtime.mediaManifestPath, backend.defaultBranch)));
         const row = manifest[oldHash];
         if (!row) {
             return fail(404, {
@@ -1710,10 +1796,9 @@ export function createContentRoutes(runtime, deps = {}) {
         let plan;
         try {
             plan = await planMediaRewrite({
-                backend: runtime.backend,
-                token,
+                backend,
                 concepts: runtime.concepts,
-                contentManifest: await readManifest(token),
+                contentManifest: await readManifest(backend),
                 hash: oldHash,
                 transform: (md) => repointMediaRef(md, oldHash, newToken),
             });
@@ -1743,7 +1828,7 @@ export function createContentRoutes(runtime, deps = {}) {
         changes.push({ path: runtime.mediaManifestPath, content: serializeMediaManifest(upsertMediaEntry(manifest, record)) });
         const commitFields = { concept: 'media', id: oldHash, editor: editor.email };
         try {
-            await commitFiles(runtime.backend, changes, { message: `Replace media: ${row.slug}`, author: { name: editor.displayName, email: editor.email } }, token);
+            await backend.commit(backend.defaultBranch, changes, { name: editor.displayName, email: editor.email }, `Replace media: ${row.slug}`);
             log.info('media.replaced', { editor: editor.email, oldHash, newHash, affected: plan.affectedCount });
         }
         catch (err) {
@@ -1782,22 +1867,21 @@ export function createContentRoutes(runtime, deps = {}) {
         if (!MEDIA_HASH_RE.test(hash)) {
             return fail(400, { error: 'Invalid media hash.' });
         }
-        const token = await mintToken(event.platform?.env ?? {});
+        const backend = resolveBackend(event);
         // The default alt to propagate is the asset's manifest row value (set via mediaUpdateAction). An
         // asset with no committed row has no default alt to push, so refuse.
-        const mediaManifest = parseMediaManifest(parseMediaJson(await readRaw(runtime.backend, runtime.mediaManifestPath, token)));
+        const mediaManifest = parseMediaManifest(parseMediaJson(await backend.readFile(runtime.mediaManifestPath, backend.defaultBranch)));
         const row = mediaManifest[hash];
         if (!row) {
             return fail(404, { error: 'That asset is not committed.' });
         }
         // Plan the fill. The planner runs strict, so an unverifiable branch read throws out of here; catch
         // it and fail closed, the same posture replace and delete take.
-        const contentManifest = await readManifest(token);
+        const contentManifest = await readManifest(backend);
         let plan;
         try {
             plan = await planMediaRewrite({
-                backend: runtime.backend,
-                token,
+                backend,
                 concepts: runtime.concepts,
                 contentManifest,
                 hash,
@@ -1843,14 +1927,14 @@ export function createContentRoutes(runtime, deps = {}) {
      */
     async function mediaAltApply(event) {
         const editor = requireSession(event);
-        const token = await mintToken(event.platform?.env ?? {});
+        const backend = resolveBackend(event);
         const form = await event.request.formData();
         const hash = String(form.get('hash') ?? '');
         if (!MEDIA_HASH_RE.test(hash))
             throw error(400, 'Invalid media hash');
         // The opt-in to also overwrite customized alts; absent (the default) leaves custom alts alone.
         const overwrite = form.get('overwrite') === 'on' || form.get('overwrite') === 'true';
-        const mediaManifest = parseMediaManifest(parseMediaJson(await readRaw(runtime.backend, runtime.mediaManifestPath, token)));
+        const mediaManifest = parseMediaManifest(parseMediaJson(await backend.readFile(runtime.mediaManifestPath, backend.defaultBranch)));
         const row = mediaManifest[hash];
         if (!row) {
             return fail(404, { error: 'That asset is not committed.' });
@@ -1864,10 +1948,9 @@ export function createContentRoutes(runtime, deps = {}) {
         let plan;
         try {
             plan = await planMediaRewrite({
-                backend: runtime.backend,
-                token,
+                backend,
                 concepts: runtime.concepts,
-                contentManifest: await readManifest(token),
+                contentManifest: await readManifest(backend),
                 hash,
                 transform: (md) => fillAltForHash(md, hash, row.alt, { overwrite }),
             });
@@ -1884,7 +1967,7 @@ export function createContentRoutes(runtime, deps = {}) {
         const changes = changed.map((e) => ({ path: e.path, content: e.newMarkdown }));
         const commitFields = { concept: 'media', id: hash, editor: editor.email };
         try {
-            await commitFiles(runtime.backend, changes, { message: `Propagate alt: ${row.slug}`, author: { name: editor.displayName, email: editor.email } }, token);
+            await backend.commit(backend.defaultBranch, changes, { name: editor.displayName, email: editor.email }, `Propagate alt: ${row.slug}`);
             log.info('media.alt_propagated', { editor: editor.email, hash, overwrite, written: changed.length });
         }
         catch (err) {
@@ -1908,21 +1991,21 @@ export function createContentRoutes(runtime, deps = {}) {
      *  the canonical file back. Shared by the first attempt and the post-conflict retry, so both re-read
      *  the head and re-merge the same additions; the merge is order-independent, so a concurrent editor's
      *  word that already landed is preserved and the result is the same sorted set regardless of order.
-     *  Returns the merged word list. Throws CommitConflictError (via commitFiles) when the branch moves
-     *  under the commit, which the caller catches to retry once.
+     *  Returns the merged word list. Throws CommitConflictError (via backend.commit) when the branch
+     *  moves under the commit, which the caller catches to retry once.
      */
-    async function mergeAndCommitDictionary(token, additions, editor) {
+    async function mergeAndCommitDictionary(backend, additions, editor) {
         const path = dictionaryFilePath();
         // The existing file as its canonical sorted set, so a no-op add is detected against the same
         // normalization the commit would write (an already-sorted file never re-commits just to reorder).
-        const canonicalExisting = mergeDictionaryWords(parseDictionary(await readRaw(runtime.backend, path, token)), []);
+        const canonicalExisting = mergeDictionaryWords(parseDictionary(await backend.readFile(path, backend.defaultBranch)), []);
         const merged = mergeDictionaryWords(canonicalExisting, additions);
         // Nothing new (every addition was already present): skip the commit so an idempotent add never
         // pushes an empty commit that would redeploy the site. The merged set is still returned so the
         // client reconciles its pending additions away.
         if (merged.length === canonicalExisting.length)
             return merged;
-        await commitFiles(runtime.backend, [{ path, content: serializeDictionary(merged) }], { message: `Add to dictionary: ${additions.join(', ')}`, author: { name: editor.displayName, email: editor.email } }, token);
+        await backend.commit(backend.defaultBranch, [{ path, content: serializeDictionary(merged) }], { name: editor.displayName, email: editor.email }, `Add to dictionary: ${additions.join(', ')}`);
         return merged;
     }
     /**
@@ -1970,8 +2053,8 @@ export function createContentRoutes(runtime, deps = {}) {
     /**
      * Save the editor-tier tidy conventions: validate the posted block, then read-modify-commit it into
      *  the same committed YAML the nav editor writes, with the session editor as author. The transport is
-     *  the nav save's exactly: a form POST carrying the conventions JSON, the read-modify-commit through
-     *  `commitFile`, and a stale-SHA `isConflict` bounced back as a reload prompt. Only the conventions
+     *  the nav save's exactly: a form POST carrying the conventions JSON, a head-guarded
+     *  `backend.commit`, and a stale-head `isConflict` bounced back as a reload prompt. Only the conventions
      *  block is written (setTidy leaves `tidy.enabled` and `tidy.model` untouched), so an editor's save can
      *  never flip the developer-tier deploy facts. The save refuses before any commit when tidy is not
      *  enabled, so the gate state's absent editor tier can never be saved past.
@@ -1992,15 +2075,20 @@ export function createContentRoutes(runtime, deps = {}) {
             throw redirect(303, `/admin/settings?error=${encodeURIComponent(message)}`);
         }
         const path = siteConfigPath();
-        const token = await mintToken(event.platform?.env ?? {});
-        const raw = await readRaw(runtime.backend, path, token);
+        const backend = resolveBackend(event);
+        // Read the head BEFORE the content, so this expectedHead is at-or-before the bytes the commit
+        // merges. The settings write lands on the default branch and triggers a deploy, so it is
+        // fail-closed: a concurrent commit to the config moves the head off this value and the commit
+        // throws a conflict, surfacing the reload-and-reapply prompt below rather than a last-writer-wins.
+        const head = await backend.branchHead(backend.defaultBranch);
+        const raw = await backend.readFile(path, backend.defaultBranch);
         if (raw === null)
             throw error(404, 'Site config not found');
         // Parse first so a malformed file fails before the write rather than committing onto a broken base.
         parseSiteConfig(raw);
         const commitFields = { concept: 'settings', id: 'tidy', editor: editor.email };
         try {
-            await commitFile(runtime.backend, path, setTidy(raw, conventions), { message: 'Update tidy settings', author: { name: editor.displayName, email: editor.email } }, token);
+            await backend.commit(backend.defaultBranch, [{ path, content: setTidy(raw, conventions) }], { name: editor.displayName, email: editor.email }, 'Update tidy settings', head ?? undefined);
             log.info('commit.succeeded', commitFields);
         }
         catch (err) {
@@ -2021,7 +2109,7 @@ export function createContentRoutes(runtime, deps = {}) {
      *  `{ words }`. It reads the current file from the default branch, inserts the validated words in
      *  sorted order if absent (idempotent), and commits through the GitHub-App pipeline.
      *
-     *  The commit is SHA-guarded with commit-and-retry: commitFiles throws CommitConflictError when the
+     *  The commit is SHA-guarded with commit-and-retry: backend.commit throws CommitConflictError when the
      *  branch moved under it, which is caught here to re-read the new head, re-merge the same additions
      *  (the sorted insert is order-independent, so a concurrent editor's word is preserved), and retry
      *  once. The response is the merged word list, so the client drops the now-committed words from its
@@ -2056,10 +2144,10 @@ export function createContentRoutes(runtime, deps = {}) {
         if (additions.length === 0) {
             return fail(400, { error: 'No valid word to add to the dictionary.' });
         }
-        const token = await mintToken(event.platform?.env ?? {});
+        const backend = resolveBackend(event);
         const commitFields = { concept: 'dictionary', id: additions[0], editor: editor.email };
         try {
-            const words = await mergeAndCommitDictionary(token, additions, editor);
+            const words = await mergeAndCommitDictionary(backend, additions, editor);
             log.info('dictionary.added', { editor: editor.email, words: additions });
             return { words };
         }
@@ -2070,7 +2158,7 @@ export function createContentRoutes(runtime, deps = {}) {
             // retry once. The merge is order-independent, so a concurrent editor's word that landed in the
             // window is preserved and the two adds converge on the same sorted set.
             try {
-                const words = await mergeAndCommitDictionary(token, additions, editor);
+                const words = await mergeAndCommitDictionary(backend, additions, editor);
                 log.info('dictionary.added', { editor: editor.email, words: additions, retried: true });
                 return { words };
             }
@@ -2194,7 +2282,7 @@ export function createContentRoutes(runtime, deps = {}) {
         log.info('tidy.done', { editor: editor.email, model: message.model, usage: message.usage });
         return { corrected, model: message.model, usage: message.usage };
     }
-    return { layoutLoad, helpLoad, indexRedirect, listLoad, mediaLibraryLoad, settingsLoad, settingsSave, createAction, editLoad, saveAction, publishAction, publishAllAction, discardAction, deleteAction, listDeleteAction, renameAction, uploadAction, mediaDeleteAction, mediaBulkDelete, mediaOrphanScan, mediaPurgeOrphans, mediaUpdateAction, mediaReplacePreview, mediaReplaceApply, mediaAltPreview, mediaAltApply, addDictionaryWord, tidyAction, mintToken };
+    return { layoutLoad, helpLoad, indexRedirect, listLoad, mediaLibraryLoad, settingsLoad, settingsSave, createAction, editLoad, saveAction, publishAction, publishAllAction, discardAction, deleteAction, listDeleteAction, renameAction, uploadAction, mediaDeleteAction, mediaBulkDelete, mediaOrphanScan, mediaPurgeOrphans, mediaUpdateAction, mediaReplacePreview, mediaReplaceApply, mediaAltPreview, mediaAltApply, addDictionaryWord, tidyAction };
 }
 /**
  * The cap, in characters, on the stored alt text. The human fields are display copy, not content,