@sapiom/harness 0.8.9 → 0.9.0

package/dist/core/system-graph-store.d.ts

@@ -0,0 +1,45 @@
+import type { SystemGraphSnapshot, WorkspaceKey } from "../shared/system-graph.js";
+import type { SystemGraphBuilder, WorkspaceScope } from "./system-graph.js";
+export interface SystemGraphStoreOptions {
+    /** Called only for an accepted lifecycle transition. */
+    onChange?: (snapshot: SystemGraphSnapshot) => void;
+}
+/**
+ * Process-lifetime, workspace-scoped projection store.
+ *
+ * Cold reads coalesce behind one build. Later refreshes keep the last usable
+ * graph visible as stale, serialize rebuilds, and reject an older generation's
+ * result when another edit arrives while it is in flight.
+ */
+export declare class SystemGraphStore {
+    private readonly builder;
+    private readonly options;
+    private readonly entries;
+    private readonly revisionFloors;
+    constructor(builder: SystemGraphBuilder, options?: SystemGraphStoreOptions);
+    get(scope: WorkspaceScope): Promise<SystemGraphSnapshot>;
+    /** Marks a workspace dirty and starts (or queues) a background refresh. */
+    requestRefresh(scope: WorkspaceScope): SystemGraphSnapshot;
+    /** Explicit user recovery: start a fresh projection and await its result. */
+    refresh(scope: WorkspaceScope): Promise<SystemGraphSnapshot>;
+    peek(workspaceKey: WorkspaceKey): SystemGraphSnapshot | null;
+    /** Records a refresh prerequisite failure while preserving visible data. */
+    reportRefreshFailure(scope: WorkspaceScope): SystemGraphSnapshot;
+    /** Retires projections for workspace scopes Studio no longer exposes. */
+    retain(workspaceKeys: ReadonlySet<WorkspaceKey>): void;
+    /** Stops retaining a scope that Studio no longer exposes. */
+    retire(workspaceKey: WorkspaceKey): void;
+    /** Backward-compatible alias for callers that explicitly drop a snapshot. */
+    invalidate(workspaceKey: WorkspaceKey): void;
+    clear(): void;
+    private ensureEntry;
+    private queueRefresh;
+    private startBuild;
+    private finishBuild;
+    private finishFailure;
+    private canCommit;
+    private continueAfterSupersededBuild;
+    private retainBuilderWorkspaces;
+    private transition;
+}
+//# sourceMappingURL=system-graph-store.d.ts.map

package/dist/core/system-graph-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-graph-store.d.ts","sourceRoot":"","sources":["../../src/core/system-graph-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,mBAAmB,EACnB,YAAY,EACb,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAE5E,MAAM,WAAW,uBAAuB;IACtC,wDAAwD;IACxD,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,mBAAmB,KAAK,IAAI,CAAC;CACpD;AAaD;;;;;;GAMG;AACH,qBAAa,gBAAgB;IAKzB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAL1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6C;IACrE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAmC;gBAG/C,OAAO,EAAE,kBAAkB,EAC3B,OAAO,GAAE,uBAA4B;IAGxD,GAAG,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAyBxD,2EAA2E;IAC3E,cAAc,CAAC,KAAK,EAAE,cAAc,GAAG,mBAAmB;IAO1D,6EAA6E;IAC7E,OAAO,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAM5D,IAAI,CAAC,YAAY,EAAE,YAAY,GAAG,mBAAmB,GAAG,IAAI;IAI5D,4EAA4E;IAC5E,oBAAoB,CAAC,KAAK,EAAE,cAAc,GAAG,mBAAmB;IAchE,yEAAyE;IACzE,MAAM,CAAC,aAAa,EAAE,WAAW,CAAC,YAAY,CAAC,GAAG,IAAI;IAMtD,6DAA6D;IAC7D,MAAM,CAAC,YAAY,EAAE,YAAY,GAAG,IAAI;IAUxC,6EAA6E;IAC7E,UAAU,CAAC,YAAY,EAAE,YAAY,GAAG,IAAI;IAI5C,KAAK,IAAI,IAAI;IAOb,OAAO,CAAC,WAAW;IAyBnB,OAAO,CAAC,YAAY;IAoBpB,OAAO,CAAC,UAAU;IA4BlB,OAAO,CAAC,WAAW;IAiBnB,OAAO,CAAC,aAAa;IAcrB,OAAO,CAAC,SAAS;IAQjB,OAAO,CAAC,4BAA4B;IAkBpC,OAAO,CAAC,uBAAuB;IAQ/B,OAAO,CAAC,UAAU;CA8BnB"}

