@mosetta/content 0.0.0-stage → 0.0.10

package/src/paths.ts

@@ -0,0 +1,115 @@
+// Source-folder layout of a revisioned entity. Single source of truth for the transport
+// paths — the node provider mirrors these shapes with plain regexes (it cannot import TS at runtime).
+//
+//   pages/<name>/page.json            prefabs/<name>/prefab.json     ← meta
+//   pages/<name>/versions/<rev>.json  prefabs/<name>/versions/<rev>.json   ← published/archived only
+//   pages/<name>/drafts/<id>.json     prefabs/<name>/drafts/<id>.json      ← working copies
+import { ContentKind, ENTITY_NAME_RE } from './model';
+
+export const META_FILE: Record<ContentKind, string> = { pages: 'page.json', prefabs: 'prefab.json' };
+
+export const metaPath = (kind: ContentKind, name: string) => `${kind}/${name}/${META_FILE[kind]}`;
+
+export const versionPath = (kind: ContentKind, name: string, rev: number) => `${kind}/${name}/versions/${rev}.json`;
+
+export const draftPath = (kind: ContentKind, name: string, id: string) => `${kind}/${name}/drafts/${id}.json`;
+
+/** trailing slash = "list draft ids of this entity" for the transport */
+export const draftsPrefix = (kind: ContentKind, name: string) => `${kind}/${name}/drafts/`;
+
+/** the whole entity folder — DELETE target for removing an entity with its full history */
+export const entityPath = (kind: ContentKind, name: string) => `${kind}/${name}`;
+
+/** trailing slash = "list entity names of this kind" for the transport */
+export const listPrefix = (kind: ContentKind) => `${kind}/`;
+
+// ---- published pages: the route lives in the KEY --------------------------------------------
+//
+// The route table is a LISTING of published pages, not an index: an index would have to be
+// updated on every publish and would need concurrent-publish race handling, while a listing needs
+// no maintenance at all. So the listing alone can answer "which URL is which page", the route is
+// encoded into the entry name:
+//
+//   pages/published/<encodeURIComponent(pattern)>~<name>~<rev>
+//
+// `~` never appears in `encodeURIComponent` output, entity names match `^[a-z][A-Za-z0-9]*$`,
+// the revision is an integer: parsing is unambiguous. The prod store puts such an entry on
+// publish (an empty marker object); the dev provider owns the disk and derives the same listing
+// from the metas.
+
+export const PUBLISHED_PREFIX = 'pages/published/';
+
+/**
+ * GONE markers: `pages/gone/<encoded pattern>` — a route whose page was deleted while live. The
+ * site answers such an address 410 Gone (a search engine drops it at once, where a 404 is
+ * retried for weeks). Written when a live page is deleted, removed when a page is published at
+ * the route again; kept forever otherwise.
+ */
+export const GONE_PREFIX = 'pages/gone/';
+
+/**
+ * The GENERATION MARKER: rewritten by every publish and deletion — whatever changes what the live
+ * site shows. A reader keeps what it read of the live site (the route table, the config, the
+ * prefabs) while the marker stays the same: one conditional request instead of re-reading it all.
+ * A store that keeps none (dev) is read anew on every request.
+ */
+export const GENERATION_PATH = 'generation.json';
+
+export const goneKey = (pattern: string): string => `${GONE_PREFIX}${encodeURIComponent(pattern)}`;
+
+export function parseGoneKey(key: string): string | null {
+  try {
+    const pattern = decodeURIComponent(key);
+    return pattern.startsWith('/') ? pattern : null;
+  } catch {
+    return null;
+  }
+}
+
+/** the project's content config: the languages, the namespace */
+export const CONFIG_PATH = 'config.json';
+
+/** a listing entry: everything route matching needs — no document read required */
+export interface IPublishedRoute {
+  readonly pattern: string;
+  readonly name: string;
+  readonly rev: number;
+}
+
+/**
+ * Whether a route would take addresses that belong to a FROZEN page's route. A frozen page that
+ * answers for a whole subtree (`/workbench/{...rest}` — the workbench shell) owns everything
+ * under its base: a literal beats a rest in the route table, so a page published at `/workbench/pages`
+ * would stand in front of the shell's own address. A frozen route without a tail owns itself
+ * alone. The candidate's query requirements do not matter: the path is what collides.
+ */
+export function underFrozenRoute(candidate: string, frozen: string): boolean {
+  const path = candidate.split('?')[0];
+  const tail = /\/\{\.\.\.[^}]*\}$/.exec(frozen);
+  if (!tail) return path === frozen;
+  const base = frozen.slice(0, tail.index) || '/';
+  return path === base || path === frozen || path.startsWith(base === '/' ? '/' : `${base}/`);
+}
+
+export const publishedKey = ({ pattern, name, rev }: IPublishedRoute) => `${encodeURIComponent(pattern)}~${name}~${rev}`;
+
+export function parsePublishedKey(key: string): IPublishedRoute | null {
+  const parts = key.split('~');
+  if (parts.length !== 3) return null;
+  const rev = Number(parts[2]);
+  if (!Number.isInteger(rev) || rev <= 0 || !ENTITY_NAME_RE.test(parts[1])) return null;
+  try {
+    return { pattern: decodeURIComponent(parts[0]), name: parts[1], rev };
+  } catch {
+    return null; // broken encoding — the entry is not a route
+  }
+}
+
+/**
+ * The PUBLISHED-revision document in the public content zone. The key carries the revision and
+ * published/archived revisions are immutable — so the response is cacheable forever.
+ */
+export const publishedDocPath = (name: string, rev: number) => `pages/${name}/${rev}.json`;
+
+/** listing order matters ("first page" fallback) — do not depend on store traversal order */
+export const sortRoutes = (routes: readonly IPublishedRoute[]): IPublishedRoute[] => [...routes].sort((a, b) => (a.pattern === b.pattern ? a.name.localeCompare(b.name) : a.pattern.localeCompare(b.pattern)));

