@1agh/maude 0.60.7 → 1.0.2

package/apps/studio/test/cold-start-apply.test.ts

@@ -0,0 +1,303 @@
+// The ONE cold-start application body — Sync v2 Increment 0 (DDR-226).
+//
+// Three things are pinned here:
+//
+//   1. **The tripwire.** Both architectures import `sync/cold-start-apply.ts`.
+//      DDR-102 said the decision table is "a pure module consumed by BOTH sync
+//      paths" — the table was, the APPLICATION was not, and the twin switches
+//      drifted three times (DDR-076's empty-hub guard written twice, DDR-223's
+//      eraser FIXED twice, and the `recover-seed-dup` fallthrough below). This
+//      test makes a re-split a red test, the same way
+//      `sync-file-membership.test.ts` pins the classifier's hub mirror.
+//
+//   2. **Totality.** Every `ColdStartAction` reaches a row and produces the
+//      right body winner + effect. The compile-time `never` default catches new
+//      actions at build time; this catches a hand-edited switch at test time.
+//
+//   3. **The live regression.** `migrateSeed` on a hub body that is the local
+//      body repeated must COLLAPSE it, not keep it. Before this module,
+//      migrate-seed's switch had no `recover-seed-dup` case and no default, so
+//      the decision fell through to `hub-wins` and the duplicated body was kept
+//      and materialized to disk — an un-buildable canvas (two `export default`).
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import * as Y from 'yjs';
+
+import { applyHtmlToDoc } from '../sync/codec.ts';
+import type { ColdStartAction, ColdStartDecision } from '../sync/cold-start.ts';
+import { decideColdStart } from '../sync/cold-start.ts';
+import { applyColdStart } from '../sync/cold-start-apply.ts';
+import { migrateSeed } from '../sync/migrate-seed.ts';
+import { ORIGINS } from '../sync/origins.ts';
+
+const SYNC_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', 'sync');
+
+/** Every action the table can emit. Kept as a literal list on purpose: if
+ *  `ColdStartAction` grows a member, the `satisfies` below fails to compile. */
+const ALL_ACTIONS = [
+  'noop',
+  'materialize-hub',
+  'seed-local-up',
+  'fast-forward-hub',
+  'recover-seed-dup',
+  'conflict',
+] as const satisfies readonly ColdStartAction[];
+
+const silent = { warn: () => {}, error: () => {} };
+
+/** Record which effect the applier invoked. */
+function spyOps() {
+  const calls: string[] = [];
+  return {
+    calls,
+    takeHub: () => {
+      calls.push('takeHub');
+    },
+    takeLocal: (body: string) => {
+      calls.push(`takeLocal:${body}`);
+    },
+    checkpointIdentity: (body: string) => {
+      calls.push(`checkpoint:${body}`);
+    },
+  };
+}
+
+describe('cold-start-apply — the tripwire (one applier, both architectures)', () => {
+  test('agent.ts and migrate-seed.ts both import cold-start-apply.ts', () => {
+    for (const file of ['agent.ts', 'migrate-seed.ts']) {
+      const src = readFileSync(join(SYNC_DIR, file), 'utf8');
+      expect(src).toContain("from './cold-start-apply.ts'");
+      expect(src).toContain('applyColdStart(');
+    }
+  });
+
+  test('neither caller keeps a private switch over decision.action', () => {
+    // The whole point of the module: the row set lives in ONE place. A
+    // `switch (decision.action)` reappearing in either caller is the drift
+    // this test exists to catch.
+    for (const file of ['agent.ts', 'migrate-seed.ts']) {
+      const src = readFileSync(join(SYNC_DIR, file), 'utf8');
+      expect(src).not.toContain('switch (decision.action)');
+    }
+  });
+});
+
+describe('cold-start-apply — total over every action', () => {
+  test.each(ALL_ACTIONS)('%s reaches a row', async (action) => {
+    const decision: ColdStartDecision = {
+      action,
+      reason: 'test',
+      ...(action === 'conflict' ? { winner: 'hub' as const } : {}),
+    };
+    const ops = spyOps();
+    const result = await applyColdStart({
+      slug: 's',
+      decision,
+      localBody: 'LOCAL',
+      docBody: 'HUB',
+      log: silent,
+      ...ops,
+    });
+    expect(result.action).toBe(action);
+    expect(['local', 'hub']).toContain(result.bodyWinner);
+  });
+
+  test('an action with no row throws instead of silently keeping the hub', async () => {
+    const ops = spyOps();
+    await expect(
+      applyColdStart({
+        slug: 's',
+        // Deliberately outside the union — the shape a hand-edited table or a
+        // stale build would produce.
+        decision: { action: 'invented-row' as ColdStartAction, reason: 'test' },
+        localBody: 'LOCAL',
+        docBody: 'HUB',
+        log: silent,
+        ...ops,
+      })
+    ).rejects.toThrow(/unhandled action/);
+    expect(ops.calls).toEqual([]);
+  });
+
+  test('winners and effects per row', async () => {
+    const expected: Array<[ColdStartAction, 'local' | 'hub', string | null]> = [
+      ['noop', 'hub', null],
+      ['materialize-hub', 'hub', 'takeHub'],
+      ['fast-forward-hub', 'hub', 'takeHub'],
+      ['seed-local-up', 'local', 'takeLocal:LOCAL'],
+      ['recover-seed-dup', 'local', 'takeLocal:LOCAL'],
+    ];
+    for (const [action, winner, call] of expected) {
+      const ops = spyOps();
+      const result = await applyColdStart({
+        slug: 's',
+        decision: { action, reason: 'test' },
+        localBody: 'LOCAL',
+        docBody: 'HUB',
+        log: silent,
+        ...ops,
+      });
+      expect(result.bodyWinner).toBe(winner);
+      expect(ops.calls).toEqual(call === null ? [] : [call]);
+    }
+  });
+
+  test('noop checkpoints identity only when both sides carry the same bytes', async () => {
+    const same = spyOps();
+    await applyColdStart({
+      slug: 's',
+      decision: { action: 'noop', reason: 'identical' },
+      localBody: 'SAME',
+      docBody: 'SAME',
+      log: silent,
+      ...same,
+    });
+    expect(same.calls).toEqual(['checkpoint:SAME']);
+
+    const bothEmpty = spyOps();
+    await applyColdStart({
+      slug: 's',
+      decision: { action: 'noop', reason: 'both empty' },
+      localBody: null,
+      docBody: '',
+      log: silent,
+      ...bothEmpty,
+    });
+    expect(bothEmpty.calls).toEqual([]);
+  });
+});
+
+describe('cold-start-apply — DDR-102 fail-closed, in one place', () => {
+  test('hub wins normally when the snapshot lands', async () => {
+    const ops = spyOps();
+    const result = await applyColdStart({
+      slug: 's',
+      decision: { action: 'conflict', winner: 'hub', reason: 'diverged' },
+      localBody: 'LOCAL',
+      docBody: 'HUB',
+      snapshot: async () => 'ts-1',
+      log: silent,
+      ...ops,
+    });
+    expect(result.bodyWinner).toBe('hub');
+    expect(result.conflict?.snapshotFailed).toBe(false);
+    expect(ops.calls).toEqual(['takeHub']);
+  });
+
+  test('a hub-wins verdict is REFUSED when the local snapshot did not land', async () => {
+    const ops = spyOps();
+    const errors: string[] = [];
+    const result = await applyColdStart({
+      slug: 's',
+      decision: { action: 'conflict', winner: 'hub', reason: 'diverged' },
+      localBody: 'LOCAL',
+      docBody: 'HUB',
+      snapshot: async () => null, // both snapshots fail
+      log: { warn: () => {}, error: (m) => errors.push(m) },
+      ...ops,
+    });
+    expect(result.bodyWinner).toBe('local');
+    expect(result.conflict?.snapshotFailed).toBe(true);
+    expect(ops.calls).toEqual(['takeLocal:LOCAL']);
+    expect(errors.join(' ')).toContain('REFUSING to overwrite local');
+  });
+
+  test('no snapshot fn at all ⇒ plain newest-wins (standalone wiring)', async () => {
+    const ops = spyOps();
+    const result = await applyColdStart({
+      slug: 's',
+      decision: { action: 'conflict', winner: 'hub', reason: 'diverged' },
+      localBody: 'LOCAL',
+      docBody: 'HUB',
+      log: silent,
+      ...ops,
+    });
+    expect(result.bodyWinner).toBe('hub');
+    expect(result.conflict?.snapshotFailed).toBe(false);
+  });
+
+  test('the conflict report carries the POST-guard winner', async () => {
+    const seen: Array<{ winner?: string; snapshotFailed?: boolean }> = [];
+    await applyColdStart({
+      slug: 's',
+      decision: { action: 'conflict', winner: 'hub', reason: 'diverged' },
+      localBody: 'LOCAL',
+      docBody: 'HUB',
+      snapshot: async () => null,
+      onConflict: (info) => seen.push(info),
+      log: silent,
+      ...spyOps(),
+    });
+    expect(seen).toHaveLength(1);
+    expect(seen[0]?.winner).toBe('local');
+    expect(seen[0]?.snapshotFailed).toBe(true);
+  });
+});
+
+/* ---------------------------------------------------------------------- */
+
+describe('migrate-seed — the recover-seed-dup fallthrough (LIVE regression)', () => {
+  let dir: string;
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'cold-start-apply-'));
+  });
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  const paths = () => ({
+    html: join(dir, 'screen.html'),
+    comments: join(dir, 'screen.comments.json'),
+    annotations: join(dir, 'screen.annotations.svg'),
+    meta: join(dir, 'screen.meta.json'),
+    css: join(dir, 'screen.css'),
+  });
+
+  test('a doubled hub body is COLLAPSED to one copy, not kept', async () => {
+    const p = paths();
+    const body = '<main>one copy</main>';
+    writeFileSync(p.html, body);
+
+    // The shape of a concurrent cold-seed collision: two peers each seeded the
+    // same body into an empty hub and the CRDT concatenated both insertions.
+    const doc = new Y.Doc();
+    applyHtmlToDoc(doc, body + body, ORIGINS.MIGRATION);
+
+    // Sanity: the table really does emit `recover-seed-dup` for this input.
+    expect(
+      decideColdStart({
+        localBody: body,
+        docBody: body + body,
+        journalHash: null,
+        localMtimeMs: null,
+        docBodyEditAtMs: null,
+      }).action
+    ).toBe('recover-seed-dup');
+
+    const result = await migrateSeed({ slug: 's', doc, paths: p });
+
+    // Before Increment 0 this returned 'hub-wins' and the doc kept `body+body`.
+    expect(result).toBe('recover-seed-dup');
+    expect(doc.getText('html').toString()).toBe(body);
+  });
+
+  test('a THREE-fold repeat collapses too, and re-running is a no-op', async () => {
+    const p = paths();
+    const body = '<main>x</main>';
+    writeFileSync(p.html, body);
+
+    const doc = new Y.Doc();
+    applyHtmlToDoc(doc, body.repeat(3), ORIGINS.MIGRATION);
+
+    expect(await migrateSeed({ slug: 's', doc, paths: p })).toBe('recover-seed-dup');
+    expect(doc.getText('html').toString()).toBe(body);
+
+    // Idempotent: the second pass sees identical sides.
+    expect(await migrateSeed({ slug: 's', doc, paths: p })).toBe('hub-wins');
+    expect(doc.getText('html').toString()).toBe(body);
+  });
+});

