@drawnagency/primitives 0.1.114 → 0.1.115

package/src/lib/sidecars.ts

@@ -0,0 +1,221 @@
+import type { ZodType } from "zod";
+import { NavEntrySchema, NavFileSchema, type NavEntry } from "../schemas/nav";
+import { TagEntrySchema, TagsFileSchema, type TagEntry } from "../schemas/tags";
+import type { SiteIndex } from "../schemas/site-config";
+import { reconcileNavReport } from "./nav-tree";
+import { mergeTags, reconcileTagsReport } from "./tags";
+import type { SidecarDiagnostic } from "./sidecar-diagnostics";
+
+export type { SidecarDiagnostic };
+
+/**
+ * One definition per Sidecar — a content file kept beside index.json rather than
+ * on it, so a writer that predates it cannot drop it (CONTEXT.md). Every rule a
+ * caller would otherwise re-implement per file lives behind these: lenient
+ * parse, lifting the wire key off an index before IndexSchema strips it, and the
+ * two places the Sidecars genuinely differ — how a list is repaired against the
+ * index, and how concurrent edits rebase. Pure and browser-safe: the editor uses
+ * it during hydration, and callers do their own I/O.
+ */
+export interface SidecarDefinition<E> {
+  /** Also the key the Sidecar travels under on the wire (`index.nav`, `index.tags`). */
+  name: "nav" | "tags";
+  path: string;
+  /** The key holding the entry list inside the file. */
+  fileKey: "entries" | "tags";
+  entrySchema: ZodType<E>;
+  fileSchema: ZodType<unknown>;
+  /** Total, pure and idempotent; also reports what it repaired. */
+  reconcile(entries: E[], index: SiteIndex): { entries: E[]; diagnostics: SidecarDiagnostic[] };
+  /** The list after a collab rebase; `undefined` when no side carries one. */
+  rebase(args: { base: E[] | undefined; local: E[] | undefined; remote: E[] | undefined }): E[] | undefined;
+  /** Words for a declined write's warning. */
+  words: {
+    /** What the file holds: "navigation entries". */
+    entries: string;
+    /** What did not land: "Page grouping changes". */
+    changes: string;
+    /** What a valid payload is: "a valid navigation tree". */
+    valid: string;
+    /** The expected wire shape, for an agent that sent the wrong one. */
+    shape: string;
+  };
+}
+
+export const NAV: SidecarDefinition<NavEntry> = {
+  name: "nav",
+  path: "src/content/nav.json",
+  fileKey: "entries",
+  entrySchema: NavEntrySchema,
+  fileSchema: NavFileSchema,
+  reconcile: (entries, index) => reconcileNavReport(entries, index.pages),
+  // Grouping is edited rarely and has no dirty tracking, so persisted remote
+  // state beats unsaved local edits. A remote without the Sidecar (an older
+  // server) keeps ours rather than flattening it.
+  rebase: ({ local, remote }) => (remote !== undefined ? remote : local),
+  words: {
+    entries: "navigation entries",
+    changes: "Page grouping changes",
+    valid: "a valid navigation tree",
+    shape: 'an array of {kind:"page",pageId} / {kind:"group",id,label,startCollapsed,pageIds} entries',
+  },
+};
+
+export const TAGS: SidecarDefinition<TagEntry> = {
+  name: "tags",
+  path: "src/content/tags.json",
+  fileKey: "tags",
+  entrySchema: TagEntrySchema,
+  fileSchema: TagsFileSchema,
+  reconcile: (entries, index) => reconcileTagsReport(entries, index.sections),
+  // Tagging is edited from every section's chrome, so remote-wins would drop
+  // unsaved tagging whenever a peer saved anything. See mergeTags.
+  rebase: mergeTags,
+  words: {
+    entries: "tag entries",
+    changes: "Tag changes",
+    valid: "a valid tag list",
+    shape: "an array of {id,label,sectionIds} entries",
+  },
+};
+
+// Widened once here: the definitions are invariant in their entry type, so a
+// loop over both needs the common type.
+export const SIDECARS: readonly SidecarDefinition<unknown>[] = [NAV, TAGS] as readonly SidecarDefinition<unknown>[];
+
+/**
+ * A Sidecar as read. `degraded` means the file was present but held something
+ * this package version could not represent, so `entries` is missing it: the read
+ * is a Degraded read, never to be cached, posted back, or written over the file.
+ */
+export type SidecarRead<E> = { entries: E[]; degraded: boolean };
+
+/**
+ * Tolerance is per entry: one unknown entry kind (a newer package's addition, an
+ * authoring typo) drops that entry alone, not every group or tag on the site.
+ */
+function readEntries<E>(def: SidecarDefinition<E>, raw: unknown): SidecarRead<E> {
+  if (!Array.isArray(raw)) {
+    console.warn(`[sidecars] ${def.name}: entry list is not a list; reading it as empty and degraded`);
+    return { entries: [], degraded: true };
+  }
+  const entries: E[] = [];
+  let dropped = 0;
+  for (const item of raw) {
+    const parsed = def.entrySchema.safeParse(item);
+    if (parsed.success) entries.push(parsed.data);
+    else dropped++;
+  }
+  if (dropped > 0) {
+    console.warn(`[sidecars] ${def.name}: dropped ${dropped} entr${dropped === 1 ? "y" : "ies"} this package version cannot represent; the read is degraded`);
+  }
+  return { entries, degraded: dropped > 0 };
+}
+
+/** Read a parsed Sidecar file. Absent (null/undefined) is an empty list, not degraded. */
+export function readSidecar<E>(def: SidecarDefinition<E>, file: unknown): SidecarRead<E> {
+  if (file === undefined || file === null) return { entries: [], degraded: false };
+  return readEntries(def, (file as Record<string, unknown>)[def.fileKey]);
+}
+
+/**
+ * Read a Sidecar file's raw text. Present-but-unparseable JSON is degraded, not
+ * absent: a site whose nav.json is corrupt still has groups, and treating it as
+ * "never had any" would let a writer replace them.
+ */
+export function readSidecarText<E>(def: SidecarDefinition<E>, text: string | undefined): SidecarRead<E> {
+  if (text === undefined) return { entries: [], degraded: false };
+  let file: unknown;
+  try {
+    file = JSON.parse(text);
+  } catch {
+    console.warn(`[sidecars] ${def.name}: ${def.path} is not valid JSON; the read is degraded`);
+    return { entries: [], degraded: true };
+  }
+  return readSidecar(def, file);
+}
+
+/**
+ * Lift the Sidecars off an index as it arrives on the wire, BEFORE anything
+ * parses it with IndexSchema — the parse strips unknown keys, and an index
+ * round-tripped through it has lost its Sidecars. A key the index does not carry
+ * is `undefined` (omitted: writers leave the file alone); a carried key is read
+ * with the file's per-entry leniency, into fresh objects that never alias the
+ * caller's.
+ */
+export function liftSidecars(rawIndex: unknown): { nav?: SidecarRead<NavEntry>; tags?: SidecarRead<TagEntry> } {
+  const raw = rawIndex !== null && typeof rawIndex === "object" ? (rawIndex as Record<string, unknown>) : {};
+  return {
+    ...(raw.nav !== undefined ? { nav: readEntries(NAV, raw.nav) } : {}),
+    ...(raw.tags !== undefined ? { tags: readEntries(TAGS, raw.tags) } : {}),
+  };
+}
+
+/** The Sidecar file on the branch a write lands on, as the writer read it. */
+export type SidecarFileState =
+  | { kind: "absent" }
+  | { kind: "present"; text: string }
+  /** The read itself failed, so nothing is known about the file. */
+  | { kind: "unreadable" };
+
+export type SidecarWritePlan =
+  | { action: "untouched" }
+  | { action: "write"; path: string; content: string }
+  /** Declined. The rest of the write still lands, so the warning is what tells the caller. */
+  | { action: "skip"; warning: string };
+
+/**
+ * What a write does to one Sidecar file, given what was posted (from
+ * liftSidecars) and the file on the branch. Every Sidecar write REPLACES the
+ * file, and the posted list was built from what this package version could
+ * READ — so a file holding anything this version cannot fully parse (an entry
+ * from a newer package, or a corrupt file) is read-only: replacing it would
+ * destroy those entries with a clean write. The same holds for a posted
+ * Degraded read.
+ *
+ * Emptiness is judged on the POSTED list, before reconcile: an empty list never
+ * creates a file (every editor save carries the Sidecars, and nav's reconcile
+ * would turn [] into the page list), while an empty list over an existing file
+ * replaces it wholesale. A written list is reconciled against the index being
+ * written, so it never names a page or section that write removed.
+ */
+export function planSidecarWrite<E>(
+  def: SidecarDefinition<E>,
+  posted: SidecarRead<E> | undefined,
+  branch: SidecarFileState,
+  index: SiteIndex,
+): SidecarWritePlan {
+  if (posted === undefined) return { action: "untouched" };
+  const skip = (reason: string): SidecarWritePlan => ({
+    action: "skip",
+    warning: `${def.path} was left unchanged: ${reason} ${def.words.changes} from this save did not land. Upgrade the site's @drawnagency packages (or repair ${def.path} directly in the repo), then retry.`,
+  });
+
+  if (posted.degraded) {
+    // Leaving the file alone is the right action; saying nothing is not — an
+    // agent that posted a malformed list would otherwise believe it landed.
+    return {
+      action: "skip",
+      warning: `${def.name} was not ${def.words.valid}, so ${def.path} was left unchanged (it held entries this package version cannot read). Expected ${def.words.shape}.`,
+    };
+  }
+  if (branch.kind === "unreadable") {
+    return skip("the current file could not be read to confirm the replacement loses nothing.");
+  }
+  if (branch.kind === "present") {
+    let existing: unknown;
+    try {
+      existing = JSON.parse(branch.text);
+    } catch {
+      return skip("the current file is not valid JSON, so this version cannot prove a replacement keeps its entries.");
+    }
+    if (!def.fileSchema.safeParse(existing).success) {
+      return skip(`the current file holds ${def.words.entries} this package version cannot represent (likely written by a newer version).`);
+    }
+  } else if (posted.entries.length === 0) {
+    return { action: "untouched" };
+  }
+
+  const { entries } = def.reconcile(posted.entries, index);
+  return { action: "write", path: def.path, content: JSON.stringify({ [def.fileKey]: entries }, null, 2) };
+}

