@gobing-ai/knowledge-kit 0.0.29 → 0.0.30

package/plugins/sp/scripts/history-anatomy-cache.mjs

@@ -1,902 +0,0 @@
-#!/usr/bin/env node
-import { createRequire } from 'node:module';
-
-var __require = /* @__PURE__ */ createRequire(import.meta.url);
-
-// plugins/sp/scripts/history-anatomy-cache.ts
-import { spawnSync } from 'node:child_process';
-// plugins/sp/lib/artifact-digest.generated.mjs
-import { createHash, createHash as createHash2 } from 'node:crypto';
-import {
-    closeSync,
-    existsSync,
-    fsyncSync,
-    openSync,
-    readdirSync,
-    readFileSync,
-    renameSync,
-    rmSync,
-    statSync,
-    writeFileSync,
-} from 'node:fs';
-import { join } from 'node:path';
-
-var ARTIFACT_ARRAY_CLASSIFICATION = {
-    byTool: 'ranked',
-    bySession: 'ranked',
-    topStepsByTokens: 'ranked',
-    topStepsByDuration: 'ranked',
-    topSteps: 'ranked',
-    bottlenecks: 'ranked',
-    coverage: 'set',
-    daily: 'set',
-    loops: 'set',
-    warnings: 'set',
-    pairings: 'set',
-    ladderSnapshot: 'set',
-    stepSupport: 'set',
-    phases: 'set',
-    tools: 'set',
-    skills: 'set',
-    sources: 'set',
-    models: 'set',
-};
-var RANKED_ARTIFACT_KEYS = new Set(
-    Object.entries(ARTIFACT_ARRAY_CLASSIFICATION)
-        .filter(([, kind]) => kind === 'ranked')
-        .map(([key]) => key),
-);
-function canonicalize(value, key) {
-    if (key === 'generatedAt' || key === 'validatedAt' || key === 'baselineArtifactDigest') return null;
-    if (Array.isArray(value)) {
-        const raw = value.map((v) => JSON.stringify(canonicalize(v, '')));
-        return RANKED_ARTIFACT_KEYS.has(key) ? raw : [...raw].sort();
-    }
-    if (value !== null && typeof value === 'object') {
-        const out = {};
-        for (const k of Object.keys(value).sort()) {
-            out[k] = canonicalize(value[k], k);
-        }
-        return out;
-    }
-    return value;
-}
-function semanticArtifactDigest(artifactJson) {
-    const material = JSON.stringify(canonicalize(artifactJson, 'root'));
-    return createHash('sha256').update(material).digest('hex');
-}
-
-// plugins/sp/scripts/history-anatomy-cache.ts
-var REPORT_SECTIONS = [
-    'Scope and provenance',
-    'Executive summary',
-    'Baseline comparison',
-    'Findings',
-    'Recurrence ledger',
-    'Telemetry gaps',
-    'Remediation options',
-    'Performance analysis',
-    'Workflow and process improvements',
-    'Report-only advisories',
-    'Positive patterns',
-    'Evidence ledger',
-];
-var FINDING_FIELDS = [
-    'key',
-    'category',
-    'impact',
-    'trend',
-    'observation',
-    'inference',
-    'confidence',
-    'contradictions',
-    'evidenceAnchor',
-    'severity',
-    'reproCommand',
-    'ownerSurface',
-];
-function parseScalar(raw) {
-    const t = raw.trim();
-    if (t.startsWith('"') && t.endsWith('"')) return t.slice(1, -1).replaceAll('\\"', '"');
-    if (t === 'null') return null;
-    return t;
-}
-function parseBlock(text) {
-    const obj = {};
-    const lines = text.split(`
-`);
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i] ?? '';
-        if (/^\s*$/.test(line) || /^\s*#/.test(line) || /^-\s+/.test(line.trim())) continue;
-        const indent = line.search(/\S/);
-        const eq = line.indexOf(':');
-        if (eq === -1) continue;
-        const key = line.slice(0, eq).trim();
-        const val = parseScalar(line.slice(eq + 1).trim());
-        let consumed = 0;
-        const next = lines[i + 1];
-        if ((val === '' || val === undefined) && /^\s*-\s+/.test(next ?? '')) {
-            const items = [];
-            let j = i + 1;
-            while (j < lines.length && /^\s*-\s+/.test(lines[j] ?? '')) {
-                const entry = {};
-                for (const part of (lines[j] ?? '').trim().replace(/^-\s+/, '').split(',')) {
-                    const e = part.indexOf(':');
-                    if (e === -1) continue;
-                    entry[part.slice(0, e).trim()] = parseScalar(part.slice(e + 1).trim());
-                }
-                items.push(entry);
-                j++;
-            }
-            obj[key] = items;
-            consumed = j - i - 1;
-        } else if (val === '' || val === undefined) {
-            const block = [];
-            let j = i + 1;
-            while (j < lines.length) {
-                const nl = lines[j] ?? '';
-                if (nl.trim() === '') {
-                    block.push('');
-                    j++;
-                    continue;
-                }
-                const nind = nl.search(/\S/);
-                if (nind <= indent) break;
-                block.push(nl);
-                j++;
-            }
-            obj[key] = parseBlock(
-                block.join(`
-`),
-            );
-            consumed = j - i - 1;
-        } else {
-            obj[key] = val;
-        }
-        i += consumed;
-    }
-    return obj;
-}
-function readSourceName(s) {
-    if (s !== null && typeof s === 'object') return String(s.source ?? '');
-    return String(s);
-}
-var DISPOSITIONS = ['hit', 'miss', 'forced-recompute'];
-function optionalString(v) {
-    return v == null || v === '' ? undefined : String(v);
-}
-function parseProvenance(reportMarkdown) {
-    const match = reportMarkdown.match(/^---\n([\s\S]*?)\n---/);
-    if (match === null) return null;
-    try {
-        const obj = parseBlock(match[1] ?? '');
-        const identity = obj.identity;
-        const coverage = obj.coverage;
-        if (identity === undefined || !Array.isArray(coverage)) return null;
-        const bounds = identity.bounds;
-        if (bounds === undefined || typeof bounds.since !== 'string' || typeof bounds.until !== 'string') {
-            return null;
-        }
-        return {
-            identity: {
-                contractVersion: String(identity.contractVersion ?? ''),
-                mode: identity.mode === 'ad-hoc' ? 'ad-hoc' : 'daily',
-                date: String(identity.date ?? ''),
-                timezone: String(identity.timezone ?? ''),
-                bounds: { since: bounds.since, until: bounds.until },
-                sources: Array.isArray(identity.sources) ? identity.sources.map(readSourceName) : [],
-            },
-            windowState: obj.windowState === 'closed' ? 'closed' : 'provisional',
-            generatedAt: String(obj.generatedAt ?? ''),
-            validatedAt: String(obj.validatedAt ?? ''),
-            artifactDigest: String(obj.artifactDigest ?? ''),
-            baselineArtifactDigest: obj.baselineArtifactDigest == null ? null : String(obj.baselineArtifactDigest),
-            contractDigest: String(obj.contractDigest ?? ''),
-            skillDigest: String(obj.skillDigest ?? ''),
-            workflowDigest: String(obj.workflowDigest ?? ''),
-            helperDigest: String(obj.helperDigest ?? ''),
-            coverage: coverage.map((c) => ({
-                source: String(c.source ?? ''),
-                status: String(c.status ?? ''),
-                lastImportedAt: c.lastImportedAt == null ? null : String(c.lastImportedAt),
-            })),
-            runId: optionalString(obj.runId),
-            currentArtifactPath: optionalString(obj.currentArtifactPath),
-            baselineArtifactPath: obj.baselineArtifactPath == null ? null : String(obj.baselineArtifactPath),
-            spurVersion: optionalString(obj.spurVersion),
-            schemaVersion: obj.schemaVersion == null ? undefined : Number(obj.schemaVersion),
-            executor: optionalString(obj.executor),
-            model: optionalString(obj.model),
-            cacheDisposition: DISPOSITIONS.includes(obj.cacheDisposition) ? obj.cacheDisposition : undefined,
-        };
-    } catch {
-        return null;
-    }
-}
-function decideCache(cached, current, opts) {
-    if (opts.recompute) return { disposition: 'forced-recompute', reasons: ['recompute'] };
-    if (cached === null) return { disposition: 'miss', reasons: ['no-cache'] };
-    const reasons = [];
-    const id = cached.identity;
-    const cur = current.identity;
-    if (id.contractVersion !== cur.contractVersion) reasons.push('identity:contractVersion');
-    if (id.mode !== cur.mode) reasons.push('identity:mode');
-    if (id.date !== cur.date) reasons.push('identity:date');
-    if (id.timezone !== cur.timezone) reasons.push('identity:timezone');
-    if (id.bounds.since !== cur.bounds.since || id.bounds.until !== cur.bounds.until) reasons.push('identity:bounds');
-    if ([...id.sources].sort().join('\x00') !== [...cur.sources].sort().join('\x00')) reasons.push('identity:sources');
-    if (cached.artifactDigest !== current.artifactDigest) reasons.push('data-changed');
-    if (cached.contractDigest !== current.contractDigest) reasons.push('logic-changed:contract');
-    if (cached.skillDigest !== current.skillDigest) reasons.push('logic-changed:skill');
-    if (cached.workflowDigest !== current.workflowDigest) reasons.push('logic-changed:workflow');
-    if (cached.helperDigest !== current.helperDigest) reasons.push('logic-changed:helper');
-    const currentSources = new Set(current.coverage.map((c) => c.source));
-    if (cached.coverage.some((c) => !currentSources.has(c.source))) reasons.push('coverage-degraded');
-    if (cached.windowState === 'provisional' && opts.dayClosed) reasons.push('window-closed');
-    return { disposition: reasons.length === 0 ? 'hit' : 'miss', reasons };
-}
-function escapeRe(s) {
-    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-var FINDING_CATEGORIES = ['reliability', 'repetition', 'workflow', 'performance', 'coverage', 'telemetry', 'positive'];
-function checkReportStructure(reportMarkdown) {
-    const problems = [];
-    if (/TODO|PLACEHOLDER|FIXME|^\|\s*\|/im.test(reportMarkdown)) problems.push('placeholder-or-todo-present');
-    let lastIdx = -1;
-    for (const section of REPORT_SECTIONS) {
-        const re = new RegExp(`^#{2,3}\\s+${escapeRe(section)}\\s*$`, 'm');
-        const m = reportMarkdown.match(re);
-        if (m === null || (m.index ?? -1) <= lastIdx) {
-            problems.push(`section-missing-or-out-of-order:${section}`);
-        } else if (m.index !== undefined) {
-            lastIdx = m.index;
-        }
-    }
-    const findingsIdx = reportMarkdown.search(/^##\s+Findings\s*$/im);
-    if (findingsIdx !== -1) {
-        const tail = reportMarkdown.slice(findingsIdx);
-        const nextSection = tail.slice(1).search(/^##\s+/im);
-        const findingsBody = nextSection === -1 ? tail : tail.slice(0, nextSection + 1);
-        const catAlt = FINDING_CATEGORIES.join('|');
-        const knownRows = findingsBody.match(new RegExp(`^\\|\\s*(?:${catAlt}):[^|]+`, 'gm')) ?? [];
-        const invalidRows = findingsBody.match(/^\|\s*([^|:\s][^|:]*):[^|]+/gm) ?? [];
-        for (const row of [...new Set([...knownRows, ...invalidRows])]) {
-            const segMatch = row.match(/^\|\s*([^:|]+):/);
-            if (segMatch && !FINDING_CATEGORIES.includes(segMatch[1].trim())) {
-                problems.push(`finding-invalid-key-category:${segMatch[1].trim()}`);
-            }
-            const rowLower = row.toLowerCase();
-            for (const field of FINDING_FIELDS) {
-                if (!rowLower.includes(field.toLowerCase())) problems.push(`finding-missing-field:${field}`);
-            }
-        }
-        const blocks = findingsBody.split(/^###\s+/m).slice(1);
-        for (const block of blocks) {
-            if (!block.includes('`key`') && !/\|\s*key\s*:/.test(block)) continue;
-            for (const field of FINDING_FIELDS) {
-                if (!block.includes(field)) problems.push(`finding-missing-field:${field}`);
-            }
-            if (!/(^|[\s`])P[123]([\s`.]|$)/.test(block) && !block.includes('symbolic-severity')) {
-                problems.push('finding-invalid-severity');
-            }
-            const catValue = block.match(/`category`\s*[:=]\s*`?([^`\n]+?)`?\s*(?:\n|$)/)?.[1];
-            if (catValue && !FINDING_CATEGORIES.includes(catValue.trim())) {
-                problems.push(`finding-invalid-category:${catValue.trim()}`);
-            }
-            const keyValue = block.match(/`key`\s*[:=]\s*`?([^`\n]+?)`?\s*(?:\n|$)/)?.[1] ?? '';
-            const firstSegment = keyValue.split(':')[0]?.trim() ?? '';
-            if (keyValue !== '' && !FINDING_CATEGORIES.includes(firstSegment)) {
-                problems.push(`finding-invalid-key-category:${firstSegment}`);
-            }
-        }
-    }
-    const ledgerIdx = reportMarkdown.search(/^#{2,3}\s+Evidence\s+ledger/im);
-    if (ledgerIdx !== -1) {
-        const ledgerSection = reportMarkdown.slice(ledgerIdx);
-        const sep = ledgerSection.match(/^\|[\s:|-]+\|[ \t]*$/m);
-        const body = sep?.index === undefined ? ledgerSection : ledgerSection.slice(sep.index + sep[0].length);
-        const claimRows = body.match(/^[|>]\s+\S.*$/gm) ?? [];
-        for (const row of claimRows) {
-            const hasAnchor = /`[^`]+:\d+`|`[^`]+\.(md|ts|json)`|[a-z][a-z0-9_-]*\/[a-z][a-z0-9_./-]*:[0-9]+/i.test(
-                row,
-            );
-            if (!hasAnchor) {
-                problems.push('evidence-claim-without-anchor');
-                break;
-            }
-        }
-    }
-    return { ok: problems.length === 0, problems };
-}
-var NOT_AVAILABLE = 'not available';
-function logicDigest(path) {
-    if (path === undefined || path === '' || !existsSync(path)) return NOT_AVAILABLE;
-    try {
-        const h = createHash2('sha256');
-        if (statSync(path).isDirectory()) {
-            const walk = (dir) =>
-                readdirSync(dir, { withFileTypes: true })
-                    .flatMap((e) =>
-                        e.isDirectory()
-                            ? walk(join(dir, e.name))
-                            : /\.(md|ya?ml)$/.test(e.name)
-                              ? [join(dir, e.name)]
-                              : [],
-                    )
-                    .sort();
-            for (const f of walk(path)) {
-                h.update(f.slice(path.length));
-                h.update(readFileSync(f));
-            }
-        } else {
-            h.update(readFileSync(path));
-        }
-        return h.digest('hex');
-    } catch {
-        return NOT_AVAILABLE;
-    }
-}
-function importedSnapshotAsOf(coverage) {
-    const stamps = coverage.map((c) => c.lastImportedAt).filter((v) => typeof v === 'string' && v !== '');
-    if (stamps.length === 0 || stamps.length !== coverage.length) return NOT_AVAILABLE;
-    return [...stamps].sort()[0] ?? NOT_AVAILABLE;
-}
-function localDay(tz, at = new Date()) {
-    try {
-        return new Intl.DateTimeFormat('en-CA', { timeZone: tz, dateStyle: 'short' }).format(at);
-    } catch {
-        return at.toISOString().slice(0, 10);
-    }
-}
-function tzOffsetMs(tz, at) {
-    const parts = Object.fromEntries(
-        new Intl.DateTimeFormat('en-US', {
-            timeZone: tz,
-            hour12: false,
-            year: 'numeric',
-            month: '2-digit',
-            day: '2-digit',
-            hour: '2-digit',
-            minute: '2-digit',
-            second: '2-digit',
-        })
-            .formatToParts(at)
-            .filter((p) => p.type !== 'literal')
-            .map((p) => [p.type, p.value]),
-    );
-    const asUtc = Date.UTC(
-        Number(parts.year),
-        Number(parts.month) - 1,
-        Number(parts.day),
-        parts.hour === '24' ? 0 : Number(parts.hour),
-        Number(parts.minute),
-        Number(parts.second),
-    );
-    const atSec = Math.floor(at.getTime() / 1000) * 1000;
-    return asUtc - atSec;
-}
-function zonedDayStart(tz, ymd) {
-    const [y, m, d] = ymd.split('-').map(Number);
-    const utcMidnight = Date.UTC(y ?? 1970, (m ?? 1) - 1, d ?? 1);
-    const guess = new Date(utcMidnight - tzOffsetMs(tz, new Date(utcMidnight)));
-    return new Date(utcMidnight - tzOffsetMs(tz, guess));
-}
-function formatZonedIso(tz, at) {
-    const off = tzOffsetMs(tz, at);
-    const abs = Math.abs(off);
-    const pad = (n) => String(n).padStart(2, '0');
-    const offStr = `${off < 0 ? '-' : '+'}${pad(Math.floor(abs / 3600000))}:${pad(Math.floor((abs % 3600000) / 60000))}`;
-    return `${new Date(at.getTime() + off).toISOString().slice(0, 23)}${offStr}`;
-}
-function dayBounds(tz, ymd) {
-    const start = zonedDayStart(tz, ymd);
-    const nextYmd = localDay(tz, new Date(start.getTime() + 30 * 3600000));
-    return {
-        since: formatZonedIso(tz, start),
-        until: formatZonedIso(tz, new Date(zonedDayStart(tz, nextYmd).getTime() - 1)),
-    };
-}
-function resolvePaths(opts) {
-    const m = opts.helper.match(/\/scripts\/(?:([^/]+)\/)?[^/]+$/);
-    const pluginRoot = m ? opts.helper.slice(0, m.index) : opts.helper;
-    const skill = `${pluginRoot}/skills/${m?.[1] ? `${m[1]}-history-anatomy` : 'history-anatomy'}`;
-    const tz = opts.tz ?? Intl.DateTimeFormat().resolvedOptions().timeZone ?? 'UTC';
-    const date = opts.date !== undefined && opts.date !== '' ? opts.date : localDay(tz, opts.now ?? new Date());
-    const target =
-        opts.output !== undefined && opts.output !== '' ? opts.output : `${opts.reportDir}/${date}-history-anatomy.md`;
-    const adHoc = opts.mode === 'ad-hoc' && !!opts.since && !!opts.until;
-    let env = `HA_HELPER=${opts.helper}
-HA_SKILL=${skill}
-HA_TARGET=${target}
-HA_DATE=${date}
-`;
-    if (adHoc) {
-        return `${env}HA_SINCE=${opts.since}
-HA_UNTIL=${opts.until}
-`;
-    }
-    const current = dayBounds(tz, date);
-    const baseline = dayBounds(tz, localDay(tz, new Date(zonedDayStart(tz, date).getTime() - 12 * 3600000)));
-    env += `HA_SINCE=${current.since}
-HA_UNTIL=${current.until}
-`;
-    env += `HA_BASELINE_SINCE=${baseline.since}
-HA_BASELINE_UNTIL=${baseline.until}
-`;
-    return env;
-}
-function buildProvenance(opts) {
-    let raw;
-    try {
-        raw = JSON.parse(readFileSync(opts.artifact, 'utf8'));
-    } catch (err) {
-        throw new Error(`could not parse fresh analyze artifact at ${opts.artifact}: ${err.message}`);
-    }
-    const coverage = (raw.coverage ?? []).map((c) => ({
-        source: String(c.source ?? ''),
-        status: String(c.status ?? ''),
-        lastImportedAt: c.lastImportedAt == null ? null : String(c.lastImportedAt),
-    }));
-    const tz = Intl.DateTimeFormat().resolvedOptions().timeZone ?? 'UTC';
-    const now = opts.now ?? new Date();
-    const date = opts.date !== undefined && opts.date !== '' ? opts.date : localDay(tz, now);
-    const windowState = opts.mode === 'ad-hoc' || date < localDay(tz, now) ? 'closed' : 'provisional';
-    const nowIso = now.toISOString();
-    return {
-        identity: {
-            contractVersion: opts.contractVersion ?? '1',
-            mode: opts.mode,
-            date,
-            timezone: tz,
-            bounds: { since: String(raw.selector?.since ?? ''), until: String(raw.selector?.until ?? '') },
-            sources: coverage.map((c) => c.source).sort(),
-        },
-        windowState,
-        generatedAt: nowIso,
-        validatedAt: nowIso,
-        artifactDigest: semanticArtifactDigest(raw),
-        baselineArtifactDigest: (() => {
-            if (!(opts.baseline !== undefined && existsSync(opts.baseline))) return null;
-            try {
-                return semanticArtifactDigest(JSON.parse(readFileSync(opts.baseline, 'utf8')));
-            } catch (err) {
-                throw new Error(`could not parse baseline artifact at ${opts.baseline}: ${err.message}`);
-            }
-        })(),
-        contractDigest: logicDigest(opts.contractFile),
-        skillDigest: logicDigest(opts.skillDir),
-        workflowDigest: logicDigest(opts.workflowFile),
-        helperDigest: logicDigest(opts.helperFile),
-        coverage,
-        runId: opts.runId,
-        currentArtifactPath: opts.artifact,
-        baselineArtifactPath: opts.baseline ?? null,
-        spurVersion: opts.spurVersion ?? NOT_AVAILABLE,
-        schemaVersion: typeof raw.schemaVersion === 'number' ? raw.schemaVersion : undefined,
-        executor: opts.executor ?? NOT_AVAILABLE,
-        model: opts.model ?? NOT_AVAILABLE,
-    };
-}
-function probe(opts) {
-    const current = buildProvenance(opts);
-    const cachedText = existsSync(opts.target) ? readFileSync(opts.target, 'utf8') : null;
-    const cached = cachedText === null ? null : parseProvenance(cachedText);
-    const decision =
-        opts.mode === 'ad-hoc'
-            ? { disposition: 'miss', reasons: ['ad-hoc-never-cached'] }
-            : decideCache(cached, current, {
-                  recompute: opts.recompute,
-                  dayClosed: current.windowState === 'closed',
-              });
-    current.cacheDisposition = decision.disposition;
-    return { decision, current };
-}
-var YAML_KEYS = [
-    'windowState',
-    'generatedAt',
-    'validatedAt',
-    'artifactDigest',
-    'baselineArtifactDigest',
-    'contractDigest',
-    'skillDigest',
-    'workflowDigest',
-    'helperDigest',
-    'runId',
-    'currentArtifactPath',
-    'baselineArtifactPath',
-    'spurVersion',
-    'schemaVersion',
-    'executor',
-    'model',
-    'cacheDisposition',
-];
-function yamlScalar(v) {
-    if (v === null || v === undefined) return 'null';
-    if (typeof v === 'number' || typeof v === 'boolean') return String(v);
-    return `"${String(v).replaceAll('"', '\\"')}"`;
-}
-function renderProvenanceFrontmatter(p) {
-    const lines = [
-        '---',
-        'identity:',
-        `  contractVersion: ${yamlScalar(p.identity.contractVersion)}`,
-        `  mode: ${p.identity.mode}`,
-        `  date: ${yamlScalar(p.identity.date)}`,
-        `  timezone: ${p.identity.timezone}`,
-        '  bounds:',
-        `    since: ${p.identity.bounds.since}`,
-        `    until: ${p.identity.bounds.until}`,
-        '  sources:',
-    ];
-    for (const s of p.identity.sources) lines.push(`    - source: ${s}`);
-    for (const k of YAML_KEYS) {
-        if (p[k] === undefined) continue;
-        lines.push(`${k}: ${yamlScalar(p[k])}`);
-    }
-    lines.push('coverage:');
-    for (const c of p.coverage) {
-        lines.push(`  - source: ${c.source}, status: ${c.status}, lastImportedAt: ${c.lastImportedAt ?? 'null'}`);
-    }
-    lines.push('---');
-    return lines.join(`
-`);
-}
-function bannerLine(p) {
-    return `> imported snapshot as of ${importedSnapshotAsOf(p.coverage)} · window ${p.windowState} · cache ${p.cacheDisposition ?? NOT_AVAILABLE}`;
-}
-function stripHeader(md) {
-    const body = md.replace(/^---\n[\s\S]*?\n---\n?/, '').replace(/^\n+/, '');
-    return body.replace(/^> imported snapshot as of [^\n]*\n+/, '');
-}
-function stampReport(candidateMarkdown, p) {
-    return `${renderProvenanceFrontmatter(p)}
-
-${bannerLine(p)}
-
-${stripHeader(candidateMarkdown).replace(/^\n+/, '')}`;
-}
-function refreshReport(publishedMarkdown, validatedAt, disposition) {
-    const cached = parseProvenance(publishedMarkdown);
-    if (cached === null) return publishedMarkdown;
-    const refreshed = { ...cached, validatedAt, cacheDisposition: disposition };
-    return stampReport(publishedMarkdown, refreshed);
-}
-function publishAtomically(candidatePath, targetPath) {
-    const tmpPath = `${targetPath}.tmp`;
-    try {
-        writeFileSync(tmpPath, readFileSync(candidatePath));
-        const fd = openSync(tmpPath, 'r');
-        try {
-            fsyncSync(fd);
-        } finally {
-            closeSync(fd);
-        }
-        renameSync(tmpPath, targetPath);
-    } catch (err) {
-        try {
-            rmSync(tmpPath, { force: true });
-        } catch {}
-        throw err;
-    }
-}
-function porcelainPaths(text) {
-    return new Set(
-        text
-            .split(`
-`)
-            .map((line) => line.replace(/^\S+\s+/, '').trim())
-            .filter((line) => line.length > 0),
-    );
-}
-function diffPorcelain(before, now, expects) {
-    const beforePaths = porcelainPaths(before);
-    return [...porcelainPaths(now)].filter((p) => !beforePaths.has(p) && !expects.has(p)).sort();
-}
-var VALID_COMMANDS = 'digest, check, paths, assert-clean, probe, stamp, refresh, publish';
-var PROBE_USAGE =
-    '<script> probe --artifact <a.json> --target <report.md> [--baseline <b.json>] [--mode daily|ad-hoc] ' +
-    '[--date <YYYY-MM-DD>] [--recompute true] [--out <prov.json>] [--skill-dir <d>] [--contract <f>] [--workflow <f>] [--helper <f>]';
-function parseFlags(args) {
-    const out = {};
-    for (let i = 0; i < args.length; i++) {
-        const a = args[i] ?? '';
-        if (!a.startsWith('--')) continue;
-        const key = a.slice(2);
-        const next = args[i + 1];
-        if (next === undefined || next.startsWith('--')) {
-            out[key] = 'true';
-        } else {
-            out[key] = next;
-            i++;
-        }
-    }
-    return out;
-}
-function runCacheCli(argv) {
-    const [cmd, a, b] = argv;
-    switch (cmd) {
-        case 'digest': {
-            if (a === undefined) {
-                return {
-                    exitCode: 1,
-                    stdout: '',
-                    stderr: `usage: <script> digest <artifact.json>
-`,
-                };
-            }
-            let artifact;
-            try {
-                artifact = JSON.parse(readFileSync(a, 'utf8'));
-            } catch {
-                return {
-                    exitCode: 1,
-                    stdout: '',
-                    stderr: `could not parse artifact at ${a}
-`,
-                };
-            }
-            const digest = semanticArtifactDigest(artifact);
-            return {
-                exitCode: 0,
-                stdout: `${digest}
-`,
-                stderr: '',
-            };
-        }
-        case 'check': {
-            if (a === undefined) {
-                return {
-                    exitCode: 1,
-                    stdout: '',
-                    stderr: `usage: <script> check <report.md>
-`,
-                };
-            }
-            const result = checkReportStructure(readFileSync(a, 'utf8'));
-            const stdout = `${result.ok ? 'PASS' : 'FAIL'}
-${result.problems
-    .map(
-        (p) => `- ${p}
-`,
-    )
-    .join('')}`;
-            return { exitCode: result.ok ? 0 : 1, stdout, stderr: '' };
-        }
-        case 'publish': {
-            if (a === undefined || b === undefined) {
-                return {
-                    exitCode: 1,
-                    stdout: '',
-                    stderr: `usage: <script> publish <candidate.md> <target.md>
-`,
-                };
-            }
-            publishAtomically(a, b);
-            return { exitCode: 0, stdout: '', stderr: '' };
-        }
-        case 'assert-clean': {
-            const f = parseFlags(argv.slice(1));
-            if (f.baseline === undefined) {
-                return {
-                    exitCode: 1,
-                    stdout: '',
-                    stderr: `usage: <script> assert-clean --baseline <porcelain.txt> [--expect <path>]...
-`,
-                };
-            }
-            const expects = new Set();
-            for (const arg of argv.slice(1)) {
-                if (arg.startsWith('--expect=')) expects.add(arg.slice('--expect='.length));
-            }
-            let now;
-            try {
-                now =
-                    spawnSync('git', ['status', '--porcelain'], {
-                        encoding: 'utf8',
-                        ...(f.cwd !== undefined ? { cwd: f.cwd } : {}),
-                    }).stdout ?? '';
-            } catch {
-                return {
-                    exitCode: 0,
-                    stdout: '',
-                    stderr: `assert-clean: git unavailable; skipped
-`,
-                };
-            }
-            const undeclared = diffPorcelain(readFileSync(f.baseline, 'utf8'), now, expects);
-            if (undeclared.length > 0) {
-                return {
-                    exitCode: 1,
-                    stdout: '',
-                    stderr: undeclared
-                        .map(
-                            (p) => `undeclared write: ${p}
-`,
-                        )
-                        .join(''),
-                };
-            }
-            return {
-                exitCode: 0,
-                stdout: `clean
-`,
-                stderr: '',
-            };
-        }
-        case 'paths': {
-            const f = parseFlags(argv.slice(1));
-            if (f.helper === undefined || f.out === undefined) {
-                return {
-                    exitCode: 1,
-                    stdout: '',
-                    stderr: `usage: <script> paths --helper <p> --out <env> [--report-dir <d>] [--date <d>] [--output <p>] [--mode <m>] [--since <s>] [--until <u>]
-`,
-                };
-            }
-            writeFileSync(
-                f.out,
-                resolvePaths({
-                    helper: f.helper,
-                    reportDir: f['report-dir'] ?? 'docs/report',
-                    date: f.date,
-                    output: f.output,
-                    mode: f.mode,
-                    since: f.since,
-                    until: f.until,
-                }),
-            );
-            return { exitCode: 0, stdout: '', stderr: '' };
-        }
-        case 'probe': {
-            const f = parseFlags(argv.slice(1));
-            if (f.artifact === undefined || f.target === undefined) {
-                return {
-                    exitCode: 1,
-                    stdout: '',
-                    stderr: `usage: ${PROBE_USAGE}
-`,
-                };
-            }
-            let result;
-            try {
-                result = probe({
-                    artifact: f.artifact,
-                    target: f.target,
-                    baseline: f.baseline,
-                    mode: f.mode === 'ad-hoc' ? 'ad-hoc' : 'daily',
-                    date: f.date,
-                    recompute: f.recompute === 'true',
-                    executor: f.executor,
-                    model: f.model,
-                    skillDir: f['skill-dir'],
-                    contractFile: f.contract,
-                    workflowFile: f.workflow,
-                    helperFile: f.helper,
-                    contractVersion: f['contract-version'],
-                    runId: f['run-id'],
-                    spurVersion: f['spur-version'],
-                });
-            } catch {
-                return {
-                    exitCode: 1,
-                    stdout: '',
-                    stderr: `could not read artifact at ${f.artifact}
-`,
-                };
-            }
-            if (f.out !== undefined)
-                writeFileSync(
-                    f.out,
-                    `${JSON.stringify(result.current, null, 2)}
-`,
-                );
-            const reasons = result.decision.reasons
-                .map(
-                    (r) => `- ${r}
-`,
-                )
-                .join('');
-            return {
-                exitCode: 0,
-                stdout: `${result.decision.disposition}
-${reasons}`,
-                stderr: '',
-            };
-        }
-        case 'stamp': {
-            const f = parseFlags(argv.slice(1));
-            if (f.candidate === undefined || f.provenance === undefined || f.out === undefined) {
-                return {
-                    exitCode: 1,
-                    stdout: '',
-                    stderr: `usage: <script> stamp --candidate <c.md> --provenance <p.json> --out <o.md>
-`,
-                };
-            }
-            try {
-                const p = JSON.parse(readFileSync(f.provenance, 'utf8'));
-                writeFileSync(
-                    f.out,
-                    `${stampReport(readFileSync(f.candidate, 'utf8'), p)}
-`,
-                );
-            } catch {
-                return {
-                    exitCode: 1,
-                    stdout: '',
-                    stderr: `stamp: could not read candidate or provenance
-`,
-                };
-            }
-            return { exitCode: 0, stdout: '', stderr: '' };
-        }
-        case 'refresh': {
-            const f = parseFlags(argv.slice(1));
-            if (f.report === undefined || f.out === undefined) {
-                return {
-                    exitCode: 1,
-                    stdout: '',
-                    stderr: `usage: <script> refresh --report <published.md> --out <o.md> [--disposition hit]
-`,
-                };
-            }
-            try {
-                const disposition = f.disposition ?? 'hit';
-                const refreshed = refreshReport(
-                    readFileSync(f.report, 'utf8'),
-                    f['validated-at'] ?? new Date().toISOString(),
-                    disposition,
-                );
-                writeFileSync(
-                    f.out,
-                    refreshed.endsWith(`
-`)
-                        ? refreshed
-                        : `${refreshed}
-`,
-                );
-            } catch {
-                return {
-                    exitCode: 1,
-                    stdout: '',
-                    stderr: `refresh: could not read report at ${f.report}
-`,
-                };
-            }
-            return { exitCode: 0, stdout: '', stderr: '' };
-        }
-        default:
-            return {
-                exitCode: 1,
-                stdout: '',
-                stderr: `valid commands: ${VALID_COMMANDS}
-`,
-            };
-    }
-}
-{
-    const { exitCode, stdout, stderr } = runCacheCli(process.argv.slice(2));
-    process.stdout.write(stdout);
-    process.stderr.write(stderr);
-    process.exitCode = exitCode;
-}
-
-export {
-    bannerLine,
-    buildProvenance,
-    checkReportStructure,
-    decideCache,
-    diffPorcelain,
-    importedSnapshotAsOf,
-    logicDigest,
-    parseProvenance,
-    porcelainPaths,
-    probe,
-    publishAtomically,
-    refreshReport,
-    renderProvenanceFrontmatter,
-    resolvePaths,
-    runCacheCli,
-    semanticArtifactDigest,
-    stampReport,
-};