@llblab/pi-kit 0.1.0

package/node_modules/@llblab/pi-actors/dist/lib/tool-review-transaction.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Journaled active-tool portfolio mutation.
+ * Zones: approved-plan CAS, source quarantine, target commit, crash recovery
+ * Owns deterministic filesystem mutation; reviewer policy and runtime activation remain separate domains.
+ */
+import type { ToolReviewDecision } from "./tool-review.ts";
+export interface ToolReviewApprovedSource {
+    action: ToolReviewDecision["action"];
+    name: string;
+    path: string;
+    sha256: string;
+}
+export interface ToolReviewApprovedTarget {
+    expectedSha256: string | null;
+    lineage: "demote" | "evolve" | "merge" | "replace" | "split";
+    name: string;
+    path: string;
+    recipe: Record<string, unknown>;
+    sources: string[];
+}
+export interface ToolReviewApprovedPlan {
+    createdAt: string;
+    decisions: ToolReviewDecision[];
+    reviewId: string;
+    sources: ToolReviewApprovedSource[];
+    targets: ToolReviewApprovedTarget[];
+}
+export type ToolReviewTransactionPhase = "committed" | "prepared" | "rollback_required" | "rolled_back" | "sources_quarantined" | "targets_written";
+export interface ToolReviewTransactionResult {
+    evidencePath?: string;
+    journalPath: string;
+    phase: ToolReviewTransactionPhase;
+    quarantineDir: string;
+}
+export type ToolReviewTransactionCheckpoint = "evidence_written" | "prepared" | "source_quarantined" | "sources_quarantined" | "target_written" | "targets_written";
+export interface ToolReviewTransactionOptions {
+    checkpoint?(checkpoint: ToolReviewTransactionCheckpoint): void;
+    now?(): Date;
+    recipeRoot: string;
+}
+interface PathContainmentApi {
+    isAbsolute(path: string): boolean;
+    relative(from: string, to: string): string;
+    resolve(...paths: string[]): string;
+    sep: string;
+}
+export declare function isPathContained(path: string, root: string, pathApi?: PathContainmentApi): boolean;
+export declare function applyToolReviewPlan(approvedPath: string, options: ToolReviewTransactionOptions): ToolReviewTransactionResult;
+export declare function recoverToolReviewTransaction(approvedPath: string, options: ToolReviewTransactionOptions): ToolReviewTransactionResult;
+export {};

package/node_modules/@llblab/pi-actors/dist/lib/tool-review-transaction.js