package/dist/core/system-graph-store.js

@@ -0,0 +1,222 @@
+/**
+ * Process-lifetime, workspace-scoped projection store.
+ *
+ * Cold reads coalesce behind one build. Later refreshes keep the last usable
+ * graph visible as stale, serialize rebuilds, and reject an older generation's
+ * result when another edit arrives while it is in flight.
+ */
+export class SystemGraphStore {
+    constructor(builder, options = {}) {
+        this.builder = builder;
+        this.options = options;
+        this.entries = new Map();
+        this.revisionFloors = new Map();
+    }
+    get(scope) {
+        const entry = this.ensureEntry(scope);
+        if (entry.activeBuild) {
+            return entry.snapshot.graph === null
+                ? entry.activeBuild
+                : Promise.resolve(entry.snapshot);
+        }
+        if (entry.snapshot.state === "building" && entry.snapshot.graph === null) {
+            return this.startBuild(entry);
+        }
+        // Non-ready projections are deliberately not healthy cache hits. One
+        // later open awaits a recovery build, while a permanent failure cannot
+        // charge every collapse/expand forever.
+        if ((entry.snapshot.state === "degraded" ||
+            entry.snapshot.state === "stale") &&
+            !entry.automaticRetryUsed) {
+            entry.automaticRetryUsed = true;
+            this.queueRefresh(entry, entry.snapshot.state === "degraded");
+        }
+        return Promise.resolve(entry.snapshot);
+    }
+    /** Marks a workspace dirty and starts (or queues) a background refresh. */
+    requestRefresh(scope) {
+        const entry = this.ensureEntry(scope);
+        entry.automaticRetryUsed = false;
+        this.queueRefresh(entry);
+        return entry.snapshot;
+    }
+    /** Explicit user recovery: start a fresh projection and await its result. */
+    refresh(scope) {
+        const entry = this.ensureEntry(scope);
+        entry.automaticRetryUsed = false;
+        return this.queueRefresh(entry) ?? Promise.resolve(entry.snapshot);
+    }
+    peek(workspaceKey) {
+        return this.entries.get(workspaceKey)?.snapshot ?? null;
+    }
+    /** Records a refresh prerequisite failure while preserving visible data. */
+    reportRefreshFailure(scope) {
+        const entry = this.ensureEntry(scope);
+        entry.generation += 1;
+        entry.refreshPending = false;
+        // Registry recovery must happen before projection. Do not let a later
+        // graph read rebuild from the stale inventory and relabel it ready; the
+        // watcher retries the failed inventory callback instead.
+        entry.automaticRetryUsed = true;
+        const visibleGraph = entry.lastGood ?? entry.snapshot.graph;
+        return visibleGraph === null
+            ? this.transition(entry, "degraded", null)
+            : this.transition(entry, "stale", visibleGraph);
+    }
+    /** Retires projections for workspace scopes Studio no longer exposes. */
+    retain(workspaceKeys) {
+        for (const workspaceKey of [...this.entries.keys()]) {
+            if (!workspaceKeys.has(workspaceKey))
+                this.retire(workspaceKey);
+        }
+    }
+    /** Stops retaining a scope that Studio no longer exposes. */
+    retire(workspaceKey) {
+        const entry = this.entries.get(workspaceKey);
+        if (!entry)
+            return;
+        entry.retired = true;
+        entry.generation += 1;
+        this.revisionFloors.set(workspaceKey, entry.snapshot.revision);
+        this.entries.delete(workspaceKey);
+        this.retainBuilderWorkspaces();
+    }
+    /** Backward-compatible alias for callers that explicitly drop a snapshot. */
+    invalidate(workspaceKey) {
+        this.retire(workspaceKey);
+    }
+    clear() {
+        for (const workspaceKey of [...this.entries.keys()]) {
+            this.retire(workspaceKey);
+        }
+        this.revisionFloors.clear();
+    }
+    ensureEntry(scope) {
+        const existing = this.entries.get(scope.workspaceKey);
+        if (existing) {
+            existing.scope = scope;
+            return existing;
+        }
+        const entry = {
+            scope,
+            snapshot: {
+                workspaceKey: scope.workspaceKey,
+                revision: this.revisionFloors.get(scope.workspaceKey) ?? 0,
+                state: "building",
+                graph: null,
+            },
+            lastGood: null,
+            activeBuild: null,
+            generation: 0,
+            refreshPending: false,
+            automaticRetryUsed: false,
+            retired: false,
+        };
+        this.entries.set(scope.workspaceKey, entry);
+        return entry;
+    }
+    queueRefresh(entry, preserveLifecycle = false) {
+        if (entry.retired)
+            return null;
+        entry.generation += 1;
+        entry.refreshPending = true;
+        const visibleGraph = entry.lastGood ?? entry.snapshot.graph;
+        if (!preserveLifecycle) {
+            this.transition(entry, visibleGraph === null ? "building" : "stale", visibleGraph);
+        }
+        if (entry.activeBuild)
+            return entry.activeBuild;
+        entry.refreshPending = false;
+        return this.startBuild(entry);
+    }
+    startBuild(entry) {
+        if (entry.activeBuild)
+            return entry.activeBuild;
+        const generation = entry.generation;
+        entry.refreshPending = false;
+        const visibleGraph = entry.lastGood ?? entry.snapshot.graph;
+        if (entry.snapshot.state !== "degraded") {
+            this.transition(entry, visibleGraph === null ? "building" : "stale", visibleGraph);
+        }
+        let build;
+        try {
+            build = Promise.resolve(this.builder.build(entry.scope));
+        }
+        catch (error) {
+            build = Promise.reject(error);
+        }
+        const active = build.then((result) => this.finishBuild(entry, generation, result), () => this.finishFailure(entry, generation));
+        entry.activeBuild = active;
+        return active;
+    }
+    finishBuild(entry, generation, result) {
+        if (!this.canCommit(entry, generation)) {
+            return this.continueAfterSupersededBuild(entry);
+        }
+        entry.activeBuild = null;
+        if (result.cacheable) {
+            entry.lastGood = result.graph;
+            entry.automaticRetryUsed = false;
+            return this.transition(entry, "ready", result.graph);
+        }
+        return this.transition(entry, "degraded", result.graph);
+    }
+    finishFailure(entry, generation) {
+        if (!this.canCommit(entry, generation)) {
+            return this.continueAfterSupersededBuild(entry);
+        }
+        entry.activeBuild = null;
+        const visibleGraph = entry.lastGood ?? entry.snapshot.graph;
+        return visibleGraph === null
+            ? this.transition(entry, "degraded", null)
+            : this.transition(entry, "stale", visibleGraph, true);
+    }
+    canCommit(entry, generation) {
+        return (!entry.retired &&
+            this.entries.get(entry.scope.workspaceKey) === entry &&
+            entry.generation === generation);
+    }
+    continueAfterSupersededBuild(entry) {
+        entry.activeBuild = null;
+        if (entry.retired ||
+            this.entries.get(entry.scope.workspaceKey) !== entry) {
+            this.retainBuilderWorkspaces();
+            return entry.snapshot;
+        }
+        if (entry.refreshPending) {
+            entry.refreshPending = false;
+            return this.startBuild(entry);
+        }
+        return entry.snapshot;
+    }
+    retainBuilderWorkspaces() {
+        try {
+            this.builder.retainWorkspaces?.(new Set(this.entries.keys()));
+        }
+        catch {
+            // Cache pruning cannot make graph reads or scope retirement fail.
+        }
+    }
+    transition(entry, state, graph, forceRevision = false) {
+        if (!forceRevision &&
+            entry.snapshot.state === state &&
+            entry.snapshot.graph === graph) {
+            return entry.snapshot;
+        }
+        entry.snapshot = {
+            workspaceKey: entry.scope.workspaceKey,
+            revision: entry.snapshot.revision + 1,
+            state,
+            graph,
+        };
+        this.revisionFloors.set(entry.scope.workspaceKey, entry.snapshot.revision);
+        try {
+            this.options.onChange?.(entry.snapshot);
+        }
+        catch {
+            // Observers (the event bus) cannot make graph refreshes fail.
+        }
+        return entry.snapshot;
+    }
+}
+//# sourceMappingURL=system-graph-store.js.map

