@multileaf/ai-workflow 0.7.0 → 0.9.0

package/dist/hook-installer.d.ts

@@ -0,0 +1,30 @@
+import type { FileSystem } from "./types.js";
+/**
+ * Claude Code hook installer: wires harness events to `aiw heartbeat`
+ * without a scheduler. Project-scoped: writes `.claude/settings.json` in
+ * the repository, never the user's global settings.
+ *
+ * Merge policy: existing hooks the project already declares are preserved
+ * untouched; AIW only appends its own entries, identified by the
+ * `aiw heartbeat` command, and skips them when already present
+ * (idempotent). Any JSON that is not a settings object is a hard conflict.
+ */
+export declare const CLAUDE_HOOK_COMMAND = "npx --yes --package=@multileaf/ai-workflow -- aiw heartbeat";
+export type ClaudeHookEntry = {
+    hooks: {
+        type: string;
+        command: string;
+        timeout?: number;
+    }[];
+};
+export type ClaudeSettings = {
+    hooks?: Record<string, ClaudeHookEntry[]>;
+} & Record<string, unknown>;
+export declare const AIW_HEARTBEAT_EVENTS: readonly ["Stop", "UserPromptSubmit"];
+export declare function parseClaudeSettings(content: string): ClaudeSettings;
+export declare function installHeartbeatHooks(settings: ClaudeSettings): {
+    settings: ClaudeSettings;
+    added: string[];
+    alreadyPresent: string[];
+};
+export declare function writeClaudeSettings(fs: FileSystem, path: string, settings: ClaudeSettings): void;

package/dist/hook-installer.js

@@ -0,0 +1,52 @@
+/**
+ * Claude Code hook installer: wires harness events to `aiw heartbeat`
+ * without a scheduler. Project-scoped: writes `.claude/settings.json` in
+ * the repository, never the user's global settings.
+ *
+ * Merge policy: existing hooks the project already declares are preserved
+ * untouched; AIW only appends its own entries, identified by the
+ * `aiw heartbeat` command, and skips them when already present
+ * (idempotent). Any JSON that is not a settings object is a hard conflict.
+ */
+export const CLAUDE_HOOK_COMMAND = "npx --yes --package=@multileaf/ai-workflow -- aiw heartbeat";
+export const AIW_HEARTBEAT_EVENTS = ["Stop", "UserPromptSubmit"];
+export function parseClaudeSettings(content) {
+    if (!content.trim())
+        return {};
+    const parsed = JSON.parse(content);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        throw new Error(".claude/settings.json must be a JSON object.");
+    const settings = parsed;
+    if (settings.hooks !== undefined) {
+        if (typeof settings.hooks !== "object" ||
+            settings.hooks === null ||
+            Array.isArray(settings.hooks))
+            throw new Error(".claude/settings.json hooks must be an object keyed by event name.");
+        for (const [event, entries] of Object.entries(settings.hooks))
+            if (!Array.isArray(entries))
+                throw new Error(`.claude/settings.json hooks.${event} must be a list.`);
+    }
+    return settings;
+}
+export function installHeartbeatHooks(settings) {
+    const hooks = { ...(settings.hooks ?? {}) };
+    const added = [];
+    const alreadyPresent = [];
+    for (const event of AIW_HEARTBEAT_EVENTS) {
+        const entries = hooks[event] ? [...hooks[event]] : [];
+        const exists = entries.some((entry) => entry.hooks?.some((hook) => hook.command === CLAUDE_HOOK_COMMAND));
+        if (exists)
+            alreadyPresent.push(event);
+        else {
+            entries.push({
+                hooks: [{ type: "command", command: CLAUDE_HOOK_COMMAND, timeout: 15 }],
+            });
+            added.push(event);
+        }
+        hooks[event] = entries;
+    }
+    return { settings: { ...settings, hooks }, added, alreadyPresent };
+}
+export function writeClaudeSettings(fs, path, settings) {
+    fs.write(path, `${JSON.stringify(settings, null, 2)}\n`);
+}

