@1agh/maude 0.47.0 → 0.49.0

package/apps/studio/server.ts

@@ -34,6 +34,12 @@ import { createHttp } from './http.ts';
 import { createInspect } from './inspect.ts';
 import { startHeapWatch } from './mem.ts';
 import { createSyncRuntime } from './sync/index.ts';
+import {
+  assertContainment,
+  isForbiddenRoute,
+  isWorkspaceMode,
+  pruneForWorkspace,
+} from './workspace-mode.ts';
 import { createWs, isLoopbackHost, isSameOriginWs, parseCollabSlug, type WsData } from './ws.ts';
 
 // Phase 19 / DDR-044 — covers the marketplace-cache-install gap where
@@ -141,16 +147,73 @@ type BunServer = ReturnType<typeof Bun.serve<WsData, never>>;
 // transient-buffer tradeoff on the buffering routes, noted in DDR-148).
 const MAX_REQUEST_BODY = ASSET_MAX_VIDEO_BYTES + 8 * 1024 * 1024;
 
+// Containment invariant (DDR-193 §2) — the boot-assert. No-op outside workspace
+// mode; in a cell it refuses to start when a rendering / evaluating / exporting
+// surface is reachable, naming exactly which one. See workspace-mode.ts for why
+// this is a process that will not start rather than a convention.
+//
+// Checked against the ACTUAL route table (`http.routes` keys plus the paths the
+// `fetch` fall-through owns), not a hand-maintained list, so a future route can
+// only escape it by being invisible to both.
+const WORKSPACE_FETCH_ROUTES = ['/_ws/acp', '/_canvas-shell.html', '/_canvas-runtime/'];
+const WORKSPACE = isWorkspaceMode();
+// PRUNE first, then assert over what survived — so the assert is a
+// post-condition on the pruning rather than a second, driftable opinion. A
+// prefix added to the vocabulary then both prunes and is verified, together.
+const pruned = WORKSPACE ? pruneForWorkspace(http.routes) : { routes: http.routes, removed: [] };
+const SERVER_ROUTES = pruned.routes as typeof http.routes;
+if (WORKSPACE && pruned.removed.length > 0) {
+  console.log(
+    `[studio] workspace mode — withheld ${pruned.removed.length} route(s) that would evaluate ` +
+      `tenant content: ${pruned.removed.join(', ')}`
+  );
+}
+try {
+  assertContainment([...Object.keys(SERVER_ROUTES), ...(WORKSPACE ? [] : WORKSPACE_FETCH_ROUTES)], {
+    // Presence of the dependency is the signal: a cell image that ships
+    // Playwright is one import() away from rendering tenant content. Skippable
+    // in a dev checkout, where Playwright is a legitimate devDependency of the
+    // E2E harness and would otherwise make workspace mode untestable locally.
+    // A BUILT cell image has no such escape — scripts/check-containment.sh
+    // enforces the runtime-dependency half at build time.
+    resolveModule:
+      process.env.MAUDE_WORKSPACE_ALLOW_DEV_MODULES === '1'
+        ? undefined
+        : (specifier) => {
+            try {
+              return !!import.meta.resolveSync?.(specifier);
+            } catch {
+              return false;
+            }
+          },
+  });
+} catch (err) {
+  console.error(`\n${(err as Error).message}\n`);
+  process.exit(1);
+}
+if (isWorkspaceMode()) {
+  console.log('[studio] workspace mode — sync + git + assets only (DDR-193 containment invariant)');
+}
+
 function startServer(port: number): BunServer {
   return Bun.serve<WsData, never>({
     port,
     hostname: '127.0.0.1',
     development: process.env.NODE_ENV !== 'production',
     maxRequestBodySize: MAX_REQUEST_BODY,
-    routes: http.routes,
+    routes: SERVER_ROUTES,
     async fetch(req, srv) {
       const pathname = new URL(req.url).pathname;
 
+      // Containment (DDR-193 §2) — the `fetch` fall-through owns paths that are
+      // not in the route table (`/_ws/acp`, `/_canvas-shell.html`,
+      // `/_canvas-runtime/*`), so pruning the table alone would leave them
+      // reachable. 404, not 403: a cell should look like it never had the
+      // feature, rather than like it is refusing one.
+      if (WORKSPACE && isForbiddenRoute(pathname)) {
+        return new Response('not found', { status: 404 });
+      }
+
       // Phase 8 — collab WS, binary y-websocket protocol. Loopback-only;
       // DDR-047 makes cross-machine collab a Phase 9 hub-deploy story, not
       // a `--bind 0.0.0.0` flag on this server.
@@ -167,6 +230,8 @@ function startServer(port: number): BunServer {
             remote: req.headers.get('x-forwarded-for') ?? '127.0.0.1',
             kind: 'collab',
             slug: collabSlug,
+            // Privileged shell origin — ungated (see collab/origins.ts).
+            realm: 'main',
           },
         });
         if (ok) return undefined as unknown as Response;
@@ -275,6 +340,10 @@ function startCanvasServer(port: number): BunServer {
             remote: req.headers.get('x-forwarded-for') ?? '127.0.0.1',
             kind: 'collab',
             slug: collabSlug,
+            // UNTRUSTED canvas iframe origin (DDR-063 split). Every sync frame
+            // from here goes through the origin gate and may never write a
+            // body lane — DDR-122 follow-up, collab/origins.ts.
+            realm: 'canvas',
           },
         });
         if (ok) return undefined as unknown as Response;