package/dist/core/system-graph-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-graph-store.js","sourceRoot":"","sources":["../../src/core/system-graph-store.ts"],"names":[],"mappings":"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"}

package/dist/core/system-graph-watcher.d.ts

@@ -0,0 +1,51 @@
+import type { WorkspaceKey } from "../shared/system-graph.js";
+import type { WorkspaceScope } from "./system-graph.js";
+/**
+ * Async source fingerprint for the registered agent roots in one workspace.
+ *
+ * The graph watcher deliberately does not reuse Canvas's synchronous,
+ * 400-file project snapshot here: a workspace can contain many agent projects,
+ * and polling it on the server event loop would both stutter Studio and miss
+ * edits after that project-sized ceiling. Async directory reads yield between
+ * entries, while scoping the walk to registry roots keeps the unbounded file
+ * count honest without traversing unrelated workspace trees.
+ */
+export declare function snapshotWorkflowSourceRootsAsync(sourceRoots: readonly string[]): Promise<ReadonlyMap<string, string>>;
+export interface SystemGraphWatcherCallbacks {
+    /** Current registry roots inside this scope; read lazily on every poll. */
+    listSourceRoots: (scope: WorkspaceScope) => readonly string[];
+    onSourceChange: (scope: WorkspaceScope, 
+    /** Null when the platform can only report a workspace-level change. */
+    sourcePaths: readonly string[] | null) => void | Promise<void>;
+    onInventoryChange: (scope: WorkspaceScope) => void | Promise<void>;
+}
+export interface SystemGraphWatchHandle {
+    close(): void;
+    on(event: "error", listener: (error: Error) => void): SystemGraphWatchHandle;
+}
+export type SystemGraphWatchFactory = (root: string, listener: (event: "rename" | "change", filename: string | null) => void) => SystemGraphWatchHandle;
+export interface SystemGraphWatcherOptions {
+    sourceDebounceMs?: number;
+    inventoryDebounceMs?: number;
+    inventoryRetryBaseMs?: number;
+    maxInventoryRetries?: number;
+    pollIntervalMs?: number;
+    /** Deterministic test seam for the supported polling fallback. */
+    forcePolling?: boolean;
+    /** Deterministic test seam for native event routing and watcher errors. */
+    watchFactory?: SystemGraphWatchFactory;
+}
+/** One watcher per requested workspace, independent of harness sessions. */
+export declare class SystemGraphWatcherManager {
+    private readonly callbacks;
+    private readonly options;
+    private readonly watchers;
+    private readonly pendingStarts;
+    constructor(callbacks: SystemGraphWatcherCallbacks, options?: SystemGraphWatcherOptions);
+    start(scope: WorkspaceScope): Promise<void>;
+    retain(workspaceKeys: ReadonlySet<WorkspaceKey>): void;
+    stop(workspaceKey: WorkspaceKey): void;
+    stopAll(): void;
+    get size(): number;
+}
+//# sourceMappingURL=system-graph-watcher.d.ts.map

