Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
import { execFileSync } from 'node:child_process';
import { existsSync, mkdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
import { mkdtemp, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { resolve } from 'node:path';
import { setTimeout as wait } from 'node:timers/promises';
import { atomicTempPath } from '@inkeep/open-knowledge-core/server';
import {
CHECKPOINT_KIND_REGISTRY,
CHECKPOINT_KINDS,
CHECKPOINT_SAMPLE_BY_KIND,
type CheckpointKind,
formatCheckpointBodyLine,
parseCheckpoint,
parseOkActor,
} from '@inkeep/open-knowledge-core/shadow-repo-layout';
import simpleGit from 'simple-git';
import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
import { configureTestGitRepository } from '../../../test-support/configure-git-fixture.test-helper.ts';
import { applySkillWrite } from './content/skills-write.ts';
import { getLogger } from './logger.ts';
import { getMetrics, resetMetrics } from './metrics.ts';
import {
buildWipTree,
commitUpstreamImport,
commitWip,
DEFAULT_CHECKPOINT_RETENTION,
FANOUT_INDEX_NAME,
GIT_UPSTREAM_WRITER,
gitDirExcludePatterns,
type InMemoryCheckpointParams,
initShadowRepo,
isShadowExcludesDegraded,
listRescueCheckpoints,
type ParkableDoc,
parkBranch,
readParkedState,
resetFoldedWipRefs,
SERVICE_WRITER,
type ShadowHandle,
safetyCheckpoint,
saveInMemoryCheckpoint,
saveVersion,
shadowGit,
sweepLegacyShadowRefs,
type WriterIdentity,
} from './shadow-repo';
const fsTracedRecorder = vi.hoisted(() => ({ renameSources: [] as string[] }));
vi.mock('./fs-traced.ts', async (importOriginal) => {
const actual = await importOriginal<typeof import('./fs-traced.ts')>();
return {
...actual,
tracedRenameSync: (from: string, to: string): void => {
fsTracedRecorder.renameSources.push(from);
actual.tracedRenameSync(from, to);
},
};
});
let tmpDir: string;
beforeEach(async () => {
tmpDir = await mkdtemp(resolve(tmpdir(), 'ok-shadow-test-'));
});
afterEach(async () => {
await rm(tmpDir, { recursive: true, force: true });
});
describe('initShadowRepo', () => {
test('creates shadow at .git/ok/ when project .git/ exists', async () => {
const projectRoot = resolve(tmpDir, 'project');
mkdirSync(projectRoot, { recursive: true });
const git = simpleGit(projectRoot);
await git.init();
configureTestGitRepository(projectRoot);
await git.raw('config', 'user.name', 'Test');
await git.raw('config', 'user.email', '[email protected]');
const shadow = await initShadowRepo(projectRoot);
expect(shadow.gitDir).toBe(resolve(projectRoot, '.git/ok'));
expect(shadow.workTree).toBe(projectRoot);
expect(existsSync(resolve(shadow.gitDir, 'HEAD'))).toBe(true);
const sg = simpleGit().env({ GIT_DIR: shadow.gitDir });
const worktree = (await sg.raw('config', 'core.worktree')).trim();
expect(worktree).toBe(projectRoot);
const userName = (await sg.raw('config', 'user.name')).trim();
expect(userName).toBe('openknowledge');
});
test('does not modify .gitignore (shadow is inside .git/ already)', async () => {
const projectRoot = resolve(tmpDir, 'project');
mkdirSync(projectRoot, { recursive: true });
const git = simpleGit(projectRoot);
await git.init();
configureTestGitRepository(projectRoot);
await git.raw('config', 'user.name', 'Test');
await git.raw('config', 'user.email', '[email protected]');
const gitignorePath = resolve(projectRoot, '.gitignore');
await initShadowRepo(projectRoot);
expect(existsSync(gitignorePath)).toBe(false);
const gitignore = 'node_modules/\n.env\n';
writeFileSync(gitignorePath, gitignore);
await initShadowRepo(projectRoot);
expect(readFileSync(gitignorePath, 'utf-8')).toBe(gitignore);
});
test('is idempotent — second call does not error', async () => {
const projectRoot = resolve(tmpDir, 'project');
mkdirSync(projectRoot, { recursive: true });
const git = simpleGit(projectRoot);
await git.init();
configureTestGitRepository(projectRoot);
await git.raw('config', 'user.name', 'Test');
await git.raw('config', 'user.email', '[email protected]');
const shadow1 = await initShadowRepo(projectRoot);
const shadow2 = await initShadowRepo(projectRoot);
expect(shadow1.gitDir).toBe(shadow2.gitDir);
expect(existsSync(resolve(shadow2.gitDir, 'HEAD'))).toBe(true);
});
test('sub-projects whose names differ only in non-Latin letters get separate shadow repos', async () => {
const repo = resolve(tmpDir, 'repo');
mkdirSync(repo, { recursive: true });
await simpleGit(repo).init();
configureTestGitRepository(repo);
const projectA = resolve(repo, 'ノート');
const projectB = resolve(repo, '日記帳');
mkdirSync(projectA, { recursive: true });
mkdirSync(projectB, { recursive: true });
const shadowA = await initShadowRepo(projectA);
const shadowB = await initShadowRepo(projectB);
expect(shadowA.gitDir).not.toBe(shadowB.gitDir);
for (const [shadow, project] of [
[shadowA, projectA],
[shadowB, projectB],
] as const) {
const sg = simpleGit().env({ GIT_DIR: shadow.gitDir });
expect((await sg.raw('config', 'core.worktree')).trim()).toBe(project);
}
expect((await initShadowRepo(projectA)).gitDir).toBe(shadowA.gitDir);
});
test("an earlier version's lossy shadow repo stays with its owner after upgrade", async () => {
const repo = resolve(tmpDir, 'repo');
mkdirSync(repo, { recursive: true });
await simpleGit(repo).init();
configureTestGitRepository(repo);
const owner = resolve(repo, 'ノート');
const other = resolve(repo, '日記帳');
mkdirSync(owner, { recursive: true });
mkdirSync(other, { recursive: true });
const legacyDir = resolve(repo, '.git', 'ok-___');
execFileSync('git', ['init', '--bare', '--quiet', legacyDir]);
execFileSync('git', ['config', 'core.worktree', owner], {
env: { ...process.env, GIT_DIR: legacyDir },
});
expect((await initShadowRepo(owner)).gitDir).toBe(legacyDir);
expect((await initShadowRepo(other)).gitDir).not.toBe(legacyDir);
});
test('R9 rename shim: legacy .git/openknowledge/ is renamed to .git/ok/', async () => {
const projectRoot = resolve(tmpDir, 'legacy');
mkdirSync(projectRoot, { recursive: true });
const git = simpleGit(projectRoot);
await git.init();
configureTestGitRepository(projectRoot);
await git.raw('config', 'user.name', 'Test');
await git.raw('config', 'user.email', '[email protected]');
const legacyDir = resolve(projectRoot, '.git/openknowledge');
mkdirSync(legacyDir, { recursive: true });
await git.raw('init', '--bare', legacyDir);
configureTestGitRepository(legacyDir);
const sg = simpleGit({ timeout: { block: 30_000 } }).env({ GIT_DIR: legacyDir });
await sg.raw('config', '--unset', 'core.bare');
await sg.raw('config', 'core.worktree', projectRoot);
writeFileSync(resolve(legacyDir, 'SENTINEL'), 'migrated');
const shadow = await initShadowRepo(projectRoot);
expect(shadow.gitDir).toBe(resolve(projectRoot, '.git/ok'));
expect(existsSync(legacyDir)).toBe(false);
expect(existsSync(resolve(projectRoot, '.git/ok/SENTINEL'))).toBe(true);
expect(existsSync(resolve(projectRoot, '.git/ok/HEAD'))).toBe(true);
});
test('R9 defensive: both legacy and new shadow present — no rename, warning logged', async () => {
const projectRoot = resolve(tmpDir, 'both-present');
mkdirSync(projectRoot, { recursive: true });
const git = simpleGit(projectRoot);
await git.init();
configureTestGitRepository(projectRoot);
await git.raw('config', 'user.name', 'Test');
await git.raw('config', 'user.email', '[email protected]');
const legacyDir = resolve(projectRoot, '.git/openknowledge');
const newDir = resolve(projectRoot, '.git/ok');
mkdirSync(legacyDir, { recursive: true });
mkdirSync(newDir, { recursive: true });
writeFileSync(resolve(legacyDir, 'LEGACY_SENTINEL'), 'legacy');
writeFileSync(resolve(newDir, 'NEW_SENTINEL'), 'new');
const warnSpy = vi.spyOn(getLogger('shadow-repo'), 'warn');
try {
await initShadowRepo(projectRoot);
expect(existsSync(resolve(legacyDir, 'LEGACY_SENTINEL'))).toBe(true);
expect(existsSync(resolve(newDir, 'NEW_SENTINEL'))).toBe(true);
const warnings = warnSpy.mock.calls.map((call) => String(call[1] ?? ''));
expect(warnings.some((w) => w.includes('[shadow-repo] unexpected legacy + new shadow'))).toBe(
true,
);
} finally {
warnSpy.mockRestore();
}
});
});
describe('buildWipTree contentRoot pathspec', () => {
test("'.' pathspec succeeds when content lives at the project root", async () => {
const projectRoot = resolve(tmpDir, 'project');
mkdirSync(projectRoot, { recursive: true });
writeFileSync(resolve(projectRoot, 'AGENTS.md'), '# hello\n');
const shadow = await initShadowRepo(projectRoot);
const sha = await buildWipTree(shadow, '.');
expect(sha).toMatch(/^[0-9a-f]{40}$/);
});
test("literal 'content' pathspec fails when no such subfolder exists", async () => {
const projectRoot = resolve(tmpDir, 'project');
mkdirSync(projectRoot, { recursive: true });
writeFileSync(resolve(projectRoot, 'AGENTS.md'), '# hello\n');
const shadow = await initShadowRepo(projectRoot);
await expect(buildWipTree(shadow, 'content')).rejects.toThrow(/pathspec ':\(literal\)content'/);
});
test('a ":"-prefixed contentRoot scopes to that subtree instead of over-matching', async () => {
const projectRoot = resolve(tmpDir, 'project');
mkdirSync(resolve(projectRoot, ':vault'), { recursive: true });
writeFileSync(resolve(projectRoot, ':vault', 'a.md'), '# a\n');
writeFileSync(resolve(projectRoot, 'sibling.md'), '# sibling\n');
const shadow = await initShadowRepo(projectRoot);
const sha = await buildWipTree(shadow, ':vault');
const listed = await simpleGit(projectRoot)
.env({ GIT_DIR: shadow.gitDir, GIT_WORK_TREE: projectRoot })
.raw(['ls-tree', '-r', '--name-only', sha]);
const entries = listed.trim().split('\n').filter(Boolean);
expect(entries).toContain(':vault/a.md');
expect(entries).not.toContain('sibling.md');
});
test('a wildcard-bearing contentRoot selects only its own subtree', async () => {
const projectRoot = resolve(tmpDir, 'project');
mkdirSync(resolve(projectRoot, 'star*'), { recursive: true });
mkdirSync(resolve(projectRoot, 'starfish'), { recursive: true });
writeFileSync(resolve(projectRoot, 'star*', 'a.md'), '# a\n');
writeFileSync(resolve(projectRoot, 'starfish', 'b.md'), '# b\n');
const shadow = await initShadowRepo(projectRoot);
const sha = await buildWipTree(shadow, 'star*');
const listed = await simpleGit(projectRoot)
.env({ GIT_DIR: shadow.gitDir, GIT_WORK_TREE: projectRoot })
.raw(['ls-tree', '-r', '--name-only', sha]);
const entries = listed.trim().split('\n').filter(Boolean);
expect(entries).toContain('star*/a.md');
expect(entries).not.toContain('starfish/b.md');
});
});
describe('buildWipTree persistent fan-out index', () => {
let projectRoot: string;
let shadow: ShadowHandle;
let contentDir: string;
beforeEach(async () => {
projectRoot = resolve(tmpDir, 'project');
contentDir = resolve(projectRoot, 'content');
mkdirSync(contentDir, { recursive: true });
const git = simpleGit(projectRoot);
await git.init();
configureTestGitRepository(projectRoot);
shadow = await initShadowRepo(projectRoot);
});
test('reused index tracks modify, add, and delete across successive builds', async () => {
writeFileSync(resolve(contentDir, 'a.md'), '# A v1\n');
writeFileSync(resolve(contentDir, 'b.md'), '# B v1\n');
const tree1 = await buildWipTree(shadow, 'content');
expect(existsSync(resolve(shadow.gitDir, 'index-wip-fanout'))).toBe(true);
writeFileSync(resolve(contentDir, 'a.md'), '# A v2\n');
rmSync(resolve(contentDir, 'b.md'));
writeFileSync(resolve(contentDir, 'c.md'), '# C v1\n');
const tree2 = await buildWipTree(shadow, 'content');
expect(tree2).not.toBe(tree1);
const sg = shadowGit(shadow);
const listing = await sg.raw('ls-tree', '-r', '--name-only', tree2);
const paths = listing.trim().split('\n').sort();
expect(paths).toEqual(['content/a.md', 'content/c.md']);
expect((await sg.raw('cat-file', '-p', `${tree2}:content/a.md`)).trim()).toBe('# A v2');
});
test('reused index produces the same tree a fresh index would', async () => {
writeFileSync(resolve(contentDir, 'a.md'), '# A v1\n');
await buildWipTree(shadow, 'content');
writeFileSync(resolve(contentDir, 'a.md'), '# A v2\n');
const warmTree = await buildWipTree(shadow, 'content');
rmSync(resolve(shadow.gitDir, 'index-wip-fanout'));
const freshTree = await buildWipTree(shadow, 'content');
expect(warmTree).toBe(freshTree);
});
test('corrupt persistent index falls back to a fresh rebuild', async () => {
writeFileSync(resolve(contentDir, 'a.md'), '# A v1\n');
const tree1 = await buildWipTree(shadow, 'content');
writeFileSync(resolve(shadow.gitDir, 'index-wip-fanout'), 'not a git index');
const warnSpy = vi.spyOn(getLogger('shadow-repo'), 'warn');
try {
const tree2 = await buildWipTree(shadow, 'content');
expect(tree2).toBe(tree1);
const warnings = warnSpy.mock.calls.map((call) => String(call[1] ?? ''));
expect(warnings.some((w) => w.includes('persistent fan-out index failed'))).toBe(true);
} finally {
warnSpy.mockRestore();
}
expect(existsSync(resolve(shadow.gitDir, 'index-wip-fanout'))).toBe(false);
});
test('stale index.lock from a killed add falls back and is cleared', async () => {
writeFileSync(resolve(contentDir, 'a.md'), '# A v1\n');
const tree1 = await buildWipTree(shadow, 'content');
writeFileSync(resolve(shadow.gitDir, 'index-wip-fanout.lock'), '');
const warnSpy = vi.spyOn(getLogger('shadow-repo'), 'warn');
try {
const tree2 = await buildWipTree(shadow, 'content');
expect(tree2).toBe(tree1);
const warnings = warnSpy.mock.calls.map((call) => String(call[1] ?? ''));
expect(warnings.some((w) => w.includes('persistent fan-out index failed'))).toBe(true);
} finally {
warnSpy.mockRestore();
}
expect(existsSync(resolve(shadow.gitDir, 'index-wip-fanout.lock'))).toBe(false);
});
test('boot sweep removes throwaway indices, stale lock, and orphaned park blob dirs but keeps the cache', async () => {
writeFileSync(resolve(shadow.gitDir, 'index-wip-fanout-deadbeef'), '');
writeFileSync(resolve(shadow.gitDir, 'index-wip-fanout.lock'), '');
writeFileSync(resolve(shadow.gitDir, 'index-wip-fanout'), '');
const orphanParkDir = resolve(shadow.gitDir, 'tmp-park-blobs-deadbeef');
mkdirSync(orphanParkDir, { recursive: true });
writeFileSync(resolve(orphanParkDir, '0-state'), '# orphaned park blob\n');
const reinit = await initShadowRepo(projectRoot);
expect(existsSync(resolve(reinit.gitDir, 'index-wip-fanout-deadbeef'))).toBe(false);
expect(existsSync(resolve(reinit.gitDir, 'index-wip-fanout.lock'))).toBe(false);
expect(existsSync(orphanParkDir)).toBe(false);
expect(existsSync(resolve(reinit.gitDir, 'index-wip-fanout'))).toBe(true);
});
});
describe('commitWip', () => {
let projectRoot: string;
let shadow: ShadowHandle;
let contentDir: string;
const writer: WriterIdentity = {
id: 'human-ada',
name: 'Ada Lovelace',
email: '[email protected]',
};
beforeEach(async () => {
projectRoot = resolve(tmpDir, 'project');
mkdirSync(projectRoot, { recursive: true });
contentDir = resolve(projectRoot, 'content/docs');
mkdirSync(contentDir, { recursive: true });
const git = simpleGit(projectRoot);
await git.init();
configureTestGitRepository(projectRoot);
await git.raw('config', 'user.name', 'Test');
await git.raw('config', 'user.email', '[email protected]');
shadow = await initShadowRepo(projectRoot);
});
test('creates commit on refs/wip/<branch>/<writer-id>', async () => {
writeFileSync(resolve(contentDir, 'intro.md'), '# Hello\n');
const sha = await commitWip(shadow, writer, 'content/docs', 'WIP: intro');
expect(sha).toHaveLength(40);
const sg = shadowGit(shadow);
const refSha = (await sg.raw('rev-parse', `refs/wip/main/${writer.id}`)).trim();
expect(refSha).toBe(sha);
const msg = (await sg.raw('log', '-1', '--format=%s', sha)).trim();
expect(msg).toBe('WIP: intro');
});
test('commit is authored by the writer', async () => {
writeFileSync(resolve(contentDir, 'intro.md'), '# Hello\n');
const sha = await commitWip(shadow, writer, 'content/docs', 'WIP: check author');
const sg = shadowGit(shadow);
const authorName = (await sg.raw('log', '-1', '--format=%an', sha)).trim();
const authorEmail = (await sg.raw('log', '-1', '--format=%ae', sha)).trim();
expect(authorName).toBe(writer.name);
expect(authorEmail).toBe(writer.email);
const committerName = (await sg.raw('log', '-1', '--format=%cn', sha)).trim();
expect(committerName).toBe('openknowledge');
});
test('second commit parents the first', async () => {
writeFileSync(resolve(contentDir, 'intro.md'), '# Hello\n');
const sha1 = await commitWip(shadow, writer, 'content/docs', 'WIP: first');
writeFileSync(resolve(contentDir, 'intro.md'), '# Hello World\n');
const sha2 = await commitWip(shadow, writer, 'content/docs', 'WIP: second');
expect(sha2).not.toBe(sha1);
const sg = shadowGit(shadow);
const parent = (await sg.raw('log', '-1', '--format=%P', sha2)).trim();
expect(parent).toBe(sha1);
});
test('CONCURRENT same-writer commits serialize: linear chain, no stale tree (P0 pin)', async () => {
writeFileSync(resolve(contentDir, 'a.md'), '# A\n');
const base = await commitWip(shadow, writer, 'content/docs', 'WIP: base');
writeFileSync(resolve(contentDir, 'b.md'), '# B\n');
writeFileSync(resolve(contentDir, 'c.md'), '# C\n');
const [s1, s2] = await Promise.all([
commitWip(shadow, writer, 'content/docs', 'WIP: concurrent 1'),
commitWip(shadow, writer, 'content/docs', 'WIP: concurrent 2'),
]);
const sg = shadowGit(shadow);
const p1 = (await sg.raw('log', '-1', '--format=%P', s1)).trim();
const p2 = (await sg.raw('log', '-1', '--format=%P', s2)).trim();
expect([p1, p2].sort()).toEqual([base, s1].sort());
const files = (await sg.raw('ls-tree', '-r', '--name-only', `refs/wip/main/${writer.id}`))
.trim()
.split('\n')
.sort();
expect(files).toEqual(['content/docs/a.md', 'content/docs/b.md', 'content/docs/c.md']);
});
test('different writers get independent refs', async () => {
const agent: WriterIdentity = {
id: 'agent-cursor',
name: 'cursor-agent',
email: '[email protected]',
};
writeFileSync(resolve(contentDir, 'intro.md'), '# Hello from human\n');
const humanSha = await commitWip(shadow, writer, 'content/docs', 'WIP: human edit');
writeFileSync(resolve(contentDir, 'guide.md'), '# Agent guide\n');
const agentSha = await commitWip(shadow, agent, 'content/docs', 'WIP: agent edit');
const sg = shadowGit(shadow);
const humanRef = (await sg.raw('rev-parse', 'refs/wip/main/human-ada')).trim();
const agentRef = (await sg.raw('rev-parse', 'refs/wip/main/agent-cursor')).trim();
expect(humanRef).toBe(humanSha);
expect(agentRef).toBe(agentSha);
});
test('branch-scoped WIP refs are isolated', async () => {
writeFileSync(resolve(contentDir, 'intro.md'), '# Main content\n');
const mainSha = await commitWip(shadow, writer, 'content/docs', 'WIP: main edit', 'main');
writeFileSync(resolve(contentDir, 'intro.md'), '# Feature content\n');
const featureSha = await commitWip(
shadow,
writer,
'content/docs',
'WIP: feature edit',
'feature/xyz',
);
const sg = shadowGit(shadow);
const mainRef = (await sg.raw('rev-parse', 'refs/wip/main/human-ada')).trim();
const featureRef = (await sg.raw('rev-parse', 'refs/wip/feature/xyz/human-ada')).trim();
expect(mainRef).toBe(mainSha);
expect(featureRef).toBe(featureSha);
expect(mainRef).not.toBe(featureRef);
});
});
describe('commitUpstreamImport', () => {
let projectRoot: string;
let shadow: ShadowHandle;
let contentDir: string;
beforeEach(async () => {
projectRoot = resolve(tmpDir, 'project');
mkdirSync(projectRoot, { recursive: true });
contentDir = resolve(projectRoot, 'content/docs');
mkdirSync(contentDir, { recursive: true });
const git = simpleGit(projectRoot);
await git.init();
configureTestGitRepository(projectRoot);
await git.raw('config', 'user.name', 'Test');
await git.raw('config', 'user.email', '[email protected]');
shadow = await initShadowRepo(projectRoot);
});
test('creates commit on refs/wip/<branch>/git-upstream', async () => {
writeFileSync(resolve(contentDir, 'api.md'), '# API Reference\n');
const sha = await commitUpstreamImport(shadow, 'content/docs', 'aabbccdd', '11223344');
expect(sha).toHaveLength(40);
const sg = shadowGit(shadow);
const refSha = (await sg.raw('rev-parse', 'refs/wip/main/git-upstream')).trim();
expect(refSha).toBe(sha);
});
test('commit message includes old..new head range', async () => {
writeFileSync(resolve(contentDir, 'api.md'), '# API\n');
const sha = await commitUpstreamImport(
shadow,
'content/docs',
'aabbccddeeff0011',
'1122334455667788',
);
const sg = shadowGit(shadow);
const msg = (await sg.raw('log', '-1', '--format=%s', sha)).trim();
expect(msg).toBe('import: from aabbccdd..11223344');
});
test('commit message handles null oldHead (initial import)', async () => {
writeFileSync(resolve(contentDir, 'api.md'), '# API\n');
const sha = await commitUpstreamImport(shadow, 'content/docs', null, '1122334455667788');
const sg = shadowGit(shadow);
const msg = (await sg.raw('log', '-1', '--format=%s', sha)).trim();
expect(msg).toBe('import: initial at 11223344');
});
test('upstream commit is authored by upstream writer', async () => {
writeFileSync(resolve(contentDir, 'api.md'), '# API\n');
const sha = await commitUpstreamImport(shadow, 'content/docs', null, 'deadbeef');
const sg = shadowGit(shadow);
const authorName = (await sg.raw('log', '-1', '--format=%an', sha)).trim();
expect(authorName).toBe('Git (upstream)');
});
test('commit body carries ok-actor: line (US-015)', async () => {
writeFileSync(resolve(contentDir, 'api.md'), '# API\n');
const sha = await commitUpstreamImport(shadow, 'content/docs', 'aabb0011', 'ccdd2233');
const sg = shadowGit(shadow);
const body = (await sg.raw('log', '-1', '--format=%B', sha)).trim();
const actor = parseOkActor(body);
expect(actor).not.toBeNull();
expect(actor?.v).toBe(1);
expect(actor?.display_name).toBe('Git (upstream)');
});
});
describe('safetyCheckpoint', () => {
let projectRoot: string;
let shadow: ShadowHandle;
let contentDir: string;
beforeEach(async () => {
projectRoot = resolve(tmpDir, 'project');
mkdirSync(projectRoot, { recursive: true });
contentDir = resolve(projectRoot, 'content/docs');
mkdirSync(contentDir, { recursive: true });
const git = simpleGit(projectRoot);
await git.init();
configureTestGitRepository(projectRoot);
await git.raw('config', 'user.name', 'Test');
await git.raw('config', 'user.email', '[email protected]');
shadow = await initShadowRepo(projectRoot);
});
test('uses checkpoint: prefix subject (US-015)', async () => {
writeFileSync(resolve(contentDir, 'intro.md'), '# Hello\n');
const sha = await safetyCheckpoint(shadow, 'content/docs', { action: 'rollback', context: {} });
const sg = shadowGit(shadow);
const subject = (await sg.raw('log', '-1', '--format=%s', sha)).trim();
expect(subject).toBe('checkpoint: pre-rollback');
});
test('commit body carries ok-actor: line (US-015)', async () => {
writeFileSync(resolve(contentDir, 'intro.md'), '# Hello\n');
const sha = await safetyCheckpoint(shadow, 'content/docs', { action: 'rollback', context: {} });
const sg = shadowGit(shadow);
const body = (await sg.raw('log', '-1', '--format=%B', sha)).trim();
const actor = parseOkActor(body);
expect(actor).not.toBeNull();
expect(actor?.v).toBe(1);
expect(actor?.display_name).toBe('OpenKnowledge (service)');
});
});
describe('parkBranch', () => {
let projectRoot: string;
let shadow: ShadowHandle;
beforeEach(async () => {
projectRoot = resolve(tmpDir, 'project');
mkdirSync(projectRoot, { recursive: true });
const git = simpleGit(projectRoot);
await git.init();
configureTestGitRepository(projectRoot);
await git.raw('config', 'user.name', 'Test');
await git.raw('config', 'user.email', '[email protected]');
shadow = await initShadowRepo(projectRoot);
});
test('creates park commit with Y.Doc state and disk snapshot (US-017)', async () => {
const docs: ParkableDoc[] = [
{
docName: 'intro',
markdown: '# Hello World\n\nEdited content\n',
diskSnapshot: '# Hello\n',
},
];
const sha = await parkBranch(shadow, 'main', SERVICE_WRITER.id, docs, 'feature');
expect(sha).toHaveLength(40);
if (!sha) throw new Error('parkBranch returned null');
const sg = shadowGit(shadow);
const msg = (await sg.raw('log', '-1', '--format=%s', sha)).trim();
expect(msg).toBe('park: main -> feature');
const refSha = (await sg.raw('rev-parse', `refs/wip/main/${SERVICE_WRITER.id}`)).trim();
expect(refSha).toBe(sha);
const content = (await sg.raw('show', `${sha}:intro`)).trim();
expect(content).toBe('# Hello World\n\nEdited content');
const base = (await sg.raw('show', `${sha}:.park-base/intro`)).trim();
expect(base).toBe('# Hello');
});
test('returns null for empty documents', async () => {
const sha = await parkBranch(shadow, 'main', SERVICE_WRITER.id, []);
expect(sha).toBeNull();
});
test('commit body carries ok-actor: line (US-015)', async () => {
const docs: ParkableDoc[] = [
{ docName: 'intro', markdown: '# Hello\n', diskSnapshot: '# Hello\n' },
];
const sha = await parkBranch(shadow, 'feature', SERVICE_WRITER.id, docs);
if (!sha) throw new Error('parkBranch returned null');
const sg = shadowGit(shadow);
const body = (await sg.raw('log', '-1', '--format=%B', sha)).trim();
const actor = parseOkActor(body);
expect(actor).not.toBeNull();
expect(actor?.v).toBe(1);
expect(actor?.display_name).toBe('OpenKnowledge (service)');
expect(actor?.docs).toContain('intro');
});
test('readParkedState retrieves parked content', async () => {
const docs: ParkableDoc[] = [
{ docName: 'guide', markdown: '# Guide v2\n', diskSnapshot: '# Guide v1\n' },
];
await parkBranch(shadow, 'feature', SERVICE_WRITER.id, docs);
const state = await readParkedState(shadow, 'feature', SERVICE_WRITER.id, 'guide');
expect(state).not.toBeNull();
expect(state?.markdown).toBe('# Guide v2\n');
expect(state?.diskSnapshot).toBe('# Guide v1\n');
});
test('readParkedState returns the parked markdown byte for byte', async () => {
const parked = '\n # Guide v2\r\n\nbody \n\n';
await parkBranch(shadow, 'feature', SERVICE_WRITER.id, [
{ docName: 'guide', markdown: parked, diskSnapshot: '# Guide v1\n' },
]);
const state = await readParkedState(shadow, 'feature', SERVICE_WRITER.id, 'guide');
expect(state?.markdown).toBe(parked);
});
test('readParkedState returns null when no park exists', async () => {
const state = await readParkedState(shadow, 'main', 'none', 'intro');
expect(state).toBeNull();
});
test('parks multiple documents', async () => {
const docs: ParkableDoc[] = [
{ docName: 'intro', markdown: '# Intro\n', diskSnapshot: '# Intro old\n' },
{ docName: 'guide', markdown: '# Guide\n', diskSnapshot: '# Guide old\n' },
];
const sha = await parkBranch(shadow, 'main', SERVICE_WRITER.id, docs);
expect(sha).toHaveLength(40);
const sg = shadowGit(shadow);
const introContent = (await sg.raw('show', `${sha}:intro`)).trim();
const guideContent = (await sg.raw('show', `${sha}:guide`)).trim();
expect(introContent).toBe('# Intro');
expect(guideContent).toBe('# Guide');
});
test('parks enough documents to span multiple hash/stage batches', async () => {
const docs: ParkableDoc[] = Array.from({ length: 120 }, (_, i) => ({
docName: `notes/doc-${i}`,
markdown: `# Doc ${i} memory\n`,
diskSnapshot: `# Doc ${i} disk\n`,
}));
const sha = await parkBranch(shadow, 'main', SERVICE_WRITER.id, docs);
expect(sha).toHaveLength(40);
const sg = shadowGit(shadow);
for (const i of [0, 99, 100, 119]) {
const content = (await sg.raw('show', `${sha}:notes/doc-${i}`)).trim();
expect(content).toBe(`# Doc ${i} memory`);
const base = (await sg.raw('show', `${sha}:.park-base/notes/doc-${i}`)).trim();
expect(base).toBe(`# Doc ${i} disk`);
}
});
test('isPairedWriteOrigin(PARK_SNAPSHOT_ORIGIN) returns true (US-017)', () => {
const origin = {
source: 'local' as const,
skipStoreHooks: false,
context: { origin: 'park-snapshot', paired: true as const },
};
expect(origin.context.paired).toBe(true);
expect(typeof origin.context.origin).toBe('string');
});
});
describe('saveVersion', () => {
let projectRoot: string;
let shadow: ShadowHandle;
let contentDir: string;
const human: WriterIdentity = {
id: 'human-ada',
name: 'Ada Lovelace',
email: '[email protected]',
};
const agent: WriterIdentity = {
id: 'agent-cursor',
name: 'cursor-agent',
email: '[email protected]',
};
beforeEach(async () => {
projectRoot = resolve(tmpDir, 'project');
mkdirSync(projectRoot, { recursive: true });
contentDir = resolve(projectRoot, 'content/docs');
mkdirSync(contentDir, { recursive: true });
const git = simpleGit(projectRoot);
await git.init();
configureTestGitRepository(projectRoot);
await git.raw('config', 'user.name', 'Test');
await git.raw('config', 'user.email', '[email protected]');
writeFileSync(resolve(contentDir, 'intro.md'), '# Hello\n');
await git.add('.');
await git.commit('Initial commit');
shadow = await initShadowRepo(projectRoot);
});
test('creates checkpoint ref in shadow', async () => {
writeFileSync(resolve(contentDir, 'intro.md'), '# Checkpoint\n');
const result = await saveVersion(shadow, 'content/docs', [human]);
const sg = shadowGit(shadow);
const checkpointSha = (await sg.raw('rev-parse', result.checkpointRef)).trim();
expect(checkpointSha).toHaveLength(40);
expect(result.checkpointRef).toBe(`refs/checkpoints/main/${checkpointSha}`);
const tree = (await sg.raw('ls-tree', '-r', '--name-only', result.checkpointRef)).trim();
expect(tree).toContain('content/docs/intro.md');
});
test('resets WIP refs after save', async () => {
writeFileSync(resolve(contentDir, 'intro.md'), '# WIP content\n');
await commitWip(shadow, human, 'content/docs', 'WIP: edit');
const sg = shadowGit(shadow);
const wipBefore = (await sg.raw('rev-parse', 'refs/wip/main/human-ada')).trim();
expect(wipBefore).toHaveLength(40);
await saveVersion(shadow, 'content/docs', [human]);
let wipExists = true;
try {
await sg.raw('rev-parse', 'refs/wip/main/human-ada');
} catch {
wipExists = false;
}
expect(wipExists).toBe(false);
});
test('multi-parent checkpoint preserves all writer chains', async () => {
writeFileSync(resolve(contentDir, 'intro.md'), '# Human edit\n');
const humanWipSha = await commitWip(shadow, human, 'content/docs', 'WIP: human edit');
writeFileSync(resolve(contentDir, 'intro.md'), '# Agent edit\n');
const agentWipSha = await commitWip(shadow, agent, 'content/docs', 'WIP: agent edit');
const result = await saveVersion(shadow, 'content/docs', [human, agent]);
const sg = shadowGit(shadow);
const parentLine = (await sg.raw('log', '-1', '--format=%P', result.checkpointRef)).trim();
const parents = parentLine.split(' ').filter(Boolean);
expect(parents).toContain(humanWipSha);
expect(parents).toContain(agentWipSha);
expect(parents.length).toBe(2);
const authorEmails = (
await sg.raw(
'log',
'--full-history',
'--author-date-order',
'--format=%ae',
result.checkpointRef,
)
)
.trim()
.split('\n')
.filter(Boolean);
expect(authorEmails).toContain(human.email);
expect(authorEmails).toContain(agent.email);
});
test('checkpoint commit carries ok-actor: body line (US-015)', async () => {
writeFileSync(resolve(contentDir, 'intro.md'), '# v1\n');
const result = await saveVersion(shadow, 'content/docs', [human]);
const sg = shadowGit(shadow);
const body = (await sg.raw('log', '-1', '--format=%B', result.checkpointRef)).trim();
const subject = (await sg.raw('log', '-1', '--format=%s', result.checkpointRef)).trim();
expect(subject).toBe('checkpoint: Checkpoint version');
const actor = parseOkActor(body);
expect(actor).not.toBeNull();
expect(actor?.v).toBe(1);
expect(actor?.display_name).toBe('OpenKnowledge (service)');
});
test('checkpoint falls back to latest checkpoint when no WIP activity', async () => {
writeFileSync(resolve(contentDir, 'intro.md'), '# v1\n');
await commitWip(shadow, human, 'content/docs', 'WIP: v1');
const result1 = await saveVersion(shadow, 'content/docs', [human]);
const sg = shadowGit(shadow);
const checkpoint1Sha = (await sg.raw('rev-parse', result1.checkpointRef)).trim();
writeFileSync(resolve(contentDir, 'intro.md'), '# v2 (direct write, no WIP commit)\n');
const result2 = await saveVersion(shadow, 'content/docs', [human]);
const parentLine = (await sg.raw('log', '-1', '--format=%P', result2.checkpointRef)).trim();
const parents = parentLine.split(' ').filter(Boolean);
expect(parents).toContain(checkpoint1Sha);
});
test('D21: every checkpoint adopts the latest prior checkpoint as a parent (even with WIP activity)', async () => {
writeFileSync(resolve(contentDir, 'intro.md'), '# v1\n');
await commitWip(shadow, human, 'content/docs', 'WIP: v1');
const result1 = await saveVersion(shadow, 'content/docs', [human]);
const sg = shadowGit(shadow);
const checkpoint1Sha = (await sg.raw('rev-parse', result1.checkpointRef)).trim();
writeFileSync(resolve(contentDir, 'intro.md'), '# v2\n');
const wip2 = await commitWip(shadow, human, 'content/docs', 'WIP: v2');
const result2 = await saveVersion(shadow, 'content/docs', [human]);
const parents = (await sg.raw('log', '-1', '--format=%P', result2.checkpointRef))
.trim()
.split(' ')
.filter(Boolean);
expect(parents).toContain(wip2);
expect(parents).toContain(checkpoint1Sha);
const reachable = (await sg.raw('rev-list', result2.checkpointRef)).trim().split('\n');
expect(reachable).toContain(checkpoint1Sha);
});
test('M3: checkpoints a feature branch (branch threaded through the spine)', async () => {
writeFileSync(resolve(contentDir, 'intro.md'), '# feature work\n');
await commitWip(shadow, human, 'content/docs', 'WIP: feature', 'feature-x');
const sg = shadowGit(shadow);
expect((await sg.raw('rev-parse', 'refs/wip/feature-x/human-ada')).trim()).toHaveLength(40);
const result = await saveVersion(shadow, 'content/docs', [human], 'feature-x');
expect(result.checkpointRef).toContain('refs/checkpoints/feature-x/');
let featureWipGone = false;
try {
await sg.raw('rev-parse', 'refs/wip/feature-x/human-ada');
} catch {
featureWipGone = true;
}
expect(featureWipGone).toBe(true);
});
test('M6: concurrent saveVersion calls use isolated scratch indexes (no corruption)', async () => {
writeFileSync(resolve(contentDir, 'intro.md'), '# human\n');
await commitWip(shadow, human, 'content/docs', 'WIP: human');
writeFileSync(resolve(contentDir, 'intro.md'), '# agent\n');
await commitWip(shadow, agent, 'content/docs', 'WIP: agent');
const [r1, r2] = await Promise.all([
saveVersion(shadow, 'content/docs', [human]),
saveVersion(shadow, 'content/docs', [agent]),
]);
const sg = shadowGit(shadow);
for (const r of [r1, r2]) {
const sha = (await sg.raw('rev-parse', r.checkpointRef)).trim();
expect(sha).toHaveLength(40);
const tree = (await sg.raw('ls-tree', '-r', '--name-only', r.checkpointRef)).trim();
expect(tree).toContain('content/docs/intro.md');
}
});
test('resetFoldedWipRefs skips a ref advanced past the snapshot, deletes a matching one', async () => {
writeFileSync(resolve(contentDir, 'intro.md'), '# agent v1\n');
const agentV1 = await commitWip(shadow, agent, 'content/docs', 'WIP: agent v1');
writeFileSync(resolve(contentDir, 'intro.md'), '# human stable\n');
const humanSha = await commitWip(shadow, human, 'content/docs', 'WIP: human stable');
const snapshot = new Map([
[agent.id, agentV1],
[human.id, humanSha],
]);
writeFileSync(resolve(contentDir, 'intro.md'), '# agent v2\n');
const agentV2 = await commitWip(shadow, agent, 'content/docs', 'WIP: agent v2');
const sg = shadowGit(shadow);
await resetFoldedWipRefs(sg, 'main', [agent, human], snapshot);
expect((await sg.raw('rev-parse', `refs/wip/main/${agent.id}`)).trim()).toBe(agentV2);
let humanGone = false;
try {
await sg.raw('rev-parse', `refs/wip/main/${human.id}`);
} catch {
humanGone = true;
}
expect(humanGone).toBe(true);
});
test('includeUpstream:false does not fold or reset the git-upstream chain', async () => {
writeFileSync(resolve(contentDir, 'intro.md'), '# agent\n');
const agentSha = await commitWip(shadow, agent, 'content/docs', 'WIP: agent');
writeFileSync(resolve(contentDir, 'intro.md'), '# upstream import\n');
const upstreamSha = await commitWip(
shadow,
GIT_UPSTREAM_WRITER,
'content/docs',
'WIP: upstream',
);
const result = await saveVersion(shadow, 'content/docs', [agent], 'main', undefined, {
includeUpstream: false,
});
const sg = shadowGit(shadow);
const parents = (await sg.raw('log', '-1', '--format=%P', result.checkpointRef))
.trim()
.split(' ')
.filter(Boolean);
expect(parents).toContain(agentSha);
expect(parents).not.toContain(upstreamSha);
expect((await sg.raw('rev-parse', `refs/wip/main/${GIT_UPSTREAM_WRITER.id}`)).trim()).toBe(
upstreamSha,
);
});
test('D9: checkpointKind tags the checkpoint as auto-consolidation', async () => {
writeFileSync(resolve(contentDir, 'intro.md'), '# consolidated\n');
await commitWip(shadow, agent, 'content/docs', 'WIP: agent');
const result = await saveVersion(shadow, 'content/docs', [agent], 'main', undefined, {
checkpointKind: { foldedRefs: 4, trigger: 'dead-chain' },
});
const sg = shadowGit(shadow);
const body = (await sg.raw('log', '-1', '--format=%B', result.checkpointRef)).trim();
const parsed = parseCheckpoint(body);
expect(parsed?.kind).toBe('auto-consolidation');
if (parsed?.kind === 'auto-consolidation') {
expect(parsed.metadata.foldedRefs).toBe(4);
expect(parsed.metadata.trigger).toBe('dead-chain');
}
});
test('user Save Version checkpoints stay untyped (no auto-consolidation tag)', async () => {
writeFileSync(resolve(contentDir, 'intro.md'), '# user save\n');
await commitWip(shadow, human, 'content/docs', 'WIP: human');
const result = await saveVersion(shadow, 'content/docs', [human]);
const sg = shadowGit(shadow);
const body = (await sg.raw('log', '-1', '--format=%B', result.checkpointRef)).trim();
expect(parseCheckpoint(body)).toBe(null);
});
});
describe('saveInMemoryCheckpoint (bridge-correctness SPEC §6 R7a)', () => {
let projectRoot: string;
let shadow: ShadowHandle;
beforeEach(async () => {
projectRoot = resolve(tmpDir, 'project');
mkdirSync(projectRoot, { recursive: true });
mkdirSync(resolve(projectRoot, 'content/docs'), { recursive: true });
const git = simpleGit(projectRoot);
await git.init();
configureTestGitRepository(projectRoot);
await git.raw('config', 'user.name', 'Test');
await git.raw('config', 'user.email', '[email protected]');
shadow = await initShadowRepo(projectRoot);
});
test('round-trips a bridge-merge-loss checkpoint — ref exists, parseCheckpoint recovers metadata', async () => {
const params: InMemoryCheckpointParams = {
kind: 'bridge-merge-loss',
docName: 'intro',
contents: '# Pre-merge baseline\n',
label: 'Before concurrent merge @ 2026-04-17T08:00:00Z',
branch: 'main',
metadata: { lostSubstrings: ['user keystroke', 'another lost phrase'] },
};
const sha = await saveInMemoryCheckpoint(shadow, 'content/docs', params);
const sg = shadowGit(shadow);
const refSha = (await sg.raw('rev-parse', `refs/checkpoints/main/${sha}`)).trim();
expect(refSha).toBe(sha);
const body = (await sg.raw('log', '-1', '--format=%B', sha)).trim();
expect(body).toContain('checkpoint: Before concurrent merge @ 2026-04-17T08:00:00Z');
const parsed = parseCheckpoint(body);
expect(parsed).not.toBeNull();
if (parsed?.kind !== 'bridge-merge-loss') throw new Error('expected bridge-merge-loss kind');
expect(parsed.metadata.lostSubstrings).toEqual(['user keystroke', 'another lost phrase']);
const tree = (await sg.raw('ls-tree', '-r', sha)).trim();
expect(tree).toContain('content/docs/intro');
expect(tree).not.toContain('content/docs/intro.md');
if (parsed.kind !== 'bridge-merge-loss') throw new Error('narrow');
expect(parsed.docName).toBe('intro');
expect(parsed.size).toBe(Buffer.byteLength('# Pre-merge baseline\n', 'utf-8'));
});
test('round-trips an external-change-rescue checkpoint', async () => {
const params: InMemoryCheckpointParams = {
kind: 'external-change-rescue',
docName: 'intro.md',
contents: '# Rescued in-memory content\n',
label: 'External change recovered @ 2026-04-17T08:00:00Z',
metadata: { incomingDiskSha: 'abc123def456' },
};
const sha = await saveInMemoryCheckpoint(shadow, 'content/docs', params);
const sg = shadowGit(shadow);
const body = (await sg.raw('log', '-1', '--format=%B', sha)).trim();
const parsed = parseCheckpoint(body);
expect(parsed).not.toBeNull();
if (parsed?.kind !== 'external-change-rescue') {
throw new Error('expected external-change-rescue kind');
}
expect(parsed.metadata.incomingDiskSha).toBe('abc123def456');
});
test('lists external-change-rescue checkpoints written by saveInMemoryCheckpoint', async () => {
const docName = 'hyvää yötä.md';
const contents = '# Rescued fast-path content\n';
const sha = await saveInMemoryCheckpoint(shadow, 'content/docs', {
kind: 'external-change-rescue',
docName,
contents,
label: 'Fast-path rescue',
metadata: { incomingDiskSha: 'abc123' },
});
const entries = await listRescueCheckpoints(shadow, 'main');
expect(entries).toHaveLength(1);
expect(entries[0]).toMatchObject({
docName,
size: Buffer.byteLength(contents, 'utf-8'),
sha,
label: 'Fast-path rescue',
incomingDiskSha: 'abc123',
});
expect(entries[0]?.timestamp).toMatch(/^\d{4}-\d{2}-\d{2}T/);
});
test('lists external-change-rescue-disk-update checkpoints and excludes non-rescue kinds', async () => {
const diskUpdateSha = await saveInMemoryCheckpoint(shadow, 'content/docs', {
kind: 'external-change-rescue-disk-update',
docName: 'disk-update.md',
contents: '# Disk-update rescued content\n',
label: 'External change recovered @ 2026-04-17T08:00:00Z',
metadata: { incomingDiskSha: 'abc123' },
});
await saveInMemoryCheckpoint(shadow, 'content/docs', {
kind: 'bridge-merge-loss',
docName: 'notes.md',
contents: '# Lost content\n',
label: 'Before concurrent merge @ 2026-04-17T08:00:00Z',
metadata: { lostSubstrings: ['dropped phrase'] },
});
const entries = await listRescueCheckpoints(shadow, 'main');
const names = entries.map((entry) => entry.docName);
expect(names).toContain('disk-update.md');
expect(names).not.toContain('notes.md');
expect(entries.find((entry) => entry.sha === diskUpdateSha)).toBeDefined();
});
test('lists legacy external-change-rescue checkpoints with non-ASCII docNames', async () => {
const docName = 'hyvää yötä.md';
const contents = '# Rescued legacy content\n';
const sg = shadowGit(shadow);
const tmpIndex = resolve(shadow.gitDir, 'index-legacy-rescue-test');
const tmpBlobFile = resolve(shadow.gitDir, 'tmp-legacy-rescue.md');
try {
writeFileSync(tmpBlobFile, contents);
const blobSha = (
await sg
.env({ GIT_DIR: shadow.gitDir, GIT_INDEX_FILE: tmpIndex })
.raw('hash-object', '-w', tmpBlobFile)
).trim();
await sg
.env({ GIT_DIR: shadow.gitDir, GIT_INDEX_FILE: tmpIndex })
.raw('update-index', '--add', '--cacheinfo', `100644,${blobSha},content/docs/${docName}`);
const treeSha = (
await sg.env({ GIT_DIR: shadow.gitDir, GIT_INDEX_FILE: tmpIndex }).raw('write-tree')
).trim();
const body =
'checkpoint: Legacy rescue\n\n' +
'ok-checkpoint-v1: {"kind":"external-change-rescue","metadata":{"incomingDiskSha":"abc123"}}';
const sha = (
await sg
.env({
GIT_DIR: shadow.gitDir,
GIT_AUTHOR_NAME: 'openknowledge',
GIT_AUTHOR_EMAIL: '[email protected]',
GIT_COMMITTER_NAME: 'openknowledge',
GIT_COMMITTER_EMAIL: '[email protected]',
})
.raw('commit-tree', treeSha, '-m', body)
).trim();
await sg.raw('update-ref', `refs/checkpoints/main/${sha}`, sha);
const entries = await listRescueCheckpoints(shadow, 'main');
expect(entries).toHaveLength(1);
expect(entries[0]).toMatchObject({
docName: 'hyvää yötä',
size: Buffer.byteLength(contents, 'utf-8'),
sha,
label: 'Legacy rescue',
incomingDiskSha: 'abc123',
});
expect(entries[0]?.timestamp).toMatch(/^\d{4}-\d{2}-\d{2}T/);
} finally {
rmSync(tmpIndex, { force: true });
rmSync(tmpBlobFile, { force: true });
}
});
test('does NOT touch refs/wip/* — distinct from saveVersion', async () => {
const writer: WriterIdentity = {
id: 'human-ada',
name: 'Ada',
email: '[email protected]',
};
const contentDir = resolve(projectRoot, 'content/docs');
writeFileSync(resolve(contentDir, 'intro.md'), '# hello\n');
await commitWip(shadow, writer, 'content/docs', 'WIP: setup');
const sg = shadowGit(shadow);
const wipShaBefore = (await sg.raw('rev-parse', 'refs/wip/main/human-ada')).trim();
await saveInMemoryCheckpoint(shadow, 'content/docs', {
kind: 'bridge-merge-loss',
docName: 'intro.md',
contents: '# pre-merge\n',
label: 'silent checkpoint',
metadata: { lostSubstrings: ['foo'] },
});
const wipShaAfter = (await sg.raw('rev-parse', 'refs/wip/main/human-ada')).trim();
expect(wipShaAfter).toBe(wipShaBefore);
});
test('concurrent invocations on the same shadow produce distinct refs (Q8)', async () => {
const params = (n: number): InMemoryCheckpointParams => ({
kind: 'bridge-merge-loss',
docName: `doc-${n}.md`,
contents: `# contents ${n}\n`,
label: `concurrent ${n}`,
metadata: { lostSubstrings: [`lost-${n}`] },
});
const results = await Promise.all(
[1, 2, 3, 4, 5].map((n) => saveInMemoryCheckpoint(shadow, 'content/docs', params(n))),
);
const unique = new Set(results);
expect(unique.size).toBe(5);
const sg = shadowGit(shadow);
for (const sha of results) {
const refSha = (await sg.raw('rev-parse', `refs/checkpoints/main/${sha}`)).trim();
expect(refSha).toBe(sha);
}
});
test('parseContributors tolerates sibling ok-checkpoint-v1 body lines (Q7)', async () => {
const body = [
'checkpoint: Before concurrent merge @ t',
'',
'ok-contributors: {"id":"human-a","name":"Alice","docs":["intro.md"]}',
'ok-checkpoint-v1: {"kind":"bridge-merge-loss","docName":"intro.md","size":16,"metadata":{"lostSubstrings":["x"]}}',
].join('\n');
const { parseContributors } = await import('@inkeep/open-knowledge-core/shadow-repo-layout');
const contributors = parseContributors(body);
expect(contributors).toHaveLength(1);
expect(contributors[0]?.id).toBe('human-a');
const checkpoint = parseCheckpoint(body);
expect(checkpoint?.kind).toBe('bridge-merge-loss');
});
});
describe('gcCheckpointRefs (bridge-correctness SPEC §6 R7 + review iteration 5)', () => {
let projectRoot: string;
let shadow: ShadowHandle;
beforeEach(async () => {
projectRoot = resolve(tmpDir, 'gc-project');
mkdirSync(projectRoot, { recursive: true });
mkdirSync(resolve(projectRoot, 'content/docs'), { recursive: true });
const git = simpleGit(projectRoot);
await git.init();
configureTestGitRepository(projectRoot);
await git.raw('config', 'user.name', 'Test');
await git.raw('config', 'user.email', '[email protected]');
shadow = await initShadowRepo(projectRoot);
});
test('keeps only the most-recent N bridge-merge-loss refs per branch', async () => {
const { gcCheckpointRefs } = await import('./shadow-repo.ts');
for (let i = 0; i < 7; i++) {
await saveInMemoryCheckpoint(shadow, 'content/docs', {
kind: 'bridge-merge-loss',
docName: `doc-${i}.md`,
contents: `contents ${i}\n`,
label: `loss ${i}`,
metadata: { lostSubstrings: [`lost-${i}`] },
date: `@${1_700_000_000 + i * 100} +0000`,
});
}
const result = await gcCheckpointRefs(shadow, 'main', {
...DEFAULT_CHECKPOINT_RETENTION,
maxBridgeMergeLoss: 3,
maxProducerGuardLoss: 50,
maxExternalChangeRescue: 50,
maxAutoConsolidation: 2,
ttlMs: 0,
});
expect(result.scanned).toBe(7);
expect(result.deletedBridgeMergeLoss).toBe(4);
expect(result.deletedExternalChangeRescue).toBe(0);
const sg = shadowGit(shadow);
const remaining = (
await sg.raw('for-each-ref', '--format=%(refname)', 'refs/checkpoints/main/')
)
.trim()
.split('\n')
.filter(Boolean);
expect(remaining).toHaveLength(3);
});
test('keeps only the most-recent N producer-guard-loss refs per branch', async () => {
const { gcCheckpointRefs } = await import('./shadow-repo.ts');
for (let i = 0; i < 7; i++) {
await saveInMemoryCheckpoint(shadow, 'content/docs', {
kind: 'producer-guard-loss',
docName: `doc-${i}.md`,
contents: `contents ${i}\n`,
label: `guard loss ${i}`,
metadata: { construct: 'table' },
date: `@${1_700_000_000 + i * 100} +0000`,
});
}
await saveInMemoryCheckpoint(shadow, 'content/docs', {
kind: 'bridge-merge-loss',
docName: 'merge.md',
contents: '# pre-merge\n',
label: 'merge loss',
metadata: { lostSubstrings: ['x'] },
});
const result = await gcCheckpointRefs(shadow, 'main', {
...DEFAULT_CHECKPOINT_RETENTION,
maxBridgeMergeLoss: 50,
maxProducerGuardLoss: 3,
maxExternalChangeRescue: 50,
maxAutoConsolidation: 2,
ttlMs: 0,
});
expect(result.scanned).toBe(8);
expect(result.deletedProducerGuardLoss).toBe(4);
expect(result.deletedBridgeMergeLoss).toBe(0);
const sg = shadowGit(shadow);
const remaining = (
await sg.raw('for-each-ref', '--format=%(refname)', 'refs/checkpoints/main/')
)
.trim()
.split('\n')
.filter(Boolean);
expect(remaining).toHaveLength(4);
});
test('applies TTL independently of the count cap', async () => {
for (let i = 0; i < 2; i++) {
await saveInMemoryCheckpoint(shadow, 'content/docs', {
kind: 'external-change-rescue',
docName: `doc-${i}.md`,
contents: `contents ${i}\n`,
label: `rescue ${i}`,
metadata: { incomingDiskSha: `sha-${i}` },
});
}
await wait(5);
const { gcCheckpointRefs } = await import('./shadow-repo.ts');
const result = await gcCheckpointRefs(shadow, 'main', {
...DEFAULT_CHECKPOINT_RETENTION,
maxBridgeMergeLoss: 50,
maxProducerGuardLoss: 50,
maxExternalChangeRescue: 50,
maxAutoConsolidation: 2,
ttlMs: 1,
});
expect(result.deletedExternalChangeRescue).toBe(2);
});
test('does NOT delete untyped Save-Version-style checkpoints', async () => {
const { gcCheckpointRefs } = await import('./shadow-repo.ts');
const sg = shadowGit(shadow);
const emptyTreeSha = (await sg.raw('hash-object', '-t', 'tree', '-w', '/dev/null')).trim();
const untypedSha = (
await sg
.env({
GIT_DIR: shadow.gitDir,
GIT_AUTHOR_NAME: 'test',
GIT_AUTHOR_EMAIL: 'test@test',
GIT_COMMITTER_NAME: 'test',
GIT_COMMITTER_EMAIL: 'test@test',
})
.raw('commit-tree', emptyTreeSha, '-m', 'checkpoint: Save Version')
).trim();
await sg.raw('update-ref', `refs/checkpoints/main/${untypedSha}`, untypedSha);
await saveInMemoryCheckpoint(shadow, 'content/docs', {
kind: 'bridge-merge-loss',
docName: 'intro.md',
contents: '# pre-merge\n',
label: 'silent',
metadata: { lostSubstrings: ['x'] },
});
const result = await gcCheckpointRefs(shadow, 'main', {
...DEFAULT_CHECKPOINT_RETENTION,
maxBridgeMergeLoss: 0,
maxProducerGuardLoss: 0,
maxExternalChangeRescue: 0,
maxAutoConsolidation: 2,
ttlMs: 0,
});
expect(result.deletedBridgeMergeLoss).toBe(1);
const refs = (await sg.raw('for-each-ref', '--format=%(refname)', 'refs/checkpoints/main/'))
.trim()
.split('\n')
.filter(Boolean);
expect(refs).toContain(`refs/checkpoints/main/${untypedSha}`);
});
async function writeAutoConsolidationCheckpoint(
s: ShadowHandle,
foldedRefs: number,
ageRank = foldedRefs,
): Promise<string> {
const sg = shadowGit(s);
const emptyTreeSha = (await sg.raw('hash-object', '-t', 'tree', '-w', '/dev/null')).trim();
const body = `checkpoint: consolidated ${foldedRefs} inactive sessions\n\n${formatCheckpointBodyLine(
{
kind: 'auto-consolidation',
docName: null,
size: null,
metadata: { foldedRefs, trigger: 'dead-chain' },
},
)}`;
const date = `@${1_700_000_000 + ageRank * 100} +0000`;
const sha = (
await sg
.env({
GIT_DIR: s.gitDir,
GIT_AUTHOR_NAME: 'openknowledge-service',
GIT_AUTHOR_EMAIL: '[email protected]',
GIT_AUTHOR_DATE: date,
GIT_COMMITTER_NAME: 'openknowledge-service',
GIT_COMMITTER_EMAIL: '[email protected]',
GIT_COMMITTER_DATE: date,
})
.raw('commit-tree', emptyTreeSha, '-m', body)
).trim();
await sg.raw('update-ref', `refs/checkpoints/main/${sha}`, sha);
return sha;
}
test('A3: adding the auto-consolidation kind does not throw the byKind partition', async () => {
const { gcCheckpointRefs } = await import('./shadow-repo.ts');
await writeAutoConsolidationCheckpoint(shadow, 3);
const result = await gcCheckpointRefs(shadow, 'main', DEFAULT_CHECKPOINT_RETENTION);
expect(result.scanned).toBe(1);
expect(result.deletedAutoConsolidation).toBe(0);
});
test('keeps only the newest 2 auto-consolidation refs (count-only, D21)', async () => {
const { gcCheckpointRefs } = await import('./shadow-repo.ts');
const shas: string[] = [];
for (let i = 0; i < 5; i++) {
shas.push(await writeAutoConsolidationCheckpoint(shadow, i + 1, i + 1));
}
const result = await gcCheckpointRefs(shadow, 'main', {
...DEFAULT_CHECKPOINT_RETENTION,
maxBridgeMergeLoss: 50,
maxProducerGuardLoss: 50,
maxExternalChangeRescue: 50,
maxAutoConsolidation: 2,
ttlMs: 0,
});
expect(result.scanned).toBe(5);
expect(result.deletedAutoConsolidation).toBe(3);
const sg = shadowGit(shadow);
const remaining = (
await sg.raw('for-each-ref', '--format=%(refname)', 'refs/checkpoints/main/')
)
.trim()
.split('\n')
.filter(Boolean);
expect(remaining).toHaveLength(2);
expect(remaining).toContain(`refs/checkpoints/main/${shas[4]}`);
expect(remaining).toContain(`refs/checkpoints/main/${shas[3]}`);
});
test('TTL never reaps auto-consolidation refs (chained history must stay anchored)', async () => {
const { gcCheckpointRefs } = await import('./shadow-repo.ts');
await writeAutoConsolidationCheckpoint(shadow, 1);
await writeAutoConsolidationCheckpoint(shadow, 2);
const result = await gcCheckpointRefs(shadow, 'main', {
...DEFAULT_CHECKPOINT_RETENTION,
maxBridgeMergeLoss: 50,
maxProducerGuardLoss: 50,
maxExternalChangeRescue: 50,
maxAutoConsolidation: 2,
ttlMs: 1,
});
expect(result.deletedAutoConsolidation).toBe(0);
});
const seedDate = (rank: number): string => `@${1_700_000_000 + rank * 100} +0000`;
const seedKind = async (kind: CheckpointKind, tag = '', date?: string): Promise<void> => {
switch (kind) {
case 'bridge-merge-loss':
await saveInMemoryCheckpoint(shadow, 'content/docs', {
kind,
docName: 'a.md',
contents: `a${tag}\n`,
label: 'l',
date,
metadata: { lostSubstrings: ['x'] },
});
return;
case 'producer-guard-loss':
await saveInMemoryCheckpoint(shadow, 'content/docs', {
kind,
docName: 'b.md',
contents: `b${tag}\n`,
label: 'l',
date,
metadata: { construct: 'tableCell' },
});
return;
case 'observer-a-duplication':
await saveInMemoryCheckpoint(shadow, 'content/docs', {
kind,
docName: 'c.md',
contents: `c${tag}\n`,
label: 'l',
date,
metadata: { duplicatedLineCount: 1 },
});
return;
case 'external-change-rescue':
await saveInMemoryCheckpoint(shadow, 'content/docs', {
kind,
docName: 'd.md',
contents: `d${tag}\n`,
label: 'l',
date,
metadata: { incomingDiskSha: 'sha' },
});
return;
case 'external-change-rescue-disk-update':
await saveInMemoryCheckpoint(shadow, 'content/docs', {
kind,
docName: 'd.md',
contents: `d${tag}\n`,
label: 'l',
date,
metadata: { incomingDiskSha: 'sha' },
});
return;
case 'defer-exhaustion-loss':
await saveInMemoryCheckpoint(shadow, 'content/docs', {
kind,
docName: 'e.md',
contents: `e${tag}\n`,
label: 'l',
date,
metadata: { deferCount: 8 },
});
return;
case 'observer-a-apply-loss':
await saveInMemoryCheckpoint(shadow, 'content/docs', {
kind,
docName: 'h.md',
contents: `h${tag}\n`,
label: 'l',
date,
metadata: { lostSubstrings: ['dropped'] },
});
return;
case 'bridge-derive-loss':
await saveInMemoryCheckpoint(shadow, 'content/docs', {
kind,
docName: 'f.md',
contents: `f${tag}\n`,
label: 'l',
date,
metadata: { lostSubstrings: ['dropped'] },
});
return;
case 'bridge-backstop-trip':
await saveInMemoryCheckpoint(shadow, 'content/docs', {
kind,
docName: 'g.md',
contents: `g${tag}\n`,
label: 'l',
date,
metadata: { rounds: 8 },
});
return;
case 'persistence-reconcile-loss':
await saveInMemoryCheckpoint(shadow, 'content/docs', {
kind,
docName: 'i.md',
contents: `i${tag}\n`,
label: 'l',
date,
metadata: { atRiskLines: 1, witnessAvailable: true },
});
return;
case 'persistence-duplication-reset':
await saveInMemoryCheckpoint(shadow, 'content/docs', {
kind,
docName: 'j.md',
contents: `j${tag}\n`,
label: 'l',
date,
metadata: { copies: 2, fragmentChildren: 18 },
});
return;
case 'persistence-divergence-realign':
await saveInMemoryCheckpoint(shadow, 'content/docs', {
kind,
docName: 'k.md',
contents: `k${tag}\n`,
label: 'l',
date,
metadata: { diskBytes: 37, discardedBytes: 79 },
});
return;
case 'managed-artifact-reconcile':
await saveInMemoryCheckpoint(shadow, 'content/docs', {
kind,
docName: 'm.md',
contents: `m${tag}\n`,
label: 'l',
date,
metadata: { diskBytes: 41, discardedBytes: 66 },
});
return;
case 'external-change-both-kept':
await saveInMemoryCheckpoint(shadow, 'content/docs', {
kind,
docName: 'n.md',
contents: `n${tag}\n`,
label: 'l',
date,
metadata: { side: 'theirs', keptBlocks: 1 },
});
return;
case 'external-change-kept-live':
await saveInMemoryCheckpoint(shadow, 'content/docs', {
kind,
docName: 'o.md',
contents: `o${tag}\n`,
label: 'l',
date,
metadata: { side: 'theirs', reason: 'check-failed' },
});
return;
case 'external-change-no-engine':
await saveInMemoryCheckpoint(shadow, 'content/docs', {
kind,
docName: 'p.mmd',
contents: `p${tag}\n`,
label: 'l',
date,
metadata: { side: 'theirs', fileType: 'mermaid' },
});
return;
case 'auto-consolidation':
await writeAutoConsolidationCheckpoint(shadow, tag === '' ? 1 : Number(tag));
return;
default: {
const unseeded: never = kind;
throw new Error(`unseeded checkpoint kind: ${unseeded}`);
}
}
};
test('buckets every registered checkpoint kind without throwing', async () => {
const { gcCheckpointRefs } = await import('./shadow-repo.ts');
for (const kind of CHECKPOINT_KINDS) await seedKind(kind);
const result = await gcCheckpointRefs(shadow, 'main', {
...DEFAULT_CHECKPOINT_RETENTION,
maxBridgeMergeLoss: 50,
maxProducerGuardLoss: 50,
maxObserverADuplication: 50,
maxExternalChangeRescue: 50,
maxDeferExhaustionLoss: 50,
maxBridgeDeriveLoss: 50,
maxObserverAApplyLoss: 50,
maxBridgeBackstopTrip: 50,
maxPersistenceReconcileLoss: 50,
maxPersistenceDuplicationReset: 50,
maxPersistenceDivergenceRealign: 50,
maxManagedArtifactReconcile: 50,
maxAutoConsolidation: 50,
ttlMs: 0,
});
expect(result.scanned).toBe(CHECKPOINT_KINDS.length);
expect(result.retained).toBe(CHECKPOINT_KINDS.length);
});
test('a document-scoped history kind keeps its cap per document and never expires', async () => {
const { gcCheckpointRefs } = await import('./shadow-repo.ts');
const seed = (docName: string, rank: number): Promise<string> =>
saveInMemoryCheckpoint(shadow, 'content/docs', {
kind: 'external-change-both-kept',
docName,
contents: `${docName} ${rank}\n`,
label: 'l',
date: seedDate(rank),
metadata: { side: 'theirs', keptBlocks: 1 },
});
const quiet = [await seed('quiet.md', 1), await seed('quiet.md', 2)];
const busy: string[] = [];
for (let rank = 3; rank <= 8; rank++) busy.push(await seed('busy.md', rank));
const result = await gcCheckpointRefs(shadow, 'main', {
...DEFAULT_CHECKPOINT_RETENTION,
maxExternalChangeBothKeptPerDocument: 3,
ttlMs: 1,
});
expect(result.deletedExternalChangeBothKept).toBe(3);
const remaining = (
await shadowGit(shadow).raw(
'for-each-ref',
'--format=%(objectname)',
'refs/checkpoints/main/',
)
)
.trim()
.split('\n')
.sort();
expect(remaining).toEqual([...quiet, ...busy.slice(3)].sort());
});
test('outside versions of files with no merge engine keep a per-document cap and never expire', async () => {
const { gcCheckpointRefs } = await import('./shadow-repo.ts');
const seed = (docName: string, rank: number): Promise<string> =>
saveInMemoryCheckpoint(shadow, 'content/docs', {
kind: 'external-change-no-engine',
docName,
contents: `${docName} ${rank}\n`,
label: 'l',
date: seedDate(rank),
metadata: { side: 'theirs', fileType: 'excalidraw' },
});
const quiet = await seed('quiet.excalidraw', 1);
const busy: string[] = [];
for (let rank = 2; rank <= 5; rank++) busy.push(await seed('busy.excalidraw', rank));
const result = await gcCheckpointRefs(shadow, 'main', {
...DEFAULT_CHECKPOINT_RETENTION,
maxExternalChangeNoEnginePerDocument: 2,
ttlMs: 1,
});
expect(result.deletedExternalChangeNoEngine).toBe(2);
const remaining = (
await shadowGit(shadow).raw(
'for-each-ref',
'--format=%(objectname)',
'refs/checkpoints/main/',
)
)
.trim()
.split('\n')
.sort();
expect(remaining).toEqual([quiet, ...busy.slice(2)].sort());
});
test('every registered kind is actually REAPED at its own limit, not merely bucketed', async () => {
const { gcCheckpointRefs } = await import('./shadow-repo.ts');
for (const kind of CHECKPOINT_KINDS) {
await seedKind(kind, '1', seedDate(1));
await seedKind(kind, '2', seedDate(2));
}
const limits = Object.fromEntries(
Object.entries(DEFAULT_CHECKPOINT_RETENTION).map(([k, v]) =>
k.startsWith('max') ? [k, 1] : [k, v],
),
) as typeof DEFAULT_CHECKPOINT_RETENTION;
const result = await gcCheckpointRefs(shadow, 'main', { ...limits, ttlMs: 0 });
const deleted = Object.entries(result).filter(([k]) => k.startsWith('deleted'));
expect(deleted.length).toBe(CHECKPOINT_KINDS.length);
for (const [counter, count] of deleted) {
expect(`${counter}=${count}`).toBe(`${counter}=1`);
}
expect(result.retained).toBe(CHECKPOINT_KINDS.length);
});
});
describe('checkpoint chain anchoring', () => {
let projectRoot: string;
let shadow: ShadowHandle;
const WRITER: WriterIdentity = {
id: 'agent-a',
name: 'Agent A',
email: '[email protected]',
};
beforeEach(async () => {
projectRoot = resolve(tmpDir, 'chain-project');
mkdirSync(resolve(projectRoot, 'content/docs'), { recursive: true });
const git = simpleGit(projectRoot);
await git.init();
configureTestGitRepository(projectRoot);
await git.raw('config', 'user.name', 'Test');
await git.raw('config', 'user.email', '[email protected]');
shadow = await initShadowRepo(projectRoot);
});
const at = (rank: number): string => `@${1_700_000_000 + rank * 100} +0000`;
async function edit(tag: string, rank: number): Promise<void> {
writeFileSync(resolve(projectRoot, 'content/docs/intro.md'), `# ${tag}\n`, 'utf-8');
await commitWip(shadow, WRITER, 'content/docs', `wip ${tag}`, 'main', { date: at(rank) });
}
async function consolidate(tag: string, rank: number): Promise<string> {
const { checkpointRef } = await saveVersion(shadow, 'content/docs', [WRITER], 'main', tag, {
checkpointKind: { foldedRefs: 1, trigger: 'dead-chain' },
date: at(rank),
});
return checkpointRef.split('/').pop() as string;
}
async function lossCheckpoint(rank: number): Promise<string> {
return saveInMemoryCheckpoint(shadow, 'content/docs', {
kind: 'bridge-merge-loss',
docName: 'intro.md',
contents: '# rescued\n',
label: 'merge loss',
metadata: { lostSubstrings: ['x'] },
date: at(rank),
});
}
const reachableShas = async (): Promise<string[]> =>
(await shadowGit(shadow).raw('rev-list', '--all')).trim().split('\n').filter(Boolean);
const parentsOf = async (sha: string): Promise<string[]> =>
(await shadowGit(shadow).raw('rev-list', '--parents', '-n', '1', sha))
.trim()
.split(/\s+/)
.slice(1);
test('a kind that anchors the chain is count-only, and a single-document kind never anchors', async () => {
const { GC_BUCKET_POLICY } = await import('./shadow-repo.ts');
for (const kind of CHECKPOINT_KINDS) {
const { chainAnchor, gcBucket } = CHECKPOINT_KIND_REGISTRY[kind];
if (chainAnchor) {
expect(`${kind}:applyTtl=${GC_BUCKET_POLICY[gcBucket].applyTtl}`).toBe(
`${kind}:applyTtl=false`,
);
}
if (CHECKPOINT_SAMPLE_BY_KIND[kind].docName !== null) {
expect(`${kind}:chainAnchor=${chainAnchor}`).toBe(`${kind}:chainAnchor=false`);
}
}
});
test('a reaped consolidation stays reachable when a loss checkpoint landed between folds', async () => {
const { gcCheckpointRefs } = await import('./shadow-repo.ts');
await edit('one', 1);
const c1 = await consolidate('auto 1', 2);
await lossCheckpoint(3);
await edit('two', 4);
const c2 = await consolidate('auto 2', 5);
await edit('three', 6);
await consolidate('auto 3', 7);
const gc = await gcCheckpointRefs(shadow, 'main', {
...DEFAULT_CHECKPOINT_RETENTION,
maxAutoConsolidation: 2,
ttlMs: 0,
});
expect(gc.deletedAutoConsolidation).toBe(1);
expect(await parentsOf(c2)).toContain(c1);
expect(await reachableShas()).toContain(c1);
});
test('a consolidation adopts every dangling durable tip, not just one', async () => {
await edit('one', 1);
const c1 = await consolidate('auto 1', 2);
await lossCheckpoint(3);
await edit('two', 4);
const c2 = await consolidate('auto 2', 5);
await edit('three', 6);
const c3 = await consolidate('auto 3', 7);
const reachableFromC3 = (await shadowGit(shadow).raw('rev-list', c3))
.trim()
.split('\n')
.filter(Boolean);
expect(reachableFromC3).toContain(c2);
expect(reachableFromC3).toContain(c1);
});
test('a consolidation re-joins a chain that is already forked into two durable tips', async () => {
const { gcCheckpointRefs } = await import('./shadow-repo.ts');
const sg = shadowGit(shadow);
await edit('one', 1);
const c1 = await consolidate('auto 1', 2);
const tree = (await sg.raw('rev-parse', `${c1}^{tree}`)).trim();
const severed = (
await sg
.env({
GIT_DIR: shadow.gitDir,
GIT_AUTHOR_NAME: 'openknowledge',
GIT_AUTHOR_EMAIL: '[email protected]',
GIT_COMMITTER_NAME: 'openknowledge',
GIT_COMMITTER_EMAIL: '[email protected]',
GIT_AUTHOR_DATE: at(3),
GIT_COMMITTER_DATE: at(3),
})
.raw(
'commit-tree',
tree,
'-m',
`checkpoint: severed\n\n${formatCheckpointBodyLine({
kind: 'auto-consolidation',
docName: null,
size: null,
metadata: { foldedRefs: 1, trigger: 'dead-chain' },
})}`,
)
).trim();
await sg.raw('update-ref', `refs/checkpoints/main/${severed}`, severed);
await edit('two', 4);
const c2 = await consolidate('auto 2', 5);
const parents = await parentsOf(c2);
expect(parents).toContain(severed);
expect(parents).toContain(c1);
const gc = await gcCheckpointRefs(shadow, 'main', {
...DEFAULT_CHECKPOINT_RETENTION,
maxAutoConsolidation: 2,
ttlMs: 0,
});
expect(gc.deletedAutoConsolidation).toBe(1);
expect(await reachableShas()).toContain(c1);
});
test('a loss checkpoint is never adopted, so reaping its ref still bounds its content', async () => {
const { gcCheckpointRefs } = await import('./shadow-repo.ts');
await edit('one', 1);
await consolidate('auto 1', 2);
const loss = await lossCheckpoint(3);
await edit('two', 4);
const c2 = await consolidate('auto 2', 5);
expect(await parentsOf(c2)).not.toContain(loss);
const gc = await gcCheckpointRefs(shadow, 'main', {
...DEFAULT_CHECKPOINT_RETENTION,
maxBridgeMergeLoss: 0,
maxAutoConsolidation: 2,
ttlMs: 0,
});
expect(gc.deletedBridgeMergeLoss).toBe(1);
expect(await reachableShas()).not.toContain(loss);
});
});
describe('sweepLegacyShadowRefs (US-018, D35, NFR-6)', () => {
let projectRoot: string;
let shadow: ShadowHandle;
beforeEach(async () => {
projectRoot = resolve(tmpDir, 'sweep-test');
mkdirSync(projectRoot, { recursive: true });
const git = simpleGit(projectRoot);
await git.init();
configureTestGitRepository(projectRoot);
await git.raw('config', 'user.name', 'Test');
await git.raw('config', 'user.email', '[email protected]');
shadow = await initShadowRepo(projectRoot);
});
async function createRef(refname: string): Promise<void> {
const sg = shadowGit(shadow);
const emptyTreeSha = (await sg.raw('hash-object', '-t', 'tree', '-w', '/dev/null')).trim();
const commitSha = (
await sg
.env({
GIT_DIR: shadow.gitDir,
GIT_AUTHOR_DATE: '2020-01-01T00:00:00+00:00',
GIT_COMMITTER_DATE: '2020-01-01T00:00:00+00:00',
GIT_AUTHOR_NAME: 'test',
GIT_AUTHOR_EMAIL: '[email protected]',
GIT_COMMITTER_NAME: 'test',
GIT_COMMITTER_EMAIL: '[email protected]',
})
.raw('commit-tree', emptyTreeSha, '-m', `test: ${refname}`)
).trim();
await sg.raw('update-ref', refname, commitSha);
}
test('deletes only legacy refs (server, human-*, upstream); preserves new taxonomy (US-018)', async () => {
await createRef('refs/wip/main/server');
await createRef('refs/wip/main/human-abc');
await createRef('refs/wip/main/human-def123');
await createRef('refs/wip/main/upstream');
await createRef('refs/wip/main/agent-xyz');
await createRef('refs/wip/main/principal-def');
await createRef('refs/wip/main/file-system');
await createRef('refs/wip/main/git-upstream');
await createRef('refs/wip/main/openknowledge-service');
const deleted = await sweepLegacyShadowRefs(shadow);
expect(deleted).toBe(4);
const sg = shadowGit(shadow);
const remaining = (await sg.raw('for-each-ref', '--format=%(refname)', 'refs/wip'))
.trim()
.split('\n')
.filter(Boolean);
expect(remaining).not.toContain('refs/wip/main/server');
expect(remaining).not.toContain('refs/wip/main/human-abc');
expect(remaining).not.toContain('refs/wip/main/human-def123');
expect(remaining).not.toContain('refs/wip/main/upstream');
expect(remaining).toContain('refs/wip/main/agent-xyz');
expect(remaining).toContain('refs/wip/main/principal-def');
expect(remaining).toContain('refs/wip/main/file-system');
expect(remaining).toContain('refs/wip/main/git-upstream');
expect(remaining).toContain('refs/wip/main/openknowledge-service');
});
test('idempotent — second sweep deletes nothing (US-018)', async () => {
await createRef('refs/wip/main/server');
await createRef('refs/wip/main/agent-abc');
const first = await sweepLegacyShadowRefs(shadow);
expect(first).toBe(1);
const second = await sweepLegacyShadowRefs(shadow);
expect(second).toBe(0);
});
test('fresh repo with no refs returns 0 (US-018)', async () => {
const deleted = await sweepLegacyShadowRefs(shadow);
expect(deleted).toBe(0);
});
});
const STOCK_GIT_EXCLUDE = `# git ls-files --others --exclude-from=.git/info/exclude
# Lines that start with '#' are comments.
`;
describe('shadow repo excludes OpenKnowledge machine-local state', () => {
let projectRoot: string;
let shadow: ShadowHandle;
const writer: WriterIdentity = {
id: 'human-ada',
name: 'Ada Lovelace',
email: '[email protected]',
};
beforeEach(async () => {
projectRoot = resolve(tmpDir, 'project');
mkdirSync(resolve(projectRoot, '.ok/local/cache/main'), { recursive: true });
mkdirSync(resolve(projectRoot, '.ok/worktrees/feature'), { recursive: true });
const git = simpleGit(projectRoot);
await git.init();
configureTestGitRepository(projectRoot);
await git.raw('config', 'user.name', 'Test');
await git.raw('config', 'user.email', '[email protected]');
writeFileSync(resolve(projectRoot, 'intro.md'), '# Hello\n');
writeFileSync(resolve(projectRoot, '.ok/config.yml'), 'content:\n dir: .\n');
writeFileSync(
resolve(projectRoot, '.ok/local/principal.json'),
'{"email":"[email protected]"}\n',
);
writeFileSync(resolve(projectRoot, '.ok/local/server.lock'), '{"pid":1}\n');
writeFileSync(resolve(projectRoot, '.ok/local/cache/main/backlinks.json'), '{}\n');
writeFileSync(resolve(projectRoot, '.ok/worktrees/feature/scratch.md'), '# scratch\n');
shadow = await initShadowRepo(projectRoot);
});
async function seedStaleWipRef(handle: ShadowHandle, writerId: string): Promise<void> {
const excludeFile = resolve(handle.gitDir, 'info/exclude');
const realExclude = existsSync(excludeFile) ? readFileSync(excludeFile, 'utf-8') : '';
const seedIndex = resolve(handle.gitDir, `index-stale-seed-${writerId}`);
rmSync(seedIndex, { force: true });
writeFileSync(excludeFile, STOCK_GIT_EXCLUDE);
const gitEnv = { ...process.env, GIT_DIR: handle.gitDir, GIT_INDEX_FILE: seedIndex };
try {
execFileSync('git', ['add', '-A', '.'], {
cwd: handle.workTree,
env: { ...gitEnv, GIT_WORK_TREE: handle.workTree },
});
const tree = execFileSync('git', ['write-tree'], {
cwd: handle.workTree,
env: gitEnv,
encoding: 'utf-8',
}).trim();
const commit = execFileSync('git', ['commit-tree', tree, '-m', 'WIP: pre-upgrade'], {
cwd: handle.workTree,
env: gitEnv,
encoding: 'utf-8',
}).trim();
execFileSync('git', ['update-ref', `refs/wip/main/${writerId}`, commit], {
cwd: handle.workTree,
env: gitEnv,
});
} finally {
writeFileSync(excludeFile, realExclude);
rmSync(seedIndex, { force: true });
}
}
function seedStaleFanoutIndex(handle: ShadowHandle): string {
const excludeFile = resolve(handle.gitDir, 'info/exclude');
const realExclude = existsSync(excludeFile) ? readFileSync(excludeFile, 'utf-8') : '';
const fanoutIndex = resolve(handle.gitDir, FANOUT_INDEX_NAME);
rmSync(fanoutIndex, { force: true });
writeFileSync(excludeFile, STOCK_GIT_EXCLUDE);
try {
execFileSync('git', ['add', '-A', '.'], {
cwd: handle.workTree,
env: {
...process.env,
GIT_DIR: handle.gitDir,
GIT_WORK_TREE: handle.workTree,
GIT_INDEX_FILE: fanoutIndex,
},
});
} finally {
writeFileSync(excludeFile, realExclude);
}
return fanoutIndex;
}
function indexPaths(handle: ShadowHandle, indexFile: string): string[] {
return execFileSync('git', ['ls-files'], {
cwd: handle.workTree,
env: { ...process.env, GIT_DIR: handle.gitDir, GIT_INDEX_FILE: indexFile },
encoding: 'utf-8',
})
.split('\n')
.map((path) => path.trim())
.filter((path) => path.length > 0);
}
async function wipTreePaths(handle: ShadowHandle, writerId: string): Promise<string[]> {
const sg = shadowGit(handle);
return (await sg.raw('ls-tree', '-r', '--name-only', `refs/wip/main/${writerId}`))
.split('\n')
.map((path) => path.trim())
.filter((path) => path.length > 0);
}
async function checkpointTreePaths(ref: string): Promise<string[]> {
const sg = shadowGit(shadow);
return (await sg.raw('ls-tree', '-r', '--name-only', ref))
.split('\n')
.map((path) => path.trim())
.filter((path) => path.length > 0);
}
test('the shadow does not see .ok/local or .ok/worktrees as content', async () => {
const sg = shadowGit(shadow);
const status = await sg.raw('status', '--porcelain', '--untracked-files=all');
const paths = status
.split('\n')
.map((line) => line.slice(3).trim())
.filter((p) => p.length > 0);
expect(paths).toContain('intro.md');
expect(paths).toContain('.ok/config.yml');
expect(paths.filter((p) => p.startsWith('.ok/local/'))).toEqual([]);
expect(paths.filter((p) => p.startsWith('.ok/worktrees/'))).toEqual([]);
});
test('a checkpoint keeps machine-local state out of version history', async () => {
const result = await saveVersion(shadow, '.', [writer]);
const sg = shadowGit(shadow);
const tree = (await sg.raw('ls-tree', '-r', '--name-only', result.checkpointRef))
.split('\n')
.map((p) => p.trim())
.filter((p) => p.length > 0);
expect(tree).toContain('intro.md');
expect(tree).toContain('.ok/config.yml');
expect(tree.filter((p) => p.startsWith('.ok/local/'))).toEqual([]);
expect(tree.filter((p) => p.startsWith('.ok/worktrees/'))).toEqual([]);
});
test('a nested content dir keeps its own .ok/local out of the staged tree', async () => {
mkdirSync(resolve(projectRoot, 'docs/.ok/local'), { recursive: true });
writeFileSync(resolve(projectRoot, 'docs/note.md'), '# note\n');
writeFileSync(resolve(projectRoot, 'docs/.ok/local/comments.json'), '{}\n');
const result = await saveVersion(shadow, 'docs', [writer]);
const sg = shadowGit(shadow);
const tree = (await sg.raw('ls-tree', '-r', '--name-only', result.checkpointRef))
.split('\n')
.map((p) => p.trim())
.filter((p) => p.length > 0);
expect(tree).toContain('docs/note.md');
expect(tree.filter((p) => p.startsWith('docs/.ok/local/'))).toEqual([]);
});
test('legacy machine-local files at the .ok root stay out of a checkpoint', async () => {
const legacyRootFiles = [
'principal.json',
'state.json',
'server.lock',
'ui.lock',
'sync-state.json',
'conflicts.json',
'last-spawn-error.log',
];
const legacyRootDirs = ['local', 'worktrees', 'cache', 'tmp'];
for (const name of legacyRootFiles) {
writeFileSync(resolve(projectRoot, '.ok', name), '{"legacy":true}\n');
}
for (const name of legacyRootDirs) {
mkdirSync(resolve(projectRoot, '.ok', name), { recursive: true });
writeFileSync(resolve(projectRoot, '.ok', name, 'residue.json'), '{}\n');
}
const result = await saveVersion(shadow, '.', [writer]);
const sg = shadowGit(shadow);
const tree = (await sg.raw('ls-tree', '-r', '--name-only', result.checkpointRef))
.split('\n')
.map((p) => p.trim())
.filter((p) => p.length > 0);
expect(tree).toContain('.ok/config.yml');
expect(tree).toContain('intro.md');
for (const name of legacyRootFiles) {
expect(tree).not.toContain(`.ok/${name}`);
}
for (const name of legacyRootDirs) {
expect(tree.filter((p) => p.startsWith(`.ok/${name}/`))).toEqual([]);
}
});
test('an in-flight document flush is not staged into a checkpoint', async () => {
const inFlight = atomicTempPath(resolve(projectRoot, 'intro.md'));
writeFileSync(inFlight, '# half written\n');
const result = await saveVersion(shadow, '.', [writer]);
const sg = shadowGit(shadow);
const tree = (await sg.raw('ls-tree', '-r', '--name-only', result.checkpointRef))
.split('\n')
.map((p) => p.trim())
.filter((p) => p.length > 0);
expect(tree).toContain('intro.md');
expect(tree.filter((p) => p.includes('.tmp.'))).toEqual([]);
});
test('an in-flight skill write is not staged into a checkpoint', async () => {
const skillsRoot = resolve(projectRoot, '.ok/skills');
const skillFile = resolve(skillsRoot, 'trip-log/SKILL.md');
fsTracedRecorder.renameSources.length = 0;
const written = applySkillWrite({
boundary: projectRoot,
skillsRoot,
name: 'trip-log',
body: '# Steps\n\nDo the thing.',
frontmatter: { name: 'trip-log', description: 'Use when logging a fishing trip.' },
});
expect(written.ok).toBe(true);
const inFlight = fsTracedRecorder.renameSources.find((from) =>
from.startsWith(`${skillFile}.`),
);
expect(inFlight).toBeDefined();
writeFileSync(inFlight as string, '# half written\n');
const result = await saveVersion(shadow, '.', [writer]);
const sg = shadowGit(shadow);
const tree = (await sg.raw('ls-tree', '-r', '--name-only', result.checkpointRef))
.split('\n')
.map((p) => p.trim())
.filter((p) => p.length > 0);
expect(tree).toContain('.ok/skills/trip-log/SKILL.md');
expect(tree.filter((p) => p.startsWith('.ok/skills/trip-log/SKILL.md.'))).toEqual([]);
});
test('a WIP commit drops machine-local paths a previous build had staged', async () => {
const agentWriter: WriterIdentity = {
id: 'agent-cursor',
name: 'cursor-agent',
email: '[email protected]',
};
await seedStaleWipRef(shadow, agentWriter.id);
expect(await wipTreePaths(shadow, agentWriter.id)).toContain('.ok/local/principal.json');
const reinit = await initShadowRepo(projectRoot);
writeFileSync(resolve(projectRoot, 'intro.md'), '# Hello again\n');
await commitWip(reinit, agentWriter, '.', 'WIP: post-upgrade');
const freshTree = await wipTreePaths(reinit, agentWriter.id);
expect(freshTree).toContain('intro.md');
expect(freshTree.filter((p) => p.startsWith('.ok/local/'))).toEqual([]);
});
test('paths that only share a prefix with a machine-local name stay in a checkpoint', async () => {
mkdirSync(resolve(projectRoot, 'docs/.ok'), { recursive: true });
writeFileSync(resolve(projectRoot, '.ok/state.json'), '{"machine":true}\n');
writeFileSync(resolve(projectRoot, '.ok/state.jsonl'), '{"content":true}\n');
writeFileSync(resolve(projectRoot, '.ok/principal.json'), '{"machine":true}\n');
writeFileSync(resolve(projectRoot, '.ok/principal.json.bak'), '{"content":true}\n');
writeFileSync(resolve(projectRoot, 'docs/.ok/server.lock'), '{"machine":true}\n');
writeFileSync(resolve(projectRoot, 'docs/.ok/server.lock.disabled'), '{"content":true}\n');
const result = await saveVersion(shadow, '.', [writer]);
const tree = await checkpointTreePaths(result.checkpointRef);
expect(tree).toContain('.ok/state.jsonl');
expect(tree).toContain('.ok/principal.json.bak');
expect(tree).toContain('docs/.ok/server.lock.disabled');
expect(tree).not.toContain('.ok/state.json');
expect(tree).not.toContain('.ok/principal.json');
expect(tree).not.toContain('docs/.ok/server.lock');
});
test('a staged path whose name begins with a dash is still dropped', async () => {
const agentWriter: WriterIdentity = {
id: 'agent-dash',
name: 'dash-agent',
email: '[email protected]',
};
const leadingDash = `-lead.md${atomicTempPath('x').slice(1)}`;
writeFileSync(resolve(projectRoot, leadingDash), '# half written\n');
await seedStaleWipRef(shadow, agentWriter.id);
expect(await wipTreePaths(shadow, agentWriter.id)).toContain(leadingDash);
const reinit = await initShadowRepo(projectRoot);
await commitWip(reinit, agentWriter, '.', 'WIP: post-upgrade');
const freshTree = await wipTreePaths(reinit, agentWriter.id);
expect(freshTree).toContain('intro.md');
expect(freshTree).not.toContain(leadingDash);
});
test('a contaminated index larger than the argv ceiling is still repaired', async () => {
const agentWriter: WriterIdentity = {
id: 'agent-bulk',
name: 'bulk-agent',
email: '[email protected]',
};
const leaf = 'q'.repeat(160);
const threadsDir = resolve(projectRoot, '.ok/local/threads');
mkdirSync(threadsDir, { recursive: true });
const bulk = Array.from(
{ length: 8_000 },
(_unused, i) => `${String(i).padStart(6, '0')}-${leaf}.ndjson`,
);
for (const name of bulk) writeFileSync(resolve(threadsDir, name), '{}\n');
const argvBytes = bulk.reduce((acc, name) => acc + `.ok/local/threads/${name}`.length + 1, 0);
expect(argvBytes).toBeGreaterThan(1_500_000);
await seedStaleWipRef(shadow, agentWriter.id);
const staleTree = await wipTreePaths(shadow, agentWriter.id);
expect(staleTree.filter((p) => p.startsWith('.ok/local/threads/'))).toHaveLength(8_000);
const reinit = await initShadowRepo(projectRoot);
await commitWip(reinit, agentWriter, '.', 'WIP: post-upgrade');
const freshTree = await wipTreePaths(reinit, agentWriter.id);
expect(freshTree).toContain('intro.md');
expect(freshTree.filter((p) => p.startsWith('.ok/local/'))).toEqual([]);
}, 120_000);
test('a repair the index sweep cannot run does not abort initialization, but degrades the shadow', async () => {
writeFileSync(resolve(shadow.gitDir, FANOUT_INDEX_NAME), 'GARBAGE-NOT-AN-INDEX-FILE');
resetMetrics();
const warnSpy = vi.spyOn(getLogger('shadow-repo'), 'warn');
try {
const reinit = await initShadowRepo(projectRoot);
expect(existsSync(resolve(reinit.gitDir, 'info/exclude'))).toBe(true);
expect(isShadowExcludesDegraded(reinit)).toBe(true);
expect(getMetrics().shadowExcludeIndexSweepFailures).toBe(1);
expect(getMetrics().shadowExcludeIndexEntriesDropped).toBe(0);
const warnings = warnSpy.mock.calls.map((call) => String(call[1] ?? ''));
expect(
warnings.some((message) =>
message.includes(
'[shadow-repo] could not read the index to clear excluded entries — none were dropped and an unknown number are still staged',
),
),
).toBe(true);
} finally {
warnSpy.mockRestore();
}
});
test('an index sweep blocked partway reports how many machine-local entries it left staged', async () => {
const fanoutIndex = seedStaleFanoutIndex(shadow);
const machineLocalStaged = indexPaths(shadow, fanoutIndex).filter(
(path) => path.startsWith('.ok/local/') || path.startsWith('.ok/worktrees/'),
);
expect(machineLocalStaged.length).toBeGreaterThan(0);
writeFileSync(`${fanoutIndex}.lock`, '');
resetMetrics();
const warnSpy = vi.spyOn(getLogger('shadow-repo'), 'warn');
const infoSpy = vi.spyOn(getLogger('shadow-repo'), 'info');
try {
const reinit = await initShadowRepo(projectRoot);
expect(isShadowExcludesDegraded(reinit)).toBe(true);
expect(getMetrics().shadowExcludeIndexSweepFailures).toBe(1);
expect(getMetrics().shadowExcludeIndexEntriesDropped).toBe(0);
expect(
indexPaths(reinit, fanoutIndex).filter(
(path) => path.startsWith('.ok/local/') || path.startsWith('.ok/worktrees/'),
),
).toEqual(machineLocalStaged);
const warnings = warnSpy.mock.calls.map((call) => String(call[1] ?? ''));
expect(
warnings.some((message) =>
message.includes(`dropped 0, left ${machineLocalStaged.length} still staged`),
),
).toBe(true);
const infos = infoSpy.mock.calls.map((call) => String(call[1] ?? ''));
expect(
infos.some((message) =>
message.includes('[shadow-repo] dropped excluded entries a previous build had staged'),
),
).toBe(false);
} finally {
warnSpy.mockRestore();
infoSpy.mockRestore();
}
});
test('a checkpoint stays clean even when the shadow exclude file is gone', async () => {
writeFileSync(resolve(shadow.gitDir, 'info/exclude'), STOCK_GIT_EXCLUDE);
const result = await saveVersion(shadow, '.', [writer]);
const tree = await checkpointTreePaths(result.checkpointRef);
expect(tree).toContain('intro.md');
expect(tree).toContain('.ok/config.yml');
expect(tree.filter((p) => p.startsWith('.ok/local/'))).toEqual([]);
expect(tree.filter((p) => p.startsWith('.ok/worktrees/'))).toEqual([]);
});
test('a shadow whose exclude file cannot be written reports itself degraded', async () => {
const excludeFile = resolve(shadow.gitDir, 'info/exclude');
rmSync(excludeFile, { force: true });
symlinkSync(resolve(tmpDir, 'planted-exclude'), excludeFile);
const reinit = await initShadowRepo(projectRoot);
expect(isShadowExcludesDegraded(reinit)).toBe(true);
});
test('a symlink at the exclude path is refused at error level, not warned as I/O', async () => {
const excludeFile = resolve(shadow.gitDir, 'info/exclude');
rmSync(excludeFile, { force: true });
symlinkSync(resolve(tmpDir, 'planted-exclude'), excludeFile);
const errorSpy = vi.spyOn(getLogger('shadow-repo'), 'error');
const warnSpy = vi.spyOn(getLogger('shadow-repo'), 'warn');
try {
await initShadowRepo(projectRoot);
const errors = errorSpy.mock.calls.map((call) => String(call[1] ?? ''));
const warnings = warnSpy.mock.calls.map((call) => String(call[1] ?? ''));
expect(
errors.some((message) =>
message.includes('[shadow-repo] refused to write the shadow exclude file'),
),
).toBe(true);
expect(
warnings.some((message) =>
message.includes('[shadow-repo] could not write the shadow exclude file'),
),
).toBe(false);
} finally {
errorSpy.mockRestore();
warnSpy.mockRestore();
}
});
test('a symlinked shadow info directory pointing at a live directory is refused, not followed', async () => {
const infoDir = resolve(shadow.gitDir, 'info');
const plantedInfo = resolve(tmpDir, 'planted-info-live');
mkdirSync(plantedInfo, { recursive: true });
rmSync(infoDir, { recursive: true, force: true });
symlinkSync(plantedInfo, infoDir);
const errorSpy = vi.spyOn(getLogger('shadow-repo'), 'error');
const warnSpy = vi.spyOn(getLogger('shadow-repo'), 'warn');
try {
const reinit = await initShadowRepo(projectRoot);
expect(isShadowExcludesDegraded(reinit)).toBe(true);
expect(existsSync(resolve(plantedInfo, 'exclude'))).toBe(false);
const errors = errorSpy.mock.calls.map((call) => String(call[1] ?? ''));
const warnings = warnSpy.mock.calls.map((call) => String(call[1] ?? ''));
expect(
errors.some((message) =>
message.includes('[shadow-repo] refused to write the shadow exclude file'),
),
).toBe(true);
expect(
warnings.some((message) =>
message.includes('[shadow-repo] could not write the shadow exclude file'),
),
).toBe(false);
} finally {
errorSpy.mockRestore();
warnSpy.mockRestore();
}
});
test('a dangling symlink at the shadow info directory is refused, not warned as I/O', async () => {
const infoDir = resolve(shadow.gitDir, 'info');
rmSync(infoDir, { recursive: true, force: true });
symlinkSync(resolve(tmpDir, 'planted-info-absent'), infoDir);
const errorSpy = vi.spyOn(getLogger('shadow-repo'), 'error');
const warnSpy = vi.spyOn(getLogger('shadow-repo'), 'warn');
try {
const reinit = await initShadowRepo(projectRoot);
expect(isShadowExcludesDegraded(reinit)).toBe(true);
const errors = errorSpy.mock.calls.map((call) => String(call[1] ?? ''));
const warnings = warnSpy.mock.calls.map((call) => String(call[1] ?? ''));
expect(
errors.some((message) =>
message.includes('[shadow-repo] refused to write the shadow exclude file'),
),
).toBe(true);
expect(
warnings.some((message) =>
message.includes('[shadow-repo] could not write the shadow exclude file'),
),
).toBe(false);
} finally {
errorSpy.mockRestore();
warnSpy.mockRestore();
}
});
test('the index repair reports its drop count through the metrics surface', async () => {
const agentWriter: WriterIdentity = {
id: 'agent-metrics',
name: 'metrics-agent',
email: '[email protected]',
};
await seedStaleWipRef(shadow, agentWriter.id);
const reinit = await initShadowRepo(projectRoot);
resetMetrics();
await commitWip(reinit, agentWriter, '.', 'WIP: post-upgrade');
expect(getMetrics().shadowExcludeIndexEntriesDropped).toBeGreaterThan(0);
});
test('re-initializing drops a fan-out index that already staged machine-local state', async () => {
const fanoutIndex = seedStaleFanoutIndex(shadow);
expect(indexPaths(shadow, fanoutIndex)).toContain('.ok/local/principal.json');
const reinit = await initShadowRepo(projectRoot);
const freshTree = await buildWipTree(reinit, '.');
const sgFresh = shadowGit(reinit);
const freshNames = (await sgFresh.raw('ls-tree', '-r', '--name-only', freshTree))
.split('\n')
.map((p) => p.trim())
.filter((p) => p.length > 0);
expect(freshNames).toContain('intro.md');
expect(freshNames.filter((p) => p.startsWith('.ok/local/'))).toEqual([]);
});
test('a fan-out WIP tree stays clean even when the shadow exclude file is gone', async () => {
writeFileSync(resolve(shadow.gitDir, 'info/exclude'), STOCK_GIT_EXCLUDE);
const tree = await buildWipTree(shadow, '.');
const names = await checkpointTreePaths(tree);
expect(names).toContain('intro.md');
expect(names.filter((p) => p.startsWith('.ok/local/'))).toEqual([]);
expect(names.filter((p) => p.startsWith('.ok/worktrees/'))).toEqual([]);
});
test('re-initializing an existing shadow restores the exclusions', async () => {
writeFileSync(resolve(shadow.gitDir, 'info/exclude'), STOCK_GIT_EXCLUDE);
const reinit = await initShadowRepo(projectRoot);
const sg = shadowGit(reinit);
const status = await sg.raw('status', '--porcelain', '--untracked-files=all');
expect(status).not.toContain('.ok/local/');
});
});
describe('shadow repo excludes a git dir that lives inside the work tree under another name', () => {
let projectRoot: string;
let shadow: ShadowHandle;
const writer: WriterIdentity = {
id: 'human-ada',
name: 'Ada Lovelace',
email: '[email protected]',
};
function treePaths(handle: ShadowHandle, ref: string): string[] {
return execFileSync('git', ['ls-tree', '-r', '--name-only', ref], {
cwd: handle.workTree,
env: { ...process.env, GIT_DIR: handle.gitDir },
encoding: 'utf-8',
})
.split('\n')
.map((path) => path.trim())
.filter((path) => path.length > 0);
}
beforeEach(async () => {
projectRoot = resolve(tmpDir, 'project');
mkdirSync(projectRoot, { recursive: true });
const git = simpleGit(projectRoot);
await git.init();
await git.raw('config', 'user.name', 'Test');
await git.raw('config', 'user.email', '[email protected]');
execFileSync('mv', ['.git', '.git.nosync'], { cwd: projectRoot });
symlinkSync('.git.nosync', resolve(projectRoot, '.git'));
writeFileSync(resolve(projectRoot, 'intro.md'), '# Hello\n');
shadow = await initShadowRepo(projectRoot);
});
test('derives anchored excludes for the symlink target and the shadow dir', () => {
expect(gitDirExcludePatterns(shadow)).toEqual(['/.git.nosync/', '/.git.nosync/ok/']);
const exclude = readFileSync(resolve(shadow.gitDir, 'info/exclude'), 'utf-8');
expect(exclude).toContain('/.git.nosync/\n');
});
test('a regular .git directory needs no extra excludes', async () => {
const plainRoot = resolve(tmpDir, 'plain');
mkdirSync(plainRoot, { recursive: true });
await simpleGit(plainRoot).init();
const plainShadow = await initShadowRepo(plainRoot);
expect(gitDirExcludePatterns(plainShadow)).toEqual([]);
});
test('WIP commits never stage the shadow repo or the project git dir', async () => {
await commitWip(shadow, writer, '.', 'WIP: first');
writeFileSync(resolve(projectRoot, 'intro.md'), '# Hello again\n');
await commitWip(shadow, writer, '.', 'WIP: second');
const paths = treePaths(shadow, `refs/wip/main/${writer.id}`);
expect(paths).toContain('intro.md');
expect(paths.filter((path) => path.startsWith('.git.nosync/'))).toEqual([]);
});
test('the fan-out tree never stages the shadow repo or the project git dir', async () => {
await commitWip(shadow, writer, '.', 'WIP: seed objects');
const tree = await buildWipTree(shadow, '.');
const paths = treePaths(shadow, tree);
expect(paths).toContain('intro.md');
expect(paths.filter((path) => path.startsWith('.git.nosync/'))).toEqual([]);
});
test('a fan-out index that already staged the git dir is swept on the next build', async () => {
const fanoutIndex = resolve(shadow.gitDir, FANOUT_INDEX_NAME);
const excludeFile = resolve(shadow.gitDir, 'info/exclude');
const realExclude = readFileSync(excludeFile, 'utf-8');
writeFileSync(excludeFile, '');
try {
execFileSync('git', ['add', '-A', '.'], {
cwd: shadow.workTree,
env: {
...process.env,
GIT_DIR: shadow.gitDir,
GIT_WORK_TREE: shadow.workTree,
GIT_INDEX_FILE: fanoutIndex,
},
});
} finally {
writeFileSync(excludeFile, realExclude);
}
const tree = await buildWipTree(shadow, '.');
expect(treePaths(shadow, tree).filter((path) => path.startsWith('.git.nosync/'))).toEqual([]);
});
test('a git dir reached through a `.git` pointer file is fully excluded from staging', async () => {
const pointerRoot = resolve(tmpDir, 'pointer-project');
mkdirSync(pointerRoot, { recursive: true });
const gitData = resolve(pointerRoot, '.gitdata');
execFileSync('git', ['init', `--separate-git-dir=${gitData}`, pointerRoot]);
execFileSync('git', ['config', 'user.name', 'Test'], {
cwd: pointerRoot,
env: { ...process.env, GIT_DIR: gitData },
});
execFileSync('git', ['config', 'user.email', '[email protected]'], {
cwd: pointerRoot,
env: { ...process.env, GIT_DIR: gitData },
});
writeFileSync(resolve(pointerRoot, 'intro.md'), '# Hello\n');
const pointerShadow = await initShadowRepo(pointerRoot);
expect(gitDirExcludePatterns(pointerShadow)).toEqual(['/.gitdata/', '/.gitdata/ok/']);
await commitWip(pointerShadow, writer, '.', 'WIP: pointer');
const paths = treePaths(pointerShadow, `refs/wip/main/${writer.id}`);
expect(paths).toContain('intro.md');
expect(paths.filter((path) => path.startsWith('.gitdata/'))).toEqual([]);
});
test('a git dir that resolves outside the work tree contributes no excludes', async () => {
const externalRoot = resolve(tmpDir, 'external-project');
mkdirSync(externalRoot, { recursive: true });
const externalGitDir = resolve(tmpDir, 'external-store');
execFileSync('git', ['init', `--separate-git-dir=${externalGitDir}`, externalRoot]);
execFileSync('git', ['config', 'user.name', 'Test'], {
cwd: externalRoot,
env: { ...process.env, GIT_DIR: externalGitDir },
});
execFileSync('git', ['config', 'user.email', '[email protected]'], {
cwd: externalRoot,
env: { ...process.env, GIT_DIR: externalGitDir },
});
writeFileSync(resolve(externalRoot, 'intro.md'), '# Hello\n');
const externalShadow = await initShadowRepo(externalRoot);
expect(gitDirExcludePatterns(externalShadow)).toEqual([]);
const exclude = readFileSync(resolve(externalShadow.gitDir, 'info/exclude'), 'utf-8');
expect(exclude).not.toContain('/../');
});
test('a git dir named with a glob metacharacter still lets other content stage', async () => {
const metaRoot = resolve(tmpDir, 'meta-project');
mkdirSync(metaRoot, { recursive: true });
const git = simpleGit(metaRoot);
await git.init();
await git.raw('config', 'user.name', 'Test');
await git.raw('config', 'user.email', '[email protected]');
execFileSync('mv', ['.git', '*'], { cwd: metaRoot });
symlinkSync('*', resolve(metaRoot, '.git'));
mkdirSync(resolve(metaRoot, 'docs'), { recursive: true });
writeFileSync(resolve(metaRoot, 'docs/note.md'), '# Note\n');
writeFileSync(resolve(metaRoot, 'intro.md'), '# Hello\n');
const metaShadow = await initShadowRepo(metaRoot);
expect(gitDirExcludePatterns(metaShadow)).toEqual(['/\\*/', '/\\*/ok/']);
await commitWip(metaShadow, writer, '.', 'WIP: meta');
const paths = treePaths(metaShadow, `refs/wip/main/${writer.id}`);
expect(paths).toContain('docs/note.md');
expect(paths).toContain('intro.md');
expect(paths.some((path) => path.startsWith('*/'))).toBe(false);
});
test('a git dir name containing a newline is skipped, not written as a broken pattern', async () => {
const nlRoot = resolve(tmpDir, 'newline-project');
mkdirSync(nlRoot, { recursive: true });
const git = simpleGit(nlRoot);
await git.init();
await git.raw('config', 'user.name', 'Test');
await git.raw('config', 'user.email', '[email protected]');
const weird = 'git\nweird';
execFileSync('mv', ['.git', weird], { cwd: nlRoot });
symlinkSync(weird, resolve(nlRoot, '.git'));
writeFileSync(resolve(nlRoot, 'intro.md'), '# Hello\n');
const nlShadow = await initShadowRepo(nlRoot);
expect(gitDirExcludePatterns(nlShadow)).toEqual([]);
});
});