crewhaus 0.1.8 → 0.2.0

package/dist/sessions-index.js

@@ -0,0 +1,51 @@
+/**
+ * Item #57 — durable sessions index. Before a session JSONL is evicted (30-day
+ * TTL), it is summarized into a compact index entry under
+ * `.crewhaus/sessions-index/<id>.json` so the harness retains long-term
+ * knowledge (outcome, tools used, ratings, key facts) past raw-transcript
+ * retention. These entries feed the memory-store / few-shot / FAQ features.
+ *
+ * The summary logic lives in `@crewhaus/session-store` (`summarizeSession`, a
+ * deterministic no-model reducer). This module is the CLI-side glue: read a
+ * session's JSONL, summarize it, and write the index entry idempotently. Kept
+ * thin + separately testable, mirroring `feedback.ts` / `dataset-mine.ts`.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { summarizeSession } from "@crewhaus/session-store";
+/** The index directory, relative to a session root's PARENT `.crewhaus`. */
+export const SESSIONS_INDEX_DIRNAME = "sessions-index";
+/** Parse a JSONL blob into `{ kind, payload }` events, skipping bad lines. */
+export function parseSessionLog(text) {
+    const out = [];
+    for (const line of text.split("\n")) {
+        if (line.trim() === "")
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch {
+            // A single malformed line must not abort the summary.
+        }
+    }
+    return out;
+}
+/**
+ * Summarize the session whose `.jsonl` lives at `logPath` into `indexDir`,
+ * returning the written summary (or undefined when the log is missing/empty).
+ * Idempotent: re-writing the same session overwrites its entry rather than
+ * duplicating. `now` is injectable for deterministic tests.
+ */
+export function summarizeSessionIntoIndex(sessionId, logPath, indexDir, now = () => new Date()) {
+    if (!existsSync(logPath))
+        return undefined;
+    const events = parseSessionLog(readFileSync(logPath, "utf-8"));
+    if (events.length === 0)
+        return undefined;
+    const summary = summarizeSession(sessionId, events, { now });
+    mkdirSync(indexDir, { recursive: true });
+    writeFileSync(join(indexDir, `${sessionId}.json`), `${JSON.stringify(summary, null, 2)}\n`, {
+        mode: 0o600,
+    });
+    return summary;
+}

package/dist/slo-doctor.d.ts

