pm-ops 2026.10.27 → 2026.10.29

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,19 @@
1
1
  # Changelog
2
2
 
3
+ ## 2026.10.29 - 2026-10-29
4
+
5
+ No tracked changes.
6
+
7
+ ## 2026.10.28 - 2026-10-28
8
+
9
+ ### Fixed
10
+
11
+ - Keep release changelog bytes stable when the pending version becomes a tag ([ops-release-changelog-stability](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-release-changelog-stability.toon))
12
+
13
+ ### Other
14
+
15
+ - Stop Hound from linting generated dist/ output ([ops-hound-generated-dist](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/chores/ops-hound-generated-dist.toon))
16
+
3
17
  ## 2026.10.27 - 2026-10-27
4
18
 
5
19
  ### Other
@@ -44,12 +58,9 @@ No tracked changes.
44
58
  ### Fixed
45
59
 
46
60
  - A release run bumped and committed a new version every night while publishing was impossible, because the only externally-failable step runs last ([ops-e9g6](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-e9g6.toon))
47
- - Fix release publish-before-protected-main-push ordering ([ops-gitr](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-gitr.toon))
48
- - A parenthesised command inside a case arm is read as an arm label, refusing a publish the shell attests ([ops-vkvy](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-vkvy.toon))
49
61
  - Self-hosted pm-changelog is reported not ready because it does not depend on itself ([ops-pksh](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-pksh.toon))
50
62
  - Adding a source file breaks the coverage gate in three places, and none of them says so ([ops-cl0o](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-cl0o.toon))
51
63
  - Recognize third-party publish wrappers (semantic-release, np, release-it, lerna publish, changeset publish) in the canonical attestation auditor ([ops-third-party-publish-wrappers](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-third-party-publish-wrappers.toon))
52
- - A hardcoded fixture date aged out of the seven day window and broke the daily release ([ops-i2iz](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-i2iz.toon))
53
64
  - The release completeness audit reported a published version and its GitHub Release as missing, turning a successful release into a failed one ([ops-fcow](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-fcow.toon))
54
65
  - Guarded merge-driver launcher: omit-dev clone installs complete instead of failing on the devDependency import ([ops-mqdi](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-mqdi.toon))
55
66
  - Duplication gate scans generated PM extension copies ([ops-to4t](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-to4t.toon))
@@ -63,6 +74,12 @@ No tracked changes.
63
74
  - Enable GitHub CodeQL code scanning ([ops-jasw](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/chores/ops-jasw.toon))
64
75
  - Characterize pre-existing fleet workflow scanner refusals ([ops-0u7l](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/tasks/ops-0u7l.toon))
65
76
 
77
+ ### Closed
78
+
79
+ - Closed: Fix release publish-before-protected-main-push ordering ([ops-gitr](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-gitr.toon))
80
+ - Closed: A parenthesised command inside a case arm is read as an arm label, refusing a publish the shell attests ([ops-vkvy](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-vkvy.toon))
81
+ - Closed: A hardcoded fixture date aged out of the seven day window and broke the daily release ([ops-i2iz](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-i2iz.toon))
82
+
66
83
  ## 2026.10.21 - 2026-10-21
67
84
 
68
85
  No tracked changes.
@@ -214,9 +231,9 @@ No tracked changes.
214
231
 
215
232
  ## 2026.9.8 - 2026-09-08
216
233
 
217
- ### Security
234
+ ### Closed
218
235
 
219
- - An assignment the scanner cannot read leaves the previous binding standing, so a replaced provenance flag still attests the publish ([ops-3wbz](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-3wbz.toon))
236
+ - Closed: An assignment the scanner cannot read leaves the previous binding standing, so a replaced provenance flag still attests the publish ([ops-3wbz](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-3wbz.toon))
220
237
 
221
238
  ## 2026.9.7 - 2026-09-07
222
239
 
@@ -243,9 +260,9 @@ No tracked changes.
243
260
 
