pm-ops 2026.10.26 → 2026.10.28

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,21 @@
1
1
  # Changelog
2
2
 
3
+ ## 2026.10.28 - 2026-10-28
4
+
5
+ ### Fixed
6
+
7
+ - 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))
8
+
9
+ ### Other
10
+
11
+ - 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))
12
+
13
+ ## 2026.10.27 - 2026-10-27
14
+
15
+ ### Other
16
+
17
+ - Use SDK corpus reads for backend assurance and diagnostics ([ops-sdk-adoption-1025](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/tasks/ops-sdk-adoption-1025.toon))
18
+
3
19
  ## 2026.10.26 - 2026-10-26
4
20
 
5
21
  ### Fixed
@@ -38,12 +54,9 @@ No tracked changes.
38
54
  ### Fixed
39
55
 
40
56
  - 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))
41
- - Fix release publish-before-protected-main-push ordering ([ops-gitr](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-gitr.toon))
42
- - 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))
43
57
  - 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))
44
58
  - 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))
45
59
  - 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))
46
- - 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))
47
60
  - 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))
48
61
  - 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))
49
62
  - Duplication gate scans generated PM extension copies ([ops-to4t](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-to4t.toon))
@@ -57,6 +70,12 @@ No tracked changes.
57
70
  - Enable GitHub CodeQL code scanning ([ops-jasw](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/chores/ops-jasw.toon))
58
71
  - Characterize pre-existing fleet workflow scanner refusals ([ops-0u7l](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/tasks/ops-0u7l.toon))
59
72
 
73
+ ### Closed
74
+
75
+ - 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))
76
+ - 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))
77
+ - 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))
78
+
60
79
  ## 2026.10.21 - 2026-10-21
61
80
 
62
81
  No tracked changes.
@@ -208,9 +227,9 @@ No tracked changes.
208
227
 
209
228
  ## 2026.9.8 - 2026-09-08
210
229
 
211
- ### Security
230
+ ### Closed
212
231
 
213
- - 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))
232
+ - 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))
214
233
 
215
234
  ## 2026.9.7 - 2026-09-07
216
235
 
@@ -237,9 +256,9 @@ No tracked changes.
237
256
 
238
257
  ## 2026.9.5 - 2026-09-05
239
258
 
240
- ### Security
259
+ ### Closed
241
260
 
242
- - 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))
261
+ - 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))
243
262
 
244
263
  ## 2026.9.2 - 2026-09-02
245
264
 
@@ -252,7 +271,6 @@ No tracked changes.
252
271
 
253
272
  - 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))
254
273
  - 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))
255
- - 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))
256
274
  - 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))
257
275
  - 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))
258
276
  - 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))
@@ -265,10 +283,7 @@ No tracked changes.
265
283
  ### Security
266
284
 
267
285
  - 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))
268
- - 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))
269
- - 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))
270
286
  - 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))
271
- - 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))
272
287
  - 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))
273
288
  - 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))
274
289
  - 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))
@@ -278,22 +293,32 @@ No tracked changes.
278
293
 
279
294
  - 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))
280
295
 
296
+ ### Closed
297
+
298
+ - 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))
299
+ - 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))
300
+ - 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))
301
+ - 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))
302
+
281
303
  ## 2026.8.31 - 2026-08-31
282
304
 
283
- ### Fixed
305
+ ### Closed
284
306
 
285
- - 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))
307
+ - 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))
286
308
 
287
309
  ## 2026.8.29 - 2026-08-29
288
310
 
289
311
  ### Fixed
290
312
 
291
313
  - 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))
292
- - Harden literal scalar assignment parsing ([ops-mjnd](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-mjnd.toon))
293
314
  - 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))
294
- - 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))
295
315
  - 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))
296
316
 
317
+ ### Closed
318
+
319
+ - Closed: Harden literal scalar assignment parsing ([ops-mjnd](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-mjnd.toon))
320
+ - 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))
321
+
297
322
  ## 2026.8.28 - 2026-08-28
298
323
 
299
324
  ### Fixed