@@ -0,0 +1,67 @@
+import { type PricingTable } from "@crewhaus/cost-tracker";
+/**
+ * A metrics-collector histogram series (one label set). `counts[i]` is the
+ * CUMULATIVE count at or below `buckets[i]` (as `Histogram.observe` stores it),
+ * `total` is the overall count. Used for the Prometheus-scrape fallback source.
+ */
+export type HistogramSeries = {
+    readonly buckets: ReadonlyArray<number>;
+    readonly counts: ReadonlyArray<number>;
+    readonly total: number;
+};
+/**
+ * Derive an approximate p-th percentile from a cumulative histogram's buckets —
+ * the coarse bucket-boundary estimate a Prometheus `histogram_quantile` gives.
+ * Returns the upper edge of the first bucket whose cumulative count reaches the
+ * rank. Empty ⇒ 0. The registry stores `model_ttft_seconds` in SECONDS, so the
+ * caller multiplies by 1000 for a millisecond comparison.
+ */
+export declare function percentileFromHistogram(series: HistogramSeries, p: number): number;
+/**
+ * Compute the trailing-N mean of the durable per-session `ttftP95Seconds`
+ * values from a sessions.jsonl text (torn lines skipped). Returns undefined
+ * when there is no usable history, so the probe can report "no data" rather
+ * than a spurious 0ms. `windowSessions` bounds how much recency the probe
+ * trusts (default 20 — a working week of runs).
+ */
+export declare function recentTtftP95Ms(sessionsJsonl: string, windowSessions?: number): number | undefined;
+export type FasterCandidate = {
+    readonly modelString: string;
+    readonly blendedPer1M: number;
+};
+/**
+ * Name faster-candidate models for a slow slot, cheapest blended price first.
+ * Cheaper models are smaller and — as a first-order proxy — faster to first
+ * token; the probe surfaces them as CANDIDATES to eval, never as an automatic
+ * swap (a spec change stays human-reviewed). Excludes the current model's own
+ * family and known sunsets. Empty when the current model isn't table-backed
+ * (local / azure / named-host) — the probe then just reports the breach.
+ */
+export declare function nameFasterCandidates(currentModel: string, opts?: {
+    readonly pricing?: PricingTable;
+    readonly limit?: number;
+}): FasterCandidate[];
+export type SloProbeResult = {
+    /** 0 = within SLO / no data (a probe must not flap on a cold store); 1 = breach. */
+    readonly exitCode: number;
+    readonly lines: ReadonlyArray<string>;
+};
+export type SloProbeInput = {
+    /** SLO ttft target in ms, from the lowered spec. Undefined ⇒ nothing to probe. */
+    readonly ttftTargetMs: number | undefined;
+    /** The spec's current agent model string (for candidate naming). */
+    readonly currentModel: string | undefined;
+    /** Durable sessions.jsonl text (`.crewhaus/metrics/sessions.jsonl`), or "". */
+    readonly sessionsJsonl: string;
+    /** Optional histogram fallback source (metrics-collector snapshot). */
+    readonly histogram?: HistogramSeries;
+    readonly pricing?: PricingTable;
+};
+/**
+ * Run the TTFT probe: build the human-readable report + the exit code. Pure —
+ * the CLI reads the files and owns `process.exit`. Precedence: durable
+ * sessions.jsonl first (the alert-watchdog's own history), then the histogram
+ * fallback. No target ⇒ exit 0 with a "nothing declared" note; no data ⇒ exit 0
+ * (a HEALTHCHECK must not flap on a store that has not accrued history yet).
+ */
+export declare function runSloProbe(input: SloProbeInput): SloProbeResult;

package/dist/slo-doctor.js

