@voybio/ace-swarm 2.4.3 → 2.4.6

package/dist/store/repositories/goal-repository.js

@@ -0,0 +1,157 @@
+/**
+ * GoalRepository — durable storage for the ACE Goal Engine (WS-F).
+ *
+ * Persists one {@link GoalRecord} plus its active {@link TaskPlan} per goal, and
+ * a lightweight index for listing. Storage is plain JSON under
+ * `<workspaceRoot>/agent-state/goals/`, written atomically (temp + rename) so a
+ * crash mid-write never leaves a torn record — the property WS-F's resume path
+ * depends on. The repository is intentionally root-parameterized (rather than
+ * bound to the packed store) so the Goal Engine and its tests can drive it
+ * hermetically against a temp workspace.
+ *
+ * Layout:
+ *   agent-state/goals/index.json          { version, updated_at, goals: [...] }
+ *   agent-state/goals/<goal_id>.json      GoalRecord
+ *   agent-state/goals/<goal_id>.plan.json TaskPlan (rewritten every transition)
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+export function newGoalId() {
+    return `goal-${randomUUID()}`;
+}
+function nowIso() {
+    return new Date().toISOString();
+}
+export class GoalRepository {
+    workspaceRoot;
+    dir;
+    constructor(workspaceRoot) {
+        this.workspaceRoot = workspaceRoot;
+        this.dir = join(workspaceRoot, "agent-state", "goals");
+    }
+    ensureDir() {
+        if (!existsSync(this.dir)) {
+            mkdirSync(this.dir, { recursive: true });
+        }
+    }
+    goalPath(goalId) {
+        return join(this.dir, `${goalId}.json`);
+    }
+    planPath(goalId) {
+        return join(this.dir, `${goalId}.plan.json`);
+    }
+    indexPath() {
+        return join(this.dir, "index.json");
+    }
+    writeAtomic(path, value) {
+        this.ensureDir();
+        const tmp = `${path}.${process.pid}.${randomUUID().slice(0, 8)}.tmp`;
+        writeFileSync(tmp, JSON.stringify(value, null, 2));
+        renameSync(tmp, path);
+    }
+    readJson(path) {
+        if (!existsSync(path))
+            return undefined;
+        try {
+            return JSON.parse(readFileSync(path, "utf8"));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    readIndex() {
+        const stored = this.readJson(this.indexPath());
+        if (!stored || stored.version !== 1 || !Array.isArray(stored.goals)) {
+            return { version: 1, updated_at: nowIso(), goals: [] };
+        }
+        return stored;
+    }
+    upsertIndex(goal) {
+        const index = this.readIndex();
+        const entry = {
+            goal_id: goal.goal_id,
+            status: goal.status,
+            objective: goal.objective,
+            updated_at: goal.updated_at,
+        };
+        const next = index.goals.filter((row) => row.goal_id !== goal.goal_id);
+        next.push(entry);
+        next.sort((a, b) => (a.updated_at < b.updated_at ? 1 : -1));
+        this.writeAtomic(this.indexPath(), {
+            version: 1,
+            updated_at: nowIso(),
+            goals: next,
+        });
+    }
+    /** Persist a goal record and refresh the index in one call. */
+    saveGoal(goal) {
+        const record = { ...goal, updated_at: nowIso() };
+        this.writeAtomic(this.goalPath(record.goal_id), record);
+        this.upsertIndex(record);
+        return record;
+    }
+    getGoal(goalId) {
+        return this.readJson(this.goalPath(goalId));
+    }
+    savePlan(goalId, plan) {
+        this.writeAtomic(this.planPath(goalId), plan);
+    }
+    getPlan(goalId) {
+        return this.readJson(this.planPath(goalId));
+    }
+    listGoals(filter) {
+        return this.readIndex().goals.filter((row) => filter?.status ? row.status === filter.status : true);
+    }
+    /** Delete a goal, its plan, and its index entry. Returns true if present. */
+    deleteGoal(goalId) {
+        const goalPath = this.goalPath(goalId);
+        const existed = existsSync(goalPath);
+        for (const path of [goalPath, this.planPath(goalId)]) {
+            if (existsSync(path))
+                rmSync(path);
+        }
+        const index = this.readIndex();
+        this.writeAtomic(this.indexPath(), {
+            version: 1,
+            updated_at: nowIso(),
+            goals: index.goals.filter((row) => row.goal_id !== goalId),
+        });
+        return existed;
+    }
+    /**
+     * Rebuild the index from the on-disk goal files. Cheap self-heal used at
+     * startup so a hand-deleted or partially-written index never hides live goals.
+     */
+    rebuildIndex() {
+        this.ensureDir();
+        const goals = [];
+        for (const name of readdirSync(this.dir)) {
+            if (!name.endsWith(".json") || name.endsWith(".plan.json") || name === "index.json") {
+                continue;
+            }
+            const record = this.readJson(join(this.dir, name));
+            if (record?.goal_id) {
+                goals.push({
+                    goal_id: record.goal_id,
+                    status: record.status,
+                    objective: record.objective,
+                    updated_at: record.updated_at,
+                });
+            }
+        }
+        goals.sort((a, b) => (a.updated_at < b.updated_at ? 1 : -1));
+        const file = { version: 1, updated_at: nowIso(), goals };
+        this.writeAtomic(this.indexPath(), file);
+        return file;
+    }
+}
+export function defaultGoalBudgets() {
+    return {
+        max_wall_clock_ms: 4 * 60 * 60 * 1000, // 4h
+        max_ticks: 200,
+        max_replans: 3,
+        max_step_retries: 1,
+    };
+}
+//# sourceMappingURL=goal-repository.js.map

