projectkeeper 0.0.0-stage → 1.0.0

package/src/sources/watch.ts

@@ -0,0 +1,215 @@
+/**
+ * Watch the scope for change (Spec §3.2): files in included directories, native session logs
+ * for the scoped working directories, and repository heads. Changes are reported as pending
+ * material; a piece of work counts as "settled" after a quiet period so active writing is
+ * gathered instead of re-done on every keystroke. The rhythm parameters are execution-layer
+ * knobs (D31), not product premises.
+ */
+import { EventEmitter } from 'node:events';
+import { existsSync, statSync, watch, type FSWatcher } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import type { PendingMaterial, Project, ScopeItem } from '../model/types.ts';
+import { isWithin, nameForm, normalizePath, pathKey, relativeDisplay } from '../util/paths.ts';
+import { gitHead } from '../util/git.ts';
+import { claudeSessionFolders, codexSessionRoots, cwdMatcher, readCodexSessionHeader } from './sessions/locate.ts';
+import { sessionItemForCwd, sessionStoreRootOf } from './sessions/scope.ts';
+import { isDocumentPath, isReadRoot, overridesIgnoreRules, readingOf, skippedSegment, treatmentOf } from '../scope/skip.ts';
+import { isIgnored } from '../scope/ignore.ts';
+import { ignoredPlaceOf } from '../scope/ignored-place.ts';
+
+export interface WatchSettings {
+  /** A file whose last change is older than this is considered settled. */
+  readonly fileQuietMs: number;
+  /** A session log whose last growth is older than this is considered settled. */
+  readonly sessionQuietMs: number;
+  /** How often to poll repository heads and re-check quiet periods. */
+  readonly pollMs: number;
+}
+export const DEFAULT_WATCH: WatchSettings = { fileQuietMs: 45_000, sessionQuietMs: 4 * 60_000, pollMs: 15_000 };
+
+export interface PendingChange extends PendingMaterial {
+  readonly lastEventAt: number;
+  readonly scopeItemId: string;
+}
+
+/** Repositories and worktrees whose new commits are the project's (not a vendored library's upstream history). */
+const committing = (scope: readonly ScopeItem[]) => scope.filter((i) => (i.category === 'Repository' || i.category === 'Worktree') && isReadRoot(scope, i) && ['read', 'changes'].includes(treatmentOf(i)));
+
+export class ScopeWatcher extends EventEmitter {
+  private readonly watchers: FSWatcher[] = [];
+  private readonly pending = new Map<string, PendingChange>();
+  private readonly heads = new Map<string, string | null>();
+  /** What git's ignore rules said about a file already seen (the check runs once per path). */
+  private readonly ignoredCache = new Map<string, boolean>();
+  /** Whether a scope item lies in a place a repository around it ignores (asked once per item between starts). */
+  private readonly placeCache = new Map<string, boolean>();
+  private keep = new Set<string>();
+  private timer: NodeJS.Timeout | null = null;
+  private readonly settings: WatchSettings;
+  private project: Project;
+
+  constructor(project: Project, settings: Partial<WatchSettings> = {}) {
+    super();
+    this.project = project;
+    this.settings = { ...DEFAULT_WATCH, ...settings };
+  }
+
+  /**
+   * The scope item a changed file belongs to, when the scan would read it (Spec §1.1): not what the one skip list or
+   * the project's ignore rules leave out, not generated output, only documents of third-party material, and nothing
+   * under a location that is left out. Nor a file of a location that itself lies where a repository around it ignores —
+   * a worktree under an ignored directory (D105): its working files are no change to take in; its commits are polled.
+   */
+  private accept(file: string): ScopeItem | null {
+    const scope = this.project.scope;
+    const { item, treatment } = readingOf(scope, file);
+    if (!item || treatment === 'none' || !isReadRoot(scope, item)) return null;
+    const rel = relativeDisplay(item.path, file);
+    if (skippedSegment(rel) !== null) return null;
+    if (treatment === 'documents' && !isDocumentPath(file)) return null;
+    let inIgnoredPlace = this.placeCache.get(item.id);
+    if (inIgnoredPlace === undefined) { inIgnoredPlace = ignoredPlaceOf(scope, item) !== null; this.placeCache.set(item.id, inIgnoredPlace); }
+    if (inIgnoredPlace) return null;
+    if (item.versionControl !== 'none' && !overridesIgnoreRules(scope, item) && !this.keep.has(pathKey(file))) {
+      const key = pathKey(file);
+      let ignored = this.ignoredCache.get(key);
+      if (ignored === undefined) { ignored = isIgnored(item.path, rel); this.ignoredCache.set(key, ignored); }
+      if (ignored) return null;
+    }
+    return item;
+  }
+
+  start(): void {
+    this.stop();
+    const p = this.project;
+    this.ignoredCache.clear();
+    this.placeCache.clear();
+    this.keep = new Set(p.scope.filter((i) => i.relation !== 'Excluded' && i.ignoredBy?.paths).flatMap((i) => (i.ignoredBy!.paths ?? []).map((f) => pathKey(join(dirname(i.path), f.split('/').pop()!)))));
+    const roots = p.scope.filter((i) => i.category !== 'Session source' && isReadRoot(p.scope, i));
+    // One recursive watch per outermost location; each change is attributed to the deepest item that holds it (CKC-07 AC-1).
+    const outer = roots.filter((r) => !roots.some((o) => o !== r && isWithin(o.path, r.path) && pathKey(o.path) !== pathKey(r.path)));
+    for (const root of outer) {
+      this.watchDir(root.path, (file) => {
+        const owner = this.accept(file);
+        if (!owner) return;
+        this.note({ kind: 'file', ref: file, label: file, since: new Date().toISOString(), lastEventAt: Date.now(), scopeItemId: owner.id });
+      });
+    }
+    for (const repo of committing(p.scope)) {
+      this.heads.set(repo.id, gitHead(repo.path));
+    }
+    // Session logs: Claude's per-project directory and both Codex homes.
+    const cwds = new Set<string>();
+    for (const item of roots) cwds.add(item.path);
+    for (const item of p.scope) if (item.copyOf) cwds.add(item.copyOf);
+    const home = homedir();
+    /** The directories whose sessions one host keeps in the same native home, home by home. */
+    const byHome = (host: 'claude' | 'codex'): { home: string; cwds: string[] }[] => {
+      const groups = new Map<string, { home: string; cwds: string[] }>();
+      for (const cwd of cwds) {
+        const selected = sessionStoreRootOf(p.scope, host, cwd, home);
+        const key = pathKey(selected);
+        const group = groups.get(key) ?? { home: selected, cwds: [] };
+        group.cwds.push(cwd);
+        groups.set(key, group);
+      }
+      return [...groups.values()];
+    };
+    for (const group of byHome('claude')) {
+      // The folder named after the directory, and any named after another spelling of it (through a junction, say).
+      for (const { dir, cwd } of claudeSessionFolders(group.cwds, group.home)) {
+        // The full normalised path is the identity. A substring lets D:\x steal events from D:\x-y, depending on order.
+        const item = sessionItemForCwd(p.scope, 'claude', cwd);
+        // Removing a discovered session source records an owner exclusion. Keep watching a cwd with no item so its
+        // first new session is still caught, but an item the owner explicitly excluded stays quiet.
+        if (item?.relation === 'Excluded') continue;
+        this.watchDir(dir, (file) => {
+          if (!file.endsWith('.jsonl')) return;
+          this.note({ kind: 'session', ref: file, label: `Claude Code session ${file.split(/[\\/]/).pop()}`, since: new Date().toISOString(), lastEventAt: Date.now(), scopeItemId: item?.id ?? '' });
+        });
+      }
+    }
+    for (const group of byHome('codex')) {
+      const matched = cwdMatcher(group.cwds);
+      for (const rootDir of codexSessionRoots(group.home)) {
+        this.watchDir(rootDir, (file) => {
+          if (!file.endsWith('.jsonl')) return;
+          // A native home can contain every project. Only the header's complete cwd selects its session source: one of
+          // these directories, in whatever spelling the log records it.
+          const header = readCodexSessionHeader(file);
+          const cwd = header ? matched(header.cwd) : null;
+          if (!cwd) return;
+          const item = sessionItemForCwd(p.scope, 'codex', cwd);
+          if (item?.relation === 'Excluded') return;
+          this.note({ kind: 'session', ref: file, label: `Codex session ${file.split(/[\\/]/).pop()}`, since: new Date().toISOString(), lastEventAt: Date.now(), scopeItemId: item?.id ?? '' });
+        });
+      }
+    }
+    this.timer = setInterval(() => this.poll(), this.settings.pollMs);
+    this.timer.unref?.();
+  }
+
+  update(project: Project): void {
+    this.project = project;
+    this.start();
+  }
+
+  stop(): void {
+    for (const w of this.watchers) { try { w.close(); } catch { /* ignore */ } }
+    this.watchers.length = 0;
+    if (this.timer) { clearInterval(this.timer); this.timer = null; }
+  }
+
+  private watchDir(dir: string, onFile: (file: string) => void): void {
+    try {
+      const w = watch(dir, { recursive: true, persistent: false }, (_event, filename) => {
+        if (!filename) return;
+        const file = normalizePath(join(dir, nameForm(String(filename))));
+        onFile(file);
+      });
+      w.on('error', () => { /* a vanished directory just stops being watched */ });
+      this.watchers.push(w);
+    } catch (error) {
+      this.emit('warning', `Cannot watch ${dir}: ${(error as Error).message}`);
+    }
+  }
+
+  private note(change: PendingChange): void {
+    const key = `${change.kind}:${pathKey(change.ref)}`;
+    const existing = this.pending.get(key);
+    this.pending.set(key, existing ? { ...existing, lastEventAt: change.lastEventAt } : change);
+    this.emit('pending', this.list());
+  }
+
+  /** Everything seen changed and not yet handed to organizing. */
+  list(): PendingChange[] { return [...this.pending.values()]; }
+
+  /** Changes whose quiet period has passed: work that has settled (§3.2). */
+  settled(now = Date.now()): PendingChange[] {
+    return this.list().filter((c) => {
+      const quiet = c.kind === 'session' ? this.settings.sessionQuietMs : this.settings.fileQuietMs;
+      return now - c.lastEventAt >= quiet;
+    });
+  }
+
+  take(changes: readonly PendingChange[]): void {
+    for (const c of changes) this.pending.delete(`${c.kind}:${pathKey(c.ref)}`);
+  }
+
+  private poll(): void {
+    for (const repo of committing(this.project.scope)) {
+      const head = gitHead(repo.path);
+      if (head !== this.heads.get(repo.id)) {
+        this.heads.set(repo.id, head);
+        this.note({ kind: 'commit', ref: `${repo.path}@${head ?? 'none'}`, label: `${repo.path.split(/[\\/]/).pop()} head → ${head?.slice(0, 8) ?? 'none'}`, since: new Date().toISOString(), lastEventAt: 0, scopeItemId: repo.id });
+      }
+    }
+    const settled = this.settled();
+    if (settled.length > 0) this.emit('settled', settled);
+    for (const c of this.list()) {
+      if (c.kind === 'file' && !existsSync(c.ref)) continue;
+      if (c.kind === 'file') { try { const st = statSync(c.ref); if (st.mtimeMs > c.lastEventAt) this.note({ ...c, lastEventAt: st.mtimeMs }); } catch { /* removed */ } }
+    }
+  }
+}