@@ -0,0 +1,119 @@
+import { DEFAULT_PRICING, enumerateCandidates, providerOfSpecString, } from "@crewhaus/cost-tracker";
+/**
+ * Derive an approximate p-th percentile from a cumulative histogram's buckets —
+ * the coarse bucket-boundary estimate a Prometheus `histogram_quantile` gives.
+ * Returns the upper edge of the first bucket whose cumulative count reaches the
+ * rank. Empty ⇒ 0. The registry stores `model_ttft_seconds` in SECONDS, so the
+ * caller multiplies by 1000 for a millisecond comparison.
+ */
+export function percentileFromHistogram(series, p) {
+    if (series.total === 0 || series.buckets.length === 0)
+        return 0;
+    const rank = p * series.total;
+    for (let i = 0; i < series.buckets.length; i += 1) {
+        if ((series.counts[i] ?? 0) >= rank)
+            return series.buckets[i] ?? 0;
+    }
+    // Above the top finite bucket → report the top edge (the +Inf bucket has no
+    // upper bound to name).
+    return series.buckets[series.buckets.length - 1] ?? 0;
+}
+/**
+ * Compute the trailing-N mean of the durable per-session `ttftP95Seconds`
+ * values from a sessions.jsonl text (torn lines skipped). Returns undefined
+ * when there is no usable history, so the probe can report "no data" rather
+ * than a spurious 0ms. `windowSessions` bounds how much recency the probe
+ * trusts (default 20 — a working week of runs).
+ */
+export function recentTtftP95Ms(sessionsJsonl, windowSessions = 20) {
+    const values = [];
+    for (const line of sessionsJsonl.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed === "")
+            continue;
+        try {
+            const snap = JSON.parse(trimmed);
+            if (typeof snap.ttftP95Seconds === "number" && Number.isFinite(snap.ttftP95Seconds)) {
+                values.push(snap.ttftP95Seconds * 1000);
+            }
+        }
+        catch {
+            // torn/append-in-progress line — skip.
+        }
+    }
+    if (values.length === 0)
+        return undefined;
+    const window = values.slice(-windowSessions);
+    return window.reduce((s, v) => s + v, 0) / window.length;
+}
+/**
+ * Name faster-candidate models for a slow slot, cheapest blended price first.
+ * Cheaper models are smaller and — as a first-order proxy — faster to first
+ * token; the probe surfaces them as CANDIDATES to eval, never as an automatic
+ * swap (a spec change stays human-reviewed). Excludes the current model's own
+ * family and known sunsets. Empty when the current model isn't table-backed
+ * (local / azure / named-host) — the probe then just reports the breach.
+ */
+export function nameFasterCandidates(currentModel, opts = {}) {
+    const parsed = providerOfSpecString(currentModel);
+    if (parsed === undefined)
+        return [];
+    const pricing = opts.pricing ?? DEFAULT_PRICING;
+    const candidates = enumerateCandidates(parsed, {
+        pricing,
+        sameProviderOnly: true,
+        excludeCurrent: true,
+        excludeSunsets: true,
+    });
+    const limit = opts.limit ?? 3;
+    return candidates.slice(0, limit).map((c) => ({
+        modelString: c.modelString,
+        blendedPer1M: c.blendedPer1M,
+    }));
+}
+/**
+ * Run the TTFT probe: build the human-readable report + the exit code. Pure —
+ * the CLI reads the files and owns `process.exit`. Precedence: durable
+ * sessions.jsonl first (the alert-watchdog's own history), then the histogram
+ * fallback. No target ⇒ exit 0 with a "nothing declared" note; no data ⇒ exit 0
+ * (a HEALTHCHECK must not flap on a store that has not accrued history yet).
+ */
+export function runSloProbe(input) {
+    const lines = [];
+    if (input.ttftTargetMs === undefined) {
+        lines.push("~ SLO ttft: no observability.slo.ttft_ms declared in the cwd spec — nothing to probe");
+        return { exitCode: 0, lines };
+    }
+    let observedMs = recentTtftP95Ms(input.sessionsJsonl);
+    let source = ".crewhaus/metrics/sessions.jsonl";
+    if (observedMs === undefined && input.histogram !== undefined) {
+        observedMs = percentileFromHistogram(input.histogram, 0.95) * 1000;
+        source = "metrics histogram (model_ttft_seconds)";
+    }
+    if (observedMs === undefined) {
+        lines.push("~ SLO ttft: no recent TTFT history yet (run the agent a few times so `.crewhaus/metrics/sessions.jsonl` accrues) — probe skipped");
+        return { exitCode: 0, lines };
+    }
+    const target = input.ttftTargetMs;
+    const within = observedMs <= target;
+    const fmt = (n) => `${Math.round(n)}ms`;
+    if (within) {
+        lines.push(`✓ SLO ttft: p95 ${fmt(observedMs)} within target ${fmt(target)} (source: ${source})`);
+        return { exitCode: 0, lines };
+    }
+    lines.push(`✗ SLO ttft: p95 ${fmt(observedMs)} exceeds target ${fmt(target)} (source: ${source})`);
+    const candidates = input.currentModel !== undefined
+        ? nameFasterCandidates(input.currentModel, {
+            ...(input.pricing !== undefined ? { pricing: input.pricing } : {}),
+        })
+        : [];
+    if (candidates.length > 0) {
+        const list = candidates.map((c) => c.modelString).join(",");
+        lines.push(`  faster candidates (cheaper ⇒ smaller ⇒ lower TTFT, same provider): ${list}`);
+        lines.push(`  confirm the swap holds quality: crewhaus eval --models ${input.currentModel},${list}`);
+    }
+    else if (input.currentModel !== undefined) {
+        lines.push(`  no table-backed faster candidates for ${input.currentModel} (local/named-host model) — measure alternatives with crewhaus eval --models <m1,m2>`);
+    }
+    return { exitCode: 1, lines };
+}

