@voybio/ace-swarm 0.1.0

package/dist/store/types.d.ts

@@ -0,0 +1,155 @@
+export declare const ContentSource: {
+    readonly Package: 0;
+    readonly User: 1;
+    readonly Runtime: 2;
+};
+export type ContentSourceCode = 0 | 1 | 2;
+export declare const EntityKind: {
+    readonly Handoff: 0;
+    readonly Todo: 1;
+    readonly LedgerEvent: 2;
+    readonly SchedulerTick: 3;
+    readonly SessionEvent: 4;
+    readonly RuntimeKv: 5;
+    readonly HookEvent: 6;
+    readonly DiscoveryResult: 7;
+    readonly VericifyPost: 8;
+    readonly AgentInstruction: 9;
+    readonly AgentManifest: 10;
+    readonly SkillDefinition: 11;
+    readonly GateDefinition: 12;
+    readonly RoleCapability: 13;
+    readonly SchemaDefinition: 14;
+    readonly KernelArtifact: 15;
+    readonly TopologyEntry: 16;
+    readonly DomainDocument: 17;
+    readonly HookContext: 18;
+    readonly CatalogEntry: 19;
+};
+export type EntityKindCode = (typeof EntityKind)[keyof typeof EntityKind];
+export interface UnifiedEntry {
+    id: number;
+    kind: EntityKindCode;
+    content_source: ContentSourceCode;
+    ts: number;
+    key: string;
+    payload: unknown;
+    parent_id?: number;
+    flags?: number;
+}
+export declare const MAGIC = "ACEPACK\0";
+export declare const STORE_VERSION = 1;
+export declare const HEADER_SIZE = 64;
+export interface ChunkIndexEntry {
+    offset: number;
+    length: number;
+}
+/** Zarrita AsyncReadable protocol */
+export interface AsyncReadable {
+    get(key: string): Promise<Uint8Array | undefined>;
+}
+/** Zarrita AsyncWritable protocol */
+export interface AsyncWritable {
+    set(key: string, value: Uint8Array): Promise<void>;
+    delete(key: string): Promise<boolean>;
+}
+/** Full store API */
+export interface IAcePackedStore extends AsyncReadable, AsyncWritable {
+    open(path: string): Promise<void>;
+    commit(): Promise<void>;
+    compact(): Promise<void>;
+    close(): Promise<void>;
+    list(): AsyncGenerator<string>;
+    getJSON<T>(key: string): Promise<T | undefined>;
+    setJSON(key: string, value: unknown): Promise<void>;
+    getBlob(key: string): Promise<string | undefined>;
+    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>;
+    getTopology(kind: string): Promise<TopologyEntry[]>;
+    setTopology(kind: string, entries: TopologyEntry[]): Promise<void>;
+    getAgentInstruction(agent: string, file: string): Promise<string | undefined>;
+    setAgentInstruction(agent: string, file: string, content: string, source?: ContentSourceCode): Promise<void>;
+    getSkillContent(skill: string, file: string): Promise<string | undefined>;
+    setSkillContent(skill: string, file: string, content: string, source?: ContentSourceCode): Promise<void>;
+    listAgents(): Promise<string[]>;
+    listSkills(): Promise<string[]>;
+}
+export interface EntryFilter {
+    kind?: EntityKindCode;
+    content_source?: ContentSourceCode;
+    keyPrefix?: string;
+    since?: number;
+    includeDeleted?: boolean;
+}
+export interface TopologyEntry {
+    kind: string;
+    key: string;
+    value: unknown;
+    source: ContentSourceCode;
+}
+export interface StateReader {
+    handoffs(): Promise<unknown[]>;
+    todos(): Promise<unknown[]>;
+    ledger(): Promise<unknown[]>;
+    schedulerState(): Promise<unknown>;
+    sessions(): Promise<unknown[]>;
+    statusEvents(): Promise<unknown[]>;
+    providerDiscovery(): Promise<unknown[]>;
+    vericifyPosts(): Promise<unknown[]>;
+    domainDocs(domain: string): Promise<unknown[]>;
+}
+export interface AgentKnowledge {
+    name: string;
+    instructions: Record<string, string>;
+    manifest?: unknown;
+}
+export interface SkillKnowledge {
+    name: string;
+    files: Record<string, string>;
+}
+export interface KnowledgeResolver {
+    resolveAgent(name: string): Promise<AgentKnowledge>;
+    resolveSkill(name: string): Promise<SkillKnowledge>;
+    resolveGate(name: string): Promise<unknown>;
+    resolveRole(name: string): Promise<unknown>;
+    resolveSchema(name: string): Promise<unknown>;
+    resolveKernel(name: string): Promise<string>;
+    catalog(): Promise<unknown[]>;
+}
+export interface MaterializationChecksum {
+    path: string;
+    hash: string;
+    written_at: number;
+}
+export interface HookContextSnapshot {
+    schema_version: 1;
+    generated_at: string;
+    task: {
+        content: string;
+        hash: string;
+    };
+    status: {
+        content: string;
+        hash: string;
+    };
+    scope: {
+        content: string;
+        hash: string;
+    };
+    evidence_log: {
+        content: string;
+        hash: string;
+    };
+    workflow: {
+        content: string;
+        hash: string;
+    };
+    active_agents: string[];
+    gated_tools: Record<string, {
+        allowed: boolean;
+        gate: string;
+    }>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/store/types.js

@@ -0,0 +1,35 @@
+// ACE Packed Store — type definitions
+// ── Content source codes ──────────────────────────────────────────────────────
+export const ContentSource = {
+    Package: 0, // shipped with the npm package or installed via `ace add skills`
+    User: 1, // user override of a package-sourced entry — never touched by package installs
+    Runtime: 2, // created by ACE runtime during sessions
+};
+// ── Entity kind codes ─────────────────────────────────────────────────────────
+export const EntityKind = {
+    Handoff: 0,
+    Todo: 1,
+    LedgerEvent: 2,
+    SchedulerTick: 3,
+    SessionEvent: 4,
+    RuntimeKv: 5,
+    HookEvent: 6,
+    DiscoveryResult: 7,
+    VericifyPost: 8,
+    AgentInstruction: 9,
+    AgentManifest: 10,
+    SkillDefinition: 11,
+    GateDefinition: 12,
+    RoleCapability: 13,
+    SchemaDefinition: 14,
+    KernelArtifact: 15,
+    TopologyEntry: 16,
+    DomainDocument: 17,
+    HookContext: 18,
+    CatalogEntry: 19,
+};
+// ── Store file header constants ───────────────────────────────────────────────
+export const MAGIC = "ACEPACK\0";
+export const STORE_VERSION = 1;
+export const HEADER_SIZE = 64;
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1,26 @@
+export interface WorkspaceSnapshotFileRecord {
+    path: string;
+    size: number;
+    mtime_ms: number;
+    encoding: "utf8" | "base64";
+    key: string;
+    virtual_path: string;
+}
+export interface WorkspaceSnapshotResult {
+    version: 1;
+    captured_at: string;
+    session_id: string;
+    source_workspace_path: string;
+    virtual_root: string;
+    manifest_key: string;
+    manifest_path: string;
+    file_count: number;
+    files: WorkspaceSnapshotFileRecord[];
+    skipped_paths: Array<{
+        path: string;
+        reason: string;
+    }>;
+}
+export declare function workspaceSnapshotVirtualRoot(workspaceRoot: string, sessionId: string): string;
+export declare function persistWorkspaceSnapshot(workspaceRoot: string, sessionId: string, sourceWorkspacePath: string): Promise<WorkspaceSnapshotResult>;
+//# sourceMappingURL=workspace-snapshot.d.ts.map

package/dist/store/workspace-snapshot.js

@@ -0,0 +1,107 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { relative, resolve, sep } from "node:path";
+import { openStore } from "./ace-packed-store.js";
+import { getWorkspaceStorePath, toVirtualStorePath } from "./store-snapshot.js";
+import { withStoreWriteQueue } from "./write-queue.js";
+function normalizeRelPath(path) {
+    return path.split(sep).join("/");
+}
+function workspaceSnapshotPrefix(sessionId) {
+    return `state/runtime/executor/sessions/${sessionId}/workspace`;
+}
+function workspaceSnapshotFileKey(sessionId, relPath) {
+    return `${workspaceSnapshotPrefix(sessionId)}/files/${normalizeRelPath(relPath)}`;
+}
+function workspaceSnapshotManifestKey(sessionId) {
+    return `${workspaceSnapshotPrefix(sessionId)}/manifest.json`;
+}
+function encodeBuffer(content) {
+    const utf8 = content.toString("utf8");
+    if (Buffer.from(utf8, "utf8").equals(content)) {
+        return { encoding: "utf8", body: utf8 };
+    }
+    return { encoding: "base64", body: content.toString("base64") };
+}
+function collectWorkspaceFiles(rootPath, currentPath, output, skipped) {
+    const entries = readdirSync(currentPath, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+        const absPath = resolve(currentPath, entry.name);
+        const relPath = normalizeRelPath(relative(rootPath, absPath));
+        if (entry.isSymbolicLink()) {
+            skipped.push({ path: relPath, reason: "symlink" });
+            continue;
+        }
+        if (entry.isDirectory()) {
+            collectWorkspaceFiles(rootPath, absPath, output, skipped);
+            continue;
+        }
+        if (entry.isFile()) {
+            output.push({ absPath, relPath });
+            continue;
+        }
+        skipped.push({ path: relPath, reason: "unsupported_entry_type" });
+    }
+}
+export function workspaceSnapshotVirtualRoot(workspaceRoot, sessionId) {
+    return toVirtualStorePath(getWorkspaceStorePath(workspaceRoot), workspaceSnapshotPrefix(sessionId));
+}
+export async function persistWorkspaceSnapshot(workspaceRoot, sessionId, sourceWorkspacePath) {
+    const files = [];
+    const skipped = [];
+    collectWorkspaceFiles(sourceWorkspacePath, sourceWorkspacePath, files, skipped);
+    const storePath = getWorkspaceStorePath(workspaceRoot);
+    const manifestKey = workspaceSnapshotManifestKey(sessionId);
+    const virtualRoot = workspaceSnapshotVirtualRoot(workspaceRoot, sessionId);
+    const capturedAt = new Date().toISOString();
+    const manifestFiles = [];
+    await withStoreWriteQueue(storePath, async () => {
+        const store = await openStore(storePath);
+        try {
+            for (const file of files) {
+                const content = readFileSync(file.absPath);
+                const stats = statSync(file.absPath);
+                const encoded = encodeBuffer(content);
+                const key = workspaceSnapshotFileKey(sessionId, file.relPath);
+                await store.setBlob(key, encoded.body);
+                manifestFiles.push({
+                    path: file.relPath,
+                    size: stats.size,
+                    mtime_ms: stats.mtimeMs,
+                    encoding: encoded.encoding,
+                    key,
+                    virtual_path: toVirtualStorePath(storePath, key),
+                });
+            }
+            const manifest = {
+                version: 1,
+                captured_at: capturedAt,
+                session_id: sessionId,
+                source_workspace_path: sourceWorkspacePath,
+                virtual_root: virtualRoot,
+                manifest_key: manifestKey,
+                manifest_path: toVirtualStorePath(storePath, manifestKey),
+                file_count: manifestFiles.length,
+                files: manifestFiles,
+                skipped_paths: skipped,
+            };
+            await store.setJSON(manifestKey, manifest);
+            await store.commit();
+        }
+        finally {
+            await store.close();
+        }
+    });
+    return {
+        version: 1,
+        captured_at: capturedAt,
+        session_id: sessionId,
+        source_workspace_path: sourceWorkspacePath,
+        virtual_root: virtualRoot,
+        manifest_key: manifestKey,
+        manifest_path: toVirtualStorePath(storePath, manifestKey),
+        file_count: manifestFiles.length,
+        files: manifestFiles,
+        skipped_paths: skipped,
+    };
+}
+//# sourceMappingURL=workspace-snapshot.js.map

package/dist/store/write-queue.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Serialize write-capable store operations per store path inside a single
+ * process. This prevents overlapping open/commit/close cycles from racing
+ * against each other and rewriting the packed-store header/index out of order.
+ */
+export declare function withStoreWriteQueue<T>(storePath: string, fn: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=write-queue.d.ts.map

package/dist/store/write-queue.js

@@ -0,0 +1,26 @@
+const storeWriteQueues = new Map();
+/**
+ * Serialize write-capable store operations per store path inside a single
+ * process. This prevents overlapping open/commit/close cycles from racing
+ * against each other and rewriting the packed-store header/index out of order.
+ */
+export async function withStoreWriteQueue(storePath, fn) {
+    const previous = storeWriteQueues.get(storePath) ?? Promise.resolve();
+    let release;
+    const current = new Promise((resolve) => {
+        release = resolve;
+    });
+    const tail = previous.catch(() => { }).then(() => current);
+    storeWriteQueues.set(storePath, tail);
+    await previous.catch(() => { });
+    try {
+        return await fn();
+    }
+    finally {
+        release();
+        if (storeWriteQueues.get(storePath) === tail) {
+            storeWriteQueues.delete(storePath);
+        }
+    }
+}
+//# sourceMappingURL=write-queue.js.map

package/dist/todo-state.d.ts

@@ -0,0 +1,41 @@
+export type TodoNodeStatus = "backlog" | "in_progress" | "blocked" | "gated" | "done";
+export interface TodoNode {
+    id: string;
+    title: string;
+    section: string;
+    source_line: number;
+    depends_on: string[];
+    status: TodoNodeStatus;
+}
+export interface TodoStateFile {
+    version: 1;
+    updated_at: string;
+    source_todo_path: string;
+    order: string[];
+    nodes: Record<string, TodoNode>;
+}
+export interface TodoTransitionResult {
+    ok: boolean;
+    path: string;
+    todo_path: string;
+    node_id?: string;
+    from?: TodoNodeStatus;
+    to?: TodoNodeStatus;
+    unresolved_dependencies?: string[];
+    allowed?: TodoNodeStatus[];
+    error?: string;
+}
+export declare function waitForTodoStoreMirror(): Promise<void>;
+export declare function getTodoStatePath(): string;
+export declare function syncTodoState(todoContent?: string): {
+    state: TodoStateFile;
+    path: string;
+};
+export declare function syncTodoStateSafe(todoContent?: string): Promise<{
+    state: TodoStateFile;
+    path: string;
+}>;
+export declare function readTodoState(): TodoStateFile;
+export declare function transitionTodoNode(nodeId: string, targetStatus: TodoNodeStatus): TodoTransitionResult;
+export declare function transitionTodoNodeSafe(nodeId: string, targetStatus: TodoNodeStatus): Promise<TodoTransitionResult>;
+//# sourceMappingURL=todo-state.d.ts.map