package/src/store/json-file.ts

@@ -0,0 +1,50 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+
+export function readJson<T>(path: string, fallback: T): T {
+  if (!existsSync(path)) return fallback;
+  try {
+    return JSON.parse(readFileSync(path, 'utf8')) as T;
+  } catch {
+    // A corrupt file is kept next to the fresh one instead of being silently overwritten.
+    try { renameSync(path, `${path}.corrupt-${Date.now()}`); } catch { /* keep going */ }
+    return fallback;
+  }
+}
+
+/** `mode`: the file's permissions on macOS and Linux when it must not be readable by other accounts (not used on Windows). */
+export function writeJsonAtomic(path: string, value: unknown, mode?: number): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const temp = join(dirname(path), `.${randomBytes(6).toString('hex')}.tmp`);
+  writeFileSync(temp, JSON.stringify(value, null, 1), { encoding: 'utf8', flag: 'wx', ...(mode === undefined ? {} : { mode }) });
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      renameSync(temp, path);
+      return;
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      if (attempt >= 5 || !['EPERM', 'EBUSY', 'EACCES'].includes(code ?? '')) {
+        try { unlinkSync(temp); } catch { /* nothing else to do */ }
+        throw error;
+      }
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20 * (attempt + 1));
+    }
+  }
+}
+
+export function appendJsonLine(path: string, value: unknown): void {
+  mkdirSync(dirname(path), { recursive: true });
+  appendFileSync(path, `${JSON.stringify(value)}\n`, 'utf8');
+}
+
+export function readJsonLines<T>(path: string, limit = Infinity): T[] {
+  if (!existsSync(path)) return [];
+  const lines = readFileSync(path, 'utf8').split('\n').filter((l) => l.trim());
+  const slice = Number.isFinite(limit) ? lines.slice(-limit) : lines;
+  const out: T[] = [];
+  for (const line of slice) {
+    try { out.push(JSON.parse(line) as T); } catch { /* skip broken line */ }
+  }
+  return out;
+}

