@lsctech/polaris 0.1.0

package/dist/loop/lifecycle-dispatch.test.js

@@ -0,0 +1,318 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_os_1 = require("node:os");
+const lifecycle_dispatch_js_1 = require("./lifecycle-dispatch.js");
+function makeDir() {
+    const dir = (0, node_path_1.join)((0, node_os_1.tmpdir)(), `polaris-lifecycle-dispatch-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+    return dir;
+}
+function baseConfig() {
+    return {
+        version: "1.0",
+        repo: {
+            name: "",
+            sourceRoots: ["src"],
+            docsRoots: [],
+            taskchainRoots: [],
+            generatedRoots: [],
+            sidecarOutputPath: ".polaris/map",
+        },
+        map: {
+            confidenceThreshold: 0.75,
+            autoWriteAbove: 0.85,
+            reviewRequiredBelow: 0.75,
+            inferenceRules: [],
+            onLowConfidence: "warn",
+        },
+        loop: {
+            bootstrapOutputPath: ".polaris/bootstrap",
+            analyzeImplBoundaryEnforced: true,
+            sessionTerminationMode: "emit-marker",
+            allowBranchDivergence: false,
+        },
+        orchestration: {
+            mode: "auto",
+            auto_finalize: false,
+            notification_format: "terse",
+        },
+        execution: {
+            adapter: "terminal-cli",
+            providers: {
+                worker: { command: "worker-cli" },
+                startup: { command: "startup-cli" },
+                finalizer: { command: "finalizer-cli" },
+            },
+            rotation: ["worker"],
+            allowCrossAgentFallback: false,
+            roles: {
+                worker: { provider: "worker" },
+                startup: { provider: "startup", model: "gpt-startup" },
+                finalizer: { provider: "finalizer", model: "gpt-finalizer" },
+            },
+        },
+        finalize: {
+            targetBranch: "main",
+            prDraft: true,
+            runChecks: [],
+            requireMapValidation: true,
+            requireSchemaValidation: true,
+            archiveRunSnapshot: true,
+        },
+        tracker: {
+            linear: {
+                enabled: false,
+                teamId: "",
+                projectId: "",
+            },
+        },
+        integrations: {
+            github: {
+                owner: "",
+                repo: "",
+            },
+        },
+        canon: {
+            checkOnContinue: true,
+            checkOnFinalize: true,
+        },
+        providers: {
+            repoAnalysis: {
+                preferred: undefined,
+                fallback: ["polaris-map", "ripgrep"],
+            },
+            compactionProviders: [],
+        },
+        budget: {
+            mode: "fixed-cap",
+            max_children: 3,
+            stop_on_fail: false,
+            allow_analyze_children: false,
+        },
+        compact: {
+            orchestratorMode: "standard",
+            workerMode: "standard",
+            level: "standard",
+        },
+        skill_packet: {
+            analysis_confidence_threshold: 85,
+            auto_deep_analysis: false,
+            allow_cross_provider_delegation: false,
+        },
+    };
+}
+function makeAdapter(writeResult) {
+    return {
+        name: "mock",
+        async dispatch(packet, options) {
+            const resultFile = packet.result_file_contract?.result_file;
+            const result = writeResult(packet);
+            if (resultFile && result !== undefined) {
+                (0, node_fs_1.writeFileSync)(resultFile, typeof result === "string" ? result : JSON.stringify(result, null, 2));
+            }
+            return {
+                exit_code: 0,
+                provider_used: options.provider,
+                command_run: `mock:${options.provider}`,
+                summary: JSON.stringify({ status: "done" }),
+            };
+        },
+    };
+}
+(0, vitest_1.describe)("resolveLifecycleProvider", () => {
+    (0, vitest_1.it)("selects role-specific provider and model before default worker rotation", () => {
+        const resolved = (0, lifecycle_dispatch_js_1.resolveLifecycleProvider)(baseConfig(), "startup");
+        (0, vitest_1.expect)(resolved).toEqual({
+            adapter: "terminal-cli",
+            provider: "startup",
+            model: "gpt-startup",
+        });
+    });
+});
+(0, vitest_1.describe)("dispatchLifecyclePhase", () => {
+    (0, vitest_1.it)("executes startup as a sealed dispatch phase and records role telemetry", async () => {
+        const dir = makeDir();
+        try {
+            const telemetryFile = (0, node_path_1.join)(dir, "telemetry.jsonl");
+            const result = await (0, lifecycle_dispatch_js_1.dispatchLifecyclePhase)({
+                phase: "startup",
+                runId: "run-1",
+                clusterId: "POL-188",
+                branch: "polaris/POL-188",
+                stateFile: (0, node_path_1.join)(dir, "current-state.json"),
+                telemetryFile,
+                config: baseConfig(),
+                adapter: makeAdapter((packet) => ({
+                    run_id: packet.run_id,
+                    role: "startup",
+                    status: "success",
+                    execution_plan: ["POL-198"],
+                    first_child: "POL-198",
+                })),
+            });
+            (0, vitest_1.expect)(result.ok).toBe(true);
+            if (result.ok) {
+                (0, vitest_1.expect)(result.role).toBe("startup");
+                (0, vitest_1.expect)(result.provider).toBe("startup");
+                (0, vitest_1.expect)(result.result.first_child).toBe("POL-198");
+            }
+            const telemetry = (0, node_fs_1.readFileSync)(telemetryFile, "utf-8");
+            (0, vitest_1.expect)(telemetry).toContain("\"event\":\"lifecycle-dispatched\"");
+            (0, vitest_1.expect)(telemetry).toContain("\"role\":\"startup\"");
+            (0, vitest_1.expect)(telemetry).toContain("\"event\":\"lifecycle-result-accepted\"");
+        }
+        finally {
+            (0, node_fs_1.rmSync)(dir, { recursive: true, force: true });
+        }
+    });
+    (0, vitest_1.it)("executes finalization as a sealed dispatch phase", async () => {
+        const dir = makeDir();
+        try {
+            const result = await (0, lifecycle_dispatch_js_1.dispatchLifecyclePhase)({
+                phase: "finalize",
+                runId: "run-1",
+                clusterId: "POL-188",
+                branch: "polaris/POL-188",
+                stateFile: (0, node_path_1.join)(dir, "current-state.json"),
+                telemetryFile: (0, node_path_1.join)(dir, "telemetry.jsonl"),
+                config: baseConfig(),
+                adapter: makeAdapter((packet) => ({
+                    run_id: packet.run_id,
+                    role: "finalize",
+                    status: "success",
+                    branch_validated: true,
+                    commits_validated: true,
+                    tests_validated: true,
+                    tracker_reconciliation_ready: true,
+                })),
+            });
+            (0, vitest_1.expect)(result.ok).toBe(true);
+            if (result.ok) {
+                (0, vitest_1.expect)(result.role).toBe("finalize");
+                (0, vitest_1.expect)(result.provider).toBe("finalizer");
+                (0, vitest_1.expect)(result.result.tracker_reconciliation_ready).toBe(true);
+            }
+        }
+        finally {
+            (0, node_fs_1.rmSync)(dir, { recursive: true, force: true });
+        }
+    });
+    (0, vitest_1.it)("archives cognition notes after accepting a sealed lifecycle result", async () => {
+        const dir = makeDir();
+        try {
+            (0, node_fs_1.mkdirSync)((0, node_path_1.join)(dir, ".git"), { recursive: true });
+            (0, node_fs_1.mkdirSync)((0, node_path_1.join)(dir, ".polaris", "cognition", "pending", "src", "loop"), { recursive: true });
+            (0, node_fs_1.writeFileSync)((0, node_path_1.join)(dir, ".polaris", "cognition", "pending", "src", "loop", "note.md"), "pending note", "utf-8");
+            const result = await (0, lifecycle_dispatch_js_1.dispatchLifecyclePhase)({
+                phase: "finalize",
+                runId: "run-1",
+                clusterId: "POL-188",
+                branch: "polaris/POL-188",
+                repoRoot: dir,
+                stateFile: (0, node_path_1.join)(dir, "current-state.json"),
+                telemetryFile: (0, node_path_1.join)(dir, "telemetry.jsonl"),
+                config: baseConfig(),
+                adapter: makeAdapter((packet) => ({
+                    run_id: packet.run_id,
+                    role: "finalize",
+                    status: "success",
+                    cognition_archive: {
+                        reconcile_id: "reconcile-1",
+                        notes_consumed: ["src/loop/note.md"],
+                        polaris_md_updated: true,
+                        summary_md_updated: false,
+                    },
+                })),
+            });
+            (0, vitest_1.expect)(result.ok).toBe(true);
+            (0, vitest_1.expect)((0, node_fs_1.readFileSync)((0, node_path_1.join)(dir, ".polaris", "cognition", "archive", "src", "loop", "note.md"), "utf-8")).toBe("pending note");
+            const index = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(dir, ".polaris", "cognition", "archive", "src", "loop", "cognition-index.json"), "utf-8"));
+            (0, vitest_1.expect)(index.entries).toEqual([
+                {
+                    reconcile_id: "reconcile-1",
+                    run_id: "run-1",
+                    reconciled_at: vitest_1.expect.any(String),
+                    notes_consumed: ["note.md"],
+                    polaris_md_updated: true,
+                    summary_md_updated: false,
+                },
+            ]);
+        }
+        finally {
+            (0, node_fs_1.rmSync)(dir, { recursive: true, force: true });
+        }
+    });
+    (0, vitest_1.it)("halts safely when the sealed result file is missing", async () => {
+        const dir = makeDir();
+        try {
+            const result = await (0, lifecycle_dispatch_js_1.dispatchLifecyclePhase)({
+                phase: "finalize",
+                runId: "run-1",
+                clusterId: "POL-188",
+                branch: "polaris/POL-188",
+                stateFile: (0, node_path_1.join)(dir, "current-state.json"),
+                telemetryFile: (0, node_path_1.join)(dir, "telemetry.jsonl"),
+                config: baseConfig(),
+                adapter: makeAdapter(() => undefined),
+            });
+            (0, vitest_1.expect)(result.ok).toBe(false);
+            if (!result.ok) {
+                (0, vitest_1.expect)(result.error).toBe("missing_result");
+            }
+        }
+        finally {
+            (0, node_fs_1.rmSync)(dir, { recursive: true, force: true });
+        }
+    });
+    (0, vitest_1.it)("halts safely on malformed sealed result JSON", async () => {
+        const dir = makeDir();
+        try {
+            const result = await (0, lifecycle_dispatch_js_1.dispatchLifecyclePhase)({
+                phase: "startup",
+                runId: "run-1",
+                clusterId: "POL-188",
+                branch: "polaris/POL-188",
+                stateFile: (0, node_path_1.join)(dir, "current-state.json"),
+                telemetryFile: (0, node_path_1.join)(dir, "telemetry.jsonl"),
+                config: baseConfig(),
+                adapter: makeAdapter(() => "{not json"),
+            });
+            (0, vitest_1.expect)(result.ok).toBe(false);
+            if (!result.ok) {
+                (0, vitest_1.expect)(result.error).toBe("malformed_result");
+            }
+        }
+        finally {
+            (0, node_fs_1.rmSync)(dir, { recursive: true, force: true });
+        }
+    });
+    (0, vitest_1.it)("halts safely on mismatched result role", async () => {
+        const dir = makeDir();
+        try {
+            const result = await (0, lifecycle_dispatch_js_1.dispatchLifecyclePhase)({
+                phase: "startup",
+                runId: "run-1",
+                clusterId: "POL-188",
+                branch: "polaris/POL-188",
+                stateFile: (0, node_path_1.join)(dir, "current-state.json"),
+                telemetryFile: (0, node_path_1.join)(dir, "telemetry.jsonl"),
+                config: baseConfig(),
+                adapter: makeAdapter((packet) => ({
+                    run_id: packet.run_id,
+                    role: "finalize",
+                    status: "success",
+                })),
+            });
+            (0, vitest_1.expect)(result.ok).toBe(false);
+            if (!result.ok) {
+                (0, vitest_1.expect)(result.error).toBe("mismatched_result");
+            }
+        }
+        finally {
+            (0, node_fs_1.rmSync)(dir, { recursive: true, force: true });
+        }
+    });
+});

package/dist/loop/lifecycle.js

@@ -0,0 +1,93 @@
+"use strict";
+/**
+ * Worker lifecycle manager for delegated-chain execution.
+ *
+ * Enforces the one-active-worker policy: by default the parent may have at
+ * most one live worker at a time. The parent calls register() immediately
+ * before dispatch and release() immediately after the worker returns a result.
+ *
+ * On session startup the parent should call forceReleaseAll() to recover from
+ * any orphaned registrations left by a previous crashed session.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorkerLifecycleManager = void 0;
+// ── WorkerLifecycleManager ────────────────────────────────────────────────────
+class WorkerLifecycleManager {
+    workers = new Map();
+    maxConcurrentWorkers;
+    constructor(maxConcurrentWorkers = 1) {
+        if (maxConcurrentWorkers < 1) {
+            throw new RangeError(`maxConcurrentWorkers must be >= 1, got ${maxConcurrentWorkers}`);
+        }
+        this.maxConcurrentWorkers = maxConcurrentWorkers;
+    }
+    // ── Slot management ─────────────────────────────────────────────────────────
+    /** Returns true when a new worker can be dispatched without exceeding the limit. */
+    canDispatch() {
+        return this.workers.size < this.maxConcurrentWorkers;
+    }
+    /**
+     * Register a worker before dispatch.
+     * Throws `Error` if the active-worker limit would be exceeded.
+     */
+    register(workerId, childId, role) {
+        if (this.workers.has(workerId)) {
+            throw new Error(`Worker "${workerId}" is already registered`);
+        }
+        if (!this.canDispatch()) {
+            const active = this.describeActive();
+            throw new Error(`Cannot dispatch worker "${workerId}": ` +
+                `${this.workers.size}/${this.maxConcurrentWorkers} worker slot(s) in use. ` +
+                `Active: ${active}. ` +
+                `Release the active worker before dispatching a new one.`);
+        }
+        const record = {
+            worker_id: workerId,
+            child_id: childId,
+            role,
+            dispatched_at: new Date().toISOString(),
+        };
+        this.workers.set(workerId, record);
+        return record;
+    }
+    /**
+     * Release a worker after it returns.
+     * No-op if the worker ID is not registered (idempotent).
+     */
+    release(workerId) {
+        this.workers.delete(workerId);
+    }
+    // ── Inspection ──────────────────────────────────────────────────────────────
+    /** Returns snapshot of currently registered workers. */
+    getActiveWorkers() {
+        return Array.from(this.workers.values());
+    }
+    /** Active worker count. */
+    get activeCount() {
+        return this.workers.size;
+    }
+    /** Returns true when any workers remain registered (orphan indicator). */
+    hasOrphanedWorkers() {
+        return this.workers.size > 0;
+    }
+    // ── Recovery ────────────────────────────────────────────────────────────────
+    /**
+     * Force-release all active registrations without waiting for workers.
+     * Use at session startup to recover from orphaned state.
+     * Returns the IDs that were released.
+     */
+    forceReleaseAll() {
+        const ids = Array.from(this.workers.keys());
+        this.workers.clear();
+        return ids;
+    }
+    // ── Helpers ──────────────────────────────────────────────────────────────────
+    describeActive() {
+        if (this.workers.size === 0)
+            return '(none)';
+        return Array.from(this.workers.values())
+            .map((w) => `${w.worker_id}[${w.role}:${w.child_id ?? 'no-child'}]`)
+            .join(', ');
+    }
+}
+exports.WorkerLifecycleManager = WorkerLifecycleManager;

package/dist/loop/lifecycle.test.js

@@ -0,0 +1,150 @@
+"use strict";
+/**
+ * Unit tests for src/loop/lifecycle.ts
+ *
+ * Verifies one-active-worker enforcement, register/release semantics,
+ * and orphan recovery via forceReleaseAll().
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const lifecycle_js_1 = require("./lifecycle.js");
+// ── Constructor ───────────────────────────────────────────────────────────────
+(0, vitest_1.describe)("WorkerLifecycleManager constructor", () => {
+    (0, vitest_1.it)("defaults to maxConcurrentWorkers = 1", () => {
+        const m = new lifecycle_js_1.WorkerLifecycleManager();
+        (0, vitest_1.expect)(m.maxConcurrentWorkers).toBe(1);
+    });
+    (0, vitest_1.it)("accepts a custom maxConcurrentWorkers", () => {
+        const m = new lifecycle_js_1.WorkerLifecycleManager(3);
+        (0, vitest_1.expect)(m.maxConcurrentWorkers).toBe(3);
+    });
+    (0, vitest_1.it)("throws RangeError for maxConcurrentWorkers < 1", () => {
+        (0, vitest_1.expect)(() => new lifecycle_js_1.WorkerLifecycleManager(0)).toThrow(RangeError);
+        (0, vitest_1.expect)(() => new lifecycle_js_1.WorkerLifecycleManager(-1)).toThrow(RangeError);
+    });
+});
+// ── canDispatch ───────────────────────────────────────────────────────────────
+(0, vitest_1.describe)("canDispatch", () => {
+    (0, vitest_1.it)("returns true when no workers are registered", () => {
+        const m = new lifecycle_js_1.WorkerLifecycleManager(1);
+        (0, vitest_1.expect)(m.canDispatch()).toBe(true);
+    });
+    (0, vitest_1.it)("returns false when the slot is full", () => {
+        const m = new lifecycle_js_1.WorkerLifecycleManager(1);
+        m.register("w1", "POL-121", "impl");
+        (0, vitest_1.expect)(m.canDispatch()).toBe(false);
+    });
+    (0, vitest_1.it)("returns true after all slots are released", () => {
+        const m = new lifecycle_js_1.WorkerLifecycleManager(1);
+        m.register("w1", "POL-121", "impl");
+        m.release("w1");
+        (0, vitest_1.expect)(m.canDispatch()).toBe(true);
+    });
+});
+// ── register ──────────────────────────────────────────────────────────────────
+(0, vitest_1.describe)("register", () => {
+    (0, vitest_1.it)("returns the worker record", () => {
+        const m = new lifecycle_js_1.WorkerLifecycleManager(1);
+        const rec = m.register("w1", "POL-121", "impl");
+        (0, vitest_1.expect)(rec.worker_id).toBe("w1");
+        (0, vitest_1.expect)(rec.child_id).toBe("POL-121");
+        (0, vitest_1.expect)(rec.role).toBe("impl");
+        (0, vitest_1.expect)(typeof rec.dispatched_at).toBe("string");
+    });
+    (0, vitest_1.it)("throws when slot limit is already reached", () => {
+        const m = new lifecycle_js_1.WorkerLifecycleManager(1);
+        m.register("w1", "POL-121", "impl");
+        (0, vitest_1.expect)(() => m.register("w2", "POL-122", "impl")).toThrow(/slot/i);
+    });
+    (0, vitest_1.it)("allows null child_id for finalize workers", () => {
+        const m = new lifecycle_js_1.WorkerLifecycleManager(1);
+        const rec = m.register("w1", null, "finalize");
+        (0, vitest_1.expect)(rec.child_id).toBeNull();
+    });
+    (0, vitest_1.it)("increments activeCount after register", () => {
+        const m = new lifecycle_js_1.WorkerLifecycleManager(2);
+        (0, vitest_1.expect)(m.activeCount).toBe(0);
+        m.register("w1", "POL-121", "impl");
+        (0, vitest_1.expect)(m.activeCount).toBe(1);
+        m.register("w2", "POL-122", "impl");
+        (0, vitest_1.expect)(m.activeCount).toBe(2);
+    });
+});
+// ── release ───────────────────────────────────────────────────────────────────
+(0, vitest_1.describe)("release", () => {
+    (0, vitest_1.it)("removes the worker from active set", () => {
+        const m = new lifecycle_js_1.WorkerLifecycleManager(1);
+        m.register("w1", "POL-121", "impl");
+        m.release("w1");
+        (0, vitest_1.expect)(m.activeCount).toBe(0);
+    });
+    (0, vitest_1.it)("is idempotent — releasing an unknown ID is a no-op", () => {
+        const m = new lifecycle_js_1.WorkerLifecycleManager(1);
+        (0, vitest_1.expect)(() => m.release("unknown-worker")).not.toThrow();
+    });
+    (0, vitest_1.it)("frees the slot for the next dispatch", () => {
+        const m = new lifecycle_js_1.WorkerLifecycleManager(1);
+        m.register("w1", "POL-121", "impl");
+        m.release("w1");
+        (0, vitest_1.expect)(() => m.register("w2", "POL-122", "impl")).not.toThrow();
+    });
+});
+// ── getActiveWorkers ──────────────────────────────────────────────────────────
+(0, vitest_1.describe)("getActiveWorkers", () => {
+    (0, vitest_1.it)("returns empty array when no workers registered", () => {
+        const m = new lifecycle_js_1.WorkerLifecycleManager(1);
+        (0, vitest_1.expect)(m.getActiveWorkers()).toEqual([]);
+    });
+    (0, vitest_1.it)("returns all registered worker records", () => {
+        const m = new lifecycle_js_1.WorkerLifecycleManager(3);
+        m.register("w1", "POL-121", "impl");
+        m.register("w2", null, "finalize");
+        const workers = m.getActiveWorkers();
+        (0, vitest_1.expect)(workers).toHaveLength(2);
+        (0, vitest_1.expect)(workers.map((w) => w.worker_id).sort()).toEqual(["w1", "w2"]);
+    });
+});
+// ── hasOrphanedWorkers ────────────────────────────────────────────────────────
+(0, vitest_1.describe)("hasOrphanedWorkers", () => {
+    (0, vitest_1.it)("returns false when no workers registered", () => {
+        const m = new lifecycle_js_1.WorkerLifecycleManager(1);
+        (0, vitest_1.expect)(m.hasOrphanedWorkers()).toBe(false);
+    });
+    (0, vitest_1.it)("returns true when workers are registered", () => {
+        const m = new lifecycle_js_1.WorkerLifecycleManager(1);
+        m.register("w1", "POL-121", "impl");
+        (0, vitest_1.expect)(m.hasOrphanedWorkers()).toBe(true);
+    });
+});
+// ── forceReleaseAll ───────────────────────────────────────────────────────────
+(0, vitest_1.describe)("forceReleaseAll", () => {
+    (0, vitest_1.it)("returns empty array when nothing registered", () => {
+        const m = new lifecycle_js_1.WorkerLifecycleManager(1);
+        (0, vitest_1.expect)(m.forceReleaseAll()).toEqual([]);
+    });
+    (0, vitest_1.it)("clears all workers and returns their IDs", () => {
+        const m = new lifecycle_js_1.WorkerLifecycleManager(3);
+        m.register("w1", "POL-121", "impl");
+        m.register("w2", "POL-122", "impl");
+        const released = m.forceReleaseAll();
+        (0, vitest_1.expect)(released.sort()).toEqual(["w1", "w2"]);
+        (0, vitest_1.expect)(m.activeCount).toBe(0);
+    });
+    (0, vitest_1.it)("allows new registrations after force release", () => {
+        const m = new lifecycle_js_1.WorkerLifecycleManager(1);
+        m.register("w1", "POL-121", "impl");
+        m.forceReleaseAll();
+        (0, vitest_1.expect)(() => m.register("w2", "POL-122", "impl")).not.toThrow();
+    });
+});
+// ── One-active-worker enforcement (integration) ───────────────────────────────
+(0, vitest_1.describe)("one-active-worker policy (default)", () => {
+    (0, vitest_1.it)("enforces serial dispatch: second register fails until first is released", () => {
+        const m = new lifecycle_js_1.WorkerLifecycleManager();
+        m.register("worker-POL-121", "POL-121", "impl");
+        (0, vitest_1.expect)(() => m.register("worker-POL-122", "POL-122", "impl")).toThrow();
+        m.release("worker-POL-121");
+        // Now should succeed
+        (0, vitest_1.expect)(() => m.register("worker-POL-122", "POL-122", "impl")).not.toThrow();
+    });
+});