@eir-labs/coltrane 0.4.0

package/dist/src/server_relay.js.map

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

package/dist/src/simulate.d.ts

@@ -0,0 +1,60 @@
+import type { Depth, ModelTier } from "./pricing.js";
+/** The structural facts a simulation needs about the standard it is simulating. A projection,
+ *  not the Standard itself, so this module stays free of the composition layer. */
+export interface SimulatedStandardShape {
+    slug: string;
+    phases: readonly {
+        name: string;
+        chairs: number;
+    }[];
+}
+export interface SimulateQuery {
+    standard_slug: string;
+    mock_input: Record<string, unknown>;
+    depth: Depth;
+    model_tier?: ModelTier;
+    agent_count?: number;
+    base_cost_usd?: number;
+    base_duration_ms?: number;
+    /**
+     * #239 — the standard being simulated. Without it `standardSimulate` received only a SLUG,
+     * so it could not read the thing it was estimating: the 6-phase submission-convergence came
+     * back as three invented phases named sense/process/deliver. The caller reads it out of the
+     * genome and passes it here.
+     */
+    standard?: SimulatedStandardShape | undefined;
+    /**
+     * Settled per-run costs (USD) previously observed for this standard, from the ledger's gig
+     * rows (#195). When present these ARE the estimate — a measured mean beats any formula.
+     */
+    observed_costs_usd?: readonly number[] | undefined;
+}
+export interface SimulatedPhase {
+    name: string;
+    /** How many chairs this phase dispatches. 0 when the standard could not be read. */
+    chairs: number;
+    estimated_cost: number;
+    estimated_duration_ms: number;
+}
+/**
+ * Where the number came from. The pre-spend check CLAUDE.md tells operators to run before
+ * dispatching has to say which of these it is, or a guess reads like a reading:
+ *   observed   — mean of real settled runs of this standard, depth-adjusted
+ *   structural — derived from this standard's real phases + chair count
+ *   fallback   — no standard resolvable; a per-slug default, i.e. a guess
+ */
+export type SimulationBasis = "observed" | "structural" | "fallback";
+export interface SimulationResult {
+    phases: readonly SimulatedPhase[];
+    estimated_cost: number;
+    estimated_duration_ms: number;
+    basis: SimulationBasis;
+    /** How many real runs the `observed` estimate averaged. 0 for the other bases. */
+    sample_size: number;
+}
+/** Structural per-chair cost, USD, at depth=standard/tier=standard. A documented constant,
+ *  not a measurement — which is why a structural estimate is labelled `structural`. */
+export declare const PER_CHAIR_BASE_COST_USD = 0.6;
+/** Structural per-chair wall clock, ms, at depth=standard. Same caveat. */
+export declare const PER_CHAIR_BASE_DURATION_MS = 30000;
+export declare function standardSimulate(q: SimulateQuery): SimulationResult;

package/dist/src/simulate.js