package/dist/slo-sink.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Ops item 37 — construct the `SloMitigationSink` the runtime SLO monitor walks
+ * on a sustained breach. Three ladder rungs beyond the trace event, all
+ * best-effort + injected so this entry-file module stays testable and no
+ * deploy/gateway/audit I/O happens at import time:
+ *
+ *   - `audit`       → a tamper-evident `slo_mitigation` record on the
+ *                     hash-chained audit log (so the mitigation history is
+ *                     itself auditable), for EVERY attempted rung;
+ *   - `alert`       → reuses the same delivery the alert watchdog builds
+ *                     (settings.json `alert` hook + webhook POST) — an SLO
+ *                     breach is an alert;
+ *   - `pauseIntake` → flips a durable intake gate (`.crewhaus/slo/intake.json`
+ *                     `{ paused: true }`) that the gateway/managed daemon reads
+ *                     to send new requests down the 429 `budget_exceeded` path;
+ *                     the SAME writer is invoked with `paused:false` (resume)
+ *                     when the breach clears, so admission re-opens without
+ *                     operator intervention;
+ *   - `rollback`    → auto-rollback the env pin to the LAST-KNOWN-GOOD version —
+ *                     the version that was pinned to the env immediately before
+ *                     the current one, read from the `deployment_action` audit
+ *                     history (see {@link lastKnownGoodFromAuditRecords}), NOT a
+ *                     lexicographic guess — via the injected deployment-controller.
+ *
+ * Side-effect-free + injected (audit log, alert delivery, intake writer, rollback
+ * closure) mirroring `alert-sink.ts`. The CLI `run` path wires the real
+ * `openAuditLog`, the reused alert sink, an fs-backed intake writer, and a
+ * deployment-controller `rollback` when a spec-registry + `slo.rollback` target
+ * are present.
+ */
+import type { SloMitigationEvent, SloMitigationSink } from "@crewhaus/runtime-core";
+/** Minimal audit seam — structurally satisfied by `@crewhaus/audit-log`. */
+export type SloAuditSink = {
+    append(input: {
+        readonly kind: "slo_mitigation";
+        readonly payload: unknown;
+    }): Promise<unknown>;
+};
+/** The intake-gate writer seam. Flips a durable pause flag the daemon reads.
+ *  Called with `paused:true` on the `pause-intake` rung and `paused:false` when
+ *  the breach clears (resume), so the gate can honestly re-open admission. */
+export type IntakeGateWriter = (paused: boolean, reason: string) => Promise<void>;
+/** The rollback seam — a deployment-controller `rollback` closure bound to the
+ *  harness name + env + last-known-good version. */
+export type SloRollback = (event: SloMitigationEvent) => Promise<void>;
+/** The alert-delivery seam — reuses the alert watchdog's fireAlertHook shape. */
+export type SloAlertDelivery = (event: SloMitigationEvent) => Promise<void>;
+export type BuildSloSinkOptions = {
+    /** Durable audit log (undefined ⇒ no audit records). */
+    readonly audit?: SloAuditSink;
+    /** Alert delivery (undefined ⇒ the `alert` rung is a no-op, still audited). */
+    readonly alert?: SloAlertDelivery;
+    /** Intake-gate writer (undefined ⇒ the `pause-intake` rung is a no-op). */
+    readonly pauseIntake?: IntakeGateWriter;
+    /** Rollback closure (undefined ⇒ the `rollback` rung is a no-op). */
+    readonly rollback?: SloRollback;
+    /** Warn sink for best-effort failures (defaults to stderr). */
+    readonly warn?: (line: string) => void;
+};
+/**
+ * Build the `SloMitigationSink`, or `undefined` when NO channel is configured
+ * (the caller then spreads nothing and the monitor keeps only its trace-event
+ * behaviour). Every rung is best-effort: a failure is warned, never thrown — a
+ * mitigation-delivery hiccup must not fail a run (the monitor's own catch also
+ * guards this, but a double floor is cheap).
+ */
+export declare function buildSloSink(opts: BuildSloSinkOptions): SloMitigationSink | undefined;
+/** The on-disk intake-gate shape read by the gateway/managed daemon. Paused
+ *  ⇒ new requests get the 429 `budget_exceeded` path until an operator clears
+ *  the flag (`crewhaus ... ` or by deleting the file). */
+export type IntakeGateFile = {
+    readonly version: 1;
+    readonly paused: boolean;
+    readonly reason?: string;
+    readonly ts: number;
+};
+/** Build the JSON payload for the durable intake gate (pure — the caller owns
+ *  the write). Kept next to the reader shape so the two can't drift. */
+export declare function intakeGatePayload(paused: boolean, reason: string, now?: number): IntakeGateFile;
+/**
+ * Resolve the LAST-KNOWN-GOOD version to roll `name`'s `env` pin back to, from
+ * the `deployment_action` audit history — the actual version that was pinned to
+ * `env` immediately BEFORE `current`, never a lexicographic guess.
+ *
+ * The predecessor is the `fromVersion` of the most recent `deployment_action`
+ * that set `env` to `current` (a promote with `toEnv === env` OR a rollback with
+ * `env === env`, in both cases `toVersion === current`). Records are consulted
+ * newest-first by `ts` so an env that flip-flopped (v1 → v9 → v1 → v9) rolls
+ * back to whatever was live just before THIS pin, not an ancient one.
+ *
+ * Returns `undefined` when the history reveals no distinct predecessor (e.g. the
+ * env was pinned once via a raw `spec pin`, or the recorded predecessor equals
+ * `current`). The caller MUST treat `undefined` as "cannot safely roll back —
+ * skip", never fall back to a lexicographic pick.
+ */
+export declare function lastKnownGoodFromAuditRecords(records: ReadonlyArray<unknown>, name: string, env: string, current: string | undefined): string | undefined;

