pm-ops 2026.10.27 → 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,15 @@
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
+
3
13
  ## 2026.10.27 - 2026-10-27
4
14
 
5
15
  ### Other
@@ -44,12 +54,9 @@ No tracked changes.
44
54
  ### Fixed
45
55
 
46
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))
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
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))
50
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))
51
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))
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
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))
54
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))
55
62
  - 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 +70,12 @@ No tracked changes.
63
70
  - Enable GitHub CodeQL code scanning ([ops-jasw](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/chores/ops-jasw.toon))
64
71
  - Characterize pre-existing fleet workflow scanner refusals ([ops-0u7l](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/tasks/ops-0u7l.toon))
65
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
+
66
79
  ## 2026.10.21 - 2026-10-21
67
80
 
68
81
  No tracked changes.
@@ -214,9 +227,9 @@ No tracked changes.
214
227
 
215
228
  ## 2026.9.8 - 2026-09-08
216
229
 
217
- ### Security
230
+ ### Closed
218
231
 
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))
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))
220
233
 
221
234
  ## 2026.9.7 - 2026-09-07
222
235
 
@@ -243,9 +256,9 @@ No tracked changes.
243
256
 
244
257
  ## 2026.9.5 - 2026-09-05
245
258
 
246
- ### Security
259
+ ### Closed
247
260
 
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))
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))
249
262
 
250
263
  ## 2026.9.2 - 2026-09-02
251
264
 
@@ -258,7 +271,6 @@ No tracked changes.
258
271
 
259
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))
260
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))
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
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))
263
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))
264
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))
@@ -271,10 +283,7 @@ No tracked changes.
271
283
  ### Security
272
284
 
273
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))
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
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))
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
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))
279
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))
280
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))
@@ -284,22 +293,32 @@ No tracked changes.
284
293
 
285
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))
286
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
+
287
303
  ## 2026.8.31 - 2026-08-31
288
304
 
289
- ### Fixed
305
+ ### Closed
290
306
 
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))
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))
292
308
 
293
309
  ## 2026.8.29 - 2026-08-29
294
310
 
295
311
  ### Fixed
296
312
 
297
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))
298
- - Harden literal scalar assignment parsing ([ops-mjnd](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-mjnd.toon))
299
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))
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
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))
302
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
+
303
322
  ## 2026.8.28 - 2026-08-28
304
323
 
305
324
  ### Fixed
@@ -309,18 +328,21 @@ No tracked changes.
309
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))
310
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))
311
330
 
312
- ### Security
331
+ ### Closed
313
332
 
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))
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))
315
334
 
316
335
  ## 2026.8.17 - 2026-08-17
317
336
 
318
337
  ### Fixed
319
338
 
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
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))
322
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))
323
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
+
324
346
  ## 2026.8.16 - 2026-08-16
325
347
 
326
348
  ### Added
@@ -436,14 +458,14 @@ No tracked changes.
436
458
 
437
459
  ## 2026.7.23 - 2026-07-23
438
460
 
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
461
  ### Other
444
462
 
445
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))
446
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
+
447
469
  ## 2026.7.22 - 2026-07-22
448
470
 
449
471
  No tracked changes.
@@ -489,9 +511,7 @@ No tracked changes.
489
511
 
490
512
  ## 2026.7.10 - 2026-07-10
491
513
 
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))
514
+ No tracked changes.
495
515
 
496
516
  ## 2026.7.7 - 2026-07-07
497
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
@@ -831,3 +831,86 @@ See the [SDK contract and example](docs/diagnostic-witnesses.md) and the
831
831
 
832
832
  Witness reduction works without Git, including when Git is absent from PATH.
833
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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"}