@@ -0,0 +1,72 @@
+import { DEPTH_MULTIPLIER, MODEL_MULTIPLIER } from "./pricing.js";
+// Retained ONLY as the no-standard fallback (see SimulationBasis.fallback). These are the
+// original hardcoded lookups; they are no longer the primary path, and a result computed from
+// them is labelled `fallback` so no caller mistakes one for a reading of their pipeline.
+const KNOWN_BASE_COST = {
+    "readiness-scan": 0.95,
+    "bug-fix": 1.0,
+    "feature-build": 12.0,
+};
+const KNOWN_PHASES = {
+    "readiness-scan": ["sense", "interpret", "report"],
+};
+/** Structural per-chair cost, USD, at depth=standard/tier=standard. A documented constant,
+ *  not a measurement — which is why a structural estimate is labelled `structural`. */
+export const PER_CHAIR_BASE_COST_USD = 0.6;
+/** Structural per-chair wall clock, ms, at depth=standard. Same caveat. */
+export const PER_CHAIR_BASE_DURATION_MS = 30_000;
+export function standardSimulate(q) {
+    const tier = q.model_tier ?? "standard";
+    const depthMult = DEPTH_MULTIPLIER[q.depth];
+    const tierMult = MODEL_MULTIPLIER[tier];
+    // Phase shape: the standard's own phases when we can read it, the per-slug fallback otherwise.
+    const phaseShapes = q.standard
+        ? q.standard.phases.map((p) => ({ name: p.name, chairs: p.chairs }))
+        : (KNOWN_PHASES[q.standard_slug] ?? ["sense", "process", "deliver"]).map((name) => ({ name, chairs: 0 }));
+    const chairTotal = phaseShapes.reduce((s, p) => s + p.chairs, 0);
+    // Cost. Observed history wins; then the standard's real size; then the per-slug default.
+    const observed = (q.observed_costs_usd ?? []).filter((n) => Number.isFinite(n) && n > 0);
+    let basis;
+    let baseCost;
+    if (q.base_cost_usd !== undefined) {
+        // An explicit caller-supplied base is honoured, and honestly labelled by what it describes.
+        basis = q.standard ? "structural" : "fallback";
+        baseCost = q.base_cost_usd;
+    }
+    else if (observed.length > 0) {
+        basis = "observed";
+        // Observed runs are already depth-and-tier-inclusive of whatever depth they RAN at; we have
+        // no per-run depth on the ledger, so normalise to depth=standard and let the multipliers
+        // re-apply. Honest about being an approximation — it is still a measurement of this pipeline.
+        baseCost = observed.reduce((s, n) => s + n, 0) / observed.length;
+    }
+    else if (q.standard) {
+        basis = "structural";
+        baseCost = Math.max(chairTotal, 1) * PER_CHAIR_BASE_COST_USD;
+    }
+    else {
+        basis = "fallback";
+        baseCost = KNOWN_BASE_COST[q.standard_slug] ?? 1.0;
+    }
+    const baseDuration = q.base_duration_ms
+        ?? (q.standard ? Math.max(phaseShapes.length, 1) * PER_CHAIR_BASE_DURATION_MS : 30_000);
+    const totalCost = baseCost * depthMult * tierMult;
+    const totalDuration = baseDuration * depthMult;
+    const n = Math.max(phaseShapes.length, 1);
+    // Spread cost by chair count when we know it (a 3-chair phase costs more than a 1-chair one);
+    // evenly when we don't.
+    const phases = phaseShapes.map((p) => ({
+        name: p.name,
+        chairs: p.chairs,
+        estimated_cost: chairTotal > 0 ? (totalCost * p.chairs) / chairTotal : totalCost / n,
+        estimated_duration_ms: totalDuration / n,
+    }));
+    return {
+        phases,
+        estimated_cost: totalCost,
+        estimated_duration_ms: totalDuration,
+        basis,
+        sample_size: basis === "observed" ? observed.length : 0,
+    };
+}
+//# sourceMappingURL=simulate.js.map

package/dist/src/simulate.js.map

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

package/dist/src/skill_runner.mjs

@@ -0,0 +1,34 @@
+// Skill runner — the child harness executed under Node's --permission sandbox.
+//
+// The parent (skill_subprocess.ts) spawns:
+//   node --permission --allow-fs-read=* [tier flags] skill_runner.mjs <skill-dir>
+// and pipes the input as JSON on stdin. This harness imports the skill's execution
+// half, calls run(input), and writes {ok, output} (or {ok:false, error}) to stdout.
+//
+// stdin/stdout are not gated by the permission model; fs/child/net are — so a tier-0
+// skill can read its own code + inputs but cannot write, spawn, or reach the network.
+import { argv, stdin, stdout, exit } from "node:process";
+import { pathToFileURL } from "node:url";
+import { join, isAbsolute, resolve } from "node:path";
+
+const skillDir = argv[2];
+
+async function main() {
+  let raw = "";
+  for await (const chunk of stdin) raw += chunk;
+  const input = raw.trim() ? JSON.parse(raw) : {};
+
+  const dir = isAbsolute(skillDir) ? skillDir : resolve(skillDir);
+  const mod = await import(pathToFileURL(join(dir, "skill.mjs")).href);
+  const run = mod.default ?? mod.run;
+  if (typeof run !== "function") {
+    throw new Error(`skill at ${skillDir} exports no default run() function`);
+  }
+  const output = await run(input);
+  stdout.write(JSON.stringify({ ok: true, output }));
+}
+
+main().catch((e) => {
+  stdout.write(JSON.stringify({ ok: false, error: String(e?.message ?? e) }));
+  exit(1);
+});

package/dist/src/skill_subprocess.d.ts