package/dist/slo-sink.js

@@ -0,0 +1,107 @@
+/**
+ * Build the `SloMitigationSink`, or `undefined` when NO channel is configured
+ * (the caller then spreads nothing and the monitor keeps only its trace-event
+ * behaviour). Every rung is best-effort: a failure is warned, never thrown — a
+ * mitigation-delivery hiccup must not fail a run (the monitor's own catch also
+ * guards this, but a double floor is cheap).
+ */
+export function buildSloSink(opts) {
+    const hasAny = opts.audit !== undefined ||
+        opts.alert !== undefined ||
+        opts.pauseIntake !== undefined ||
+        opts.rollback !== undefined;
+    if (!hasAny)
+        return undefined;
+    const warn = opts.warn ?? ((line) => process.stderr.write(`${line}\n`));
+    const sink = {};
+    if (opts.audit !== undefined) {
+        sink.audit = async (event) => {
+            await opts.audit?.append({ kind: "slo_mitigation", payload: event }).catch((err) => {
+                warn(`[slo] audit failed: ${err instanceof Error ? err.message : String(err)}`);
+            });
+        };
+    }
+    if (opts.alert !== undefined) {
+        sink.alert = async (event) => {
+            await opts.alert?.(event).catch((err) => {
+                warn(`[slo] alert failed: ${err instanceof Error ? err.message : String(err)}`);
+            });
+        };
+    }
+    if (opts.pauseIntake !== undefined) {
+        sink.pauseIntake = async (event) => {
+            await opts.pauseIntake?.(true, `SLO breach: ${event.breach.detail}`).catch((err) => {
+                warn(`[slo] pause-intake failed: ${err instanceof Error ? err.message : String(err)}`);
+            });
+        };
+        // Resume is the SAME durable gate flipped back to `paused:false` when the
+        // breach clears, so admission re-opens without operator intervention.
+        sink.resumeIntake = async (event) => {
+            await opts.pauseIntake?.(false, `SLO recovered: ${event.breach.detail}`).catch((err) => {
+                warn(`[slo] resume-intake failed: ${err instanceof Error ? err.message : String(err)}`);
+            });
+        };
+    }
+    if (opts.rollback !== undefined) {
+        sink.rollback = async (event) => {
+            await opts.rollback?.(event).catch((err) => {
+                warn(`[slo] rollback failed: ${err instanceof Error ? err.message : String(err)}`);
+            });
+        };
+    }
+    return sink;
+}
+/** Build the JSON payload for the durable intake gate (pure — the caller owns
+ *  the write). Kept next to the reader shape so the two can't drift. */
+export function intakeGatePayload(paused, reason, now = Date.now()) {
+    return { version: 1, paused, ...(reason !== "" ? { reason } : {}), ts: now };
+}
+/**
+ * Resolve the LAST-KNOWN-GOOD version to roll `name`'s `env` pin back to, from
+ * the `deployment_action` audit history — the actual version that was pinned to
+ * `env` immediately BEFORE `current`, never a lexicographic guess.
+ *
+ * The predecessor is the `fromVersion` of the most recent `deployment_action`
+ * that set `env` to `current` (a promote with `toEnv === env` OR a rollback with
+ * `env === env`, in both cases `toVersion === current`). Records are consulted
+ * newest-first by `ts` so an env that flip-flopped (v1 → v9 → v1 → v9) rolls
+ * back to whatever was live just before THIS pin, not an ancient one.
+ *
+ * Returns `undefined` when the history reveals no distinct predecessor (e.g. the
+ * env was pinned once via a raw `spec pin`, or the recorded predecessor equals
+ * `current`). The caller MUST treat `undefined` as "cannot safely roll back —
+ * skip", never fall back to a lexicographic pick.
+ */
+export function lastKnownGoodFromAuditRecords(records, name, env, current) {
+    let best;
+    for (const raw of records) {
+        if (raw === null || typeof raw !== "object")
+            continue;
+        const rec = raw;
+        if (rec.kind !== "deployment_action")
+            continue;
+        const p = rec.payload;
+        if (p === null || typeof p !== "object")
+            continue;
+        const payload = p;
+        if (payload.name !== name)
+            continue;
+        // The env this action targeted: promote → toEnv, rollback → env.
+        const targetEnv = payload.action === "promote" ? payload.toEnv : payload.env;
+        if (targetEnv !== env)
+            continue;
+        // Only actions that produced the CURRENT pin tell us its predecessor. When
+        // `current` is unknown (no live pin), any prior good pin for the env works,
+        // so accept the newest action's fromVersion.
+        if (current !== undefined && payload.toVersion !== current)
+            continue;
+        const from = payload.fromVersion;
+        if (typeof from !== "string" || from === "" || from === current)
+            continue;
+        // Prefer the record with the LATEST timestamp (payload.ts, else record ts).
+        const ts = typeof payload.ts === "number" ? payload.ts : (rec.ts ?? 0);
+        if (best === undefined || ts >= best.ts)
+            best = { fromVersion: from, ts };
+    }
+    return best?.fromVersion;
+}