package/dist/model-routing.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Static model routing table — advisory, versioned, evidence-linked.
+ *
+ * Research consensus (docs/token-efficiency-study-notes.md §1 and §5):
+ * optimal routing is usually static — per-request dynamism mostly adds
+ * failure modes. Rules follow the ModelFit discipline: every recommendation
+ * names the evidence behind it, execution is advisory only, and humans can
+ * always override. The table never invokes a model; it answers "which model
+ * should this category use, and why".
+ */
+export declare const ROUTING_TABLE_SCHEMA = 1;
+export declare const ROUTING_TABLE_PATH = "routing.yml";
+export declare const ROUTING_DEFAULT_UNSET = "unset";
+export type RoutingRule = {
+    category: string;
+    model: string;
+    /** Named evidence (benchmark, parity run, ADR) backing this rule. Empty means unevidenced. */
+    evidence: string;
+};
+export type RoutingTable = {
+    schema: number;
+    default: string;
+    rules: RoutingRule[];
+};
+export type ResolvedRoute = {
+    category: string;
+    model: string;
+    matchedRule: boolean;
+    evidence?: string;
+    advisory: "evidenced" | "unevidenced-rule" | "default-fallback" | "default-unset";
+};
+export declare function validateRoutingTable(table: RoutingTable): RoutingTable;
+export declare function defaultRoutingTable(): RoutingTable;
+export declare function parseRoutingTable(content: string): RoutingTable;
+export declare function serializeRoutingTable(table: RoutingTable): string;
+/** Resolve a category to a model. Deterministic: same table, same category, same answer. */
+export declare function resolveRoute(table: RoutingTable, category: string): ResolvedRoute;
+export declare function serializeResolvedRoute(route: ResolvedRoute): string;

package/dist/model-routing.js

