@1agh/maude 0.47.0 → 0.49.0

package/apps/studio/test/sync-autocommit.test.ts

@@ -0,0 +1,334 @@
+// Cloud Phase 3 Task 1 — autosave as append-only git commits.
+//
+// Driven against a REAL git repository in a temp dir, not a mocked runner. The
+// properties that matter (authorship survives, history is never rewritten, a
+// no-op write produces no commit) are properties of git's actual behaviour, and
+// a mock would only prove that the arguments match what I expected them to be.
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+
+import { spawn } from 'node:child_process';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import {
+  commitMessage,
+  createAutoCommit,
+  formatAuthor,
+  type GitRunner,
+  pushMirror,
+  sanitizeAttribution,
+  UNKNOWN_AUTHOR,
+} from '../sync/autocommit.ts';
+
+const git: GitRunner = (args, { cwd }) =>
+  new Promise((resolve) => {
+    const child = spawn('git', args, {
+      cwd,
+      env: { ...process.env, GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_SYSTEM: '/dev/null' },
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (d) => {
+      stdout += d;
+    });
+    child.stderr.on('data', (d) => {
+      stderr += d;
+    });
+    child.on('close', (code) => resolve({ code: code ?? 1, stdout, stderr }));
+  });
+
+let repo: string;
+
+async function initRepo(): Promise<string> {
+  const dir = mkdtempSync(path.join(tmpdir(), 'maude-autocommit-'));
+  await git(['init', '--initial-branch=main'], { cwd: dir });
+  await git(['config', 'user.name', 'Seed'], { cwd: dir });
+  await git(['config', 'user.email', 'seed@example.com'], { cwd: dir });
+  mkdirSync(path.join(dir, '.design', 'ui'), { recursive: true });
+  writeFileSync(path.join(dir, '.design', 'ui', 'Screen.tsx'), 'export default () => null;\n');
+  await git(['add', '-A'], { cwd: dir });
+  await git(['commit', '-m', 'seed'], { cwd: dir });
+  return dir;
+}
+
+const ALICE = { name: 'Alice Novák', email: 'alice@example.com' };
+const BOB = { name: 'Bob', email: 'bob@example.com' };
+const REL = '.design/ui/Screen.tsx';
+
+const write = (rel: string, body: string) => writeFileSync(path.join(repo, rel), body);
+const log = async (fmt: string) =>
+  (await git(['log', `--pretty=format:${fmt}`], { cwd: repo })).stdout.split('\n').filter(Boolean);
+
+beforeEach(async () => {
+  repo = await initRepo();
+});
+
+afterEach(() => {
+  if (repo) rmSync(repo, { recursive: true, force: true });
+});
+
+describe('attribution', () => {
+  test('a missing author is UNKNOWN, never 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 visibly
+    // wrong.
+    expect(sanitizeAttribution(null)).toEqual(UNKNOWN_AUTHOR);
+    expect(sanitizeAttribution(undefined)).toEqual(UNKNOWN_AUTHOR);
+    expect(sanitizeAttribution({ name: '', email: '' })).toEqual(UNKNOWN_AUTHOR);
+  });
+
+  test('presence-supplied identity cannot forge commit trailers', () => {
+    // Presence arrives over a semi-trusted hub (DDR-054): a name is
+    // attacker-influenceable text, and `--author` takes `Name <email>`.
+    const evil = sanitizeAttribution({
+      name: 'Real Person <real@example.com>\nSigned-off-by: Someone Else',
+      email: 'a@b.com\r\nCo-Authored-By: Nobody',
+    });
+    expect(evil.name).not.toContain('\n');
+    expect(evil.name).not.toContain('<');
+    expect(evil.name).not.toContain('>');
+    expect(evil.email).not.toContain('\r');
+    expect(formatAuthor(evil)).toMatch(/^[^<>\n]+ <[^<>\n]+>$/);
+  });
+
+  test('names are bounded so one peer cannot bloat every commit', () => {
+    const long = sanitizeAttribution({ name: 'x'.repeat(500), email: 'y'.repeat(500) });
+    expect(long.name.length).toBeLessThanOrEqual(96);
+    expect(long.email.length).toBeLessThanOrEqual(96);
+  });
+
+  test('unicode names survive intact — this is a real person, not a slug', () => {
+    expect(sanitizeAttribution(ALICE).name).toBe('Alice Novák');
+  });
+});
+
+describe('commit message', () => {
+  test('names the canvas rather than saying "autosave"', () => {
+    // 400 identical subjects is the same as no history.
+    const one = commitMessage(['.design/ui/Screen.tsx'], ALICE);
+    expect(one.split('\n')[0]).toBe('design: update Screen');
+    expect(one).toContain('Alice Novák <alice@example.com>');
+    expect(one).toContain('append-only');
+  });
+
+  test('a multi-file commit summarizes and lists', () => {
+    const many = commitMessage(
+      ['.design/ui/Screen.tsx', '.design/ui/Settings.tsx', '.design/ui/Screen.meta.json'],
+      ALICE
+    );
+    // Screen.tsx + Screen.meta.json are ONE canvas — a subject that said
+    // "3 canvases" would overstate what changed on every single commit.
+    expect(many.split('\n')[0]).toBe('design: update 2 canvases');
+    expect(many).toContain('- Screen');
+    expect(many).toContain('- Settings');
+    expect(many).not.toContain('- Screen.meta');
+  });
+});
+
+describe('committing, against a real repo', () => {
+  test('an edit becomes a commit authored by the HUMAN, committed by the bot', async () => {
+    const auto = createAutoCommit({ repoRoot: repo, run: git, debounceMs: 5, log: silent() });
+    write(REL, 'export default () => <main>alice was here</main>;\n');
+    auto.note(REL, ALICE);
+
+    const outcome = await auto.flush();
+    expect(outcome?.ok).toBe(true);
+
+    // This is the point of using git's author/committer split at all: blame
+    // answers "who designed this", not "the server did".
+    expect(await log('%an|%ae')).toEqual([
+      'Alice Novák|alice@example.com',
+      'Seed|seed@example.com',
+    ]);
+    expect((await log('%cn'))[0]).toBe('Maude Workspace');
+    expect((await log('%s'))[0]).toBe('design: update Screen');
+  });
+
+  test('edits COALESCE — a typing session is one commit, not four hundred', async () => {
+    const auto = createAutoCommit({ repoRoot: repo, run: git, debounceMs: 5, log: silent() });
+    for (let i = 0; i < 20; i++) {
+      write(REL, `export default () => <main>v${i}</main>;\n`);
+      auto.note(REL, ALICE);
+    }
+    await auto.flush();
+    expect((await log('%s')).length).toBe(2); // seed + one autosave
+  });
+
+  test('a no-op write produces NO commit', async () => {
+    // An echo, or a write of identical bytes. Committing it would be noise.
+    const auto = createAutoCommit({ repoRoot: repo, run: git, debounceMs: 5, log: silent() });
+    auto.note(REL, ALICE);
+    const outcome = await auto.flush();
+    expect(outcome?.ok).toBe(false);
+    expect(outcome && !outcome.ok && outcome.reason).toBe('nothing-to-commit');
+    expect((await log('%s')).length).toBe(1);
+  });
+
+  test('only the NOTED files are staged — an unrelated dirty file is left alone', async () => {
+    // `git add -A` in a workspace would sweep in whatever else is in the tree.
+    // The cell must never commit something it wasn't told about.
+    const auto = createAutoCommit({ repoRoot: repo, run: git, debounceMs: 5, log: silent() });
+    write(REL, 'export default () => <main>noted</main>;\n');
+    writeFileSync(path.join(repo, 'UNRELATED.md'), 'not part of the design\n');
+    auto.note(REL, ALICE);
+    await auto.flush();
+
+    const show = await git(['show', '--name-only', '--pretty=format:', 'HEAD'], { cwd: repo });
+    expect(show.stdout.trim()).toBe(REL);
+    const status = await git(['status', '--porcelain'], { cwd: repo });
+    expect(status.stdout).toContain('UNRELATED.md');
+  });
+
+  test('history is APPEND-ONLY — an earlier state is still reachable', async () => {
+    const auto = createAutoCommit({ repoRoot: repo, run: git, debounceMs: 5, log: silent() });
+    write(REL, 'export default () => <main>first</main>;\n');
+    auto.note(REL, ALICE);
+    await auto.flush();
+    const firstSha = (await log('%H'))[0];
+
+    write(REL, 'export default () => <main>second</main>;\n');
+    auto.note(REL, BOB);
+    await auto.flush();
+
+    // The old content is still there — the guarantee that makes a cell's
+    // autosave safe to trust with someone's only copy.
+    const old = await git(['show', `${firstSha}:${REL}`], { cwd: repo });
+    expect(old.stdout).toContain('first');
+    expect((await log('%s')).length).toBe(3);
+    expect(await log('%an')).toEqual(['Bob', 'Alice Novák', 'Seed']);
+  });
+
+  test('two peers editing before quiescence produce one commit, attributed to the last', async () => {
+    const auto = createAutoCommit({ repoRoot: repo, run: git, debounceMs: 5, log: silent() });
+    write(REL, 'export default () => <main>alice</main>;\n');
+    auto.note(REL, ALICE);
+    write(path.join('.design', 'ui', 'Second.tsx'), '');
+    writeFileSync(path.join(repo, '.design/ui/Second.tsx'), 'export default () => null;\n');
+    auto.note('.design/ui/Second.tsx', BOB);
+    await auto.flush();
+
+    expect((await log('%an'))[0]).toBe('Bob');
+    expect((await log('%s'))[0]).toBe('design: update 2 canvases');
+  });
+
+  test('a git failure RE-QUEUES the change instead of dropping it', async () => {
+    // The bytes are already on disk, so a git error must not remove the change
+    // from history permanently — making the commit a precondition of the save
+    // would turn a transient error into data loss.
+    let failNext = true;
+    const flaky: GitRunner = async (args, opts) => {
+      if (args.includes('commit') && failNext) {
+        failNext = false;
+        return { code: 1, stdout: '', stderr: 'simulated git failure' };
+      }
+      return git(args, opts);
+    };
+    const auto = createAutoCommit({ repoRoot: repo, run: flaky, debounceMs: 5, log: silent() });
+    write(REL, 'export default () => <main>retry me</main>;\n');
+    auto.note(REL, ALICE);
+
+    const first = await auto.flush();
+    expect(first?.ok).toBe(false);
+    expect(auto.pending()).toEqual([REL]);
+
+    const second = await auto.flush();
+    expect(second?.ok).toBe(true);
+    expect((await log('%s')).length).toBe(2);
+  });
+
+  test('flush with nothing pending is a no-op, not an empty commit', async () => {
+    const auto = createAutoCommit({ repoRoot: repo, run: git, debounceMs: 5, log: silent() });
+    expect(await auto.flush()).toBe(null);
+    expect((await log('%s')).length).toBe(1);
+  });
+
+  test('stop() prevents further scheduling', async () => {
+    const auto = createAutoCommit({ repoRoot: repo, run: git, debounceMs: 5, log: silent() });
+    auto.stop();
+    write(REL, 'export default () => <main>after stop</main>;\n');
+    auto.note(REL, ALICE);
+    expect(auto.pending()).toEqual([]);
+  });
+});
+
+describe('mirror push — never rewrites someone else’s work', () => {
+  test('a non-fast-forward push is REPORTED as rejected, never forced', async () => {
+    // The cell has no way to know whether merging a stranger's commits is
+    // right, so it stops and surfaces it. DDR-119's hazard, arriving from the
+    // other direction.
+    const remote = mkdtempSync(path.join(tmpdir(), 'maude-remote-'));
+    await git(['init', '--bare', '--initial-branch=main'], { cwd: remote });
+    await git(['remote', 'add', 'origin', remote], { cwd: repo });
+    await git(['push', 'origin', 'main'], { cwd: repo });
+
+    // Someone else pushes first, from a separate clone.
+    const other = mkdtempSync(path.join(tmpdir(), 'maude-other-'));
+    await git(['clone', remote, other], { cwd: path.dirname(other) });
+    await git(['config', 'user.name', 'Other'], { cwd: other });
+    await git(['config', 'user.email', 'other@example.com'], { cwd: other });
+    writeFileSync(path.join(other, 'theirs.txt'), 'their work\n');
+    await git(['add', '-A'], { cwd: other });
+    await git(['commit', '-m', 'their work'], { cwd: other });
+    await git(['push', 'origin', 'main'], { cwd: other });
+
+    // Now the cell has a diverging commit.
+    const auto = createAutoCommit({ repoRoot: repo, run: git, debounceMs: 5, log: silent() });
+    write(REL, 'export default () => <main>ours</main>;\n');
+    auto.note(REL, ALICE);
+    await auto.flush();
+
+    const res = await pushMirror({ repoRoot: repo, run: git, branch: 'main', log: silent() });
+    expect(res.ok).toBe(false);
+    expect(res.rejected).toBe(true);
+
+    // Their commit is still the remote's tip — nothing of theirs was destroyed.
+    const remoteLog = await git(['log', '--pretty=format:%s', 'main'], { cwd: remote });
+    expect(remoteLog.stdout.split('\n')[0]).toBe('their work');
+
+    rmSync(remote, { recursive: true, force: true });
+    rmSync(other, { recursive: true, force: true });
+  });
+
+  test('a fast-forward push succeeds', async () => {
+    const remote = mkdtempSync(path.join(tmpdir(), 'maude-remote-ok-'));
+    await git(['init', '--bare', '--initial-branch=main'], { cwd: remote });
+    await git(['remote', 'add', 'origin', remote], { cwd: repo });
+    await git(['push', 'origin', 'main'], { cwd: repo });
+
+    const auto = createAutoCommit({ repoRoot: repo, run: git, debounceMs: 5, log: silent() });
+    write(REL, 'export default () => <main>ours</main>;\n');
+    auto.note(REL, ALICE);
+    await auto.flush();
+
+    const res = await pushMirror({ repoRoot: repo, run: git, branch: 'main', log: silent() });
+    expect(res.ok).toBe(true);
+    expect(res.rejected).toBe(false);
+
+    rmSync(remote, { recursive: true, force: true });
+  });
+
+  test('pushMirror never passes a force flag', async () => {
+    // Pinned as an argv assertion: the guarantee is the ABSENCE of a flag, and
+    // absence is exactly what a future edit could add without any test noticing.
+    const seen: string[][] = [];
+    await pushMirror({
+      repoRoot: repo,
+      branch: 'main',
+      run: async (args) => {
+        seen.push(args);
+        return { code: 0, stdout: '', stderr: '' };
+      },
+      log: silent(),
+    });
+    const flat = seen.flat();
+    expect(flat.some((a) => /^--force/.test(a))).toBe(false);
+    expect(flat.some((a) => a.startsWith('+'))).toBe(false);
+    expect(flat).toContain('refs/heads/main:refs/heads/main');
+  });
+});
+
+function silent() {
+  return { warn: () => {}, error: () => {}, log: () => {} };
+}

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