244
261
  ## 2026.9.5 - 2026-09-05
245
262
 
246
- ### Security
263
+ ### Closed
247
264
 
248
- - The merge-driver test builds a shell command from an environment-controlled path, which is the pattern this repository asks every other one to stop using ([ops-6no1](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-6no1.toon))
265
+ - Closed: The merge-driver test builds a shell command from an environment-controlled path, which is the pattern this repository asks every other one to stop using ([ops-6no1](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-6no1.toon))
249
266
 
250
267
  ## 2026.9.2 - 2026-09-02
251
268
 
@@ -258,7 +275,6 @@ No tracked changes.
258
275
 
259
276
  - Finish shell-accurate heredoc and unset handling in publish attestation ([ops-62d1](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-62d1.toon))
260
277
  - Repaired the ops-5jp6 history drift that had blocked two stacked release pull requests ([ops-yxej](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-yxej.toon))
261
- - A case opener sharing its first arm cleared the outer scope and refused a genuinely attested publish ([ops-cout](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-cout.toon))
262
278
  - Three shell-scope and quoting fail-opens attest unproven npm publishes ([ops-p9lb](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-p9lb.toon))
263
279
  - A malformed npm reply crashed the release audit, and the docstring already promised it would not ([ops-f5m7](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-f5m7.toon))
264
280
  - The revert-proof test read its vulnerable fixture from origin/main, so merging it would have turned it red ([ops-9ktn](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-9ktn.toon))
@@ -271,10 +287,7 @@ No tracked changes.
271
287
  ### Security
272
288
 
273
289
  - A heredoc body and a discarded binding both let an unattested publish pass the attestation gate ([ops-5jp6](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-5jp6.toon))
274
- - Four more fail modes in the canonical gate: an arm pattern read as an opener, an escaped run key read as data, a sequence marker missing from the indent, and composite actions unscanned ([ops-cxrx](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-cxrx.toon))
275
- - Attributing a case arm label by presence rather than position refused an attested publish, and a quoted key hid a phantom one ([ops-setc](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-setc.toon))
276
290
  - An arm that opens a nested case skipped the sibling reset, so a publish could borrow a flag from a mutually exclusive arm ([ops-rsbn](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-rsbn.toon))
277
- - Skipping the sibling-arm reset for any depth-increasing segment let a later arm borrow the previous arm's binding ([ops-narm](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-narm.toon))
278
291
  - A tracked executable whose name merely ends in package.json has its publish hidden from the audit ([ops-fnbd](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-fnbd.toon))
279
292
  - A case opener sharing a segment with its first arm leaks that arm's binding past esac ([ops-csop](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-csop.toon))
280
293
  - Branch-local and compound-line publish bindings let an unattested npm publish pass the attestation gate ([ops-brsc](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-brsc.toon))
@@ -284,22 +297,32 @@ No tracked changes.
284
297
 
285
298
  - Converge the pinned pm-cli on 2026.8.31 and repair history hashes ([ops-uulf](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/chores/ops-uulf.toon))
286
299
 
300
+ ### Closed
301
+
302
+ - Closed: Four more fail modes in the canonical gate: an arm pattern read as an opener, an escaped run key read as data, a sequence marker missing from the indent, and composite actions unscanned ([ops-cxrx](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-cxrx.toon))
303
+ - Closed: Attributing a case arm label by presence rather than position refused an attested publish, and a quoted key hid a phantom one ([ops-setc](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-setc.toon))
304
+ - Closed: Skipping the sibling-arm reset for any depth-increasing segment let a later arm borrow the previous arm's binding ([ops-narm](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-narm.toon))
305
+ - Closed: A case opener sharing its first arm cleared the outer scope and refused a genuinely attested publish ([ops-cout](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-cout.toon))
306
+
287
307
  ## 2026.8.31 - 2026-08-31
288
308
 
289
- ### Fixed
309
+ ### Closed
290
310
 