@@ -303,18 +328,21 @@ No tracked changes.
303
328
  - 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))
304
329
  - 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))
305
330
 
306
- ### Security
331
+ ### Closed
307
332
 
308
- - 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))
333
+ - 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))
309
334
 
310
335
  ## 2026.8.17 - 2026-08-17
311
336
 
312
337
  ### Fixed
313
338
 
314
- - 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))
315
339
  - 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))
316
340
  - 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))
317
341
 
342
+ ### Closed
343
+
344
+ - 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))
345
+
318
346
  ## 2026.8.16 - 2026-08-16
319
347
 
320
348
  ### Added
@@ -430,14 +458,14 @@ No tracked changes.
430
458
 
431
459
  ## 2026.7.23 - 2026-07-23
432
460
 
433
- ### Fixed
434
-
435
- - 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))
436
-
437
461
  ### Other
438
462
 
439
463
  - 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))
440
464
 
465
+ ### Closed
466
+
467
+ - 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))
468
+
441
469
  ## 2026.7.22 - 2026-07-22
442
470
 
443
471
  No tracked changes.
@@ -483,9 +511,7 @@ No tracked changes.
483
511
 
484
512
  ## 2026.7.10 - 2026-07-10
485
513
 
486
- ### Fixed
487
-
488
- - 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))
514
+ No tracked changes.
489
515
 
490
516
  ## 2026.7.7 - 2026-07-07
491
517
 
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.
@@ -648,8 +648,8 @@ The repository changelog scripts require Git for release-tag windows and refuse
648
648
  plain-directory trackers with an explicit diagnostic. The changelog adapter can
649
649
  still generate directly from tracker items when invoked without tag flags.
650
650
 
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
651
+ Compatibility explanations, diagnostic witnesses, evidence expiry, backend capability diagnostics, scan, policy, status, outdated, audit, metrics,
652
+ reports and docstring analysis work in plain directories. The compatibility, witness, capability and
653
653
  evidence expiry paths never invoke Git. Release verification runs package-defined
654
654
  scripts, which may
655
655
  need Git; GitHub queries need their own credentials and network access. Configure
@@ -662,6 +662,9 @@ membership to the pinned generator, then renders empty sections as
662
662
  generator currently hardcodes `No changes.` and has no empty-message option.
663
663
  Every tag gets one section, including consecutive empty releases and same-day
664
664
  suffixes; a pending release also gets its section before its tag exists.
665
+ The adapter omits an empty `Unreleased` window above release history, so creating
666
+ the release tag does not change the committed changelog. Nonempty unreleased
667
+ work stays visible, and empty version sections retain their notes.
665
668
  Regenerating main cannot change changelogs inside historical release commits.
666
669
 
667
670
  ## Operational evidence expiry
@@ -828,3 +831,86 @@ See the [SDK contract and example](docs/diagnostic-witnesses.md) and the
828
831
 
829
832
  Witness reduction works without Git, including when Git is absent from PATH.
830
833
  It reads only the selected input file and never reads or changes tracker state.