package/dist/spec-changelog.d.ts

@@ -0,0 +1,102 @@
+import { type WriteBackHeaderInfo } from "@crewhaus/spec-patch";
+import type { RegistryAdapter } from "@crewhaus/spec-registry";
+/** The per-spec changelog file, beside the registry's `manifest.json`. */
+export declare const CHANGELOG_FILE = "CHANGELOG.md";
+/**
+ * Map a spec's display name (spec `safeName`: letters, digits, spaces,
+ * `_ . - :`) onto the registry's stricter name grammar: runs of characters
+ * outside `[A-Za-z0-9_.-]` collapse to a single `-`, leading dots are
+ * stripped (the registry hides dot-dirs), and an empty result falls back to
+ * `"spec"`. Deterministic, so the same spec always lands in the same slot.
+ */
+export declare function registrySpecName(specName: string): string;
+/** SHA-256 hex of the exact YAML text (the registry stores bytes verbatim). */
+export declare function contentHash(yaml: string): string;
+/**
+ * Next auto-version: `v<max+1>` over the existing `v<N>` versions (manifest
+ * order, numeric — `v10` beats `v2`). Manually-put versions that don't match
+ * `v<N>` (e.g. `2.0`, `release-1`) are ignored for numbering.
+ */
+export declare function nextVersion(existing: ReadonlyArray<string>): string;
+/**
+ * Optimizer provenance for a changelog entry: the write-back header fields
+ * plus the `rationale` string the optimizer stored in that run's
+ * `patch.json` (the SpecPatch field documented as existing "for audit /
+ * write-back commit messages" — this is where it finally surfaces).
+ */
+export type OptimizeMetadata = WriteBackHeaderInfo & {
+    readonly rationale?: string;
+};
+export type ExtractOptimizeMetadataOptions = {
+    /** The YAML being registered (its leading comment block is scanned). */
+    readonly yaml: string;
+    /** Root of the optimizer run dirs (`.crewhaus/optimize`) for `<runId>/patch.json` lookup. */
+    readonly optimizeRootDir?: string | undefined;
+    /** Explicit patch.json path — the optimize --write-back hook knows its own out-dir (which `-o` may relocate). */
+    readonly patchJsonPath?: string | undefined;
+};
+/**
+ * When the YAML carries a `formatWriteBackHeader` stamp, recover the run
+ * metadata and — if that run's `patch.json` is readable — its `rationale`.
+ * Returns `undefined` for content that was never written back. Never throws:
+ * provenance is best-effort garnish on the changelog, not a gate.
+ */
+export declare function extractOptimizeMetadata(opts: ExtractOptimizeMetadataOptions): OptimizeMetadata | undefined;
+export type ChangelogEntryOptions = {
+    readonly version: string;
+    readonly yaml: string;
+    /** The previous version's YAML; omit for a spec's first version. */
+    readonly previousYaml?: string | undefined;
+    readonly optimizeRootDir?: string | undefined;
+    readonly patchJsonPath?: string | undefined;
+    /** Injectable clock for deterministic tests. */
+    readonly now?: Date | undefined;
+};
+/**
+ * Render one changelog entry (pure): `## <version> — <date>` followed by
+ * the field-level diff bullets vs the previous version (or `initial
+ * version`) and, when present, the optimizer provenance + rationale.
+ */
+export declare function renderChangelogEntry(opts: ChangelogEntryOptions): string;
+/**
+ * Insert an entry into a changelog text, NEWEST FIRST (pure): the new entry
+ * lands above the previous top `## ` heading, under the `# Changelog — …`
+ * title. `crewhaus spec log` can therefore print the file verbatim and read
+ * most-recent-first.
+ */
+export declare function insertNewestFirst(existing: string, name: string, entry: string): string;
+export type AppendChangelogOptions = ChangelogEntryOptions & {
+    /** Registry root (`.crewhaus/specs`) — the changelog lives beside `<name>/manifest.json`. */
+    readonly registryRootDir: string;
+    /** Registry-grammar spec name (already sanitized/validated by the caller's `put`). */
+    readonly name: string;
+};
+/**
+ * Append (newest-first) one entry to `<registryRoot>/<name>/CHANGELOG.md`,
+ * creating the file with its title on first use. Returns the file path.
+ */
+export declare function appendChangelogEntry(opts: AppendChangelogOptions): string;
+export type AutoRegisterOptions = {
+    readonly registry: RegistryAdapter;
+    readonly registryRootDir: string;
+    /** The spec's display name straight from the YAML (sanitized internally). */
+    readonly specName: string;
+    /** The exact YAML text to register (including any write-back header). */
+    readonly yaml: string;
+    readonly optimizeRootDir?: string | undefined;
+    readonly patchJsonPath?: string | undefined;
+    readonly now?: Date | undefined;
+};
+export type AutoRegisterResult = {
+    readonly status: "registered" | "unchanged";
+    /** The registry-grammar name the spec landed under. */
+    readonly name: string;
+    readonly version: string;
+};
+/**
+ * Content-hash gated auto-put: when some stored version already carries this
+ * exact content, report `unchanged` (with that version); otherwise `put` the
+ * next `vN` and append the distilled changelog entry. The previous-latest
+ * version (manifest order) is the diff baseline.
+ */
+export declare function autoRegisterSpecVersion(opts: AutoRegisterOptions): Promise<AutoRegisterResult>;