@@ -0,0 +1,65 @@
+export interface SkillMeta {
+    slug: string;
+    version: number;
+    skill_type?: string;
+    input_type?: string;
+    output_type?: string;
+    determinism_ratio?: number;
+    permission?: {
+        tier?: number;
+    };
+    /** Per-skill execution ceiling. Caps the caller-supplied timeout (whichever is smaller). */
+    timeout_ms?: number;
+}
+export interface SkillFixture {
+    id: string;
+    description?: string;
+    input: unknown;
+    expected_output?: unknown;
+    assertions?: {
+        path: string;
+        op: string;
+        value?: unknown;
+    }[];
+}
+export interface ExecuteResult {
+    ok: boolean;
+    output?: unknown;
+    error?: string;
+    duration_ms: number;
+}
+/**
+ * Permission tier → Node --permission flags. Tier 0 is read-only with no side effects
+ * (can load its own code + read inputs, but cannot write, spawn, or reach the network).
+ * Higher tiers add write, then child_process (needed by skills that shell out, e.g.
+ * run-vitest-band). The grant IS the enforcement — a skill can do only what its tier allows.
+ */
+export declare function tierFlags(tier: number): string[];
+export declare function readSkillMeta(skillDir: string): SkillMeta;
+export declare function loadFixtures(skillDir: string): SkillFixture[];
+/** Run a skill's execution half in a permission-scoped subprocess. `tierOverride` runs the
+ *  skill at a tier other than its declared one — used by the cage matrix to exercise one
+ *  capability probe across every tier. */
+export declare function executeSkill(skillDir: string, input: unknown, timeoutMs?: number, tierOverride?: number): ExecuteResult;
+export interface FixtureResult {
+    id: string;
+    passed: boolean;
+    stable: boolean;
+    error?: string;
+}
+export interface FixtureReport {
+    skill: string;
+    total: number;
+    passed: number;
+    pass_rate: number;
+    deterministic: boolean;
+    determinism_runs: number;
+    results: FixtureResult[];
+}
+/**
+ * Run every fixture for a skill. Each fixture is executed DETERMINISM_RUNS times: the first
+ * run is checked against expected_output + assertions (the test suite + evolution gate); all
+ * runs must produce identical output (the determinism meter). A pure skill is green +
+ * deterministic; a candidate skill.mjs that regresses a fixture fails here — the gate.
+ */
+export declare function runSkillFixtures(skillDir: string): FixtureReport;

package/dist/src/skill_subprocess.js