@@ -0,0 +1,362 @@
+/**
+ * Journaled active-tool portfolio mutation.
+ * Zones: approved-plan CAS, source quarantine, target commit, crash recovery
+ * Owns deterministic filesystem mutation; reviewer policy and runtime activation remain separate domains.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep, } from "node:path";
+import { withFileMutationLock, writeJsonAtomic } from "./file-state.js";
+import * as RecipesReferences from "./recipes-references.js";
+function sha256Bytes(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function sha256File(path) {
+    return sha256Bytes(readFileSync(path));
+}
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (!value || typeof value !== "object")
+        return JSON.stringify(value);
+    const record = value;
+    return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(",")}}`;
+}
+export function isPathContained(path, root, pathApi = { isAbsolute, relative, resolve, sep }) {
+    const relation = pathApi.relative(pathApi.resolve(root), pathApi.resolve(path));
+    return Boolean(relation &&
+        relation !== ".." &&
+        !relation.startsWith(`..${pathApi.sep}`) &&
+        !pathApi.isAbsolute(relation));
+}
+function assertNoSymlinkComponents(path, root) {
+    const absoluteRoot = resolve(root);
+    if (!existsSync(absoluteRoot) || lstatSync(absoluteRoot).isSymbolicLink()) {
+        throw new Error(`Invalid tool review transaction root: ${absoluteRoot}`);
+    }
+    if (!isPathContained(path, absoluteRoot)) {
+        throw new Error(`Tool review path escapes transaction root: ${path}`);
+    }
+    let current = absoluteRoot;
+    for (const segment of relative(absoluteRoot, resolve(path)).split(/[\\/]/u)) {
+        current = join(current, segment);
+        if (!existsSync(current))
+            break;
+        if (lstatSync(current).isSymbolicLink()) {
+            throw new Error(`Symlink is not allowed in tool review transaction: ${current}`);
+        }
+    }
+}
+function captureRootIdentity(path) {
+    const absolute = resolve(path);
+    const lexical = lstatSync(absolute);
+    if (!lexical.isDirectory() || lexical.isSymbolicLink()) {
+        throw new Error(`Invalid tool review transaction root: ${absolute}`);
+    }
+    const canonical = realpathSync.native(absolute);
+    const stat = statSync(canonical, { bigint: true });
+    return {
+        dev: String(stat.dev),
+        ino: String(stat.ino),
+        path: absolute,
+        realpath: canonical,
+    };
+}
+function captureRootIdentities(cycleDir, quarantineDir, recipeRoot) {
+    return {
+        cycleDir: captureRootIdentity(cycleDir),
+        quarantineDir: captureRootIdentity(quarantineDir),
+        recipeRoot: captureRootIdentity(recipeRoot),
+    };
+}
+function verifyRootIdentities(roots, cycleDir, quarantineDir, recipeRoot) {
+    const current = captureRootIdentities(cycleDir, quarantineDir, recipeRoot);
+    for (const key of ["cycleDir", "quarantineDir", "recipeRoot"]) {
+        const expected = roots?.[key];
+        if (!expected ||
+            expected.path !== current[key].path ||
+            expected.realpath !== current[key].realpath ||
+            expected.dev !== current[key].dev ||
+            expected.ino !== current[key].ino) {
+            throw new Error(`Tool review transaction root changed: ${key}`);
+        }
+    }
+}
+function deriveOperations(plan, quarantineDir) {
+    const sources = changedSources(plan).map((source, index) => ({
+        original: resolve(source.path),
+        quarantine: join(quarantineDir, `${index}-${basename(source.path)}`),
+        sha256: source.sha256,
+    }));
+    const targets = plan.targets.map((target) => ({
+        path: resolve(target.path),
+        sha256: sha256Bytes(`${JSON.stringify(target.recipe, null, 2)}\n`),
+    }));
+    return { sources, targets };
+}
+function assertPlan(plan, recipeRoot) {
+    if (!/^[a-f0-9-]{36}$/u.test(plan.reviewId) ||
+        plan.sources.length !== 36 ||
+        plan.decisions.length !== 36) {
+        throw new Error("Invalid approved tool review plan identity.");
+    }
+    const sourcePaths = new Set();
+    for (const source of plan.sources) {
+        if (!isPathContained(source.path, recipeRoot) || sourcePaths.has(resolve(source.path))) {
+            throw new Error(`Invalid or duplicate tool review source: ${source.path}`);
+        }
+        sourcePaths.add(resolve(source.path));
+    }
+    const targetPaths = new Set();
+    for (const target of plan.targets) {
+        if (!isPathContained(target.path, recipeRoot) || targetPaths.has(resolve(target.path))) {
+            throw new Error(`Invalid or duplicate tool review target: ${target.path}`);
+        }
+        targetPaths.add(resolve(target.path));
+        if (!target.recipe || typeof target.recipe !== "object" || !("template" in target.recipe)) {
+            throw new Error(`Incomplete tool review target recipe: ${target.path}`);
+        }
+    }
+}
+function readPlan(path) {
+    return JSON.parse(readFileSync(path, "utf8"));
+}
+function readJournal(path, plan, cycleDir, quarantineDir, recipeRoot) {
+    const journal = JSON.parse(readFileSync(path, "utf8"));
+    const phases = [
+        "committed",
+        "prepared",
+        "rollback_required",
+        "rolled_back",
+        "sources_quarantined",
+        "targets_written",
+    ];
+    const operations = deriveOperations(plan, quarantineDir);
+    if (journal.reviewId !== plan.reviewId ||
+        journal.approvedSha256 !== sha256Bytes(canonicalJson(plan)) ||
+        !phases.includes(journal.phase) ||
+        journal.operationsSha256 !== sha256Bytes(canonicalJson(journal.operations)) ||
+        canonicalJson(journal.operations) !== canonicalJson(operations) ||
+        journal.quarantined.length > operations.sources.length ||
+        journal.writtenTargets.length > operations.targets.length ||
+        canonicalJson(journal.quarantined) !==
+            canonicalJson(operations.sources.slice(0, journal.quarantined.length)) ||
+        canonicalJson(journal.writtenTargets) !==
+            canonicalJson(operations.targets.slice(0, journal.writtenTargets.length))) {
+        throw new Error("Invalid or mismatched tool review transaction journal.");
+    }
+    verifyRootIdentities(journal.roots, cycleDir, quarantineDir, recipeRoot);
+    for (const source of operations.sources) {
+        assertNoSymlinkComponents(source.original, recipeRoot);
+        assertNoSymlinkComponents(source.quarantine, cycleDir);
+    }
+    for (const target of operations.targets) {
+        assertNoSymlinkComponents(target.path, recipeRoot);
+    }
+    return journal;
+}
+function writeJournal(path, journal) {
+    writeJsonAtomic(path, journal);
+}
+function changedSources(plan) {
+    return plan.sources.filter((source) => source.action !== "keep");
+}
+function assertCas(plan) {
+    for (const source of plan.sources) {
+        if (!existsSync(source.path) || sha256File(source.path) !== source.sha256) {
+            throw new Error(`Tool review source CAS failed: ${source.path}`);
+        }
+    }
+    for (const target of plan.targets) {
+        if (target.expectedSha256 === null) {
+            if (existsSync(target.path))
+                throw new Error(`Tool review target appeared: ${target.path}`);
+        }
+        else if (!existsSync(target.path) || sha256File(target.path) !== target.expectedSha256) {
+            throw new Error(`Tool review target CAS failed: ${target.path}`);
+        }
+    }
+}
+function rollback(journalPath, journal, now) {
+    for (const target of [...journal.writtenTargets].reverse()) {
+        if (!existsSync(target.path))
+            continue;
+        if (sha256File(target.path) !== target.sha256) {
+            const failed = { ...journal, phase: "rollback_required", updatedAt: now.toISOString() };
+            writeJournal(journalPath, failed);
+            return failed;
+        }
+        rmSync(target.path);
+    }
+    for (const source of [...journal.quarantined].reverse()) {
+        const originalExists = existsSync(source.original);
+        const quarantineExists = existsSync(source.quarantine);
+        if (originalExists &&
+            !quarantineExists &&
+            sha256File(source.original) === source.sha256)
+            continue;
+        if (originalExists ||
+            !quarantineExists ||
+            sha256File(source.quarantine) !== source.sha256) {
+            const failed = { ...journal, phase: "rollback_required", updatedAt: now.toISOString() };
+            writeJournal(journalPath, failed);
+            return failed;
+        }
+        mkdirSync(dirname(source.original), { recursive: true });
+        renameSync(source.quarantine, source.original);
+    }
+    const rolledBack = {
+        ...journal,
+        phase: "rolled_back",
+        updatedAt: now.toISOString(),
+        writtenTargets: [],
+    };
+    writeJournal(journalPath, rolledBack);
+    return rolledBack;
+}
+function commitEvidence(cycleDir, journalPath, journal, plan, now, checkpoint) {
+    verifyRootIdentities(journal.roots, cycleDir, join(cycleDir, "quarantine"), journal.roots.recipeRoot.path);
+    if (journal.writtenTargets.length !== journal.operations.targets.length) {
+        throw new Error("Committed tool review targets are incomplete.");
+    }
+    for (const target of journal.writtenTargets) {
+        if (!existsSync(target.path) || sha256File(target.path) !== target.sha256) {
+            throw new Error(`Committed tool review target changed: ${target.path}`);
+        }
+    }
+    if (journal.quarantined.length !== journal.operations.sources.length) {
+        throw new Error("Committed tool review quarantine is incomplete.");
+    }
+    for (const source of journal.quarantined) {
+        const replacement = journal.operations.targets.find((target) => resolve(target.path) === resolve(source.original));
+        if (existsSync(source.original) &&
+            (!replacement || sha256File(source.original) !== replacement.sha256)) {
+            throw new Error(`Committed tool review source changed: ${source.original}`);
+        }
+        if (!existsSync(source.quarantine) ||
+            sha256File(source.quarantine) !== source.sha256) {
+            throw new Error(`Committed tool review quarantine changed: ${source.quarantine}`);
+        }
+    }
+    const evidencePath = join(cycleDir, "evidence.json");
+    writeJsonAtomic(evidencePath, {
+        actions: Object.fromEntries([...new Set(plan.sources.map((source) => source.action))].map((action) => [
+            action,
+            plan.sources.filter((source) => source.action === action).length,
+        ])),
+        reviewId: plan.reviewId,
+        sources: plan.sources.length,
+        targets: plan.targets.length,
+        ts: now.toISOString(),
+    });
+    checkpoint?.("evidence_written");
+    const committed = { ...journal, phase: "committed", updatedAt: now.toISOString() };
+    writeJournal(journalPath, committed);
+    return {
+        evidencePath,
+        journalPath,
+        phase: "committed",
+        quarantineDir: join(cycleDir, "quarantine"),
+    };
+}
+export function applyToolReviewPlan(approvedPath, options) {
+    const plan = readPlan(approvedPath);
+    assertPlan(plan, options.recipeRoot);
+    const cycleDir = dirname(approvedPath);
+    const journalPath = join(cycleDir, "journal.json");
+    const quarantineDir = join(cycleDir, "quarantine");
+    const now = options.now ?? (() => new Date());
+    return withFileMutationLock(options.recipeRoot, () => {
+        if (existsSync(journalPath)) {
+            throw new Error(`Tool review transaction already exists: ${plan.reviewId}`);
+        }
+        mkdirSync(quarantineDir, { recursive: true });
+        const operations = deriveOperations(plan, quarantineDir);
+        const roots = captureRootIdentities(cycleDir, quarantineDir, options.recipeRoot);
+        for (const source of operations.sources) {
+            assertNoSymlinkComponents(source.original, options.recipeRoot);
+            assertNoSymlinkComponents(source.quarantine, cycleDir);
+        }
+        for (const target of operations.targets) {
+            assertNoSymlinkComponents(target.path, options.recipeRoot);
+        }
+        assertCas(plan);
+        let journal = {
+            approvedSha256: sha256Bytes(canonicalJson(plan)),
+            operations,
+            operationsSha256: sha256Bytes(canonicalJson(operations)),
+            phase: "prepared",
+            quarantined: [],
+            reviewId: plan.reviewId,
+            roots,
+            updatedAt: now().toISOString(),
+            writtenTargets: [],
+        };
+        writeJournal(journalPath, journal);
+        options.checkpoint?.("prepared");
+        try {
+            for (const source of operations.sources) {
+                journal = {
+                    ...journal,
+                    quarantined: [...journal.quarantined, source],
+                    updatedAt: now().toISOString(),
+                };
+                writeJournal(journalPath, journal);
+                renameSync(source.original, source.quarantine);
+                options.checkpoint?.("source_quarantined");
+            }
+            journal = { ...journal, phase: "sources_quarantined", updatedAt: now().toISOString() };
+            writeJournal(journalPath, journal);
+            options.checkpoint?.("sources_quarantined");
+            for (const [index, target] of plan.targets.entries()) {
+                const operation = operations.targets[index];
+                mkdirSync(dirname(operation.path), { recursive: true });
+                journal = {
+                    ...journal,
+                    writtenTargets: [...journal.writtenTargets, operation],
+                    updatedAt: now().toISOString(),
+                };
+                writeJournal(journalPath, journal);
+                writeJsonAtomic(operation.path, target.recipe);
+                if (sha256File(operation.path) !== operation.sha256 ||
+                    !RecipesReferences.readResolvedRecipeConfig(operation.path)) {
+                    throw new Error(`Written tool review target is invalid: ${operation.path}`);
+                }
+                options.checkpoint?.("target_written");
+            }
+            journal = { ...journal, phase: "targets_written", updatedAt: now().toISOString() };
+            writeJournal(journalPath, journal);
+            options.checkpoint?.("targets_written");
+            return commitEvidence(cycleDir, journalPath, journal, plan, now(), options.checkpoint);
+        }
+        catch (error) {
+            const result = rollback(journalPath, journal, now());
+            if (result.phase === "rollback_required") {
+                throw new Error(`Tool review rollback requires operator attention: ${plan.reviewId}`);
+            }
+            throw error;
+        }
+    });
+}
+export function recoverToolReviewTransaction(approvedPath, options) {
+    const plan = readPlan(approvedPath);
+    assertPlan(plan, options.recipeRoot);
+    const cycleDir = dirname(approvedPath);
+    const journalPath = join(cycleDir, "journal.json");
+    const quarantineDir = join(cycleDir, "quarantine");
+    const now = options.now ?? (() => new Date());
+    return withFileMutationLock(options.recipeRoot, () => {
+        const journal = readJournal(journalPath, plan, cycleDir, quarantineDir, options.recipeRoot);
+        if (journal.phase === "committed") {
+            return commitEvidence(cycleDir, journalPath, journal, plan, now());
+        }
+        if (journal.phase === "targets_written") {
+            return commitEvidence(cycleDir, journalPath, journal, plan, now());
+        }
+        if (journal.phase === "rollback_required") {
+            return { journalPath, phase: journal.phase, quarantineDir };
+        }
+        const recovered = rollback(journalPath, journal, now());
+        return { journalPath, phase: recovered.phase, quarantineDir };
+    });
+}

package/node_modules/@llblab/pi-actors/dist/lib/tool-review.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Automatic active-tool portfolio review contract.
+ * Zones: thirty-six-tool reviewer input, evolution decisions, mechanical contract gates
+ * Owns strict read-only keep/evolve/replace/demote/merge/split review semantics.
+ */
+export declare const TOOL_REVIEW_THRESHOLD = 36;
+export interface ToolReviewAssessment {
+    adaptability: number;
+    futureUsefulness: number;
+    lifetimeCalls: number;
+    redundancy: number;
+    revisionCalls: number;
+    safety: string;
+}
+export interface ToolReviewTool {
+    name: string;
+    path: string;
+    recipe: Record<string, unknown>;
+    riskLabels: string[];
+    sha256: string;
+    usage?: Record<string, unknown>;
+    valid: boolean;
+}
+export interface ToolReviewInput {
+    createdAt: string;
+    reviewId: string;
+    tools: ToolReviewTool[];
+}
+export interface ToolReviewOutputRecipe {
+    name: string;
+    recipe: Record<string, unknown>;
+}
+export type ToolReviewAction = "demote" | "evolve" | "keep" | "merge" | "replace" | "split";
+export interface ToolReviewDecision {
+    action: ToolReviewAction;
+    assessment: ToolReviewAssessment;
+    rationale: string;
+    recipe?: Record<string, unknown>;
+    sha256: string;
+    source: string;
+    target?: string;
+    outputs?: ToolReviewOutputRecipe[];
+}
+export interface ToolReviewResult {
+    createdAt: string;
+    decisions: ToolReviewDecision[];
+    reviewId: string;
+}
+export interface ToolReviewValidation {
+    errors: string[];
+    ok: boolean;
+}
+export declare function validateToolReviewInput(input: ToolReviewInput): ToolReviewValidation;
+export declare function validateToolReviewResult(input: ToolReviewInput, result: ToolReviewResult): ToolReviewValidation;
+export declare function parseToolReviewResult(stdout: string): ToolReviewResult;
+export declare function createToolReviewPrompt(inputPath: string): string;

