@voybio/ace-swarm 0.1.0 → 0.2.1

package/dist/job-scheduler.js

@@ -1,10 +1,15 @@
 import { randomUUID } from "node:crypto";
 import { readHandoffRegistry } from "./handoff-registry.js";
-import { safeRead, safeWrite, withFileLock, wsPath } from "./helpers.js";
+import { resolveWorkspaceRoot, safeRead, safeWrite, withFileLock, wsPath } from "./helpers.js";
 import { isReadError } from "./shared.js";
 import { appendStatusEventSafe, readStatusEvents } from "./status-events.js";
 import { appendRunLedgerEntrySafe } from "./run-ledger.js";
 import { readTodoState } from "./todo-state.js";
+import { openStore } from "./store/ace-packed-store.js";
+import { ProjectionManager } from "./store/materializers/projection-manager.js";
+import { SchedulerRepository } from "./store/repositories/scheduler-repository.js";
+import { getWorkspaceStorePath, readStoreJsonSync, storeExistsSync, } from "./store/store-snapshot.js";
+import { withStoreWriteQueue } from "./store/write-queue.js";
 // ── Buffered transition-event infrastructure ────────────────────────
 // Events are collected during the scheduler lock and flushed after
 // the lock is released.  Emission is failure-tolerant: a broken
@@ -270,33 +275,63 @@ export function getSchedulerLeasePath() {
     return wsPath(SCHEDULER_LEASE_REL);
 }
 export function readJobQueue() {
+    const root = resolveWorkspaceRoot();
+    if (storeExistsSync(root)) {
+        const stored = readStoreJsonSync(root, "state/scheduler/queue");
+        if (stored)
+            return stored;
+    }
     const raw = safeRead(JOB_QUEUE_REL);
     if (isReadError(raw))
         return defaultQueueFile();
     return parseQueueFile(raw) ?? defaultQueueFile();
 }
 export function readJobLockTable() {
+    const root = resolveWorkspaceRoot();
+    if (storeExistsSync(root)) {
+        const stored = readStoreJsonSync(root, "state/scheduler/locks");
+        if (stored)
+            return stored;
+    }
     const raw = safeRead(JOB_LOCK_TABLE_REL);
     if (isReadError(raw))
         return defaultJobLockFile();
     return parseJobLockFile(raw) ?? defaultJobLockFile();
 }
 export function readSchedulerLease() {
+    const root = resolveWorkspaceRoot();
+    if (storeExistsSync(root)) {
+        const stored = readStoreJsonSync(root, "state/scheduler/lease");
+        if (stored)
+            return stored ?? undefined;
+    }
     const raw = safeRead(SCHEDULER_LEASE_REL);
     if (isReadError(raw))
         return undefined;
     return parseLease(raw);
 }