@@ -0,0 +1,116 @@
+import { parseDocument } from "yaml";
+/**
+ * Static model routing table — advisory, versioned, evidence-linked.
+ *
+ * Research consensus (docs/token-efficiency-study-notes.md §1 and §5):
+ * optimal routing is usually static — per-request dynamism mostly adds
+ * failure modes. Rules follow the ModelFit discipline: every recommendation
+ * names the evidence behind it, execution is advisory only, and humans can
+ * always override. The table never invokes a model; it answers "which model
+ * should this category use, and why".
+ */
+export const ROUTING_TABLE_SCHEMA = 1;
+export const ROUTING_TABLE_PATH = "routing.yml";
+export const ROUTING_DEFAULT_UNSET = "unset";
+const CATEGORY_PATTERN = /^[a-z][a-z0-9-]*(?:\.[a-z][a-z0-9-]*)*$/;
+function validateRule(rule) {
+    if (!CATEGORY_PATTERN.test(rule.category))
+        throw new Error(`Routing category must be dot-separated kebab-case: ${rule.category}.`);
+    if (!rule.model.trim())
+        throw new Error(`Routing rule for ${rule.category} needs a model.`);
+}
+export function validateRoutingTable(table) {
+    if (table.schema !== ROUTING_TABLE_SCHEMA)
+        throw new Error(`Routing table schema must be version ${ROUTING_TABLE_SCHEMA}.`);
+    if (!table.default.trim())
+        throw new Error("Routing table default model must not be empty.");
+    table.rules.forEach(validateRule);
+    const categories = table.rules.map((rule) => rule.category);
+    if (new Set(categories).size !== categories.length)
+        throw new Error("Routing table categories must be unique.");
+    return table;
+}
+export function defaultRoutingTable() {
+    return validateRoutingTable({
+        schema: ROUTING_TABLE_SCHEMA,
+        default: ROUTING_DEFAULT_UNSET,
+        rules: [],
+    });
+}
+export function parseRoutingTable(content) {
+    const document = parseDocument(content);
+    if (document.errors.length)
+        throw new Error("Routing table is not valid YAML.");
+    const schema = document.get("schema");
+    if (schema !== ROUTING_TABLE_SCHEMA)
+        throw new Error(`Routing table schema must be version ${ROUTING_TABLE_SCHEMA}.`);
+    const pick = (key) => document.get(key);
+    const rulesNode = pick("rules");
+    const rules = [];
+    if (rulesNode !== null && rulesNode !== undefined) {
+        const items = Array.isArray(rulesNode)
+            ? rulesNode
+            : typeof rulesNode.items === "object"
+                ? rulesNode.items
+                : undefined;
+        if (items === undefined)
+            throw new Error("Routing table rules must be a list.");
+        for (const raw of items) {
+            const read = (key) => typeof raw.get === "function"
+                ? raw.get(key)
+                : raw[key];
+            rules.push({
+                category: String(read("category")),
+                model: String(read("model")),
+                evidence: read("evidence") === null || read("evidence") === undefined
+                    ? ""
+                    : String(read("evidence")),
+            });
+        }
+    }
+    return validateRoutingTable({
+        schema: ROUTING_TABLE_SCHEMA,
+        default: String(pick("default") ?? ""),
+        rules,
+    });
+}
+export function serializeRoutingTable(table) {
+    validateRoutingTable(table);
+    const lines = [`schema: ${table.schema}`, `default: ${table.default}`, "rules:"];
+    if (!table.rules.length)
+        lines.push("  []");
+    for (const rule of table.rules) {
+        lines.push(`  - category: ${rule.category}`, `    model: ${rule.model}`, `    evidence: ${rule.evidence ? JSON.stringify(rule.evidence) : '""'}`);
+    }
+    return lines.join("\n") + "\n";
+}
+/** Resolve a category to a model. Deterministic: same table, same category, same answer. */
+export function resolveRoute(table, category) {
+    if (!CATEGORY_PATTERN.test(category))
+        throw new Error(`Routing category must be dot-separated kebab-case: ${category}.`);
+    const rule = table.rules.find((candidate) => candidate.category === category);
+    if (rule)
+        return {
+            category,
+            model: rule.model,
+            matchedRule: true,
+            ...(rule.evidence ? { evidence: rule.evidence } : {}),
+            advisory: rule.evidence ? "evidenced" : "unevidenced-rule",
+        };
+    if (table.default === ROUTING_DEFAULT_UNSET)
+        return { category, model: table.default, matchedRule: false, advisory: "default-unset" };
+    return { category, model: table.default, matchedRule: false, advisory: "default-fallback" };
+}
+export function serializeResolvedRoute(route) {
+    const advisoryText = {
+        evidenced: `advisory: rule is evidence-backed (${route.evidence})`,
+        "unevidenced-rule": "advisory: rule has no named evidence; benchmark it before trusting the routing",
+        "default-fallback": "advisory: no rule for this category; fell back to the table default",
+        "default-unset": "advisory: no rule for this category and the default is unset; a human must choose the model",
+    };
+    return [
+        `category: ${route.category}`,
+        `model: ${route.model}`,
+        advisoryText[route.advisory],
+    ].join("\n");
+}

package/dist/task-parity.d.ts