package/dist/core/system-graph-watcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-graph-watcher.d.ts","sourceRoot":"","sources":["../../src/core/system-graph-watcher.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAG9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAsCxD;;;;;;;;;GASG;AACH,wBAAsB,gCAAgC,CACpD,WAAW,EAAE,SAAS,MAAM,EAAE,GAC7B,OAAO,CAAC,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAwCtC;AAgCD,MAAM,WAAW,2BAA2B;IAC1C,2EAA2E;IAC3E,eAAe,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,SAAS,MAAM,EAAE,CAAC;IAC9D,cAAc,EAAE,CACd,KAAK,EAAE,cAAc;IACrB,uEAAuE;IACvE,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,KAClC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B,iBAAiB,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpE;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,IAAI,IAAI,CAAC;IACd,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,sBAAsB,CAAC;CAC9E;AAED,MAAM,MAAM,uBAAuB,GAAG,CACpC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,CAAC,KAAK,EAAE,QAAQ,GAAG,QAAQ,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,KACpE,sBAAsB,CAAC;AAE5B,MAAM,WAAW,yBAAyB;IACxC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kEAAkE;IAClE,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,2EAA2E;IAC3E,YAAY,CAAC,EAAE,uBAAuB,CAAC;CACxC;AAgUD,4EAA4E;AAC5E,qBAAa,yBAAyB;IAWlC,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAX1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAGrB;IACJ,OAAO,CAAC,QAAQ,CAAC,aAAa,CAG1B;gBAGe,SAAS,EAAE,2BAA2B,EACtC,OAAO,GAAE,yBAA8B;IAG1D,KAAK,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAiC3C,MAAM,CAAC,aAAa,EAAE,WAAW,CAAC,YAAY,CAAC,GAAG,IAAI;IAUtD,IAAI,CAAC,YAAY,EAAE,YAAY,GAAG,IAAI;IAMtC,OAAO,IAAI,IAAI;IAUf,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}