package/src/policy.ts

@@ -0,0 +1,133 @@
+import { ContentKind, IContentMeta, RevisionStatus } from './model';
+import { META_FILE, publishedKey } from './paths';
+
+/**
+ * Revision rules at the TRUST BOUNDARY.
+ *
+ * Whoever owns the store must enforce them: action code comes from a distribution and carries no
+ * trust. These checks used to live inside the dev provider (node, .mjs) — the rule had no home, a
+ * prod provider would have to rewrite it. Now they are pure functions of this package, and store
+ * implementations (dev worker over files, node provider, a future object store) are thin adapters
+ * around them.
+ *
+ * Checking HERE does not replace the check in `ContentRepository` (isolate side): that one gives
+ * the author sensible errors, this one gives the guarantee. Two checks on opposite sides of the
+ * boundary are not duplication.
+ */
+
+const ENTITY = '[a-z][A-Za-z0-9]*';
+const DRAFT = '[a-z0-9][a-z0-9-]{5,63}'; // mirrors DRAFT_ID_RE (kept inline: composed regexes)
+const LIST_RE = /^(pages|prefabs)\/$/;
+const META_RE = new RegExp(`^(pages|prefabs)/(${ENTITY})/(page|prefab)\\.json$`);
+const VERSION_RE = new RegExp(`^(pages|prefabs)/(${ENTITY})/versions/([1-9][0-9]*)\\.json$`);
+const DRAFT_RE = new RegExp(`^(pages|prefabs)/(${ENTITY})/drafts/(${DRAFT})\\.json$`);
+const DRAFT_LIST_RE = new RegExp(`^(pages|prefabs)/(${ENTITY})/drafts/$`);
+const ENTITY_RE = new RegExp(`^(pages|prefabs)/(${ENTITY})$`);
+
+const REV_STATUSES = new Set<string>(['published', 'archived']);
+
+/** published/archived are immutable — nothing may overwrite or delete them */
+export const IMMUTABLE: ReadonlySet<string> = new Set(['published', 'archived']);
+
+export type TContentTarget = { readonly kind: 'list'; readonly collection: ContentKind }
+  | { readonly kind: 'meta'; readonly collection: ContentKind; readonly name: string; readonly rel: string }
+  | { readonly kind: 'version'; readonly collection: ContentKind; readonly name: string; readonly rev: number; readonly rel: string }
+  | { readonly kind: 'draft'; readonly collection: ContentKind; readonly name: string; readonly draftId: string; readonly rel: string }
+  | { readonly kind: 'draftList'; readonly collection: ContentKind; readonly name: string }
+  | { readonly kind: 'entity'; readonly collection: ContentKind; readonly name: string; readonly rel: string };
+
+/** parse a content-channel path; `null` — the path is outside the channel and must not be served */
+export function parseContentPath(rel: string): TContentTarget | null {
+  if (rel.includes('..')) return null;
+  const list = LIST_RE.exec(rel);
+  if (list) return { kind: 'list', collection: list[1] as ContentKind };
+  const meta = META_RE.exec(rel);
+  if (meta) {
+    const collection = meta[1] as ContentKind;
+    // the meta file name must match the collection: pages/<x>/prefab.json is not a channel path
+    if (META_FILE[collection] !== `${meta[3]}.json`) return null;
+    return { kind: 'meta', collection, name: meta[2], rel };
+  }
+  const version = VERSION_RE.exec(rel);
+  if (version) {
+    return { kind: 'version', collection: version[1] as ContentKind, name: version[2], rev: Number(version[3]), rel };
+  }
+  const draft = DRAFT_RE.exec(rel);
+  if (draft) {
+    return { kind: 'draft', collection: draft[1] as ContentKind, name: draft[2], draftId: draft[3], rel };
+  }
+  const draftList = DRAFT_LIST_RE.exec(rel);
+  if (draftList) return { kind: 'draftList', collection: draftList[1] as ContentKind, name: draftList[2] };
+  const entity = ENTITY_RE.exec(rel);
+  if (entity) return { kind: 'entity', collection: entity[1] as ContentKind, name: entity[2], rel };
+  return null;
+}
+
+/**
+ * Why the proposed draft write is illegal (or `null` when it is legal) — the OPTIMISTIC
+ * CONCURRENCY gate. Every draft carries an integer `seq`; an accepted write must be the direct
+ * successor of what is stored. A writer that fell behind (someone else saved meanwhile) breaks
+ * the chain and is refused — the store answers 412, the editor answers fork-or-rollback.
+ */
+export function draftRejection(oldDoc: unknown, next: unknown): string | null {
+  if (!next || typeof next !== 'object' || Array.isArray(next)) return 'malformed draft';
+  const seq = (next as { seq?: unknown }).seq;
+  if (!Number.isInteger(seq) || (seq as number) < 1) return 'draft must carry an integer seq >= 1';
+  if (!oldDoc || typeof oldDoc !== 'object') {
+    return seq === 1 ? null : 'first write of a draft must carry seq 1';
+  }
+  const stored = (oldDoc as { seq?: unknown }).seq;
+  if (!Number.isInteger(stored)) return null; // stored draft has no chain (hand-edited) — repairable
+  return seq === (stored as number) + 1
+    ? null
+    : `draft seq ${seq as number} does not follow stored seq ${stored as number} (concurrent edit?)`;
+}
+
+/**
+ * Why the proposed meta is illegal (or `null` when it is legal). Immutable revisions must survive
+ * any rewrite: they cannot be removed, turned back into drafts, or re-published; `live` must point
+ * at the single published revision.
+ */
+export function metaRejection(oldMeta: IContentMeta | null, next: unknown): string | null {
+  if (!next || typeof next !== 'object' || Array.isArray(next)) return 'malformed meta';
+  const meta = next as { live?: unknown; versions?: unknown };
+  if (meta.live !== null && !Number.isInteger(meta.live)) return 'malformed meta: live must be an int or null';
+  if (!meta.versions || typeof meta.versions !== 'object' || Array.isArray(meta.versions)) {
+    return 'malformed meta: versions map required';
+  }
+  const entries = Object.entries(meta.versions as Record<string, unknown>);
+  if (entries.some(([rev, s]) => !/^[1-9][0-9]*$/.test(rev) || typeof s !== 'string' || !REV_STATUSES.has(s))) {
+    return 'malformed meta: bad revision entry';
+  }
+  const published = entries.filter(([, s]) => s === 'published');
+  if (published.length > 1) return 'more than one published revision';
+  const expectedLive = published.length === 1 ? Number(published[0][0]) : null;
+  if (meta.live !== expectedLive) return 'live must point at the published revision';
+  for (const [rev, status] of Object.entries(oldMeta?.versions ?? {})) {
+    if (!IMMUTABLE.has(status)) continue;
+    const nextStatus = (meta.versions as Record<string, string>)[rev];
+    if (!nextStatus) return `immutable revision ${rev} cannot be removed`;
+    if (status === 'archived' && nextStatus !== 'archived') return `archived revision ${rev} cannot be re-published`;
+  }
+  return null;
+}
+
+/** revision status per the meta (for immutability checks and serving published documents) */
+export function statusOf(meta: IContentMeta | null, rev: number): RevisionStatus | null {
+  return meta?.versions?.[String(rev)] ?? null;
+}
+
+/**
+ * Route table from published pages: the key carries the pattern, name and revision.
+ * Input is the already-read meta and live-revision document; reading is the store adapter's job.
+ */
+export function publishedKeysFrom(
+  entities: readonly { name: string; meta: IContentMeta | null; doc: { pattern?: unknown } | null }[],
+): string[] {
+  const keys: string[] = [];
+  for (const { name, meta, doc } of entities) {
+    if (!meta || typeof meta.live !== 'number' || !doc || typeof doc.pattern !== 'string') continue;
+    keys.push(publishedKey({ pattern: doc.pattern, name, rev: meta.live }));
+  }
+  return keys.sort();
+}

