crewhaus 0.1.7 → 0.2.0

package/dist/lessons.js

@@ -0,0 +1,207 @@
+/**
+ * Item #56 — auto-maintained LESSONS.md + per-user preference files.
+ *
+ * `crewhaus lessons update` mines two durable signals:
+ *   - CORRECTION lessons: a `user_feedback` record carrying a `correction`
+ *     (the user's better answer) OR a low-rated turn with a comment — the
+ *     "here's what went wrong / do this instead" signal.
+ *   - FAILURE→FIX lessons: recurring negative signals from `dataset-mine`'s
+ *     `mineSession` (tool-error spikes, runtime errors, loop nudges, retries)
+ *     paired to the triggering turn — "when X happens, watch out."
+ * These fold into a deduped, append-with-merge LESSONS.md (like the project-
+ * memory files the runtime already auto-loads — LESSONS.md is added to the
+ * canonical set, so it is injected into the system prompt at run start).
+ *
+ * Per-user preferences: when feedback carries a `rater` identity, ratings +
+ * comments for that rater fold into a per-user prefs file
+ * (`.crewhaus/preferences/<rater>.md`) injected when that user is known.
+ *
+ * Pure + deterministic (stable order, normalized-text dedupe → idempotent
+ * re-runs); FS + redaction wiring lives in `apps/cli/src/index.ts`. Lesson +
+ * preference text is model/user output → PII/secret-redacted by the caller.
+ */
+import { mergeFeedback, normalizeRating } from "./feedback";
+function normalizeKey(s) {
+    return s.toLowerCase().replace(/\s+/g, " ").trim();
+}
+function clip(s, n) {
+    const t = s.replace(/\s+/g, " ").trim();
+    return t.length > n ? `${t.slice(0, n - 1).trimEnd()}…` : t;
+}
+/**
+ * Mine lessons from turns + feedback + pre-mined failure signals. Returns a
+ * deterministically-ordered, deduped list. `failureSignals` is the output of
+ * `mineSession` across the scanned sessions (each `{ input, reason }`), so the
+ * failure→fix lessons reuse the same negative-signal detection the dataset
+ * miner uses rather than reinventing it.
+ */
+export async function mineLessons(turns, feedback, failureSignals, opts = {}) {
+    const lowScore = opts.lowScore ?? 0.5;
+    const redact = opts.redact ?? (async (t) => t);
+    const turnByKey = new Map();
+    for (const t of turns)
+        turnByKey.set(`${t.sessionId}#${t.turnNumber}`, t);
+    const byKey = new Map();
+    const add = (text, kind) => {
+        const clean = clip(text, 300);
+        if (clean === "")
+            return;
+        const key = normalizeKey(clean);
+        if (!byKey.has(key))
+            byKey.set(key, { key, text: clean, kind });
+    };
+    // Correction lessons from feedback (merged so one per turn). #56 F3 — the
+    // echoed question prefix is a raw user turn (may carry a pasted credential),
+    // so it is redacted too, not just the correction/comment body.
+    for (const fb of mergeFeedback(feedback)) {
+        const turn = turnByKey.get(`${fb.sessionId}#${fb.turnNumber}`);
+        const question = turn?.input?.trim();
+        const score = normalizeRating(fb);
+        if (fb.correction !== undefined && fb.correction.trim() !== "") {
+            const q = question ? `For "${await redact(clip(question, 80))}": ` : "";
+            add(`${q}prefer this answer — ${await redact(fb.correction)}`, "correction");
+        }
+        else if (fb.comment !== undefined &&
+            fb.comment.trim() !== "" &&
+            score !== undefined &&
+            score <= lowScore) {
+            const q = question ? `For "${await redact(clip(question, 80))}": ` : "";
+            add(`${q}avoid — ${await redact(fb.comment)}`, "correction");
+        }
+    }
+    // Failure→fix lessons from the mined negative signals. #56 F3 — BOTH the
+    // echoed user input AND the failure reason (raw error messages carry
+    // connection strings / tokens) are redacted before landing in an
+    // auto-injected lesson.
+    for (const sig of failureSignals) {
+        const redactedInput = sig.input.trim() !== "" ? await redact(clip(sig.input, 80)) : "";
+        const q = redactedInput !== "" ? ` on "${redactedInput}"` : "";
+        add(`Watch out${q}: ${await redact(sig.reason)}.`, "failure-fix");
+    }
+    // Stable order: corrections first (higher-signal), then failure-fixes; each
+    // group alphabetized by key so re-runs produce byte-identical output.
+    return [...byKey.values()].sort((a, b) => (a.kind === b.kind ? 0 : a.kind === "correction" ? -1 : 1) || a.key.localeCompare(b.key));
+}
+/**
+ * Merge fresh lessons into existing ones, deduping by normalized key so a
+ * re-run never duplicates a lesson (append-with-merge idempotency). Existing
+ * lessons are preserved; new keys appended; ordering re-stabilized.
+ */
+export function mergeLessons(existing, fresh) {
+    const byKey = new Map();
+    for (const l of existing)
+        byKey.set(l.key, l);
+    for (const l of fresh)
+        if (!byKey.has(l.key))
+            byKey.set(l.key, l);
+    return [...byKey.values()].sort((a, b) => (a.kind === b.kind ? 0 : a.kind === "correction" ? -1 : 1) || a.key.localeCompare(b.key));
+}
+const LESSONS_HEADER = "# LESSONS";
+const LESSONS_NOTE = "<!-- Auto-maintained by `crewhaus lessons update`. Deduped + idempotent; hand-edits above the marker are preserved. -->";
+const LESSONS_MARKER = "<!-- crewhaus:lessons -->";
+/**
+ * Render LESSONS.md. Everything BELOW the `crewhaus:lessons` marker is machine-
+ * managed (the sorted lesson list); anything a human wrote ABOVE it is
+ * preserved verbatim by `parseLessonsMd` on the next update.
+ */
+export function renderLessonsMd(lessons, preamble = "") {
+    const corrections = lessons.filter((l) => l.kind === "correction");
+    const failures = lessons.filter((l) => l.kind === "failure-fix");
+    const lines = [];
+    const pre = preamble.trimEnd();
+    lines.push(pre === "" ? `${LESSONS_HEADER}\n\n${LESSONS_NOTE}` : pre);
+    lines.push("");
+    lines.push(LESSONS_MARKER);
+    if (corrections.length > 0) {
+        lines.push("");
+        lines.push("## Corrections & preferences");
+        lines.push("");
+        for (const l of corrections)
+            lines.push(`- ${l.text}`);
+    }
+    if (failures.length > 0) {
+        lines.push("");
+        lines.push("## Known failure patterns");
+        lines.push("");
+        for (const l of failures)
+            lines.push(`- ${l.text}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+/**
+ * Parse an existing LESSONS.md back into `{ preamble, lessons }`. The preamble
+ * is everything before the `crewhaus:lessons` marker (preserved on re-render);
+ * lessons are the `- ` bullets under the two managed sections, tagged by which
+ * section they came from. Files without the marker are treated as all-preamble
+ * (a human-authored file), so we never clobber hand-written lessons.
+ */
+export function parseLessonsMd(content) {
+    const markerIdx = content.indexOf(LESSONS_MARKER);
+    if (markerIdx === -1)
+        return { preamble: content, lessons: [] };
+    const preamble = content.slice(0, markerIdx).trimEnd();
+    const managed = content.slice(markerIdx + LESSONS_MARKER.length);
+    const lessons = [];
+    let kind = "correction";
+    for (const rawLine of managed.split("\n")) {
+        const line = rawLine.trim();
+        if (line.startsWith("## Known failure"))
+            kind = "failure-fix";
+        else if (line.startsWith("## Corrections"))
+            kind = "correction";
+        else if (line.startsWith("- ")) {
+            const text = line.slice(2).trim();
+            if (text !== "")
+                lessons.push({ key: normalizeKey(text), text, kind });
+        }
+    }
+    return { preamble, lessons };
+}
+/**
+ * Fold feedback carrying a `rater` into per-user preference notes. A rater's
+ * comments (on any rating) and corrections become their preference bullets,
+ * deduped + stably ordered. Returns one entry per rater, sorted by rater id.
+ */
+export async function minePreferences(feedback, opts = {}) {
+    const redact = opts.redact ?? (async (t) => t);
+    const byRater = new Map();
+    for (const fb of mergeFeedback(feedback)) {
+        if (fb.rater === undefined || fb.rater.trim() === "")
+            continue;
+        const bucket = byRater.get(fb.rater) ?? { keys: new Set(), notes: [] };
+        const candidates = [];
+        if (fb.correction !== undefined && fb.correction.trim() !== "") {
+            candidates.push(`prefers answers like: ${await redact(fb.correction)}`);
+        }
+        if (fb.comment !== undefined && fb.comment.trim() !== "") {
+            candidates.push(await redact(fb.comment));
+        }
+        for (const c of candidates) {
+            const clean = clip(c, 240);
+            const key = normalizeKey(clean);
+            if (clean !== "" && !bucket.keys.has(key)) {
+                bucket.keys.add(key);
+                bucket.notes.push(clean);
+            }
+        }
+        byRater.set(fb.rater, bucket);
+    }
+    return [...byRater.entries()]
+        .filter(([, b]) => b.notes.length > 0)
+        .map(([rater, b]) => ({ rater, notes: b.notes }))
+        .sort((a, b) => a.rater.localeCompare(b.rater));
+}
+/** Render a per-user preferences markdown file (a project-memory-style block). */
+export function renderPreferencesMd(prefs) {
+    const lines = [
+        `# Preferences — ${prefs.rater}`,
+        "",
+        "<!-- Auto-maintained by `crewhaus lessons update`. -->",
+        "",
+        "When serving this user, honour these preferences learned from their feedback:",
+        "",
+    ];
+    for (const n of prefs.notes)
+        lines.push(`- ${n}`);
+    return `${lines.join("\n")}\n`;
+}

package/dist/lint.d.ts

@@ -0,0 +1,127 @@
+import { type IrNode } from "@crewhaus/compiler";
+import { type IrPass } from "@crewhaus/ir-passes";
+import { type Spec } from "@crewhaus/spec";
+import { auditToolScopes } from "@crewhaus/tool-builder";
+import type { RegisteredTool } from "@crewhaus/tool-catalog";
+/**
+ * Item 41 — `crewhaus lint`. A check-only command: `parseSpec` +
+ * `compile({ applyIrPasses: true })` (the §47 chain / graph-crew
+ * well-formedness passes) + `auditToolScopes`, WITHOUT emitting a bundle.
+ *
+ * WHY THIS EXISTS: the CLI compile path never applied the ir-passes today, so
+ * §47 referential-integrity and graph/crew well-formedness checks silently
+ * skipped for CLI users — a spec with a dangling `wallets[].chainId` or an
+ * unreachable graph node compiled clean. `lint` runs those passes (discarding
+ * the result) so authoring bugs surface without a build.
+ *
+ * COLLECT-ALL vs FAIL-FAST: the IR passes throw on the FIRST violation. For
+ * `--format text` that fail-fast is fine (one error, fix, re-run). For
+ * `--format json` (editors/CI) we want as many findings as possible, so we run
+ * each pass INDEPENDENTLY and catch-and-continue — collecting at most one
+ * finding per pass. That is the honest limit of an exception-based pass API
+ * (a single pass still stops at its own first violation); it is documented
+ * here and surfaced as `severity: "error"` findings with a stable `path`.
+ *
+ * Side-effect-free: `runLint` is a pure function over the spec text plus an
+ * injected tool resolver (so tests don't import the heavy tool packages). The
+ * CLI wrapper owns file IO and process exit.
+ */
+export type LintSeverity = "error" | "warning";
+/** One structured finding. `path` is a dot-joined spec/IR location (or a
+ *  synthetic id for whole-spec failures); shaped for editor/CI consumption. */
+export type LintFinding = {
+    readonly message: string;
+    readonly path: string;
+    readonly severity: LintSeverity;
+    /** Stable rule id (parse | ir-pass:<name> | scope | …) for grouping. */
+    readonly rule: string;
+};
+export type LintResult = {
+    readonly ok: boolean;
+    readonly findings: readonly LintFinding[];
+    /** The parsed spec when parse succeeded (so --fix can operate on it). */
+    readonly spec?: Spec;
+    /** The lowered IR when lowering succeeded. */
+    readonly ir?: IrNode;
+};
+/**
+ * Run the lint pipeline. `resolveTool` maps a tool NAME (either the camelCase
+ * spec key or its registered PascalCase name) to a `RegisteredTool`, or
+ * undefined — injected so this stays pure. `passes` defaults to the published
+ * `DEFAULT_PIPELINE` and is overridable for tests.
+ */
+export declare function runLint(yamlText: string, resolveTool: (name: string) => RegisteredTool | undefined, passes?: ReadonlyArray<IrPass>): LintResult;
+/** Re-exported for the CLI wrapper's philosophy-alignment parity note. */
+export { auditToolScopes };
+/** A single mechanical fix suggestion for a lint finding. */
+export type LintFixSuggestion = {
+    readonly kind: "unknown-tool" | "secret-typo" | "safe-name";
+    /** The offending token as written in the spec. */
+    readonly from: string;
+    /** The suggested replacement. */
+    readonly to: string;
+    /** Human-readable one-liner. */
+    readonly note: string;
+};
+/** Case-insensitive Levenshtein distance — the nearest-match metric. */
+export declare function levenshtein(a: string, b: string): number;
+/**
+ * The outcome of a nearest-match lookup:
+ *  - `undefined` — no candidate close enough (genuinely unknown, not a typo),
+ *    or the name is already legal.
+ *  - `{ kind: "match", name }` — a single unambiguous nearest candidate;
+ *    safe to auto-apply.
+ *  - `{ kind: "ambiguous", candidates }` — two or more equally-near
+ *    candidates whose I/O capability DIFFERS (e.g. a read-only tool vs a
+ *    mutating one), so auto-applying could silently cross a capability
+ *    boundary. Callers should surface this as a suggestion, not a fix.
+ */
+export type NearestToolMatch = {
+    readonly kind: "match";
+    readonly name: string;
+} | {
+    readonly kind: "ambiguous";
+    readonly candidates: readonly string[];
+};
+/**
+ * Nearest legal name(s) for a mistyped tool name. `candidates` is the union of
+ * the legal spellings — the camelCase BUILTIN_TOOL_MAP keys AND the registered
+ * PascalCase names (both forms are legal in a spec: top-level `tools:` uses the
+ * camelCase key; a sub-agent `tools:` uses the PascalCase registered name). An
+ * exact match returns undefined (nothing to fix). Otherwise the closest
+ * candidate(s) within `maxDistance` (default 3) are considered; undefined
+ * means nothing is close enough (a genuinely unknown tool, not a typo).
+ *
+ * `getReadOnly` is an optional injected lookup from candidate name → the
+ * resolved tool's `readOnly` flag (undefined when the candidate can't be
+ * resolved to a RegisteredTool, e.g. an unregistered custom-tool name — in
+ * that case its capability is unknown and it is never treated as crossing a
+ * boundary against another candidate). When ALL of the closest candidates
+ * (same minimum distance) agree on `readOnly` — including the degenerate
+ * single-candidate case — this returns a `"match"` for the first of them
+ * (stable, deterministic). When they DISAGREE — a typo equidistant from a
+ * read-only tool (e.g. `Read`) and a mutating one (e.g. `Edit`) — this
+ * returns `"ambiguous"` with the full tied set rather than silently picking
+ * one, because auto-applying would cross a read-only/mutating capability
+ * boundary the author never asked for.
+ */
+export declare function nearestToolName(name: string, candidates: readonly string[], maxDistance?: number, getReadOnly?: (candidateName: string) => boolean | undefined): NearestToolMatch | undefined;
+/**
+ * Suggest a `$UPPER_SNAKE_CASE` correction for a credential value that looks
+ * like an env reference but isn't a valid one — the same class the compiler's
+ * `lowerCredential` rejects (`$slack_token`, `${SLACK}`, `$1PASSWORD`).
+ * Returns the normalised form, or undefined when `value` is not a
+ * malformed-env-ref (a genuine literal, or already valid). Pure string logic.
+ */
+export declare function suggestSecretFix(value: string): string | undefined;
+/**
+ * Normalise a name that violates the `safeName` charset (letters, digits,
+ * spaces, `_ . - :`) by replacing every illegal character with `-` and
+ * collapsing runs. Returns undefined when `name` is already safe. Pure.
+ */
+export declare function suggestSafeName(name: string): string | undefined;
+/** Render the lint findings as the human-readable `text` report. Returns the
+ *  block plus whether it is clean, so the CLI can pick the exit code. */
+export declare function formatLintText(result: LintResult): string;
+/** Render the lint findings as `{ findings: LintFinding[] }` JSON for editors/CI. */
+export declare function formatLintJson(result: LintResult): string;

package/dist/lint.js

@@ -0,0 +1,226 @@
+import { lower } from "@crewhaus/compiler";
+import { CrewhausError } from "@crewhaus/errors";
+import { DEFAULT_PIPELINE } from "@crewhaus/ir-passes";
+import { SpecParseError, parseSpec } from "@crewhaus/spec";
+import { auditToolScopes } from "@crewhaus/tool-builder";
+import { auditSpecToolNames, collectToolNames } from "./scope-audit";
+/**
+ * Run the lint pipeline. `resolveTool` maps a tool NAME (either the camelCase
+ * spec key or its registered PascalCase name) to a `RegisteredTool`, or
+ * undefined — injected so this stays pure. `passes` defaults to the published
+ * `DEFAULT_PIPELINE` and is overridable for tests.
+ */
+export function runLint(yamlText, resolveTool, passes = DEFAULT_PIPELINE) {
+    const findings = [];
+    // Stage 1 — parse. A parse failure is terminal: without a spec there is
+    // nothing to lower or audit.
+    let spec;
+    try {
+        spec = parseSpec(yamlText);
+    }
+    catch (err) {
+        const message = err instanceof SpecParseError ? err.message : err.message;
+        findings.push({ message, path: "<spec>", severity: "error", rule: "parse" });
+        return { ok: false, findings };
+    }
+    // Stage 2 — lower. lower() can throw CompilerError (e.g. a malformed
+    // credential env-ref); treat as terminal for the IR-pass stage.
+    let ir;
+    try {
+        ir = lower(spec);
+    }
+    catch (err) {
+        const message = err instanceof CrewhausError ? err.message : err.message;
+        findings.push({ message, path: "<lower>", severity: "error", rule: "lower" });
+        return { ok: false, findings, spec };
+    }
+    // Stage 3 — IR passes, COLLECT-ALL. Run each pass independently so one pass's
+    // violation doesn't hide the others'. Validating passes
+    // (transactionPolicyEnforcement, wellFormednessCheck) throw IrPassError; the
+    // rewriting passes are pure and never throw. We discard rewritten IR (lint
+    // never emits) — only the thrown violations matter.
+    for (const pass of passes) {
+        try {
+            pass(ir);
+        }
+        catch (err) {
+            const message = err instanceof CrewhausError ? err.message : err.message;
+            findings.push({
+                message,
+                path: `ir-pass:${pass.name || "anonymous"}`,
+                severity: "error",
+                rule: `ir-pass:${pass.name || "anonymous"}`,
+            });
+        }
+    }
+    // Stage 4 — tool-scope audit over the IR's tool names, sharing the exact
+    // gate `compile --strict` uses. A resolvable built-in is audited by
+    // capability/scope; an outward-by-name sink that resolves to no external
+    // tool is a finding.
+    const toolNames = collectToolNames(ir);
+    const scopeFindings = auditSpecToolNames(toolNames, resolveTool);
+    for (const f of scopeFindings) {
+        findings.push({
+            message: `tool "${f.toolName}" ${f.reason}`,
+            path: `tools.${f.toolName}`,
+            severity: "error",
+            rule: "scope",
+        });
+    }
+    return { ok: findings.length === 0, findings, spec, ir };
+}
+/** Re-exported for the CLI wrapper's philosophy-alignment parity note. */
+export { auditToolScopes };
+/** Case-insensitive Levenshtein distance — the nearest-match metric. */
+export function levenshtein(a, b) {
+    const s = a.toLowerCase();
+    const t = b.toLowerCase();
+    const m = s.length;
+    const n = t.length;
+    if (m === 0)
+        return n;
+    if (n === 0)
+        return m;
+    let prev = Array.from({ length: n + 1 }, (_, i) => i);
+    let curr = new Array(n + 1);
+    for (let i = 1; i <= m; i++) {
+        curr[0] = i;
+        for (let j = 1; j <= n; j++) {
+            const cost = s[i - 1] === t[j - 1] ? 0 : 1;
+            curr[j] = Math.min((prev[j] ?? 0) + 1, (curr[j - 1] ?? 0) + 1, (prev[j - 1] ?? 0) + cost);
+        }
+        [prev, curr] = [curr, prev];
+    }
+    return prev[n] ?? 0;
+}
+/**
+ * Nearest legal name(s) for a mistyped tool name. `candidates` is the union of
+ * the legal spellings — the camelCase BUILTIN_TOOL_MAP keys AND the registered
+ * PascalCase names (both forms are legal in a spec: top-level `tools:` uses the
+ * camelCase key; a sub-agent `tools:` uses the PascalCase registered name). An
+ * exact match returns undefined (nothing to fix). Otherwise the closest
+ * candidate(s) within `maxDistance` (default 3) are considered; undefined
+ * means nothing is close enough (a genuinely unknown tool, not a typo).
+ *
+ * `getReadOnly` is an optional injected lookup from candidate name → the
+ * resolved tool's `readOnly` flag (undefined when the candidate can't be
+ * resolved to a RegisteredTool, e.g. an unregistered custom-tool name — in
+ * that case its capability is unknown and it is never treated as crossing a
+ * boundary against another candidate). When ALL of the closest candidates
+ * (same minimum distance) agree on `readOnly` — including the degenerate
+ * single-candidate case — this returns a `"match"` for the first of them
+ * (stable, deterministic). When they DISAGREE — a typo equidistant from a
+ * read-only tool (e.g. `Read`) and a mutating one (e.g. `Edit`) — this
+ * returns `"ambiguous"` with the full tied set rather than silently picking
+ * one, because auto-applying would cross a read-only/mutating capability
+ * boundary the author never asked for.
+ */
+export function nearestToolName(name, candidates, maxDistance = 3, getReadOnly) {
+    if (candidates.includes(name))
+        return undefined;
+    let bestDist;
+    let tied = [];
+    for (const cand of candidates) {
+        const dist = levenshtein(name, cand);
+        if (bestDist === undefined || dist < bestDist) {
+            bestDist = dist;
+            tied = [cand];
+        }
+        else if (dist === bestDist) {
+            tied.push(cand);
+        }
+    }
+    if (bestDist === undefined || bestDist > maxDistance)
+        return undefined;
+    if (tied.length === 1) {
+        const only = tied[0];
+        if (only === undefined)
+            return undefined;
+        return { kind: "match", name: only };
+    }
+    // Multiple equally-near candidates. If a capability lookup was injected and
+    // the tied set spans more than one `readOnly` value, that is a genuine
+    // cross-capability ambiguity — refuse to pick one. Candidates with unknown
+    // capability (getReadOnly returns undefined) don't by themselves create
+    // ambiguity: they only conflict when they disagree with a KNOWN capability
+    // among the tied set.
+    if (getReadOnly !== undefined) {
+        const knownCapabilities = new Set(tied.map((c) => getReadOnly(c)).filter((v) => v !== undefined));
+        if (knownCapabilities.size > 1) {
+            return { kind: "ambiguous", candidates: tied };
+        }
+    }
+    else {
+        // No capability signal available — a plain tie is still ambiguous rather
+        // than silently guessing via iteration order.
+        return { kind: "ambiguous", candidates: tied };
+    }
+    const first = tied[0];
+    if (first === undefined)
+        return undefined;
+    return { kind: "match", name: first };
+}
+/**
+ * Suggest a `$UPPER_SNAKE_CASE` correction for a credential value that looks
+ * like an env reference but isn't a valid one — the same class the compiler's
+ * `lowerCredential` rejects (`$slack_token`, `${SLACK}`, `$1PASSWORD`).
+ * Returns the normalised form, or undefined when `value` is not a
+ * malformed-env-ref (a genuine literal, or already valid). Pure string logic.
+ */
+export function suggestSecretFix(value) {
+    if (!value.startsWith("$"))
+        return undefined;
+    // Already valid $UPPER_SNAKE_CASE — nothing to fix.
+    if (/^\$[A-Z_][A-Z0-9_]*$/.test(value))
+        return undefined;
+    // Strip a ${...} brace wrapper, then normalise the inner token.
+    const inner = value.replace(/^\$\{?/, "").replace(/\}$/, "");
+    if (inner === "")
+        return undefined;
+    // UPPER_SNAKE_CASE it: non-alnum → _, then uppercase, then ensure it does
+    // not start with a digit (prefix `_`).
+    let normalised = inner.replace(/[^A-Za-z0-9]+/g, "_").toUpperCase();
+    if (/^[0-9]/.test(normalised))
+        normalised = `_${normalised}`;
+    if (!/^[A-Z_][A-Z0-9_]*$/.test(normalised))
+        return undefined;
+    return `$${normalised}`;
+}
+/** The single-line-safe name charset the spec's `safeName` enforces. */
+const SAFE_NAME_RE = /^[\w .:-]+$/;
+/**
+ * Normalise a name that violates the `safeName` charset (letters, digits,
+ * spaces, `_ . - :`) by replacing every illegal character with `-` and
+ * collapsing runs. Returns undefined when `name` is already safe. Pure.
+ */
+export function suggestSafeName(name) {
+    if (SAFE_NAME_RE.test(name) && name.length >= 1)
+        return undefined;
+    const fixed = name
+        .replace(/[^\w .:-]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "")
+        .trim();
+    if (fixed === "" || !SAFE_NAME_RE.test(fixed))
+        return undefined;
+    return fixed;
+}
+/** Render the lint findings as the human-readable `text` report. Returns the
+ *  block plus whether it is clean, so the CLI can pick the exit code. */
+export function formatLintText(result) {
+    if (result.findings.length === 0)
+        return "lint: clean — no findings.\n";
+    const lines = [];
+    for (const f of result.findings) {
+        const marker = f.severity === "error" ? "✗" : "~";
+        lines.push(`${marker} [${f.rule}] ${f.path}: ${f.message}`);
+    }
+    const errorCount = result.findings.filter((f) => f.severity === "error").length;
+    lines.push("");
+    lines.push(`lint: ${errorCount} error(s), ${result.findings.length - errorCount} warning(s).`);
+    return `${lines.join("\n")}\n`;
+}
+/** Render the lint findings as `{ findings: LintFinding[] }` JSON for editors/CI. */
+export function formatLintJson(result) {
+    return `${JSON.stringify({ ok: result.ok, findings: result.findings }, null, 2)}\n`;
+}

package/dist/loadtest.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Item 68 — `crewhaus loadtest <spec>`: drive a daemon-shape harness (managed
+ * gateway / channel-bot / batch) under concurrent load and measure throughput,
+ * p50/p95/p99 latency, error rate, and cost/req — with a `--gate` mode that
+ * fails (exit 1) when p95 latency or error rate exceed declared thresholds (a
+ * pre-deploy gate).
+ *
+ * Load is driven through an INJECTED `LoadDriver` — one async call per request
+ * that returns a `RequestOutcome`. That seam makes the runner deterministic +
+ * credential-free in tests (a stub driver returns canned latencies), while the
+ * CLI wires a real driver: the managed gateway's in-process `handle()` behind a
+ * stub/echo model, or the batch queue's consumer. No live server or provider
+ * key is needed for the runner itself.
+ *
+ * Everything here is side-effect-free (the CLI entry file constructs the driver
+ * + writes the report). The aggregation is pure: same outcomes → same report.
+ */
+/** Thrown on bad flags / driver misuse. The CLI routes it through `die()`. */
+export declare class LoadtestError extends Error {
+    readonly name = "LoadtestError";
+}
+/** The result of one driven request. */
+export type RequestOutcome = {
+    readonly ok: boolean;
+    readonly latencyMs: number;
+    /** Token usage, when the driver knows it (for cost/req). */
+    readonly tokens?: {
+        input: number;
+        output: number;
+    };
+    /** A short classification when `ok` is false (e.g. "429", "timeout"). */
+    readonly errorKind?: string;
+};
+/** The injected load driver: given a 0-based request index, drive ONE request
+ *  and resolve with its outcome. Must not throw — a thrown error is caught and
+ *  recorded as an errored request (errorKind "threw"). */
+export type LoadDriver = (reqIndex: number) => Promise<RequestOutcome>;
+export type LoadtestConfig = {
+    /** Concurrent in-flight requests. Default 10. */
+    readonly concurrency?: number;
+    /** Total requests to send. Mutually informative with `durationMs`; when both
+     *  are set, whichever bound is hit first ends the run. Default 100. */
+    readonly requests?: number;
+    /** Wall-clock budget (ms). When set, the run stops issuing new requests once
+     *  elapsed ≥ durationMs (in-flight requests still drain). */
+    readonly durationMs?: number;
+    /** Target requests-per-second. When set, the runner paces request dispatch to
+     *  approximately this rate (open-loop). Default: unthrottled (closed-loop). */
+    readonly rps?: number;
+    /** Price per 1M input / output tokens (USD) for the cost/req estimate. */
+    readonly pricePerMInput?: number;
+    readonly pricePerMOutput?: number;
+    /** A monotonic clock (ms) — injected for deterministic tests. Default performance.now. */
+    readonly now?: () => number;
+    /** A sleep(ms) primitive — injected for deterministic tests (rps pacing). */
+    readonly sleep?: (ms: number) => Promise<void>;
+};
+/** Gate thresholds — a run fails when any is exceeded. */
+export type GateThresholds = {
+    readonly maxP95LatencyMs?: number;
+    readonly maxErrorRate?: number;
+};
+export type LoadtestReport = {
+    readonly requests: number;
+    readonly succeeded: number;
+    readonly failed: number;
+    readonly errorRate: number;
+    readonly wallClockMs: number;
+    readonly throughputRps: number;
+    readonly latency: {
+        readonly p50: number;
+        readonly p95: number;
+        readonly p99: number;
+        readonly min: number;
+        readonly max: number;
+        readonly mean: number;
+    };
+    readonly tokens: {
+        input: number;
+        output: number;
+    };
+    /** USD per request (0 when pricing not supplied). */
+    readonly costPerReqUsd: number;
+    readonly totalCostUsd: number;
+    /** Breakdown of error kinds → count. */
+    readonly errorKinds: Readonly<Record<string, number>>;
+};
+/**
+ * Run a concurrent load test against the injected driver. Dispatches up to
+ * `concurrency` requests in flight until the request budget (or duration) is
+ * exhausted, then drains. Deterministic given a deterministic driver + clock.
+ */
+export declare function runLoadtest(driver: LoadDriver, config?: LoadtestConfig): Promise<LoadtestReport>;
+/**
+ * Aggregate raw outcomes into a report. Pure — exported so tests can assert on
+ * percentile math without driving a run, and so the CLI can re-aggregate a
+ * persisted outcome set.
+ */
+export declare function aggregateLoadtest(outcomes: readonly RequestOutcome[], opts: {
+    wallClockMs: number;
+    pricePerMInput?: number;
+    pricePerMOutput?: number;
+}): LoadtestReport;
+/** The gate verdict — which thresholds (if any) were breached. */
+export type GateVerdict = {
+    readonly passed: boolean;
+    readonly breaches: readonly string[];
+};
+/** Evaluate a report against gate thresholds. Empty thresholds → always passes. */
+export declare function evaluateGate(report: LoadtestReport, thresholds: GateThresholds): GateVerdict;
+/** Render a plain-text loadtest report. */
+export declare function renderLoadtestText(report: LoadtestReport, verdict?: GateVerdict): string;
+/** Render an HTML loadtest report (self-contained). */
+export declare function renderLoadtestHtml(report: LoadtestReport, verdict?: GateVerdict): string;