@@ -377,7 +446,11 @@ ctx.mainOrigin = `http://localhost:${server.port} http://127.0.0.1:${server.port
 const CANVAS_ORIGIN_SPLIT = !/^(0|false|off|no)$/i.test(
   process.env.MAUDE_CANVAS_ORIGIN_SPLIT ?? ''
 );
-const canvasServer = CANVAS_ORIGIN_SPLIT ? startCanvasServer(0) : null;
+// The canvas origin exists to SERVE AND RENDER canvases (DDR-063). A workspace
+// cell has no business starting it — that second origin is the surface the
+// containment invariant is about. Not started here rather than started-and-
+// pruned: there would be nothing left to serve.
+const canvasServer = CANVAS_ORIGIN_SPLIT && !WORKSPACE ? startCanvasServer(0) : null;
 const canvasOrigin = canvasServer ? `http://localhost:${canvasServer.port}` : undefined;
 if (canvasOrigin) ctx.canvasOrigin = canvasOrigin;
 

package/apps/studio/sync/autocommit.ts

@@ -0,0 +1,299 @@
+// Autosave → append-only git commits — Cloud Phase 3 Task 1.
+//
+// On a laptop, autosave writing a file IS the save: the developer's own git is
+// the history, and they commit when they mean to. In a workspace cell there is
+// no developer at the keyboard, so an unwritten history means the only record
+// of a design is its current bytes — one bad sync away from unrecoverable.
+//
+// So the cell commits. Three rules make that safe rather than merely noisy:
+//
+//   1. APPEND-ONLY. `git add` + `git commit`, ever. No amend, no rebase, no
+//      reset, no `checkout --` over a dirty tree, and NEVER a force-push. The
+//      history is allowed to be ugly; it is not allowed to lose a state that
+//      once existed.
+//   2. AUTHORSHIP IS THE EDITING HUMAN. git separates author from committer
+//      precisely for this: the author is the person whose edit this was (from
+//      presence), the committer is the workspace bot. `git blame` then answers
+//      "who designed this" instead of "the server did", which is the whole
+//      reason to keep history at all.
+//   3. QUIESCENCE, NOT KEYSTROKES. Commits fire after edits stop, so a typing
+//      session is one commit rather than four hundred.
+//
+// The disk write has ALREADY happened by the time anything here runs. A git
+// failure therefore never loses work — it leaves the change uncommitted and
+// retries on the next quiescence. That ordering is deliberate: making the
+// commit a precondition of the save would turn a transient git error into
+// data loss, which is precisely backwards.
+
+import path from 'node:path';
+
+/** How long the tree must be quiet before a commit fires. */
+const DEFAULT_DEBOUNCE_MS = 3000;
+
+export interface GitRunResult {
+  code: number;
+  stdout: string;
+  stderr: string;
+}
+
+/** Injected so tests drive a real repo and callers can swap the runner. */
+export type GitRunner = (args: string[], opts: { cwd: string }) => Promise<GitRunResult>;
+
+export interface EditAttribution {
+  /** Display name from presence, e.g. "Alice Novak". */
+  name: string;
+  /** Address from presence, or a synthesized stable one. */
+  email: string;
+}
+
+export interface AutoCommitOptions {
+  repoRoot: string;
+  run: GitRunner;
+  /** Quiescence window. */
+  debounceMs?: number;
+  /** Committer identity — the machine, never the human. */
+  bot?: EditAttribution;
+  log?: Pick<Console, 'warn' | 'error' | 'log'>;
+}
+
+export interface AutoCommit {
+  /**
+   * Record that `relPath` changed, attributed to `who`. Repeated calls within
+   * the debounce window coalesce into one commit.
+   */
+  note(relPath: string, who?: EditAttribution | null): void;
+  /** Force the pending commit now (branch switch, shutdown). */
+  flush(): Promise<CommitOutcome | null>;
+  /** Pending paths, for tests + status surfaces. */
+  pending(): string[];
+  stop(): void;
+}
+
+export type CommitOutcome =
+  | { ok: true; sha: string; files: string[]; author: EditAttribution }
+  | { ok: false; reason: 'nothing-to-commit' | 'git-failed'; detail?: string; files: string[] };
+
+const DEFAULT_BOT: EditAttribution = {
+  name: 'Maude Workspace',
+  email: 'workspace@maude.local',
+};
+
+/**
+ * Attribution for an edit whose author we don't know.
+ *
+ * Deliberately NOT the bot: attributing an anonymous human's work to the server
+ * makes `git blame` lie in a way that is hard to notice later. "Unknown" is
+ * honest, and it is visibly wrong in a way that prompts a fix.
+ */
+export const UNKNOWN_AUTHOR: EditAttribution = {
+  name: 'Unknown editor',
+  email: 'unknown@maude.local',
+};
+
+/**
+ * Sanitize a presence-supplied identity before it reaches a git argument.
+ *
+ * Presence comes from peers over the hub, which is semi-trusted (DDR-054): a
+ * name is attacker-influenceable text. Newlines are the specific hazard —
+ * `git commit --author` takes `Name <email>`, and an embedded newline could
+ * forge trailer lines in the commit message. Everything is passed as argv (no
+ * shell), so this is about the git format, not shell quoting.
+ */
+export function sanitizeAttribution(who: EditAttribution | null | undefined): EditAttribution {
+  if (!who) return UNKNOWN_AUTHOR;
+  const clean = (s: string, fallback: string) => {
+    const out = String(s ?? '')
+      // biome-ignore lint/suspicious/noControlCharactersInRegex: stripping control chars is the point.
+      .replace(/[\s\u0000-\u001f\u007f-\u009f]+/g, ' ')
+      .replace(/[<>]/g, '')
+      .trim()
+      .slice(0, 96);
+    return out || fallback;
+  };
+  return {
+    name: clean(who.name, UNKNOWN_AUTHOR.name),
+    email: clean(who.email, UNKNOWN_AUTHOR.email),
+  };
+}
+
+/** `Name <email>` as git's `--author` wants it. */
+export function formatAuthor(who: EditAttribution): string {
+  const s = sanitizeAttribution(who);
+  return `${s.name} <${s.email}>`;
+}
+
+/**
+ * Commit subject. Names WHAT changed rather than "autosave", because a history
+ * of four hundred identical subjects is the same as no history.
+ */
+export function commitMessage(files: string[], who: EditAttribution): string {
+  // Strip from the FIRST dot, not the last: `Screen.tsx` and `Screen.meta.json`
+  // are one canvas, and counting them as two would make every commit subject
+  // overstate what changed.
+  const canvases = [...new Set(files.map((f) => path.basename(f).replace(/\..*$/, '')))].sort();
+  const subject =
+    canvases.length === 1
+      ? `design: update ${canvases[0]}`
+      : `design: update ${canvases.length} canvases`;
+  const body = [
+    '',
+    canvases.length > 1 ? canvases.map((c) => `- ${c}`).join('\n') : '',
+    '',
+    `Edited by ${who.name} <${who.email}> via the Maude workspace.`,
+    'Autosaved — append-only; this history is never rewritten.',
+  ]
+    .filter((line, i, all) => !(line === '' && all[i - 1] === ''))
+    .join('\n');
+  return `${subject}\n${body}`;
+}
+
+export function createAutoCommit(opts: AutoCommitOptions): AutoCommit {
+  const {
+    repoRoot,
+    run,
+    debounceMs = DEFAULT_DEBOUNCE_MS,
+    bot = DEFAULT_BOT,
+    log = console,
+  } = opts;
+
+  const touched = new Set<string>();
+  let author: EditAttribution | null = null;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let inFlight: Promise<CommitOutcome | null> | null = null;
+  let stopped = false;
+
+  function note(relPath: string, who?: EditAttribution | null): void {
+    if (stopped) return;
+    touched.add(relPath);
+    // Last writer wins for attribution. A commit that coalesced two people's
+    // edits can only name one author; the message body names them, and the
+    // alternative (splitting per author) would fight the quiescence batching
+    // that keeps this history readable.
+    if (who) author = who;
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = null;
+      void flush();
+    }, debounceMs);
+  }
+
+  async function flush(): Promise<CommitOutcome | null> {
+    if (inFlight) return inFlight;
+    if (timer) {
+      clearTimeout(timer);
+      timer = null;
+    }
+    if (touched.size === 0) return null;
+
+    const files = [...touched].sort();
+    const who = sanitizeAttribution(author);
+    touched.clear();
+    author = null;
+
+    inFlight = (async (): Promise<CommitOutcome> => {
+      try {
+        // Stage ONLY what changed. `git add -A` in a workspace would sweep in
+        // whatever else is in the tree — including files a future feature drops
+        // there — and the cell must never commit something it wasn't told about.
+        const add = await run(['add', '--', ...files], { cwd: repoRoot });
+        if (add.code !== 0) {
+          log.warn?.(`[autocommit] git add failed: ${add.stderr.trim()}`);
+          return { ok: false, reason: 'git-failed', detail: add.stderr.trim(), files };
+        }
+
+        // Nothing staged ⇒ the write was a no-op (an echo, or identical bytes).
+        // Not an error, and committing an empty change would be noise.
+        const staged = await run(['diff', '--cached', '--name-only'], { cwd: repoRoot });
+        if (staged.code === 0 && staged.stdout.trim() === '') {
+          return { ok: false, reason: 'nothing-to-commit', files };
+        }
+
+        const commit = await run(
+          [
+            '-c',
+            `user.name=${bot.name}`,
+            '-c',
+            `user.email=${bot.email}`,
+            'commit',
+            '--author',
+            formatAuthor(who),
+            '--only',
+            '--message',
+            commitMessage(files, who),
+            '--',
+            ...files,
+          ],
+          { cwd: repoRoot }
+        );
+        if (commit.code !== 0) {
+          log.warn?.(`[autocommit] git commit failed: ${commit.stderr.trim()}`);
+          // The bytes are on disk. Re-queue so the next quiescence retries
+          // rather than silently dropping the change from history.
+          for (const f of files) touched.add(f);
+          return { ok: false, reason: 'git-failed', detail: commit.stderr.trim(), files };
+        }
+
+        const head = await run(['rev-parse', 'HEAD'], { cwd: repoRoot });
+        const sha = head.stdout.trim();
+        log.log?.(`[autocommit] ${sha.slice(0, 8)} ${files.length} file(s) by ${who.name}`);
+        return { ok: true, sha, files, author: who };
+      } finally {
+        inFlight = null;
+      }
+    })();
+
+    return inFlight;
+  }
+
+  return {
+    note,
+    flush,
+    pending: () => [...touched].sort(),
+    stop() {
+      stopped = true;
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+      }
+    },
+  };
+}
+
+/**
+ * Push to a mirror remote, refusing anything that would rewrite it.
+ *
+ * A cell that force-pushes destroys work that exists only on the remote —
+ * exactly the hazard DDR-119 was written about, arriving from the other
+ * direction. On rejection the correct behaviour is to STOP and surface it, not
+ * to "resolve" it: a non-fast-forward means someone else's commits are there,
+ * and the cell has no way to know whether merging them is right.
+ */
+export async function pushMirror({
+  repoRoot,
+  run,
+  remote = 'origin',
+  branch,
+  log = console,
+}: {
+  repoRoot: string;
+  run: GitRunner;
+  remote?: string;
+  branch: string;
+  log?: Pick<Console, 'warn'>;
+}): Promise<{ ok: boolean; rejected: boolean; detail?: string }> {
+  // No --force, no --force-with-lease, no +refspec. If this ever needs one,
+  // that is a design conversation, not a flag.
+  const res = await run(['push', remote, `refs/heads/${branch}:refs/heads/${branch}`], {
+    cwd: repoRoot,
+  });
+  if (res.code === 0) return { ok: true, rejected: false };
+  const detail = `${res.stderr}\n${res.stdout}`.trim();
+  const rejected = /\brejected\b|non-fast-forward|fetch first/i.test(detail);
+  if (rejected) {
+    log.warn?.(
+      '[autocommit] mirror push REJECTED — someone else saved first. Stopping rather than ' +
+        'rewriting their work; the local history is intact and nothing was lost.'
+    );
+  }
+  return { ok: false, rejected, detail };
+}

