@voybio/ace-swarm 0.2.0 → 0.2.2

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

@@ -0,0 +1,448 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { dirname, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import * as ts from "typescript";
+import { ACE_ROOT_REL, ACE_SCRIPTS_ROOT_REL, ACE_TASKS_ROOT_REL, mapAceWorkspaceRelativePath, safeWrite, } from "../helpers.js";
+import { OPERATIONAL_ARTIFACT_REL_PATHS, operationalArtifactKey } from "./store-artifacts.js";
+export const STORE_AUTHORITY_AUDIT_REPORT_REL_PATH = "agent-state/STORE_AUTHORITY_AUDIT.md";
+const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const SRC_ROOT = resolve(PACKAGE_ROOT, "src");
+const TARGET_CALLS = new Set(["safeWrite", "safeWriteWorkspaceFile", "safeWriteReport"]);
+const SKIPPED_INTERNAL_FUNCTIONS = new Set(["safeWriteWorkspaceFile", "safeWriteReport"]);
+const TASK_KEY_TO_FILE = {
+    todo: "todo.md",
+    role_tasks: "role_tasks.md",
+    cli_work_split: "cli_work_split.md",
+    lessons: "lessons.md",
+    readme: "README.md",
+    handoff_template: "SWARM_HANDOFF.template.json",
+    handoff_example: "SWARM_HANDOFF.example.json",
+    handoff_example_vos_ui: "SWARM_HANDOFF.example_vos_to_ui.json",
+    handoff_example_ui_coders: "SWARM_HANDOFF.example_ui_to_coders.json",
+};
+const STATIC_AGENT_STATE = new Set([
+    "ACE_WORKFLOW.md",
+    "ARTIFACT_MANIFEST.json",
+    "AST_GREP_COMMANDS.md",
+    "AST_GREP_INDEX.json",
+    "AST_GREP_INDEX.md",
+    "DECISIONS.md",
+    "EVIDENCE_LOG.md",
+    "HANDOFF.json",
+    "INTERFACE_REGISTRY.md",
+    "PROVENANCE_LOG.md",
+    "QUALITY_GATES.md",
+    "RISKS.md",
+    "SCOPE.md",
+    "SKILL_CATALOG.md",
+    "STATUS.md",
+    "STATUS_EVENTS.ndjson",
+    "TASK.md",
+    "TEAL_CONFIG.md",
+    "MODULES/registry.json",
+    "handoff-registry.json",
+    "index-fingerprints.json",
+    "index.json",
+    "run-ledger.json",
+    "runtime-executor-sessions.json",
+    "runtime-tool-specs.json",
+    "runtime-workspaces.json",
+    "todo-state.json",
+    "tracker-snapshot.json",
+    "vericify/ace-bridge.json",
+    "vericify/process-posts.json",
+]);
+function isKnowledgeReportArtifact(canonicalPath) {
+    const fileName = canonicalPath.split("/").pop() ?? canonicalPath;
+    return /(?:REPORT|AUDIT|TRIAGE|PLAN)\.md$/i.test(fileName);
+}
+function normalizeAuditPath(path) {
+    return path.replace(/\\/g, "/").replace(/^(?:\.\/)+/, "").replace(/\/+/g, "/");
+}
+function isFunctionLike(node) {
+    return (ts.isFunctionDeclaration(node) ||
+        ts.isMethodDeclaration(node) ||
+        ts.isFunctionExpression(node) ||
+        ts.isArrowFunction(node) ||
+        ts.isConstructorDeclaration(node));
+}
+function functionName(node) {
+    if (ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node) || ts.isMethodDeclaration(node)) {
+        return node.name?.getText();
+    }
+    if (ts.isArrowFunction(node) || ts.isConstructorDeclaration(node))
+        return undefined;
+    return undefined;
+}
+function callName(node) {
+    const expr = node.expression;
+    if (ts.isIdentifier(expr))
+        return expr.text;
+    if (ts.isPropertyAccessExpression(expr))
+        return expr.name.text;
+    return undefined;
+}
+function collectResolvableConstants(root, sourceFile, inherited) {
+    const constants = new Map(inherited);
+    const pending = [];
+    const visit = (node) => {
+        if (node !== root && isFunctionLike(node))
+            return;
+        if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer) {
+            pending.push({ name: node.name.text, initializer: node.initializer });
+        }
+        if (node.kind === ts.SyntaxKind.Parameter) {
+            const parameter = node;
+            if (ts.isIdentifier(parameter.name) && parameter.initializer) {
+                pending.push({ name: parameter.name.text, initializer: parameter.initializer });
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    ts.forEachChild(root, visit);
+    let changed = true;
+    let safety = 0;
+    while (changed && safety < pending.length + 2) {
+        changed = false;
+        safety += 1;
+        for (const entry of pending) {
+            if (constants.has(entry.name))
+                continue;
+            const resolved = resolveExpression(entry.initializer, sourceFile, constants);
+            if (resolved) {
+                constants.set(entry.name, resolved);
+                changed = true;
+            }
+        }
+    }
+    return constants;
+}
+function resolvePathExpression(expr, sourceFile, constants) {
+    if (ts.isStringLiteralLike(expr))
+        return normalizeAuditPath(expr.text);
+    if (ts.isNoSubstitutionTemplateLiteral(expr))
+        return normalizeAuditPath(expr.text);
+    if (ts.isParenthesizedExpression(expr))
+        return resolveExpression(expr.expression, sourceFile, constants);
+    if (ts.isAsExpression(expr) || ts.isTypeAssertionExpression(expr)) {
+        return resolveExpression(expr.expression, sourceFile, constants);
+    }
+    if (ts.isIdentifier(expr)) {
+        return constants.get(expr.text);
+    }
+    if (ts.isTemplateExpression(expr)) {
+        let value = expr.head.text;
+        for (const span of expr.templateSpans) {
+            const segment = resolveExpression(span.expression, sourceFile, constants);
+            if (typeof segment !== "string")
+                return undefined;
+            value += `${segment}${span.literal.text}`;
+        }
+        return normalizeAuditPath(value);
+    }
+    if (ts.isCallExpression(expr)) {
+        const name = callName(expr);
+        const args = expr.arguments.map((arg) => resolveExpression(arg, sourceFile, constants));
+        if (name === "resolveWritableTaskPath") {
+            const key = args[0];
+            if (typeof key !== "string")
+                return undefined;
+            const file = TASK_KEY_TO_FILE[key];
+            if (!file)
+                return undefined;
+            return mapAceWorkspaceRelativePath(`${ACE_TASKS_ROOT_REL}/${file}`);
+        }
+        if (name === "wsPath" || name === "acePath") {
+            const segments = expr.arguments.map((arg) => resolvePathLikeSegment(arg, sourceFile, constants));
+            if (segments.length === 0)
+                return undefined;
+            return mapAceWorkspaceRelativePath(segments.join("/"));
+        }
+        if (name === "join" || name === "resolve") {
+            const segments = expr.arguments.map((arg) => resolvePathLikeSegment(arg, sourceFile, constants));
+            if (segments.length === 0)
+                return undefined;
+            return normalizeAuditPath(segments.join("/"));
+        }
+        if (args.length === 1 && typeof args[0] === "string")
+            return normalizeAuditPath(args[0]);
+    }
+    return undefined;
+}
+function resolvePathLikeSegment(expr, sourceFile, constants) {
+    const resolved = resolveExpression(expr, sourceFile, constants);
+    if (typeof resolved === "string" && resolved.length > 0) {
+        return resolved;
+    }
+    return "*";
+}
+function resolveExpression(expr, sourceFile, constants) {
+    if (ts.isStringLiteralLike(expr) || ts.isNoSubstitutionTemplateLiteral(expr)) {
+        return normalizeAuditPath(expr.text);
+    }
+    if (ts.isTemplateExpression(expr) || ts.isParenthesizedExpression(expr) || ts.isAsExpression(expr) || ts.isTypeAssertionExpression(expr)) {
+        return resolvePathExpression(expr, sourceFile, constants);
+    }
+    if (ts.isIdentifier(expr)) {
+        return constants.get(expr.text);
+    }
+    if (ts.isCallExpression(expr)) {
+        return resolvePathExpression(expr, sourceFile, constants);
+    }
+    return undefined;
+}
+function collectSourceFiles(root) {
+    const files = [];
+    const walk = (dir) => {
+        if (!existsSync(dir))
+            return;
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            if (entry.name === "dist" || entry.name === "node_modules" || entry.name.startsWith(".")) {
+                continue;
+            }
+            const abs = resolve(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(abs);
+                continue;
+            }
+            if (!entry.isFile() || !entry.name.endsWith(".ts"))
+                continue;
+            files.push(abs);
+        }
+    };
+    walk(root);
+    return files.sort((left, right) => left.localeCompare(right));
+}
+function maybeMapAbsoluteRuntimeFile(path) {
+    const normalized = normalizeAuditPath(path);
+    if (!normalized)
+        return undefined;
+    return mapAceWorkspaceRelativePath(normalized);
+}
+function deriveFallbackKeys(canonicalPath) {
+    const keys = new Set();
+    const canonical = maybeMapAbsoluteRuntimeFile(canonicalPath);
+    if (!canonical)
+        return [];
+    if (canonical.startsWith(`${ACE_ROOT_REL}/agent-state/`)) {
+        const rel = canonical.slice(`${ACE_ROOT_REL}/agent-state/`.length);
+        if (rel.startsWith("context-snapshots/")) {
+            const snapshotRel = rel.slice("context-snapshots/".length);
+            if (snapshotRel.length > 0) {
+                keys.add(`state/memory/context_snapshots/${snapshotRel}`);
+            }
+        }
+        const operationalKey = `agent-state/${rel}`;
+        if (OPERATIONAL_ARTIFACT_REL_PATHS.has(operationalKey)) {
+            keys.add(operationalArtifactKey(operationalKey));
+        }
+        if (STATIC_AGENT_STATE.has(rel)) {
+            keys.add(`knowledge/agent-state/${rel}`);
+        }
+        if (rel.startsWith("MODULES/gates/")) {
+            keys.add(`knowledge/gates/${rel.slice("MODULES/gates/".length)}`);
+        }
+        if (rel.startsWith("MODULES/roles/")) {
+            keys.add(`knowledge/roles/${rel.slice("MODULES/roles/".length)}`);
+        }
+        if (rel.startsWith("MODULES/schemas/")) {
+            keys.add(`knowledge/schemas/${rel.slice("MODULES/schemas/".length)}`);
+        }
+    }
+    if (canonical.startsWith(`${ACE_TASKS_ROOT_REL}/`)) {
+        keys.add(`knowledge/tasks/${canonical.slice(`${ACE_TASKS_ROOT_REL}/`.length)}`);
+    }
+    if (canonical.startsWith(`${ACE_SCRIPTS_ROOT_REL}/`)) {
+        keys.add(`knowledge/scripts/${canonical.slice(`${ACE_SCRIPTS_ROOT_REL}/`.length)}`);
+    }
+    return [...keys];
+}
+function classifyTarget(targetPath) {
+    if (!targetPath) {
+        return {
+            classification: "canonical knowledge artifact",
+            fallbackKeys: [],
+            canonicalTarget: undefined,
+            note: "dynamic target could not be resolved statically",
+            bypassesAcepack: false,
+            regenerableFromStore: false,
+        };
+    }
+    const canonicalTarget = maybeMapAbsoluteRuntimeFile(targetPath);
+    const fallbackKeys = deriveFallbackKeys(targetPath);
+    const targetFile = canonicalTarget?.split("/").pop() ?? "";
+    const isKanbanProjection = canonicalTarget?.startsWith(`${ACE_ROOT_REL}/agent-state/kanban.`) === true;
+    const runtimeNamespace = canonicalTarget?.startsWith(`${ACE_ROOT_REL}/agent-state/`) ||
+        canonicalTarget?.startsWith(`${ACE_TASKS_ROOT_REL}/`);
+    if (canonicalTarget && isKnowledgeReportArtifact(canonicalTarget)) {
+        return {
+            classification: "canonical knowledge artifact",
+            fallbackKeys,
+            canonicalTarget,
+            note: "report artifact is intentionally file-backed",
+            bypassesAcepack: false,
+            regenerableFromStore: false,
+        };
+    }
+    if (isKanbanProjection || targetFile === "kanban.html" || targetFile === "kanban.json") {
+        return {
+            classification: "projection only",
+            fallbackKeys,
+            canonicalTarget,
+            note: "Kanban snapshot is a derived projection and can be regenerated from store state",
+            bypassesAcepack: false,
+            regenerableFromStore: true,
+        };
+    }
+    if (runtimeNamespace) {
+        return {
+            classification: fallbackKeys.length > 0 ? "projection only" : "canonical runtime state",
+            fallbackKeys,
+            canonicalTarget,
+            note: fallbackKeys.length > 0
+                ? "runtime surface is store-backed and projected for compatibility"
+                : "runtime surface has no store fallback key",
+            bypassesAcepack: fallbackKeys.length === 0,
+            regenerableFromStore: fallbackKeys.length > 0,
+        };
+    }
+    return {
+        classification: "canonical knowledge artifact",
+        fallbackKeys,
+        canonicalTarget,
+        note: fallbackKeys.length > 0
+            ? "knowledge surface also has a store fallback key"
+            : "knowledge artifact is file-backed by design",
+        bypassesAcepack: false,
+        regenerableFromStore: fallbackKeys.length > 0,
+    };
+}
+function formatLocation(sourceFile, node) {
+    const pos = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+    return { line: pos.line + 1, column: pos.character + 1 };
+}
+function scanSourceFile(sourcePath) {
+    const raw = readFileSync(sourcePath, "utf-8");
+    const sourceFile = ts.createSourceFile(sourcePath, raw, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const sites = [];
+    const scanNode = (node, inheritedConstants, currentFunction) => {
+        if (node !== sourceFile && isFunctionLike(node)) {
+            const name = functionName(node) ?? currentFunction;
+            const constants = collectResolvableConstants(node, sourceFile, inheritedConstants);
+            if (node.body) {
+                ts.forEachChild(node.body, (child) => scanNode(child, constants, name));
+            }
+            return;
+        }
+        if (ts.isCallExpression(node)) {
+            const name = callName(node);
+            if (name && TARGET_CALLS.has(name)) {
+                if (currentFunction && SKIPPED_INTERNAL_FUNCTIONS.has(currentFunction) && name === "safeWrite") {
+                    return;
+                }
+                const firstArg = node.arguments[0];
+                const targetPath = firstArg ? resolveExpression(firstArg, sourceFile, inheritedConstants) : undefined;
+                const resolved = classifyTarget(targetPath);
+                const location = formatLocation(sourceFile, node);
+                sites.push({
+                    call: name,
+                    classification: resolved.classification,
+                    file: normalizeAuditPath(relative(PACKAGE_ROOT, sourcePath)),
+                    line: location.line,
+                    column: location.column,
+                    target_expression: firstArg ? firstArg.getText(sourceFile) : "",
+                    target_path: resolved.canonicalTarget,
+                    fallback_keys: resolved.fallbackKeys,
+                    bypasses_acepack: resolved.bypassesAcepack,
+                    regenerable_from_store: resolved.regenerableFromStore,
+                    note: resolved.note,
+                });
+            }
+        }
+        ts.forEachChild(node, (child) => scanNode(child, inheritedConstants, currentFunction));
+    };
+    const fileConstants = collectResolvableConstants(sourceFile, sourceFile, new Map());
+    ts.forEachChild(sourceFile, (child) => scanNode(child, fileConstants));
+    return sites;
+}
+function groupByClassification(sites) {
+    return {
+        "canonical knowledge artifact": sites.filter((site) => site.classification === "canonical knowledge artifact"),
+        "canonical runtime state": sites.filter((site) => site.classification === "canonical runtime state"),
+        "projection only": sites.filter((site) => site.classification === "projection only"),
+    };
+}
+export function auditStoreAuthority() {
+    const safeWriteSites = collectSourceFiles(SRC_ROOT).flatMap((sourcePath) => scanSourceFile(sourcePath));
+    const classifications = groupByClassification(safeWriteSites);
+    const runtimeFilesWithoutStoreFallbackKeys = safeWriteSites.filter((site) => site.bypasses_acepack);
+    const nonRegenerableProjections = safeWriteSites.filter((site) => site.classification === "projection only" && !site.regenerable_from_store);
+    const report_path = STORE_AUTHORITY_AUDIT_REPORT_REL_PATH;
+    return {
+        bypassing_sites: runtimeFilesWithoutStoreFallbackKeys,
+        classifications,
+        generated_at: new Date().toISOString(),
+        non_regenerable_projections: nonRegenerableProjections,
+        report_path,
+        runtime_files_without_store_fallback_keys: runtimeFilesWithoutStoreFallbackKeys,
+        safe_write_sites: safeWriteSites.sort((left, right) => {
+            const byFile = left.file.localeCompare(right.file);
+            if (byFile !== 0)
+                return byFile;
+            if (left.line !== right.line)
+                return left.line - right.line;
+            return left.column - right.column;
+        }),
+        source_root: SRC_ROOT,
+        total_safe_write_sites: safeWriteSites.length,
+    };
+}
+function renderSites(label, sites) {
+    const lines = [`## ${label}`];
+    if (sites.length === 0) {
+        lines.push("- none");
+        return lines;
+    }
+    for (const site of sites) {
+        lines.push(`- \`${site.file}:${site.line}:${site.column}\` \`${site.call}\` -> \`${site.target_expression || "<dynamic>"}\``);
+        lines.push(`  - target: ${site.target_path ? `\`${site.target_path}\`` : "unresolved"}`);
+        lines.push(`  - fallback keys: ${site.fallback_keys.length > 0 ? site.fallback_keys.map((key) => `\`${key}\``).join(", ") : "none"}`);
+        lines.push(`  - classification: \`${site.classification}\``);
+        lines.push(`  - note: ${site.note}`);
+    }
+    return lines;
+}
+export function renderStoreAuthorityAuditReport(result) {
+    const lines = [
+        "# STORE_AUTHORITY_AUDIT",
+        "",
+        `Generated: ${result.generated_at}`,
+        `Source root: ${result.source_root}`,
+        `Total safeWrite users: ${result.total_safe_write_sites}`,
+        "",
+        "## Summary",
+        `- bypassing ACEPACK: ${result.bypassing_sites.length}`,
+        `- runtime files without store fallback keys: ${result.runtime_files_without_store_fallback_keys.length}`,
+        `- non-regenerable projections: ${result.non_regenerable_projections.length}`,
+        `- canonical knowledge artifacts: ${result.classifications["canonical knowledge artifact"].length}`,
+        `- canonical runtime state writers: ${result.classifications["canonical runtime state"].length}`,
+        `- projection-only writers: ${result.classifications["projection only"].length}`,
+        "",
+        ...renderSites("Writers Bypassing ACEPACK", result.bypassing_sites),
+        "",
+        ...renderSites("Runtime Files Without Store Fallback Keys", result.runtime_files_without_store_fallback_keys),
+        "",
+        ...renderSites("Projections That Cannot Be Regenerated From Store State", result.non_regenerable_projections),
+        "",
+        ...renderSites("Canonical Knowledge Artifacts", result.classifications["canonical knowledge artifact"]),
+        "",
+        ...renderSites("Canonical Runtime State Writers", result.classifications["canonical runtime state"]),
+        "",
+        ...renderSites("Projection Only Writers", result.classifications["projection only"]),
+    ];
+    return lines.join("\n");
+}
+export function writeStoreAuthorityAuditReport(result, targetPath = STORE_AUTHORITY_AUDIT_REPORT_REL_PATH) {
+    return safeWrite(targetPath, renderStoreAuthorityAuditReport(result));
+}
+//# sourceMappingURL=store-authority-audit.js.map

package/dist/store/types.d.ts

@@ -25,6 +25,7 @@ export declare const EntityKind: {
     readonly DomainDocument: 17;
     readonly HookContext: 18;
     readonly CatalogEntry: 19;
+    readonly ContextSnapshot: 20;
 };
 export type EntityKindCode = (typeof EntityKind)[keyof typeof EntityKind];
 export interface UnifiedEntry {
@@ -99,6 +100,7 @@ export interface StateReader {
     sessions(): Promise<unknown[]>;
     statusEvents(): Promise<unknown[]>;
     providerDiscovery(): Promise<unknown[]>;
+    runtimeStatuses(): Promise<unknown[]>;
     vericifyPosts(): Promise<unknown[]>;
     domainDocs(domain: string): Promise<unknown[]>;
 }

package/dist/store/types.js

@@ -27,6 +27,7 @@ export const EntityKind = {
     DomainDocument: 17,
     HookContext: 18,
     CatalogEntry: 19,
+    ContextSnapshot: 20,
 };
 // ── Store file header constants ───────────────────────────────────────────────
 export const MAGIC = "ACEPACK\0";