@@ -0,0 +1,67 @@
+import { type ContextLayer, type ContextStore } from "./context-store.js";
+/**
+ * Task parity suite (deterministic, offline, zero API cost).
+ *
+ * Each parity task pins a quality constraint on context assembly: the
+ * critical facts and completion markers a task needs must survive the
+ * just-in-time assembly path (`retrieveTaskContext`), not only the full
+ * composed context. If a fact only exists in a layer that retrieval drops,
+ * the task fails — that is a true-positive detection of context loss, not
+ * a benchmark artifact (see docs/token-efficiency-study-notes.md, step 2).
+ *
+ * Cost is reported (estimated, characters/4) but never gates: this suite is
+ * the quality gate; the cost gate is `aiw context-bench`.
+ */
+export declare const PARITY_TASK_SCHEMA = 1;
+export type ParityTask = {
+    schema: number;
+    id: string;
+    description: string;
+    layers: Partial<Record<ContextLayer, string>>;
+    criticalFacts: string[];
+    completionMarkers: string[];
+    /** Project-relative artifact paths loaded into layers before assembly (inter-stage parity). */
+    sources?: Partial<Record<ContextLayer, string>>;
+    /** Every literal match of these patterns in the loaded sources must survive assembly. */
+    requiredPatterns?: string[];
+};
+export type ParityAssembler = {
+    name: string;
+    assemble(store: ContextStore): string;
+};
+/** The default just-in-time assembly path under test. */
+export declare const TASK_ASSEMBLER: ParityAssembler;
+/** The full-context baseline every assembler is compared against. */
+export declare const FULL_ASSEMBLER: ParityAssembler;
+export type ParityTaskResult = {
+    id: string;
+    passed: boolean;
+    factsTotal: number;
+    factsRetained: number;
+    missingFacts: string[];
+    missingMarkers: string[];
+    missingPatterns: string[];
+    baselineTokens: number;
+    assembledTokens: number;
+    tokenDelta: number;
+};
+export type ParitySuiteResult = {
+    schema: number;
+    assembler: string;
+    total: number;
+    passed: number;
+    failed: number;
+    totalBaselineTokens: number;
+    totalAssembledTokens: number;
+    results: ParityTaskResult[];
+};
+export declare function parseParityTask(content: string): ParityTask;
+/**
+ * Load declared artifact sources into their layers (inter-stage parity).
+ * Source content is appended after any declared layer content.
+ */
+export declare function materializeParityTask(task: ParityTask, readSource: (path: string) => string): ParityTask;
+/** Run one task: baseline (full context) vs the assembler under test. Exits are pass/fail only. */
+export declare function runParityTask(task: ParityTask, assembler?: ParityAssembler): ParityTaskResult;
+export declare function runParitySuite(tasks: ParityTask[], assembler?: ParityAssembler): ParitySuiteResult;
+export declare function serializeParitySuite(result: ParitySuiteResult): string;

package/dist/task-parity.js