@@ -0,0 +1,132 @@
+// Skill execution + the fixture/determinism runner (skills as first-class, Phase 1 —
+// docs/skills-as-first-class.md). A skill package is a directory:
+//   skills/<slug>/ { meta.json, skill.mjs, fixtures/*.json }
+// The execution half runs in a Node --permission subprocess scoped by the skill's
+// permission tier (the Node analog of the old Deno --allow cage). Fixtures are the
+// load-bearing instrument: they are the skill's test suite, the determinism meter
+// (stable across repeated runs), AND the evolution gate (an improved skill.mjs is
+// accepted only if every fixture still passes).
+import { spawnSync } from "node:child_process";
+import { readFileSync, readdirSync, existsSync } from "node:fs";
+import { join, extname } from "node:path";
+import { fileURLToPath } from "node:url";
+const RUNNER = fileURLToPath(new URL("./skill_runner.mjs", import.meta.url));
+/**
+ * Permission tier → Node --permission flags. Tier 0 is read-only with no side effects
+ * (can load its own code + read inputs, but cannot write, spawn, or reach the network).
+ * Higher tiers add write, then child_process (needed by skills that shell out, e.g.
+ * run-vitest-band). The grant IS the enforcement — a skill can do only what its tier allows.
+ */
+export function tierFlags(tier) {
+    const flags = ["--permission", "--allow-fs-read=*"];
+    if (tier >= 1)
+        flags.push("--allow-fs-write=*");
+    if (tier >= 2)
+        flags.push("--allow-child-process");
+    return flags;
+}
+export function readSkillMeta(skillDir) {
+    return JSON.parse(readFileSync(join(skillDir, "meta.json"), "utf-8"));
+}
+export function loadFixtures(skillDir) {
+    const dir = join(skillDir, "fixtures");
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((f) => extname(f) === ".json")
+        .sort()
+        .map((f) => JSON.parse(readFileSync(join(dir, f), "utf-8")));
+}
+/** Run a skill's execution half in a permission-scoped subprocess. `tierOverride` runs the
+ *  skill at a tier other than its declared one — used by the cage matrix to exercise one
+ *  capability probe across every tier. */
+export function executeSkill(skillDir, input, timeoutMs = 120_000, tierOverride) {
+    const meta = readSkillMeta(skillDir);
+    const tier = tierOverride ?? (meta.permission?.tier ?? 0);
+    // the skill's own meta.timeout_ms caps the caller's timeout — a runaway code half can't
+    // outlive its declared budget. SIGKILL (not the default SIGTERM) is the kill signal so a
+    // SIGTERM-trapping child can't survive the timeout.
+    const timeout = typeof meta.timeout_ms === "number" ? Math.min(timeoutMs, meta.timeout_ms) : timeoutMs;
+    const started = Date.now();
+    const res = spawnSync("node", [...tierFlags(tier), RUNNER, skillDir], {
+        input: JSON.stringify(input),
+        encoding: "utf-8",
+        maxBuffer: 64 * 1024 * 1024,
+        timeout,
+        killSignal: "SIGKILL",
+    });
+    const duration_ms = Date.now() - started;
+    if (res.error)
+        return { ok: false, error: String(res.error.message), duration_ms };
+    try {
+        const parsed = JSON.parse(res.stdout);
+        return { ...parsed, duration_ms };
+    }
+    catch {
+        return { ok: false, error: `unparseable skill output: ${(res.stdout || res.stderr || "").slice(0, 300)}`, duration_ms };
+    }
+}
+function getPath(obj, path) {
+    return path.split(".").reduce((acc, k) => (acc != null ? acc[k] : undefined), obj);
+}
+function checkAssertion(output, a) {
+    const v = getPath(output, a.path);
+    switch (a.op) {
+        case "exists": return v !== undefined && v !== null;
+        case "is_number": return typeof v === "number";
+        case "is_string": return typeof v === "string";
+        case "is_boolean": return typeof v === "boolean";
+        case "equals": return JSON.stringify(v) === JSON.stringify(a.value);
+        default: return false;
+    }
+}
+function deepEqual(a, b) {
+    return JSON.stringify(canon(a)) === JSON.stringify(canon(b));
+}
+function canon(v) {
+    if (Array.isArray(v))
+        return v.map(canon);
+    if (v && typeof v === "object") {
+        return Object.fromEntries(Object.keys(v).sort().map((k) => [k, canon(v[k])]));
+    }
+    return v;
+}
+// How many times each fixture runs to read determinism. >=3 so a coincidentally-stable pair
+// can't pass as deterministic — a flaky skill that happens to agree twice gets caught.
+const DETERMINISM_RUNS = 3;
+/**
+ * Run every fixture for a skill. Each fixture is executed DETERMINISM_RUNS times: the first
+ * run is checked against expected_output + assertions (the test suite + evolution gate); all
+ * runs must produce identical output (the determinism meter). A pure skill is green +
+ * deterministic; a candidate skill.mjs that regresses a fixture fails here — the gate.
+ */
+export function runSkillFixtures(skillDir) {
+    const slug = readSkillMeta(skillDir).slug;
+    const fixtures = loadFixtures(skillDir);
+    const results = [];
+    let passed = 0;
+    let deterministic = true;
+    for (const fx of fixtures) {
+        const runs = Array.from({ length: DETERMINISM_RUNS }, () => executeSkill(skillDir, fx.input));
+        const r1 = runs[0];
+        const stable = runs.every((r) => r.ok) && runs.every((r) => deepEqual(r.output, r1.output));
+        const matchesExpected = fx.expected_output === undefined || deepEqual(r1.output, fx.expected_output);
+        const assertionsHold = (fx.assertions ?? []).every((a) => checkAssertion(r1.output, a));
+        const ok = r1.ok && matchesExpected && assertionsHold;
+        if (ok)
+            passed++;
+        if (!stable)
+            deterministic = false;
+        results.push({ id: fx.id, passed: ok, stable, ...(r1.ok ? {} : { error: r1.error }) });
+    }
+    return {
+        skill: slug,
+        total: fixtures.length,
+        passed,
+        pass_rate: fixtures.length ? passed / fixtures.length : 0,
+        deterministic,
+        determinism_runs: DETERMINISM_RUNS,
+        results,
+    };
+}
+//# sourceMappingURL=skill_subprocess.js.map

