@guanlin4924/devflow-pi 0.1.70 → 0.1.71

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guanlin4924/devflow-pi",
-  "version": "0.1.70",
+  "version": "0.1.71",
   "type": "module",
   "description": "Devflow 专项研发 Pi，基于固定版本 OMP Runtime 组装研发状态机、代码智能、设计、实现与质量门禁。",
   "license": "UNLICENSED",

package/src/constants.ts

@@ -1,5 +1,5 @@
 export const PRODUCT_NAME = "Devflow Pi";
-export const PRODUCT_VERSION = "0.1.70";
+export const PRODUCT_VERSION = "0.1.71";
 export const PROJECT_SCHEMA_VERSION = 1;
 export const OMP_RUNTIME_VERSION = "17.2.7";
 

package/src/initialization-store.ts

@@ -1,5 +1,6 @@
 import { createHash, randomUUID } from "node:crypto";
 import { copyFile, cp, mkdir, readFile, realpath, stat, writeFile, rename, rm } from "node:fs/promises";
+import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { Database } from "bun:sqlite";
 
@@ -263,12 +264,33 @@ export class InitializationStore {
         await writeFile(migrationBackup, db.serialize(), { flag: "wx" });
       }
     }
-    db.transaction(() => {
+    const migrate = db.transaction(() => {
       db.exec(SCHEMA);
+      const ensureColumn = (table: string, column: string, definition: string) => {
+        const columns = db.query(`PRAGMA table_info(${table})`).all() as Array<{ name: string }>;
+        if (!columns.some(item => item.name === column)) db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${definition}`);
+      };
+      ensureColumn("context_snapshots", "index_ref_json", "TEXT");
+      ensureColumn("document_jobs", "model_role", "TEXT");
+      ensureColumn("document_jobs", "output_hash", "TEXT");
+      ensureColumn("document_jobs", "conflict_path", "TEXT");
+      ensureColumn("document_jobs", "error", "TEXT");
       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);
-    })();
+      if (!meta) {
+        db.query("INSERT INTO schema_meta(version) VALUES (?)").run(INITIALIZATION_SCHEMA_VERSION);
+      } else {
+        let version = meta.version;
+        if (version < 2) {
+          db.exec("CREATE INDEX IF NOT EXISTS idx_input_snapshots_project ON input_snapshots(project_id, workspace_id, config_id)");
+          db.exec("CREATE INDEX IF NOT EXISTS idx_document_jobs_status ON document_jobs(status, updated_at)");
+          version = 2;
+        }
+        db.query("UPDATE schema_meta SET version=?").run(version);
+      }
+      const verified = db.query("SELECT version FROM schema_meta LIMIT 1").get() as { version: number };
+      if (verified.version !== INITIALIZATION_SCHEMA_VERSION) throw new Error(`Initialization schema migration stopped at ${verified.version}`);
+    });
+    try { migrate(); } catch (error) { db.close(); throw new Error(`Initialization database migration failed: ${error instanceof Error ? error.message : String(error)}`); }
     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);
@@ -311,13 +333,23 @@ export class InitializationStore {
     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 } {
+  createInputSnapshot(workspaceId: string, configId: string, files: Array<{ repository: string; path: string; contentHash: string; size?: number }>, stable = false): { id: string; fingerprint: string; created: boolean } {
+    const binding = this.db.query(`SELECT w.id AS workspaceId,c.id AS configId,w.project_id AS workspaceProject,c.project_id AS configProject,c.config_json AS config
+      FROM workspaces w JOIN scan_configs c ON c.project_id=w.project_id
+      WHERE w.id=? AND c.id=? AND w.project_id=?`).get(workspaceId, configId, this.context.manifest.projectId) as { workspaceId: string; configId: string; workspaceProject: string; configProject: string; config: string } | null;
+    if (!binding) throw new Error("Input snapshot workspace and scan config do not belong to the same project boundary");
+    const configured = new Map((parse<ScanConfigInput>(binding.config).repositories ?? []).map(repository => [repository.name, repository.relativePath]));
+    for (const file of files) {
+      if (!configured.has(file.repository)) throw new Error(`Input snapshot repository is not configured: ${file.repository}`);
+      const base = configured.get(file.repository)!;
+      if (base !== "." && !path.isAbsolute(base) && file.path !== base && !file.path.startsWith(`${base.replace(/\\/g, "/").replace(/\/$/, "")}/`)) throw new Error(`Input snapshot path is outside repository: ${file.repository}/${file.path}`);
+    }
     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);
+      if (stable && !existing.stable) throw new Error("Existing input snapshot is unstable; confirm it explicitly before publishing");
       return { id: existing.id, fingerprint, created: false };
     }
     const id = randomUUID();
@@ -369,27 +401,39 @@ export class InitializationStore {
   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());
+      const repository = input.repository ?? "";
+      this.db.query("DELETE FROM evidence WHERE fact_id IN (SELECT id FROM facts WHERE run_id=? AND repository=? AND kind=?)").run(runId, repository, input.kind);
+      this.db.query("DELETE FROM facts WHERE run_id=? AND repository=? AND kind=?").run(runId, repository, input.kind);
+      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,created_at=excluded.created_at").run(randomUUID(), runId, 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 };
+        this.db.query("INSERT INTO facts(id,run_id,kind,object_key,repository,value_json,evidence_level,extractor,confidence,created_at) VALUES (?,?,?,?,?,?,?,?,?,?)").run(factId, runId, fact.kind, fact.objectKey, fact.repository ?? repository, canonicalJson(fact.value), fact.evidenceLevel, fact.extractor, fact.confidence ?? "inferred", now());
+        const stored = { id: factId };
         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;
+  cancelRun(runId: string, leaseToken: string, expectedRevision: number): boolean {
+    const row = this.db.query("SELECT status,lease_token AS leaseToken,lease_expires_at AS expires,workspace_id AS workspaceId,config_id AS configId FROM initialization_runs WHERE id=?").get(runId) as { status: RunStatus; leaseToken: string; expires: string; workspaceId: string; configId: 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 cancelling");
+    const current = this.db.query("SELECT revision FROM current_context WHERE workspace_id=? AND config_id=?").get(row.workspaceId, row.configId) as { revision: number } | null;
+    if (expectedRevision !== (current?.revision ?? 0)) throw new Error("Initialization run revision conflict");
+    const timestamp = now();
+    return this.db.query("UPDATE initialization_runs SET status='cancelled',updated_at=? WHERE id=? AND lease_token=? AND lease_expires_at>? AND status IN ('preparing','collecting','validating')").run(timestamp, runId, leaseToken, timestamp).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;
+    this.assertWritableRun(runId, leaseToken);
+    const timestamp = now();
+    return this.db.query("UPDATE initialization_runs SET status='failed',error=?,updated_at=? WHERE id=? AND lease_token=? AND lease_expires_at>? AND status IN ('preparing','collecting','validating')").run(error.slice(0, 4000), timestamp, runId, leaseToken, timestamp).changes === 1;
   }
 
   recoverRun(runId: string, leaseMs = 15 * 60_000): { leaseToken: string } {
@@ -399,11 +443,12 @@ export class InitializationStore {
     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);
+    const changed = this.db.query("UPDATE initialization_runs SET lease_token=?,lease_expires_at=?,updated_at=? WHERE id=? AND lease_expires_at<? AND status IN ('preparing','collecting','validating')").run(leaseToken, new Date(Date.now() + leaseMs).toISOString(), now(), runId, now());
+    if (changed.changes !== 1) throw new Error("Initialization run recovery conflict");
     return { leaseToken };
   }
 
-  publishRun(runId: string, leaseToken: string, options: { expectedRevision?: number; completeness?: "complete" | "partial"; indexRef?: Record<string, unknown>; updateCurrent?: boolean } = {}): { snapshotId: string; revision: number } {
+  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");
@@ -422,12 +467,31 @@ export class InitializationStore {
     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}`);
+    if (options.expectedRevision !== (current?.revision ?? 0)) throw new Error(`Current context revision conflict: expected ${options.expectedRevision}, actual ${current?.revision ?? 0}`);
+    if (options.indexRef) {
+      if (options.indexRef.inputFingerprint !== input.fingerprint || options.indexRef.workspaceId !== run.workspaceId || options.indexRef.configId !== run.configId) throw new Error("Index reference does not match initialization input snapshot");
+      if (options.indexRef.status === "complete" && (typeof options.indexRef.generation !== "string" || typeof options.indexRef.snapshotHash !== "string")) throw new Error("Complete index references require generation and snapshot hash");
+      if (options.indexRef.status === "complete") {
+        if (typeof options.indexRef.contentManifestHash !== "string" || typeof options.indexRef.repositoryRevision !== "string") throw new Error("Complete index references require content manifest and repository revision");
+        const indexRoot = path.resolve(this.context.root, String(options.indexRef.stagingPath ?? options.indexRef.path ?? ".planning/code-index"));
+        const immutable = path.resolve(indexRoot, String(options.indexRef.immutablePath ?? `snapshots/${options.indexRef.generation}`));
+        const snapshotFile = path.join(immutable, "SNAPSHOT.json");
+        if (!existsSync(snapshotFile)) throw new Error("Complete index reference does not point to an immutable generation");
+        const actual = hash(readFileSync(snapshotFile));
+        if (actual !== options.indexRef.snapshotHash) throw new Error("Code index snapshot hash does not match index reference");
+        const payload = JSON.parse(readFileSync(snapshotFile, "utf8")) as { generation?: string };
+        if (payload.generation !== options.indexRef.generation) throw new Error("Code index generation does not match SNAPSHOT.json");
+        const workspace = (payload as any).workspace ?? {};
+        if (workspace.contentManifestHash !== options.indexRef.contentManifestHash) throw new Error("Code index content manifest does not match index reference");
+        if (workspace.repositoryRevision !== options.indexRef.repositoryRevision) throw new Error("Code index repository revision does not match index reference");
+      }
+    }
     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());
+      const persistedIndexRef = options.indexRef ? Object.fromEntries(Object.entries(options.indexRef).filter(([key]) => key !== "stagingPath")) : null;
+      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)), persistedIndexRef ? canonicalJson(persistedIndexRef) : null, now());
       if (options.updateCurrent === false) {
         // Shadow imports are immutable and queryable without becoming current.
       } else if (current) {
@@ -484,6 +548,11 @@ export class InitializationStore {
     return this.queryContext({ workspaceId, configId: current.configId, ...input });
   }
 
+  currentRevision(workspaceId: string, configId: string): number {
+    const row = this.db.query("SELECT revision FROM current_context WHERE workspace_id=? AND config_id=?").get(workspaceId, configId) as { revision: number } | null;
+    return row?.revision ?? 0;
+  }
+
   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=?
@@ -498,11 +567,14 @@ export class InitializationStore {
 
   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 }>;
+    const snapshots = this.db.query("SELECT id,project_id AS projectId,workspace_id AS workspaceId,config_id AS configId,input_snapshot_id AS inputSnapshotId FROM context_snapshots WHERE id IN (?,?)").all(fromSnapshotId, toSnapshotId) as Array<{ id: string; projectId: string; workspaceId: string; configId: string; inputSnapshotId: 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.projectId !== toMeta.projectId || fromMeta.workspaceId !== toMeta.workspaceId) return { comparable: false, reason: "workspace_changed", added: [], changed: [], disappeared: [] };
     if (fromMeta.configId !== toMeta.configId) return { comparable: false, reason: "scan_config_changed", added: [], changed: [], disappeared: [] };
+    const manifests = this.db.query("SELECT id,manifest_json AS manifest FROM input_snapshots WHERE id IN (?,?)").all(fromMeta.inputSnapshotId, toMeta.inputSnapshotId) as Array<{ id: string; manifest: string }>;
+    if (manifests.length !== 2) return { comparable: false, reason: "input_snapshot_missing", 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}`;
@@ -539,7 +611,8 @@ export class InitializationStore {
     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 claimed = 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);
+    if (claimed.changes !== 1) throw new Error(`Document job is no longer writable: ${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;
@@ -559,7 +632,8 @@ export class InitializationStore {
     }
     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);
+    const completed = this.db.query("UPDATE document_jobs SET status='complete',output_hash=?,updated_at=? WHERE id=? AND status='generating'").run(hash(output), now(), jobId);
+    if (completed.changes !== 1) throw new Error(`Document job completion conflict: ${jobId}`);
     return { status: "complete", path: target };
   }
 