@@ -0,0 +1,202 @@
+import { isAbsolute } from "node:path";
+import { isMap, isScalar, isSeq, parseDocument } from "yaml";
+import { composeContext, CONTEXT_LAYERS, } from "./context-store.js";
+import { retrieveTaskContext } from "./context-retrieval.js";
+import { estimateTokens } from "./context-benchmark.js";
+/**
+ * Task parity suite (deterministic, offline, zero API cost).
+ *
+ * Each parity task pins a quality constraint on context assembly: the
+ * critical facts and completion markers a task needs must survive the
+ * just-in-time assembly path (`retrieveTaskContext`), not only the full
+ * composed context. If a fact only exists in a layer that retrieval drops,
+ * the task fails — that is a true-positive detection of context loss, not
+ * a benchmark artifact (see docs/token-efficiency-study-notes.md, step 2).
+ *
+ * Cost is reported (estimated, characters/4) but never gates: this suite is
+ * the quality gate; the cost gate is `aiw context-bench`.
+ */
+export const PARITY_TASK_SCHEMA = 1;
+/** The default just-in-time assembly path under test. */
+export const TASK_ASSEMBLER = {
+    name: "task-retrieval",
+    assemble: retrieveTaskContext,
+};
+/** The full-context baseline every assembler is compared against. */
+export const FULL_ASSEMBLER = {
+    name: "full-context",
+    assemble: composeContext,
+};
+export function parseParityTask(content) {
+    const document = parseDocument(content);
+    if (document.errors.length)
+        throw new Error(`Parity task is not valid YAML.`);
+    const schema = document.get("schema");
+    if (schema !== PARITY_TASK_SCHEMA)
+        throw new Error(`Parity task schema must be version ${PARITY_TASK_SCHEMA}.`);
+    const id = String(document.get("id") ?? "").trim();
+    if (!id)
+        throw new Error("Parity task id is required.");
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(id))
+        throw new Error(`Parity task id must be lowercase letters, numbers, and hyphens: ${id}.`);
+    const description = String(document.get("description") ?? "").trim();
+    const layersNode = document.get("layers");
+    const layers = {};
+    if (layersNode !== null && layersNode !== undefined) {
+        if (!isMap(layersNode))
+            throw new Error("Parity task layers must be a mapping.");
+        for (const layer of CONTEXT_LAYERS) {
+            const value = layersNode.get(layer);
+            if (value !== null && value !== undefined) {
+                if (typeof value !== "string")
+                    throw new Error(`Parity task layer ${layer} must be a string.`);
+                layers[layer] = value;
+            }
+        }
+    }
+    if (!CONTEXT_LAYERS.some((layer) => (layers[layer] ?? "").trim()))
+        throw new Error(`Parity task ${id} needs at least one non-empty context layer.`);
+    const listOf = (key) => {
+        const node = document.get(key);
+        if (node === null || node === undefined)
+            return [];
+        if (!isSeq(node))
+            throw new Error(`Parity task ${key} must be a list.`);
+        return node.items.map((item) => {
+            const value = isScalar(item) ? item.value : item;
+            if (typeof value !== "string" || !value.trim())
+                throw new Error(`Parity task ${key} entries must be non-empty strings.`);
+            return value;
+        });
+    };
+    const criticalFacts = listOf("critical_facts");
+    const completionMarkers = listOf("completion_markers");
+    const requiredPatterns = listOf("required_patterns");
+    if (!criticalFacts.length && !completionMarkers.length && !requiredPatterns.length)
+        throw new Error(`Parity task ${id} needs at least one critical fact, completion marker, or required pattern.`);
+    for (const pattern of requiredPatterns)
+        try {
+            new RegExp(pattern);
+        }
+        catch {
+            throw new Error(`Parity task ${id} has an invalid required pattern: ${pattern}`);
+        }
+    const sourcesNode = document.get("sources");
+    const sources = {};
+    if (sourcesNode !== null && sourcesNode !== undefined) {
+        if (!isMap(sourcesNode))
+            throw new Error("Parity task sources must be a mapping of layer to path.");
+        for (const layer of CONTEXT_LAYERS) {
+            const value = sourcesNode.get(layer);
+            if (value === null || value === undefined)
+                continue;
+            if (typeof value !== "string" || !value.trim())
+                throw new Error(`Parity task source for ${layer} must be a non-empty project-relative path.`);
+            if (isAbsolute(value) || value.split(/[\\/]/).includes(".."))
+                throw new Error(`Parity task source for ${layer} must be a safe project-relative path: ${value}`);
+            sources[layer] = value;
+        }
+    }
+    return {
+        schema: PARITY_TASK_SCHEMA,
+        id,
+        description,
+        layers,
+        criticalFacts,
+        completionMarkers,
+        ...(Object.keys(sources).length ? { sources } : {}),
+        ...(requiredPatterns.length ? { requiredPatterns } : {}),
+    };
+}
+/**
+ * Load declared artifact sources into their layers (inter-stage parity).
+ * Source content is appended after any declared layer content.
+ */
+export function materializeParityTask(task, readSource) {
+    if (!task.sources)
+        return task;
+    const layers = { ...task.layers };
+    for (const [layer, path] of Object.entries(task.sources)) {
+        let content;
+        try {
+            content = readSource(path);
+        }
+        catch (error) {
+            throw new Error(`Parity task ${task.id} cannot read source ${path}: ${error.message}`, {
+                cause: error,
+            });
+        }
+        layers[layer] = `${layers[layer] ? `${layers[layer].trimEnd()}\n\n` : ""}${content}`;
+    }
+    return { ...task, layers };
+}
+/** Run one task: baseline (full context) vs the assembler under test. Exits are pass/fail only. */
+export function runParityTask(task, assembler = TASK_ASSEMBLER) {
+    const store = {
+        layers: Object.fromEntries(CONTEXT_LAYERS.map((layer) => [layer, (task.layers[layer] ?? "").trim()])),
+    };
+    const baseline = FULL_ASSEMBLER.assemble(store);
+    const assembled = assembler.assemble(store);
+    const missingFacts = task.criticalFacts.filter((fact) => !assembled.includes(fact));
+    const missingMarkers = task.completionMarkers.filter((marker) => !assembled.includes(marker));
+    const missingPatterns = [];
+    if (task.requiredPatterns?.length) {
+        const sourceContent = CONTEXT_LAYERS.map((layer) => store.layers[layer]).join("\n");
+        for (const pattern of task.requiredPatterns) {
+            const matches = new Set(sourceContent.match(new RegExp(pattern, "g")) ?? []);
+            for (const match of matches)
+                if (!assembled.includes(match))
+                    missingPatterns.push(`${pattern} -> ${match}`);
+        }
+    }
+    const baselineTokens = estimateTokens(baseline);
+    const assembledTokens = estimateTokens(assembled);
+    return {
+        id: task.id,
+        passed: missingFacts.length === 0 && missingMarkers.length === 0 && missingPatterns.length === 0,
+        factsTotal: task.criticalFacts.length,
+        factsRetained: task.criticalFacts.length - missingFacts.length,
+        missingFacts,
+        missingMarkers,
+        missingPatterns,
+        baselineTokens,
+        assembledTokens,
+        tokenDelta: assembledTokens - baselineTokens,
+    };
+}
+export function runParitySuite(tasks, assembler = TASK_ASSEMBLER) {
+    const results = tasks.map((task) => runParityTask(task, assembler));
+    return {
+        schema: PARITY_TASK_SCHEMA,
+        assembler: assembler.name,
+        total: results.length,
+        passed: results.filter((result) => result.passed).length,
+        failed: results.filter((result) => !result.passed).length,
+        totalBaselineTokens: results.reduce((total, result) => total + result.baselineTokens, 0),
+        totalAssembledTokens: results.reduce((total, result) => total + result.assembledTokens, 0),
+        results,
+    };
+}
+export function serializeParitySuite(result) {
+    const lines = [
+        `schema: ${result.schema}`,
+        `assembler: ${result.assembler}`,
+        `tasks: ${result.total}`,
+        `passed: ${result.passed}`,
+        `failed: ${result.failed}`,
+        `total_baseline_tokens: ${result.totalBaselineTokens}`,
+        `total_assembled_tokens: ${result.totalAssembledTokens}`,
+        "token_estimate: characters/4 (estimated; quality gates are exact containment checks)",
+        "results:",
+    ];
+    for (const entry of result.results) {
+        lines.push(`  - id: ${entry.id}`, `    passed: ${entry.passed}`, `    facts: ${entry.factsRetained}/${entry.factsTotal}`, `    baseline_tokens: ${entry.baselineTokens}`, `    assembled_tokens: ${entry.assembledTokens}`);
+        if (entry.missingFacts.length)
+            lines.push(...entry.missingFacts.map((fact) => `    missing_fact: ${fact}`));
+        if (entry.missingMarkers.length)
+            lines.push(...entry.missingMarkers.map((marker) => `    missing_marker: ${marker}`));
+        if (entry.missingPatterns.length)
+            lines.push(...entry.missingPatterns.map((pattern) => `    missing_pattern: ${pattern}`));
+    }
+    return lines.join("\n") + "\n";
+}