package/apps/studio/test/collab-stress.test.ts

@@ -116,6 +116,14 @@ describe('multi-tab stress (Phase 8 Task 8)', () => {
       room.disconnect(B);
       expect(room.size()).toBe(0);
     },
-    STRESS_MS + 5_000
+    // Headroom must scale WITH the stress window, not sit a flat few seconds
+    // above it. The body burns `STRESS_MS` of wall clock by construction
+    // (`while (Date.now() - start < STRESS_MS)`), so on a loaded machine the
+    // setup/teardown and the ~33 ms tick drift are the only slack — a flat
+    // +5 s put the budget at 15 s against a measured 10.1 s run, and this was
+    // the one test that tipped over in a full-suite run under load. Nothing
+    // here asserts speed (the checks are RSS + Y.Doc growth), so a wide budget
+    // costs no signal: a real hang still dies, just later.
+    STRESS_MS * 2 + 10_000
   );
 });

package/apps/studio/test/export-lane.test.ts

@@ -0,0 +1,245 @@
+// feature-cloud-export-render-workers (DDR-230) — the render-lane dispatch.
+//
+// The queue's contract must hold in all three lanes:
+//   local  — pre-render-workers behavior, byte-identical (covered by
+//            test/exporters/jobs.test.ts; not re-proven here).
+//   none   — browser formats refuse BEFORE taking a render slot, with the
+//            remedy message; zip still runs in-cell.
+//   remote — browser formats POST the fully-resolved job to the render
+//            service with the member's canvas grant, and the artifact comes
+//            back as a normal job result.
+
+import { afterEach, describe, expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { createBus } from '../context.ts';
+import type { ExportContext } from '../exporters/index.ts';
+import { createExportJobQueue, type EnqueueArgs } from '../exporters/jobs.ts';
+import { NO_RENDER_SERVICE_MESSAGE, REMOTE_UNSUPPORTED_MESSAGE } from '../exporters/remote.ts';
+import { resolveRenderLane } from '../workspace-mode.ts';
+
+const SAVED = {
+  mode: process.env.MAUDE_WORKSPACE_MODE,
+  url: process.env.MAUDE_RENDER_URL,
+  secret: process.env.MAUDE_RENDER_SECRET,
+};
+
+function setLane(lane: 'local' | 'remote' | 'none', url?: string): void {
+  if (lane === 'local') {
+    delete process.env.MAUDE_WORKSPACE_MODE;
+    delete process.env.MAUDE_RENDER_URL;
+  } else {
+    process.env.MAUDE_WORKSPACE_MODE = '1';
+    if (lane === 'remote') process.env.MAUDE_RENDER_URL = url ?? 'http://127.0.0.1:1';
+    else delete process.env.MAUDE_RENDER_URL;
+  }
+}
+
+afterEach(() => {
+  if (SAVED.mode === undefined) delete process.env.MAUDE_WORKSPACE_MODE;
+  else process.env.MAUDE_WORKSPACE_MODE = SAVED.mode;
+  if (SAVED.url === undefined) delete process.env.MAUDE_RENDER_URL;
+  else process.env.MAUDE_RENDER_URL = SAVED.url;
+  if (SAVED.secret === undefined) delete process.env.MAUDE_RENDER_SECRET;
+  else process.env.MAUDE_RENDER_SECRET = SAVED.secret;
+});
+
+function sandboxDesignRoot(): string {
+  const root = mkdtempSync(join(tmpdir(), 'maude-lane-'));
+  const design = join(root, '.design');
+  mkdirSync(join(design, 'ui'), { recursive: true });
+  writeFileSync(join(design, 'ui', 'Home.tsx'), 'export default function Home(){return null}\n');
+  return design;
+}
+
+function baseArgs(
+  designRoot: string,
+  format: EnqueueArgs['format'],
+  scope: EnqueueArgs['scope']
+): EnqueueArgs {
+  const repoRoot = join(designRoot, '..');
+  const ctx: ExportContext = {
+    designRoot,
+    repoRoot,
+    serverOrigin: 'http://127.0.0.1:1', // never reached in these tests
+  };
+  return {
+    format,
+    scope,
+    options: {},
+    resolve: {
+      activeJson: { active: '.design/ui/Home.tsx', selected: null },
+      designRoot,
+      repoRoot,
+    },
+    ctx,
+    remoteCanvas: { origin: 'https://tenant.example', token: 'tok-abc' },
+  };
+}
+
+describe('resolveRenderLane', () => {
+  test('local off-workspace; remote/none track MAUDE_RENDER_URL in a workspace', () => {
+    setLane('local');
+    expect(resolveRenderLane()).toBe('local');
+    setLane('none');
+    expect(resolveRenderLane()).toBe('none');
+    setLane('remote', 'http://127.0.0.1:9');
+    expect(resolveRenderLane()).toBe('remote');
+    // A laptop with MAUDE_RENDER_URL exported by accident stays local — the
+    // lane never dispatches outside workspace mode.
+    delete process.env.MAUDE_WORKSPACE_MODE;
+    expect(resolveRenderLane()).toBe('local');
+  });
+});
+
+describe('lane none', () => {
+  test('a browser format fails fast with the remedy, without taking a slot', async () => {
+    setLane('none');
+    const design = sandboxDesignRoot();
+    const queue = createExportJobQueue(createBus(), design);
+    const { id, result } = queue.enqueue(baseArgs(design, 'png', 'artboard'));
+    await expect(result).rejects.toThrow(NO_RENDER_SERVICE_MESSAGE);
+    const job = queue.get(id);
+    expect(job?.status).toBe('failed');
+    expect(job?.error).toBe(NO_RENDER_SERVICE_MESSAGE);
+  });
+
+  test('zip still exports in-cell — browser-free formats ignore the lane', async () => {
+    setLane('none');
+    const design = sandboxDesignRoot();
+    const queue = createExportJobQueue(createBus(), design);
+    const { result } = queue.enqueue(baseArgs(design, 'zip', 'project-raw'));
+    const res = await result;
+    expect(res.contentType).toBe('application/zip');
+    expect(res.body.byteLength).toBeGreaterThan(0);
+  });
+});
+
+describe('lane remote', () => {
+  test('canva refuses with the desktop remedy even when a service is configured', async () => {
+    setLane('remote', 'http://127.0.0.1:9');
+    const design = sandboxDesignRoot();
+    const queue = createExportJobQueue(createBus(), design);
+    const { id, result } = queue.enqueue(baseArgs(design, 'canva', 'canvas-as-separate'));
+    await expect(result).rejects.toThrow(REMOTE_UNSUPPORTED_MESSAGE);
+    expect(queue.get(id)?.status).toBe('failed');
+  });
+
+  test('a browser format POSTs the resolved job and the artifact comes back', async () => {
+    const seen: { auth?: string | null; body?: Record<string, unknown> } = {};
+    const service = Bun.serve({
+      port: 0,
+      fetch: async (req) => {
+        seen.auth = req.headers.get('authorization');
+        seen.body = (await req.json()) as Record<string, unknown>;
+        return new Response(new Uint8Array([137, 80, 78, 71]), {
+          headers: {
+            'content-type': 'image/png',
+            'x-maude-filename': 'home.png',
+            'x-maude-degraded': JSON.stringify({ kind: 'test-degrade' }),
+          },
+        });
+      },
+    });
+    try {
+      setLane('remote', `http://127.0.0.1:${service.port}`);
+      process.env.MAUDE_RENDER_SECRET = 'shh';
+      const design = sandboxDesignRoot();
+      const queue = createExportJobQueue(createBus(), design);
+      const { id, result } = queue.enqueue(baseArgs(design, 'png', 'artboard'));
+      const res = await result;
+
+      expect(res.filename).toBe('home.png');
+      expect(res.contentType).toBe('image/png');
+      expect(res.body).toEqual(new Uint8Array([137, 80, 78, 71]));
+      expect(res.degraded).toEqual({ kind: 'test-degrade' } as never);
+
+      // The wire contract: bearer ingress, resolved targets (pure data), the
+      // member's canvas grant — and nothing else (no fs paths leak).
+      expect(seen.auth).toBe('Bearer shh');
+      expect(seen.body?.format).toBe('png');
+      const targets = seen.body?.targets as Array<Record<string, unknown>>;
+      expect(targets).toHaveLength(1);
+      expect(targets[0]?.kind).toBe('element');
+      expect(targets[0]?.file).toBe('.design/ui/Home.tsx');
+      expect(seen.body?.canvas).toEqual({ origin: 'https://tenant.example', token: 'tok-abc' });
+
+      // Job lifecycle + bytes-on-disk contract holds on the remote lane too.
+      const job = queue.get(id);
+      expect(job?.status).toBe('done');
+      expect(job?.degraded).toEqual({ kind: 'test-degrade' } as never);
+      const dl = await queue.getBytes(id);
+      expect(dl.ok).toBe(true);
+    } finally {
+      service.stop(true);
+    }
+  });
+
+  test('a hostile filename header cannot escape the job directory (path traversal)', async () => {
+    // security-review defender: x-maude-filename lands in Bun.write(join(dir, name)).
+    const service = Bun.serve({
+      port: 0,
+      fetch: () =>
+        new Response(new Uint8Array([1, 2, 3]), {
+          headers: {
+            'content-type': 'image/png',
+            // Traversal AND a header-injection attempt in one — both must die.
+            'x-maude-filename': '../../../../etc/pw"ned.png',
+          },
+        }),
+    });
+    try {
+      setLane('remote', `http://127.0.0.1:${service.port}`);
+      const design = sandboxDesignRoot();
+      const queue = createExportJobQueue(createBus(), design);
+      const { result } = queue.enqueue(baseArgs(design, 'png', 'artboard'));
+      const res = await result;
+      // basename() drops the whole directory prefix — no separators, no `..`.
+      expect(res.filename).toBe('pwned.png');
+      expect(res.filename).not.toContain('/');
+      expect(res.filename).not.toContain('..');
+    } finally {
+      service.stop(true);
+    }
+  });
+
+  test('an oversized artifact is refused rather than buffered whole (OOM cap)', async () => {
+    // A body over the cap (the cap floors at 1 MB, so the body must clear it).
+    const service = Bun.serve({
+      port: 0,
+      fetch: () =>
+        new Response(new Uint8Array(1_100_000), { headers: { 'content-type': 'image/png' } }),
+    });
+    try {
+      setLane('remote', `http://127.0.0.1:${service.port}`);
+      process.env.MAUDE_RENDER_MAX_ARTIFACT_BYTES = '1000000';
+      const design = sandboxDesignRoot();
+      const queue = createExportJobQueue(createBus(), design);
+      const { id, result } = queue.enqueue(baseArgs(design, 'png', 'artboard'));
+      await expect(result).rejects.toThrow(/too large|exceeded/);
+      expect(queue.get(id)?.status).toBe('failed');
+    } finally {
+      service.stop(true);
+      delete process.env.MAUDE_RENDER_MAX_ARTIFACT_BYTES;
+    }
+  });
+
+  test('a refusing service surfaces its reason as the job error', async () => {
+    const service = Bun.serve({
+      port: 0,
+      fetch: () => new Response('bad token', { status: 403 }),
+    });
+    try {
+      setLane('remote', `http://127.0.0.1:${service.port}`);
+      const design = sandboxDesignRoot();
+      const queue = createExportJobQueue(createBus(), design);
+      const { id, result } = queue.enqueue(baseArgs(design, 'pdf', 'artboard'));
+      await expect(result).rejects.toThrow(/render service refused the job: bad token/);
+      expect(queue.get(id)?.status).toBe('failed');
+    } finally {
+      service.stop(true);
+    }
+  });
+});

package/apps/studio/test/fixtures/video-comp-fixture.tsx

@@ -66,7 +66,7 @@ function Fixture() {
 export default function Canvas() {
   return (
     <DesignCanvas>
-      <DCSection title="Video-comp fixture">
+      <DCSection id="video-comp-fixture" title="Video-comp fixture">
         <DCArtboard id="fixture" label="Fixture" width={640} height={360}>
           <VideoComp
             component={Fixture}

package/apps/studio/test/git-log-format.test.ts

@@ -0,0 +1,95 @@
+// One log shape, three producers — feature-cloud-managed-git-posture.
+//
+// A History row is drawn by ONE renderer (`GitPanel`), and it can now be fed by
+// three different readers: system-git (`logSystem`), isomorphic-git (`logIso`)
+// and the cloud cell (`apps/hub/src/history.mjs`). The first and the third are
+// the same code — that is what `git/log-format.ts` is for. The second is a
+// separate implementation against a separate library, and it is the one that
+// can quietly drift.
+//
+// The failure mode is specific and quiet: a reader that stops emitting `date`
+// (or emits `authorName` instead of `author`) does not throw anywhere. It draws
+// a row with a blank field, on whichever of the two engines the reader happens
+// to be on — so it is invisible on the machine of whoever made the change.
+
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { GIT_LOG_FORMAT, gitLogArgs, gitLogEnv, parseGitLog } from '../git/log-format.ts';
+
+const SERVICE = readFileSync(join(import.meta.dir, '..', 'git', 'service.ts'), 'utf8');
+
+/** The contract `GitLogEntry` declares and `GitPanel` reads. */
+const FIELDS = ['sha', 'message', 'author', 'email', 'date'] as const;
+
+describe('parseGitLog', () => {
+  test('produces exactly the declared fields', () => {
+    const rec = `abc123\x1fa message\x1fAda\x1fada@example.com\x1f2026-08-18T10:00:00+02:00\x1e`;
+    const [entry] = parseGitLog(rec);
+    expect(Object.keys(entry).sort()).toEqual([...FIELDS].sort());
+  });
+
+  test('survives every separator a commit subject can carry', () => {
+    const msg = 'fix: tabs\tquotes " and a | pipe, plus a comma';
+    const [entry] = parseGitLog(`sha\x1f${msg}\x1fAda\x1fa@b.c\x1f2026-08-18T10:00:00Z\x1e`);
+    expect(entry.message).toBe(msg);
+  });
+
+  test('a short record still yields strings, never undefined', () => {
+    // A renderer must never have to defend against a half-parsed row.
+    const [entry] = parseGitLog('justasha\x1fonly a message\x1e');
+    for (const f of FIELDS) expect(typeof entry[f]).toBe('string');
+  });
+
+  test('garbage is an empty list, never a throw', () => {
+    expect(parseGitLog('')).toEqual([]);
+    expect(parseGitLog('\x1e\x1e  \x1e')).toEqual([]);
+    // biome-ignore lint/suspicious/noExplicitAny: deliberately hostile input
+    expect(parseGitLog(null as any)).toEqual([]);
+  });
+});
+
+describe('gitLogArgs / gitLogEnv travel together', () => {
+  test('the format string is the one the parser splits on', () => {
+    expect(GIT_LOG_FORMAT).toContain('%x1f');
+    expect(GIT_LOG_FORMAT).toContain('%x1e');
+    expect(gitLogArgs(30)).toEqual(['log', '-n30', `--pretty=format:${GIT_LOG_FORMAT}`]);
+  });
+
+  test('a scoped log terminates its pathspec AND asks for literal pathspecs', () => {
+    // The `--` terminator alone does not close pathspec magic (`:(exclude)…`);
+    // GIT_LITERAL_PATHSPECS does, and the two must never be separated.
+    const args = gitLogArgs(10, '.design/ui/Card.tsx');
+    expect(args[args.length - 2]).toBe('--');
+    expect(args[args.length - 1]).toBe('.design/ui/Card.tsx');
+    expect(gitLogEnv('.design/ui/Card.tsx')).toEqual({ GIT_LITERAL_PATHSPECS: '1' });
+  });
+
+  test('an unscoped log asks for neither', () => {
+    expect(gitLogArgs(10)).not.toContain('--');
+    expect(gitLogEnv(undefined)).toBeUndefined();
+  });
+});
+
+describe('the isomorphic-git engine has not drifted from the shared shape', () => {
+  test('logSystem reads through the shared module rather than re-typing it', () => {
+    expect(SERVICE).toContain('gitLogArgs(limit, filepath), gitLogEnv(filepath)');
+    expect(SERVICE).toContain('return parseGitLog(r.stdout);');
+    // The old literal must be GONE, not merely unused — a leftover copy is the
+    // thing a later edit picks up.
+    expect(SERVICE).not.toContain("const fmt = '%H%x1f");
+  });
+
+  test('logIso still emits exactly the same five fields', () => {
+    // Source-level, because `logIso` is a private fallback with no seam to call
+    // it through: forcing the engine would mean exporting it, which invents an
+    // API for the test to check. The literal it returns IS the contract.
+    const body = SERVICE.slice(SERVICE.indexOf('async function logIso('));
+    const literal = body.slice(body.indexOf('return {'), body.indexOf('};') + 2);
+    for (const f of FIELDS) expect(literal).toContain(`${f}:`);
+    // …and nothing else, so a sixth field can't appear on one engine only.
+    const keys = [...literal.matchAll(/^\s{8}([a-zA-Z]+):/gm)].map((m) => m[1]);
+    expect(keys.sort()).toEqual([...FIELDS].sort());
+  });
+});