package/src/queryPolicy.ts

@@ -0,0 +1,33 @@
+// WHICH QUERY PARAMETERS A PAGE DOES NOT SEE. A live page is kept at the edge under its address,
+// query included — so every marketing tag a link carries (`?utm_source=tg`, `?fbclid=…`) would
+// render the same page anew and keep one more copy of it. The parameters named here are taken off
+// the address before anything else happens: the edge key AND the render go without them (the
+// render must, or a copy kept for one visitor's tags would be served to another's). Scripts in the
+// browser still read them from the address bar — only the server never sees them.
+//
+// The list is the project's content config (`config.json`: `cache.ignoreQuery`); without one the
+// defaults below apply, an empty list keeps every parameter. An entry is a parameter name or a
+// prefix ending in `*` (`utm_*`).
+
+/** the tags of the common ad and mail networks: never meant for the page, always on its links */
+export const DEFAULT_IGNORED_QUERY: readonly string[] = [
+  'utm_*',
+  'gclid', 'gbraid', 'wbraid', 'dclid',
+  'fbclid', 'msclkid', 'ttclid', 'twclid', 'igshid',
+  'yclid', 'ysclid', '_openstat',
+  'mc_cid', 'mc_eid',
+];
+
+const ENTRY_RE = /^[A-Za-z0-9_.~-]+\*?$/;
+
+/** the content config's ignore list, validated: absent or malformed → the defaults; listed → exactly that */
+export function ignoredQueryOf(config: unknown): readonly string[] {
+  const cache = (config as { cache?: { ignoreQuery?: unknown } } | null)?.cache;
+  if (!Array.isArray(cache?.ignoreQuery)) return DEFAULT_IGNORED_QUERY;
+  return cache.ignoreQuery.filter((entry): entry is string => typeof entry === 'string' && ENTRY_RE.test(entry));
+}
+
+/** a parameter the list names: by its whole name, or by a prefix entry (`utm_*`) */
+export function isIgnoredQuery(name: string, ignored: readonly string[]): boolean {
+  return ignored.some((entry) => (entry.endsWith('*') ? name.startsWith(entry.slice(0, -1)) : name === entry));
+}