package/dist/traceability.d.ts

@@ -10,6 +10,8 @@ export type TraceabilityGraph = {
     schema: 1;
     links: TraceabilityLink[];
 };
+/** Parse a serialized traceability graph (round-trips serializeTraceabilityGraph). */
+export declare function parseTraceabilityGraph(content: string): TraceabilityGraph;
 type TraceabilityInput = {
     specification: string;
     plan: string;

package/dist/traceability.js

@@ -1,3 +1,38 @@
+/** Parse a serialized traceability graph (round-trips serializeTraceabilityGraph). */
+export function parseTraceabilityGraph(content) {
+    if (!content.trim())
+        throw new Error("Traceability graph is empty.");
+    const schema = content.match(/^schema: (\d+)$/m)?.[1];
+    if (schema !== "1")
+        throw new Error("Traceability graph schema must be version 1.");
+    const links = [];
+    for (const match of content.matchAll(/^ {2}- requirement: (REQ-\d+)$/gm)) {
+        const requirement = match[1];
+        const blockStart = (match.index ?? 0) + match[0].length;
+        const next = content.slice(blockStart).match(/^ {2}- requirement: /m);
+        const block = content.slice(blockStart, next?.index === undefined ? undefined : blockStart + next.index);
+        const listOf = (field) => {
+            const raw = block?.match(new RegExp(`^ {4}${field}: (.+)$`, "m"))?.[1] ?? "[]";
+            if (raw === "[]")
+                return [];
+            return raw
+                .slice(1, -1)
+                .split(/,\s*/)
+                .map((value) => (value.startsWith('"') && value.endsWith('"') ? JSON.parse(value) : value));
+        };
+        links.push({
+            requirement,
+            decisions: listOf("decisions"),
+            tasks: listOf("tasks"),
+            code: listOf("code"),
+            tests: listOf("tests"),
+            evidence: listOf("evidence"),
+        });
+    }
+    if (!links.length)
+        throw new Error("Traceability graph has no requirement links.");
+    return { schema: 1, links };
+}
 const uniqueSorted = (values) => [...new Set(values)].sort();
 function valuesForField(block, field) {
     const expression = new RegExp(`^\\s*-?\\s*${field}:\\s*(.+)$`, "gim");

package/dist/usage-import.d.ts

@@ -0,0 +1,51 @@
+import type { UsageSidecarEntry } from "./usage-sidecar.js";
+/**
+ * Deterministic importers that turn local harness session logs into
+ * measured sidecar entries (the switchboard pattern: raw logs -> canonical
+ * ledger via per-source converters; no LLM, no network, no timestamps).
+ *
+ * Formats were validated against real logs:
+ * - Claude Code: the .jsonl transcripts under ~/.claude/projects/<munged-root>
+ *   carry message.usage with all four tiers; stream chunks
+ *   duplicate per message.id, so entries are deduplicated by message id.
+ * - Codex: the recursive rollout-*.jsonl tree under ~/.codex/sessions — token_usage_record entries; input_tokens includes the cached subset; session_meta.cwd
+ *   scopes a session to this project.
+ * - Gemini (antigravity-cli): the transcript_full.jsonl logs under the ~/.gemini/antigravity-cli/brain sessions — PLANNER_RESPONSE entries with
+ *   input/cache_read/output. Sessions do not record their working
+ *   directory, so Gemini imports cannot be scoped per project.
+ *
+ * - Pi (pi.dev): the session JSONL tree under ~/.pi/agent/sessions, grouped
+ *   by project directory. Assistant messages carry per-message usage with
+ *   all four tiers plus the provider and model, and dedicated usage entries
+ *   (for example cache warming) record model-attributed consumption that
+ *   never becomes a message.
+ *
+ * Import is idempotent: each event derives a stable command identity
+ * (`import.<source>.<hash>`), and events already present in the ledger
+ * are skipped, so reruns never double-count.
+ */
+export type ImportSource = "claude-code" | "codex" | "gemini" | "pi";
+/** An event ready to append: no seq (assigned by the ledger). */
+export type ImportedUsageEvent = Omit<UsageSidecarEntry, "seq">;
+export type ImportResult = {
+    source: ImportSource;
+    files: number;
+    events: number;
+    imported: number;
+    skipped: number;
+};
+/** Claude Code: one JSONL transcript per session; dedupe assistant chunks by message id. */
+export declare function parseClaudeCodeTranscript(content: string): ImportedUsageEvent[];
+/** Codex: rollout JSONL; returns undefined when the session belongs to another project. */
+export declare function parseCodexSession(content: string, projectRoot: string): ImportedUsageEvent[] | undefined;
+/** Gemini (antigravity-cli): transcript_full JSONL; PLANNER_RESPONSE steps carry token counts. */
+export declare function parseGeminiTranscript(content: string): ImportedUsageEvent[];
+/** Pi (pi.dev): session JSONL; assistant messages and dedicated usage entries both carry per-message tiers and provider. */
+export declare function parsePiSession(content: string): ImportedUsageEvent[];
+/** Merge imported events into a ledger idempotently (already-present command ids are skipped). */
+export declare function mergeImportedEvents(ledger: UsageSidecarEntry[], events: ImportedUsageEvent[]): {
+    ledger: UsageSidecarEntry[];
+    imported: number;
+    skipped: number;
+};
+export declare function summarizeImport(result: ImportResult): string;