@voybio/ace-swarm 2.4.3 → 2.4.6

package/dist/store/bootstrap-store.js

@@ -15,13 +15,14 @@
  *   9. Materialize hook context snapshot
  *  10. Write tasks/todo.md starter
  */
-import { mkdirSync, existsSync } from "fs";
+import { mkdirSync, existsSync, writeFileSync } from "fs";
 import { join, dirname, resolve } from "path";
 import { fileURLToPath } from "url";
 import { openStore } from "./ace-packed-store.js";
 import { bakeAllCoreKnowledge } from "./knowledge-bake.js";
 import { bakeTopology } from "./topology-bake.js";
 import { buildCatalog } from "./catalog-builder.js";
+import { migratePackageGateContract, recordPackageGateContractVersion, } from "./gate-contract-migration.js";
 import { HostFileMaterializer } from "./materializers/host-file-materializer.js";
 import { ProjectionManager } from "./materializers/projection-manager.js";
 import { TodoSyncer } from "./materializers/todo-syncer.js";
@@ -104,6 +105,11 @@ async function materializeStoreSurfaces(store, workspaceRoot, opts) {
 }
 // Artifacts that receive live timestamp substitution on first seed.
 const TIMESTAMPED_ARTIFACT_RELS = new Set(["agent-state/STATUS.md", "agent-state/EVIDENCE_LOG.md"]);