@@ -0,0 +1,281 @@
+// DDR-192 §5 — the `ws/<workspace-id>/<branch>/<slug>` document namespace,
+// client side: resolution (where the workspace id and branch come from), the
+// opt-in rollout rule, conformance with the hub's independent implementation,
+// and the DDR-076 fresh-doc case that makes changing doc identity safe.
+
+import { describe, expect, test } from 'bun:test';
+
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+// The HUB's implementation, imported across the package boundary on purpose —
+// this file is what pins the two grammars to each other (see doc-name.ts).
+import * as hub from '../../hub/src/doc-namespace.mjs';
+import { decideColdStart } from '../sync/cold-start.ts';
+import {
+  buildDocName,
+  createDocNameResolver,
+  isNamespaced,
+  parseDocName,
+  readBranch,
+  readOriginUrl,
+  resolveWorkspaceId,
+  sanitizeComponent,
+  workspaceIdFromRemote,
+} from '../sync/doc-name.ts';
+
+/** A throwaway repo skeleton: `.git/HEAD` + optionally `.git/config`. */
+function makeRepo(opts: { head?: string; origin?: string } = {}): string {
+  const root = mkdtempSync(path.join(tmpdir(), 'maude-docname-'));
+  mkdirSync(path.join(root, '.git'), { recursive: true });
+  writeFileSync(path.join(root, '.git', 'HEAD'), opts.head ?? 'ref: refs/heads/main\n');
+  if (opts.origin) {
+    writeFileSync(
+      path.join(root, '.git', 'config'),
+      `[core]\n\trepositoryformatversion = 0\n[remote "origin"]\n\turl = ${opts.origin}\n\tfetch = +refs/heads/*:refs/remotes/origin/*\n[branch "main"]\n\tremote = origin\n`
+    );
+  }
+  return root;
+}
+
+describe('doc-name — resolution inputs', () => {
+  test('readBranch reads a branch, a slash-branch, and a detached HEAD', () => {
+    const a = makeRepo({ head: 'ref: refs/heads/main\n' });
+    const b = makeRepo({ head: 'ref: refs/heads/feature/cloud-arc\n' });
+    const c = makeRepo({ head: '9f1c0a2b3c4d5e6f708192a3b4c5d6e7f8091a2b\n' });
+    const none = mkdtempSync(path.join(tmpdir(), 'maude-nogit-'));
+    try {
+      expect(readBranch(a)).toBe('main');
+      expect(readBranch(b)).toBe('feature/cloud-arc');
+      // A detached HEAD gets a STABLE name for that commit, so two peers
+      // detached at the same commit meet and neither joins a branch's doc.
+      expect(readBranch(c)).toBe('detached-9f1c0a2');
+      expect(readBranch(none)).toBe(null);
+    } finally {
+      for (const d of [a, b, c, none]) rmSync(d, { recursive: true, force: true });
+    }
+  });
+
+  test('readOriginUrl picks origin out of .git/config, ignoring other remotes', () => {
+    const root = makeRepo({ origin: 'git@github.com:1aGh/maude.git' });
+    try {
+      expect(readOriginUrl(root)).toBe('git@github.com:1aGh/maude.git');
+      writeFileSync(
+        path.join(root, '.git', 'config'),
+        '[remote "upstream"]\n\turl = https://example.com/x/y.git\n'
+      );
+      expect(readOriginUrl(root)).toBe(null);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test('the same project cloned different ways yields the SAME workspace id', () => {
+    // This is the property that decides whether two peers meet at all. If SSH
+    // and HTTPS clones of one repo derived different ids, each peer would see
+    // the other's documents as simply absent.
+    const forms = [
+      'git@github.com:1aGh/maude.git',
+      'https://github.com/1aGh/maude.git',
+      'https://github.com/1aGh/maude',
+      'ssh://git@github.com/1aGh/maude.git',
+      'https://user:tok@github.com/1aGh/maude.git',
+    ];
+    const ids = new Set(forms.map(workspaceIdFromRemote));
+    expect([...ids]).toEqual(['1agh-maude']);
+  });
+
+  test('different projects yield different workspace ids', () => {
+    expect(workspaceIdFromRemote('git@github.com:1aGh/maude.git')).not.toBe(
+      workspaceIdFromRemote('git@github.com:1aGh/dugmate.git')
+    );
+    expect(workspaceIdFromRemote('git@github.com:acme/site.git')).not.toBe(
+      workspaceIdFromRemote('git@gitlab.com:other/site.git')
+    );
+  });
+
+  test('resolveWorkspaceId prefers explicit config, then origin, then nothing', () => {
+    const withOrigin = makeRepo({ origin: 'git@github.com:acme/site.git' });
+    const noOrigin = makeRepo();
+    try {
+      expect(resolveWorkspaceId({ explicit: 'cloud-abc123', repoRoot: withOrigin })).toBe(
+        'cloud-abc123'
+      );
+      expect(resolveWorkspaceId({ repoRoot: withOrigin })).toBe('acme-site');
+      // No origin and no config: null. NOT a directory-name fallback — a local
+      // path differs per machine, so deriving from it would split peers apart.
+      expect(resolveWorkspaceId({ repoRoot: noOrigin })).toBe(null);
+    } finally {
+      rmSync(withOrigin, { recursive: true, force: true });
+      rmSync(noOrigin, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('doc-name — the rollout rule', () => {
+  test('unset flag + no explicit workspace id ⇒ flat (an upgrade changes nothing)', () => {
+    const root = makeRepo({ origin: 'git@github.com:acme/site.git' });
+    try {
+      const resolve = createDocNameResolver({ repoRoot: root });
+      expect(resolve('ui-screen')).toBe('ui-screen');
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test('an explicitly declared workspace id opts in', () => {
+    const root = makeRepo({ origin: 'git@github.com:acme/site.git' });
+    try {
+      const resolve = createDocNameResolver({ repoRoot: root, explicitWorkspaceId: 'acme-site' });
+      expect(resolve('ui-screen')).toBe('ws/acme-site/main/ui-screen');
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test('MAUDE_HUB_NAMESPACED=0 forces flat even with an explicit id', () => {
+    const root = makeRepo({ origin: 'git@github.com:acme/site.git' });
+    try {
+      const resolve = createDocNameResolver({
+        repoRoot: root,
+        explicitWorkspaceId: 'acme-site',
+        flag: '0',
+      });
+      expect(resolve('ui-screen')).toBe('ui-screen');
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test('MAUDE_HUB_NAMESPACED=1 namespaces from the origin remote', () => {
+    const root = makeRepo({
+      origin: 'git@github.com:acme/site.git',
+      head: 'ref: refs/heads/dev\n',
+    });
+    try {
+      const resolve = createDocNameResolver({ repoRoot: root, flag: '1' });
+      expect(resolve('ui-screen')).toBe('ws/acme-site/dev/ui-screen');
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test('MAUDE_HUB_NAMESPACED=1 with nothing to derive from THROWS, never falls back', () => {
+    // A silent fallback here would put a project the operator asked to isolate
+    // into the shared flat namespace — the failure mode is worse than a crash.
+    const noOrigin = makeRepo();
+    const noGit = mkdtempSync(path.join(tmpdir(), 'maude-nogit-'));
+    try {
+      expect(() => createDocNameResolver({ repoRoot: noOrigin, flag: '1' })).toThrow(
+        /workspace id/i
+      );
+      expect(() =>
+        createDocNameResolver({ repoRoot: noGit, flag: '1', explicitWorkspaceId: 'acme' })
+      ).toThrow(/branch/i);
+    } finally {
+      rmSync(noOrigin, { recursive: true, force: true });
+      rmSync(noGit, { recursive: true, force: true });
+    }
+  });
+
+  test('a branch with a slash is normalized, not rejected', () => {
+    const root = makeRepo({ head: 'ref: refs/heads/feature/cloud-arc\n' });
+    try {
+      const resolve = createDocNameResolver({ repoRoot: root, explicitWorkspaceId: 'acme' });
+      expect(resolve('ui-screen')).toBe('ws/acme/feature-cloud-arc/ui-screen');
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('doc-name — conformance with the hub implementation', () => {
+  const components = [
+    'main',
+    'feature/cloud-arc',
+    'Release/2026.07',
+    '  --weird--  ',
+    '...',
+    '',
+    'x'.repeat(200),
+    'ui-screen',
+    'a/b/c',
+  ];
+
+  test('sanitizeComponent agrees byte-for-byte', () => {
+    for (const c of components) {
+      expect(sanitizeComponent(c)).toBe(hub.sanitizeComponent(c));
+    }
+  });
+
+  test('buildDocName agrees, including which inputs throw', () => {
+    for (const w of components) {
+      for (const b of ['main', '...']) {
+        const args = { workspaceId: w, branch: b, slug: 'ui-screen' };
+        let mine: string | Error;
+        let theirs: string | Error;
+        try {
+          mine = buildDocName(args);
+        } catch (e) {
+          mine = e as Error;
+        }
+        try {
+          theirs = hub.buildDocName(args);
+        } catch (e) {
+          theirs = e as Error;
+        }
+        if (mine instanceof Error || theirs instanceof Error) {
+          expect(mine instanceof Error).toBe(theirs instanceof Error);
+        } else {
+          expect(mine).toBe(theirs);
+        }
+      }
+    }
+  });
+
+  test('parseDocName agrees over namespaced, legacy, and malformed names', () => {
+    const names = [
+      'ws/acme/main/ui-screen',
+      'ui-screen',
+      '',
+      'ws/acme/main',
+      'ws/acme/main/a/b',
+      'x/acme/main/ui',
+      'ws//main/ui',
+      'ws/acme//ui',
+    ];
+    for (const n of names) {
+      expect(parseDocName(n)).toEqual(hub.parseDocName(n));
+      expect(isNamespaced(n)).toBe(hub.isNamespaced(n));
+    }
+  });
+});
+
+describe('doc-name — changing identity is safe (DDR-076)', () => {
+  test('a freshly namespaced doc is EMPTY, and empty never clobbers local files', () => {
+    const root = makeRepo({ origin: 'git@github.com:acme/site.git' });
+    try {
+      // The rename itself: the same canvas addressed under a new identity.
+      const flat = createDocNameResolver({ repoRoot: root });
+      const namespaced = createDocNameResolver({ repoRoot: root, flag: '1' });
+      expect(flat('ui-screen')).toBe('ui-screen');
+      expect(namespaced('ui-screen')).toBe('ws/acme-site/main/ui-screen');
+      expect(namespaced('ui-screen')).not.toBe(flat('ui-screen'));
+
+      // Consequence: on first connect the hub has nothing under the new name.
+      // DDR-076 — that means "not seeded yet", never "authoritatively blank".
+      const decision = decideColdStart({
+        localBody: '<main>real local work</main>',
+        docBody: '',
+        journalHash: null,
+        localMtimeMs: Date.now(),
+        docBodyEditAtMs: null,
+      });
+      expect(decision.action).toBe('seed-local-up');
+      expect(decision.winner).toBeUndefined();
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});