package/dist/store/repositories/playbook-repository.d.ts

@@ -0,0 +1,107 @@
+export type PlaybookSection = "strategies" | "tool_usage" | "failure_modes" | "verification" | "env_facts";
+export type PlaybookBulletStatus = "active" | "quarantined" | "retired";
+export interface PlaybookScope {
+    role?: string;
+    model_class?: string;
+    model?: string;
+    tool?: string;
+    reason_code?: string;
+}
+export interface PlaybookBullet {
+    bullet_id: string;
+    section: PlaybookSection;
+    scope: PlaybookScope;
+    content: string;
+    helpful_count: number;
+    harmful_count: number;
+    observed_count: number;
+    status: PlaybookBulletStatus;
+    evidence_refs: string[];
+    provenance: {
+        source: "reflector" | "llm_reflector" | "operator" | "migration";
+        run_id?: string;
+    };
+    created_at: string;
+    updated_at: string;
+}
+export type PlaybookDeltaOp = {
+    type: "ADD";
+    section: PlaybookSection;
+    scope: PlaybookScope;
+    content: string;
+    evidence_refs: string[];
+    provenance: PlaybookBullet["provenance"];
+} | {
+    type: "TAG";
+    bullet_id: string;
+    tag: "helpful" | "harmful";
+};
+export interface PlaybookConfig {
+    max_active_total?: number;
+    max_active_per_section?: number;
+}
+export interface PlaybookIndexEntry {
+    bullet_id: string;
+    section: PlaybookSection;
+    status: PlaybookBulletStatus;
+    updated_at: string;
+}
+export interface PlaybookIndexFile {
+    version: 1;
+    updated_at: string;
+    bullets: PlaybookIndexEntry[];
+}
+export interface PlaybookApplyResult {
+    added: number;
+    tagged: number;
+    refused: Array<{
+        reason_code: string;
+        op: PlaybookDeltaOp;
+    }>;
+}
+export declare const PLAYBOOK_SECTIONS: readonly PlaybookSection[];
+export declare const PLAYBOOK_STATUSES: readonly PlaybookBulletStatus[];
+export declare function isPlaybookSection(value: string): value is PlaybookSection;
+export declare function isPlaybookStatus(value: string): value is PlaybookBulletStatus;
+export declare class PlaybookRepository {
+    private readonly workspaceRoot;
+    private readonly dir;
+    private migrated;
+    constructor(workspaceRoot: string);
+    get root(): string;
+    private useStore;
+    private ensureDir;
+    private bulletRelPath;
+    private bulletPath;
+    private indexRelPath;
+    private indexPath;
+    private markerRelPath;
+    private markerPath;
+    private artifactKey;
+    private writeText;
+    private writeJson;
+    private readText;
+    private existsRel;
+    private readJson;
+    private listBulletRelPaths;
+    private migrateOnce;
+    readIndex(): PlaybookIndexFile;
+    private upsertIndex;
+    saveBullet(bullet: PlaybookBullet): PlaybookBullet;
+    createBullet(input: Omit<PlaybookBullet, "bullet_id" | "helpful_count" | "harmful_count" | "observed_count" | "status" | "created_at" | "updated_at">): PlaybookBullet;
+    getBullet(bulletId: string): PlaybookBullet | undefined;
+    listBullets(filter?: {
+        section?: PlaybookSection;
+        status?: PlaybookBulletStatus;
+        scope?: PlaybookScope;
+    }): PlaybookBullet[];
+    applyDeltaOps(ops: PlaybookDeltaOp[], config?: PlaybookConfig): PlaybookApplyResult;
+    rebuildIndex(): PlaybookIndexFile;
+}
+export declare function parseLessonsMarkdown(markdown: string): Array<Omit<PlaybookBullet, "bullet_id" | "helpful_count" | "harmful_count" | "observed_count" | "status" | "created_at" | "updated_at">>;
+export declare function renderPlaybookMarkdown(repo: PlaybookRepository, filter?: {
+    section?: PlaybookSection;
+    status?: PlaybookBulletStatus;
+}): string;
+export declare function materializePlaybookMarkdown(workspaceRoot: string): string;
+//# sourceMappingURL=playbook-repository.d.ts.map

