@lsctech/polaris 0.1.0

package/dist/runtime/continuation/dry-run.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeDryRun = executeDryRun;
+const node_crypto_1 = require("node:crypto");
+const state_js_1 = require("../state.js");
+const fingerprint_js_1 = require("../verification/fingerprint.js");
+const child_selector_js_1 = require("../scheduling/child-selector.js");
+const logger_js_1 = require("../audit/logger.js");
+async function executeDryRun(request) {
+    const state = await (0, state_js_1.loadState)(request.artifact_dir);
+    if (state === null) {
+        return {
+            ok: false,
+            rejection: {
+                reason: "run_not_found",
+                detail: `No state found in .taskchain_artifacts/${request.artifact_dir}`,
+            },
+        };
+    }
+    if (state.status !== "running") {
+        return {
+            ok: false,
+            rejection: { reason: "run_not_continuable", expected: "running", actual: state.status },
+        };
+    }
+    const activeChild = state.active_child ?? "";
+    if (activeChild !== "") {
+        return {
+            ok: false,
+            rejection: { reason: "concurrent_execution", detail: `active_child is set: ${activeChild}` },
+        };
+    }
+    if (state.step_cursor !== request.expected_step_cursor) {
+        return {
+            ok: false,
+            rejection: {
+                reason: "step_cursor_mismatch",
+                expected: request.expected_step_cursor,
+                actual: state.step_cursor ?? undefined,
+            },
+        };
+    }
+    const nextChild = (0, child_selector_js_1.selectNextChild)(state);
+    if (nextChild === null) {
+        return { ok: false, rejection: { reason: "no_open_children" } };
+    }
+    // Nonce ties this fingerprint to a single approval issuance — prevents replay
+    const nonce = (0, node_crypto_1.randomUUID)();
+    const fingerprint = (0, fingerprint_js_1.computeStateFingerprint)({ state, approvalNonce: nonce });
+    await (0, logger_js_1.appendAuditEvent)(request.artifact_dir, {
+        event_type: "dry_run_executed",
+        run_id: state.run_id,
+        step_cursor: state.step_cursor ?? "",
+        operator: "mcp",
+        operation: "loop_continue_dry_run",
+        child_id: nextChild,
+        result: "preview",
+    });
+    return {
+        ok: true,
+        preview: {
+            next_child: nextChild,
+            fingerprint,
+            approval_template: {
+                run_id: state.run_id,
+                expected_step_cursor: state.step_cursor ?? "",
+                fingerprint,
+                runtime_generation: state.runtime_generation ?? 0,
+                nonce,
+                requested_action: "loop_continue",
+            },
+        },
+    };
+}

package/dist/runtime/execution-window.js

