@dsh-triage/core 0.1.0 → 0.2.0

package/dist/outcome.js

@@ -0,0 +1,376 @@
+/**
+ * Local outcome records: the whitelist that proves a record carries no PII.
+ *
+ * WHY THIS MODULE EXISTS (spec `docs/specs/M5-reflow.md` §3–§5, `T-501`):
+ * "we only store the four-state conclusion" is a claim; a whitelist projection that
+ * *rejects* the whole line when one unknown key appears is an enforcement. Everything
+ * the local store can hold is declared here, and there is exactly one function that
+ * decides whether a candidate record is allowed to reach disk (`sanitizeOutcome`) and
+ * one that decides whether an existing line may be read back (`assertOutcomeLine`).
+ *
+ * WHAT THIS MODULE MUST NEVER DO (§12 of the spec, machine-checked by the
+ * `outcome-privacy` check of `scripts/gate_governance.mjs`):
+ * - no network client of any kind, no `fs`, no clock, no `process.env`;
+ * - no randomness: `id` and `at` are injected by the caller, exactly like `generatedAt`
+ *   in `verdict.ts`;
+ * - no repair: a rejected record is rejected, never "cleaned up and written anyway".
+ *
+ * TIER DISCIPLINE (`ADR-0011` option A): a `LocalPrior` is an *annotation*. It never
+ * enters `conclusion` / `confidence` / `evidence[]`, and there is no evidence tier for
+ * it (`measured-local` is reused as a label for "this machine measured this before").
+ */
+import { valid } from 'semver';
+import { CONCLUSION_VALUES } from './types.js';
+export const OUTCOME_OS_VALUES = ['win32', 'darwin', 'linux', 'freebsd', 'other'];
+export const OUTCOME_ARCH_VALUES = ['x64', 'arm64', 'ia32', 'other'];
+export const OUTCOME_PROFILE_KIND_VALUES = ['web', 'tui', 'headless', 'unknown'];
+export const OUTCOME_SOURCE_VALUES = ['check', 'probe'];
+export const TIMING_BUCKET_VALUES = ['lt5s', '5to20s', '20to60s', 'gte60s'];
+/** The five evidence tiers, as a value list, so the sanitizer does not have to trust a cast. */
+export const EVIDENCE_TIER_VALUES = ['inferred', 'declared', 'scanned', 'measured-registry', 'measured-local'];
+/** Exactly the keys of {@link OutcomeRecord}. Anything else is an `unknown-field` rejection. */
+const ALLOWED_FIELDS = new Set([
+    'schema_version',
+    'id',
+    'at',
+    'source',
+    'package',
+    'version',
+    'dsh_version',
+    'os',
+    'arch',
+    'node_major',
+    'profile_kind',
+    'conclusion',
+    'reason_message_ids',
+    'evidence_tiers',
+    'probe',
+]);
+const PROBE_FIELDS = new Set(['total_ms_bucket', 'boot_ms_bucket']);
+/** npm's own name grammar (scope-aware), kept literal so a package name containing `/` is legal. */
+const PACKAGE_RE = /^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
+const ID_RE = /^[0-9a-f]{32}$/;
+const ISO_UTC_MS_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+const MESSAGE_ID_RE = /^(admission|collision|registry|runtime|remediation|missing|probe|tool|prior)\.[a-z0-9.-]+$/;
+const MAX_PACKAGE = 214;
+const MAX_VERSION = 64;
+const MAX_REASON_IDS = 12;
+const MAX_TIERS = 8;
+/** One line, 1024 bytes. A defence line, not a formatting preference (§5.5). */
+export const MAX_OUTCOME_BYTES = 1024;
+/**
+ * Forbidden shapes, scanned over every final string value (§5.3).
+ *
+ * WHY the context around `/`: a scoped package name (`@scope/name`) is legal, so a bare
+ * separator cannot be the signal. A path needs a drive letter, a leading separator after
+ * whitespace/`"`/`=`, a UNC prefix, or a `file://` scheme — those are the shapes that
+ * actually carry a username.
+ */
+const FORBIDDEN_SHAPES = [
+    /[A-Za-z]:[\\/]/,
+    /\\\\[A-Za-z0-9._-]+\\/,
+    /(^|[\s"=])\/(Users|home|root|tmp)\//,
+    /file:\/\//i,
+    /~\//,
+    /sk-[A-Za-z0-9]{20,}/,
+    /ghp_[A-Za-z0-9]{20,}/,
+    /npm_[A-Za-z0-9]{20,}/,
+    /bearer\s/i,
+    /token=/i,
+];
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function hasForbiddenShape(value) {
+    return FORBIDDEN_SHAPES.some((pattern) => pattern.test(value));
+}
+/** UTF-8 length without touching a Node-only global (core stays bundle-safe). */
+function utf8Length(value) {
+    return new TextEncoder().encode(value).length;
+}
+/** Every final string of the assembled record, so the forbidden-shape scan cannot skip one. */
+function recordStrings(record) {
+    const values = [
+        record.id,
+        record.at,
+        record.source,
+        record.package,
+        record.version,
+        record.os,
+        record.arch,
+        record.profile_kind,
+        record.conclusion,
+        ...record.reason_message_ids,
+        ...record.evidence_tiers,
+    ];
+    if (record.dsh_version !== null)
+        values.push(record.dsh_version);
+    if (record.probe !== null) {
+        values.push(record.probe.total_ms_bucket);
+        if (record.probe.boot_ms_bucket !== null)
+            values.push(record.probe.boot_ms_bucket);
+    }
+    return values;
+}
+/** A string array that is deduplicated AND ascending: order is part of the contract, not noise. */
+function readSortedStrings(value, limit, accept) {
+    if (!Array.isArray(value) || value.length > limit)
+        return null;
+    const out = [];
+    for (const [index, item] of value.entries()) {
+        if (typeof item !== 'string' || !accept(item))
+            return null;
+        // Strictly ascending ⇒ sorted AND deduplicated. A caller that hands us an unordered
+        // list has already lost the guarantee the gate recomputes, so we refuse instead of sorting.
+        if (index > 0) {
+            const previous = out[index - 1];
+            if (previous === undefined || !(previous < item))
+                return null;
+        }
+        out.push(item);
+    }
+    return out;
+}
+function fail(reason, field) {
+    return { ok: false, reason, field };
+}
+const isEnumValue = (values, value) => typeof value === 'string' && values.includes(value);
+/**
+ * Project a candidate record onto the whitelist, or refuse it.
+ *
+ * Order of operations is the contract (§5): unknown keys → value domains → forbidden
+ * shapes over the *assembled* record → byte cap. A rejection never mutates the input and
+ * never returns a partially cleaned record.
+ */
+export function sanitizeOutcome(input) {
+    if (!isPlainObject(input))
+        return fail('not-an-object', null);
+    // 1. Whitelist projection: an unknown key means the caller already holds data it should
+    // not have, so the whole record dies (§5.1). Silently dropping it would hide that path.
+    for (const key of Object.keys(input)) {
+        if (!ALLOWED_FIELDS.has(key))
+            return fail('unknown-field', key);
+    }
+    if (input['schema_version'] !== 1)
+        return fail('value-shape', 'schema_version');
+    const id = input['id'];
+    if (typeof id !== 'string' || !ID_RE.test(id))
+        return fail('value-shape', 'id');
+    const at = input['at'];
+    if (typeof at !== 'string' || !ISO_UTC_MS_RE.test(at) || Number.isNaN(Date.parse(at))) {
+        return fail('bad-timestamp', 'at');
+    }
+    const source = input['source'];
+    if (!isEnumValue(OUTCOME_SOURCE_VALUES, source))
+        return fail('value-shape', 'source');
+    const packageName = input['package'];
+    if (typeof packageName !== 'string' || packageName.length > MAX_PACKAGE || !PACKAGE_RE.test(packageName)) {
+        return fail('value-shape', 'package');
+    }
+    // `+build` would smuggle a build fingerprint into a version string, so it is refused
+    // rather than stripped (`semver.valid` keeps it, which is why the check is explicit).
+    const version = input['version'];
+    if (typeof version !== 'string' ||
+        version.length > MAX_VERSION ||
+        version.includes('+') ||
+        valid(version) === null) {
+        return fail('value-shape', 'version');
+    }
+    const dshVersion = input['dsh_version'];
+    if (dshVersion !== null) {
+        if (typeof dshVersion !== 'string' || dshVersion.length > MAX_VERSION || valid(dshVersion) === null) {
+            return fail('value-shape', 'dsh_version');
+        }
+    }
+    const os = input['os'];
+    if (!isEnumValue(OUTCOME_OS_VALUES, os))
+        return fail('value-shape', 'os');
+    const arch = input['arch'];
+    if (!isEnumValue(OUTCOME_ARCH_VALUES, arch))
+        return fail('value-shape', 'arch');
+    const nodeMajor = input['node_major'];
+    if (typeof nodeMajor !== 'number' || !Number.isInteger(nodeMajor) || nodeMajor < 18 || nodeMajor > 99) {
+        return fail('value-shape', 'node_major');
+    }
+    const profileKind = input['profile_kind'];
+    if (!isEnumValue(OUTCOME_PROFILE_KIND_VALUES, profileKind))
+        return fail('value-shape', 'profile_kind');
+    const conclusion = input['conclusion'];
+    if (!isEnumValue(CONCLUSION_VALUES, conclusion))
+        return fail('value-shape', 'conclusion');
+    const reasonIds = readSortedStrings(input['reason_message_ids'], MAX_REASON_IDS, (item) => MESSAGE_ID_RE.test(item));
+    if (reasonIds === null)
+        return fail('value-shape', 'reason_message_ids');
+    const tiers = readSortedStrings(input['evidence_tiers'], MAX_TIERS, (item) => isEnumValue(EVIDENCE_TIER_VALUES, item));
+    if (tiers === null)
+        return fail('value-shape', 'evidence_tiers');
+    const rawProbe = input['probe'];
+    let probe = null;
+    if (rawProbe !== null) {
+        if (!isPlainObject(rawProbe))
+            return fail('value-shape', 'probe');
+        for (const key of Object.keys(rawProbe)) {
+            if (!PROBE_FIELDS.has(key))
+                return fail('unknown-field', `probe.${key}`);
+        }
+        // Only a probe run can carry probe facts; a `check` record with buckets would be a
+        // claim about a measurement that never happened.
+        if (source !== 'probe')
+            return fail('value-shape', 'probe');
+        const total = rawProbe['total_ms_bucket'];
+        if (!isEnumValue(TIMING_BUCKET_VALUES, total))
+            return fail('value-shape', 'probe.total_ms_bucket');
+        const boot = rawProbe['boot_ms_bucket'];
+        if (boot !== null && !isEnumValue(TIMING_BUCKET_VALUES, boot)) {
+            return fail('value-shape', 'probe.boot_ms_bucket');
+        }
+        probe = { total_ms_bucket: total, boot_ms_bucket: boot };
+    }
+    const record = {
+        schema_version: 1,
+        id,
+        at,
+        source,
+        package: packageName,
+        version,
+        dsh_version: dshVersion,
+        os,
+        arch,
+        node_major: nodeMajor,
+        profile_kind: profileKind,
+        conclusion,
+        reason_message_ids: reasonIds,
+        evidence_tiers: tiers,
+        probe,
+    };
+    // 3. Forbidden shapes, over the assembled record (never over the raw input: only what we
+    // are about to write matters).
+    for (const value of recordStrings(record)) {
+        if (hasForbiddenShape(value))
+            return fail('value-shape', fieldOfShapeHit(record, value));
+    }
+    // 5. Byte cap. Free text cannot fit in a record that is capped at one short line.
+    if (utf8Length(JSON.stringify(record)) > MAX_OUTCOME_BYTES)
+        return fail('too-long', null);
+    return { ok: true, record };
+}
+/** Name the field a forbidden shape was found in, so the rejection is actionable. */
+function fieldOfShapeHit(record, value) {
+    if (value === record.id)
+        return 'id';
+    if (value === record.at)
+        return 'at';
+    if (value === record.package)
+        return 'package';
+    if (value === record.version)
+        return 'version';
+    if (value === record.dsh_version)
+        return 'dsh_version';
+    if (value === record.source)
+        return 'source';
+    if (value === record.os)
+        return 'os';
+    if (value === record.arch)
+        return 'arch';
+    if (value === record.profile_kind)
+        return 'profile_kind';
+    if (value === record.conclusion)
+        return 'conclusion';
+    if (record.reason_message_ids.includes(value))
+        return 'reason_message_ids';
+    if (record.evidence_tiers.includes(value))
+        return 'evidence_tiers';
+    return 'probe';
+}
+/**
+ * Read back one stored line.
+ *
+ * WHY A SECOND FUNCTION: reading is where a hand-edited or corrupted library turns into fake
+ * evidence. A line that does not validate is dropped by the caller and counted as
+ * `rejected_lines`; it is never repaired, and it never aborts the whole read.
+ */
+export function assertOutcomeLine(line) {
+    if (typeof line !== 'string' || line.trim() === '')
+        return { ok: false, reason: 'not-json', field: null };
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        return { ok: false, reason: 'not-json', field: null };
+    }
+    const result = sanitizeOutcome(parsed);
+    if (!result.ok)
+        return result;
+    return { ok: true, record: result.record };
+}
+/** The seven-tuple of a record (§2). One definition, so the store, the prior and D4 agree. */
+export function outcomeKeyOf(record) {
+    return {
+        package: record.package,
+        version: record.version,
+        dsh: record.dsh_version,
+        os: record.os,
+        arch: record.arch,
+        node_major: record.node_major,
+        profile_kind: record.profile_kind,
+    };
+}
+/** A key is usable for prior matching only when all seven positions are known (§2, B10). */
+export function isCompleteOutcomeKey(key) {
+    return key.dsh !== null && key.profile_kind !== 'unknown';
+}
+export function sameOutcomeKey(left, right) {
+    return (left.package === right.package &&
+        left.version === right.version &&
+        left.dsh === right.dsh &&
+        left.os === right.os &&
+        left.arch === right.arch &&
+        left.node_major === right.node_major &&
+        left.profile_kind === right.profile_kind);
+}
+/**
+ * The local prior for one key: counts, strict majority, agreement.
+ *
+ * `majority` is a **strict majority** (`counts[majority] * 2 > n`), so a tie - and any
+ * plurality that does not exceed half - reads as "no majority" rather than as a winner.
+ * Stricter than a plain mode on purpose: this number is shown to a user next to a verdict
+ * that it must not influence (`ADR-0011` §4.1), and "2 of 4 said go" is not a majority.
+ *
+ * Returns `null` when the key is incomplete or `n = 0`, and the caller then omits the whole
+ * `prior` key (§10.2: "nothing" must be distinguishable from "empty").
+ */
+export function computeLocalPrior(records, key) {
+    if (!isCompleteOutcomeKey(key))
+        return null;
+    const counts = { go: 0, risky: 0, blocked: 0, unknown: 0 };
+    let n = 0;
+    for (const record of records) {
+        if (!sameOutcomeKey(outcomeKeyOf(record), key))
+            continue;
+        counts[record.conclusion] += 1;
+        n += 1;
+    }
+    if (n < 1)
+        return null;
+    let majority = null;
+    for (const conclusion of CONCLUSION_VALUES) {
+        if (counts[conclusion] * 2 > n)
+            majority = conclusion;
+    }
+    return {
+        schema_version: 1,
+        annotation_only: true,
+        key,
+        source: 'local-outcomes',
+        method: 'outcome-log',
+        n,
+        counts,
+        majority,
+        agreement: majority === null ? null : counts[majority] / n,
+        tier: 'measured-local',
+        evidence_id: 'prior-local',
+        note_id: 'prior.annotation-only',
+    };
+}
+//# sourceMappingURL=outcome.js.map

package/dist/outcome.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outcome.js","sourceRoot":"","sources":["../src/outcome.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAA;AAC9B,OAAO,EAAE,iBAAiB,EAAsC,MAAM,YAAY,CAAA;AAelF,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,CAAU,CAAA;AAC1F,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAU,CAAA;AAC7E,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,SAAS,CAAU,CAAA;AACzF,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,OAAO,EAAE,OAAO,CAAU,CAAA;AAChE,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,CAAU,CAAA;AAEpF,gGAAgG;AAChG,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,mBAAmB,EAAE,gBAAgB,CAAU,CAAA;AAkEvH,gGAAgG;AAChG,MAAM,cAAc,GAAwB,IAAI,GAAG,CAAC;IAClD,gBAAgB;IAChB,IAAI;IACJ,IAAI;IACJ,QAAQ;IACR,SAAS;IACT,SAAS;IACT,aAAa;IACb,IAAI;IACJ,MAAM;IACN,YAAY;IACZ,cAAc;IACd,YAAY;IACZ,oBAAoB;IACpB,gBAAgB;IAChB,OAAO;CACR,CAAC,CAAA;AAEF,MAAM,YAAY,GAAwB,IAAI,GAAG,CAAC,CAAC,iBAAiB,EAAE,gBAAgB,CAAC,CAAC,CAAA;AAExF,oGAAoG;AACpG,MAAM,UAAU,GAAG,wDAAwD,CAAA;AAC3E,MAAM,KAAK,GAAG,gBAAgB,CAAA;AAC9B,MAAM,aAAa,GAAG,+CAA+C,CAAA;AACrE,MAAM,aAAa,GAAG,4FAA4F,CAAA;AAElH,MAAM,WAAW,GAAG,GAAG,CAAA;AACvB,MAAM,WAAW,GAAG,EAAE,CAAA;AACtB,MAAM,cAAc,GAAG,EAAE,CAAA;AACzB,MAAM,SAAS,GAAG,CAAC,CAAA;AACnB,gFAAgF;AAChF,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,CAAA;AAErC;;;;;;;GAOG;AACH,MAAM,gBAAgB,GAAsB;IAC1C,gBAAgB;IAChB,uBAAuB;IACvB,qCAAqC;IACrC,YAAY;IACZ,KAAK;IACL,qBAAqB;IACrB,sBAAsB;IACtB,sBAAsB;IACtB,WAAW;IACX,SAAS;CACV,CAAA;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;AAC7E,CAAC;AAED,SAAS,iBAAiB,CAAC,KAAa;IACtC,OAAO,gBAAgB,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAA;AAChE,CAAC;AAED,iFAAiF;AACjF,SAAS,UAAU,CAAC,KAAa;IAC/B,OAAO,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAA;AAC/C,CAAC;AAED,+FAA+F;AAC/F,SAAS,aAAa,CAAC,MAAqB;IAC1C,MAAM,MAAM,GAAa;QACvB,MAAM,CAAC,EAAE;QACT,MAAM,CAAC,EAAE;QACT,MAAM,CAAC,MAAM;QACb,MAAM,CAAC,OAAO;QACd,MAAM,CAAC,OAAO;QACd,MAAM,CAAC,EAAE;QACT,MAAM,CAAC,IAAI;QACX,MAAM,CAAC,YAAY;QACnB,MAAM,CAAC,UAAU;QACjB,GAAG,MAAM,CAAC,kBAAkB;QAC5B,GAAG,MAAM,CAAC,cAAc;KACzB,CAAA;IACD,IAAI,MAAM,CAAC,WAAW,KAAK,IAAI;QAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,CAAA;IAChE,IAAI,MAAM,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;QAC1B,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,eAAe,CAAC,CAAA;QACzC,IAAI,MAAM,CAAC,KAAK,CAAC,cAAc,KAAK,IAAI;YAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,cAAc,CAAC,CAAA;IACpF,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC;AAED,mGAAmG;AACnG,SAAS,iBAAiB,CACxB,KAAc,EACd,KAAa,EACb,MAAiC;IAEjC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,KAAK;QAAE,OAAO,IAAI,CAAA;IAC9D,MAAM,GAAG,GAAa,EAAE,CAAA;IACxB,KAAK,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;QAC5C,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;YAAE,OAAO,IAAI,CAAA;QAC1D,oFAAoF;QACpF,4FAA4F;QAC5F,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;YACd,MAAM,QAAQ,GAAG,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,CAAA;YAC/B,IAAI,QAAQ,KAAK,SAAS,IAAI,CAAC,CAAC,QAAQ,GAAG,IAAI,CAAC;gBAAE,OAAO,IAAI,CAAA;QAC/D,CAAC;QACD,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAChB,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,SAAS,IAAI,CAAC,MAAwB,EAAE,KAAoB;IAC1D,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,CAAA;AACrC,CAAC;AAED,MAAM,WAAW,GAAG,CAAmB,MAAoB,EAAE,KAAc,EAAc,EAAE,CACzF,OAAO,KAAK,KAAK,QAAQ,IAAK,MAA4B,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;AAE5E;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC,eAAe,EAAE,IAAI,CAAC,CAAA;IAE7D,wFAAwF;IACxF,wFAAwF;IACxF,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACrC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC,eAAe,EAAE,GAAG,CAAC,CAAA;IACjE,CAAC;IAED,IAAI,KAAK,CAAC,gBAAgB,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC,aAAa,EAAE,gBAAgB,CAAC,CAAA;IAE/E,MAAM,EAAE,GAAG,KAAK,CAAC,IAAI,CAAC,CAAA;IACtB,IAAI,OAAO,EAAE,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QAAE,OAAO,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC,CAAA;IAE/E,MAAM,EAAE,GAAG,KAAK,CAAC,IAAI,CAAC,CAAA;IACtB,IAAI,OAAO,EAAE,KAAK,QAAQ,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;QACtF,OAAO,IAAI,CAAC,eAAe,EAAE,IAAI,CAAC,CAAA;IACpC,CAAC;IAED,MAAM,MAAM,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAA;IAC9B,IAAI,CAAC,WAAW,CAAC,qBAAqB,EAAE,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAA;IAErF,MAAM,WAAW,GAAG,KAAK,CAAC,SAAS,CAAC,CAAA;IACpC,IAAI,OAAO,WAAW,KAAK,QAAQ,IAAI,WAAW,CAAC,MAAM,GAAG,WAAW,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;QACzG,OAAO,IAAI,CAAC,aAAa,EAAE,SAAS,CAAC,CAAA;IACvC,CAAC;IAED,qFAAqF;IACrF,sFAAsF;IACtF,MAAM,OAAO,GAAG,KAAK,CAAC,SAAS,CAAC,CAAA;IAChC,IACE,OAAO,OAAO,KAAK,QAAQ;QAC3B,OAAO,CAAC,MAAM,GAAG,WAAW;QAC5B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC;QACrB,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI,EACvB,CAAC;QACD,OAAO,IAAI,CAAC,aAAa,EAAE,SAAS,CAAC,CAAA;IACvC,CAAC;IAED,MAAM,UAAU,GAAG,KAAK,CAAC,aAAa,CAAC,CAAA;IACvC,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;QACxB,IAAI,OAAO,UAAU,KAAK,QAAQ,IAAI,UAAU,CAAC,MAAM,GAAG,WAAW,IAAI,KAAK,CAAC,UAAU,CAAC,KAAK,IAAI,EAAE,CAAC;YACpG,OAAO,IAAI,CAAC,aAAa,EAAE,aAAa,CAAC,CAAA;QAC3C,CAAC;IACH,CAAC;IAED,MAAM,EAAE,GAAG,KAAK,CAAC,IAAI,CAAC,CAAA;IACtB,IAAI,CAAC,WAAW,CAAC,iBAAiB,EAAE,EAAE,CAAC;QAAE,OAAO,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC,CAAA;IAEzE,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,CAAC,CAAA;IAC1B,IAAI,CAAC,WAAW,CAAC,mBAAmB,EAAE,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC,aAAa,EAAE,MAAM,CAAC,CAAA;IAE/E,MAAM,SAAS,GAAG,KAAK,CAAC,YAAY,CAAC,CAAA;IACrC,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,SAAS,CAAC,IAAI,SAAS,GAAG,EAAE,IAAI,SAAS,GAAG,EAAE,EAAE,CAAC;QACtG,OAAO,IAAI,CAAC,aAAa,EAAE,YAAY,CAAC,CAAA;IAC1C,CAAC;IAED,MAAM,WAAW,GAAG,KAAK,CAAC,cAAc,CAAC,CAAA;IACzC,IAAI,CAAC,WAAW,CAAC,2BAA2B,EAAE,WAAW,CAAC;QAAE,OAAO,IAAI,CAAC,aAAa,EAAE,cAAc,CAAC,CAAA;IAEtG,MAAM,UAAU,GAAG,KAAK,CAAC,YAAY,CAAC,CAAA;IACtC,IAAI,CAAC,WAAW,CAAC,iBAAiB,EAAE,UAAU,CAAC;QAAE,OAAO,IAAI,CAAC,aAAa,EAAE,YAAY,CAAC,CAAA;IAEzF,MAAM,SAAS,GAAG,iBAAiB,CAAC,KAAK,CAAC,oBAAoB,CAAC,EAAE,cAAc,EAAE,CAAC,IAAI,EAAE,EAAE,CACxF,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CACzB,CAAA;IACD,IAAI,SAAS,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC,aAAa,EAAE,oBAAoB,CAAC,CAAA;IAExE,MAAM,KAAK,GAAG,iBAAiB,CAAC,KAAK,CAAC,gBAAgB,CAAC,EAAE,SAAS,EAAE,CAAC,IAAI,EAAE,EAAE,CAC3E,WAAW,CAAC,oBAAoB,EAAE,IAAI,CAAC,CACxC,CAAA;IACD,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC,aAAa,EAAE,gBAAgB,CAAC,CAAA;IAEhE,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,CAAA;IAC/B,IAAI,KAAK,GAAwB,IAAI,CAAA;IACrC,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;QACtB,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC;YAAE,OAAO,IAAI,CAAC,aAAa,EAAE,OAAO,CAAC,CAAA;QACjE,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YACxC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,OAAO,IAAI,CAAC,eAAe,EAAE,SAAS,GAAG,EAAE,CAAC,CAAA;QAC1E,CAAC;QACD,mFAAmF;QACnF,iDAAiD;QACjD,IAAI,MAAM,KAAK,OAAO;YAAE,OAAO,IAAI,CAAC,aAAa,EAAE,OAAO,CAAC,CAAA;QAC3D,MAAM,KAAK,GAAG,QAAQ,CAAC,iBAAiB,CAAC,CAAA;QACzC,IAAI,CAAC,WAAW,CAAC,oBAAoB,EAAE,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC,aAAa,EAAE,uBAAuB,CAAC,CAAA;QAClG,MAAM,IAAI,GAAG,QAAQ,CAAC,gBAAgB,CAAC,CAAA;QACvC,IAAI,IAAI,KAAK,IAAI,IAAI,CAAC,WAAW,CAAC,oBAAoB,EAAE,IAAI,CAAC,EAAE,CAAC;YAC9D,OAAO,IAAI,CAAC,aAAa,EAAE,sBAAsB,CAAC,CAAA;QACpD,CAAC;QACD,KAAK,GAAG,EAAE,eAAe,EAAE,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,CAAA;IAC1D,CAAC;IAED,MAAM,MAAM,GAAkB;QAC5B,cAAc,EAAE,CAAC;QACjB,EAAE;QACF,EAAE;QACF,MAAM;QACN,OAAO,EAAE,WAAW;QACpB,OAAO;QACP,WAAW,EAAE,UAAU;QACvB,EAAE;QACF,IAAI;QACJ,UAAU,EAAE,SAAS;QACrB,YAAY,EAAE,WAAW;QACzB,UAAU;QACV,kBAAkB,EAAE,SAAS;QAC7B,cAAc,EAAE,KAAgC;QAChD,KAAK;KACN,CAAA;IAED,yFAAyF;IACzF,+BAA+B;IAC/B,KAAK,MAAM,KAAK,IAAI,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC;QAC1C,IAAI,iBAAiB,CAAC,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC,aAAa,EAAE,eAAe,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAA;IAC1F,CAAC;IAED,kFAAkF;IAClF,IAAI,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,GAAG,iBAAiB;QAAE,OAAO,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,CAAA;IAEzF,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAA;AAC7B,CAAC;AAED,qFAAqF;AACrF,SAAS,eAAe,CAAC,MAAqB,EAAE,KAAa;IAC3D,IAAI,KAAK,KAAK,MAAM,CAAC,EAAE;QAAE,OAAO,IAAI,CAAA;IACpC,IAAI,KAAK,KAAK,MAAM,CAAC,EAAE;QAAE,OAAO,IAAI,CAAA;IACpC,IAAI,KAAK,KAAK,MAAM,CAAC,OAAO;QAAE,OAAO,SAAS,CAAA;IAC9C,IAAI,KAAK,KAAK,MAAM,CAAC,OAAO;QAAE,OAAO,SAAS,CAAA;IAC9C,IAAI,KAAK,KAAK,MAAM,CAAC,WAAW;QAAE,OAAO,aAAa,CAAA;IACtD,IAAI,KAAK,KAAK,MAAM,CAAC,MAAM;QAAE,OAAO,QAAQ,CAAA;IAC5C,IAAI,KAAK,KAAK,MAAM,CAAC,EAAE;QAAE,OAAO,IAAI,CAAA;IACpC,IAAI,KAAK,KAAK,MAAM,CAAC,IAAI;QAAE,OAAO,MAAM,CAAA;IACxC,IAAI,KAAK,KAAK,MAAM,CAAC,YAAY;QAAE,OAAO,cAAc,CAAA;IACxD,IAAI,KAAK,KAAK,MAAM,CAAC,UAAU;QAAE,OAAO,YAAY,CAAA;IACpD,IAAI,MAAM,CAAC,kBAAkB,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,oBAAoB,CAAA;IAC1E,IAAI,MAAM,CAAC,cAAc,CAAC,QAAQ,CAAC,KAAqB,CAAC;QAAE,OAAO,gBAAgB,CAAA;IAClF,OAAO,OAAO,CAAA;AAChB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;IACzG,IAAI,MAAe,CAAA;IACnB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;IACvD,CAAC;IACD,MAAM,MAAM,GAAG,eAAe,CAAC,MAAM,CAAC,CAAA;IACtC,IAAI,CAAC,MAAM,CAAC,EAAE;QAAE,OAAO,MAAM,CAAA;IAC7B,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAA;AAC5C,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,YAAY,CAAC,MAAqB;IAChD,OAAO;QACL,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,GAAG,EAAE,MAAM,CAAC,WAAW;QACvB,EAAE,EAAE,MAAM,CAAC,EAAE;QACb,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,YAAY,EAAE,MAAM,CAAC,YAAY;KAClC,CAAA;AACH,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,oBAAoB,CAAC,GAAe;IAClD,OAAO,GAAG,CAAC,GAAG,KAAK,IAAI,IAAI,GAAG,CAAC,YAAY,KAAK,SAAS,CAAA;AAC3D,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,IAAgB,EAAE,KAAiB;IAChE,OAAO,CACL,IAAI,CAAC,OAAO,KAAK,KAAK,CAAC,OAAO;QAC9B,IAAI,CAAC,OAAO,KAAK,KAAK,CAAC,OAAO;QAC9B,IAAI,CAAC,GAAG,KAAK,KAAK,CAAC,GAAG;QACtB,IAAI,CAAC,EAAE,KAAK,KAAK,CAAC,EAAE;QACpB,IAAI,CAAC,IAAI,KAAK,KAAK,CAAC,IAAI;QACxB,IAAI,CAAC,UAAU,KAAK,KAAK,CAAC,UAAU;QACpC,IAAI,CAAC,YAAY,KAAK,KAAK,CAAC,YAAY,CACzC,CAAA;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAAiC,EACjC,GAAe;IAEf,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAA;IAC3C,MAAM,MAAM,GAA+B,EAAE,EAAE,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAA;IACtF,IAAI,CAAC,GAAG,CAAC,CAAA;IACT,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,CAAC,cAAc,CAAC,YAAY,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC;YAAE,SAAQ;QACxD,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,CAAA;QAC9B,CAAC,IAAI,CAAC,CAAA;IACR,CAAC;IACD,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAA;IAEtB,IAAI,QAAQ,GAAsB,IAAI,CAAA;IACtC,KAAK,MAAM,UAAU,IAAI,iBAAiB,EAAE,CAAC;QAC3C,IAAI,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,QAAQ,GAAG,UAAU,CAAA;IACvD,CAAC;IACD,OAAO;QACL,cAAc,EAAE,CAAC;QACjB,eAAe,EAAE,IAAI;QACrB,GAAG;QACH,MAAM,EAAE,gBAAgB;QACxB,MAAM,EAAE,aAAa;QACrB,CAAC;QACD,MAAM;QACN,QAAQ;QACR,SAAS,EAAE,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC;QAC1D,IAAI,EAAE,gBAAgB;QACtB,WAAW,EAAE,aAAa;QAC1B,OAAO,EAAE,uBAAuB;KACjC,CAAA;AACH,CAAC"}

package/dist/upgrade.d.ts

@@ -0,0 +1,202 @@
+/**
+ * Upgrade impact: "if I move to dsh `<target>`, which loader rows and bundles get denied?"
+ *
+ * WHAT THIS MODULE IS ALLOWED TO SAY
+ * ----------------------------------
+ * One thing per unit: **would the target runtime be admitted by the range this unit
+ * declares?** It answers that by calling `evaluateAdmission` — the same function `why`,
+ * `check`, `audit` and the panel use — with `env.dsh` replaced by the target. There is no
+ * second range implementation here on purpose: admission semantics are locked by
+ * `data/gold/admission-cases.json`, and a local copy of "engines first, then peers" would
+ * be a second rule set that drifts silently.
+ *
+ * WHAT IT REFUSES TO SAY
+ * ----------------------
+ * - "this row will *work*": a declaration being admitted is not a measurement;
+ * - anything about feature behaviour, configuration names or data migration;
+ * - anything about a plugin that is not installed (no manifest = nothing to judge);
+ * - anything about another profile. `impact.profile` names the one that was read
+ *   (`BS-38`: two profiles, two correct answers).
+ *
+ * PURITY
+ * ------
+ * No filesystem access, no network, no clock, no environment reads. Rows and bundles arrive
+ * already parsed, the timestamp arrives from the caller. Same input (in any array order) →
+ * byte-identical output: the ordering keys below form a total order and never use
+ * `localeCompare`, whose result depends on the ICU build of the machine that runs it.
+ */
+import type { AdmissionMode, AdmissionStatus, Requirement } from './admission.js';
+import { type Locale } from './messages.js';
+import type { EnvFingerprint, Reason, Remediation, Verdict } from './types.js';
+import type { RowDeclaration } from './verdict.js';
+/** The four buckets, in terminal order. A unit lands in exactly one of them. */
+export declare const UPGRADE_BUCKETS: readonly ["would-be-denied", "cannot-tell", "improved", "likely-fine"];
+export type UpgradeBucket = (typeof UPGRADE_BUCKETS)[number];
+/**
+ * Machine-readable reason for the bucket a unit landed in.
+ *
+ * `cannot-tell` is deliberately narrow: it means **admission was not established**, never
+ * "it looks fine" and never "a definite denial that we decided not to report".
+ */
+export type UpgradeCause = 'target-denied' | 'unusable-declaration' | 'no-declaration' | 'not-installed' | 'runtime-unknown' | 'denied-now-admitted-then' | 'admitted-at-target';
+/** `null` = the runtime string was absent; `invalid-runtime` = present but not a version. */
+export type UpgradeStandingStatus = AdmissionStatus | 'not-installed' | 'invalid-runtime' | null;
+export interface UpgradeStanding {
+    readonly runtime: string | null;
+    readonly status: UpgradeStandingStatus;
+    readonly mode: AdmissionMode | null;
+    /** Requirements that did not hold under **this** runtime (empty unless denied). */
+    readonly unmet: readonly Requirement[];
+}
+/** A bundle layer as the composition loader read it. */
+export interface UpgradeBundleInput {
+    readonly name: string;
+    readonly version: string | null;
+    /** Raw `package.json`; `null` when the snapshot names a bundle it does not contain. */
+    readonly manifest: unknown | null;
+}
+/**
+ * Registry lookups are **secondary evidence**: a newer published build whose declaration
+ * admits the target. They are attached as annotations and are never read while bucketing.
+ */
+export interface UpgradeRegistryFact {
+    readonly package: string;
+    readonly version: string;
+    readonly declaredRange: string;
+    /** Computed by the caller with the same `evaluateAdmission`; never recomputed here. */
+    readonly admitsTarget: boolean;
+    readonly publishedAt?: string | null;
+}
+export interface UpgradeRegistryFailure {
+    readonly package: string;
+    readonly code: string;
+    readonly detail: string;
+}
+export interface UpgradeRegistryNote {
+    readonly annotation_only: true;
+    readonly tier: 'measured-registry';
+    readonly package: string;
+    readonly version: string;
+    readonly declared_range: string;
+    readonly admits_target: boolean;
+    readonly published_at: string | null;
+    readonly note_id: 'upgrade.registry-annotation';
+}
+export interface UpgradeUnit {
+    /** `bundle:<name>` or `row:<rowId>`; unique across the list. */
+    readonly id: string;
+    readonly kind: 'bundle' | 'row';
+    /** Bundle name, or the module a row imports. */
+    readonly name: string;
+    readonly version: string | null;
+    readonly row_ids: readonly string[];
+    /** Patch layer that declares the row; `null` for a bundle. */
+    readonly source: string | null;
+    readonly bucket: UpgradeBucket;
+    readonly cause: UpgradeCause;
+    /** The current runtime denies this unit too: the upgrade did not cause the denial. */
+    readonly already_denied_at_current: boolean;
+    readonly current: UpgradeStanding;
+    readonly target: UpgradeStanding;
+    /** Exactly the remediation the same engine prints for this denial. */
+    readonly remediation: readonly Remediation[];
+    readonly reasons: readonly Reason[];
+    readonly missing_evidence: readonly string[];
+    /** Verdict at the target runtime (`env.dsh === target`); `null` when there is nothing to judge. */
+    readonly verdict: Verdict | null;
+    readonly suggestions: readonly UpgradeRegistryNote[];
+}
+export interface UpgradeCounts {
+    readonly bundles: number;
+    readonly rows: number;
+    readonly would_be_denied: number;
+    readonly cannot_tell: number;
+    readonly improved: number;
+    readonly likely_fine: number;
+    readonly total: number;
+}
+export type UpgradeRelation = 'same' | 'newer' | 'older' | 'unknown';
+export interface UpgradeImpact {
+    readonly schema_version: 1;
+    /** The profile this answer is about. Never "your setup in general". */
+    readonly profile: string;
+    readonly profile_source: 'live' | 'snapshot';
+    readonly current: string | null;
+    readonly current_valid: boolean;
+    readonly target: string;
+    readonly target_valid: true;
+    readonly target_relation: UpgradeRelation;
+    readonly buckets: readonly UpgradeBucket[];
+    readonly counts: UpgradeCounts;
+    readonly units: readonly UpgradeUnit[];
+    readonly registry: {
+        readonly consulted: boolean;
+        readonly facts: number;
+        readonly failures: readonly UpgradeRegistryFailure[];
+    };
+    readonly generated_at: string;
+}
+export type UpgradeJudgement = {
+    readonly ok: true;
+    readonly impact: UpgradeImpact;
+} | {
+    readonly ok: false;
+    readonly code: 'invalid-target';
+    readonly detail: string;
+    readonly target: string;
+};
+export interface UpgradeImpactInput {
+    /** The environment the profile was read from. `env.dsh` **is** the current runtime. */
+    readonly env: EnvFingerprint;
+    readonly target: string;
+    readonly bundles: readonly UpgradeBundleInput[];
+    readonly rows: readonly RowDeclaration[];
+    readonly generatedAt: string;
+    readonly profileSource?: 'live' | 'snapshot';
+    readonly registry?: readonly UpgradeRegistryFact[];
+    readonly registryFailures?: readonly UpgradeRegistryFailure[];
+}
+/**
+ * Validate a target before anything is read.
+ *
+ * Exposed because the CLI must reject `--to ^0.3.0` **before** it touches a profile: a
+ * usage error that depends on whether the profile exists would report the wrong thing.
+ */
+export declare function upgradeTargetProblem(target: string): string | null;
+/**
+ * Judge the impact of moving to `input.target`.
+ *
+ * The target is validated first: `semver.satisfies('0.3', '*')` returns `false` without
+ * throwing, so an unvalidated target would silently turn every unit into "denied". A bad
+ * target is a usage error, not a finding.
+ */
+export declare function judgeUpgradeImpact(input: UpgradeImpactInput): UpgradeJudgement;
+/**
+ * Turn one packument's version→manifest map into ONE annotation.
+ *
+ * Chosen here (in core, next to the range logic) rather than in the CLI, because picking
+ * "the newest version whose declaration admits the target" needs semver ordering — a second
+ * implementation of that ordering in the CLI would be exactly the kind of drift this file
+ * exists to avoid.
+ *
+ * `admitsTarget: false` is a legitimate answer: it means "I looked, and no published version
+ * declares the target". Dropping it would make the search invisible.
+ */
+export declare function registryFactFor(input: {
+    readonly packageName: string;
+    readonly versions: ReadonlyMap<string, unknown>;
+    readonly target: string;
+    readonly publishedAt?: Readonly<Record<string, string>> | null;
+}): UpgradeRegistryFact | null;
+/**
+ * Total order: bucket → kind → name → version → id.
+ *
+ * `localeCompare` is not used anywhere in this chain: it depends on the ICU build, so the
+ * same input could sort differently on two machines and the artifact would stop reproducing.
+ */
+export declare function compareUnits(left: UpgradeUnit, right: UpgradeUnit): number;
+/** Terminal rendering. Pure: locale in, text out; no colour, no clock, no width probing. */
+export declare function renderUpgradeImpact(impact: UpgradeImpact, locale: Locale): string;
+/** Convenience for callers that only need a yes/no: is anything going to be denied? */
+export declare function hasNewDenials(impact: UpgradeImpact): boolean;
+//# sourceMappingURL=upgrade.d.ts.map

package/dist/upgrade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade.d.ts","sourceRoot":"","sources":["../src/upgrade.ts"],"names":[],"mappings":"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"}