package/node_modules/@llblab/pi-actors/dist/lib/tool-review.js

@@ -0,0 +1,197 @@
+/**
+ * Automatic active-tool portfolio review contract.
+ * Zones: thirty-six-tool reviewer input, evolution decisions, mechanical contract gates
+ * Owns strict read-only keep/evolve/replace/demote/merge/split review semantics.
+ */
+export const TOOL_REVIEW_THRESHOLD = 36;
+const UUID_PATTERN = /^[a-f0-9-]{36}$/u;
+const TOOL_NAME_PATTERN = /^[a-z][a-z0-9_]*$/u;
+function isRecord(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (!isRecord(value))
+        return JSON.stringify(value);
+    return `{${Object.keys(value)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`)
+        .join(",")}}`;
+}
+function finiteScore(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1;
+}
+function calls(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0
+        ? value
+        : 0;
+}
+function validateAssessment(assessment, tool, errors) {
+    if (!isRecord(assessment) ||
+        !finiteScore(assessment.adaptability) ||
+        !finiteScore(assessment.futureUsefulness) ||
+        !finiteScore(assessment.redundancy) ||
+        typeof assessment.safety !== "string" ||
+        !assessment.safety.trim() ||
+        !Number.isInteger(assessment.lifetimeCalls) ||
+        Number(assessment.lifetimeCalls) < 0 ||
+        !Number.isInteger(assessment.revisionCalls) ||
+        Number(assessment.revisionCalls) < 0) {
+        errors.push(`invalid tool assessment: ${tool.name}`);
+        return;
+    }
+    if (assessment.lifetimeCalls !== calls(tool.usage?.lifetime_calls ?? tool.usage?.calls)) {
+        errors.push(`tool lifetime calls differ from lineage: ${tool.name}`);
+    }
+    if (assessment.revisionCalls !== calls(tool.usage?.revision_calls)) {
+        errors.push(`tool revision calls differ from lineage: ${tool.name}`);
+    }
+}
+export function validateToolReviewInput(input) {
+    const errors = [];
+    if (!UUID_PATTERN.test(input.reviewId))
+        errors.push("tool reviewId must be a UUID");
+    if (!input.createdAt || Number.isNaN(Date.parse(input.createdAt))) {
+        errors.push("tool review createdAt must be an ISO timestamp");
+    }
+    if (!Array.isArray(input.tools) || input.tools.length !== TOOL_REVIEW_THRESHOLD) {
+        errors.push(`tool review input must contain exactly ${TOOL_REVIEW_THRESHOLD} tools`);
+    }
+    const names = new Set();
+    for (const tool of input.tools ?? []) {
+        if (!tool ||
+            !TOOL_NAME_PATTERN.test(tool.name) ||
+            typeof tool.path !== "string" ||
+            typeof tool.sha256 !== "string" ||
+            typeof tool.valid !== "boolean" ||
+            !isRecord(tool.recipe) ||
+            !Array.isArray(tool.riskLabels) ||
+            names.has(tool.name)) {
+            errors.push(`invalid or duplicate reviewed tool: ${String(tool?.name)}`);
+            continue;
+        }
+        names.add(tool.name);
+    }
+    return { errors, ok: errors.length === 0 };
+}
+export function validateToolReviewResult(input, result) {
+    const errors = [...validateToolReviewInput(input).errors];
+    if (result.reviewId !== input.reviewId)
+        errors.push("tool review identity mismatch");
+    if (!result.createdAt || Number.isNaN(Date.parse(result.createdAt))) {
+        errors.push("tool review result createdAt must be an ISO timestamp");
+    }
+    if (!Array.isArray(result.decisions)) {
+        errors.push("tool review decisions must be an array");
+        return { errors, ok: false };
+    }
+    const inventory = new Map(input.tools.map((tool) => [tool.name, tool]));
+    const activeNames = new Set(inventory.keys());
+    const seen = new Set();
+    const outputNames = new Set();
+    const mergeGroups = new Map();
+    for (const decision of result.decisions) {
+        const tool = inventory.get(decision.source);
+        if (!tool) {
+            errors.push(`unknown reviewed tool: ${decision.source}`);
+            continue;
+        }
+        if (seen.has(decision.source)) {
+            errors.push(`duplicate tool decision: ${decision.source}`);
+            continue;
+        }
+        seen.add(decision.source);
+        if (decision.sha256 !== tool.sha256)
+            errors.push(`reviewed tool changed: ${tool.name}`);
+        if (!decision.rationale?.trim())
+            errors.push(`missing tool rationale: ${tool.name}`);
+        validateAssessment(decision.assessment, tool, errors);
+        if (decision.action === "keep" || decision.action === "demote") {
+            if (decision.target || decision.recipe || decision.outputs) {
+                errors.push(`${decision.action} declares evolution fields: ${tool.name}`);
+            }
+            continue;
+        }
+        if (decision.action === "replace" || decision.action === "split") {
+            errors.push(`${decision.action} requires explicit operator-authored recipe mutation: ${tool.name}`);
+            continue;
+        }
+        if (decision.action === "evolve") {
+            if (!decision.target || !TOOL_NAME_PATTERN.test(decision.target)) {
+                errors.push(`evolve requires snake_case target: ${tool.name}`);
+            }
+            if (decision.recipe !== undefined || decision.outputs !== undefined) {
+                errors.push(`evolve must not supply executable recipe content: ${tool.name}`);
+            }
+            if (decision.target &&
+                activeNames.has(decision.target) &&
+                decision.target !== tool.name) {
+                errors.push(`evolve target collides with active tool: ${decision.target}`);
+            }
+            if (decision.target && outputNames.has(decision.target)) {
+                errors.push(`duplicate evolved target: ${decision.target}`);
+            }
+            else if (decision.target)
+                outputNames.add(decision.target);
+            continue;
+        }
+        if (decision.action === "merge") {
+            if (!decision.target || !TOOL_NAME_PATTERN.test(decision.target)) {
+                errors.push(`merge requires snake_case target: ${tool.name}`);
+                continue;
+            }
+            if (decision.recipe !== undefined || decision.outputs !== undefined) {
+                errors.push(`merge must not supply executable recipe content: ${tool.name}`);
+            }
+            const group = mergeGroups.get(decision.target) ?? [];
+            group.push({ decision, recipe: canonicalJson(tool.recipe) });
+            mergeGroups.set(decision.target, group);
+            continue;
+        }
+        errors.push(`invalid tool review action: ${tool.name}`);
+    }
+    for (const tool of input.tools) {
+        if (!seen.has(tool.name))
+            errors.push(`missing tool decision: ${tool.name}`);
+    }
+    for (const [target, group] of mergeGroups) {
+        if (group.length < 2)
+            errors.push(`merge target requires at least two sources: ${target}`);
+        if (activeNames.has(target) &&
+            !group.some((entry) => entry.decision.source === target)) {
+            errors.push(`merge target collides with unrelated active tool: ${target}`);
+        }
+        if (new Set(group.map((entry) => entry.recipe)).size !== 1) {
+            errors.push(`merge target recipes differ: ${target}`);
+        }
+        if (outputNames.has(target))
+            errors.push(`duplicate evolved target: ${target}`);
+        outputNames.add(target);
+    }
+    return { errors, ok: errors.length === 0 };
+}
+export function parseToolReviewResult(stdout) {
+    const marker = "TOOL_REVIEW_RESULT";
+    const markerIndex = stdout.lastIndexOf(marker);
+    if (markerIndex < 0)
+        throw new Error("Tool reviewer output marker is missing.");
+    const payload = stdout.slice(markerIndex + marker.length).trim();
+    if (!payload.startsWith("{") || !payload.endsWith("}")) {
+        throw new Error("Tool reviewer output must end with one JSON object.");
+    }
+    const value = JSON.parse(payload);
+    if (!isRecord(value))
+        throw new Error("Tool reviewer result must be an object.");
+    return value;
+}
+export function createToolReviewPrompt(inputPath) {
+    return [
+        `Review the attached immutable active-tool portfolio from ${inputPath}.`,
+        "Evaluate all 36 tools independently from lifetime/revision usage, adaptability, redundancy, safety, contract quality, and likely future usefulness.",
+        "Choose exactly one action per source: keep, evolve, demote, or merge. There is no quota for any action.",
+        "evolve may only rename one unchanged captured recipe; demote moves the unchanged recipe to draft memory; merge may only deduplicate at least two canonically identical captured recipes. Never return recipe or outputs fields. replace and split require explicit operator-authored mutation and are unavailable to automatic review.",
+        "Do not mutate, register, move, or delete recipes. You are a read-only selector; the deterministic executor derives exact recipe bytes from captured sources and owns every portfolio mutation.",
+        "End stdout with TOOL_REVIEW_RESULT on its own line followed by exactly one JSON object with reviewId, createdAt, and decisions.",
+    ].join("\n");
+}

package/node_modules/@llblab/pi-actors/dist/lib/tools-access.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Public tool access and ownership checks
+ * Zones: session ownership, run visibility guards, tool authorization errors
+ * Owns consistent session-mismatch diagnostics for public tool execution paths
+ */
+export interface SessionContext {
+    sessionManager?: {
+        getSessionId?: () => string;
+    };
+}
+export declare function getContextSessionId(ctx: unknown): string | undefined;
+export declare function requireContextSessionId(ctx: unknown, actor: string): string;
+export declare function sessionMismatchError(input: {
+    currentSession?: string;
+    expectedSession?: string;
+    run?: string;
+    target?: string;
+}): Error;
+export declare function assertRunAccessibleToContext(runId: string, ctx: unknown): Record<string, unknown>;