package/src/store/paths.ts

@@ -0,0 +1,39 @@
+import { existsSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { canonicalPath } from '../util/paths.ts';
+
+/** ProjectKeeper's own home, in the file system's own spelling. Tests point `PROJECTKEEPER_HOME` at a temporary directory. */
+export function projectKeeperHome(): string {
+  const override = process.env.PROJECTKEEPER_HOME;
+  return canonicalPath(override && override.trim() ? override : join(homedir(), '.projectkeeper'));
+}
+
+/**
+ * The home, made if it is not there — for its owner alone (0700) on macOS and Linux, where a new directory is otherwise
+ * open to every account of the machine: it holds the saved keys and what was read of the projects. A home that exists
+ * is left as it is; its owner may have placed it and shared it on purpose. On Windows the profile's own access rules
+ * cover it and the mode is not used.
+ */
+export function ensureHome(home: string): void {
+  if (!existsSync(home)) mkdirSync(home, { recursive: true, mode: 0o700 });
+}
+
+export function workspaceFile(home = projectKeeperHome()): string {
+  return join(home, 'workspace.json');
+}
+
+export function projectDir(projectId: string, home = projectKeeperHome()): string {
+  return join(home, 'projects', projectId);
+}
+
+/**
+ * D107: the folder, inside a project's directory here, that holds what a takeover by the table leaves — the session
+ * material, the takeover's work folders and, for a public project, the table with its own git history. Clearing the
+ * project keeps it (project-store.ts `clearAll`).
+ */
+export const TABLE_FOLDER = 'table';
+
+export function tableDir(projectId: string, home = projectKeeperHome()): string {
+  return join(projectDir(projectId, home), TABLE_FOLDER);
+}

package/src/store/project-store.ts

@@ -0,0 +1,295 @@
+/**
+ * Per-project asset store (Spec §8.5). One JSON file per collection under
+ * `~/.projectkeeper/projects/<id>/`, written atomically and debounced; `trace.jsonl` records
+ * every write with its basis so the owner can ask "why do you think so" (§3.10).
+ *
+ * The store emits `change` events ({collection, ids}) that the server forwards to open views.
+ */
+import { EventEmitter } from 'node:events';
+import { existsSync, mkdirSync, readdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import type {
+  AreaUnderstanding, Authorization, ChangeRecord, ContextPackage, Coverage, EntryMark, FactRecord,
+  FollowUpRound, GraphNode, GraphRelation, JudgementRecord, KeeperJob, MergeRecord, ModificationRequest, Note,
+  ObjectJudgement, OrganizingPlan, ProjectRule, ReferenceItem, ScopeJudgement, Source, TraceEntry, WorkThread,
+} from '../model/types.ts';
+import type {
+  Breakpoint, ClerkRound, CodeTerritory, Generation, KeeperNumber, LayerEntry, ProcessLink, RoundDoc, SemanticPatch, SendBack, SessionDraft,
+} from '../model/k-types.ts';
+import { appendJsonLine, readJson, readJsonLines, writeJsonAtomic } from './json-file.ts';
+import { ensureHome, projectKeeperHome, projectDir, TABLE_FOLDER } from './paths.ts';
+
+export interface TraceInfo {
+  readonly jobId: string | null;
+  readonly basisSourceIds?: readonly string[];
+  readonly summary: string;
+}
+
+export interface Identified { readonly id: string }
+
+export class Collection<T extends Identified> {
+  readonly name: string;
+  private readonly items = new Map<string, T>();
+  private readonly store: ProjectStore;
+
+  constructor(name: string, store: ProjectStore, initial: readonly T[]) {
+    this.name = name;
+    this.store = store;
+    for (const item of initial) this.items.set(item.id, item);
+  }
+
+  all(): T[] { return [...this.items.values()]; }
+  get(id: string): T | undefined { return this.items.get(id); }
+  has(id: string): boolean { return this.items.has(id); }
+  get size(): number { return this.items.size; }
+  find(predicate: (item: T) => boolean): T | undefined {
+    for (const item of this.items.values()) if (predicate(item)) return item;
+    return undefined;
+  }
+  filter(predicate: (item: T) => boolean): T[] { return this.all().filter(predicate); }
+
+  put(item: T, trace?: TraceInfo): T {
+    this.items.set(item.id, item);
+    this.store.markDirty(this.name, [item.id]);
+    if (trace) this.store.trace({ collection: this.name, id: item.id, op: 'put', ...trace });
+    return item;
+  }
+
+  putMany(items: readonly T[], trace?: TraceInfo): void {
+    if (items.length === 0) return;
+    for (const item of items) this.items.set(item.id, item);
+    this.store.markDirty(this.name, items.map((i) => i.id));
+    if (trace) for (const item of items) this.store.trace({ collection: this.name, id: item.id, op: 'put', ...trace });
+  }
+
+  remove(id: string, trace?: TraceInfo): boolean {
+    const existed = this.items.delete(id);
+    if (existed) {
+      this.store.markDirty(this.name, [id]);
+      if (trace) this.store.trace({ collection: this.name, id, op: 'remove', ...trace });
+    }
+    return existed;
+  }
+
+  snapshot(): T[] { return this.all(); }
+
+  /** Forget every item, without writing or tracing: the store's `clearAll` removes the files and tells the views. */
+  drop(): void { this.items.clear(); }
+}
+
+export interface ChangeEvent {
+  readonly projectId: string;
+  readonly collection: string;
+  readonly ids: readonly string[];
+}
+
+const COLLECTIONS = [
+  'sources', 'facts', 'threads', 'areas', 'reference', 'nodes', 'relations', 'notes', 'changes',
+  'marks', 'judgements', 'jobs', 'authorizations', 'requests', 'contexts', 'propagation', 'rounds',
+  'rules', 'plans', 'merges', 'scopeJudgements',
+  // Increment K (Spec v3.0): the clerk method's positions and markers.
+  'breakpoints', 'sendbacks', 'patches', 'numbers', 'drafts', 'territories', 'generations', 'layers', 'roundDocs', 'links', 'clerkRounds',
+] as const;
+export type CollectionName = (typeof COLLECTIONS)[number];
+
+function emptyCoverage(projectId: string): Coverage {
+  return {
+    // A project with no assets has not been organized (Spec §1.11, §6.14; D105).
+    projectId, state: 'Not organized yet', scopes: [], missingSourceKinds: [], processedByKind: {},
+    pendingByKind: {}, updatedAt: new Date().toISOString(),
+  };
+}
+
+export class ProjectStore extends EventEmitter {
+  readonly projectId: string;
+  readonly dir: string;
+  readonly sources: Collection<Source>;
+  readonly facts: Collection<FactRecord>;
+  readonly threads: Collection<WorkThread>;
+  readonly areas: Collection<AreaUnderstanding>;
+  readonly reference: Collection<ReferenceItem>;
+  readonly nodes: Collection<GraphNode>;
+  readonly relations: Collection<GraphRelation>;
+  readonly notes: Collection<Note>;
+  readonly changes: Collection<ChangeRecord>;
+  readonly marks: Collection<EntryMark>;
+  readonly judgements: Collection<JudgementRecord>;
+  readonly jobs: Collection<KeeperJob>;
+  readonly authorizations: Collection<Authorization>;
+  readonly requests: Collection<ModificationRequest>;
+  readonly contexts: Collection<ContextPackage>;
+  /** §2.10 one judgement per object per round; the entries inside the change records follow from these. */
+  readonly propagation: Collection<ObjectJudgement>;
+  /** §5.5 one round of Follow up, with its one result. */
+  readonly rounds: Collection<FollowUpRound>;
+  /** §1.15 the rules the project set for itself: about its material, and about how it works (D62, D64). */
+  readonly rules: Collection<ProjectRule>;
+  /** §3.7 the plan and focus of the organizing after the framing round (D62); one per project. */
+  readonly plans: Collection<OrganizingPlan>;
+  /** §1.4 duplicates merged into the work item kept (E64, E65); the merged id resolves through these. */
+  readonly merges: Collection<MergeRecord>;
+  /** §1.1 the Keeper's classification of scope locations and the owner's corrections (CKC-04 AC-13, AC-17). */
+  readonly scopeJudgements: Collection<ScopeJudgement>;
+  /** §2.12 breakpoints: a due next step without a trace, hanging on an object (CKC-24 AC-7). */
+  readonly breakpoints: Collection<Breakpoint>;
+  /** §1.18 send-backs to Work or Plan: Suggested → Returned → Closed (CKC-24 AC-9, AC-10). */
+  readonly sendbacks: Collection<SendBack>;
+  /** §1.17 semantic patches: what a docs change of meaning withdrew and what replaced it (CKC-26). */
+  readonly patches: Collection<SemanticPatch>;
+  /** §1.17 the numbers the Keeper gave to what the project did not number (D72). */
+  readonly numbers: Collection<KeeperNumber>;
+  /** §3.11 one session draft per session (D88). */
+  readonly drafts: Collection<SessionDraft>;
+  /** §1.19 the judged half of the code territories (CKC-25). */
+  readonly territories: Collection<CodeTerritory>;
+  /** §2.12 earlier generations of plans (D85). */
+  readonly generations: Collection<Generation>;
+  /** §3.3 orientation's map of which file is which layer. */
+  readonly layers: Collection<LayerEntry>;
+  /** §3.3 what a round leaves behind: history map, questions, briefs, reports, adoption record, spot check, result. */
+  readonly roundDocs: Collection<RoundDoc>;
+  /** §1.4 links between work and ledger entries the program could not make from ids alone. */
+  readonly links: Collection<ProcessLink>;
+  /** §3.3 the rounds of the clerk method, with what each produced. */
+  readonly clerkRounds: Collection<ClerkRound>;
+  private coverageDoc: Coverage;
+  private readonly dirty = new Map<string, Set<string>>();
+  private timer: NodeJS.Timeout | null = null;
+  private pendingFlush: Promise<void> | null = null;
+  private resolveFlush: (() => void) | null = null;
+
+  private constructor(projectId: string, dir: string) {
+    super();
+    this.projectId = projectId;
+    this.dir = dir;
+    const load = <T extends Identified>(name: string): T[] => readJson<T[]>(join(dir, `${name}.json`), []);
+    this.sources = new Collection('sources', this, load<Source>('sources'));
+    this.facts = new Collection('facts', this, load<FactRecord>('facts'));
+    this.threads = new Collection('threads', this, load<WorkThread>('threads'));
+    this.areas = new Collection('areas', this, load<AreaUnderstanding>('areas'));
+    this.reference = new Collection('reference', this, load<ReferenceItem>('reference'));
+    this.nodes = new Collection('nodes', this, load<GraphNode>('nodes'));
+    this.relations = new Collection('relations', this, load<GraphRelation>('relations'));
+    this.notes = new Collection('notes', this, load<Note>('notes'));
+    this.changes = new Collection('changes', this, load<ChangeRecord>('changes'));
+    this.marks = new Collection('marks', this, load<EntryMark>('marks'));
+    this.judgements = new Collection('judgements', this, load<JudgementRecord>('judgements'));
+    this.jobs = new Collection('jobs', this, load<KeeperJob>('jobs'));
+    this.authorizations = new Collection('authorizations', this, load<Authorization>('authorizations'));
+    this.requests = new Collection('requests', this, load<ModificationRequest>('requests'));
+    this.contexts = new Collection('contexts', this, load<ContextPackage>('contexts'));
+    this.propagation = new Collection('propagation', this, load<ObjectJudgement>('propagation'));
+    this.rounds = new Collection('rounds', this, load<FollowUpRound>('rounds'));
+    // Added with Spec v2.8. A home written before them has no such files and opens with them empty.
+    this.rules = new Collection('rules', this, load<ProjectRule>('rules'));
+    this.plans = new Collection('plans', this, load<OrganizingPlan>('plans'));
+    this.merges = new Collection('merges', this, load<MergeRecord>('merges'));
+    this.scopeJudgements = new Collection('scopeJudgements', this, load<ScopeJudgement>('scopeJudgements'));
+    // Added with Spec v3.0 (increment K). A home written before them opens with them empty.
+    this.breakpoints = new Collection('breakpoints', this, load<Breakpoint>('breakpoints'));
+    this.sendbacks = new Collection('sendbacks', this, load<SendBack>('sendbacks'));
+    this.patches = new Collection('patches', this, load<SemanticPatch>('patches'));
+    this.numbers = new Collection('numbers', this, load<KeeperNumber>('numbers'));
+    this.drafts = new Collection('drafts', this, load<SessionDraft>('drafts'));
+    this.territories = new Collection('territories', this, load<CodeTerritory>('territories'));
+    this.generations = new Collection('generations', this, load<Generation>('generations'));
+    this.layers = new Collection('layers', this, load<LayerEntry>('layers'));
+    this.roundDocs = new Collection('roundDocs', this, load<RoundDoc>('roundDocs'));
+    this.links = new Collection('links', this, load<ProcessLink>('links'));
+    this.clerkRounds = new Collection('clerkRounds', this, load<ClerkRound>('clerkRounds'));
+    this.coverageDoc = readJson<Coverage>(join(dir, 'coverage.json'), emptyCoverage(projectId));
+  }
+
+  static open(projectId: string, home = projectKeeperHome()): ProjectStore {
+    const dir = projectDir(projectId, home);
+    ensureHome(home);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    return new ProjectStore(projectId, dir);
+  }
+
+  collection(name: CollectionName): Collection<Identified> {
+    return this[name] as unknown as Collection<Identified>;
+  }
+
+  get coverage(): Coverage { return this.coverageDoc; }
+  setCoverage(coverage: Coverage, trace?: TraceInfo): void {
+    this.coverageDoc = { ...coverage, updatedAt: new Date().toISOString() };
+    this.markDirty('coverage', ['coverage']);
+    if (trace) this.trace({ collection: 'coverage', id: 'coverage', op: 'put', ...trace });
+  }
+
+  trace(entry: { collection: string; id: string; op: 'put' | 'remove' } & TraceInfo): void {
+    const record: TraceEntry = {
+      at: new Date().toISOString(), jobId: entry.jobId, collection: entry.collection, id: entry.id,
+      op: entry.op, basisSourceIds: entry.basisSourceIds ?? [], summary: entry.summary,
+    };
+    appendJsonLine(join(this.dir, 'trace.jsonl'), record);
+  }
+
+  traceFor(collection: string, id: string, limit = 50): TraceEntry[] {
+    return readJsonLines<TraceEntry>(join(this.dir, 'trace.jsonl'))
+      .filter((e) => e.collection === collection && e.id === id).slice(-limit);
+  }
+
+  traceByJob(jobId: string, limit = 200): TraceEntry[] {
+    return readJsonLines<TraceEntry>(join(this.dir, 'trace.jsonl')).filter((e) => e.jobId === jobId).slice(-limit);
+  }
+
+  markDirty(collection: string, ids: readonly string[]): void {
+    let set = this.dirty.get(collection);
+    if (!set) { set = new Set(); this.dirty.set(collection, set); }
+    for (const id of ids) set.add(id);
+    if (!this.timer) {
+      this.timer = setTimeout(() => this.flushNow(), 40);
+      this.timer.unref?.();
+    }
+  }
+
+  /**
+   * Remove every asset of the project (Spec §3.7 清空, §8.5): every collection, the coverage, the trace, and whatever
+   * else lies in the project's asset directory — the ledger, the kept versions, the code index. The store stays open,
+   * empty; the views are told that everything changed. The `table/` folder stays (D107): the table an agent filled, its
+   * history and the takeover's work folders are the record of a takeover, not the Keeper's organizing, and can be taken in
+   * again. Returns the entries of the directory that could not be removed
+   * (a file another process still holds), so the caller can say so. Nothing outside this directory is touched.
+   */
+  clearAll(): string[] {
+    if (this.timer) { clearTimeout(this.timer); this.timer = null; }
+    this.dirty.clear();
+    for (const name of COLLECTIONS) this.collection(name).drop();
+    this.coverageDoc = emptyCoverage(this.projectId);
+    const left: string[] = [];
+    for (const entry of existsSync(this.dir) ? readdirSync(this.dir) : []) {
+      if (entry === TABLE_FOLDER) continue;
+      try { rmSync(join(this.dir, entry), { recursive: true, force: true, maxRetries: 5, retryDelay: 100 }); }
+      catch { left.push(entry); }
+    }
+    if (!existsSync(this.dir)) mkdirSync(this.dir, { recursive: true });
+    for (const name of [...COLLECTIONS, 'coverage']) this.emit('change', { projectId: this.projectId, collection: name, ids: [] } satisfies ChangeEvent);
+    return left;
+  }
+
+  /** Persist everything dirty. Resolves once the files are on disk. */
+  flush(): Promise<void> {
+    if (this.dirty.size === 0 && !this.timer) return Promise.resolve();
+    this.flushNow();
+    return Promise.resolve();
+  }
+
+  private flushNow(): void {
+    if (this.timer) { clearTimeout(this.timer); this.timer = null; }
+    const changed = [...this.dirty.entries()];
+    this.dirty.clear();
+    for (const [collection] of changed) {
+      if (collection === 'coverage') writeJsonAtomic(join(this.dir, 'coverage.json'), this.coverageDoc);
+      else if ((COLLECTIONS as readonly string[]).includes(collection)) {
+        writeJsonAtomic(join(this.dir, `${collection}.json`), this.collection(collection as CollectionName).snapshot());
+      }
+    }
+    for (const [collection, ids] of changed) {
+      const event: ChangeEvent = { projectId: this.projectId, collection, ids: [...ids] };
+      this.emit('change', event);
+    }
+    if (this.resolveFlush) { this.resolveFlush(); this.resolveFlush = null; this.pendingFlush = null; }
+  }
+}