package/src/project-context.ts

@@ -136,15 +136,17 @@ export async function loadProjectContext(root: string): Promise<ProjectContext>
   const manifestPath = path.join(canonicalRoot, ".devflow", "project.json");
   const manifest = validateManifest(JSON.parse(await readFile(manifestPath, "utf8")), manifestPath);
   const planningRoot = await assertPlanningBoundary(canonicalRoot);
+  if (!(await exists(projectControlDatabasePath(manifest.projectId)))) throw new Error("Project initialization database is not registered; run explicit project initialization first");
   return attachInitializationStore({ root: canonicalRoot, manifestPath, manifest, planningRoot });
 }
 
 async function attachInitializationStore(context: Omit<ProjectContext, "workspaceId" | "controlDatabasePath">): Promise<ProjectContext> {
   const store = await InitializationStore.open(context);
   try {
-    const workspace = await store.registerWorkspace();
-    store.putScanConfig({ mode: "full", repositories: [{ name: context.manifest.name, relativePath: ".", role: "other" }] });
-    return { ...context, workspaceId: workspace.id, controlDatabasePath: projectControlDatabasePath(context.manifest.projectId) };
+    const location = await realpath(context.root);
+    const workspace = store.listWorkspaces().find(item => item.location === location);
+    if (!workspace) throw new Error("Project workspace is not registered; run explicit project initialization first");
+    return { ...context, workspaceId: String(workspace.id), controlDatabasePath: projectControlDatabasePath(context.manifest.projectId) };
   } finally {
     store.close();
   }
@@ -174,6 +176,8 @@ export async function initializeProject(root: string): Promise<{ context: Projec
     createdAt: new Date().toISOString(),
   };
   await atomicWriteJson(manifestPath, manifest);
+  const bootstrapStore = await InitializationStore.open({ root: canonicalRoot, manifest });
+  try { await bootstrapStore.registerWorkspace(); } finally { bootstrapStore.close(); }
   return {
     context: await attachInitializationStore({ root: canonicalRoot, manifestPath, manifest, planningRoot }),
     created: true,

package/src/project-documents.ts

@@ -77,6 +77,10 @@ function table(headers: string[], rows: unknown[][]): string {
 }
 function yamlString(value: string): string { return JSON.stringify(value); }
 function frontmatter(fields: Record<string, string | boolean | string[] | null | undefined>): string {
+  if (fields.source_snapshot && !fields.snapshot_id) fields.snapshot_id = fields.source_snapshot;
+  if (fields.source_snapshot) fields.generated = true;
+  if (fields.source_snapshot && !fields.generated_at) fields.generated_at = new Date().toISOString();
+  if (fields.source_snapshot && !fields.source_revision) fields.source_revision = fields.code_index_generation ?? "unknown";
   const lines = ["---"];
   for (const [key, value] of Object.entries(fields)) {
     if (value === undefined || value === null) continue;

package/src/project-initializer.ts

@@ -1,5 +1,5 @@
-import { createHash } from "node:crypto";
-import { readFile, readdir, stat } from "node:fs/promises";
+import { createHash, randomUUID } from "node:crypto";
+import { readFile, readdir, stat, rename, rm } from "node:fs/promises";
 import path from "node:path";
 
 import { FACT_KINDS, InitializationStore, type FactInput, type FactKind, type ScanConfigInput } from "./initialization-store.ts";
@@ -177,7 +177,7 @@ async function runProcess(argv: string[], cwd: string): Promise<{ stdout: string
 
 async function buildCodeIndex(context: ProjectContext, config: ScanConfigInput): Promise<Record<string, unknown>> {
   const script = path.resolve(import.meta.dir, "../plugins/devflow-intel/skills/workflow-code-index/scripts/code_index.py");
-  const output = ".planning/code-index";
+  const output = `.planning/.code-index-pending-${randomUUID()}`;
   const codebases = config.repositories.flatMap(repository => ["--codebase", `${repository.name}:${path.resolve(context.root, repository.relativePath)}:${repository.role}`]);
   await runProcess(["python3", script, "scan", "--root", context.root, "--output", output, ...codebases], context.root);
   await runProcess(["python3", script, "validate", "--index", output], context.root);
@@ -185,7 +185,29 @@ async function buildCodeIndex(context: ProjectContext, config: ScanConfigInput):
   const snapshotPath = path.join(context.root, output, "SNAPSHOT.json");
   const bytes = await readFile(snapshotPath); const snapshot = JSON.parse(bytes.toString("utf8")) as Record<string, unknown>;
   if (!snapshot.generation || !snapshot.immutablePath) throw new Error("Code index did not publish an immutable generation");
-  return { path: output, generation: snapshot.generation, immutablePath: snapshot.immutablePath, snapshotHash: digest(bytes), status: "complete" };
+  const workspace = (snapshot.workspace ?? {}) as Record<string, unknown>;
+  return { path: ".planning/code-index", stagingPath: output, generation: snapshot.generation, immutablePath: snapshot.immutablePath, snapshotHash: digest(bytes), contentManifestHash: workspace.contentManifestHash, repositoryRevision: workspace.repositoryRevision, status: "complete" };
+}
+
+async function promoteCodeIndex(context: ProjectContext, indexRef: Record<string, unknown>): Promise<() => Promise<void>> {
+  const stagingPath = typeof indexRef.stagingPath === "string" ? path.resolve(context.root, indexRef.stagingPath) : null;
+  const target = path.resolve(context.root, ".planning/code-index");
+  if (!stagingPath) return async () => {};
+  const previous = `${target}.previous-${randomUUID()}`;
+  const existing = await stat(target).catch(() => null);
+  if (existing) await rename(target, previous);
+  try {
+    await rename(stagingPath, target);
+    delete indexRef.stagingPath;
+    return async () => {
+      await rm(target, { recursive: true, force: true });
+      if (existing) await rename(previous, target);
+    };
+  } catch (error) {
+    await rm(target, { recursive: true, force: true }).catch(() => {});
+    if (existing) await rename(previous, target).catch(() => {});
+    throw error;
+  }
 }
 
 export async function runProjectInitialization(context: ProjectContext, input: { config?: ScanConfigInput; requestId?: string; documentMode?: "low-tier-model" | "template" | "none"; organizer?: import("./project-documents.ts").LowTierDocumentOrganizer; switchAuthority?: boolean } = {}): Promise<InitializationProgress> {
@@ -236,13 +258,22 @@ export async function runProjectInitialization(context: ProjectContext, input: {
         facts: status === "complete" ? repositoryFacts : [],
       });
     }
-    const indexRef = config.mode === "full" ? await buildCodeIndex(context, config) : { status: "skipped", reason: "explicit_fast_mode" };
+    const indexRef = config.mode === "full"
+      ? { ...(await buildCodeIndex(context, config)), inputFingerprint: inputSnapshot.fingerprint, workspaceId: workspace.id, configId: storedConfig.id }
+      : { status: "skipped", reason: "explicit_fast_mode", inputFingerprint: inputSnapshot.fingerprint, workspaceId: workspace.id, configId: storedConfig.id };
     const after = await scan(context, config);
     const afterManifest = frozenManifest(after);
     const verified = store.createInputSnapshot(workspace.id, storedConfig.id, afterManifest, false);
     if (verified.fingerprint !== inputSnapshot.fingerprint) throw new Error("Source changed during initialization; refusing to publish mixed input");
     store.confirmInputSnapshot(inputSnapshot.id, inputSnapshot.fingerprint);
-    const published = store.publishRun(run.id, run.leaseToken, { expectedRevision: undefined, indexRef });
+    const rollbackIndex = await promoteCodeIndex(context, indexRef);
+    let published: { snapshotId: string; revision: number };
+    try {
+      published = store.publishRun(run.id, run.leaseToken, { expectedRevision: store.currentRevision(workspace.id, storedConfig.id), indexRef });
+    } catch (error) {
+      await rollbackIndex();
+      throw error;
+    }
     if (input.switchAuthority !== false) {
       const authority = store.getAuthority();
       if (authority.authority === "legacy") store.switchAuthority("database", authority.revision);

package/src/project-migration.ts

@@ -22,7 +22,8 @@ export async function importLegacyInitialization(context: ProjectContext, source
   try {
     const workspace = await store.registerWorkspace();
     const config = store.putScanConfig({ mode: "fast", repositories: [{ name: "legacy-materials", relativePath: ".", role: "other" }], requiredKinds: ["evidence"], adapterVersions: { "legacy-import": "1" } });
-    const input = store.createInputSnapshot(workspace.id, config.id, documents.map(item => ({ repository: "legacy-materials", path: item.relative, contentHash: item.contentHash, size: item.size })), true);
+    const input = store.createInputSnapshot(workspace.id, config.id, documents.map(item => ({ repository: "legacy-materials", path: item.relative, contentHash: item.contentHash, size: item.size })), false);
+    store.confirmInputSnapshot(input.id, input.fingerprint);
     const run = store.startRun({ workspaceId: workspace.id, configId: config.id, inputSnapshotId: input.id, requestId });
     if (!run.reused) store.recordCollection(run.id, run.leaseToken, {
       kind: "evidence", status: "complete", adapter: "legacy-import@1",
@@ -30,7 +31,7 @@ export async function importLegacyInitialization(context: ProjectContext, source
     });
     const snapshot = run.reused && store.getRun(run.id)?.publishedSnapshotId
       ? { snapshotId: String(store.getRun(run.id)!.publishedSnapshotId) }
-      : store.publishRun(run.id, run.leaseToken, { completeness: "partial", updateCurrent: false });
+      : store.publishRun(run.id, run.leaseToken, { expectedRevision: 0, completeness: "partial", updateCurrent: false });
     const imports = documents.map(item => store.registerHistoricalImport(workspace.id, item.relative, item.contentHash, snapshot.snapshotId));
     const authority = store.getAuthority();
     if (authority.authority === "legacy") store.switchAuthority("shadow", authority.revision);