-function writeQueue(queue) {
-    queue.updated_at = nowIso();
-    return safeWrite(JOB_QUEUE_REL, JSON.stringify(queue, null, 2));
-}
-function writeJobLocks(table) {
-    table.updated_at = nowIso();
-    return safeWrite(JOB_LOCK_TABLE_REL, JSON.stringify(table, null, 2));
-}
-function writeLease(lease) {
-    return safeWrite(SCHEDULER_LEASE_REL, JSON.stringify(lease, null, 2));
+async function persistSchedulerState(input) {
+    const root = resolveWorkspaceRoot();
+    if (!storeExistsSync(root)) {
+        safeWrite(JOB_QUEUE_REL, JSON.stringify({ ...input.queue, updated_at: nowIso() }, null, 2));
+        safeWrite(JOB_LOCK_TABLE_REL, JSON.stringify({ ...input.locks, updated_at: nowIso() }, null, 2));
+        safeWrite(SCHEDULER_LEASE_REL, JSON.stringify(input.lease ?? null, null, 2));
+        return;
+    }
+    const storePath = getWorkspaceStorePath(root);
+    await withStoreWriteQueue(storePath, async () => {
+        const store = await openStore(storePath);
+        try {
+            const repo = new SchedulerRepository(store);
+            await repo.replaceState(input);
+            await store.commit();
+            const projections = new ProjectionManager(store, root);
+            await projections.projectAfterCommit(["scheduler"]);
+        }
+        finally {
+            await store.close();
+        }
+    });
 }
 function compareJobs(a, b) {
     const priorityCmp = PRIORITY_WEIGHT[a.priority] - PRIORITY_WEIGHT[b.priority];
@@ -480,8 +515,7 @@ function defaultLeaseTtlSeconds() {
 function hasActiveLockForJob(locks, jobId) {
     return locks.some((lock) => lock.job_id === jobId && isJobLockActive(lock));
 }
-function acquireLease(owner, ttlSeconds, now) {
-    const existing = readSchedulerLease();
+function acquireLease(existing, owner, ttlSeconds, now) {
     const expiry = new Date(now.getTime() + ttlSeconds * 1000);
     if (!existing) {
         const lease = {
@@ -492,7 +526,6 @@ function acquireLease(owner, ttlSeconds, now) {
             heartbeat_at: nowIso(now),
             expires_at: nowIso(expiry),
         };
-        writeLease(lease);
         return { acquired: true, lease, recovery_mode: false };
     }
     const existingExpiry = parseDate(existing.expires_at);
@@ -506,7 +539,6 @@ function acquireLease(owner, ttlSeconds, now) {
             heartbeat_at: nowIso(now),
             expires_at: nowIso(expiry),
         };
-        writeLease(lease);
         return { acquired: true, lease, recovery_mode: expired };
     }
     return { acquired: false, lease: existing, recovery_mode: false };
@@ -522,7 +554,7 @@ function hasActiveLeaseForOwner(lease, owner, now) {
     return expires.getTime() > now.getTime();
 }
 function ensureLeaseForOwner(owner, now, ttlSeconds = defaultLeaseTtlSeconds()) {
-    const leaseResult = acquireLease(owner, ttlSeconds, now);
+    const leaseResult = acquireLease(readSchedulerLease(), owner, ttlSeconds, now);
     if (!leaseResult.acquired) {
         return leaseResult;
     }
@@ -532,7 +564,6 @@ function ensureLeaseForOwner(owner, now, ttlSeconds = defaultLeaseTtlSeconds())
         heartbeat_at: nowIso(now),
         expires_at: nowIso(new Date(now.getTime() + ttlSeconds * 1000)),
     };
-    writeLease(refreshedLease);
     return {
         ...leaseResult,
         lease: refreshedLease,
@@ -657,7 +688,7 @@ function reconcileRecoveryState(queue, table, now, recoveryMode, buf) {
 }
 export async function enqueueJob(input) {
     const buf = newEventBuffer();
-    const result = await withFileLock(SCHEDULER_LOCK_REL, () => {
+    const result = await withFileLock(SCHEDULER_LOCK_REL, async () => {
         if (!input.kind || input.kind.trim().length === 0) {
             const queue = readJobQueue();
             return {
@@ -715,7 +746,11 @@ export async function enqueueJob(input) {
             accepted_at: created,
         };
         queue.jobs.push(job);
-        const path = writeQueue(queue);
+        await persistSchedulerState({
+            queue,
+            locks: readJobLockTable(),
+            lease: readSchedulerLease(),
+        });
         buf.status.push({
             event_type: "SCHEDULER_JOB_ENQUEUED",
             status: "started",
@@ -741,7 +776,7 @@ export async function enqueueJob(input) {
         });
         return {
             ok: true,
-            path,
+            path: getJobQueuePath(),
             queue,
             ack: {
                 job_id: job.job_id,
@@ -754,7 +789,7 @@ export async function enqueueJob(input) {
 }
 export async function acknowledgeJob(input) {
     const buf = newEventBuffer();
-    const result = await withFileLock(SCHEDULER_LOCK_REL, () => {
+    const result = await withFileLock(SCHEDULER_LOCK_REL, async () => {
         const queue = readJobQueue();
         const job = queue.jobs.find((row) => row.job_id === input.job_id);
         if (!job) {
@@ -794,7 +829,11 @@ export async function acknowledgeJob(input) {
                 }
             }
         }
-        const path = writeQueue(queue);
+        await persistSchedulerState({
+            queue,
+            locks: readJobLockTable(),
+            lease: readSchedulerLease(),
+        });
         buf.status.push({
             event_type: "SCHEDULER_JOB_ACK",
             status: job.status === "canceled" ? "done" : "pass",
@@ -821,7 +860,7 @@ export async function acknowledgeJob(input) {
         });
         return {
             ok: true,
-            path,
+            path: getJobQueuePath(),
             queue,
             from,
             to: job.status,
@@ -832,14 +871,14 @@ export async function acknowledgeJob(input) {
 }
 export async function dispatchJobs(input = {}) {
     const buf = newEventBuffer();
-    const result = await withFileLock(SCHEDULER_LOCK_REL, () => {
+    const result = await withFileLock(SCHEDULER_LOCK_REL, async () => {
         const owner = deriveOwner(input.owner);
         const now = parseDate(input.now_iso) ?? new Date();
         const table = readJobLockTable();
         const leaseTtl = typeof input.lease_ttl_seconds === "number" && input.lease_ttl_seconds > 0
             ? Math.floor(input.lease_ttl_seconds)
             : defaultLeaseTtlSeconds();
-        const leaseResult = acquireLease(owner, leaseTtl, now);
+        const leaseResult = acquireLease(readSchedulerLease(), owner, leaseTtl, now);
         if (!leaseResult.acquired) {
             const queue = readJobQueue();
             return {
@@ -913,9 +952,11 @@ export async function dispatchJobs(input = {}) {
             heartbeat_at: nowIso(now),
             expires_at: nowIso(new Date(now.getTime() + leaseTtl * 1000)),
         };
-        writeLease(refreshedLease);
-        const finalQueuePath = writeQueue(queue);
-        const finalLockPath = writeJobLocks(table);
+        await persistSchedulerState({
+            queue,
+            locks: table,
+            lease: refreshedLease,
+        });
         const summary = {
             total_jobs: queue.jobs.length,
             blocked_jobs: queue.jobs.filter((job) => job.status === "blocked").length,
@@ -954,8 +995,8 @@ export async function dispatchJobs(input = {}) {
             owner,
             lease_acquired: true,
             lease: refreshedLease,
-            queue_path: finalQueuePath,
-            lock_path: finalLockPath,
+            queue_path: getJobQueuePath(),
+            lock_path: getJobLockTablePath(),
             queue,
             locks: table,
             summary,
@@ -966,7 +1007,7 @@ export async function dispatchJobs(input = {}) {
 }
 export async function dispatchJobNow(input) {
     const buf = newEventBuffer();
-    const result = await withFileLock(SCHEDULER_LOCK_REL, () => {
+    const result = await withFileLock(SCHEDULER_LOCK_REL, async () => {
         const owner = deriveOwner(input.owner);
         const now = parseDate(input.now_iso) ?? new Date();
         const leaseResult = ensureLeaseForOwner(owner, now);
@@ -1022,12 +1063,15 @@ export async function dispatchJobNow(input) {
                 job.started_at ??
                 nowIso(now);
             heartbeatRunningLocks(table, leaseResult.lease.lease_id, now);
-            const queuePath = writeQueue(queue);
-            const lockPath = writeJobLocks(table);
+            await persistSchedulerState({
+                queue,
+                locks: table,
+                lease: leaseResult.lease,
+            });
             return {
                 ok: true,
-                queue_path: queuePath,
-                lock_path: lockPath,
+                queue_path: getJobQueuePath(),
+                lock_path: getJobLockTablePath(),
                 queue,
                 locks: table,
                 started_lock: {
@@ -1069,12 +1113,15 @@ export async function dispatchJobNow(input) {
             occupancy.add(resource);
         }
         const startedLock = startJobNow(job, table, leaseResult.lease, now, buf, "dispatch_job_now");
-        const queuePath = writeQueue(queue);
-        const lockPath = writeJobLocks(table);
+        await persistSchedulerState({
+            queue,
+            locks: table,
+            lease: leaseResult.lease,
+        });
         return {
             ok: true,
-            queue_path: queuePath,
-            lock_path: lockPath,
+            queue_path: getJobQueuePath(),
+            lock_path: getJobLockTablePath(),
             queue,
             locks: table,
             started_lock: startedLock,
@@ -1085,7 +1132,7 @@ export async function dispatchJobNow(input) {
 }
 export async function completeJob(input) {
     const buf = newEventBuffer();
-    const result = await withFileLock(SCHEDULER_LOCK_REL, () => {
+    const result = await withFileLock(SCHEDULER_LOCK_REL, async () => {
         const owner = deriveOwner(input.owner);
         const now = parseDate(input.now_iso) ?? new Date();
         const leaseResult = ensureLeaseForOwner(owner, now);
@@ -1170,8 +1217,11 @@ export async function completeJob(input) {
                 job.started_at = undefined;
             }
         }
-        const queuePath = writeQueue(queue);
-        const lockPath = writeJobLocks(table);
+        await persistSchedulerState({
+            queue,
+            locks: table,
+            lease: leaseResult.lease,
+        });
         const finalStatus = job.status;
         const isSuccess = finalStatus === "done";
         buf.status.push({
@@ -1203,8 +1253,8 @@ export async function completeJob(input) {
         });
         return {
             ok: true,
-            queue_path: queuePath,
-            lock_path: lockPath,
+            queue_path: getJobQueuePath(),
+            lock_path: getJobLockTablePath(),
             queue,
             locks: table,
             status: job.status,

package/dist/run-ledger.js

@@ -2,7 +2,7 @@ import { existsSync } from "node:fs";
 import { resolveWorkspaceRoot, safeRead, safeWrite, wsPath, withFileLock, } from "./helpers.js";
 import { isReadError } from "./shared.js";
 import { openStore } from "./store/ace-packed-store.js";
-import { VericifyProjector } from "./store/materializers/vericify-projector.js";
+import { ProjectionManager } from "./store/materializers/projection-manager.js";
 import { LedgerRepository } from "./store/repositories/ledger-repository.js";
 import { withStoreWriteQueue } from "./store/write-queue.js";
 import { getWorkspaceStorePath, listStoreKeysSync, readStoreJsonSync, storeExistsSync, } from "./store/store-snapshot.js";
@@ -234,9 +234,8 @@ export async function appendRunLedgerEntrySafe(input) {
                     },
                 });
                 await store.commit();
-                const projector = new VericifyProjector(store, root);
-                await projector.projectLedger();
-                await store.commit();
+                const projections = new ProjectionManager(store, root);
+                await projections.projectAfterCommit(["ledger"]);
                 return {
                     entry: toLegacyRunLedgerEntryDirect(record),
                     path: operationalArtifactVirtualPath(root, RUN_LEDGER_REL),

package/dist/server.d.ts

@@ -1,6 +1,6 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 export declare const ACE_MCP_SERVER_NAME = "ace-swarm";
-export declare const ACE_MCP_SERVER_VERSION = "1.1.0";
+export declare const ACE_MCP_SERVER_VERSION = "0.2.1";
 export interface CreateAceServerOptions {
     toolGovernance?: boolean;
     instructions?: string;

package/dist/server.js

@@ -7,7 +7,7 @@ import { registerResources } from "./resources.js";
 import { registerTools } from "./tools.js";
 import { backfillHandoffsIntoScheduler } from "./tools-handoff.js";
 export const ACE_MCP_SERVER_NAME = "ace-swarm";
-export const ACE_MCP_SERVER_VERSION = "1.1.0";
+export const ACE_MCP_SERVER_VERSION = "0.2.1";
 export function createAceServer(options = {}) {
     const workspaceRoot = resolveWorkspaceRoot();
     const server = new McpServer({

package/dist/shared.d.ts

@@ -45,9 +45,9 @@ export declare const ROLE_ENUM: z.ZodEnum<{
     release: "release";
 }>;
 export declare const HANDOFF_VALIDATION_MODE: z.ZodOptional<z.ZodEnum<{
+    "agent-state": "agent-state";
     auto: "auto";
     swarm: "swarm";
-    "agent-state": "agent-state";
 }>>;
 export declare const KERNEL_KEY_ENUM: z.ZodEnum<{
     directive_kernel: "directive_kernel";

package/dist/status-events.js

@@ -4,7 +4,7 @@ import { resolveWorkspaceRoot, resolveWorkspaceArtifactPath as resolveWorkspaceA
 import { isReadError } from "./shared.js";
 import { validateStatusEventPayload, PROVENANCE_CRITICAL_EVENT_TYPES } from "./schemas.js";
 import { openStore } from "./store/ace-packed-store.js";
-import { VericifyProjector } from "./store/materializers/vericify-projector.js";
+import { ProjectionManager } from "./store/materializers/projection-manager.js";
 import { TrackerRepository } from "./store/repositories/tracker-repository.js";
 import { getWorkspaceStorePath, listStoreKeysSync, readStoreJsonSync, storeExistsSync, } from "./store/store-snapshot.js";
 import { operationalArtifactVirtualPath } from "./store/store-artifacts.js";
@@ -90,8 +90,7 @@ function rotateIfNeeded(content) {
     safeWriteWorkspaceFile(STATUS_EVENTS_ARCHIVE_REL, archiveFull);
     return lines.join("\n") + "\n";
 }
-async function mirrorStatusEventToStore(event) {
-    const root = workspaceRoot();
+async function mirrorStatusEventToStore(root, event) {
     const storePath = getWorkspaceStorePath(root);
     if (!existsSync(storePath))
         return;
@@ -115,9 +114,8 @@ async function mirrorStatusEventToStore(event) {
                 },
             });
             await store.commit();
-            const projector = new VericifyProjector(store, root);
-            await projector.projectStatusEvents();
-            await store.commit();
+            const projections = new ProjectionManager(store, root);
+            await projections.projectAfterCommit(["status_events"]);
         }
         finally {
             await store.close();
@@ -125,17 +123,17 @@ async function mirrorStatusEventToStore(event) {
     });
 }
 function scheduleStatusEventMirror(event) {
+    const root = workspaceRoot();
     const snapshot = JSON.parse(JSON.stringify(event));
     trackerMirrorChain = trackerMirrorChain
         .catch(() => { })
-        .then(() => mirrorStatusEventToStore(snapshot))
+        .then(() => mirrorStatusEventToStore(root, snapshot))
         .catch(() => { });
 }
 export async function waitForPendingStatusEventMirrors() {
     await trackerMirrorChain.catch(() => { });
 }
-async function appendStatusEventStoreBacked(event) {
-    const root = workspaceRoot();
+async function appendStatusEventStoreBacked(root, event) {
     const storePath = getWorkspaceStorePath(root);
     return withStoreWriteQueue(storePath, async () => {
         const store = await openStore(storePath);
@@ -157,9 +155,8 @@ async function appendStatusEventStoreBacked(event) {
                 },
             });
             await store.commit();
-            const projector = new VericifyProjector(store, root);
-            await projector.projectStatusEvents();
-            await store.commit();
+            const projections = new ProjectionManager(store, root);
+            await projections.projectAfterCommit(["status_events"]);
             return {
                 path: operationalArtifactVirtualPath(root, STATUS_EVENTS_REL_PATH),
                 event,
@@ -187,11 +184,12 @@ export function appendStatusEvent(input) {
  * Use this from async tool handlers where parallel subagents may fire.
  */
 export async function appendStatusEventSafe(input) {
+    const root = workspaceRoot();
     return withDynamicFileLock(STATUS_EVENTS_REL_PATH, async () => {
         const event = buildStatusEvent(input);
         validateStatusEvent(event);
-        if (storeExistsSync(workspaceRoot())) {
-            return appendStatusEventStoreBacked(event);
+        if (storeExistsSync(root)) {
+            return appendStatusEventStoreBacked(root, event);
         }
         return appendStatusEvent(input);
     });

package/dist/store/ace-packed-store.d.ts

@@ -1,42 +1,81 @@
 /**
- * AcePackedStore
+ * AcePackedStore — ACEPACK v2
  *
- * Custom single-file store that implements Zarrita's AsyncReadable + AsyncWritable
- * interfaces over a packed binary file at `.agents/ACE/ace-state.zarr`.
+ * Single-file binary store. One file, no subdirectories, no companion files.
+ * Events grow in the columnar section indefinitely (Option A). compact() only
+ * reclaims dead space in the KV chunk region — it does NOT reset or archive
+ * events. Historical event replay across all past runs is always available.
  *
- * File format:
- *   [ Header  64 bytes ]   magic(8) version(4) flags(4) index_offset(8) index_length(8) reserved(32)
- *   [ Chunk region     ]   chunk_0: [uint32 length][bytes] ... chunk_N: [uint32 length][bytes]
- *   [ Index region     ]   UTF-8 JSON: { key → { offset, length } }
+ * File layout:
  *
- * Write protocol:
- *   1. Append new chunk to end of chunk region.
- *   2. Update in-memory index.
- *   3. On commit(): rewrite index region → update header → fsync.
+ *   ┌─────────────────────────────────────────────────────────┐
+ *   │ Header (128 bytes, big-endian)                           │
+ *   │   magic "ACEPACK\0" · version uint32 · flags uint32     │
+ *   │   kv_index_offset uint64 · kv_index_length uint64       │
+ *   │   kv_chunk_end uint64                                    │
+ *   │   evt_offset uint64 · evt_length uint64                  │
+ *   │   evt_count uint32 · evt_base_id uint32                  │
+ *   │   reserved (zeros)                                       │
+ *   ├─────────────────────────────────────────────────────────┤
+ *   │ KV Chunk Region (append-only, random-access)            │
+ *   │   knowledge/agents/{name}/{file} → instruction text     │
+ *   │   knowledge/skills/{name}/{file} → skill content        │
+ *   │   topology/{kind}                → JSON array           │
+ *   │   state/{...}                    → runtime state blobs  │
+ *   │   meta/{...}                     → schema version etc.  │
+ *   │   Each chunk: [uint32 length BE][bytes]                 │
+ *   ├─────────────────────────────────────────────────────────┤
+ *   │ Columnar Event Section (rewritten on every commit)      │
+ *   │   uint32    count                                        │
+ *   │   int64[N]  timestamps  (epoch ms, big-endian)          │
+ *   │   uint8[N]  kinds       (EntityKind enum)               │
+ *   │   uint8[N]  sources     (ContentSource enum)            │
+ *   │   uint8[N]  flags       (0x01=deleted)                  │
+ *   │   [pad to 4-byte alignment]                             │
+ *   │   uint32[N] pay_offsets (relative to pool start)        │
+ *   │   uint32[N] pay_lengths                                 │
+ *   │   uint32    pool_length                                  │
+ *   │   bytes[M]  payload pool (UTF-8 JSON: {key,payload,...})│
+ *   ├─────────────────────────────────────────────────────────┤
+ *   │ KV Index (JSON, rewritten on commit)                    │
+ *   │   { "knowledge/agents/ace-ops/AGENT.md": {offset, length}, ... }
+ *   └─────────────────────────────────────────────────────────┘
  *
- * Compaction:
- *   Write live chunks to temp file → validate → atomic rename.
+ * Event overhead: ~19 bytes fixed + payload (vs ~150 bytes full JSON).
+ * Timestamp/kind scanning reads only the fixed-width columns, never the pool.
  *
- * Locking:
- *   Advisory flock-style via a `.lock` sidecar file (PID + timestamp).
- *   Stale detection: lock held >30s and PID not alive → break lock.
+ * compact() removes dead KV space (overwritten keys) via atomic tmp-rename.
+ * Events are preserved across compact() — they accumulate for the workspace
+ * lifetime. See HOT_COLD_EVENT_TIERING.md for a future branch that adds
+ * BGZF batch archiving for very long-lived workspaces.
+ *
+ * Backward compat: v1 files (64-byte header) are migrated on first commit().
+ * v1 events live in core/log/ KV blobs and are pulled into the columnar section.
  */
 import { IAcePackedStore, UnifiedEntry, EntryFilter, TopologyEntry, ContentSourceCode } from "./types.js";
 export declare class AcePackedStore implements IAcePackedStore {
     private storePath;
-    private lockPath;
     private readOnly;
-    private index;
-    private chunkEnd;
     private fh;
-    private dirty;
-    private entryCounter;
+    private kvIndex;
+    private kvChunkEnd;
+    private committed;
+    private pending;
+    private evtBaseId;
     open(path: string, opts?: {
         readOnly?: boolean;
     }): Promise<void>;
-    private _initNewStore;
-    private _loadExistingStore;
+    private _initNew;
+    private _loadExisting;
+    /** Read a KV blob directly from a loaded file buffer (used during migration). */
+    private _readKvBlobDirect;
     commit(): Promise<void>;
+    /**
+     * Compacts the KV chunk region — removes dead space left by overwritten keys.
+     * Events are NOT reset or archived; they accumulate in the columnar section
+     * for the workspace lifetime (Option A — grow forever).
+     * See HOT_COLD_EVENT_TIERING.md for the future branch that adds BGZF archiving.
+     */
     compact(): Promise<void>;
     close(): Promise<void>;
     get(key: string): Promise<Uint8Array | undefined>;
@@ -49,7 +88,7 @@ export declare class AcePackedStore implements IAcePackedStore {
     setBlob(key: string, content: string): Promise<void>;
     appendEntry(entry: Omit<UnifiedEntry, "id" | "ts">): Promise<UnifiedEntry>;
     getEntries(filter?: EntryFilter): Promise<UnifiedEntry[]>;
-    getEntry(key: string): Promise<UnifiedEntry | undefined>;
+    getEntry(_key: string): Promise<UnifiedEntry | undefined>;
     getTopology(kind: string): Promise<TopologyEntry[]>;
     setTopology(kind: string, entries: TopologyEntry[]): Promise<void>;
     getAgentInstruction(agent: string, file: string): Promise<string | undefined>;
@@ -58,9 +97,9 @@ export declare class AcePackedStore implements IAcePackedStore {
     getSkillContent(skill: string, file: string): Promise<string | undefined>;
     setSkillContent(skill: string, file: string, content: string, source?: ContentSourceCode): Promise<void>;
     listSkills(): Promise<string[]>;
-    /** Dead space ratio — used to decide if compaction is needed */
+    /** Dead space ratio in the KV chunk region. Used to decide if compaction is needed. */
     get deadSpaceRatio(): number;
-    /** Number of entries in the unified log */
+    /** Total events in log (committed + pending). */
     get entryCount(): number;
 }
 export declare function openStore(storePath: string, opts?: {