package/apps/studio/sync/doc-name.ts

@@ -0,0 +1,228 @@
+// Document namespace, client side — `ws/<workspace-id>/<branch>/<slug>` (DDR-192 §5).
+//
+// ⚠ THE GRAMMAR IS MIRRORED in `apps/hub/src/doc-namespace.mjs` and the two are
+// pinned to each other by `test/sync-doc-name.test.ts`, which imports the hub's
+// implementation and asserts both agree over the same corpus. They are separate
+// files on purpose: the hub image installs frozen against its own bun.lock and
+// must not reach into apps/studio. Change one, change the other.
+//
+// WHAT IS NAMESPACED AND WHAT IS NOT: only the WIRE name changes. Every local
+// map — the provider registry, the sync agent, the projection, `_history/`,
+// `_comments/` — stays keyed by the flat slug. The namespace exists to keep two
+// projects (or two branches) from colliding INSIDE A HUB; on disk they already
+// live in different directories.
+
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+/** The prefix that marks a namespaced documentName. */
+export const DOC_NAMESPACE_PREFIX = 'ws';
+
+/** Max length of one path component (workspace id / branch / slug). */
+export const COMPONENT_MAX = 64;
+
+export interface DocNamespace {
+  workspaceId: string;
+  branch: string;
+  slug: string;
+}
+
+/**
+ * Normalize one path component into the namespace charset. `/` is the
+ * separator, so a git branch like `feature/foo` becomes `feature-foo`.
+ */
+export function sanitizeComponent(raw: string): string {
+  if (typeof raw !== 'string') return '';
+  return raw
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/-{2,}/g, '-')
+    .replace(/^[-.]+|[-.]+$/g, '')
+    .slice(0, COMPONENT_MAX)
+    .replace(/[-.]+$/g, '');
+}
+
+/** Build `ws/<workspace-id>/<branch>/<slug>`. Throws if a component is empty. */
+export function buildDocName({ workspaceId, branch, slug }: DocNamespace): string {
+  const w = sanitizeComponent(workspaceId);
+  const b = sanitizeComponent(branch);
+  const s = sanitizeComponent(slug);
+  if (!w) throw new Error('buildDocName: workspaceId is empty after normalization');
+  if (!b) throw new Error('buildDocName: branch is empty after normalization');
+  if (!s) throw new Error('buildDocName: slug is empty after normalization');
+  return `${DOC_NAMESPACE_PREFIX}/${w}/${b}/${s}`;
+}
+
+/** Parse a documentName; null means a legacy flat slug (expected, not an error). */
+export function parseDocName(name: string): DocNamespace | null {
+  if (typeof name !== 'string' || name.length === 0) return null;
+  const parts = name.split('/');
+  if (parts.length !== 4) return null;
+  const [prefix, workspaceId, branch, slug] = parts;
+  if (prefix !== DOC_NAMESPACE_PREFIX) return null;
+  if (!workspaceId || !branch || !slug) return null;
+  return { workspaceId, branch, slug };
+}
+
+/** True when `name` is a namespaced documentName. */
+export function isNamespaced(name: string): boolean {
+  return parseDocName(name) !== null;
+}
+
+// ---------------------------------------------------------------------------
+// Resolution — where the workspace id and the branch actually come from
+// ---------------------------------------------------------------------------
+
+/**
+ * Current branch, read straight from `.git/HEAD` (no subprocess — the same
+ * source `collab/git-lifecycle.ts` watches).
+ *
+ * A detached HEAD yields `detached-<sha7>`, which is a *stable* name for that
+ * commit: two peers detached at the same commit meet, and a peer on a branch
+ * never accidentally shares a doc with a detached checkout.
+ *
+ * Returns null when there is no git repo at all.
+ */
+export function readBranch(repoRoot: string): string | null {
+  const headPath = path.join(repoRoot, '.git', 'HEAD');
+  if (!existsSync(headPath)) return null;
+  let head: string;
+  try {
+    head = readFileSync(headPath, 'utf8').trim();
+  } catch {
+    return null;
+  }
+  const ref = head.match(/^ref:\s*refs\/heads\/(.+)$/);
+  if (ref?.[1]) return ref[1];
+  if (/^[0-9a-f]{7,40}$/i.test(head)) return `detached-${head.slice(0, 7)}`;
+  return null;
+}
+
+/**
+ * Read the `origin` remote URL from `.git/config` without shelling out.
+ * Returns null when there is no origin (a purely local repo).
+ */
+export function readOriginUrl(repoRoot: string): string | null {
+  const cfgPath = path.join(repoRoot, '.git', 'config');
+  if (!existsSync(cfgPath)) return null;
+  let raw: string;
+  try {
+    raw = readFileSync(cfgPath, 'utf8');
+  } catch {
+    return null;
+  }
+  const section = raw.match(/\[remote "origin"\]([\s\S]*?)(?=\n\[|$)/);
+  const url = section?.[1]?.match(/^\s*url\s*=\s*(.+)$/m)?.[1]?.trim();
+  return url && url.length > 0 ? url : null;
+}
+
+/**
+ * Reduce a git remote URL to a stable `<owner>-<repo>` identity, so
+ * `git@github.com:1aGh/maude.git` and `https://github.com/1aGh/maude` — the
+ * same project cloned two different ways — produce the SAME workspace id.
+ *
+ * Getting this wrong is not a cosmetic bug: two peers of one project that
+ * derive different ids would stop meeting, and each would see the other's docs
+ * as absent.
+ */
+export function workspaceIdFromRemote(url: string): string {
+  let s = url.trim().replace(/\.git$/i, '');
+  s = s.replace(/^[a-z0-9+.-]+:\/\//i, ''); // scheme
+  s = s.replace(/^[^@/]+@/, ''); // user@
+  s = s.replace(/^([^/:]+):/, '$1/'); // scp-style host:path → host/path
+  const segments = s.split('/').filter(Boolean);
+  const tail = segments.slice(-2); // <owner>/<repo>
+  return sanitizeComponent(tail.join('-'));
+}
+
+export interface ResolveWorkspaceOpts {
+  /** Explicit id from config — authoritative when present (the cloud sets it). */
+  explicit?: string | undefined;
+  repoRoot: string;
+}
+
+/**
+ * Resolve the workspace id, or null when it cannot be derived in a way that is
+ * STABLE ACROSS MACHINES.
+ *
+ * Order: explicit config → git origin remote. There is deliberately no
+ * directory-name fallback: a local path is not the same on two machines, so
+ * deriving from it would split peers of the same project into separate
+ * documents — the exact failure the namespace exists to prevent, arrived at
+ * from the other direction. No stable id ⇒ stay flat (see `createDocNameResolver`).
+ */
+export function resolveWorkspaceId({ explicit, repoRoot }: ResolveWorkspaceOpts): string | null {
+  const fromConfig = sanitizeComponent(explicit ?? '');
+  if (fromConfig) return fromConfig;
+  const origin = readOriginUrl(repoRoot);
+  if (!origin) return null;
+  const derived = workspaceIdFromRemote(origin);
+  return derived || null;
+}
+
+export interface DocNameResolver {
+  /** Map a local canvas slug to the name used on the wire. */
+  (slug: string): string;
+}
+
+export interface DocNameResolverOpts {
+  repoRoot: string;
+  /** `linkedHub.workspaceId` when the config carries one. */
+  explicitWorkspaceId?: string | undefined;
+  /** `MAUDE_HUB_NAMESPACED` — '1' forces on, '0' forces off, absent = auto. */
+  flag?: string | undefined;
+  /** Test seam: override branch detection. */
+  branch?: string | undefined;
+}
+
+/**
+ * Build the slug → documentName mapping for this process.
+ *
+ * Rollout rule (DDR-192 §5): namespacing CHANGES DOC IDENTITY, so it is opt-in
+ * for now and becomes default-on in workspace mode (Phase 3).
+ *
+ *   MAUDE_HUB_NAMESPACED=0  → always flat, even with an explicit workspace id
+ *   MAUDE_HUB_NAMESPACED=1  → namespaced, and it is an ERROR to be unable to
+ *                             (an operator who asked for isolation gets a loud
+ *                             failure, never a silent fallback into a shared doc)
+ *   unset                   → namespaced only when config declares a workspace
+ *                             id explicitly; otherwise flat
+ *
+ * The auto case is deliberately NOT "namespace whenever a git origin exists":
+ * flipping identity under an existing linked hub would make every doc look
+ * freshly empty. DDR-076 keeps that from eating local files, but the hub-side
+ * history would be orphaned, and nobody asked for that on upgrade.
+ */
+export function createDocNameResolver(opts: DocNameResolverOpts): DocNameResolver {
+  const flag = opts.flag;
+  if (flag === '0') return (slug) => slug;
+
+  const workspaceId = resolveWorkspaceId({
+    explicit: opts.explicitWorkspaceId,
+    repoRoot: opts.repoRoot,
+  });
+  const branch = sanitizeComponent(opts.branch ?? readBranch(opts.repoRoot) ?? '');
+
+  if (flag === '1') {
+    if (!workspaceId) {
+      throw new Error(
+        'MAUDE_HUB_NAMESPACED=1 but no workspace id could be resolved. Set ' +
+          '`linkedHub.workspaceId` in .design/config.json, or give the repo an ' +
+          '`origin` remote. Refusing to fall back to flat slugs — that would put ' +
+          'this project in a shared document namespace (DDR-192 §5).'
+      );
+    }
+    if (!branch) {
+      throw new Error(
+        'MAUDE_HUB_NAMESPACED=1 but the current branch could not be read from ' +
+          '.git/HEAD. Refusing to fall back to flat slugs (DDR-192 §5).'
+      );
+    }
+  }
+
+  const explicitlyDeclared = sanitizeComponent(opts.explicitWorkspaceId ?? '') !== '';
+  const on = flag === '1' || (explicitlyDeclared && !!workspaceId && !!branch);
+  if (!on || !workspaceId || !branch) return (slug) => slug;
+
+  return (slug) => buildDocName({ workspaceId, branch, slug });
+}