package/src/repository.ts

@@ -0,0 +1,358 @@
+// The content state machine over a content transport, on TWO axes:
+//   drafts/<id>  ──publish──▶ versions/<n> published (= live, exactly one) ──next publish──▶ archived
+// Versions are immutable publish history; drafts are a flat set of working copies under random
+// ids, listed by prefix and NEVER recorded in the meta (a meta entry per draft would make the
+// meta a shared write hotspot between concurrent editors). Every mutation here checks the meta
+// or the stored draft first, and the dev provider independently enforces the same rules on its
+// side of the trust boundary.
+import { DiInject, DiService, SingleDiToken } from '@mosetta/di';
+import {
+  ContentKind,
+  IContentEntity,
+  IContentMeta,
+  IDraftSummary,
+  ILoadedContent,
+  ILoadedDraft,
+  maxRevision,
+  PrefabType,
+  publishedFormOf,
+  RevisionStatus,
+} from './model';
+import { draftPath, draftsPrefix, entityPath, GENERATION_PATH, goneKey, listPrefix, metaPath, parsePublishedKey, PUBLISHED_PREFIX, publishedKey, underFrozenRoute, versionPath } from './paths';
+import { EMPTY_ROOTS, parseRoots, ROOTS_PATH, rootsEntryOf, withRootsEntry } from './roots';
+import type { IRootsEntry, IBlueprintManifest } from './roots';
+import { CONTENT_TRANSPORT_TOKEN, ContentTransportError } from './transport';
+import { draftRejection } from './policy';
+import { draftTitleOf, revisionTitleOf } from './names';
+// import type: the name sits in a DECORATED signature — emitDecoratorMetadata under
+// isolatedModules refuses a value-import there (TS1272); di uses explicit tokens, no metadata
+import type { IContentTransport } from './transport';
+
+export type ContentErrorCode = 'NOT_FOUND' | 'ALREADY_EXISTS' | 'NO_REVISION' | 'NO_DRAFT' | 'CONFLICT' | 'MEDIA' | 'LOCKED' | 'TOO_LARGE';
+
+/**
+ * The largest document that may be PUBLISHED, as JSON. A site renders its pages in one isolate of
+ * about 128 MB: a document of 6 MB (30 000 nodes) took 5–6 s to render, one of 12 MB ran the
+ * isolate out of memory every other request. A draft may grow past it; publishing it is refused.
+ */
+export const MAX_PUBLISHED_BYTES = 4 * 1024 * 1024;
+
+export class ContentError extends Error {
+  constructor(
+    readonly code: ContentErrorCode,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+export const CONTENT_REPOSITORY_TOKEN = new SingleDiToken<ContentRepository>('CONTENT_REPOSITORY_TOKEN');
+
+@DiService(CONTENT_REPOSITORY_TOKEN)
+export class ContentRepository {
+  constructor(
+    @DiInject(CONTENT_TRANSPORT_TOKEN)
+    private readonly transport: IContentTransport,
+  ) {}
+
+  /** every entity with its meta and drafts — the entities read side by side, not one after another */
+  async list(kind: ContentKind): Promise<IContentEntity[]> {
+    const names = await this.transport.list(listPrefix(kind));
+    const entities = await Promise.all(names.map(async (name): Promise<IContentEntity | null> => {
+      const [meta, drafts] = await Promise.all([
+        this.transport.read(metaPath(kind, name)) as Promise<IContentMeta | null>,
+        this.listDrafts(kind, name),
+      ]);
+      return meta ? { name, meta, drafts } : null;
+    }));
+    return entities.filter((e): e is IContentEntity => e !== null);
+  }
+
+  /** the entity's drafts: id + working fields (and a page's route), read side by side */
+  async listDrafts(kind: ContentKind, name: string): Promise<IDraftSummary[]> {
+    const ids = await this.transport.list(draftsPrefix(kind, name));
+    const drafts = await Promise.all(ids.map(async (id): Promise<IDraftSummary | null> => {
+      const doc = (await this.transport.read(draftPath(kind, name, id))) as (Partial<IDraftSummary> & { pattern?: unknown }) | null;
+      if (!doc) return null;
+      return {
+        id,
+        seq: Number.isInteger(doc.seq) ? doc.seq! : 1,
+        createdAt: typeof doc.createdAt === 'string' ? doc.createdAt : '',
+        ...(Number.isInteger(doc.baseRev) ? { baseRev: doc.baseRev } : {}),
+        ...(typeof doc.title === 'string' ? { title: doc.title } : {}),
+        ...(typeof doc.pattern === 'string' ? { pattern: doc.pattern } : {}),
+      };
+    }));
+    return drafts.filter((d): d is IDraftSummary => d !== null);
+  }
+
+  /** the routes of the live pages, by page name — read off the publish markers, no document opened */
+  async livePatterns(): Promise<Map<string, string>> {
+    const out = new Map<string, string>();
+    for (const key of await this.transport.keys(PUBLISHED_PREFIX)) {
+      const route = parsePublishedKey(key.slice(PUBLISHED_PREFIX.length));
+      if (route) out.set(route.name, route.pattern);
+    }
+    return out;
+  }
+
+  /** rev omitted → live; only published/archived versions live on this axis */
+  async load<TDoc>(kind: ContentKind, name: string, rev?: number): Promise<ILoadedContent<TDoc>> {
+    const meta = await this.requireMeta(kind, name);
+    const revToLoad = rev ?? meta.live;
+    if (revToLoad == null || !meta.versions[String(revToLoad)]) {
+      throw new ContentError('NO_REVISION', `${kind}/${name} has no published revision ${revToLoad ?? '(none)'}`);
+    }
+    const doc = await this.transport.read(versionPath(kind, name, revToLoad));
+    if (doc == null) {
+      throw new ContentError('NO_REVISION', `${kind}/${name} revision ${revToLoad} file is missing`);
+    }
+    return { name, meta, rev: revToLoad, doc: doc as TDoc };
+  }
+
+  async loadDraft<TDoc>(kind: ContentKind, name: string, id: string): Promise<ILoadedDraft<TDoc>> {
+    await this.requireMeta(kind, name);
+    const doc = await this.transport.read(draftPath(kind, name, id));
+    if (doc == null) throw new ContentError('NO_DRAFT', `${kind}/${name} has no draft ${id}`);
+    return { name, id, doc: doc as TDoc };
+  }
+
+  /** creates the entity: an empty publish history and the given doc as its first draft */
+  async create(kind: ContentKind, name: string, doc: unknown, type?: PrefabType): Promise<string> {
+    const existing = await this.transport.read(metaPath(kind, name));
+    if (existing) throw new ContentError('ALREADY_EXISTS', `${kind}/${name} already exists`);
+    const meta: IContentMeta = { live: null, versions: {}, ...(type ? { type } : {}) };
+    // meta first: the provider's enforcement admits draft writes only for entities it knows
+    await this.transport.write(metaPath(kind, name), meta);
+    return this.putFreshDraft(kind, name, doc as object);
+  }
+
+  /**
+   * The save is the CONFLICT gate: the doc must carry `seq = stored.seq + 1`. Checked HERE, before
+   * the write, whatever store sits behind the transport: a plain object store (R2 over S3) writes
+   * whatever it is given, and only the dev store refused a broken chain itself (412). Without the
+   * check a save into a draft discarded or published meanwhile silently brought it back, and two
+   * tabs overwrote each other. A draft that is gone answers CONFLICT too — the editor offers to
+   * fork the working copy. (Read-then-write: the window between them is the store's to close,
+   * with a conditional write, once a transport offers one.)
+   */
+  async saveDraft(kind: ContentKind, name: string, id: string, doc: unknown): Promise<void> {
+    await this.requireUnlocked(kind, name);
+    const stored = await this.transport.read(draftPath(kind, name, id));
+    const rejection = stored == null
+      ? `${kind}/${name} draft ${id} is gone (discarded or published)`
+      : draftRejection(stored, doc);
+    if (rejection) throw new ContentError('CONFLICT', rejection);
+    try {
+      await this.transport.write(draftPath(kind, name, id), doc);
+    } catch (e) {
+      if (e instanceof ContentTransportError && e.status === 412) {
+        throw new ContentError('CONFLICT', `${kind}/${name} draft ${id}: ${e.message}`);
+      }
+      throw e;
+    }
+  }
+
+  /** copies a PUBLISHED version (default: live) into a fresh draft */
+  async createDraft(kind: ContentKind, name: string, fromRev?: number): Promise<{ id: string; doc: unknown }> {
+    const meta = await this.requireUnlocked(kind, name);
+    const sourceRev = fromRev ?? meta.live;
+    if (sourceRev == null || !meta.versions[String(sourceRev)]) {
+      throw new ContentError('NO_REVISION', `${kind}/${name} has no published revision ${sourceRev ?? '(none)'}`);
+    }
+    const source = await this.transport.read(versionPath(kind, name, sourceRev));
+    if (source == null) {
+      throw new ContentError('NO_REVISION', `${kind}/${name} revision ${sourceRev} file is missing`);
+    }
+    return this.putDraft(kind, name, { ...(source), baseRev: sourceRev });
+  }
+
+  /**
+   * Writes the GIVEN doc as a new draft under a fresh identity — the conflict modal's "fork"
+   * button: the local working copy (undo stacks and lineage included) survives under its own id.
+   */
+  async forkDraft(kind: ContentKind, name: string, doc: unknown): Promise<{ id: string; doc: unknown }> {
+    await this.requireUnlocked(kind, name);
+    return this.putDraft(kind, name, doc as object);
+  }
+
+  /**
+   * Promotes a draft into the NEXT published version; the previous live becomes archived, the
+   * draft is deleted — it has become a version. Working fields (seq, undo stacks, …) are stripped:
+   * a published version is pure content.
+   */
+  /** the draft becomes the next revision; `title` — the name the publication goes by, if any */
+  async publish(kind: ContentKind, name: string, draftId: string, title?: string): Promise<number> {
+    const meta = await this.requireUnlocked(kind, name);
+    const { doc } = await this.loadDraft(kind, name, draftId);
+    if (kind === 'pages') await this.refuseFrozenRoute(name, (doc as { pattern?: unknown }).pattern);
+    const rev = (maxRevision(meta) ?? 0) + 1;
+    const published = publishedFormOf(doc as object);
+    const bytes = new TextEncoder().encode(JSON.stringify(published)).length;
+    if (bytes > MAX_PUBLISHED_BYTES) {
+      throw new ContentError('TOO_LARGE', `${kind}/${name}: the page is ${Math.ceil(bytes / 1024)} KiB — a published page may be at most ${MAX_PUBLISHED_BYTES / 1024} KiB; split it into several pages`);
+    }
+    // the version file first: the rev is unknown to the meta, so the store admits the write;
+    // the meta write below is what makes it immutable
+    await this.transport.write(versionPath(kind, name, rev), published);
+    const versions: Record<string, RevisionStatus> = { ...meta.versions, [String(rev)]: 'published' };
+    if (meta.live != null && meta.live !== rev) versions[String(meta.live)] = 'archived';
+    const named = revisionTitleOf(title);
+    const names = named ? { ...meta.names, [String(rev)]: named } : meta.names;
+    await this.transport.write(metaPath(kind, name), { ...meta, live: rev, versions, ...(names ? { names } : {}) });
+    await this.transport.delete(draftPath(kind, name, draftId));
+    if (kind === 'pages') {
+      const { pattern } = doc as { pattern?: unknown };
+      await this.syncMarkers(name, { pattern, rev });
+      // the route lives again: it is no longer gone
+      if (typeof pattern === 'string') await this.transport.delete(goneKey(pattern));
+    }
+    await this.syncRoots(kind, name, rootsEntryOf(kind, publishedFormOf(doc as object)));
+    await this.markGeneration();
+    return rev;
+  }
+
+  /**
+   * The project's roots (ADR-0052) follow the live site: the entity's entry is set (published) or
+   * removed (deleted). A store that keeps no such file — dev derives it — refuses, and that is
+   * fine: the file is a hint the site isolate starts from, never what a render depends on.
+   */
+  private async syncRoots(kind: ContentKind, name: string, entry: IRootsEntry | null): Promise<void> {
+    try {
+      let stored: unknown;
+      try {
+        stored = await this.transport.read(ROOTS_PATH);
+      } catch {
+        return; // the file cannot be read now: left as it is rather than overwritten blind
+      }
+      // a store without the file yet: the whole live site first — a file naming one entity would
+      // tell every site isolate that nothing else is published
+      const current = stored == null ? await this.deriveRoots() : parseRoots(stored);
+      await this.transport.write(ROOTS_PATH, withRootsEntry(current, kind, name, entry));
+    } catch {
+      // the store derives the file itself (dev), or refuses it — the hint is not kept here
+    }
+  }
+
+  /** the roots of the live site as the store holds it: every entity's live revision */
+  private async deriveRoots(): Promise<IBlueprintManifest> {
+    let file = EMPTY_ROOTS;
+    for (const kind of ['pages', 'prefabs'] as const) {
+      for (const entity of await this.transport.list(listPrefix(kind))) {
+        const meta = await this.transport.read(metaPath(kind, entity)) as IContentMeta | null;
+        if (meta?.live == null) continue;
+        const doc = await this.transport.read(versionPath(kind, entity, meta.live));
+        if (doc != null) file = withRootsEntry(file, kind, entity, rootsEntryOf(kind, doc));
+      }
+    }
+    return file;
+  }
+
+  /**
+   * The live site changed: a new generation marker (GENERATION_PATH), so readers drop what they
+   * kept. A store that keeps none (dev, which reads everything anew anyway) refuses it — no matter.
+   */
+  private async markGeneration(): Promise<boolean> {
+    try {
+      await this.transport.write(GENERATION_PATH, { at: new Date().toISOString(), id: crypto.randomUUID() });
+      return true;
+    } catch {
+      return false; // no marker kept — readers read anew on every request
+    }
+  }
+
+  /**
+   * A new generation marker without a publish: whatever readers kept of the live site — a page's
+   * render, the route table, the site's isolate — is read anew. The remedy for a change made to
+   * the store by hand. False — the store keeps no marker (dev): nothing is kept there anyway.
+   */
+  refreshLiveSite(): Promise<boolean> {
+    return this.markGeneration();
+  }
+
+  /**
+   * The route table is a listing of publish MARKERS (`pages/published/<pattern>~<name>~<rev>`,
+   * see paths.ts): the live revision of a page owns exactly one. The new marker lands before the
+   * stale ones go, so a concurrent request never sees the page routeless. A store that derives
+   * the listing itself (dev) treats these writes as no-ops.
+   */
+  private async syncMarkers(name: string, live: { pattern: unknown; rev: number } | null): Promise<void> {
+    const wanted = live && typeof live.pattern === 'string' ? `${PUBLISHED_PREFIX}${publishedKey({ pattern: live.pattern, name, rev: live.rev })}` : null;
+    if (wanted) await this.transport.write(wanted, {});
+    const stale = (await this.transport.keys(PUBLISHED_PREFIX))
+      .filter((key) => key !== wanted && parsePublishedKey(key.slice(PUBLISHED_PREFIX.length))?.name === name);
+    for (const key of stale) await this.transport.delete(key);
+  }
+
+  async discardDraft(kind: ContentKind, name: string, id: string): Promise<void> {
+    await this.requireMeta(kind, name);
+    await this.transport.delete(draftPath(kind, name, id));
+  }
+
+  /** removes the entity with its whole history (the provider deletes the entity folder) */
+  async delete(kind: ContentKind, name: string): Promise<void> {
+    const meta = await this.requireUnlocked(kind, name);
+    // a LIVE page leaves its route GONE — unless another live page answers at it
+    let gone: string | null = null;
+    if (kind === 'pages' && meta.live != null) {
+      const live = (await this.transport.read(versionPath(kind, name, meta.live))) as { pattern?: unknown } | null;
+      if (typeof live?.pattern === 'string') gone = live.pattern;
+    }
+    await this.transport.delete(entityPath(kind, name));
+    if (kind === 'pages') {
+      await this.syncMarkers(name, null);
+      if (gone !== null) {
+        const heldElsewhere = (await this.transport.keys(PUBLISHED_PREFIX))
+          .some((key) => parsePublishedKey(key.slice(PUBLISHED_PREFIX.length))?.pattern === gone);
+        if (!heldElsewhere) await this.transport.write(goneKey(gone), {});
+      }
+    }
+    await this.syncRoots(kind, name, null);
+    await this.markGeneration();
+  }
+
+  /** the meta of an entity the editors may change — a frozen one answers LOCKED */
+  private async requireUnlocked(kind: ContentKind, name: string): Promise<IContentMeta> {
+    const meta = await this.requireMeta(kind, name);
+    if (meta.locked) throw new ContentError('LOCKED', `${kind}/${name} belongs to the platform and cannot be changed`);
+    return meta;
+  }
+
+  /**
+   * A frozen page's route is its own: another page publishing at it — or anywhere under it, when
+   * the frozen page answers for a subtree (underFrozenRoute) — would take its place.
+   */
+  private async refuseFrozenRoute(name: string, pattern: unknown): Promise<void> {
+    if (typeof pattern !== 'string') return;
+    const holders = (await this.transport.keys(PUBLISHED_PREFIX))
+      .map((key) => parsePublishedKey(key.slice(PUBLISHED_PREFIX.length)))
+      .filter((route) => route !== null && route.name !== name && underFrozenRoute(pattern, route.pattern));
+    for (const route of holders) {
+      const meta = (await this.transport.read(metaPath('pages', route!.name))) as IContentMeta | null;
+      if (meta?.locked) throw new ContentError('LOCKED', `${pattern} belongs to the platform's page ${route!.name}`);
+    }
+  }
+
+  private async requireMeta(kind: ContentKind, name: string): Promise<IContentMeta> {
+    const meta = (await this.transport.read(metaPath(kind, name))) as IContentMeta | null;
+    if (!meta) throw new ContentError('NOT_FOUND', `${kind}/${name} does not exist`);
+    return meta;
+  }
+
+  /** a fresh draft from a doc that carries no lineage of its own */
+  private putFreshDraft(kind: ContentKind, name: string, doc: object): Promise<string> {
+    return this.putDraft(kind, name, doc).then(({ id }) => id);
+  }
+
+  /**
+   * Stamps a fresh identity and chain start (random id — creation needs no coordination), and a
+   * NAME of two words drawn from the id: a draft is known by words, never by its id (a copy of a
+   * named draft gets words of its own, so two drafts never go by the same ones by accident)
+   */
+  private async putDraft(kind: ContentKind, name: string, doc: object): Promise<{ id: string; doc: unknown }> {
+    const id = crypto.randomUUID();
+    const stamped = { ...doc, seq: 1, createdAt: new Date().toISOString(), title: draftTitleOf(id) };
+    await this.transport.write(draftPath(kind, name, id), stamped);
+    return { id, doc: stamped };
+  }
+}