package/dist/src/skill_subprocess.js.map

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

package/dist/src/skills.d.ts

@@ -0,0 +1,85 @@
+import { type SkillMeta, type SkillFixture, type ExecuteResult } from "./skill_subprocess.js";
+export { executeSkill, runSkillFixtures, loadFixtures, readSkillMeta, tierFlags, type SkillMeta, type SkillFixture, type ExecuteResult, type FixtureReport, type FixtureResult, } from "./skill_subprocess.js";
+export declare class SkillLoadError extends Error {
+}
+export declare class SkillCompositionCycleError extends Error {
+}
+export declare const CODE_HASH_ALGO = "sha256";
+export declare function hashSkillCode(codePath: string): string;
+export interface SkillPackage {
+    dir: string;
+    meta: SkillMeta & {
+        code_hash?: string;
+        composable_with?: readonly string[];
+        input_schema?: Record<string, unknown>;
+        output_schema?: Record<string, unknown>;
+    };
+    codeHash: string | null;
+    fixtures: SkillFixture[];
+    mdPath: string | null;
+}
+/** Load a skill package: meta + code (content-hashed) + fixtures + the reasoning half.
+ *  A malformed package (unreadable/sluggless meta, bad fixture shape) raises SkillLoadError;
+ *  an ABSENT code half is allowed (codeHash null) — that degrades to pure reasoning at run. */
+export declare function loadSkillPackage(dir: string): SkillPackage;
+export type FieldOrigin = "code" | "model";
+export interface ResolutionResult {
+    output: Record<string, unknown>;
+    resolved: Record<string, unknown>;
+    residual: string[];
+    field_origins: Record<string, FieldOrigin>;
+    degraded?: {
+        reason: string;
+    };
+}
+export type ResidualInvoker = (ctx: {
+    unresolved: readonly string[];
+    resolved: Record<string, unknown>;
+    md: string;
+}) => Record<string, unknown> | Promise<Record<string, unknown>>;
+/** Options for resolution + chain recording. `chainDir` isolates the durable chain so
+ *  tests (and consumers) can point it at a scratch location instead of ambient state. */
+export interface SkillChainOpts {
+    chainDir?: string;
+}
+/** Run code first, compute the residual, let the model fill only the gap, tag origins.
+ *  When `opts.chainDir` is set, append a SkillChainEvent recording this resolution. */
+export declare function resolveSkill(dir: string, input: unknown, invoke: ResidualInvoker, opts?: SkillChainOpts): Promise<ResolutionResult>;
+export interface SkillChainEvent {
+    slug: string;
+    version: number;
+    code_hash: string;
+    tier: number;
+    duration_ms: number;
+    permission_violations: string[];
+    field_origins: Record<string, FieldOrigin>;
+    degraded_reason?: string;
+}
+/** Read the recorded resolution events for a skill+version — the log determinism reads from. */
+export declare function skillChainEvents(slug: string, version?: number, opts?: SkillChainOpts): SkillChainEvent[];
+export interface DeterminismReport {
+    slug: string;
+    version: number;
+    ratio: number;
+    window: number;
+    samples: number;
+}
+export declare function computeDeterminismRatio(slug: string, version: number, opts?: SkillChainOpts & {
+    window?: number;
+}): DeterminismReport;
+export interface EvolutionVerdict {
+    accepted: boolean;
+    failing_fixtures: string[];
+}
+/** Run a candidate skill.mjs against the package's fixtures; accept iff none regress. The
+ *  fixtures are the evolution gate: an "improvement" that breaks any committed contract is
+ *  rejected, and the broken fixtures are named. */
+export declare function evolveSkill(dir: string, candidateCodePath: string): EvolutionVerdict;
+export interface CompositionResult {
+    order: string[];
+    merged_residual: string[];
+}
+/** Compose multiple skills for one chair: validate composable_with, order by deps,
+ *  detect cycles (SkillCompositionCycleError), merge the residual. */
+export declare function composeSkills(dirs: readonly string[]): CompositionResult;
+export type { ExecuteResult as _ExecuteResult };