@multileaf/ai-workflow 0.6.1 → 0.8.0

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/recommendations.js

@@ -14,6 +14,19 @@ const CATALOG = [
             ? { evidence: projectEvidence(profile), confidence: 0.92 }
             : undefined,
     },
+    {
+        id: "ticket-driven-development",
+        provider: "multileaf",
+        rationale: "Work often arrives as a ticket or an already-clear requirement; this entry point starts the SDD flow from the ticket without a brainstorming phase.",
+        permissions: [],
+        resources: local([
+            { type: "skills", id: "ticket" },
+            { type: "templates", id: "task" },
+        ]),
+        matches: (profile) => hasProjectSignals(profile)
+            ? { evidence: projectEvidence(profile), confidence: 0.9 }
+            : undefined,
+    },
     {
         id: "requirements-specification",
         provider: "multileaf",

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/token-usage.d.ts

@@ -2,8 +2,14 @@ export type TokenUsage = {
     stage: string;
     budget: number;
     used: number;
+    model?: string;
 };
 export declare function validateTokenUsage(usage: TokenUsage): TokenUsage;
 export declare function parseTokenUsage(content: string): TokenUsage[];
 export declare function serializeTokenUsage(entries: TokenUsage[]): string;
 export declare function recordTokenUsage(entries: TokenUsage[], usage: TokenUsage): TokenUsage[];
+export declare function summarizeUsageByModel(entries: TokenUsage[]): {
+    model: string;
+    tokens: number;
+    stages: string[];
+}[];

package/dist/token-usage.js

@@ -10,6 +10,8 @@ export function validateTokenUsage(usage) {
     }
     if (usage.used > usage.budget)
         throw new Error(`Token budget exceeded for stage: ${usage.stage}`);
+    if (usage.model !== undefined && (typeof usage.model !== "string" || !usage.model.trim()))
+        throw new Error("Token usage model must be a non-empty string when present.");
     return usage;
 }
 export function parseTokenUsage(content) {
@@ -20,19 +22,44 @@ export function parseTokenUsage(content) {
         .slice(1)
         .filter(Boolean)
         .map((line) => {
-        const [stage, budget, used] = line.split("|");
-        return validateTokenUsage({ stage, budget: Number(budget), used: Number(used) });
+        const [stage, budget, used, model] = line.split("|");
+        return validateTokenUsage({
+            stage,
+            budget: Number(budget),
+            used: Number(used),
+            ...(model ? { model } : {}),
+        });
     });
 }
 export function serializeTokenUsage(entries) {
     return ([
         "schema: 1",
         ...entries
-            .sort((a, b) => a.stage.localeCompare(b.stage))
-            .map((entry) => `${entry.stage}|${entry.budget}|${entry.used}`),
+            .sort((a, b) => a.stage < b.stage
+            ? -1
+            : a.stage > b.stage
+                ? 1
+                : (a.model ?? "").localeCompare(b.model ?? ""))
+            .map((entry) => `${entry.stage}|${entry.budget}|${entry.used}${entry.model ? `|${entry.model}` : ""}`),
     ].join("\n") + "\n");
 }
 export function recordTokenUsage(entries, usage) {
     validateTokenUsage(usage);
-    return [...entries.filter((entry) => entry.stage !== usage.stage), usage];
+    return [
+        ...entries.filter((entry) => entry.stage !== usage.stage || entry.model !== usage.model),
+        usage,
+    ];
+}
+export function summarizeUsageByModel(entries) {
+    const byModel = new Map();
+    for (const entry of entries) {
+        const model = entry.model ?? "unattributed";
+        const bucket = byModel.get(model) ?? { tokens: 0, stages: new Set() };
+        bucket.tokens += entry.used;
+        bucket.stages.add(entry.stage);
+        byModel.set(model, bucket);
+    }
+    return [...byModel]
+        .map(([model, { tokens, stages }]) => ({ model, tokens, stages: [...stages].sort() }))
+        .sort((a, b) => b.tokens - a.tokens || a.model.localeCompare(b.model));
 }

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-sidecar.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Usage sidecar (switchboard pattern): per-run token records with billing
+ * tiers, measurement labels, and harness attribution, stored alongside
+ * workflow checkpoints.
+ *
+ * Honest-measurement rules (docs/token-efficiency-study-notes.md):
+ * - every entry carries `measured` or `estimated`; aggregates propagate the
+ *   label pessimistically (any estimated component makes the total estimated);
+ * - no timestamps: entries are ordered by a monotonic sequence number, so
+ *   unchanged input produces byte-identical output;
+ * - naive `tokens x price` accounting overstates savings on cache-heavy
+ *   agents, so tiers are kept separate and cache hit rate is a first-class
+ *   metric. Cost conversion is deliberately not built in: provider prices
+ *   rot, and unlabeled dollars would be dishonest by default.
+ */
+export declare const USAGE_SIDECAR_SCHEMA = 1;
+export declare const USAGE_SIDECAR_PATH = "checkpoints/usage-sidecar.yml";
+export declare const USAGE_SIDECAR_CAP = 500;
+export declare const USAGE_TIERS: readonly ["cache-read", "fresh-input", "cache-write", "output"];
+export type UsageTier = (typeof USAGE_TIERS)[number];
+export type UsageLabel = "measured" | "estimated";
+export type UsageSidecarEntry = {
+    seq: number;
+    command: string;
+    label: UsageLabel;
+    tiers: Record<UsageTier, number>;
+    model?: string;
+    harness?: string;
+    harnessVersion?: string;
+    requirement?: string;
+    /** Correlates entries with one SDD task run (`aiw task start --id=` or ticket), start to merged PR. */
+    workflow?: string;
+};
+export type UsageSidecarSummary = {
+    entries: number;
+    label: UsageLabel;
+    tiers: Record<UsageTier, number>;
+    cacheHitRate?: number;
+    byModel: {
+        model: string;
+        tokens: number;
+        label: UsageLabel;
+    }[];
+    byHarness: {
+        harness: string;
+        tokens: number;
+        label: UsageLabel;
+    }[];
+};
+export declare function validateUsageSidecarEntry(entry: UsageSidecarEntry): UsageSidecarEntry;
+export declare function parseUsageSidecar(content: string): UsageSidecarEntry[];
+export declare function serializeUsageSidecar(entries: UsageSidecarEntry[]): string;
+/** Append an entry, assigning the next sequence number. Drops nothing: the ledger is capped by the caller. */
+export declare function appendUsageSidecarEntry(entries: UsageSidecarEntry[], entry: Omit<UsageSidecarEntry, "seq">): UsageSidecarEntry[];
+export declare function summarizeUsageSidecar(entries: UsageSidecarEntry[]): UsageSidecarSummary;
+export declare function serializeUsageSidecarSummary(summary: UsageSidecarSummary): string;