@guanlin4924/devflow-pi 0.1.60 → 0.1.63

package/src/initialization-store.ts

@@ -0,0 +1,656 @@
+import { createHash, randomUUID } from "node:crypto";
+import { copyFile, cp, mkdir, readFile, realpath, stat, writeFile, rename, rm } from "node:fs/promises";
+import path from "node:path";
+import { Database } from "bun:sqlite";
+
+import { projectControlDatabasePath, projectDataDir } from "./paths.ts";
+
+export const INITIALIZATION_SCHEMA_VERSION = 2;
+export const FACT_KINDS = [
+  "asset", "technology", "api", "page", "data_model", "integration",
+  "rule", "toolchain", "evidence", "capability",
+] as const;
+export type FactKind = typeof FACT_KINDS[number];
+export type CoverageStatus = "complete" | "partial" | "unsupported" | "not_applicable" | "skipped" | "failed";
+export type RunStatus = "preparing" | "collecting" | "validating" | "finished" | "failed" | "cancelled";
+export type EvidenceLevel = "observed" | "explicit_rule" | "historical" | "candidate";
+
+export interface InitializationContextLike {
+  root: string;
+  manifest: { projectId: string; name: string };
+}
+
+export interface ScanRepository {
+  name: string;
+  relativePath: string;
+  role: "frontend" | "backend" | "shared" | "other";
+}
+
+export interface ScanConfigInput {
+  mode: "full" | "fast";
+  repositories: ScanRepository[];
+  includes?: string[];
+  excludes?: string[];
+  requiredKinds?: FactKind[];
+  adapterVersions?: Record<string, string>;
+}
+
+export interface FactInput {
+  kind: FactKind;
+  objectKey: string;
+  value: Record<string, unknown>;
+  evidenceLevel: EvidenceLevel;
+  repository?: string;
+  sourcePath?: string;
+  sourceLine?: number;
+  sourceFingerprint?: string;
+  extractor: string;
+  confidence?: "exact" | "inferred" | "heuristic";
+}
+
+const SCHEMA = `
+PRAGMA foreign_keys = ON;
+CREATE TABLE IF NOT EXISTS schema_meta(version INTEGER NOT NULL);
+CREATE TABLE IF NOT EXISTS projects(id TEXT PRIMARY KEY, name TEXT NOT NULL, created_at TEXT NOT NULL);
+CREATE TABLE IF NOT EXISTS workspaces(
+  id TEXT PRIMARY KEY, project_id TEXT NOT NULL REFERENCES projects(id), location TEXT NOT NULL,
+  repository_identity TEXT, created_at TEXT NOT NULL, updated_at TEXT NOT NULL,
+  UNIQUE(project_id, location)
+);
+CREATE TABLE IF NOT EXISTS scan_configs(
+  id TEXT PRIMARY KEY, project_id TEXT NOT NULL REFERENCES projects(id), revision INTEGER NOT NULL,
+  content_hash TEXT NOT NULL, config_json TEXT NOT NULL, created_at TEXT NOT NULL,
+  UNIQUE(project_id, revision), UNIQUE(project_id, content_hash)
+);
+CREATE TABLE IF NOT EXISTS input_snapshots(
+  id TEXT PRIMARY KEY, project_id TEXT NOT NULL REFERENCES projects(id), workspace_id TEXT NOT NULL REFERENCES workspaces(id),
+  config_id TEXT NOT NULL REFERENCES scan_configs(id), fingerprint TEXT NOT NULL, manifest_json TEXT NOT NULL,
+  stable INTEGER NOT NULL CHECK(stable IN (0,1)), created_at TEXT NOT NULL,
+  UNIQUE(workspace_id, config_id, fingerprint)
+);
+CREATE TABLE IF NOT EXISTS initialization_runs(
+  id TEXT PRIMARY KEY, project_id TEXT NOT NULL REFERENCES projects(id), workspace_id TEXT NOT NULL REFERENCES workspaces(id),
+  config_id TEXT NOT NULL REFERENCES scan_configs(id), input_snapshot_id TEXT NOT NULL REFERENCES input_snapshots(id),
+  request_id TEXT, request_hash TEXT NOT NULL, status TEXT NOT NULL,
+  lease_token TEXT NOT NULL, lease_expires_at TEXT NOT NULL, created_at TEXT NOT NULL, updated_at TEXT NOT NULL,
+  published_snapshot_id TEXT, error TEXT, UNIQUE(workspace_id, request_id)
+);
+CREATE TABLE IF NOT EXISTS collection_results(
+  id TEXT PRIMARY KEY, run_id TEXT NOT NULL REFERENCES initialization_runs(id), repository TEXT NOT NULL DEFAULT '',
+  kind TEXT NOT NULL, status TEXT NOT NULL, adapter TEXT NOT NULL, capability_json TEXT NOT NULL,
+  diagnostics_json TEXT NOT NULL, created_at TEXT NOT NULL, UNIQUE(run_id, repository, kind)
+);
+CREATE TABLE IF NOT EXISTS facts(
+  id TEXT PRIMARY KEY, run_id TEXT NOT NULL REFERENCES initialization_runs(id), kind TEXT NOT NULL,
+  object_key TEXT NOT NULL, repository TEXT NOT NULL DEFAULT '', value_json TEXT NOT NULL,
+  evidence_level TEXT NOT NULL, extractor TEXT NOT NULL, confidence TEXT NOT NULL,
+  created_at TEXT NOT NULL, UNIQUE(run_id, kind, repository, object_key)
+);
+CREATE TABLE IF NOT EXISTS evidence(
+  id TEXT PRIMARY KEY, fact_id TEXT NOT NULL REFERENCES facts(id), source_path TEXT NOT NULL,
+  source_line INTEGER, source_fingerprint TEXT NOT NULL, method TEXT NOT NULL, created_at TEXT NOT NULL,
+  UNIQUE(fact_id, source_path, source_line, method)
+);
+CREATE TABLE IF NOT EXISTS context_snapshots(
+  id TEXT PRIMARY KEY, project_id TEXT NOT NULL REFERENCES projects(id), workspace_id TEXT NOT NULL REFERENCES workspaces(id),
+  config_id TEXT NOT NULL REFERENCES scan_configs(id), input_snapshot_id TEXT NOT NULL REFERENCES input_snapshots(id),
+  run_id TEXT NOT NULL UNIQUE REFERENCES initialization_runs(id), completeness TEXT NOT NULL,
+  content_hash TEXT NOT NULL, index_ref_json TEXT, created_at TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS current_context(
+  workspace_id TEXT NOT NULL REFERENCES workspaces(id), config_id TEXT NOT NULL REFERENCES scan_configs(id),
+  snapshot_id TEXT NOT NULL REFERENCES context_snapshots(id), revision INTEGER NOT NULL,
+  PRIMARY KEY(workspace_id, config_id)
+);
+CREATE TABLE IF NOT EXISTS document_jobs(
+  id TEXT PRIMARY KEY, snapshot_id TEXT NOT NULL REFERENCES context_snapshots(id), target_path TEXT NOT NULL,
+  ownership TEXT NOT NULL CHECK(ownership IN ('generated','human','mixed')), template_version TEXT NOT NULL,
+  model_role TEXT, status TEXT NOT NULL, input_hash TEXT NOT NULL, output_hash TEXT,
+  conflict_path TEXT, error TEXT, created_at TEXT NOT NULL, updated_at TEXT NOT NULL,
+  UNIQUE(snapshot_id, target_path, template_version)
+);
+CREATE TABLE IF NOT EXISTS authority_state(
+  project_id TEXT PRIMARY KEY REFERENCES projects(id), authority TEXT NOT NULL CHECK(authority IN ('legacy','shadow','database')),
+  revision INTEGER NOT NULL, switched_at TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS historical_imports(
+  id TEXT PRIMARY KEY, project_id TEXT NOT NULL REFERENCES projects(id), workspace_id TEXT NOT NULL REFERENCES workspaces(id),
+  source_path TEXT NOT NULL, content_hash TEXT NOT NULL, status TEXT NOT NULL CHECK(status IN ('shadow','accepted','rejected')),
+  snapshot_id TEXT REFERENCES context_snapshots(id), created_at TEXT NOT NULL,
+  UNIQUE(workspace_id, source_path, content_hash)
+);
+CREATE TABLE IF NOT EXISTS content_objects(
+  content_hash TEXT PRIMARY KEY, relative_path TEXT NOT NULL UNIQUE, size_bytes INTEGER NOT NULL, created_at TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS snapshot_relations(
+  id TEXT PRIMARY KEY, snapshot_id TEXT NOT NULL REFERENCES context_snapshots(id), source_key TEXT NOT NULL,
+  relation_type TEXT NOT NULL, target_key TEXT, external_target TEXT, resolution TEXT NOT NULL,
+  confidence TEXT NOT NULL, evidence_json TEXT NOT NULL,
+  CHECK((target_key IS NOT NULL) != (external_target IS NOT NULL))
+);
+CREATE INDEX IF NOT EXISTS idx_facts_snapshot_query ON facts(kind, repository, object_key);
+CREATE INDEX IF NOT EXISTS idx_evidence_path ON evidence(source_path);
+CREATE INDEX IF NOT EXISTS idx_runs_workspace_status ON initialization_runs(workspace_id, status);
+CREATE INDEX IF NOT EXISTS idx_snapshot_relations_source ON snapshot_relations(snapshot_id, source_key, relation_type);
+CREATE INDEX IF NOT EXISTS idx_snapshot_relations_target ON snapshot_relations(snapshot_id, target_key, relation_type);
+CREATE TRIGGER IF NOT EXISTS validate_run_status_insert BEFORE INSERT ON initialization_runs
+WHEN NEW.status NOT IN ('preparing','collecting','validating','finished','failed','cancelled')
+BEGIN SELECT RAISE(ABORT, 'invalid initialization run status'); END;
+CREATE TRIGGER IF NOT EXISTS validate_collection_insert BEFORE INSERT ON collection_results
+WHEN NEW.kind NOT IN ('asset','technology','api','page','data_model','integration','rule','toolchain','evidence','capability')
+ OR NEW.status NOT IN ('complete','partial','unsupported','not_applicable','skipped','failed')
+BEGIN SELECT RAISE(ABORT, 'invalid collection kind or status'); END;
+CREATE TRIGGER IF NOT EXISTS validate_collection_update BEFORE UPDATE ON collection_results
+WHEN NEW.kind NOT IN ('asset','technology','api','page','data_model','integration','rule','toolchain','evidence','capability')
+ OR NEW.status NOT IN ('complete','partial','unsupported','not_applicable','skipped','failed')
+BEGIN SELECT RAISE(ABORT, 'invalid collection kind or status'); END;
+CREATE TRIGGER IF NOT EXISTS validate_fact_insert BEFORE INSERT ON facts
+WHEN NEW.kind NOT IN ('asset','technology','api','page','data_model','integration','rule','toolchain','evidence','capability')
+ OR NEW.evidence_level NOT IN ('observed','explicit_rule','historical','candidate')
+ OR NEW.confidence NOT IN ('exact','inferred','heuristic')
+BEGIN SELECT RAISE(ABORT, 'invalid fact type, evidence level, or confidence'); END;
+CREATE TRIGGER IF NOT EXISTS validate_fact_update BEFORE UPDATE ON facts
+WHEN NEW.kind NOT IN ('asset','technology','api','page','data_model','integration','rule','toolchain','evidence','capability')
+ OR NEW.evidence_level NOT IN ('observed','explicit_rule','historical','candidate')
+ OR NEW.confidence NOT IN ('exact','inferred','heuristic')
+BEGIN SELECT RAISE(ABORT, 'invalid fact type, evidence level, or confidence'); END;
+CREATE TRIGGER IF NOT EXISTS validate_document_job_insert BEFORE INSERT ON document_jobs
+WHEN NEW.ownership NOT IN ('generated','human','mixed') OR NEW.status NOT IN ('queued','generating','pending_review','complete','failed','conflict')
+BEGIN SELECT RAISE(ABORT, 'invalid document ownership or status'); END;
+CREATE TRIGGER IF NOT EXISTS validate_document_job_update BEFORE UPDATE ON document_jobs
+WHEN NEW.ownership NOT IN ('generated','human','mixed') OR NEW.status NOT IN ('queued','generating','pending_review','complete','failed','conflict')
+BEGIN SELECT RAISE(ABORT, 'invalid document ownership or status'); END;
+CREATE TRIGGER IF NOT EXISTS validate_context_snapshot_binding BEFORE INSERT ON context_snapshots
+WHEN NOT EXISTS(
+  SELECT 1 FROM initialization_runs r JOIN input_snapshots i ON i.id=NEW.input_snapshot_id
+  WHERE r.id=NEW.run_id AND r.project_id=NEW.project_id AND r.workspace_id=NEW.workspace_id
+    AND r.config_id=NEW.config_id AND r.input_snapshot_id=NEW.input_snapshot_id
+    AND i.project_id=NEW.project_id AND i.workspace_id=NEW.workspace_id AND i.config_id=NEW.config_id
+)
+BEGIN SELECT RAISE(ABORT, 'context snapshot crosses project or input boundary'); END;
+CREATE TRIGGER IF NOT EXISTS validate_current_context_binding_insert BEFORE INSERT ON current_context
+WHEN NOT EXISTS(
+  SELECT 1 FROM context_snapshots s
+  WHERE s.id=NEW.snapshot_id AND s.workspace_id=NEW.workspace_id AND s.config_id=NEW.config_id
+)
+BEGIN SELECT RAISE(ABORT, 'current context crosses workspace or configuration boundary'); END;
+CREATE TRIGGER IF NOT EXISTS validate_current_context_binding_update BEFORE UPDATE ON current_context
+WHEN NOT EXISTS(
+  SELECT 1 FROM context_snapshots s
+  WHERE s.id=NEW.snapshot_id AND s.workspace_id=NEW.workspace_id AND s.config_id=NEW.config_id
+)
+BEGIN SELECT RAISE(ABORT, 'current context crosses workspace or configuration boundary'); END;
+CREATE TRIGGER IF NOT EXISTS immutable_context_snapshot_update BEFORE UPDATE ON context_snapshots
+BEGIN SELECT RAISE(ABORT, 'context snapshots are immutable'); END;
+CREATE TRIGGER IF NOT EXISTS immutable_context_snapshot_delete BEFORE DELETE ON context_snapshots
+BEGIN SELECT RAISE(ABORT, 'context snapshots are immutable'); END;
+CREATE TRIGGER IF NOT EXISTS stable_input_immutable BEFORE UPDATE ON input_snapshots
+WHEN OLD.stable=1 OR NEW.id!=OLD.id OR NEW.project_id!=OLD.project_id OR NEW.workspace_id!=OLD.workspace_id
+ OR NEW.config_id!=OLD.config_id OR NEW.fingerprint!=OLD.fingerprint OR NEW.manifest_json!=OLD.manifest_json
+BEGIN SELECT RAISE(ABORT, 'stable input snapshots are immutable'); END;
+CREATE TRIGGER IF NOT EXISTS published_fact_immutable_update BEFORE UPDATE ON facts
+WHEN EXISTS(SELECT 1 FROM initialization_runs r WHERE r.id=OLD.run_id AND r.status='finished')
+BEGIN SELECT RAISE(ABORT, 'published facts are immutable'); END;
+CREATE TRIGGER IF NOT EXISTS published_fact_immutable_delete BEFORE DELETE ON facts
+WHEN EXISTS(SELECT 1 FROM initialization_runs r WHERE r.id=OLD.run_id AND r.status='finished')
+BEGIN SELECT RAISE(ABORT, 'published facts are immutable'); END;
+`;
+
+function now(): string { return new Date().toISOString(); }
+function canonicalJson(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (value && typeof value === "object") return `{${Object.entries(value as Record<string, unknown>).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`).join(",")}}`;
+  return JSON.stringify(value);
+}
+function hash(value: string | Uint8Array): string { return `sha256:${createHash("sha256").update(value).digest("hex")}`; }
+function parse<T>(value: string): T { return JSON.parse(value) as T; }
+function validateRelative(relative: string): string {
+  const normalized = relative.replaceAll("\\", "/").replace(/^\.\//, "");
+  if (!normalized || normalized === ".." || normalized.startsWith("../") || path.isAbsolute(normalized)) throw new Error(`Path escapes project boundary: ${relative}`);
+  return normalized;
+}
+function validateFactShape(fact: FactInput): void {
+  if (!fact.value || Array.isArray(fact.value) || typeof fact.value !== "object") throw new Error(`${fact.kind} fact value must be a structured object`);
+  if (fact.evidenceLevel === "historical") {
+    if (typeof fact.value.sourcePath !== "string" || typeof fact.value.contentHash !== "string") throw new Error("Historical facts require sourcePath and contentHash metadata");
+    return;
+  }
+  const has = (...keys: string[]) => keys.some(key => typeof fact.value[key] === "string" && String(fact.value[key]).length > 0);
+  const valid = fact.kind === "asset" ? has("path")
+    : fact.kind === "technology" ? has("name", "extension", "path")
+    : fact.kind === "api" ? has("path")
+    : fact.kind === "page" ? has("route", "componentPath")
+    : fact.kind === "data_model" ? has("name")
+    : fact.kind === "integration" ? has("host", "kind", "name")
+    : fact.kind === "rule" ? has("path")
+    : fact.kind === "toolchain" ? has("name", "testDefinition")
+    : fact.kind === "evidence" ? has("source")
+    : fact.kind === "capability" ? Array.isArray(fact.value.supported)
+    : false;
+  if (!valid) throw new Error(`${fact.kind} fact does not satisfy its structured value contract`);
+}
+
+async function repositoryIdentity(root: string): Promise<string | null> {
+  const child = Bun.spawn(["git", "-C", root, "rev-parse", "--git-common-dir"], { stdout: "pipe", stderr: "ignore" });
+  if (await child.exited !== 0) return null;
+  const value = (await new Response(child.stdout).text()).trim();
+  if (!value) return null;
+  return realpath(path.resolve(root, value)).catch(() => path.resolve(root, value));
+}
+
+export class InitializationStore {
+  readonly db: Database;
+  readonly databasePath: string;
+  private constructor(readonly context: InitializationContextLike, databasePath: string, db: Database) {
+    this.databasePath = databasePath;
+    this.db = db;
+  }
+
+  static async open(context: InitializationContextLike): Promise<InitializationStore> {
+    const directory = projectDataDir(context.manifest.projectId);
+    await mkdir(path.join(directory, "content"), { recursive: true });
+    const databasePath = projectControlDatabasePath(context.manifest.projectId);
+    const db = new Database(databasePath, { create: true });
+    const hasMeta = db.query("SELECT 1 FROM sqlite_master WHERE type='table' AND name='schema_meta'").get();
+    if (hasMeta) {
+      const existing = db.query("SELECT version FROM schema_meta LIMIT 1").get() as { version: number } | null;
+      if (existing && existing.version > INITIALIZATION_SCHEMA_VERSION) {
+        db.close();
+        throw new Error(`Initialization database schema ${existing.version} is newer than supported ${INITIALIZATION_SCHEMA_VERSION}`);
+      }
+      if (existing && existing.version < INITIALIZATION_SCHEMA_VERSION) {
+        const migrationBackup = `${databasePath}.pre-v${existing.version}-${Date.now()}.backup`;
+        await writeFile(migrationBackup, db.serialize(), { flag: "wx" });
+      }
+    }
+    db.transaction(() => {
+      db.exec(SCHEMA);
+      const meta = db.query("SELECT version FROM schema_meta LIMIT 1").get() as { version: number } | null;
+      if (!meta) db.query("INSERT INTO schema_meta(version) VALUES (?)").run(INITIALIZATION_SCHEMA_VERSION);
+      else if (meta.version < INITIALIZATION_SCHEMA_VERSION) db.query("UPDATE schema_meta SET version=?").run(INITIALIZATION_SCHEMA_VERSION);
+    })();
+    db.query("INSERT OR IGNORE INTO projects(id,name,created_at) VALUES (?,?,?)").run(context.manifest.projectId, context.manifest.name, now());
+    db.query("INSERT OR IGNORE INTO authority_state(project_id,authority,revision,switched_at) VALUES (?,?,?,?)").run(context.manifest.projectId, "legacy", 0, now());
+    return new InitializationStore(context, databasePath, db);
+  }
+
+  close(): void { this.db.close(); }
+
+  async registerWorkspace(options: { rebindWorkspaceId?: string } = {}): Promise<{ id: string; location: string; created: boolean }> {
+    const location = await realpath(this.context.root);
+    const existing = this.db.query("SELECT id, location FROM workspaces WHERE project_id=? AND location=?").get(this.context.manifest.projectId, location) as { id: string; location: string } | null;
+    if (existing) return { ...existing, created: false };
+    const repository = await repositoryIdentity(location);
+    if (options.rebindWorkspaceId) {
+      const changed = this.db.query("UPDATE workspaces SET location=?, repository_identity=?, updated_at=? WHERE id=? AND project_id=?").run(location, repository, now(), options.rebindWorkspaceId, this.context.manifest.projectId);
+      if (changed.changes !== 1) throw new Error(`Unknown workspace for rebind: ${options.rebindWorkspaceId}`);
+      return { id: options.rebindWorkspaceId, location, created: false };
+    }
+    const id = randomUUID();
+    this.db.query("INSERT INTO workspaces(id,project_id,location,repository_identity,created_at,updated_at) VALUES (?,?,?,?,?,?)").run(id, this.context.manifest.projectId, location, repository, now(), now());
+    return { id, location, created: true };
+  }
+
+  putScanConfig(input: ScanConfigInput): { id: string; revision: number; created: boolean } {
+    const repositories = input.repositories.map(item => ({
+      ...item,
+      relativePath: item.relativePath === "." || path.isAbsolute(item.relativePath)
+        ? item.relativePath
+        : validateRelative(item.relativePath),
+    }));
+    const requiredKinds = input.requiredKinds ?? [...FACT_KINDS];
+    if (input.mode === "fast" && requiredKinds.length === FACT_KINDS.length) throw new Error("Fast mode must explicitly limit required fact kinds");
+    const config = { ...input, repositories, requiredKinds, includes: input.includes ?? ["**/*"], excludes: input.excludes ?? [".git/**", ".planning/**", ".devflow/**"], adapterVersions: input.adapterVersions ?? {} };
+    const configJson = canonicalJson(config);
+    const contentHash = hash(configJson);
+    const existing = this.db.query("SELECT id, revision FROM scan_configs WHERE project_id=? AND content_hash=?").get(this.context.manifest.projectId, contentHash) as { id: string; revision: number } | null;
+    if (existing) return { ...existing, created: false };
+    const row = this.db.query("SELECT COALESCE(MAX(revision),0)+1 AS revision FROM scan_configs WHERE project_id=?").get(this.context.manifest.projectId) as { revision: number };
+    const id = randomUUID();
+    this.db.query("INSERT INTO scan_configs(id,project_id,revision,content_hash,config_json,created_at) VALUES (?,?,?,?,?,?)").run(id, this.context.manifest.projectId, row.revision, contentHash, configJson, now());
+    return { id, revision: row.revision, created: true };
+  }
+
+  createInputSnapshot(workspaceId: string, configId: string, files: Array<{ repository: string; path: string; contentHash: string; size?: number }>, stable = true): { id: string; fingerprint: string; created: boolean } {
+    const normalized = files.map(file => ({ ...file, path: validateRelative(file.path) })).sort((a, b) => `${a.repository}/${a.path}`.localeCompare(`${b.repository}/${b.path}`));
+    const manifestJson = canonicalJson(normalized);
+    const fingerprint = hash(manifestJson);
+    const existing = this.db.query("SELECT id,stable FROM input_snapshots WHERE workspace_id=? AND config_id=? AND fingerprint=?").get(workspaceId, configId, fingerprint) as { id: string; stable: number } | null;
+    if (existing) {
+      if (stable && !existing.stable) this.db.query("UPDATE input_snapshots SET stable=1 WHERE id=?").run(existing.id);
+      return { id: existing.id, fingerprint, created: false };
+    }
+    const id = randomUUID();
+    this.db.query("INSERT INTO input_snapshots(id,project_id,workspace_id,config_id,fingerprint,manifest_json,stable,created_at) VALUES (?,?,?,?,?,?,?,?)").run(id, this.context.manifest.projectId, workspaceId, configId, fingerprint, manifestJson, stable ? 1 : 0, now());
+    return { id, fingerprint, created: true };
+  }
+
+  confirmInputSnapshot(inputSnapshotId: string, fingerprint: string): void {
+    const result = this.db.query("UPDATE input_snapshots SET stable=1 WHERE id=? AND fingerprint=? AND stable=0").run(inputSnapshotId, fingerprint);
+    if (result.changes !== 1) {
+      const current = this.db.query("SELECT fingerprint,stable FROM input_snapshots WHERE id=?").get(inputSnapshotId) as { fingerprint: string; stable: number } | null;
+      if (!current) throw new Error(`Unknown input snapshot: ${inputSnapshotId}`);
+      if (current.fingerprint !== fingerprint) throw new Error("Source changed during initialization; refusing to publish mixed input");
+    }
+  }
+
+  startRun(input: { workspaceId: string; configId: string; inputSnapshotId: string; requestId?: string; leaseMs?: number }): { id: string; leaseToken: string; reused: boolean } {
+    const binding = this.db.query(`
+      SELECT i.id FROM input_snapshots i
+      JOIN workspaces w ON w.id=i.workspace_id
+      JOIN scan_configs c ON c.id=i.config_id
+      WHERE i.id=? AND i.workspace_id=? AND i.config_id=?
+        AND i.project_id=? AND w.project_id=i.project_id AND c.project_id=i.project_id
+    `).get(input.inputSnapshotId, input.workspaceId, input.configId, this.context.manifest.projectId);
+    if (!binding) throw new Error("Run input, workspace, and scan config do not belong to the same project boundary");
+    const requestHash = hash(canonicalJson({ workspaceId: input.workspaceId, configId: input.configId, inputSnapshotId: input.inputSnapshotId }));
+    if (input.requestId) {
+      const prior = this.db.query("SELECT id, lease_token AS leaseToken, request_hash AS requestHash FROM initialization_runs WHERE workspace_id=? AND request_id=?").get(input.workspaceId, input.requestId) as { id: string; leaseToken: string; requestHash: string } | null;
+      if (prior) {
+        if (prior.requestHash !== requestHash) throw new Error(`Idempotency conflict for request ${input.requestId}`);
+        return { id: prior.id, leaseToken: prior.leaseToken, reused: true };
+      }
+    }
+    const id = randomUUID(); const leaseToken = randomUUID(); const timestamp = now();
+    const expires = new Date(Date.now() + (input.leaseMs ?? 15 * 60_000)).toISOString();
+    this.db.query("INSERT INTO initialization_runs(id,project_id,workspace_id,config_id,input_snapshot_id,request_id,request_hash,status,lease_token,lease_expires_at,created_at,updated_at) VALUES (?,?,?,?,?,?,?,?,?,?,?,?)").run(id, this.context.manifest.projectId, input.workspaceId, input.configId, input.inputSnapshotId, input.requestId ?? null, requestHash, "collecting", leaseToken, expires, timestamp, timestamp);
+    return { id, leaseToken, reused: false };
+  }
+
+  private assertWritableRun(runId: string, leaseToken: string): { status: RunStatus; inputSnapshotId: string; workspaceId: string; configId: string } {
+    const row = this.db.query("SELECT status,input_snapshot_id AS inputSnapshotId,workspace_id AS workspaceId,config_id AS configId,lease_token AS leaseToken,lease_expires_at AS expires FROM initialization_runs WHERE id=?").get(runId) as ({ status: RunStatus; inputSnapshotId: string; workspaceId: string; configId: string; leaseToken: string; expires: string }) | null;
+    if (!row) throw new Error(`Unknown initialization run: ${runId}`);
+    if (row.leaseToken !== leaseToken) throw new Error("Initialization lease token mismatch");
+    if (Date.parse(row.expires) < Date.now()) throw new Error("Initialization lease expired; recover the run before writing");
+    if (["cancelled", "failed", "finished"].includes(row.status)) throw new Error(`Initialization run is not writable: ${row.status}`);
+    return row;
+  }
+
+  recordCollection(runId: string, leaseToken: string, input: { repository?: string; kind: FactKind; status: CoverageStatus; adapter: string; capability?: Record<string, unknown>; diagnostics?: unknown[]; facts?: FactInput[] }): void {
+    this.assertWritableRun(runId, leaseToken);
+    const transaction = this.db.transaction(() => {
+      this.db.query("INSERT INTO collection_results(id,run_id,repository,kind,status,adapter,capability_json,diagnostics_json,created_at) VALUES (?,?,?,?,?,?,?,?,?) ON CONFLICT(run_id,repository,kind) DO UPDATE SET status=excluded.status,adapter=excluded.adapter,capability_json=excluded.capability_json,diagnostics_json=excluded.diagnostics_json").run(randomUUID(), runId, input.repository ?? "", input.kind, input.status, input.adapter, canonicalJson(input.capability ?? {}), canonicalJson(input.diagnostics ?? []), now());
+      for (const fact of input.facts ?? []) {
+        if (fact.kind !== input.kind) throw new Error(`Fact kind ${fact.kind} does not match collection ${input.kind}`);
+        if (!fact.objectKey || !fact.extractor) throw new Error("Facts require objectKey and extractor");
+        if (fact.evidenceLevel === "observed" && !fact.sourcePath) throw new Error("Observed facts require source evidence");
+        validateFactShape(fact);
+        const factId = randomUUID();
+        this.db.query("INSERT INTO facts(id,run_id,kind,object_key,repository,value_json,evidence_level,extractor,confidence,created_at) VALUES (?,?,?,?,?,?,?,?,?,?) ON CONFLICT(run_id,kind,repository,object_key) DO UPDATE SET value_json=excluded.value_json,evidence_level=excluded.evidence_level,extractor=excluded.extractor,confidence=excluded.confidence").run(factId, runId, fact.kind, fact.objectKey, fact.repository ?? input.repository ?? "", canonicalJson(fact.value), fact.evidenceLevel, fact.extractor, fact.confidence ?? "inferred", now());
+        const stored = this.db.query("SELECT id FROM facts WHERE run_id=? AND kind=? AND repository=? AND object_key=?").get(runId, fact.kind, fact.repository ?? input.repository ?? "", fact.objectKey) as { id: string };
+        if (fact.sourcePath) this.db.query("INSERT OR IGNORE INTO evidence(id,fact_id,source_path,source_line,source_fingerprint,method,created_at) VALUES (?,?,?,?,?,?,?)").run(randomUUID(), stored.id, validateRelative(fact.sourcePath), fact.sourceLine ?? null, fact.sourceFingerprint ?? "unavailable", fact.extractor, now());
+      }
+    });
+    transaction();
+  }
+
+  cancelRun(runId: string): boolean {
+    return this.db.query("UPDATE initialization_runs SET status='cancelled',updated_at=? WHERE id=? AND status IN ('preparing','collecting','validating')").run(now(), runId).changes === 1;
+  }
+
+  failRun(runId: string, leaseToken: string, error: string): boolean {
+    return this.db.query("UPDATE initialization_runs SET status='failed',error=?,updated_at=? WHERE id=? AND lease_token=? AND status IN ('preparing','collecting','validating')").run(error.slice(0, 4000), now(), runId, leaseToken).changes === 1;
+  }
+
+  recoverRun(runId: string, leaseMs = 15 * 60_000): { leaseToken: string } {
+    const row = this.db.query("SELECT status,lease_expires_at AS expires FROM initialization_runs WHERE id=?").get(runId) as { status: RunStatus; expires: string } | null;
+    if (!row) throw new Error(`Unknown initialization run: ${runId}`);
+    if (row.status === "cancelled") throw new Error("Cancelled runs cannot resume automatically");
+    if (["failed", "finished"].includes(row.status)) throw new Error(`Run cannot be recovered from ${row.status}`);
+    if (Date.parse(row.expires) >= Date.now()) throw new Error("Run lease is still active");
+    const leaseToken = randomUUID();
+    this.db.query("UPDATE initialization_runs SET lease_token=?,lease_expires_at=?,updated_at=? WHERE id=?").run(leaseToken, new Date(Date.now() + leaseMs).toISOString(), now(), runId);
+    return { leaseToken };
+  }
+
+  publishRun(runId: string, leaseToken: string, options: { expectedRevision?: number; completeness?: "complete" | "partial"; indexRef?: Record<string, unknown>; updateCurrent?: boolean } = {}): { snapshotId: string; revision: number } {
+    const run = this.assertWritableRun(runId, leaseToken);
+    const input = this.db.query("SELECT stable,fingerprint FROM input_snapshots WHERE id=?").get(run.inputSnapshotId) as { stable: number; fingerprint: string };
+    if (!input.stable) throw new Error("Cannot publish an unstable input snapshot");
+    const config = this.db.query("SELECT config_json AS json FROM scan_configs WHERE id=?").get(run.configId) as { json: string };
+    const parsedConfig = parse<ScanConfigInput>(config.json);
+    const required = parsedConfig.requiredKinds ?? [...FACT_KINDS];
+    const results = this.db.query("SELECT repository,kind,status FROM collection_results WHERE run_id=?").all(runId) as Array<{ repository: string; kind: FactKind; status: CoverageStatus }>;
+    const coverage = new Map(results.map(row => [`${row.repository}\0${row.kind}`, row.status]));
+    const blockers = parsedConfig.repositories.flatMap(repository => required.flatMap(kind => {
+      // Empty repository is the v1/global collection form. Keep it readable
+      // while all new collectors write repository-scoped coverage.
+      const status = coverage.get(`${repository.name}\0${kind}`) ?? coverage.get(`\0${kind}`);
+      return !status || ["partial", "unsupported", "skipped", "failed"].includes(status) ? [`${repository.name}:${kind}`] : [];
+    }));
+    const completeness = options.completeness ?? (blockers.length ? "partial" : "complete");
+    if (completeness === "complete" && blockers.length) throw new Error(`Required collection coverage is incomplete: ${blockers.join(", ")}`);
+    const current = this.db.query("SELECT revision FROM current_context WHERE workspace_id=? AND config_id=?").get(run.workspaceId, run.configId) as { revision: number } | null;
+    const revision = (current?.revision ?? 0) + 1;
+    if (options.expectedRevision !== undefined && options.expectedRevision !== (current?.revision ?? 0)) throw new Error(`Current context revision conflict: expected ${options.expectedRevision}, actual ${current?.revision ?? 0}`);
+    const facts = this.db.query("SELECT kind,repository,object_key,value_json,evidence_level,extractor,confidence FROM facts WHERE run_id=? ORDER BY kind,repository,object_key").all(runId);
+    const snapshotId = randomUUID();
+    const transaction = this.db.transaction(() => {
+      this.db.query("UPDATE initialization_runs SET status='validating',updated_at=? WHERE id=? AND lease_token=?").run(now(), runId, leaseToken);
+      this.db.query("INSERT INTO context_snapshots(id,project_id,workspace_id,config_id,input_snapshot_id,run_id,completeness,content_hash,index_ref_json,created_at) VALUES (?,?,?,?,?,?,?,?,?,?)").run(snapshotId, this.context.manifest.projectId, run.workspaceId, run.configId, run.inputSnapshotId, runId, completeness, hash(canonicalJson(facts)), options.indexRef ? canonicalJson(options.indexRef) : null, now());
+      if (options.updateCurrent === false) {
+        // Shadow imports are immutable and queryable without becoming current.
+      } else if (current) {
+        const updated = this.db.query("UPDATE current_context SET snapshot_id=?,revision=? WHERE workspace_id=? AND config_id=? AND revision=?").run(snapshotId, revision, run.workspaceId, run.configId, current.revision);
+        if (updated.changes !== 1) throw new Error("Current context changed while publishing");
+      }
+      else this.db.query("INSERT INTO current_context(workspace_id,config_id,snapshot_id,revision) VALUES (?,?,?,?)").run(run.workspaceId, run.configId, snapshotId, revision);
+      this.db.query("UPDATE initialization_runs SET status='finished',published_snapshot_id=?,updated_at=? WHERE id=? AND lease_token=?").run(snapshotId, now(), runId, leaseToken);
+    });
+    transaction();
+    return { snapshotId, revision };
+  }
+
+  getRun(runId: string): Record<string, unknown> | null {
+    const run = this.db.query("SELECT id,status,workspace_id AS workspaceId,config_id AS configId,input_snapshot_id AS inputSnapshotId,published_snapshot_id AS publishedSnapshotId,error,created_at AS createdAt,updated_at AS updatedAt FROM initialization_runs WHERE id=?").get(runId) as Record<string, unknown> | null;
+    if (!run) return null;
+    return { ...run, collections: this.db.query("SELECT repository,kind,status,adapter,capability_json AS capability,diagnostics_json AS diagnostics FROM collection_results WHERE run_id=? ORDER BY repository,kind").all(runId).map((row: any) => ({ ...row, capability: parse(row.capability), diagnostics: parse(row.diagnostics) })) };
+  }
+
+  queryContext(input: { workspaceId?: string; configId?: string; snapshotId?: string; kind?: FactKind; repository?: string; after?: string; limit?: number }): Record<string, unknown> {
+    let snapshotId = input.snapshotId;
+    let revision: number | undefined;
+    if (!snapshotId) {
+      if (!input.workspaceId || !input.configId) throw new Error("Current context queries require workspaceId and configId");
+      const current = this.db.query("SELECT snapshot_id AS snapshotId,revision FROM current_context WHERE workspace_id=? AND config_id=?").get(input.workspaceId, input.configId) as { snapshotId: string; revision: number } | null;
+      if (!current) throw new Error("No current initialization snapshot");
+      snapshotId = current.snapshotId; revision = current.revision;
+    }
+    const snapshot = this.db.query("SELECT id,run_id AS runId,completeness,content_hash AS contentHash,index_ref_json AS indexRef,created_at AS createdAt FROM context_snapshots WHERE id=?").get(snapshotId) as Record<string, unknown> | null;
+    if (!snapshot) throw new Error(`Unknown context snapshot: ${snapshotId}`);
+    if (typeof snapshot.indexRef === "string") snapshot.indexRef = parse(snapshot.indexRef);
+    const clauses = ["run_id=?"]; const params: unknown[] = [snapshot.runId];
+    if (input.kind) { clauses.push("kind=?"); params.push(input.kind); }
+    if (input.repository !== undefined) { clauses.push("repository=?"); params.push(input.repository); }
+    if (input.after) {
+      let cursor: [string, string, string];
+      try { cursor = JSON.parse(Buffer.from(input.after, "base64url").toString("utf8")); }
+      catch { throw new Error("Invalid context pagination cursor"); }
+      if (!Array.isArray(cursor) || cursor.length !== 3 || cursor.some(item => typeof item !== "string")) throw new Error("Invalid context pagination cursor");
+      clauses.push("(kind>? OR (kind=? AND repository>?) OR (kind=? AND repository=? AND object_key>?))");
+      params.push(cursor[0], cursor[0], cursor[1], cursor[0], cursor[1], cursor[2]);
+    }
+    const limit = Math.min(Math.max(input.limit ?? 100, 1), 500); params.push(limit + 1);
+    const rows = this.db.query(`SELECT id,kind,object_key AS objectKey,repository,value_json AS value,evidence_level AS evidenceLevel,extractor,confidence FROM facts WHERE ${clauses.join(" AND ")} ORDER BY kind,repository,object_key LIMIT ?`).all(...params as any[]) as any[];
+    const truncated = rows.length > limit; const page = rows.slice(0, limit).map(row => ({ ...row, value: parse(row.value) }));
+    const last = page.at(-1);
+    const nextCursor = truncated && last ? Buffer.from(JSON.stringify([last.kind, last.repository, last.objectKey])).toString("base64url") : null;
+    return { snapshot: { ...snapshot, revision }, facts: page, truncated, nextCursor };
+  }
+
+  queryCurrent(workspaceId: string, input: { kind?: FactKind; repository?: string; after?: string; limit?: number } = {}): Record<string, unknown> {
+    const current = this.db.query("SELECT config_id AS configId FROM current_context WHERE workspace_id=? ORDER BY revision DESC LIMIT 1").get(workspaceId) as { configId: string } | null;
+    if (!current) throw new Error("No current initialization snapshot");
+    return this.queryContext({ workspaceId, configId: current.configId, ...input });
+  }
+
+  getInitializationConfiguration(workspaceId: string): Record<string, unknown> {
+    const row = this.db.query(`SELECT c.id,c.revision,c.content_hash AS contentHash,c.config_json AS config
+      FROM scan_configs c LEFT JOIN current_context p ON p.config_id=c.id AND p.workspace_id=?
+      WHERE c.project_id=? ORDER BY (p.workspace_id IS NOT NULL) DESC,c.revision DESC LIMIT 1`).get(workspaceId, this.context.manifest.projectId) as { id: string; revision: number; contentHash: string; config: string } | null;
+    if (!row) throw new Error("No initialization scan configuration");
+    return { ...row, config: parse(row.config) };
+  }
+
+  listWorkspaces(): Array<Record<string, unknown>> {
+    return this.db.query("SELECT id,location,repository_identity AS repositoryIdentity,created_at AS createdAt,updated_at AS updatedAt FROM workspaces WHERE project_id=? ORDER BY created_at").all(this.context.manifest.projectId) as Array<Record<string, unknown>>;
+  }
+
+  compareSnapshots(fromSnapshotId: string, toSnapshotId: string): Record<string, unknown> {
+    if (fromSnapshotId === toSnapshotId) return { comparable: true, fromSnapshotId, toSnapshotId, added: [], changed: [], disappeared: [] };
+    const snapshots = this.db.query("SELECT id,config_id AS configId FROM context_snapshots WHERE id IN (?,?)").all(fromSnapshotId, toSnapshotId) as Array<{ id: string; configId: string }>;
+    if (snapshots.length !== 2) throw new Error("Both context snapshots must exist");
+    const fromMeta = snapshots.find(item => item.id === fromSnapshotId)!;
+    const toMeta = snapshots.find(item => item.id === toSnapshotId)!;
+    if (fromMeta.configId !== toMeta.configId) return { comparable: false, reason: "scan_config_changed", added: [], changed: [], disappeared: [] };
+    const rows = (snapshotId: string) => this.db.query(`SELECT f.kind,f.repository,f.object_key AS objectKey,f.value_json AS value
+      FROM facts f JOIN context_snapshots s ON s.run_id=f.run_id WHERE s.id=?`).all(snapshotId) as Array<{ kind: string; repository: string; objectKey: string; value: string }>;
+    const key = (row: { kind: string; repository: string; objectKey: string }) => `${row.kind}\0${row.repository}\0${row.objectKey}`;
+    const before = new Map(rows(fromSnapshotId).map(row => [key(row), row]));
+    const after = new Map(rows(toSnapshotId).map(row => [key(row), row]));
+    const added = [...after].filter(([item]) => !before.has(item)).map(([, row]) => ({ ...row, value: parse(row.value) }));
+    const disappeared = [...before].filter(([item]) => !after.has(item)).map(([, row]) => ({ ...row, value: parse(row.value) }));
+    const changed = [...after].filter(([item, row]) => before.has(item) && before.get(item)!.value !== row.value).map(([, row]) => ({ before: parse(before.get(key(row))!.value), after: parse(row.value), kind: row.kind, repository: row.repository, objectKey: row.objectKey }));
+    return { comparable: true, fromSnapshotId, toSnapshotId, added, changed, disappeared };
+  }
+
+  createDocumentJob(snapshotId: string, input: { targetPath: string; ownership: "generated" | "human" | "mixed"; templateVersion: string; modelRole?: string; input: unknown }): string {
+    const id = randomUUID(); const timestamp = now();
+    const targetPath = validateRelative(input.targetPath);
+    this.db.query("INSERT OR IGNORE INTO document_jobs(id,snapshot_id,target_path,ownership,template_version,model_role,status,input_hash,created_at,updated_at) VALUES (?,?,?,?,?,?,?,?,?,?)").run(id, snapshotId, targetPath, input.ownership, input.templateVersion, input.modelRole ?? null, input.ownership === "human" ? "complete" : "queued", hash(canonicalJson(input.input)), timestamp, timestamp);
+    const row = this.db.query("SELECT id FROM document_jobs WHERE snapshot_id=? AND target_path=? AND template_version=?").get(snapshotId, targetPath, input.templateVersion) as { id: string };
+    return row.id;
+  }
+
+  latestDocumentHash(targetPath: string): string | null {
+    const row = this.db.query("SELECT output_hash AS outputHash FROM document_jobs WHERE target_path=? AND status='complete' AND output_hash IS NOT NULL ORDER BY updated_at DESC LIMIT 1").get(validateRelative(targetPath)) as { outputHash: string } | null;
+    return row?.outputHash ?? null;
+  }
+
+  documentJobs(snapshotId: string): Array<Record<string, unknown>> {
+    return this.db.query("SELECT id,target_path AS targetPath,ownership,template_version AS templateVersion,model_role AS modelRole,status,output_hash AS outputHash,conflict_path AS conflictPath,error FROM document_jobs WHERE snapshot_id=? ORDER BY target_path").all(snapshotId) as Array<Record<string, unknown>>;
+  }
+
+  failDocumentJob(jobId: string, error: string): void {
+    this.db.query("UPDATE document_jobs SET status='failed',error=?,updated_at=? WHERE id=? AND status NOT IN ('complete','conflict')").run(error.slice(0, 4000), now(), jobId);
+  }
+
+  async writeDocument(jobId: string, content: string, options: { expectedCurrentHash?: string; generatedRegion?: { start: string; end: string } } = {}): Promise<{ status: "complete" | "conflict"; path: string }> {
+    const job = this.db.query("SELECT target_path AS targetPath,ownership,status FROM document_jobs WHERE id=?").get(jobId) as { targetPath: string; ownership: string; status: string } | null;
+    if (!job) throw new Error(`Unknown document job: ${jobId}`);
+    if (job.ownership === "human") throw new Error("Human-owned documents cannot be generated");
+    this.db.query("UPDATE document_jobs SET status='generating',error=NULL,updated_at=? WHERE id=? AND status IN ('queued','failed','pending_review')").run(now(), jobId);
+    const target = path.resolve(this.context.root, job.targetPath);
+    if (target !== this.context.root && !target.startsWith(`${this.context.root}${path.sep}`)) throw new Error("Document path escapes project root");
+    let existing: string | null = null;
+    try { existing = await readFile(target, "utf8"); } catch {}
+    if (existing !== null && options.expectedCurrentHash && hash(existing) !== options.expectedCurrentHash) {
+      const conflict = `${target}.devflow-pending`;
+      await writeFile(conflict, content, "utf8");
+      this.db.query("UPDATE document_jobs SET status='conflict',conflict_path=?,updated_at=? WHERE id=?").run(path.relative(this.context.root, conflict), now(), jobId);
+      return { status: "conflict", path: conflict };
+    }
+    let output = content;
+    if (job.ownership === "mixed") {
+      if (!options.generatedRegion) throw new Error("Mixed documents require a generated region contract");
+      const current = existing ?? ""; const start = current.indexOf(options.generatedRegion.start); const end = current.indexOf(options.generatedRegion.end, start + options.generatedRegion.start.length);
+      if (start < 0 || end < 0) throw new Error("Mixed document generated region is missing");
+      output = `${current.slice(0, start + options.generatedRegion.start.length)}\n${content}\n${current.slice(end)}`;
+    }
+    await mkdir(path.dirname(target), { recursive: true });
+    const temporary = `${target}.${randomUUID()}.tmp`; await writeFile(temporary, output, { encoding: "utf8", flag: "wx" }); await rename(temporary, target);
+    this.db.query("UPDATE document_jobs SET status='complete',output_hash=?,updated_at=? WHERE id=?").run(hash(output), now(), jobId);
+    return { status: "complete", path: target };
+  }
+
+  async backup(target: string): Promise<void> {
+    const resolved = path.resolve(target);
+    await mkdir(path.dirname(resolved), { recursive: true });
+    this.db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+    await writeFile(resolved, this.db.serialize(), { flag: "wx" });
+    const contentStatus = await this.verifyContent();
+    const invalid = contentStatus.filter(item => item.status !== "valid");
+    if (invalid.length) { await rm(resolved, { force: true }); throw new Error(`Cannot back up missing or corrupt content: ${invalid.map(item => item.contentHash).join(", ")}`); }
+    const contentRoot = path.join(projectDataDir(this.context.manifest.projectId), "content");
+    const sidecar = `${resolved}.content`;
+    await cp(contentRoot, sidecar, { recursive: true, errorOnExist: true, force: false });
+    await writeFile(`${resolved}.manifest.json`, `${JSON.stringify({ schemaVersion: INITIALIZATION_SCHEMA_VERSION, projectId: this.context.manifest.projectId, databaseHash: hash(await readFile(resolved)), content: contentStatus }, null, 2)}\n`, { flag: "wx" });
+  }
+
+
+  getAuthority(): { authority: "legacy" | "shadow" | "database"; revision: number; switchedAt: string } {
+    const row = this.db.query("SELECT authority,revision,switched_at AS switchedAt FROM authority_state WHERE project_id=?").get(this.context.manifest.projectId) as { authority: "legacy" | "shadow" | "database"; revision: number; switchedAt: string };
+    return row;
+  }
+
+  switchAuthority(authority: "legacy" | "shadow" | "database", expectedRevision: number): { authority: string; revision: number } {
+    if (authority === "database") {
+      const published = this.db.query("SELECT 1 FROM current_context c JOIN context_snapshots s ON s.id=c.snapshot_id WHERE s.project_id=? LIMIT 1").get(this.context.manifest.projectId);
+      if (!published) throw new Error("Cannot switch to database authority without a current published snapshot");
+    }
+    const result = this.db.query("UPDATE authority_state SET authority=?,revision=revision+1,switched_at=? WHERE project_id=? AND revision=?").run(authority, now(), this.context.manifest.projectId, expectedRevision);
+    if (result.changes !== 1) throw new Error("Initialization authority revision conflict");
+    return { authority, revision: expectedRevision + 1 };
+  }
+
+  registerHistoricalImport(workspaceId: string, sourcePath: string, contentHash: string, snapshotId?: string): string {
+    const id = randomUUID();
+    this.db.query("INSERT OR IGNORE INTO historical_imports(id,project_id,workspace_id,source_path,content_hash,status,snapshot_id,created_at) VALUES (?,?,?,?,?,'shadow',?,?)").run(id, this.context.manifest.projectId, workspaceId, validateRelative(sourcePath), contentHash, snapshotId ?? null, now());
+    const row = this.db.query("SELECT id FROM historical_imports WHERE workspace_id=? AND source_path=? AND content_hash=?").get(workspaceId, validateRelative(sourcePath), contentHash) as { id: string };
+    return row.id;
+  }
+
+  listHistoricalImports(workspaceId: string): Array<Record<string, unknown>> {
+    return this.db.query("SELECT id,source_path AS sourcePath,content_hash AS contentHash,status,snapshot_id AS snapshotId,created_at AS createdAt FROM historical_imports WHERE workspace_id=? ORDER BY created_at").all(workspaceId) as Array<Record<string, unknown>>;
+  }
+
+  async putContent(content: Uint8Array): Promise<{ contentHash: string; path: string; size: number }> {
+    const contentHash = hash(content); const name = contentHash.slice("sha256:".length); const relative = path.join("content", name.slice(0, 2), name);
+    const target = path.join(projectDataDir(this.context.manifest.projectId), relative);
+    const existing = this.db.query("SELECT relative_path AS path,size_bytes AS size FROM content_objects WHERE content_hash=?").get(contentHash) as { path: string; size: number } | null;
+    if (existing) return { contentHash, ...existing };
+    await mkdir(path.dirname(target), { recursive: true });
+    const temporary = `${target}.${randomUUID()}.tmp`;
+    await writeFile(temporary, content, { flag: "wx" }); await rename(temporary, target);
+    this.db.query("INSERT INTO content_objects(content_hash,relative_path,size_bytes,created_at) VALUES (?,?,?,?)").run(contentHash, relative, content.byteLength, now());
+    return { contentHash, path: relative, size: content.byteLength };
+  }
+
+  async verifyContent(): Promise<Array<{ contentHash: string; status: "valid" | "missing" | "corrupt" }>> {
+    const rows = this.db.query("SELECT content_hash AS contentHash,relative_path AS relativePath FROM content_objects").all() as Array<{ contentHash: string; relativePath: string }>;
+    return Promise.all(rows.map(async row => {
+      try {
+        const content = await readFile(path.join(projectDataDir(this.context.manifest.projectId), row.relativePath));
+        return { contentHash: row.contentHash, status: hash(content) === row.contentHash ? "valid" as const : "corrupt" as const };
+      } catch { return { contentHash: row.contentHash, status: "missing" as const }; }
+    }));
+  }
+
+  static async restore(context: InitializationContextLike, backupPath: string): Promise<void> {
+    const resolvedBackup = path.resolve(backupPath);
+    const manifest = JSON.parse(await readFile(`${resolvedBackup}.manifest.json`, "utf8")) as { schemaVersion?: number; projectId?: string; databaseHash?: string; content?: Array<{ contentHash: string; status: string }> };
+    if (manifest.projectId !== context.manifest.projectId || manifest.databaseHash !== hash(await readFile(resolvedBackup))) throw new Error("Backup manifest validation failed");
+    const backup = new Database(resolvedBackup, { readonly: true });
+    try {
+      const meta = backup.query("SELECT version FROM schema_meta LIMIT 1").get() as { version: number } | null;
+      const project = backup.query("SELECT 1 FROM projects WHERE id=?").get(context.manifest.projectId);
+      const violations = backup.query("PRAGMA foreign_key_check").all();
+      if (!meta || meta.version > INITIALIZATION_SCHEMA_VERSION || !project || violations.length) throw new Error("Backup validation failed");
+    } finally { backup.close(); }
+    const sidecar = `${resolvedBackup}.content`;
+    for (const expected of manifest.content ?? []) {
+      const name = expected.contentHash.slice("sha256:".length); const source = path.join(sidecar, name.slice(0, 2), name);
+      if (hash(await readFile(source)) !== expected.contentHash) throw new Error(`Backup content validation failed: ${expected.contentHash}`);
+    }
+    const target = projectControlDatabasePath(context.manifest.projectId); const temporary = `${target}.${randomUUID()}.restore`;
+    await copyFile(resolvedBackup, temporary); await rename(temporary, target).catch(async error => { await rm(temporary, { force: true }); throw error; });
+    await cp(sidecar, path.join(projectDataDir(context.manifest.projectId), "content"), { recursive: true, force: true });
+  }
+}
+
+export async function fingerprintFile(root: string, relativePath: string): Promise<{ path: string; contentHash: string; size: number }> {
+  const relative = validateRelative(relativePath); const target = path.resolve(root, relative);
+  if (!target.startsWith(`${path.resolve(root)}${path.sep}`)) throw new Error(`Path escapes project boundary: ${relativePath}`);
+  const [content, info] = await Promise.all([readFile(target), stat(target)]);
+  return { path: relative, contentHash: hash(content), size: info.size };
+}