@@ -0,0 +1,106 @@
+"use strict";
+/**
+ * execution-window.ts — Execution window support for Alice/Delegator
+ *
+ * Alice/Delegator compatibility principles:
+ *
+ * 1. Approval tokens must be provider-agnostic (no Alice-specific fields).
+ *    ExecutionWindow carries only generic orchestration fields; Alice is one
+ *    possible issuer, not the assumed issuer.
+ *
+ * 2. Dry-run contract must remain stable — Alice implements against it without
+ *    version coupling. The shape of ExecutionWindow and WindowValidationResult
+ *    must not change in a breaking way without a schema_version bump in the
+ *    broader protocol.
+ *
+ * 3. Fingerprint must be deterministic — Alice can re-run the dry-run for the
+ *    same state and obtain the same fingerprint. This is guaranteed by
+ *    computeStateFingerprint in src/runtime/verification/fingerprint.ts.
+ *
+ * 4. Confirmations must be idempotent at protocol level — validateWindow is
+ *    pure and side-effect-free; calling it multiple times for the same inputs
+ *    yields the same result. Callers are responsible for persisting
+ *    decremented windows exactly once.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateWindow = validateWindow;
+exports.decrementWindow = decrementWindow;
+/**
+ * Validates an ExecutionWindow against the current runtime state and
+ * fingerprint. All checks must pass for the result to be `{ ok: true }`.
+ *
+ * Checks performed (in order):
+ *   1. run_id_mismatch           — window.run_id must equal state.run_id
+ *   2. window_not_yet_valid      — valid_from must be in the past or now
+ *   3. window_expired            — valid_until must be strictly in the future
+ *   4. window_exhausted          — max_continuations must be > 0
+ *   5. state_fingerprint_drifted — currentFingerprint must exactly match
+ *                                  window.state_fingerprint_at_issue
+ *
+ * Note: allowed_child_types is validated against the proposed continuation's
+ *       child type once that information is threaded through to this call site.
+ *       The field is intentionally included in ExecutionWindow now so that the
+ *       protocol shape is stable when that check is wired in.  Until then, a
+ *       non-empty allowed_child_types list is accepted without failing — see
+ *       the inline comment near the check location.
+ */
+function validateWindow(state, window, currentFingerprint) {
+    // 1. run_id must match
+    if (window.run_id !== state.run_id) {
+        return {
+            ok: false,
+            reason: "run_id_mismatch",
+            detail: `window.run_id=${window.run_id} state.run_id=${state.run_id}`,
+        };
+    }
+    const now = new Date();
+    // 2. Window must have started
+    if (new Date(window.valid_from) > now) {
+        return {
+            ok: false,
+            reason: "window_not_yet_valid",
+            detail: `valid_from=${window.valid_from} now=${now.toISOString()}`,
+        };
+    }
+    // 3. Window must not have expired
+    if (new Date(window.valid_until) <= now) {
+        return {
+            ok: false,
+            reason: "window_expired",
+            detail: `valid_until=${window.valid_until} now=${now.toISOString()}`,
+        };
+    }
+    // 4. Continuations remaining
+    if (window.max_continuations <= 0) {
+        return {
+            ok: false,
+            reason: "window_exhausted",
+            detail: `max_continuations=${window.max_continuations}`,
+        };
+    }
+    // 5. Fingerprint must match exactly — no tolerance
+    if (currentFingerprint !== window.state_fingerprint_at_issue) {
+        return {
+            ok: false,
+            reason: "state_fingerprint_drifted",
+            detail: `expected=${window.state_fingerprint_at_issue} got=${currentFingerprint}`,
+        };
+    }
+    // allowed_child_types check deferred — child type not yet threaded through at call site.
+    // If allowed_child_types is non-empty, we skip the check rather than fail, because the
+    // child-type information is not yet available here. This preserves protocol shape for
+    // future wiring without blocking windows that specify allowed_child_types today.
+    return { ok: true };
+}
+/**
+ * Returns a new ExecutionWindow with max_continuations decremented by 1.
+ *
+ * Does NOT mutate the input window.  The caller is responsible for persisting
+ * the returned window exactly once to ensure idempotency at the protocol level.
+ */
+function decrementWindow(window) {
+    return {
+        ...window,
+        max_continuations: window.max_continuations - 1,
+    };
+}

package/dist/runtime/scheduling/child-selector.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.selectNextChild = selectNextChild;
+/**
+ * Select the next child to execute.
+ *
+ * TODO: TEMPORARY — lexical sort of issue IDs is a placeholder only.
+ * Real scheduling must come from runtime orchestration policy (priority,
+ * dependencies, cycle assignment, etc.). Do not treat this ordering as
+ * authoritative. Replace with a SchedulingService in a future cluster.
+ */
+function selectNextChild(state) {
+    if (state.open_children.length === 0)
+        return null;
+    return [...state.open_children].sort()[0] ?? null;
+}

package/dist/runtime/state.js