package/src/lib/slug.ts

@@ -0,0 +1,6 @@
+// The one slugifier for page slugs and media names. Its own leaf, with no
+// imports, so the media worker can use it without bundling the schemas
+// lib/pages pulls in.
+export function slugifyPageSlug(input: string): string {
+  return input.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}

package/src/lib/storage-tier.ts

@@ -0,0 +1,38 @@
+import { DOCUMENT_GIT_MAX_BYTES, DOCUMENT_BUCKET_MAX_BYTES } from "../schemas/documents";
+import { MEDIA_GIT_MAX_BYTES, MEDIA_BUCKET_MAX_BYTES, type MediaConfig } from "../schemas/media";
+
+// Where a file's bytes live, decided by its size: committed to the site repo
+// (git), stored in the optional bucket, or refused. Every upload path and the
+// write path's backstop decide this the same way, and every message quotes the
+// limits through formatBytes, so a limit changes in one place.
+
+export { DOCUMENT_GIT_MAX_BYTES, DOCUMENT_BUCKET_MAX_BYTES, MEDIA_GIT_MAX_BYTES, MEDIA_BUCKET_MAX_BYTES };
+
+/**
+ * The MCP connector's own document ceiling, half the bucket cap. The binding
+ * constraint is memory, not time: a presigned PUT cannot stream, so the whole
+ * body is buffered (peak about 2x the file). The browser path has no such
+ * limit because those bytes never pass through a function.
+ */
+export const DOCUMENT_CONNECTOR_MAX_BYTES = 104_857_600;
+
+export type StorageTier = "git" | "bucket" | "too_large";
+
+type MediaLimits = Pick<MediaConfig, "maxFileSize" | "maxAssetSize">;
+
+/** Media limits come from the site's `media` config; documents' are fixed. */
+export function tierFor(
+  kind: "document" | "media",
+  bytes: number,
+  media: MediaLimits = { maxFileSize: MEDIA_GIT_MAX_BYTES, maxAssetSize: MEDIA_BUCKET_MAX_BYTES },
+): StorageTier {
+  const [gitMax, bucketMax] =
+    kind === "document" ? [DOCUMENT_GIT_MAX_BYTES, DOCUMENT_BUCKET_MAX_BYTES] : [media.maxFileSize, media.maxAssetSize];
+  if (bytes <= gitMax) return "git";
+  return bytes <= bucketMax ? "bucket" : "too_large";
+}
+
+/** "2.5 MB", "100 MB" — one decimal at most, in binary megabytes. */
+export function formatBytes(bytes: number): string {
+  return `${Math.round((bytes / 1024 / 1024) * 10) / 10} MB`;
+}