291
- - The release changelog remained Unreleased after the release tag was created ([ops-3ete](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-3ete.toon))
311
+ - Closed: The release changelog remained Unreleased after the release tag was created ([ops-3ete](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-3ete.toon))
292
312
 
293
313
  ## 2026.8.29 - 2026-08-29
294
314
 
295
315
  ### Fixed
296
316
 
297
317
  - Prevent a failed provenance publish from silently falling back to an unattested publish ([ops-w3ke](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-w3ke.toon))
298
- - Harden literal scalar assignment parsing ([ops-mjnd](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-mjnd.toon))
299
318
  - Escaped shell metacharacter in scalar value bypasses the attestation gate ([ops-5mv7](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-5mv7.toon))
300
- - Shell scalar assignments were read from raw text, so a comment could make an unattested publish pass the attestation gate ([ops-q6wi](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-q6wi.toon))
301
319
  - A multi-line fixture joined with a literal backslash-n made the array-flag case pass without exercising it ([ops-xmb6](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-xmb6.toon))
302
320
 
321
+ ### Closed
322
+
323
+ - Closed: Harden literal scalar assignment parsing ([ops-mjnd](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-mjnd.toon))
324
+ - Closed: Shell scalar assignments were read from raw text, so a comment could make an unattested publish pass the attestation gate ([ops-q6wi](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-q6wi.toon))
325
+
303
326
  ## 2026.8.28 - 2026-08-28
304
327
 
305
328
  ### Fixed
@@ -309,18 +332,21 @@ No tracked changes.
309
332
  - The changelog gate stamps an untagged version with the current date, so its verdict flips every midnight with no commit ([ops-vll0](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-vll0.toon))
310
333
  - Canonicalize fleet metric reads and enforce the pm 2026.8.20 host contract ([ops-3w9m](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-3w9m.toon))
311
334
 
312
- ### Security
335
+ ### Closed
313
336
 
314
- - The identity gate deadlocks the one remediation its own failure message prescribes ([ops-wsi9](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-wsi9.toon))
337
+ - Closed: The identity gate deadlocks the one remediation its own failure message prescribes ([ops-wsi9](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-wsi9.toon))
315
338
 
316
339
  ## 2026.8.17 - 2026-08-17
317
340
 
318
341
  ### Fixed
319
342
 
320
- - merge-receipts labels two canonical fence patterns as stale, inviting someone to delete extension merge protection ([ops-github-db3225403a4b-44](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-github-db3225403a4b-44.toon))
321
343
  - The pm CLI compatibility floor was declared only in peerDependencies, which only npm enforces, and not in manifest.json pm_min_version, which is the field the CLI enforces ([ops-zl7a](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-zl7a.toon))
322
344
  - A truncated list-all answer corrupts fleet throughput and cycle-time metrics ([ops-x3wc](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-x3wc.toon))
323
345
 
346
+ ### Closed
347
+
348
+ - Closed: merge-receipts labels two canonical fence patterns as stale, inviting someone to delete extension merge protection ([ops-github-db3225403a4b-44](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-github-db3225403a4b-44.toon))
349
+
324
350
  ## 2026.8.16 - 2026-08-16
325
351
 
326
352
  ### Added
@@ -436,14 +462,14 @@ No tracked changes.
436
462
 
437
463
  ## 2026.7.23 - 2026-07-23
438
464
 
439
- ### Fixed
440
-
441
- - Recommend pm merge reconcile (2026.7.22) over raw history-repair in Multi-agent merge safety docs ([ops-owhy](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-owhy.toon))
442
-
443
465
  ### Other
444
466
 
445
467
  - Adopt pm field-aware merge driver for multi-agent branch-merge safety ([ops-3ype](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/chores/ops-3ype.toon))
446
468
 
469
+ ### Closed
470
+
471
+ - Closed: Recommend pm merge reconcile (2026.7.22) over raw history-repair in Multi-agent merge safety docs ([ops-owhy](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-owhy.toon))
472
+
447
473
  ## 2026.7.22 - 2026-07-22