+const GATE_CONTRACT_OPERATIONAL_ARTIFACT_RELS = [
+    "agent-state/TEAL_CONFIG.md",
+    "agent-state/QUALITY_GATES.md",
+    "agent-state/INTERFACE_REGISTRY.md",
+];
 async function seedOperationalArtifacts(store) {
     const bootstrapTs = new Date().toISOString();
     for (const relPath of OPERATIONAL_ARTIFACT_REL_PATHS) {
@@ -117,8 +123,23 @@ async function seedOperationalArtifacts(store) {
         await store.setBlob(operationalArtifactKey(relPath), content);
     }
 }
+async function syncOperationalArtifacts(store, relPaths) {
+    for (const relPath of relPaths) {
+        const knowledgeKey = `knowledge/agent-state/${relPath.replace(/^agent-state\//, "")}`;
+        const content = (await store.getBlob(knowledgeKey)) ?? "";
+        await store.setBlob(operationalArtifactKey(relPath), content);
+    }
+}
+async function migrateExistingStoreGateContract(store, workspaceRoot, assetsRoot, warnings) {
+    const migration = await migratePackageGateContract(store, workspaceRoot, assetsRoot);
+    warnings.push(...migration.messages);
+    if (migration.changed) {
+        await syncOperationalArtifacts(store, GATE_CONTRACT_OPERATIONAL_ARTIFACT_RELS);
+    }
+}
 export async function bootstrapStoreWorkspace(opts) {
     const { workspaceRoot, force = false } = opts;
+    const assetsRoot = getAssetsRoot();
     const resolved = await ensureCanonicalWorkspaceStore(workspaceRoot, {
         operationLabel: "bootstrapStoreWorkspace",
     });
@@ -131,13 +152,14 @@ export async function bootstrapStoreWorkspace(opts) {
             return { storePath, agents: 0, modules: { gates: 0, roles: 0, schemas: 0 }, materialized, warnings };
         }
         if (existsSync(storePath) && !force) {
-            if (!(opts.includeMcpConfig ?? false) && !(opts.includeClientConfigBundle ?? false) && !opts.llm) {
-                warnings.push(`Store already exists at ${storePath}. Use --force to reinitialize, or run 'ace migrate' to import existing state.`);
-                return { storePath, agents: 0, modules: { gates: 0, roles: 0, schemas: 0 }, materialized, warnings };
-            }
             const existingStore = await openStore(storePath);
             try {
-                await seedOperationalArtifacts(existingStore);
+                await migrateExistingStoreGateContract(existingStore, workspaceRoot, assetsRoot, warnings);
+                if (!(opts.includeMcpConfig ?? false) && !(opts.includeClientConfigBundle ?? false) && !opts.llm) {
+                    const agents = (await existingStore.listAgents()).length;
+                    warnings.push(`Reused existing store at ${storePath}. Refreshed package gate contract state.`);
+                    return { storePath, agents, modules: { gates: 0, roles: 0, schemas: 0 }, materialized, warnings };
+                }
                 materialized.push(...(await materializeStoreSurfaces(existingStore, workspaceRoot, opts)));
                 const agents = (await existingStore.listAgents()).length;
                 warnings.push(`Reused existing store at ${storePath} and refreshed host materializations.`);
@@ -163,8 +185,8 @@ export async function bootstrapStoreWorkspace(opts) {
                 include_mcp_config: opts.includeMcpConfig ?? false,
                 include_client_config_bundle: opts.includeClientConfigBundle ?? false,
             });
-            const assetsRoot = getAssetsRoot();
             const knowledge = await bakeAllCoreKnowledge(store, assetsRoot);
+            await recordPackageGateContractVersion(store);
             await bakeTopology(store, assetsRoot);
             await store.setJSON("state/handoffs/__index", []);
             await store.setJSON("state/todo/index", []);
@@ -197,6 +219,39 @@ export async function bootstrapStoreWorkspace(opts) {
     }, { operation_label: "bootstrapStoreWorkspace" });
 }
 // ── ace repair ────────────────────────────────────────────────────────────────
+const GOAL_STORE_KEY_PREFIX = "state/artifacts/agent-state/goals/";
+/**
+ * G1 recovery: restore goal records that a pre-fix `ace compact` swept into the
+ * store. `GoalRepository` reads plain files, so a swept goal is invisible to the
+ * engine even though its bytes survive in ACEPACK. Idempotent: never overwrites
+ * a goal file that is already on disk (disk is authoritative for goals).
+ */
+async function restoreSweptGoalState(store, workspaceRoot, warnings) {
+    const goalsDir = join(workspaceRoot, "agent-state", "goals");
+    const keys = [];
+    for await (const key of store.list()) {
+        if (key.startsWith(GOAL_STORE_KEY_PREFIX))
+            keys.push(key);
+    }
+    let restored = 0;
+    for (const key of keys) {
+        const name = key.slice(GOAL_STORE_KEY_PREFIX.length);
+        if (!name || name.includes("/"))
+            continue;
+        const dest = join(goalsDir, name);
+        if (existsSync(dest))
+            continue;
+        const body = await store.getBlob(key);
+        if (body === undefined) {
+            warnings.push(`goal restore: key ${key} present in index but unreadable`);
+            continue;
+        }
+        mkdirSync(goalsDir, { recursive: true });
+        writeFileSync(dest, body);
+        restored += 1;
+    }
+    return restored;
+}
 export async function repairWorkspace(workspaceRoot) {
     const resolved = await ensureCanonicalWorkspaceStore(workspaceRoot, {
         operationLabel: "repairWorkspace",
@@ -215,7 +270,24 @@ export async function repairWorkspace(workspaceRoot) {
     const { storePath } = resolved;
     const warnings = [...resolved.warnings];
     const store = await openStore(storePath);
+    const assetsRoot = getAssetsRoot();
     try {
+        // A pre-fix `ace cache` could have ingested the write-coordinator's lease
+        // file as a permanent store key (it scanned .write.lock/ before that
+        // path was excluded). Delete it if present — it's transient runtime
+        // state, never a durable artifact.
+        const pollutedLeaseKeyPrefix = "state/artifacts/agent-state/ace-state.ace.write.lock/";
+        for await (const key of store.list()) {
+            if (key.startsWith(pollutedLeaseKeyPrefix)) {
+                await store.delete(key);
+                warnings.push(`Removed stale write-lock lease key ingested by a prior 'ace cache' run: ${key}`);
+            }
+        }
+        const restoredGoals = await restoreSweptGoalState(store, workspaceRoot, warnings);
+        if (restoredGoals > 0) {
+            warnings.push(`Restored ${restoredGoals} goal file(s) swept into the store by a pre-fix \`ace compact\`.`);
+        }
+        await migrateExistingStoreGateContract(store, workspaceRoot, assetsRoot, warnings);
         const hostPolicy = (await store.getJSON("meta/host_materialization")) ?? {};
         // Re-materialize host files
         const hostMat = new HostFileMaterializer(store, workspaceRoot);
@@ -236,7 +308,7 @@ export async function repairWorkspace(workspaceRoot) {
     return warnings;
 }
 // ── ace compact ───────────────────────────────────────────────────────────────
-export async function compactWorkspace(workspaceRoot) {
+export async function compactWorkspace(workspaceRoot, options = {}) {
     const resolved = await ensureCanonicalWorkspaceStore(workspaceRoot, {
         operationLabel: "compactWorkspace",
     });
@@ -254,6 +326,12 @@ export async function compactWorkspace(workspaceRoot) {
         await store.close();
     }
     const after = statSync(storePath).size;
-    return { before, after };
+    const sweep = options.sweep === false
+        ? undefined
+        : await (await import("./cache-workspace.js")).cacheWorkspaceArtifacts(workspaceRoot, {
+            clean: true,
+            minAgeMs: 0,
+        });
+    return { before, after, sweep };
 }
 //# sourceMappingURL=bootstrap-store.js.map

package/dist/store/cache-workspace.d.ts

@@ -1,6 +1,13 @@
 export interface CacheWorkspaceOptions {
     dryRun?: boolean;
     clean?: boolean;
+    /**
+     * Sweep-lite guard: do not ingest or delete files newer than this many
+     * milliseconds. This keeps lifecycle-triggered sweeps from racing a host
+     * agent that just wrote a loose compatibility file.
+     */
+    minAgeMs?: number;
+    gcSemanticCache?: boolean;
 }
 export interface CacheWorkspaceResult {
     storePath: string;
@@ -9,6 +16,7 @@ export interface CacheWorkspaceResult {
     scanned_files: number;
     cached_files: number;
     removed_files: number;
+    removed_semantic_cache_files: number;
     kept_projected_files: number;
     skipped_files: number;
     warnings: string[];

package/dist/store/cache-workspace.js

@@ -1,4 +1,4 @@
-import { existsSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
 import { dirname, isAbsolute, join, relative } from "node:path";
 import { ACE_ROOT_REL, isProjectedAceWorkspacePath, mapAceWorkspaceRelativePath, resolveStoreFallbackKeysForPath, } from "../helpers.js";
 import { normalizeRelPath } from "../shared.js";
@@ -9,6 +9,10 @@ const SCAN_ROOTS_REL = [
     ".agents/ACE/agent-state",
     ".agents/ACE/tasks",
     ".agents/ACE/skills",
+    // Root-level tasks/ — home of create_handoff's SWARM_HANDOFF.*.json payloads
+    // (see resolveStoreFallbackKeys). Distinct from .agents/ACE/tasks/, which
+    // holds the projected todo.md and is scanned separately above.
+    "tasks",
 ];
 function isInside(base, target) {
     const rel = relative(base, target);
@@ -49,7 +53,58 @@ function isTextBuffer(input) {
 function selectScanRoots(workspaceRoot) {
     return SCAN_ROOTS_REL.map((relPath) => join(workspaceRoot, relPath)).filter((abs) => existsSync(abs));
 }
+function removeSemanticCache(workspaceRoot, minAgeMs, dryRun) {
+    const root = join(workspaceRoot, ".tmp", "cache", "semantic");
+    if (!existsSync(root))
+        return 0;
+    const now = Date.now();
+    let removed = 0;
+    for (const absPath of collectFiles(root)) {
+        const stats = statSync(absPath);
+        if (now - stats.mtimeMs < minAgeMs)
+            continue;
+        if (!dryRun) {
+            rmSync(absPath, { force: true });
+            pruneEmptyParents(absPath, root);
+        }
+        removed += 1;
+    }
+    return removed;
+}
+/**
+ * Paths that must never be scanned/ingested by the sweeper, even though they
+ * live under a scanned root: an active write-coordinator lease dir (ingesting
+ * it destroys a live lease or pollutes the store with a permanent key for a
+ * transient file), temp/rename-in-flight files, and quarantined corrupt-store
+ * copies left by M0.5's write guard.
+ */
+function isUnsafeToScan(canonicalPath) {
+    return (/(^|\/)ace-state\.ace\.write\.lock(\/|$)/.test(canonicalPath) ||
+        /\.tmp$/.test(canonicalPath) ||
+        /\.corrupt-\d+$/.test(canonicalPath) ||
+        /ace-state\.ace(\.[^/]+)?$/.test(canonicalPath));
+}
+/**
+ * Engine-owned durable state that lives under a scanned root but is NOT
+ * store-managed. `GoalRepository` (src/store/repositories/goal-repository.ts)
+ * reads and writes these as plain files via `readFileSync`/`renameSync`;
+ * ingesting and deleting them makes every goal unreadable (`Unknown goal_id`)
+ * and kills any detached `ace goal run` mid-flight. The sweep must leave them
+ * on disk. See REPORT_GOAL_EVAL_PLAYBOOK_MITIGATIONS_2026-07-09.md (G1).
+ */
+const SWEEP_EXCLUDED_DIRS = ["agent-state/goals"];
+function isSweepExcluded(canonicalPath) {
+    return SWEEP_EXCLUDED_DIRS.some((dir) => canonicalPath === dir || canonicalPath.startsWith(`${dir}/`));
+}
 function isCacheableAcePath(path) {
+    if (isUnsafeToScan(path))
+        return false;
+    // Sits above the SWARM_HANDOFF early-return: an exclusion must never be
+    // overridden by a later allow.
+    if (isSweepExcluded(path))
+        return false;
+    if (/^tasks\/SWARM_HANDOFF\..+\.json$/.test(path))
+        return true;
     return path === "agent-state"
         || path.startsWith("agent-state/")
         || path.startsWith(`${ACE_ROOT_REL}/`);
@@ -57,6 +112,8 @@ function isCacheableAcePath(path) {
 export async function cacheWorkspaceArtifacts(workspaceRoot, options = {}) {
     const dryRun = options.dryRun ?? false;
     const clean = options.clean ?? true;
+    const minAgeMs = options.minAgeMs ?? 0;
+    const gcSemanticCache = options.gcSemanticCache ?? true;
     const storePath = getWorkspaceStorePath(workspaceRoot);
     if (!existsSync(storePath)) {
         throw new Error(`No store found at ${storePath}. Run 'ace init' first.`);
@@ -72,6 +129,11 @@ export async function cacheWorkspaceArtifacts(workspaceRoot, options = {}) {
             scanned += 1;
             const relPath = normalizeRelPath(relative(workspaceRoot, absPath));
             const canonicalPath = mapAceWorkspaceRelativePath(relPath);
+            const stats = statSync(absPath);
+            if (minAgeMs > 0 && Date.now() - stats.mtimeMs < minAgeMs) {
+                skipped += 1;
+                continue;
+            }
             if (!isCacheableAcePath(canonicalPath)) {
                 skipped += 1;
                 continue;
@@ -129,6 +191,9 @@ export async function cacheWorkspaceArtifacts(workspaceRoot, options = {}) {
             pruneEmptyParents(candidate.absPath, pruneRoot);
         }
     }
+    const removedSemanticCache = gcSemanticCache
+        ? removeSemanticCache(workspaceRoot, minAgeMs, dryRun)
+        : 0;
     return {
         storePath,
         dry_run: dryRun,
@@ -136,6 +201,7 @@ export async function cacheWorkspaceArtifacts(workspaceRoot, options = {}) {
         scanned_files: scanned,
         cached_files: candidates.length,
         removed_files: removed,
+        removed_semantic_cache_files: removedSemanticCache,
         kept_projected_files: keptProjected,
         skipped_files: skipped,
         warnings,

package/dist/store/crc32.d.ts

@@ -0,0 +1,2 @@
+export declare function crc32(bytes: Uint8Array): number;
+//# sourceMappingURL=crc32.d.ts.map

package/dist/store/crc32.js

@@ -0,0 +1,16 @@
+const CRC32_TABLE = new Uint32Array(256);
+for (let i = 0; i < CRC32_TABLE.length; i += 1) {
+    let c = i;
+    for (let bit = 0; bit < 8; bit += 1) {
+        c = (c & 1) ? (0xedb88320 ^ (c >>> 1)) : (c >>> 1);
+    }
+    CRC32_TABLE[i] = c >>> 0;
+}
+export function crc32(bytes) {
+    let crc = 0xffffffff;
+    for (const byte of bytes) {
+        crc = CRC32_TABLE[(crc ^ byte) & 0xff] ^ (crc >>> 8);
+    }
+    return (crc ^ 0xffffffff) >>> 0;
+}
+//# sourceMappingURL=crc32.js.map

package/dist/store/fsck.d.ts

@@ -0,0 +1,16 @@
+export interface StoreFsckCheck {
+    name: string;
+    ok: boolean;
+    detail: string;
+}
+export interface StoreFsckResult {
+    ok: boolean;
+    repaired: boolean;
+    storePath: string;
+    checks: StoreFsckCheck[];
+    repaired_paths: string[];
+}
+export declare function fsckWorkspaceStore(workspaceRoot: string, options?: {
+    repair?: boolean;
+}): StoreFsckResult;
+//# sourceMappingURL=fsck.d.ts.map

package/dist/store/fsck.js

@@ -0,0 +1,240 @@
+import { existsSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { basename, isAbsolute, join, relative } from "node:path";
+import { HEADER_SIZE, HEADER_SIZE_V1, MAGIC } from "./types.js";
+import { getCanonicalWorkspaceStorePath, getLegacyWorkspaceStorePath, getWorkspaceStorePath } from "./store-snapshot.js";
+import { crc32 } from "./crc32.js";
+import { classifyStoreWriteLockDir } from "./write-coordinator.js";
+const DECODE = new TextDecoder();
+function u32(bytes, offset) {
+    return new DataView(bytes.buffer, bytes.byteOffset).getUint32(offset, false);
+}
+function u64(bytes, offset) {
+    const view = new DataView(bytes.buffer, bytes.byteOffset);
+    return view.getUint32(offset, false) * 2 ** 32 + view.getUint32(offset + 4, false);
+}
+function minEventSectionLength(count) {
+    const pad = (4 - (count % 4)) % 4;
+    return 4 + 8 * count + count + count + count + pad + 4 * count + 4 * count + 4;
+}
+function isInside(base, target) {
+    const rel = relative(base, target);
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+function collectOrphans(root) {
+    const stateRoot = join(root, "agent-state");
+    if (!existsSync(stateRoot))
+        return [];
+    const found = [];
+    const walk = (dir) => {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const abs = join(dir, entry.name);
+            const rel = relative(root, abs);
+            if (/(^|\/)ace-state\.ace\.write\.lock(\/|$)/.test(rel)) {
+                found.push({ path: abs, kind: "lock" });
+                if (entry.isDirectory())
+                    continue;
+            }
+            else if (/\.tmp$/.test(entry.name)) {
+                found.push({ path: abs, kind: "tmp" });
+                if (entry.isDirectory())
+                    continue;
+            }
+            else if (/\.corrupt-\d+$/.test(entry.name)) {
+                found.push({ path: abs, kind: "corrupt" });
+                if (entry.isDirectory())
+                    continue;
+            }
+            if (entry.isDirectory())
+                walk(abs);
+        }
+    };
+    walk(stateRoot);
+    return found;
+}
+function validateEventSection(bytes) {
+    if (bytes.length < 4)
+        return "event section shorter than count field";
+    const count = u32(bytes, 0);
+    const min = minEventSectionLength(count);
+    if (bytes.length < min)
+        return `event section count=${count} requires >= ${min} bytes, got ${bytes.length}`;
+    let pos = 4 + 8 * count + count + count + count + ((4 - (count % 4)) % 4);
+    const offsets = [];
+    const lengths = [];
+    for (let i = 0; i < count; i += 1) {
+        offsets.push(u32(bytes, pos));
+        pos += 4;
+    }
+    for (let i = 0; i < count; i += 1) {
+        lengths.push(u32(bytes, pos));
+        pos += 4;
+    }
+    const poolLength = u32(bytes, pos);
+    pos += 4;
+    if (bytes.length < pos + poolLength) {
+        return `event payload pool truncated (declared=${poolLength}, available=${bytes.length - pos})`;
+    }
+    for (let i = 0; i < count; i += 1) {
+        if (offsets[i] + lengths[i] > poolLength) {
+            return `event ${i} payload exceeds pool bounds (offset=${offsets[i]}, length=${lengths[i]}, pool=${poolLength})`;
+        }
+    }
+    return undefined;
+}
+export function fsckWorkspaceStore(workspaceRoot, options = {}) {
+    const storePath = getWorkspaceStorePath(workspaceRoot);
+    const checks = [];
+    const repairedPaths = [];
+    const canonicalPath = getCanonicalWorkspaceStorePath(workspaceRoot);
+    const legacyPath = getLegacyWorkspaceStorePath(workspaceRoot);
+    checks.push({
+        name: "store:exists",
+        ok: existsSync(storePath),
+        detail: existsSync(storePath) ? storePath : `missing: ${storePath}`,
+    });
+    checks.push({
+        name: "store:legacy-dual-store",
+        ok: !(existsSync(canonicalPath) && existsSync(legacyPath)),
+        detail: existsSync(canonicalPath) && existsSync(legacyPath)
+            ? `both canonical and legacy stores exist (${canonicalPath}, ${legacyPath})`
+            : "no dual-store conflict",
+    });
+    if (existsSync(storePath)) {
+        try {
+            const file = readFileSync(storePath);
+            checks.push({
+                name: "header:size",
+                ok: file.length >= HEADER_SIZE,
+                detail: `${file.length} bytes`,
+            });
+            if (file.length >= HEADER_SIZE_V1) {
+                const magic = DECODE.decode(file.subarray(0, 8));
+                const version = u32(file, 8);
+                const kvIndexOffset = u64(file, 16);
+                const kvIndexLength = u64(file, 24);
+                const kvChunkEnd = version >= 2 ? u64(file, 32) : kvIndexOffset;
+                const evtOffset = version >= 2 ? u64(file, 40) : 0;
+                const evtLength = version >= 2 ? u64(file, 48) : 0;
+                const evtCount = version >= 2 ? u32(file, 56) : 0;
+                checks.push({ name: "header:magic", ok: magic === MAGIC, detail: magic });
+                checks.push({ name: "header:version", ok: version >= 1 && version <= 2, detail: String(version) });
+                const headerOrderOk = version >= 2
+                    ? HEADER_SIZE <= kvChunkEnd &&
+                        kvChunkEnd <= evtOffset &&
+                        evtOffset <= kvIndexOffset &&
+                        kvIndexOffset + kvIndexLength <= file.length
+                    : HEADER_SIZE_V1 <= kvIndexOffset && kvIndexOffset + kvIndexLength <= file.length;
+                checks.push({
+                    name: "header:regions",
+                    ok: headerOrderOk,
+                    detail: `kvChunkEnd=${kvChunkEnd}, evtOffset=${evtOffset}, evtLength=${evtLength}, kvIndexOffset=${kvIndexOffset}, kvIndexLength=${kvIndexLength}, fileLength=${file.length}`,
+                });
+                if (headerOrderOk) {
+                    const indexRaw = file.subarray(kvIndexOffset, kvIndexOffset + kvIndexLength);
+                    let index;
+                    try {
+                        index = JSON.parse(DECODE.decode(indexRaw));
+                        checks.push({ name: "index:parse", ok: true, detail: `${Object.keys(index).length} entries` });
+                    }
+                    catch (error) {
+                        checks.push({ name: "index:parse", ok: false, detail: error instanceof Error ? error.message : String(error) });
+                    }
+                    if (index) {
+                        const minChunkOffset = version >= 2 ? HEADER_SIZE : HEADER_SIZE_V1;
+                        const maxChunkEnd = version >= 2 ? kvChunkEnd : kvIndexOffset;
+                        for (const [key, entry] of Object.entries(index)) {
+                            const boundsOk = Number.isFinite(entry.offset) &&
+                                Number.isFinite(entry.length) &&
+                                entry.offset >= minChunkOffset &&
+                                entry.offset + 4 + entry.length <= maxChunkEnd;
+                            checks.push({
+                                name: `chunk:${key}:bounds`,
+                                ok: boundsOk,
+                                detail: `offset=${entry.offset}, length=${entry.length}, maxChunkEnd=${maxChunkEnd}`,
+                            });
+                            if (!boundsOk)
+                                continue;
+                            const prefix = u32(file, entry.offset);
+                            checks.push({
+                                name: `chunk:${key}:length-prefix`,
+                                ok: prefix === entry.length,
+                                detail: `prefix=${prefix}, index=${entry.length}`,
+                            });
+                            if (typeof entry.crc === "number") {
+                                const chunk = file.subarray(entry.offset + 4, entry.offset + 4 + entry.length);
+                                const actual = crc32(chunk);
+                                checks.push({
+                                    name: `chunk:${key}:crc32`,
+                                    ok: actual === entry.crc,
+                                    detail: `expected=${entry.crc}, actual=${actual}`,
+                                });
+                            }
+                        }
+                    }
+                    if (version >= 2) {
+                        const eventError = validateEventSection(file.subarray(evtOffset, evtOffset + evtLength));
+                        checks.push({
+                            name: "events:section",
+                            ok: !eventError,
+                            detail: eventError ?? `count=${evtCount}, length=${evtLength}`,
+                        });
+                    }
+                }
+            }
+        }
+        catch (error) {
+            checks.push({
+                name: "store:read",
+                ok: false,
+                detail: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    const allOrphans = collectOrphans(workspaceRoot);
+    const failingOrphans = [];
+    for (const orphan of allOrphans) {
+        if (orphan.kind !== "lock") {
+            failingOrphans.push(orphan);
+            continue;
+        }
+        const classification = classifyStoreWriteLockDir(orphan.path);
+        if (classification === "active") {
+            checks.push({
+                name: "workspace:write-lock",
+                ok: true,
+                detail: `active write lease (holder pid in lease.json) — not an orphan: ${relative(workspaceRoot, orphan.path)}`,
+            });
+        }
+        else {
+            failingOrphans.push(orphan);
+        }
+    }
+    checks.push({
+        name: "workspace:orphan-store-artifacts",
+        ok: failingOrphans.length === 0,
+        detail: failingOrphans.length === 0
+            ? "none"
+            : failingOrphans.map((o) => relative(workspaceRoot, o.path)).join(", "),
+    });
+    if (options.repair) {
+        for (const orphan of failingOrphans) {
+            const rel = relative(workspaceRoot, orphan.path);
+            if (/\.corrupt-\d+$/.test(basename(orphan.path)))
+                continue;
+            if (!isInside(workspaceRoot, orphan.path))
+                continue;
+            if (orphan.kind === "lock" && classifyStoreWriteLockDir(orphan.path) === "active")
+                continue;
+            rmSync(orphan.path, { recursive: true, force: true });
+            repairedPaths.push(rel);
+        }
+    }
+    return {
+        ok: checks.every((check) => check.ok),
+        repaired: repairedPaths.length > 0,
+        storePath,
+        checks,
+        repaired_paths: repairedPaths,
+    };
+}
+//# sourceMappingURL=fsck.js.map

package/dist/store/gate-contract-migration.d.ts

@@ -0,0 +1,10 @@
+import type { IAcePackedStore } from "./types.js";
+export declare const PACKAGE_GATE_CONTRACT_VERSION = 2;
+export declare const PACKAGE_GATE_CONTRACT_VERSION_KEY = "meta/package_gate_contract_version";
+export interface GateContractMigrationResult {
+    changed: boolean;
+    messages: string[];
+}
+export declare function recordPackageGateContractVersion(store: IAcePackedStore): Promise<void>;
+export declare function migratePackageGateContract(store: IAcePackedStore, workspaceRoot: string, assetsRoot: string): Promise<GateContractMigrationResult>;
+//# sourceMappingURL=gate-contract-migration.d.ts.map