package/src/lib/tags.ts

@@ -1,5 +1,6 @@
 import type { TagEntry } from "../schemas/tags";
 import type { SiteIndex } from "../schemas/site-config";
+import { diagnosticsCollector, type SidecarDiagnostic } from "./sidecar-diagnostics";
 
 /**
  * Repair the tag sidecar against the current section set.
@@ -19,6 +20,15 @@ import type { SiteIndex } from "../schemas/site-config";
  * React state, where a shared array would let a later edit mutate prior state).
  */
 export function reconcileTags(entries: TagEntry[], sections: SiteIndex["sections"]): TagEntry[] {
+  return reconcileTagsReport(entries, sections).entries;
+}
+
+/** reconcileTags plus what the repair changed — what a validator reports. */
+export function reconcileTagsReport(
+  entries: TagEntry[],
+  sections: SiteIndex["sections"],
+): { entries: TagEntry[]; diagnostics: SidecarDiagnostic[] } {
+  const report = diagnosticsCollector();
   const entryList = Array.isArray(entries) ? entries : [];
   const validIds = new Set(sections && typeof sections === "object" ? Object.keys(sections) : []);
 
@@ -26,17 +36,24 @@ export function reconcileTags(entries: TagEntry[], sections: SiteIndex["sections
   const result: TagEntry[] = [];
   for (const entry of entryList) {
     if (!entry || typeof entry !== "object") continue;
-    if (typeof entry.id !== "string" || entry.id === "" || seenTagIds.has(entry.id)) continue;
+    if (typeof entry.id !== "string" || entry.id === "") continue;
+    if (seenTagIds.has(entry.id)) {
+      report.add("duplicate-id", entry.id);
+      continue;
+    }
     seenTagIds.add(entry.id);
 
     const claimed = Array.isArray(entry.sectionIds) ? entry.sectionIds : [];
     const sectionIds: string[] = [];
     for (const id of claimed) {
-      if (typeof id === "string" && validIds.has(id) && !sectionIds.includes(id)) sectionIds.push(id);
+      if (typeof id !== "string") continue;
+      if (!validIds.has(id)) report.add("dangling", id);
+      else if (sectionIds.includes(id)) report.add("duplicate-member", id);
+      else sectionIds.push(id);
     }
     result.push({ id: entry.id, label: typeof entry.label === "string" ? entry.label : "", sectionIds });
   }
-  return result;
+  return { entries: result, diagnostics: report.list() };
 }
 
 /**

package/src/media/queue.ts

@@ -1,4 +1,5 @@
 import type { MediaKind } from "./types";
+import type { ImageVariantPlan } from "../lib/image-variant-plan";
 
 export interface QueueInput {
   buffer: ArrayBuffer;
@@ -23,6 +24,7 @@ export interface QueueItem {
     posterBlob?: Blob;
     width: number;
     height: number;
+    plan?: ImageVariantPlan;
   };
 }
 
@@ -116,6 +118,7 @@ export class ProcessingQueue {
           posterBlob: msg.posterBlob,
           width: msg.width,
           height: msg.height,
+          plan: msg.plan,
         };
         this.options.onEvent({ type: "complete", item: { ...item } });
         // The event above carries the only reference anyone reads. Holding ours

package/src/media/utils.ts

@@ -1,4 +1,4 @@
-import { slugifyPageSlug } from "../lib/pages";
+import { slugifyPageSlug } from "../lib/slug";
 import type { MediaItem } from "./types";
 
 export async function hashFileBuffer(buffer: ArrayBuffer): Promise<string> {

package/src/media/worker.ts

@@ -1,3 +1,5 @@
+import { planImageVariants, type ImageVariantPlan } from "../lib/image-variant-plan";
+
 interface ProcessMessage {
   type: "process";
   id: string;
@@ -24,6 +26,8 @@ interface CompleteMessage {
   posterBlob?: Blob;
   width: number;
   height: number;
+  /** Static images only — the shared plan the variants were rendered from. */
+  plan?: ImageVariantPlan;
 }
 
 interface ErrorMessage {
@@ -77,13 +81,17 @@ self.onmessage = async (e: MessageEvent<ProcessMessage>) => {
 
     post({ type: "progress", id: msg.id, percent: 25 });
 
-    const applicableSizes = msg.sizes
-      .filter((s) => s <= origWidth)
-      .sort((a, b) => b - a);
-
-    if (applicableSizes.length === 0) {
-      applicableSizes.push(origWidth);
-    }
+    // Widths, names and paths come from the shared plan (the sharp path uses
+    // the same one); this worker only draws. Encoded largest first so the
+    // primary blob is the largest variant.
+    const plan = planImageVariants({
+      hash: msg.hash,
+      fileName: msg.originalName,
+      width: origWidth,
+      height: origHeight,
+      media: { sizes: msg.sizes, quality: msg.quality },
+    });
+    const applicableSizes = plan.variants.map((v) => v.width).reverse();
 
     const variants: { width: number; height: number; size: number; blob: Blob }[] = [];
     const totalVariants = applicableSizes.length;
@@ -97,7 +105,7 @@ self.onmessage = async (e: MessageEvent<ProcessMessage>) => {
       const ctx = canvas.getContext("2d")!;
       ctx.drawImage(bitmap, 0, 0, targetWidth, targetHeight);
 
-      const blob = await canvas.convertToBlob({ type: "image/webp", quality: msg.quality / 100 });
+      const blob = await canvas.convertToBlob({ type: "image/webp", quality: plan.quality / 100 });
       variants.push({ width: targetWidth, height: targetHeight, size: blob.size, blob });
 
       const percent = 25 + Math.round(((i + 1) / totalVariants) * 75);
@@ -114,6 +122,7 @@ self.onmessage = async (e: MessageEvent<ProcessMessage>) => {
       primaryBlob,
       width: origWidth,
       height: origHeight,
+      plan,
     });
   } catch (err) {
     const message = err instanceof Error ? err.message : "Processing failed";

package/src/schemas/media.ts

@@ -55,13 +55,18 @@ export const ImageManifestSchema = z.object({
 
 export type MediaManifest = z.infer<typeof ImageManifestSchema>;
 
+/** Default git-tier cap for media (bytes); a site may override it as `media.maxFileSize`. */
+export const MEDIA_GIT_MAX_BYTES = 5_242_880;
+/** Default bucket-tier cap for media (bytes); a site may override it as `media.maxAssetSize`. */
+export const MEDIA_BUCKET_MAX_BYTES = 209_715_200;
+
 export const MediaConfigSchema = z.object({
   sizes: z.array(z.number()).default([640, 1080, 1920]),
-  maxFileSize: z.number().default(5242880),
+  maxFileSize: z.number().default(MEDIA_GIT_MAX_BYTES),
   quality: z.number().min(1).max(100).default(85),
   // Per-file cap for bucket-backed video uploads (bytes). The git-path cap is
   // maxFileSize; anything between the two routes to the AssetStore.
-  maxAssetSize: z.number().default(209_715_200),
+  maxAssetSize: z.number().default(MEDIA_BUCKET_MAX_BYTES),
 });
 
 export type MediaConfig = z.infer<typeof MediaConfigSchema>;

package/src/storage/memory.ts

@@ -0,0 +1,178 @@
+import {
+  IDEMPOTENCY_TRAILER,
+  NothingToPublishError,
+  StorageConflictError,
+  type FileWrite,
+  type StorageProvider,
+} from "./types";
+
+// An in-memory StorageProvider with real commit history: a `main` branch, an
+// optional draft branch, and commits addressable by sha. It exists so the write
+// path can be tested end to end without mocking it, which is only worth
+// anything if it behaves like the GitHub adapter — the storage contract suite
+// runs the same cases against both. Anything that differs from GitHub here is a
+// bug in this file.
+
+type Tree = Map<string, Uint8Array>;
+type Commit = { tree: Tree; parent: string | null; message: string };
+type Files = Record<string, string | Uint8Array | null>;
+
+// Mirrors promoteDraft in the GitHub adapter: only these subtrees publish;
+// everything else on main is inherited from main.
+const PUBLISHED_PREFIXES = ["src/content/", "assets/"];
+
+export type MemoryStorage = StorageProvider & {
+  /**
+   * Commit straight to a branch as another writer would — a concurrent editor
+   * save on the draft (created from main if absent), or a merge onto main.
+   * Returns the new commit's sha.
+   */
+  commit(branch: "main" | "draft", files: Files, message?: string): string;
+  /**
+   * Run `fn` once at the start of the next `writeFiles`, before its
+   * `baseVersion` check: a writer landing between a caller's read and its write.
+   */
+  beforeNextWrite(fn: () => void): void;
+};
+
+export function createMemoryStorage(seed: { main?: Files; draft?: Files } = {}): MemoryStorage {
+  const commits = new Map<string, Commit>();
+  let counter = 0;
+  let mainHead: string;
+  let draftHead: string | null = null;
+  let pendingHook: (() => void) | null = null;
+
+  function newCommit(tree: Tree, parent: string | null, message: string): string {
+    counter += 1;
+    const sha = counter.toString(16).padStart(40, "0");
+    commits.set(sha, { tree, parent, message });
+    return sha;
+  }
+
+  function applyFiles(base: Tree, files: Files): Tree {
+    const tree = new Map(base);
+    for (const [path, content] of Object.entries(files)) {
+      if (content === null) tree.delete(path);
+      else tree.set(path, toBytes(content));
+    }
+    return tree;
+  }
+
+  function commitTo(branch: "main" | "draft", files: Files, message = "commit"): string {
+    if (branch === "main") {
+      mainHead = newCommit(applyFiles(commits.get(mainHead)!.tree, files), mainHead, message);
+      return mainHead;
+    }
+    const parent = draftHead ?? mainHead;
+    draftHead = newCommit(applyFiles(commits.get(parent)!.tree, files), parent, message);
+    return draftHead;
+  }
+
+  // Unknown branch or sha reads as absent, as GitHub's 404 does.
+  function treeFor(options?: { draft?: boolean; at?: string }): Tree | null {
+    if (options?.at !== undefined) return commits.get(options.at)?.tree ?? null;
+    if (options?.draft) return draftHead === null ? null : commits.get(draftHead)!.tree;
+    return commits.get(mainHead)!.tree;
+  }
+
+  function checkBase(options?: { baseVersion?: string | null }): void {
+    if (options && "baseVersion" in options) {
+      const expected = options.baseVersion ?? null;
+      if (expected !== draftHead) throw new StorageConflictError(draftHead);
+    }
+  }
+
+  mainHead = newCommit(applyFiles(new Map(), seed.main ?? {}), null, "initial");
+  if (seed.draft) commitTo("draft", seed.draft, "seed draft");
+
+  return {
+    commit: commitTo,
+
+    beforeNextWrite(fn) {
+      pendingHook = fn;
+    },
+
+    async writeFiles(files: FileWrite[], message: string, options?: { baseVersion?: string | null }) {
+      const hook = pendingHook;
+      pendingHook = null;
+      hook?.();
+
+      checkBase(options);
+      if (files.length === 0) return { version: draftHead ?? mainHead };
+
+      const parentTree = commits.get(draftHead ?? mainHead)!.tree;
+      const changes: Files = {};
+      for (const file of files) {
+        // GitHub's createTree rejects deleting a path its base tree does not hold.
+        if (file.content === null && !parentTree.has(file.path)) {
+          throw new Error(`Cannot delete ${file.path}: it is not on the branch`);
+        }
+        changes[file.path] =
+          file.content === null || file.content instanceof Uint8Array || file.encoding !== "base64"
+            ? file.content
+            : fromBase64(file.content);
+      }
+      return { version: commitTo("draft", changes, message) };
+    },
+
+    async readFile(path, options) {
+      return treeFor(options)?.get(path) ?? null;
+    },
+
+    async listDirectory(path, options) {
+      const tree = treeFor(options);
+      if (!tree) return [];
+      const prefix = path.endsWith("/") ? path : `${path}/`;
+      const names: string[] = [];
+      for (const key of tree.keys()) {
+        if (!key.startsWith(prefix)) continue;
+        const rest = key.slice(prefix.length);
+        if (!rest.includes("/")) names.push(rest);
+      }
+      return names;
+    },
+
+    async getVersion() {
+      return mainHead;
+    },
+
+    async getDraftVersion() {
+      return draftHead;
+    },
+
+    async promoteDraft() {
+      if (draftHead === null) throw new NothingToPublishError();
+      const draft = commits.get(draftHead)!.tree;
+      const main = commits.get(mainHead)!.tree;
+      const published = (p: string) => PUBLISHED_PREFIXES.some((prefix) => p.startsWith(prefix));
+      if (![...draft.keys(), ...main.keys()].some(published)) {
+        throw new Error("No editor-managed content found on the saved branch — refusing to publish.");
+      }
+      const tree = new Map([...main].filter(([p]) => !published(p)));
+      for (const [p, bytes] of draft) if (published(p)) tree.set(p, bytes);
+      mainHead = newCommit(tree, mainHead, "Publish content via Brand Portal");
+      draftHead = null;
+      return { version: mainHead };
+    },
+
+    async findCommitByIdempotencyKey(key, options) {
+      const limit = Math.min(Math.max(options?.limit ?? 30, 1), 100);
+      const trailer = `${IDEMPOTENCY_TRAILER}: ${key}`;
+      let sha = draftHead;
+      for (let seen = 0; sha !== null && seen < limit; seen += 1) {
+        const commit = commits.get(sha)!;
+        if (commit.message.split("\n").some((line) => line.trim() === trailer)) return sha;
+        sha = commit.parent;
+      }
+      return null;
+    },
+  };
+}
+
+function toBytes(content: string | Uint8Array): Uint8Array {
+  return typeof content === "string" ? new TextEncoder().encode(content) : content;
+}
+
+function fromBase64(content: string): Uint8Array {
+  return Uint8Array.from(atob(content), (c) => c.charCodeAt(0));
+}

package/src/storage/types.ts

@@ -34,16 +34,29 @@ export interface StorageProvider {
     options?: { baseVersion?: string | null },
   ): Promise<{ version: string }>;
 
+  // `draft` reads the draft branch by name: null when there is no draft — a
+  // caller that wants "draft, else main" falls back itself. `at` reads as of a
+  // commit and wins over `draft`. Two reads by branch name can see two different
+  // commits moments after a write, so a read that must agree with another read
+  // (an index and the listing it is diffed against) pins both to one commit.
   readFile(
     path: string,
-    options?: { draft?: boolean },
+    options?: { draft?: boolean; at?: string },
   ): Promise<Uint8Array | null>;
 
   promoteDraft(): Promise<{ version: string }>;
 
+  /** The published branch's head. Never a valid `baseVersion`. */
   getVersion(): Promise<string>;
 
-  listDirectory(path: string, options?: { draft?: boolean }): Promise<string[]>;
+  /**
+   * The draft branch's head, or null when no draft exists — exactly the value
+   * `writeFiles` accepts as `baseVersion`.
+   */
+  getDraftVersion(): Promise<string | null>;
+
+  /** File basenames directly under `path` (no subdirectories); `[]` when absent. Same options as `readFile`. */
+  listDirectory(path: string, options?: { draft?: boolean; at?: string }): Promise<string[]>;
 
   /**
    * Find a recent commit on the draft branch whose message carries the given