@holmes-lab/holmes-kit 0.23.2 → 0.24.0

package/dist/holmes/project/analysis-currency.d.ts

@@ -0,0 +1,22 @@
+export type AnalysisState = 'analysed' | 'missing' | 'not-adopted' | 'unknown';
+export interface AnalysisVerdict {
+    state: AnalysisState;
+    openCount: number | null;
+    changedSources: number;
+}
+export interface AnalysisInput {
+    adopted: boolean;
+    openAnalyses: number | null;
+    changedSources: number;
+}
+/** Adoption is the directory's existence. A project that never analysed anything did not opt in. */
+export declare function hasAnalysisDir(root: string): boolean;
+/**
+ * Judged by COMMIT, never by clock. "An analysis within N hours" is an invented constant that turns
+ * a slow slice into a violation; what matters is whether an analysis stands open for the work that
+ * changed these files, which is exactly what `test_run` closes when it reconciles a persisted
+ * analysis against the files a slice actually touched.
+ */
+export declare function analysisCurrency(input: AnalysisInput): AnalysisVerdict;
+/** Empty when there is nothing to say; the two unjudgeable states say so rather than passing. */
+export declare function analysisStatusLine(v: AnalysisVerdict): string;

package/dist/holmes/project/analysis-currency.js

@@ -0,0 +1,96 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasAnalysisDir = hasAnalysisDir;
+exports.analysisCurrency = analysisCurrency;
+exports.analysisStatusLine = analysisStatusLine;
+// @implements A-SPEC-681
+/**
+ * Whether the graph analysis this project's own instructions require was actually run.
+ *
+ * `AGENTS.md` step 3 asks for `maintenance_analyze({persist:true})` before editing source, and
+ * nothing enforced it: measured 2026-09-19, the last persisted analysis was at 10:52 the previous
+ * day and seventeen feat/fix commits followed it with none. A user had to point at the gap.
+ *
+ * The cost was concrete. Searching for the precedent for spawning a browser, grep returned a CSS
+ * class named 'open', a d3 'start' event and a schema enum; the analysis returned `wiringSpawnCheck`
+ * and `Supervisor.spawnChild`. The question was "who opens a browser" and the answer lived under
+ * "who spawns a child" — a gap lexical search cannot cross and the graph does not notice.
+ *
+ * This OBSERVES. It does not block, and it never runs the tool on the operator's behalf: analysis is
+ * expensive and what to ask is a person's judgement.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+/** Adoption is the directory's existence. A project that never analysed anything did not opt in. */
+function hasAnalysisDir(root) {
+    try {
+        return fs.statSync(path.join(root, '.ax', 'evidence', 'maintenance')).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Judged by COMMIT, never by clock. "An analysis within N hours" is an invented constant that turns
+ * a slow slice into a violation; what matters is whether an analysis stands open for the work that
+ * changed these files, which is exactly what `test_run` closes when it reconciles a persisted
+ * analysis against the files a slice actually touched.
+ */
+function analysisCurrency(input) {
+    const changedSources = typeof input.changedSources === 'number' && Number.isFinite(input.changedSources)
+        ? Math.max(0, input.changedSources) : 0;
+    const open = input.openAnalyses;
+    const base = { openCount: typeof open === 'number' && Number.isFinite(open) ? open : null, changedSources };
+    if (!input.adopted)
+        return { state: 'not-adopted', ...base };
+    // The discipline is about editing source. Nothing changed, nothing to say.
+    if (changedSources === 0)
+        return { state: 'analysed', ...base };
+    if (typeof open !== 'number' || !Number.isFinite(open) || open < 0)
+        return { state: 'unknown', ...base };
+    return { state: open > 0 ? 'analysed' : 'missing', ...base };
+}
+/** Empty when there is nothing to say; the two unjudgeable states say so rather than passing. */
+function analysisStatusLine(v) {
+    if (v.state === 'analysed' || v.state === 'not-adopted')
+        return '';
+    if (v.state === 'unknown') {
+        return 'the persisted analyses could not be counted — whether this change was analysed could not be judged';
+    }
+    const n = v.changedSources;
+    return `${n} source file${n === 1 ? '' : 's'} changed with no analysis standing open — `
+        + 'AGENTS.md step 3 asks for `maintenance_analyze({ persist: true })` first; it finds precedents a name search cannot reach';
+}

package/dist/holmes/project/ci-lock.d.ts

@@ -0,0 +1,20 @@
+export interface CiLockHolder {
+    pid: number;
+    host: string;
+    rev: string;
+    at: string;
+}
+export type CiLockState = 'free' | 'held' | 'dead' | 'unknown';
+export interface CiLockInput {
+    holder: CiLockHolder | null;
+    thisHost: string;
+    alive: boolean;
+}
+/** Null for every shape we cannot trust — including the legacy empty directory. */
+export declare function readCiLock(lockDir: string): CiLockHolder | null;
+/**
+ * A holder written by ANOTHER host is `unknown`, not dead: we cannot ask that machine about its
+ * pids, and guessing would hand two runners the same VM. Unknown is respected like `held`.
+ */
+export declare function ciLockState(input: CiLockInput): CiLockState;
+export declare function ciLockLine(state: CiLockState, holder: CiLockHolder | null, now?: Date): string;

package/dist/holmes/project/ci-lock.js

@@ -0,0 +1,111 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readCiLock = readCiLock;
+exports.ciLockState = ciLockState;
+exports.ciLockLine = ciLockLine;
+// @implements A-SPEC-674
+/**
+ * Who holds the CI runner's lock, and is that holder still alive.
+ *
+ * The runner serialises itself with a `mkdir` lock — atomic, and that atomicity is the whole reason
+ * it works — released by `trap ... EXIT`. SIGKILL and launchd tearing down the process group skip
+ * that trap. Measured 2026-09-18: one such lock survived 95 minutes while the matrix judged nothing
+ * and nine commits went unjudged, with zero jest processes in the VM and a load of 0.57.
+ *
+ * The lock used to be an EMPTY directory, so it could not say who held it — and a lock that cannot
+ * name its holder cannot be asked whether that holder is alive. It now carries a holder file, and
+ * the judgement below is about liveness, never about elapsed time: calling a slow run dead would
+ * start a second run on the same VM, which is a worse failure than waiting.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+/** Null for every shape we cannot trust — including the legacy empty directory. */
+function readCiLock(lockDir) {
+    let raw;
+    try {
+        raw = fs.readFileSync(path.join(lockDir, 'holder.json'), 'utf8');
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    const h = parsed;
+    if (typeof h?.pid !== 'number' || !Number.isFinite(h.pid))
+        return null;
+    if (typeof h.host !== 'string' || typeof h.rev !== 'string' || typeof h.at !== 'string')
+        return null;
+    return { pid: h.pid, host: h.host, rev: h.rev, at: h.at };
+}
+/**
+ * A holder written by ANOTHER host is `unknown`, not dead: we cannot ask that machine about its
+ * pids, and guessing would hand two runners the same VM. Unknown is respected like `held`.
+ */
+function ciLockState(input) {
+    const { holder, thisHost, alive } = input;
+    if (!holder)
+        return 'free';
+    if (holder.host !== thisHost)
+        return 'unknown';
+    return alive ? 'held' : 'dead';
+}
+const elapsed = (at, now) => {
+    const t = Date.parse(at);
+    if (!Number.isFinite(t))
+        return null;
+    const mins = Math.floor((now.getTime() - t) / 60000);
+    // A clock that runs backwards is a fact about the clock, not about the holder; never report it as
+    // negative time.
+    return mins < 0 ? null : `${mins} min`;
+};
+function ciLockLine(state, holder, now = new Date()) {
+    if (state === 'free' || !holder)
+        return '';
+    const held = elapsed(holder.at, now);
+    const forHow = held ? ` for ${held}` : '';
+    if (state === 'dead') {
+        return `ci lock holder pid ${holder.pid} is gone (held${forHow}, rev ${holder.rev}) — reclaiming it; the matrix judges nothing while a dead holder stands`;
+    }
+    if (state === 'unknown') {
+        return `ci lock was taken by ${holder.host} (rev ${holder.rev}${forHow}) — this host cannot judge another machine's pids, so it is respected`;
+    }
+    return `ci lock is held by pid ${holder.pid} running rev ${holder.rev}${forHow}`;
+}

package/dist/holmes/project/dist-freshness.d.ts

@@ -0,0 +1,30 @@
+export type DistState = 'fresh' | 'behind' | 'absent' | 'no-build-id' | 'unknown';
+export interface DistVerdict {
+    state: DistState;
+    buildId: string | null;
+    head: string | null;
+    behind: number | null;
+}
+export interface DistInput {
+    distExists: boolean;
+    buildId: string | null;
+    head: string | null;
+    /** Commits from the build id to HEAD, or null when it could not be obtained. */
+    behind: number | null;
+}
+/**
+ * The adoption predicate: existence, never contents. A workspace that does not build has no build
+ * freshness to report, and telling it about one would be noise it can do nothing with (the same
+ * reasoning REQ-664 used for the CI ledger).
+ */
+export declare function hasDist(root: string): boolean;
+/** The commit the artefact came from — the part before the dash `npm run build` writes. */
+export declare function distBuildId(root: string): string | null;
+/**
+ * Five states because each calls for something different: `behind` means build, `absent` means
+ * nothing at all to this workspace, and the two unjudgeable ones mean the check did not run — which
+ * must never be reported as a check that passed.
+ */
+export declare function distFreshness(input: DistInput): DistVerdict;
+/** Empty when there is nothing to say. A line is spent only on a fact the reader can act on. */
+export declare function distStatusLine(v: DistVerdict): string;

package/dist/holmes/project/dist-freshness.js

@@ -0,0 +1,114 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasDist = hasDist;
+exports.distBuildId = distBuildId;
+exports.distFreshness = distFreshness;
+exports.distStatusLine = distStatusLine;
+// @implements A-SPEC-673
+/**
+ * Whether the built artefact still represents the source.
+ *
+ * Thirty suites in this repository load `dist/` while they run — they spawn it or require it — and
+ * nothing asserted that it was current. `scripts/verify-release.js` compares the build id to HEAD,
+ * but only at publish time, so during development a stale build does not go red: it quietly verifies
+ * old code and returns green. This repository has already paid for that once.
+ *
+ * The judgement is built on the BUILD ID, never on mtime, for a measured reason. On 2026-09-18 this
+ * tree's `dist` was nine commits behind HEAD and two changed sources were missing from it entirely,
+ * while `find src -newer dist/.build-id` answered zero — the marker's mtime had been touched without
+ * a rebuild. mtime lies. The build id says which commit the artefact actually came from.
+ *
+ * This module only JUDGES. It never rebuilds: a hook does not change the operator's tree in silence.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+/**
+ * The adoption predicate: existence, never contents. A workspace that does not build has no build
+ * freshness to report, and telling it about one would be noise it can do nothing with (the same
+ * reasoning REQ-664 used for the CI ledger).
+ */
+function hasDist(root) {
+    try {
+        return fs.statSync(path.join(root, 'dist')).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** The commit the artefact came from — the part before the dash `npm run build` writes. */
+function distBuildId(root) {
+    let raw;
+    try {
+        raw = fs.readFileSync(path.join(root, 'dist', '.build-id'), 'utf8');
+    }
+    catch {
+        return null;
+    }
+    const id = raw.trim().split('-')[0];
+    // A shape we do not recognise falls through to a judgement we cannot make, never to a pass.
+    return /^[0-9a-f]{7,40}$/.test(id) ? id : null;
+}
+/**
+ * Five states because each calls for something different: `behind` means build, `absent` means
+ * nothing at all to this workspace, and the two unjudgeable ones mean the check did not run — which
+ * must never be reported as a check that passed.
+ */
+function distFreshness(input) {
+    const { distExists, buildId, head, behind } = input;
+    const base = { buildId: buildId ?? null, head: head ?? null, behind: typeof behind === 'number' ? behind : null };
+    if (!distExists)
+        return { state: 'absent', ...base };
+    if (!buildId)
+        return { state: 'no-build-id', ...base };
+    if (!head || typeof behind !== 'number' || !Number.isFinite(behind) || behind < 0)
+        return { state: 'unknown', ...base };
+    return { state: behind === 0 ? 'fresh' : 'behind', ...base };
+}
+/** Empty when there is nothing to say. A line is spent only on a fact the reader can act on. */
+function distStatusLine(v) {
+    if (v.state === 'fresh' || v.state === 'absent')
+        return '';
+    if (v.state === 'no-build-id') {
+        return 'dist/.build-id is missing or unreadable — the build could not be judged against the source; `npm run build` writes it';
+    }
+    if (v.state === 'unknown') {
+        return `dist was built from ${v.buildId ?? 'an unknown commit'} and the distance to HEAD could not be obtained — the build could not be judged`;
+    }
+    // No invented threshold: one commit is reported like nine, because which commits matter is a
+    // question the reader can answer and this function cannot.
+    const n = v.behind ?? 0;
+    return `dist is ${n} commit${n === 1 ? '' : 's'} behind HEAD (built from ${v.buildId}) — suites that load dist are verifying that build, not this tree; \`npm run build\``;
+}

package/dist/holmes/project/field-report-url.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The report's way to us: a PREFILLED GitHub issue URL that a person submits on GitHub's own page.
+ *
+ * The alternative — holmes-kit holding a token and posting through the API — was rejected for a
+ * measured reason, not a stylistic one. Consent is the weakest link here: the first field report of
+ * the approval queue counted 1,412 unique requests against 8 decisions, 99.4% undecided. A yes/no
+ * buried in a stream of prompts is not a decision, and a user consents to "report this" without
+ * reading forty lines of body.
+ *
+ * A URL moves the decision to where the bytes are visible. The person sees the whole body in
+ * GitHub's own editor, can change it, and cancelling costs nothing — closing the tab is the entire
+ * undo. Four consequences follow structurally rather than by discipline: no token exists to leak,
+ * nothing can be sent silently, there is no auth/rate-limit/retry surface, and this module cannot
+ * exfiltrate anything because it has no transport at all. It only builds strings.
+ */
+import type { FieldReport } from './field-report';
+export declare const ISSUE_REPO = "holmes-kit/holmes-kit";
+/** Conservative: GitHub accepts more, but a URL that silently fails to open helps nobody. */
+export declare const URL_BUDGET = 8000;
+/**
+ * The repository owner, offered as the default assignee.
+ *
+ * KNOWN LIMIT, stated rather than implied: GitHub honours `assignee=` only when the person filling
+ * the form may assign (write or triage on the repo). A third-party reporter usually cannot, and the
+ * parameter is then dropped silently. It costs nothing either way — it routes when it can and is
+ * discarded when it cannot — but it is not a guarantee, and nobody should plan triage around it.
+ */
+export declare const ISSUE_ASSIGNEE = "sungnamparkkorea-arch";
+export interface UrlOptions {
+    repo?: string;
+    localPath?: string;
+    budget?: number;
+    title?: string;
+    assignee?: string | null;
+}
+/**
+ * The fingerprint rides in the title so a person scanning the issue list recognises a duplicate
+ * without opening anything. The MESSAGE deliberately does not: a title is the most visible place in
+ * the tracker, and `message` is the one allowlisted field whose VALUE can be withheld as unsafe.
+ */
+export declare function issueTitle(r: FieldReport): string;
+export declare function issueUrl(body: string, opts?: UrlOptions): {
+    url: string;
+    truncated: boolean;
+};
+/** Empty in, empty out: a query with no fingerprint lists every issue, which is not a duplicate check. */
+export declare function searchUrl(fingerprint: string, opts?: UrlOptions): string;

package/dist/holmes/project/field-report-url.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ISSUE_ASSIGNEE = exports.URL_BUDGET = exports.ISSUE_REPO = void 0;
+exports.issueTitle = issueTitle;
+exports.issueUrl = issueUrl;
+exports.searchUrl = searchUrl;
+exports.ISSUE_REPO = 'holmes-kit/holmes-kit';
+/** Conservative: GitHub accepts more, but a URL that silently fails to open helps nobody. */
+exports.URL_BUDGET = 8000;
+/**
+ * The repository owner, offered as the default assignee.
+ *
+ * KNOWN LIMIT, stated rather than implied: GitHub honours `assignee=` only when the person filling
+ * the form may assign (write or triage on the repo). A third-party reporter usually cannot, and the
+ * parameter is then dropped silently. It costs nothing either way — it routes when it can and is
+ * discarded when it cannot — but it is not a guarantee, and nobody should plan triage around it.
+ */
+exports.ISSUE_ASSIGNEE = 'sungnamparkkorea-arch';
+/**
+ * The fingerprint rides in the title so a person scanning the issue list recognises a duplicate
+ * without opening anything. The MESSAGE deliberately does not: a title is the most visible place in
+ * the tracker, and `message` is the one allowlisted field whose VALUE can be withheld as unsafe.
+ */
+function issueTitle(r) {
+    const what = r.article || r.tool || 'report';
+    return `holmes-kit ${r.kit}: ${what} (${r.fingerprint.slice(0, 8)})`;
+}
+const NOTE = (localPath) => localPath
+    ? `\n\n— truncated to fit the URL; the full report is at ${localPath}`
+    : '\n\n— truncated to fit the URL; the full report stayed on the reporter\'s machine';
+function issueUrl(body, opts = {}) {
+    const repo = opts.repo ?? exports.ISSUE_REPO;
+    const budget = opts.budget ?? exports.URL_BUDGET;
+    // The title goes in the URL, not just into a helper nobody calls. It was missing here for a
+    // slice: `issueTitle` existed, a pin called it directly, and the product path built `?body=`
+    // alone — so GitHub opened with a blank title. A function pinned in isolation says nothing about
+    // the path that is supposed to feed it.
+    const titlePart = opts.title && opts.title.trim() !== '' ? `title=${encodeURIComponent(opts.title)}&` : '';
+    // Omitted rather than emptied when absent: a fork or an internal mirror must not point at someone
+    // else's account, and `assignee=` with nothing after it is noise in the form.
+    const assigneePart = typeof opts.assignee === 'string' && opts.assignee.trim() !== ''
+        ? `assignee=${encodeURIComponent(opts.assignee.trim())}&` : '';
+    const base = `https://github.com/${repo}/issues/new?${titlePart}${assigneePart}body=`;
+    const build = (text) => base + encodeURIComponent(text);
+    const whole = build(body);
+    if (whole.length <= budget)
+        return { url: whole, truncated: false };
+    // Never a silent cut: the note is part of the body that gets sent, so the reader of the ISSUE — not
+    // just the reporter — learns that something was left out.
+    const note = NOTE(opts.localPath);
+    let keep = body.length;
+    while (keep > 0 && build(body.slice(0, keep) + note).length > budget) {
+        keep = Math.floor(keep * 0.9);
+    }
+    return { url: build(body.slice(0, keep) + note), truncated: true };
+}
+/** Empty in, empty out: a query with no fingerprint lists every issue, which is not a duplicate check. */
+function searchUrl(fingerprint, opts = {}) {
+    if (typeof fingerprint !== 'string' || fingerprint.trim() === '')
+        return '';
+    const repo = opts.repo ?? exports.ISSUE_REPO;
+    return `https://github.com/${repo}/issues?q=${encodeURIComponent(`is:issue ${fingerprint.trim()}`)}`;
+}

package/dist/holmes/project/field-report.d.ts

@@ -0,0 +1,54 @@
+/** The only keys a report may carry. Adding one is an edit here, which the pin makes visible. */
+export declare const FIELD_REPORT_KEYS: readonly ["kit", "harness", "os", "arch", "node", "message", "article", "tool", "specIds", "observations", "fingerprint", "withheld"];
+export interface FieldReportInput {
+    kit: string;
+    harness: string;
+    os: string;
+    arch: string;
+    node: string;
+    message?: string;
+    article?: string;
+    tool?: string;
+    specIds?: string[];
+    observations?: Array<{
+        label: string;
+        value: number;
+    }>;
+    /** Strings that identify this machine or person, injected by the caller so a pin can search for them. */
+    identity?: string[];
+}
+export interface FieldReport {
+    kit: string;
+    harness: string;
+    os: string;
+    arch: string;
+    node: string;
+    message: string;
+    article: string;
+    tool: string;
+    specIds: string[];
+    observations: Array<{
+        label: string;
+        value: number;
+    }>;
+    fingerprint: string;
+    withheld: string[];
+}
+/**
+ * Injected rather than read from `os` here, so a pin can search a composed body for THIS machine's
+ * real values. A module that reads the environment itself can only be tested against fixtures, and
+ * fixtures are exactly what a redaction pin must not trust.
+ *
+ * Tokens shorter than two characters are dropped: a one-character identity would redact every
+ * sentence, which is destruction rather than redaction.
+ */
+export declare function machineIdentity(env: {
+    hostname?: string;
+    username?: string;
+    homedir?: string;
+    replicas?: string[];
+}): string[];
+export declare function isSafeValue(text: string, identity: string[]): boolean;
+export declare function composeFieldReport(input: FieldReportInput): FieldReport;
+/** The bytes a human will read and paste. Anything withheld is named, never dropped in silence. */
+export declare function fieldReportBody(r: FieldReport): string;