448
474
 
449
475
  No tracked changes.
@@ -489,9 +515,7 @@ No tracked changes.
489
515
 
490
516
  ## 2026.7.10 - 2026-07-10
491
517
 
492
- ### Fixed
493
-
494
- - Fix manifest: add schema capability so registerCommand flags load (extension failed to activate) ([ops-tg86](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/tasks/ops-tg86.toon))
518
+ No tracked changes.
495
519
 
496
520
  ## 2026.7.7 - 2026-07-07
497
521
 
package/README.md CHANGED
@@ -33,7 +33,7 @@ activation.
33
33
 
34
34
  ### Without git
35
35
 
36
- Tracker metrics, policy checks and file-based reports work in plain directories.
36
+ Compatibility explanations, tracker metrics, policy checks and file-based reports work in plain directories.
37
37
  GitHub probes, release inventory/repair and changelog generation from tags need a
38
38
  git repository and their provider tools. Git-only checks do not certify a plain
39
39
  tracker as a release checkout.
@@ -154,9 +154,11 @@ npm run verify:release-completeness
154
154
  npm run verify:release-completeness -- --repair
155
155
  ```
156
156
 
157
- The default audits the git tag, published npm version, and GitHub Release inventories without writes. The daily release job explicitly opts into repair after its current release step, including days with no new release. Repair is outside `release:check` and `prepublishOnly`.
157
+ Before publication, `npm run verify:release-changelog-sections` checks every historical release and the pending `package.json.version`, including a version that has no tag yet. Each required version must have exactly one nonempty changelog section. This check runs in `release:check` and `prepublishOnly`; a missing, duplicated or empty pending section prevents the release commit. Historical tags and the package coordinate use the same version normalization, and an already-tagged package version is checked once.
158
158
 
159
- Repair completes missing remote tags and GitHub Releases only for already published calendar versions. It uses `npm audit signatures --json --include-attestations` in a disposable installation with lifecycle scripts disabled, requiring one verified SLSA v1 source repository and full commit. The signed workflow source must be an ancestor of the tag commit, which must match npm `gitHead`. Complete canonical tarball manifests must match a script-disabled pack of that tag tree: normalized paths, regular-file/directory types, modes, sizes, link targets and streamed SHA-512 content hashes. Links, special/unknown entry kinds, unsafe paths, duplicates and case/Unicode collisions refuse repair. Only npm-rewritten ownership and timestamp fields are excluded; see [the archive comparison policy](docs/tarball-manifests.md) for the exact list and supported archive formats. The downloaded tarball must also retain its signed SHA-512 integrity. A workflow can attest its trigger before committing release metadata; ancestry alone never proves the published bytes. The package name, version, repository, local/remote tag commits, and committed `package.json` must agree. Release notes come from exactly one nonempty version section in that commit's `CHANGELOG.md`, never from the working tree. Both source and release commits must already be available locally; repair does not guess a commit or fetch arbitrary objects.
159
+ The completeness audit checks the git tag, published npm version, and GitHub Release inventories without writes. The daily release job explicitly opts into repair after its current release step, including days with no new release. Repair is outside `release:check` and `prepublishOnly`.
160
+
161
+ Repair completes missing remote tags and GitHub Releases only for already published calendar versions. It uses `npm audit signatures --json --include-attestations` in a disposable installation with lifecycle scripts disabled, requiring one verified SLSA v1 source repository and full commit. The signed workflow source must be an ancestor of the tag commit, which must match npm `gitHead`. Complete canonical tarball manifests must match a script-disabled pack of that tag tree: normalized paths, regular-file/directory types, modes, sizes, link targets and streamed SHA-512 content hashes. Links, special/unknown entry kinds, unsafe paths, duplicates and case/Unicode collisions refuse repair. Only npm-rewritten ownership and timestamp fields are excluded; see [the archive comparison policy](docs/tarball-manifests.md) for the exact list and supported archive formats. The downloaded tarball must also retain its signed SHA-512 integrity. A workflow can attest its trigger before committing release metadata; ancestry alone never proves the published bytes. The package name, version, repository, local/remote tag commits, and committed `package.json` must agree. Release notes primarily come from exactly one nonempty version section in that commit's `CHANGELOG.md`. If historical notes are unusable, repair can recover the version's section from the audit-time committed `HEAD:CHANGELOG.md`; that section must satisfy the same exact-one, nonempty rule. Working-tree edits never supply notes. Both source and release commits must already be available locally; repair does not guess a commit or fetch arbitrary objects.
160
162
 
161
163
  GitHub tag lookup returns typed `github_release_absent` evidence for HTTP 404 with an access-check remedy; other read failures remain failures. Handled API diagnostics are captured instead of leaking an unexplained stderr line.
162
164
 
@@ -648,9 +650,9 @@ The repository changelog scripts require Git for release-tag windows and refuse
648
650
  plain-directory trackers with an explicit diagnostic. The changelog adapter can
649
651
  still generate directly from tracker items when invoked without tag flags.
650
652
 
651
- Diagnostic witnesses, evidence expiry, backend capability diagnostics, scan, policy, status, outdated, audit, metrics,
652
- reports and docstring analysis work in plain directories. The witness, capability and
653
- evidence expiry paths never invoke Git. Release verification runs package-defined
653
+ Re-verification plans, compatibility explanations, diagnostic witnesses, evidence expiry, backend capability diagnostics, scan, policy, status, outdated, audit, metrics,
654
+ reports and docstring analysis work in plain directories. The compatibility, witness, capability and
655
+ evidence expiry and re-verification paths never invoke Git. Release verification runs package-defined
654
656
  scripts, which may
655
657
  need Git; GitHub queries need their own credentials and network access. Configure
656
658
  and validate those requirements separately.
@@ -667,6 +669,26 @@ the release tag does not change the committed changelog. Nonempty unreleased
667
669
  work stays visible, and empty version sections retain their notes.
668
670
  Regenerating main cannot change changelogs inside historical release commits.
669
671
 
672
+ ## Cheapest valid re-verification plans
673
+
674
+ `pm ops reverify` selects the exact cheapest approved dependency closure that
675
+ can repair explicitly requested stale claims. Shared prerequisites appear once,
676
+ and every target has fresh evidence, a conditional rerun check or an explicit
677
+ gap with a remedy. It reuses evidence expiry and the caller's existing runner;
678
+ planning does not execute checks or create assurance evidence.
679
+
680
+ ```sh
681
+ pm ops reverify --input docs/examples/reverification.json --policy docs/examples/reverification-policy.json --versions docs/examples/evidence-versions.json --json
682
+ ```
683
+
684
+ TOON is the default. Both formats retain every target and unique ordered step.
685
+ The typed `pm-ops/reverification-plans` SDK exports `compileReverificationPlan`,
686
+ `parseReverificationInput`, `parseReverificationPlan` and `auditReverificationFiles`.
687
+ Integer costs, explicit approvals and a maximum of 18 checks make optimality
688
+ exact and bounded. The example costs 6 versus 16 for rerunning all approved
689
+ checks. `ok` means complete repair coverage; only a new accepted receipt can
690
+ make a rerun claim fresh. See the [contract and SDK example](docs/reverification-plans.md).
691
+
670
692
  ## Operational evidence expiry
671
693
 
672
694
  `pm ops evidence-expiry` checks whether retained health, coverage and recovery
@@ -831,3 +853,86 @@ See the [SDK contract and example](docs/diagnostic-witnesses.md) and the
831
853
 
832
854
  Witness reduction works without Git, including when Git is absent from PATH.
833
855
  It reads only the selected input file and never reads or changes tracker state.
856
+
857
+ ## Compatibility reason chains
858
+
859
+ `pm ops compatibility --input docs/examples/compatibility.json --json` explains
860
+ joint package, host and extension requirements. TOON is the default; both formats
861
+ preserve nested arrays and nulls. The example's three pins are pairwise compatible
862
+ but jointly contradictory. The report names exactly `pin-a`, `pin-b`, `pin-c` as
863
+ the minimum conflict, with `compatible_ranges: []`. Removing any one leaves a
864
+ compatible version. It also reports observed pin failures and missing capabilities,
865
+ with directed upstream declaration chains for each reason.
866
+
867
+ This is a read-only metadata preview. `commands` contains literal argv previews
868
+ for version and extension discovery; the package never executes them, resolves
869
+ packages, installs dependencies or changes configuration. Core remains authoritative
870
+ for extension admission. This command works without Git and never opens a tracker.
871
+
872
+ ```ts
873
+ import { explainCompatibility, type CompatibilityInput } from "pm-ops/compatibility-reasons";
874
+
875
+ const metadata: CompatibilityInput = {
876
+ version: 1,
877
+ components: [
878
+ { id: "package", version: "1.0.0", capabilities: [] },
879
+ { id: "host", version: "2026.10.20", capabilities: ["commands"] },
880
+ ],
881
+ requirements: [{ id: "host-peer", from: "package", to: "host",
882
+ range: ">=2026.10.20", capabilities: ["commands"],
883
+ manifest: { pm_min_version: "2026.10.20" } }],
884
+ };
885
+ const report = explainCompatibility(metadata);
886
+ ```
887
+
888
+ Every `range` uses npm semver semantics, including prerelease admission.
889
+ `compatible_ranges` is an OR of inner arrays; **every** range in an inner array
890
+ must hold. Keeping conjunctions separate preserves each declaration's prerelease
891
+ rules. A range can itself contain `||`; when expansion exceeds 16 alternatives,
892
+ one conjunction retains the original ranges exactly to keep output compact.
893
+ Joint version contradictions use exact minimum-cardinality subsets;
894
+ observed pin/support conflicts additionally rely on the target metadata shown in
895
+ the row. The report retains one minimum witness for a pin failure and all missing
896
+ capabilities. Optional native `manifest` bounds are independently evaluated through
897
+ `checkExtensionManifestCompatibility`, the SDK helper shared with core. They are
898
+ reported separately from the joint npm range intersection; include the declared
899
+ supported npm range explicitly in `range`.
900
+
901
+ Joint decisions use semver's `Range`, `intersects`, `minVersion`, `inc` and
902
+ validated observations/declarations. The solver never constructs numeric or
903
+ prerelease successor strings. Every derived library value is parsed again before
904
+ it can support a decision. A rejected value produces a typed
905
+ `UnrepresentableRangeReason` with `code: "unrepresentable_range"`, the rejected
906
+ range/conjunction and a remedy; it never proves a joint conflict. A valid observed
907
+ witness can establish a conjunction without deriving a successor, including
908
+ maximum-length prereleases. An independently verified installed-pin, capability
909
+ or native-bound conflict still remains visible alongside incomplete evidence.
910
+
911
+ A proven empty intersection survives failures while reducing its witness. The
912
+ search records each rejected subset and continues through the other candidates.
913
+ The minimum concerns parsed npm-range declarations; missing or unsupported range
914
+ declarations remain separately listed as unknown.
915
+ If smaller subsets remain undecided, `minimum_unproven: true` marks the retained
916
+ conflict: the contradiction is proven, while global minimum cardinality is not.
917
+ An undecided full set still searches for a provably conflicting subset. Within
918
+ an OR expression, an independently proven nonempty branch remains available even
919
+ when another branch cannot be represented; an unknown branch never proves emptiness.
920
+
921
+ `null` means unknown metadata; `[]` means a known empty capability declaration,
922
+ and `*` means a declared unrestricted range. Tags, workspace/file protocols,
923
+ unparseable versions and missing metadata produce `unknown`, never a fabricated
924
+ incompatibility. Known conflicts take precedence while unknown reasons stay visible.
925
+ Each target is evaluated independently. A package's arbitrary capability labels
926
+ are declared metadata, independent of backend probes or core's admission policy.
927
+
928
+ The strict version 1 schema accepts 1–16 unique components and 1–12 unique directed
929
+ requirements, 1–96 character public ids, strings of at most 256 characters, and at
930
+ most 16 unique capabilities per declaration. Input arrays must be dense, unknown
931
+ keys are refused, and files must be regular JSON no larger than 64 KiB. Up to 256
932
+ expanded alternatives per target bound the exact search. Cycles terminate; a
933
+ rootless cycle retains the local declaration. Typed `CompatibilityRefusal` errors
934
+ carry `code`, `remedy` and usage exit code 2. `ok` is false for unknown or
935
+ incompatible rows; a completed explanation still exits successfully so agents
936
+ should inspect `ok` and row status. Counts are checked for finite integer bounds.
937
+
938
+ See the [public tracker and packed validation](docs/compatibility-validation.md).
@@ -0,0 +1,124 @@
1
+ import type { ExtensionManifestCompatibilityCode } from "@unbrained/pm-cli/sdk/authoring";
2
+ /** Explicit metadata; null means unknown, while an empty capability list means known empty. */
3
+ export interface CompatibilityComponent {
4
+ /** Public metadata identity, independent of package resolution or paths. */
5
+ id: string;
6
+ /** Observed exact semantic version, or null when unavailable. */
7
+ version: string | null;
8
+ /** Exhaustive declared support, or null when unavailable. */
9
+ capabilities: string[] | null;
10
+ }
11
+ /** One directed declaration from a package or extension to its dependency or host. */
12
+ export interface CompatibilityRequirement {
13
+ /** Unique declaration identity. */
14
+ id: string;
15
+ /** Declaring component. */
16
+ from: string;
17
+ /** Required component. */
18
+ to: string;
19
+ /** npm semantic version range; null is unknown, * is explicitly unrestricted. */
20
+ range: string | null;
21
+ /** Required capabilities; null is unknown, [] explicitly requires none. */
22
+ capabilities: string[] | null;
23
+ /** Optional native extension bounds, evaluated by the public SDK against the target. */
24
+ manifest?: {
25
+ pm_min_version?: string;
26
+ pm_max_version?: string;
27
+ };
28
+ }
29
+ /** Versioned strict input; at most 16 components and 12 requirements. */
30
+ export interface CompatibilityInput {
31
+ /** Input contract version. */
32
+ version: 1;
33
+ /** Unique observed components. */
34
+ components: CompatibilityComponent[];
35
+ /** Unique directed declarations; cycles are permitted. */
36
+ requirements: CompatibilityRequirement[];
37
+ }
38
+ /** Actionable refusal that never includes supplied paths or raw parser errors. */
39
+ export declare class CompatibilityRefusal extends Error {
40
+ /** Stable machine-readable classification. */
41
+ readonly code: "invalid_compatibility_input" | "compatibility_input_unreadable" | "invalid_compatibility_output" | "compatibility_sdk_unavailable";
42
+ /** Safe recovery guidance. */
43
+ readonly remedy: string;
44
+ /** Invalid input is a usage error. */
45
+ readonly exitCode = 2;
46
+ /** Construct a sanitized refusal. */
47
+ constructor(code: CompatibilityRefusal["code"], remedy: string);
48
+ }
49
+ /** One established conflict; minimum cardinality is certified unless explicitly unproven. */
50
+ export interface CompatibilityConflict {
51
+ /** Joint declarations, observed pin, capability declaration, or native admission finding. */
52
+ code: "joint_range_conflict" | "installed_pin_conflict" | "capability_conflict" | "extension_bound_conflict";
53
+ /** Exact declaration ids; installed pin/support is explicit in the row's component. */
54
+ requirements: string[];
55
+ /** Conflicting capability or native SDK code, if relevant. */
56
+ detail: string;
57
+ /** A smaller candidate was unrepresentable; the retained contradiction is still proven. */
58
+ minimum_unproven?: true;
59
+ }
60
+ /** A rejected library value is incomplete evidence, never proof of an empty version domain. */
61
+ export interface UnrepresentableRangeReason {
62
+ /** Declaration that could not be evaluated. */
63
+ requirement: string;
64
+ /** Stable discriminant for conservative domain refusals. */
65
+ code: "unrepresentable_range";
66
+ /** Exact range or conjunction the library could not represent. */
67
+ range: string;
68
+ /** Safe action without installs or configuration edits. */
69
+ remedy: string;
70
+ }
71
+ /** Metadata gaps and native SDK advisories remain distinct from range representation failures. */
72
+ export type CompatibilityUnknownReason = UnrepresentableRangeReason | {
73
+ /** Declaration owning the incomplete evidence. */
74
+ requirement: string;
75
+ /** Missing metadata or the native SDK's own diagnostic. */
76
+ code: "range_unknown" | "version_unknown" | "capabilities_unknown" | ExtensionManifestCompatibilityCode;
77
+ };
78
+ /** Compact explanation for a component with incoming constraints. */
79
+ export interface CompatibilityRow {
80
+ /** Observed target metadata, including unknowns. */
81
+ component: CompatibilityComponent;
82
+ /** Incompatibility takes precedence; unknowns remain visible independently. */
83
+ status: "compatible" | "incompatible" | "unknown";
84
+ /** OR of conjunctions (all ranges in each inner array must hold). Preserves npm prerelease rules. */
85
+ compatible_ranges: string[][] | null;
86
+ /** Proven witnesses per conflict dimension; uncertain global minima are explicitly marked. */
87
+ conflicts: CompatibilityConflict[];
88
+ /** Declaration ids with incomplete metadata and a reason code. */
89
+ unknown: CompatibilityUnknownReason[];
90
+ /** Deterministic shortest upstream paths ending at relevant declarations; ids refer to declarations. */
91
+ chains: string[][];
92
+ /** Next safe step; never an authorization or automatic change. */
93
+ remedy: string;
94
+ }
95
+ /** Bounded report; ok means every declared check is compatible, never admission authorization. */
96
+ export interface CompatibilityReport {
97
+ /** Report contract version. */
98
+ version: 1;
99
+ /** True only with no conflicts or unknowns. */
100
+ ok: boolean;
101
+ /** Evaluation is observational. */
102
+ preview: true;
103
+ /** Complete declarations so every reason chain is self-contained. */
104
+ requirements: CompatibilityRequirement[];
105
+ /** One row per referenced target, sorted by id. */
106
+ rows: CompatibilityRow[];
107
+ /** Finite bounded outcome counts. */
108
+ counts: {
109
+ compatible: number;
110
+ incompatible: number;
111
+ unknown: number;
112
+ };
113
+ /** Literal argv previews, never executed. */
114
+ commands: string[][];
115
+ }
116
+ /** One strict structural schema shared by SDK and file producers; metadata text stays verbatim. */
117
+ export declare function parseCompatibilityInput(value: unknown): CompatibilityInput;
118
+ /** Check every emitted numeric field before returning a successful report. */
119
+ export declare function validateCompatibilityCounts(counts: CompatibilityReport["counts"], rowCount: number): void;
120
+ /** Explain joint declarations without loading extensions, invoking commands or touching tracker state. */
121
+ export declare function explainCompatibility(value: unknown): CompatibilityReport;
122
+ /** Read at most 64 KiB of regular JSON; no shell, Git, installs or configuration edits. */
123
+ export declare function readCompatibilityReasons(path: string): CompatibilityReport;
124
+ //# sourceMappingURL=compatibility-reasons.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"compatibility-reasons.d.ts","sourceRoot":"","sources":["../compatibility-reasons.ts"],"names":[],"mappings":"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"}