@@ -0,0 +1,43 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getArtifactsDir = getArtifactsDir;
+exports.getArtifactDir = getArtifactDir;
+exports.getStateFilePath = getStateFilePath;
+exports.loadState = loadState;
+exports.writeState = writeState;
+exports.listArtifactDirs = listArtifactDirs;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = __importDefault(require("node:path"));
+function getArtifactsDir() {
+    return node_path_1.default.join(process.cwd(), ".taskchain_artifacts");
+}
+function getArtifactDir(artifactDir) {
+    return node_path_1.default.join(getArtifactsDir(), artifactDir);
+}
+function getStateFilePath(artifactDir) {
+    return node_path_1.default.join(getArtifactDir(artifactDir), "current-state.json");
+}
+async function loadState(artifactDir) {
+    try {
+        const raw = await (0, promises_1.readFile)(getStateFilePath(artifactDir), "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+async function writeState(artifactDir, state) {
+    await (0, promises_1.writeFile)(getStateFilePath(artifactDir), JSON.stringify(state, null, 2) + "\n", "utf-8");
+}
+async function listArtifactDirs() {
+    try {
+        const entries = await (0, promises_1.readdir)(getArtifactsDir(), { withFileTypes: true });
+        return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/runtime/status.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getOverallStatus = getOverallStatus;
+exports.getLoopStatus = getLoopStatus;
+exports.getCurrentState = getCurrentState;
+const state_js_1 = require("./state.js");
+async function getOverallStatus() {
+    const dirs = await (0, state_js_1.listArtifactDirs)();
+    const runs = await Promise.all(dirs.map(async (dir) => {
+        const state = await (0, state_js_1.loadState)(dir);
+        return state
+            ? {
+                artifact_dir: dir,
+                run_id: state.run_id,
+                status: state.status,
+                step_cursor: state.step_cursor,
+                cluster_id: state.cluster_id,
+                open_children_count: state.open_children.length,
+                completed_children_count: state.completed_children.length,
+            }
+            : { artifact_dir: dir, status: "unreadable" };
+    }));
+    return { runs };
+}
+async function getLoopStatus(artifactDir) {
+    const state = await (0, state_js_1.loadState)(artifactDir);
+    if (!state)
+        return null;
+    return {
+        artifact_dir: artifactDir,
+        run_id: state.run_id,
+        cluster_id: state.cluster_id,
+        status: state.status,
+        step_cursor: state.step_cursor,
+        active_child: state.active_child,
+        open_children: state.open_children,
+        completed_children: state.completed_children,
+        context_budget: state.context_budget,
+        runtime_generation: state.runtime_generation,
+        orchestration_mode: state.orchestration_mode,
+        continuation_epoch: state.continuation_epoch,
+    };
+}
+async function getCurrentState(artifactDir) {
+    return (0, state_js_1.loadState)(artifactDir);
+}

package/dist/runtime/verification/envelope.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateEnvelope = validateEnvelope;
+const fingerprint_js_1 = require("./fingerprint.js");
+const child_selector_js_1 = require("../scheduling/child-selector.js");
+function validateEnvelope(state, envelope) {
+    if (envelope.requested_action !== "loop_continue") {
+        return {
+            ok: false,
+            failure: {
+                check: "requested_action",
+                reason: "unsupported_action",
+                expected: "loop_continue",
+                actual: envelope.requested_action,
+            },
+        };
+    }
+    if (state.status !== "running") {
+        return {
+            ok: false,
+            failure: { check: "status", reason: "run_not_continuable", actual: state.status },
+        };
+    }
+    const activeChild = state.active_child ?? "";
+    if (activeChild !== "") {
+        return {
+            ok: false,
+            failure: { check: "active_child", reason: "concurrent_execution", actual: activeChild },
+        };
+    }
+    if (state.run_id !== envelope.run_id) {
+        return {
+            ok: false,
+            failure: {
+                check: "run_id",
+                reason: "run_id_mismatch",
+                expected: envelope.run_id,
+                actual: state.run_id,
+            },
+        };
+    }
+    if (state.step_cursor !== envelope.expected_step_cursor) {
+        return {
+            ok: false,
+            failure: {
+                check: "step_cursor",
+                reason: "step_cursor_mismatch",
+                expected: envelope.expected_step_cursor,
+                actual: state.step_cursor,
+            },
+        };
+    }
+    const stateGeneration = state.runtime_generation ?? 0;
+    if (stateGeneration !== envelope.runtime_generation) {
+        return {
+            ok: false,
+            failure: {
+                check: "runtime_generation",
+                reason: "runtime_generation_mismatch",
+                expected: String(envelope.runtime_generation),
+                actual: String(stateGeneration),
+            },
+        };
+    }
+    const currentFingerprint = (0, fingerprint_js_1.computeStateFingerprint)({ state, approvalNonce: envelope.nonce });
+    if (currentFingerprint !== envelope.fingerprint) {
+        return {
+            ok: false,
+            failure: { check: "fingerprint", reason: "state_mutated_since_approval" },
+        };
+    }
+    const nextChild = (0, child_selector_js_1.selectNextChild)(state);
+    if (nextChild === null) {
+        return { ok: false, failure: { check: "next_child", reason: "no_open_children" } };
+    }
+    if (new Date(envelope.expires_at) <= new Date()) {
+        return { ok: false, failure: { check: "expires_at", reason: "approval_expired" } };
+    }
+    return { ok: true, next_child: nextChild };
+}

package/dist/runtime/verification/fingerprint.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeStateFingerprint = computeStateFingerprint;
+const node_crypto_1 = require("node:crypto");
+/**
+ * Compute a replay-resistant state fingerprint.
+ *
+ * Scope includes all fields that must not change between dry-run issuance and
+ * confirmed continuation. The approval_nonce (when present) ties the fingerprint
+ * to a specific approval issuance, preventing pre-computation and replay attacks.
+ */
+function computeStateFingerprint({ state, approvalNonce }) {
+    const canonical = JSON.stringify({
+        schema_version: state.schema_version,
+        runtime_generation: state.runtime_generation ?? 0,
+        run_id: state.run_id,
+        step_cursor: state.step_cursor,
+        active_child: state.active_child ?? null,
+        status: state.status,
+        orchestration_mode: state.orchestration_mode ?? "bootstrap",
+        continuation_epoch: state.continuation_epoch ?? 0,
+        open_children: [...state.open_children].sort(),
+        approval_nonce: approvalNonce ?? null,
+    });
+    return (0, node_crypto_1.createHash)("sha256").update(canonical).digest("hex");
+}

package/dist/skill-packet/cli.test.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const index_js_1 = require("./index.js");
+vitest_1.vi.mock("../config/loader.js", () => ({
+    loadConfig: () => ({
+        skill_packet: {
+            analysis_confidence_threshold: 85,
+            auto_deep_analysis: false,
+            allow_cross_provider_delegation: false,
+        },
+    }),
+}));
+function configureForTest(program, output) {
+    program.exitOverride();
+    program.configureOutput({
+        writeOut: (value) => {
+            output.stdout += value;
+        },
+        writeErr: (value) => {
+            output.stderr += value;
+        },
+    });
+    for (const command of program.commands) {
+        configureForTest(command, output);
+    }
+}
+async function runSkillCommand(argv) {
+    const output = { stdout: "", stderr: "" };
+    let exitCode = 0;
+    const stdoutSpy = vitest_1.vi.spyOn(process.stdout, "write").mockImplementation((chunk) => {
+        output.stdout += String(chunk);
+        return true;
+    });
+    const stderrSpy = vitest_1.vi.spyOn(process.stderr, "write").mockImplementation((chunk) => {
+        output.stderr += String(chunk);
+        return true;
+    });
+    const exitSpy = vitest_1.vi.spyOn(process, "exit").mockImplementation((code) => {
+        exitCode = typeof code === "number" ? code : 0;
+        throw new Error(`process.exit(${code})`);
+    });
+    const command = (0, index_js_1.createSkillCommand)({ repoRoot: "/repo" });
+    configureForTest(command, output);
+    try {
+        await command.parseAsync(["node", "polaris-skill", ...argv], { from: "node" });
+    }
+    catch (error) {
+        if (error instanceof Error && "exitCode" in error) {
+            exitCode = Number(error.exitCode);
+        }
+        else if (error instanceof Error && error.message.startsWith("process.exit(")) {
+            // swallow process.exit mock throws
+        }
+        else {
+            throw error;
+        }
+    }
+    finally {
+        stdoutSpy.mockRestore();
+        stderrSpy.mockRestore();
+        exitSpy.mockRestore();
+    }
+    return { ...output, exitCode };
+}
+(0, vitest_1.describe)("polaris skill packet CLI", () => {
+    (0, vitest_1.it)("prints skill help when no subcommand is given", async () => {
+        const result = await runSkillCommand(["--help"]);
+        (0, vitest_1.expect)(result.stdout).toContain("skill packet");
+    });
+    vitest_1.it.each(["analyze", "run", "ingest", "promote"])("generates a valid JSON packet for %s", async (skill) => {
+        const result = await runSkillCommand(["packet", skill]);
+        const packet = JSON.parse(result.stdout);
+        (0, vitest_1.expect)(packet.skill_name).toBe(skill);
+        (0, vitest_1.expect)(typeof packet.packet_id).toBe("string");
+        (0, vitest_1.expect)(typeof packet.active_role).toBe("string");
+        (0, vitest_1.expect)(typeof packet.role_summary).toBe("string");
+        (0, vitest_1.expect)(Array.isArray(packet.authority_boundaries)).toBe(true);
+        (0, vitest_1.expect)(Array.isArray(packet.prohibited_actions)).toBe(true);
+        (0, vitest_1.expect)(Array.isArray(packet.allowed_outputs)).toBe(true);
+        (0, vitest_1.expect)(Array.isArray(packet.deliverables)).toBe(true);
+        (0, vitest_1.expect)(Array.isArray(packet.stop_conditions)).toBe(true);
+        (0, vitest_1.expect)(typeof packet.generated_at).toBe("string");
+    });
+    (0, vitest_1.it)("writes error and exits for unknown skill", async () => {
+        const result = await runSkillCommand(["packet", "unknown-skill"]);
+        (0, vitest_1.expect)(result.stderr).toContain("Unknown skill");
+        (0, vitest_1.expect)(result.stderr).toContain("analyze");
+        (0, vitest_1.expect)(result.exitCode).toBe(1);
+    });
+    (0, vitest_1.it)("analyze packet includes confidence_policy", async () => {
+        const result = await runSkillCommand(["packet", "analyze"]);
+        const packet = JSON.parse(result.stdout);
+        const policy = packet.confidence_policy;
+        (0, vitest_1.expect)(policy).toBeDefined();
+        (0, vitest_1.expect)(policy.threshold).toBe(85);
+        (0, vitest_1.expect)(policy.auto_deep_analysis).toBe(false);
+        (0, vitest_1.expect)(policy.on_below_threshold).toBe("ask_user");
+    });
+    (0, vitest_1.it)("run packet does not include confidence_policy", async () => {
+        const result = await runSkillCommand(["packet", "run"]);
+        const packet = JSON.parse(result.stdout);
+        (0, vitest_1.expect)(packet.confidence_policy).toBeUndefined();
+    });
+});