834
+
835
+ ## Compatibility reason chains
836
+
837
+ `pm ops compatibility --input docs/examples/compatibility.json --json` explains
838
+ joint package, host and extension requirements. TOON is the default; both formats
839
+ preserve nested arrays and nulls. The example's three pins are pairwise compatible
840
+ but jointly contradictory. The report names exactly `pin-a`, `pin-b`, `pin-c` as
841
+ the minimum conflict, with `compatible_ranges: []`. Removing any one leaves a
842
+ compatible version. It also reports observed pin failures and missing capabilities,
843
+ with directed upstream declaration chains for each reason.
844
+
845
+ This is a read-only metadata preview. `commands` contains literal argv previews
846
+ for version and extension discovery; the package never executes them, resolves
847
+ packages, installs dependencies or changes configuration. Core remains authoritative
848
+ for extension admission. This command works without Git and never opens a tracker.
849
+
850
+ ```ts
851
+ import { explainCompatibility, type CompatibilityInput } from "pm-ops/compatibility-reasons";
852
+
853
+ const metadata: CompatibilityInput = {
854
+ version: 1,
855
+ components: [
856
+ { id: "package", version: "1.0.0", capabilities: [] },
857
+ { id: "host", version: "2026.10.20", capabilities: ["commands"] },
858
+ ],
859
+ requirements: [{ id: "host-peer", from: "package", to: "host",
860
+ range: ">=2026.10.20", capabilities: ["commands"],
861
+ manifest: { pm_min_version: "2026.10.20" } }],
862
+ };
863
+ const report = explainCompatibility(metadata);
864
+ ```
865
+
866
+ Every `range` uses npm semver semantics, including prerelease admission.
867
+ `compatible_ranges` is an OR of inner arrays; **every** range in an inner array
868
+ must hold. Keeping conjunctions separate preserves each declaration's prerelease
869
+ rules. A range can itself contain `||`; when expansion exceeds 16 alternatives,
870
+ one conjunction retains the original ranges exactly to keep output compact.
871
+ Joint version contradictions use exact minimum-cardinality subsets;
872
+ observed pin/support conflicts additionally rely on the target metadata shown in
873
+ the row. The report retains one minimum witness for a pin failure and all missing
874
+ capabilities. Optional native `manifest` bounds are independently evaluated through
875
+ `checkExtensionManifestCompatibility`, the SDK helper shared with core. They are
876
+ reported separately from the joint npm range intersection; include the declared
877
+ supported npm range explicitly in `range`.
878
+
879
+ Joint decisions use semver's `Range`, `intersects`, `minVersion`, `inc` and
880
+ validated observations/declarations. The solver never constructs numeric or
881
+ prerelease successor strings. Every derived library value is parsed again before
882
+ it can support a decision. A rejected value produces a typed
883
+ `UnrepresentableRangeReason` with `code: "unrepresentable_range"`, the rejected
884
+ range/conjunction and a remedy; it never proves a joint conflict. A valid observed
885
+ witness can establish a conjunction without deriving a successor, including
886
+ maximum-length prereleases. An independently verified installed-pin, capability
887
+ or native-bound conflict still remains visible alongside incomplete evidence.
888
+
889
+ A proven empty intersection survives failures while reducing its witness. The
890
+ search records each rejected subset and continues through the other candidates.
891
+ The minimum concerns parsed npm-range declarations; missing or unsupported range
892
+ declarations remain separately listed as unknown.
893
+ If smaller subsets remain undecided, `minimum_unproven: true` marks the retained
894
+ conflict: the contradiction is proven, while global minimum cardinality is not.
895
+ An undecided full set still searches for a provably conflicting subset. Within
896
+ an OR expression, an independently proven nonempty branch remains available even
897
+ when another branch cannot be represented; an unknown branch never proves emptiness.
898
+
899
+ `null` means unknown metadata; `[]` means a known empty capability declaration,
900
+ and `*` means a declared unrestricted range. Tags, workspace/file protocols,
901
+ unparseable versions and missing metadata produce `unknown`, never a fabricated
902
+ incompatibility. Known conflicts take precedence while unknown reasons stay visible.
903
+ Each target is evaluated independently. A package's arbitrary capability labels
904
+ are declared metadata, independent of backend probes or core's admission policy.
905
+
906
+ The strict version 1 schema accepts 1–16 unique components and 1–12 unique directed
907
+ requirements, 1–96 character public ids, strings of at most 256 characters, and at
908
+ most 16 unique capabilities per declaration. Input arrays must be dense, unknown
909
+ keys are refused, and files must be regular JSON no larger than 64 KiB. Up to 256
910
+ expanded alternatives per target bound the exact search. Cycles terminate; a
911
+ rootless cycle retains the local declaration. Typed `CompatibilityRefusal` errors
912
+ carry `code`, `remedy` and usage exit code 2. `ok` is false for unknown or
913
+ incompatible rows; a completed explanation still exits successfully so agents
914
+ should inspect `ok` and row status. Counts are checked for finite integer bounds.
915
+
916
+ 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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"}