package/dist/store/repositories/playbook-repository.js

@@ -0,0 +1,314 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { operationalArtifactKey, writeOperationalArtifactSync, } from "../store-artifacts.js";
+import { listStoreKeysSync, readStoreBlobSync, storeExistsSync, } from "../store-snapshot.js";
+export const PLAYBOOK_SECTIONS = ["strategies", "tool_usage", "failure_modes", "verification", "env_facts"];
+export const PLAYBOOK_STATUSES = ["active", "quarantined", "retired"];
+const SECTIONS = PLAYBOOK_SECTIONS;
+export function isPlaybookSection(value) {
+    return PLAYBOOK_SECTIONS.some((section) => section === value);
+}
+export function isPlaybookStatus(value) {
+    return PLAYBOOK_STATUSES.some((status) => status === value);
+}
+function nowIso() {
+    return new Date().toISOString();
+}
+function newBulletId() {
+    return `pb-${randomUUID().replace(/-/g, "").slice(0, 8)}`;
+}
+function truncateContent(content) {
+    return content.replace(/\s+/g, " ").trim().slice(0, 400);
+}
+function scopeMatches(bulletScope, filter) {
+    if (!filter)
+        return true;
+    return Object.entries(filter).every(([key, value]) => value === undefined || bulletScope[key] === undefined || bulletScope[key] === value);
+}
+export class PlaybookRepository {
+    workspaceRoot;
+    dir;
+    migrated = false;
+    constructor(workspaceRoot) {
+        this.workspaceRoot = workspaceRoot;
+        this.dir = join(workspaceRoot, "agent-state", "playbook");
+    }
+    get root() {
+        return this.workspaceRoot;
+    }
+    useStore() {
+        return storeExistsSync(this.workspaceRoot);
+    }
+    ensureDir() {
+        if (!this.useStore() && !existsSync(this.dir))
+            mkdirSync(this.dir, { recursive: true });
+        this.migrateOnce();
+    }
+    bulletRelPath(bulletId) {
+        return `agent-state/playbook/${bulletId}.json`;
+    }
+    bulletPath(bulletId) {
+        return join(this.workspaceRoot, this.bulletRelPath(bulletId));
+    }
+    indexRelPath() {
+        return "agent-state/playbook/__index.json";
+    }
+    indexPath() {
+        return join(this.workspaceRoot, this.indexRelPath());
+    }
+    markerRelPath() {
+        return "agent-state/playbook/__migrated";
+    }
+    markerPath() {
+        return join(this.workspaceRoot, this.markerRelPath());
+    }
+    artifactKey(relPath) {
+        return operationalArtifactKey(relPath);
+    }
+    writeText(relPath, content) {
+        if (this.useStore()) {
+            return writeOperationalArtifactSync(this.workspaceRoot, relPath, content);
+        }
+        const path = join(this.workspaceRoot, relPath);
+        mkdirSync(dirname(path), { recursive: true });
+        const tmp = `${path}.${process.pid}.${randomUUID().slice(0, 8)}.tmp`;
+        writeFileSync(tmp, content, "utf8");
+        renameSync(tmp, path);
+        return path;
+    }
+    writeJson(relPath, value) {
+        return this.writeText(relPath, JSON.stringify(value, null, 2));
+    }
+    readText(relPath) {
+        if (this.useStore()) {
+            const storeText = readStoreBlobSync(this.workspaceRoot, this.artifactKey(relPath));
+            if (typeof storeText === "string")
+                return storeText;
+        }
+        const path = join(this.workspaceRoot, relPath);
+        if (!existsSync(path))
+            return undefined;
+        return readFileSync(path, "utf8");
+    }
+    existsRel(relPath) {
+        if (this.useStore() && typeof readStoreBlobSync(this.workspaceRoot, this.artifactKey(relPath)) === "string") {
+            return true;
+        }
+        return existsSync(join(this.workspaceRoot, relPath));
+    }
+    readJson(relPath) {
+        const raw = this.readText(relPath);
+        if (typeof raw !== "string")
+            return undefined;
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    listBulletRelPaths() {
+        const rels = new Set();
+        if (this.useStore()) {
+            const prefix = this.artifactKey("agent-state/playbook/");
+            for (const key of listStoreKeysSync(this.workspaceRoot, prefix)) {
+                const relPath = key.slice("state/artifacts/".length);
+                if (relPath.endsWith(".json") && !relPath.endsWith("/__index.json")) {
+                    rels.add(relPath);
+                }
+            }
+        }
+        if (existsSync(this.dir)) {
+            for (const name of readdirSync(this.dir)) {
+                if (name.endsWith(".json") && name !== "__index.json") {
+                    rels.add(`agent-state/playbook/${name}`);
+                }
+            }
+        }
+        return [...rels].sort((a, b) => a.localeCompare(b));
+    }
+    migrateOnce() {
+        if (this.migrated || this.existsRel(this.markerRelPath())) {
+            this.migrated = true;
+            return;
+        }
+        this.migrated = true;
+        const lessons = this.readText("agent-state/lessons.md");
+        if (typeof lessons === "string") {
+            for (const bullet of parseLessonsMarkdown(lessons)) {
+                this.createBullet(bullet);
+            }
+        }
+        this.writeText(this.markerRelPath(), `${nowIso()}\n`);
+    }
+    readIndex() {
+        this.ensureDir();
+        const stored = this.readJson(this.indexRelPath());
+        if (!stored || stored.version !== 1 || !Array.isArray(stored.bullets)) {
+            return this.rebuildIndex();
+        }
+        return stored;
+    }
+    upsertIndex(bullet) {
+        const index = this.readIndex();
+        const next = index.bullets.filter((row) => row.bullet_id !== bullet.bullet_id);
+        next.push({
+            bullet_id: bullet.bullet_id,
+            section: bullet.section,
+            status: bullet.status,
+            updated_at: bullet.updated_at,
+        });
+        next.sort((a, b) => (a.updated_at < b.updated_at ? 1 : -1));
+        this.writeJson(this.indexRelPath(), { version: 1, updated_at: nowIso(), bullets: next });
+    }
+    saveBullet(bullet) {
+        this.ensureDir();
+        const record = { ...bullet, content: truncateContent(bullet.content), updated_at: nowIso() };
+        this.writeJson(this.bulletRelPath(record.bullet_id), record);
+        this.upsertIndex(record);
+        return record;
+    }
+    createBullet(input) {
+        const at = nowIso();
+        return this.saveBullet({
+            bullet_id: newBulletId(),
+            section: input.section,
+            scope: input.scope,
+            content: input.content,
+            helpful_count: 0,
+            harmful_count: 0,
+            observed_count: input.provenance.source === "llm_reflector" ? 0 : 1,
+            // Evidence-free notes from every producer are retained but cannot be injected
+            // until evidence is attached through a curated path.
+            status: input.evidence_refs.length === 0 ? "quarantined" : "active",
+            evidence_refs: input.evidence_refs.slice(0, 5),
+            provenance: input.provenance,
+            created_at: at,
+            updated_at: at,
+        });
+    }
+    getBullet(bulletId) {
+        this.ensureDir();
+        return this.readJson(this.bulletRelPath(bulletId));
+    }
+    listBullets(filter) {
+        return this.readIndex().bullets
+            .filter((row) => (!filter?.section || row.section === filter.section) && (!filter?.status || row.status === filter.status))
+            .flatMap((row) => {
+            const bullet = this.getBullet(row.bullet_id);
+            return bullet && scopeMatches(bullet.scope, filter?.scope) ? [bullet] : [];
+        });
+    }
+    applyDeltaOps(ops, config = {}) {
+        const result = { added: 0, tagged: 0, refused: [] };
+        for (const op of ops) {
+            if (op.type === "TAG") {
+                const bullet = this.getBullet(op.bullet_id);
+                if (!bullet)
+                    continue;
+                this.saveBullet({
+                    ...bullet,
+                    helpful_count: bullet.helpful_count + (op.tag === "helpful" ? 1 : 0),
+                    harmful_count: bullet.harmful_count + (op.tag === "harmful" ? 1 : 0),
+                });
+                result.tagged += 1;
+                continue;
+            }
+            const active = this.listBullets({ status: "active", section: op.section });
+            const perSectionCap = config.max_active_per_section ?? 64;
+            const totalCap = config.max_active_total ?? 200;
+            if (active.length >= perSectionCap || this.listBullets({ status: "active" }).length >= totalCap) {
+                result.refused.push({ reason_code: "playbook_section_full", op });
+                continue;
+            }
+            this.createBullet(op);
+            result.added += 1;
+        }
+        return result;
+    }
+    rebuildIndex() {
+        if (!this.useStore() && !existsSync(this.dir))
+            mkdirSync(this.dir, { recursive: true });
+        const bullets = [];
+        for (const relPath of this.listBulletRelPaths()) {
+            const bullet = this.readJson(relPath);
+            if (bullet?.bullet_id && SECTIONS.includes(bullet.section)) {
+                bullets.push({
+                    bullet_id: bullet.bullet_id,
+                    section: bullet.section,
+                    status: bullet.status,
+                    updated_at: bullet.updated_at,
+                });
+            }
+        }
+        bullets.sort((a, b) => (a.updated_at < b.updated_at ? 1 : -1));
+        const file = { version: 1, updated_at: nowIso(), bullets };
+        this.writeJson(this.indexRelPath(), file);
+        return file;
+    }
+}
+export function parseLessonsMarkdown(markdown) {
+    return markdown
+        .split(/^## Lesson\s+.*$/m)
+        .map((block) => block.trim())
+        .filter(Boolean)
+        .map((block) => {
+        const field = (name) => {
+            const match = block.match(new RegExp(`(?:^|\\n)\\*\\*${name}:\\*\\*\\s*([\\s\\S]*?)(?=\\n\\*\\*|$)`, "i"));
+            return match?.[1]?.trim() ?? "";
+        };
+        const guardrail = field("Guardrail");
+        const verification = field("Verification Check");
+        return {
+            section: "failure_modes",
+            scope: {},
+            content: truncateContent(`${guardrail}${verification ? ` Verify: ${verification}` : ""}`),
+            evidence_refs: [],
+            provenance: { source: "migration" },
+        };
+    })
+        .filter((bullet) => bullet.content.length > 0);
+}
+export function renderPlaybookMarkdown(repo, filter = {}) {
+    const bullets = repo
+        .listBullets(filter)
+        .sort((a, b) => a.section.localeCompare(b.section) ||
+        a.status.localeCompare(b.status) ||
+        a.bullet_id.localeCompare(b.bullet_id));
+    const lines = ["# PLAYBOOK", "", "_Derived from ACEPACK-backed `agent-state/playbook/*.json`; regenerate rather than hand-edit._", ""];
+    for (const status of ["active", "quarantined", "retired"]) {
+        const statusBullets = bullets.filter((bullet) => bullet.status === status);
+        if (statusBullets.length === 0)
+            continue;
+        lines.push(`## ${status}`, "");
+        for (const section of SECTIONS) {
+            const sectionBullets = statusBullets.filter((bullet) => bullet.section === section);
+            if (sectionBullets.length === 0)
+                continue;
+            lines.push(`### ${section}`, "");
+            for (const bullet of sectionBullets) {
+                const scope = Object.keys(bullet.scope).length > 0 ? ` scope=${JSON.stringify(bullet.scope)}` : "";
+                lines.push(`- [${bullet.bullet_id}] ${bullet.content} ` +
+                    `(helpful=${bullet.helpful_count}, harmful=${bullet.harmful_count}, observed=${bullet.observed_count}${scope})`);
+            }
+            lines.push("");
+        }
+    }
+    if (bullets.length === 0) {
+        lines.push("_No playbook bullets recorded._", "");
+    }
+    return lines.join("\n");
+}
+export function materializePlaybookMarkdown(workspaceRoot) {
+    const repo = new PlaybookRepository(workspaceRoot);
+    const relPath = "agent-state/PLAYBOOK.md";
+    if (storeExistsSync(workspaceRoot)) {
+        return writeOperationalArtifactSync(workspaceRoot, relPath, renderPlaybookMarkdown(repo));
+    }
+    const path = join(workspaceRoot, relPath);
+    mkdirSync(join(workspaceRoot, "agent-state"), { recursive: true });
+    writeFileSync(path, renderPlaybookMarkdown(repo), "utf8");
+    return path;
+}
+//# sourceMappingURL=playbook-repository.js.map

package/dist/store/store-artifacts.js

@@ -1,9 +1,10 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
 import { dirname } from "node:path";
 import { openStore } from "./ace-packed-store.js";
-import { getWorkspaceStorePath, invalidateStoreSnapshotCache, readStoreBlobSync, toVirtualStorePath, } from "./store-snapshot.js";
+import { getWorkspaceStorePath, invalidateStoreSnapshotCache, readStoreBlobSync, toVirtualStorePath, validateChunkBounds, } from "./store-snapshot.js";
 import { withStoreWriteCoordinator } from "./write-coordinator.js";
 import { HEADER_SIZE, HEADER_SIZE_V1, STORE_VERSION, MAGIC } from "./types.js";
+import { crc32 } from "./crc32.js";
 // ── v2 header constants (mirrors ace-packed-store.ts) ─────────────────────────
 const H_KV_IDX_OFF = 16;
 const H_KV_IDX_LEN = 24;
@@ -125,6 +126,29 @@ function defaultStoreBuffer() {
     buf.set(indexBytes, kvIdxOff);
     return buf;
 }
+/**
+ * Validates the structural invariants of a parsed v2 header before any code
+ * splices bytes out of the file using it. A corrupt header (e.g. kvChunkEnd
+ * pointing past EOF) must never be trusted to build a new file — that would
+ * bake a zero-filled/garbage region into the *new* store and spread
+ * corruption to every key, not just the bad one.
+ */
+function validateStoreHeaderInvariants(hdr, index, fileLength) {
+    if (!(HEADER_SIZE <= hdr.kvChunkEnd && hdr.kvChunkEnd <= hdr.evtOffset && hdr.evtOffset <= hdr.kvIndexOffset && hdr.kvIndexOffset <= fileLength)) {
+        return `header region ordering invalid (kvChunkEnd=${hdr.kvChunkEnd}, evtOffset=${hdr.evtOffset}, kvIndexOffset=${hdr.kvIndexOffset}, fileLength=${fileLength})`;
+    }
+    for (const [key, entry] of Object.entries(index)) {
+        if (!validateChunkBounds(entry, hdr.kvChunkEnd, HEADER_SIZE)) {
+            return `index entry '${key}' out of KV region bounds (offset=${entry.offset}, length=${entry.length}, kvChunkEnd=${hdr.kvChunkEnd})`;
+        }
+    }
+    return undefined;
+}
+function quarantineCorruptStore(storePath, rawFile) {
+    const quarantinePath = `${storePath}.corrupt-${Date.now()}`;
+    writeFileSync(quarantinePath, rawFile);
+    return quarantinePath;
+}
 function readStoreBuffer(storePath) {
     const rawFile = existsSync(storePath) ? readFileSync(storePath) : defaultStoreBuffer();
     // Buffer (from readFileSync) is a Uint8Array subclass — wrap to get a plain Uint8Array view
@@ -135,11 +159,25 @@ function readStoreBuffer(storePath) {
         return { file: def, kvChunkEnd: HEADER_SIZE, evtBytes: new Uint8Array(4), evtCount: 0, evtBaseId: 0, index: {} };
     }
     const hdr = readStoreHeader(file.subarray(0, Math.max(HEADER_SIZE, hdrSize)));
+    if (hdr.kvIndexOffset < 0 ||
+        hdr.kvIndexLength < 0 ||
+        hdr.kvIndexOffset + hdr.kvIndexLength > file.length ||
+        hdr.evtOffset < 0 ||
+        hdr.evtLength < 0 ||
+        hdr.evtOffset + hdr.evtLength > file.length) {
+        const quarantinePath = quarantineCorruptStore(storePath, rawFile);
+        throw new Error(`AcePackedStore artifact write refused: header region exceeds file bounds — quarantined corrupt store at ${quarantinePath}, original left in place. Run 'ace repair' or 'ace fsck --repair'.`);
+    }
     const evtBytes = hdr.evtLength > 0
         ? file.slice(hdr.evtOffset, hdr.evtOffset + hdr.evtLength)
         : new Uint8Array(4); // empty event section
     const indexRaw = file.subarray(hdr.kvIndexOffset, hdr.kvIndexOffset + hdr.kvIndexLength);
     const index = JSON.parse(DECODE.decode(indexRaw));
+    const invariantError = validateStoreHeaderInvariants(hdr, index, file.length);
+    if (invariantError) {
+        const quarantinePath = quarantineCorruptStore(storePath, rawFile);
+        throw new Error(`AcePackedStore artifact write refused: ${invariantError} — quarantined corrupt store at ${quarantinePath}, original left in place. Run 'ace repair' or 'ace fsck --repair'.`);
+    }
     return { file, kvChunkEnd: hdr.kvChunkEnd, evtBytes, evtCount: hdr.evtCount, evtBaseId: hdr.evtBaseId, index };
 }
 export function operationalArtifactKey(relPath) {
@@ -169,7 +207,11 @@ export function writeStoreBlobsSync(workspaceRoot, blobs) {
     const nextIndex = { ...index };
     let cursor = kvChunkEnd;
     for (const entry of encoded) {
-        nextIndex[entry.key] = { offset: cursor, length: entry.contentBytes.length };
+        nextIndex[entry.key] = {
+            offset: cursor,
+            length: entry.contentBytes.length,
+            crc: crc32(entry.contentBytes),
+        };
         cursor += 4 + entry.contentBytes.length;
     }
     const indexBytes = TEXT.encode(JSON.stringify(nextIndex));

package/dist/store/store-authority-audit.js

@@ -31,6 +31,7 @@ const OFFLINE_SYNC_HELPER_SOURCES = new Set([
     "src/astgrep-index.ts",
     "src/index-store.ts",
     "src/tools-files.ts",
+    "src/source-mutation-coordinator.ts",
 ]);
 const TOOL_RUNTIME_SOURCE_HINT = /(?:^|\/)(?:tools-[^/]+|tools-framework|runtime-[^/]+|tracker-[^/]+|workspace-manager|status-events|job-scheduler|run-ledger|runtime-profile|handoff-registry|astgrep-index)\.ts$/;
 const TASK_KEY_TO_FILE = {