peaks-loop 4.2.2 → 4.2.4

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.
Files changed (51) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/CHANGELOG.md +109 -0
  3. package/dist/cli/commands/code-context-now-command.js +8 -3
  4. package/dist/cli/commands/code-context-now-envelope.d.ts +27 -2
  5. package/dist/cli/commands/code-context-now-envelope.js +47 -2
  6. package/dist/cli/commands/compact-harness-window-command.js +19 -111
  7. package/dist/cli/commands/compact-harness-window-opt-out.d.ts +4 -0
  8. package/dist/cli/commands/compact-harness-window-opt-out.js +76 -0
  9. package/dist/cli/commands/compact-harness-window-percent.d.ts +39 -0
  10. package/dist/cli/commands/compact-harness-window-percent.js +78 -0
  11. package/dist/cli/commands/compact-harness-window-reports.d.ts +8 -0
  12. package/dist/cli/commands/compact-harness-window-reports.js +149 -0
  13. package/dist/cli/commands/workspace/init-actions.d.ts +2 -0
  14. package/dist/cli/commands/workspace/init-actions.js +15 -1
  15. package/dist/cli/commands/workspace/init-command.js +1 -1
  16. package/dist/cli/commands/workspace/init-envelope.d.ts +2 -1
  17. package/dist/cli/commands/workspace/init-envelope.js +18 -1
  18. package/dist/cli/commands/workspace/init-harness-threshold.d.ts +30 -0
  19. package/dist/cli/commands/workspace/init-harness-threshold.js +134 -0
  20. package/dist/services/context/auto-compact-reader.d.ts +6 -5
  21. package/dist/services/context/auto-compact-reader.js +24 -27
  22. package/dist/services/context/harness-compact-threshold-config.d.ts +178 -0
  23. package/dist/services/context/harness-compact-threshold-config.js +166 -0
  24. package/dist/services/context/harness-compact-threshold-ensure.d.ts +90 -0
  25. package/dist/services/context/harness-compact-threshold-ensure.js +158 -0
  26. package/dist/services/context/harness-compact-threshold-refusal.d.ts +39 -0
  27. package/dist/services/context/harness-compact-threshold-refusal.js +122 -0
  28. package/dist/services/context/harness-compact-threshold-reset-types.d.ts +59 -0
  29. package/dist/services/context/harness-compact-threshold-reset-types.js +9 -0
  30. package/dist/services/context/harness-compact-threshold-reset.d.ts +48 -0
  31. package/dist/services/context/harness-compact-threshold-reset.js +215 -0
  32. package/dist/services/context/harness-compact-threshold-verdict.d.ts +71 -0
  33. package/dist/services/context/harness-compact-threshold-verdict.js +124 -0
  34. package/dist/services/context/harness-percent-gates.d.ts +35 -0
  35. package/dist/services/context/harness-percent-gates.js +102 -0
  36. package/dist/services/context/harness-percent-ownership.d.ts +126 -0
  37. package/dist/services/context/harness-percent-ownership.js +200 -0
  38. package/dist/services/context/harness-settings-file.d.ts +70 -0
  39. package/dist/services/context/harness-settings-file.js +83 -0
  40. package/dist/services/context/harness-window-config.d.ts +53 -141
  41. package/dist/services/context/harness-window-config.js +58 -296
  42. package/dist/services/context/harness-window-opt-out.d.ts +67 -0
  43. package/dist/services/context/harness-window-opt-out.js +241 -0
  44. package/dist/services/context/harness-window-ownership.d.ts +49 -0
  45. package/dist/services/context/harness-window-ownership.js +130 -0
  46. package/dist/services/ide/adapters/claude-code-adapter.d.ts +9 -9
  47. package/dist/services/ide/adapters/claude-code-adapter.js +5 -5
  48. package/dist/services/ide/ide-compact-types.d.ts +23 -4
  49. package/dist/services/ide/shared/safe-path.d.ts +18 -0
  50. package/dist/services/ide/shared/safe-path.js +34 -1
  51. package/package.json +6 -6
@@ -0,0 +1,35 @@
1
+ /**
2
+ * Harness auto-compact THRESHOLD percent — THE GATES, in order.
3
+ *
4
+ * Split out of `harness-compact-threshold-config.ts` so the writer stays under
5
+ * the file-size cap and so the order of the gates can be read (and tested) on
6
+ * its own. `syncHarnessPercent` is the only caller.
7
+ *
8
+ * Order is load-bearing and is the window writer's: opt-out and the home guard
9
+ * first (they are about WHERE), then "no value asked for", then the band (an
10
+ * out-of-band request is refused whatever the file holds), then the file's
11
+ * editability, then idempotence, then provenance last — so `unchanged` is
12
+ * reported for a human's own matching value rather than a refusal.
13
+ */
14
+ import { type SettingsFileShape } from './harness-settings-file.js';
15
+ import type { HarnessCompactThresholdLocation } from './harness-compact-threshold-config.js';
16
+ /**
17
+ * The sentinel `percentSkipReason` returns for "the file already holds the
18
+ * wanted value" — a non-reason, so the action enum stays `written | unchanged |
19
+ * skipped` and the caller has one branch per outcome.
20
+ */
21
+ export declare const SKIP_UNCHANGED = "__unchanged__";
22
+ /** Everything the gates are allowed to see. */
23
+ export interface PercentGateInput {
24
+ readonly location: HarnessCompactThresholdLocation;
25
+ readonly percent: number | null;
26
+ readonly settings: SettingsFileShape | null;
27
+ readonly fileRaw: unknown;
28
+ readonly filePercent: number | null;
29
+ readonly peakWritten: boolean;
30
+ }
31
+ /**
32
+ * THE GATES: the reason this call must not write, `SKIP_UNCHANGED` when the
33
+ * file already holds the wanted value, or `null` when it may write.
34
+ */
35
+ export declare function percentSkipReason(input: PercentGateInput): string | null;
@@ -0,0 +1,102 @@
1
+ /**
2
+ * Harness auto-compact THRESHOLD percent — THE GATES, in order.
3
+ *
4
+ * Split out of `harness-compact-threshold-config.ts` so the writer stays under
5
+ * the file-size cap and so the order of the gates can be read (and tested) on
6
+ * its own. `syncHarnessPercent` is the only caller.
7
+ *
8
+ * Order is load-bearing and is the window writer's: opt-out and the home guard
9
+ * first (they are about WHERE), then "no value asked for", then the band (an
10
+ * out-of-band request is refused whatever the file holds), then the file's
11
+ * editability, then idempotence, then provenance last — so `unchanged` is
12
+ * reported for a human's own matching value rather than a refusal.
13
+ */
14
+ import { isUserHomeProjectRoot } from '../config/config-safety.js';
15
+ import { isEditableSettingsFile, isLinkedSettingsFile, settingsEnvValue } from './harness-settings-file.js';
16
+ import { HARNESS_WINDOW_SYNC_OPTOUT_KEY, HARNESS_WINDOW_SYNC_OPTOUT_VALUE } from './harness-window-config.js';
17
+ import { parseHarnessCompactPercent } from './harness-percent-ownership.js';
18
+ /**
19
+ * The sentinel `percentSkipReason` returns for "the file already holds the
20
+ * wanted value" — a non-reason, so the action enum stays `written | unchanged |
21
+ * skipped` and the caller has one branch per outcome.
22
+ */
23
+ export const SKIP_UNCHANGED = '__unchanged__';
24
+ /**
25
+ * THE GATES: the reason this call must not write, `SKIP_UNCHANGED` when the
26
+ * file already holds the wanted value, or `null` when it may write.
27
+ */
28
+ export function percentSkipReason(input) {
29
+ const where = placementRefusal(input);
30
+ if (where !== null)
31
+ return where;
32
+ if (input.percent === null)
33
+ return noValueRefusal(input);
34
+ if (parseHarnessCompactPercent(input.percent) === null)
35
+ return 'out-of-range';
36
+ // THE LINK GUARD, before `unreadable-settings`. A symlinked `settings.local.json`
37
+ // — or a symlinked `.claude` directory holding an ordinary one — parses fine, so
38
+ // the editability test would say "editable" and the write would follow the link
39
+ // into whatever it points at. Its own reason — not
40
+ // `unreadable-settings` — because the file IS readable; the problem is where a
41
+ // write would land, and the user needs to be told that, not that their JSON is
42
+ // broken. See `isLinkedSettingsFile`.
43
+ if (isLinkedSettingsFile(input.location.settingsPath))
44
+ return 'symlinked-settings';
45
+ if (!isEditableSettingsFile(input.location.settingsPath))
46
+ return 'unreadable-settings';
47
+ if (input.filePercent === input.percent)
48
+ return SKIP_UNCHANGED;
49
+ // The same provenance rule as the window, decided from the FILE against its
50
+ // own marker: peaks-loop may update what it wrote and fill an empty slot, and
51
+ // never touches a value it did not write.
52
+ if (input.fileRaw !== undefined && !input.peakWritten)
53
+ return 'not-peaks-owned';
54
+ return null;
55
+ }
56
+ /**
57
+ * The caller asked for no percent: why, from what the FILE holds.
58
+ *
59
+ * A value on disk that is not a percentage at all (`eighty`, `80.5`) is its own
60
+ * state: the caller has no number to offer because the FILE's value did not
61
+ * parse, which is not the same fact as "the caller asked for no percent" — that
62
+ * one reads `no-percent-resolved` and describes an empty slot.
63
+ *
64
+ * A whole NUMBER outside the band (`150`) is a third state: it parses, so it IS
65
+ * a percentage the harness will not accept. Reporting it as
66
+ * `unreadable-percent` told the user their value was not a percentage, which is
67
+ * false and points at the wrong remedy.
68
+ */
69
+ function noValueRefusal(input) {
70
+ if (input.fileRaw === undefined || input.filePercent !== null)
71
+ return 'no-percent-resolved';
72
+ return isWholeNumber(input.fileRaw) ? 'out-of-range' : 'unreadable-percent';
73
+ }
74
+ /**
75
+ * THE SAME SPELLING RULE THE PARSER USES — digits with no leading zero beyond a
76
+ * lone `0`. `Number('80.0')`, `Number('+80')` and `Number('00080')` all succeed,
77
+ * so a bare "is it a finite whole number" test called a float or a signed
78
+ * spelling a whole number outside the band, and the notice told the user their
79
+ * `80.0` was "outside the 1..100 percent" when it was not a number at all.
80
+ */
81
+ const PLAIN_WHOLE_SPELLING = /^(?:0|[1-9]\d*)$/;
82
+ /** One raw value is the plain whole-number spelling this module writes. */
83
+ function isWholeNumber(raw) {
84
+ if (typeof raw === 'number')
85
+ return Number.isInteger(raw);
86
+ if (typeof raw !== 'string')
87
+ return false;
88
+ return PLAIN_WHOLE_SPELLING.test(raw.trim());
89
+ }
90
+ /**
91
+ * The two WHERE gates, checked before anything about the value. Split out only
92
+ * to keep each function under the complexity ceiling — the order of the whole
93
+ * gate sequence is documented on `percentSkipReason`.
94
+ */
95
+ function placementRefusal(input) {
96
+ if (settingsEnvValue(input.settings, HARNESS_WINDOW_SYNC_OPTOUT_KEY) ===
97
+ HARNESS_WINDOW_SYNC_OPTOUT_VALUE)
98
+ return 'opted-out';
99
+ if (input.location.projectRoot !== undefined && isUserHomeProjectRoot(input.location.projectRoot))
100
+ return 'unsafe-project-root';
101
+ return null;
102
+ }
@@ -0,0 +1,126 @@
1
+ /**
2
+ * WHO owns the harness auto-compact PERCENT key — one predicate, one classifier.
3
+ *
4
+ * This module exists so the three sides that have to agree about ownership (the
5
+ * writer, the rollback, the state report) cannot drift into three spellings of
6
+ * the same question. It is also what keeps the write half under the file-size
7
+ * cap, since every one of those sides needs this and nothing else from it.
8
+ *
9
+ * The percent key is `IdeCompactProfile.autoCompactPercentEnvVar` (declared per
10
+ * adapter — no IDE names here) and its provenance marker is
11
+ * `HARNESS_PERCENT_WRITTEN_KEY`, the twin of the window's.
12
+ */
13
+ /** Whole-content plain decimal integer of at most `NAMED_INTEGER_MAX_DIGITS`. */
14
+ export declare function isPlainIntegerSpelling(raw: unknown): boolean;
15
+ /** How an unparseable settings value is described back (see above). */
16
+ export declare function boundedRawNote(raw: unknown): string;
17
+ /**
18
+ * Provenance marker for the percent key, the twin of
19
+ * `HARNESS_WINDOW_WRITTEN_KEY`: it records the value peaks-loop ITSELF last
20
+ * wrote, so a value that differs is a human's own setting and is never
21
+ * overwritten. Travels in the same write as the value it describes.
22
+ */
23
+ export declare const HARNESS_PERCENT_WRITTEN_KEY = "PEAKS_HARNESS_PERCENT_WRITTEN";
24
+ /**
25
+ * The band the harness accepts for the percentage. It is a PERCENTAGE of the
26
+ * window, so 1..100 — and, like the window band, out-of-band values are
27
+ * REFUSED rather than clamped: a clamped write would put a different number in
28
+ * the file from the one reported, which is the same two-numbers drift the
29
+ * window band exists to prevent.
30
+ */
31
+ export declare const HARNESS_COMPACT_PERCENT_MIN = 1;
32
+ /** See `HARNESS_COMPACT_PERCENT_MIN`. */
33
+ export declare const HARNESS_COMPACT_PERCENT_MAX = 100;
34
+ /**
35
+ * Parse a candidate percent. Whole integers 1..100 only (a number, or the
36
+ * numeric string a JSON `env` block always carries, in the plain decimal
37
+ * spelling `PLAIN_PERCENT_SPELLING` requires). Anything else — `0`, `101`,
38
+ * `80.5`, `80.0`, `8e1`, `'abc'`, `''`, `null` — is null, so callers can
39
+ * distinguish "absent" from "unusable" via the RAW value.
40
+ */
41
+ export declare function parseHarnessCompactPercent(raw: unknown): number | null;
42
+ /**
43
+ * THE WRITER'S OWNERSHIP PREDICATE — strict, and deliberately NOT the one the
44
+ * rollback uses. See `percentOwnershipOf` for the pair.
45
+ *
46
+ * A value is the writer's to OVERWRITE only when `HARNESS_PERCENT_WRITTEN_KEY`
47
+ * is present and BOTH sides parse to the same number.
48
+ *
49
+ * The asymmetry with `isHarnessPercentRemovable` is the point. Removing a value
50
+ * deserves a wider rule than overwriting one: `--reset` is the documented
51
+ * recovery from a broken value and the user asked for it, while a probe or an
52
+ * init rewriting a value it cannot read would destroy the raw text the user
53
+ * needs in order to see what went wrong. Widening THIS predicate is how a
54
+ * background probe would silently replace a human's `eighty` — the exact
55
+ * "peaks-loop overruled my setting" failure the provenance marker exists to
56
+ * prevent.
57
+ */
58
+ export declare function isHarnessPercentPeaksOwned(input: {
59
+ readonly fileRaw: unknown;
60
+ readonly markerRaw: unknown;
61
+ }): boolean;
62
+ /**
63
+ * THE ROLLBACK'S OWNERSHIP PREDICATE — what `--reset` may REMOVE.
64
+ *
65
+ * Wider than `isHarnessPercentPeaksOwned` by exactly ONE shape, which proves the
66
+ * value is a corruption of peaks-loop's own write rather than a human pin: the
67
+ * marker parses while the VALUE does not. peaks-loop only ever writes
68
+ * `String(n)` as its marker (a plain in-band integer), so a VALID numeric
69
+ * marker beside an unreadable value can only be its own write mangled
70
+ * afterwards — and that is the documented `--reset` recovery.
71
+ *
72
+ * No marker ⇒ human. A parseable value that differs from a parseable marker ⇒
73
+ * human takeover. A marker that does not parse is NOT evidence of ownership in
74
+ * any combination: an unreadable value beside it is the user's own (even when
75
+ * the two strings are equal — a human who typed the same typo into both rows
76
+ * proved nothing about peaks-loop), and it is KEPT. The earlier "both raws are
77
+ * equal and unreadable" arm classified that pair `peaks-corrupt` and `--reset`
78
+ * deleted a user value; it is gone.
79
+ */
80
+ export declare function isHarnessPercentRemovable(input: {
81
+ readonly fileRaw: unknown;
82
+ readonly markerRaw: unknown;
83
+ }): boolean;
84
+ /**
85
+ * WHO the percent value on disk belongs to — the five states, named once so the
86
+ * rollback and the state report cannot describe the same file differently.
87
+ *
88
+ * - `peaks` — matches its marker: both sides parse to the same number
89
+ * - `peaks-corrupt` — marker present and parseable while the VALUE is not: a
90
+ * corruption of peaks-loop's own write
91
+ * - `human` — no marker, a parseable value that differs from its
92
+ * marker (a takeover), or any value whose MARKER does not
93
+ * parse (peaks-loop never wrote such a marker)
94
+ * - `stale-marker` — the value was deleted by hand, the marker survived
95
+ * - `none` — neither the value nor a marker
96
+ */
97
+ export type HarnessPercentOwnership = 'peaks' | 'peaks-corrupt' | 'human' | 'stale-marker' | 'none';
98
+ /**
99
+ * Classify one (value, marker) pair — the single answer to "may `--reset`
100
+ * remove this, and what do we call it?".
101
+ */
102
+ export declare function percentOwnershipOf(input: {
103
+ readonly fileRaw: unknown;
104
+ readonly markerRaw: unknown;
105
+ }): HarnessPercentOwnership;
106
+ /** What the file currently holds for the percent key, ownership included. */
107
+ export interface HarnessPercentState {
108
+ readonly key: string;
109
+ /**
110
+ * A BOUNDED description of what the file holds, present only when the key
111
+ * exists — never the raw string (MED-2). This state is printed as JSON and
112
+ * folded into logs, and the value is user-writable, so a secret mis-parked
113
+ * there must not travel. Its PRESENCE is what tells "holds something that
114
+ * does not parse" from "absent"; see `boundedRawNote`.
115
+ */
116
+ readonly rawNote?: string;
117
+ /** The parsed percent, or null when absent / unparseable. */
118
+ readonly percent: number | null;
119
+ readonly ownership: HarnessPercentOwnership;
120
+ }
121
+ /**
122
+ * Read the percent half of the pair — the state-report counterpart of
123
+ * `readHarnessWindowState`, so `peaks compact harness-window` can show BOTH
124
+ * knobs it manages rather than only the window.
125
+ */
126
+ export declare function readHarnessPercentState(settingsPath: string, percentKey: string): HarnessPercentState;
@@ -0,0 +1,200 @@
1
+ /**
2
+ * WHO owns the harness auto-compact PERCENT key — one predicate, one classifier.
3
+ *
4
+ * This module exists so the three sides that have to agree about ownership (the
5
+ * writer, the rollback, the state report) cannot drift into three spellings of
6
+ * the same question. It is also what keeps the write half under the file-size
7
+ * cap, since every one of those sides needs this and nothing else from it.
8
+ *
9
+ * The percent key is `IdeCompactProfile.autoCompactPercentEnvVar` (declared per
10
+ * adapter — no IDE names here) and its provenance marker is
11
+ * `HARNESS_PERCENT_WRITTEN_KEY`, the twin of the window's.
12
+ */
13
+ /**
14
+ * WHO owns the harness auto-compact PERCENT key — one predicate, one classifier.
15
+ *
16
+ * This module exists so the three sides that have to agree about ownership (the
17
+ * writer, the rollback, the state report) cannot drift into three spellings of
18
+ * the same question. It also hosts the MED-2 bounded vocabulary below, which the
19
+ * window module and the envelope views share.
20
+ *
21
+ * The percent key is `IdeCompactProfile.autoCompactPercentEnvVar` (declared per
22
+ * adapter — no IDE names here) and its provenance marker is
23
+ * `HARNESS_PERCENT_WRITTEN_KEY`, the twin of the window's.
24
+ */
25
+ import { readSettingsObject, settingsEnvValue } from './harness-settings-file.js';
26
+ /**
27
+ * MED-2 bounded vocabulary. A value here comes from a user-writable settings key
28
+ * whose rows reach JSON envelopes and logs, so a secret mis-parked at it must not
29
+ * travel: a plain integer (never a secret, and `150` out of band is the case the
30
+ * user must see) is NAMED; anything else is a fixed phrase plus a CHARACTER
31
+ * COUNT — no content, not even a prefix.
32
+ */
33
+ const NAMED_INTEGER_MAX_DIGITS = 12;
34
+ /** Whole-content plain decimal integer of at most `NAMED_INTEGER_MAX_DIGITS`. */
35
+ export function isPlainIntegerSpelling(raw) {
36
+ if (typeof raw === 'number') {
37
+ return Number.isInteger(raw) && String(Math.abs(raw)).length <= NAMED_INTEGER_MAX_DIGITS;
38
+ }
39
+ if (typeof raw !== 'string')
40
+ return false;
41
+ return new RegExp(`^-?\\d{1,${String(NAMED_INTEGER_MAX_DIGITS)}}$`).test(raw.trim());
42
+ }
43
+ /** How an unparseable settings value is described back (see above). */
44
+ export function boundedRawNote(raw) {
45
+ if (raw === undefined)
46
+ return 'not set';
47
+ if (typeof raw === 'number' && isPlainIntegerSpelling(raw))
48
+ return `the number ${String(raw)}`;
49
+ if (typeof raw === 'string' && isPlainIntegerSpelling(raw))
50
+ return `the number ${raw.trim()}`;
51
+ if (Array.isArray(raw))
52
+ return 'an array (not echoed here)';
53
+ if (typeof raw === 'object' && raw !== null)
54
+ return 'an object (not echoed here)';
55
+ const length = typeof raw === 'string' ? raw.length : 1;
56
+ return `a value that is not a number (${String(length)} chars, not echoed here)`;
57
+ }
58
+ /**
59
+ * Provenance marker for the percent key, the twin of
60
+ * `HARNESS_WINDOW_WRITTEN_KEY`: it records the value peaks-loop ITSELF last
61
+ * wrote, so a value that differs is a human's own setting and is never
62
+ * overwritten. Travels in the same write as the value it describes.
63
+ */
64
+ export const HARNESS_PERCENT_WRITTEN_KEY = 'PEAKS_HARNESS_PERCENT_WRITTEN';
65
+ /**
66
+ * The band the harness accepts for the percentage. It is a PERCENTAGE of the
67
+ * window, so 1..100 — and, like the window band, out-of-band values are
68
+ * REFUSED rather than clamped: a clamped write would put a different number in
69
+ * the file from the one reported, which is the same two-numbers drift the
70
+ * window band exists to prevent.
71
+ */
72
+ export const HARNESS_COMPACT_PERCENT_MIN = 1;
73
+ /** See `HARNESS_COMPACT_PERCENT_MIN`. */
74
+ export const HARNESS_COMPACT_PERCENT_MAX = 100;
75
+ /**
76
+ * THE SPELLING peaks-loop writes (and therefore the only one it reads back):
77
+ * a plain decimal with NO leading zero beyond a lone `0`. `80.0`, `8e1`, `+80`,
78
+ * `080` and `00080` all evaluate to an in-band number under `Number()`, but
79
+ * none of them is a value this module can have written — `String(percent)`
80
+ * emits `80` and nothing else — so accepting them would let a hand edit or
81
+ * another tool masquerade as peaks-loop's own output. A value peaks-loop cannot
82
+ * have written is reported as unreadable, which is the honest state, and the
83
+ * `--reset` advice follows the OWNERSHIP of the value rather than this
84
+ * spelling (see `harness-compact-threshold-ensure.ts`).
85
+ *
86
+ * Two spellings matter for ownership, not for the band:
87
+ * - a lone `0`: `String(0)` is `0`, so `0` IS a spelling peaks-loop can
88
+ * emit. Paired with its own marker it is `peaks-corrupt` (out of band,
89
+ * removable), which is why it must parse here.
90
+ * - a leading zero (`080`): `String(80)` never emits one, so it is NOT a
91
+ * spelling peaks-loop writes — it must not parse to `80` (that let it equal
92
+ * its marker and be overwritten). It is also not evidence of a takeover:
93
+ * beside a VALID marker `80` it is peaks-loop's own `80` mangled afterwards,
94
+ * so `isHarnessPercentRemovable` classifies it `peaks-corrupt` through the
95
+ * marker-parses arm, never `human`.
96
+ */
97
+ const PLAIN_PERCENT_SPELLING = /^(?:0|[1-9]\d*)$/;
98
+ /** In the harness's percent band AND a whole number. */
99
+ function isPercentInBand(value) {
100
+ return (Number.isInteger(value) &&
101
+ value >= HARNESS_COMPACT_PERCENT_MIN &&
102
+ value <= HARNESS_COMPACT_PERCENT_MAX);
103
+ }
104
+ /**
105
+ * Parse a candidate percent. Whole integers 1..100 only (a number, or the
106
+ * numeric string a JSON `env` block always carries, in the plain decimal
107
+ * spelling `PLAIN_PERCENT_SPELLING` requires). Anything else — `0`, `101`,
108
+ * `80.5`, `80.0`, `8e1`, `'abc'`, `''`, `null` — is null, so callers can
109
+ * distinguish "absent" from "unusable" via the RAW value.
110
+ */
111
+ export function parseHarnessCompactPercent(raw) {
112
+ if (typeof raw === 'number')
113
+ return isPercentInBand(raw) ? raw : null;
114
+ if (typeof raw !== 'string')
115
+ return null;
116
+ const text = raw.trim();
117
+ if (!PLAIN_PERCENT_SPELLING.test(text))
118
+ return null;
119
+ const parsed = Number(text);
120
+ return isPercentInBand(parsed) ? parsed : null;
121
+ }
122
+ /**
123
+ * THE WRITER'S OWNERSHIP PREDICATE — strict, and deliberately NOT the one the
124
+ * rollback uses. See `percentOwnershipOf` for the pair.
125
+ *
126
+ * A value is the writer's to OVERWRITE only when `HARNESS_PERCENT_WRITTEN_KEY`
127
+ * is present and BOTH sides parse to the same number.
128
+ *
129
+ * The asymmetry with `isHarnessPercentRemovable` is the point. Removing a value
130
+ * deserves a wider rule than overwriting one: `--reset` is the documented
131
+ * recovery from a broken value and the user asked for it, while a probe or an
132
+ * init rewriting a value it cannot read would destroy the raw text the user
133
+ * needs in order to see what went wrong. Widening THIS predicate is how a
134
+ * background probe would silently replace a human's `eighty` — the exact
135
+ * "peaks-loop overruled my setting" failure the provenance marker exists to
136
+ * prevent.
137
+ */
138
+ export function isHarnessPercentPeaksOwned(input) {
139
+ const file = parseHarnessCompactPercent(input.fileRaw);
140
+ const marker = parseHarnessCompactPercent(input.markerRaw);
141
+ return file !== null && marker === file;
142
+ }
143
+ /**
144
+ * THE ROLLBACK'S OWNERSHIP PREDICATE — what `--reset` may REMOVE.
145
+ *
146
+ * Wider than `isHarnessPercentPeaksOwned` by exactly ONE shape, which proves the
147
+ * value is a corruption of peaks-loop's own write rather than a human pin: the
148
+ * marker parses while the VALUE does not. peaks-loop only ever writes
149
+ * `String(n)` as its marker (a plain in-band integer), so a VALID numeric
150
+ * marker beside an unreadable value can only be its own write mangled
151
+ * afterwards — and that is the documented `--reset` recovery.
152
+ *
153
+ * No marker ⇒ human. A parseable value that differs from a parseable marker ⇒
154
+ * human takeover. A marker that does not parse is NOT evidence of ownership in
155
+ * any combination: an unreadable value beside it is the user's own (even when
156
+ * the two strings are equal — a human who typed the same typo into both rows
157
+ * proved nothing about peaks-loop), and it is KEPT. The earlier "both raws are
158
+ * equal and unreadable" arm classified that pair `peaks-corrupt` and `--reset`
159
+ * deleted a user value; it is gone.
160
+ */
161
+ export function isHarnessPercentRemovable(input) {
162
+ if (input.fileRaw === undefined || input.markerRaw === undefined)
163
+ return false;
164
+ const file = parseHarnessCompactPercent(input.fileRaw);
165
+ const marker = parseHarnessCompactPercent(input.markerRaw);
166
+ if (file !== null)
167
+ return marker === file;
168
+ return marker !== null;
169
+ }
170
+ /**
171
+ * Classify one (value, marker) pair — the single answer to "may `--reset`
172
+ * remove this, and what do we call it?".
173
+ */
174
+ export function percentOwnershipOf(input) {
175
+ if (input.fileRaw === undefined && input.markerRaw === undefined)
176
+ return 'none';
177
+ if (input.fileRaw === undefined)
178
+ return 'stale-marker';
179
+ if (!isHarnessPercentRemovable(input))
180
+ return 'human';
181
+ return parseHarnessCompactPercent(input.fileRaw) === null ? 'peaks-corrupt' : 'peaks';
182
+ }
183
+ /**
184
+ * Read the percent half of the pair — the state-report counterpart of
185
+ * `readHarnessWindowState`, so `peaks compact harness-window` can show BOTH
186
+ * knobs it manages rather than only the window.
187
+ */
188
+ export function readHarnessPercentState(settingsPath, percentKey) {
189
+ const settings = readSettingsObject(settingsPath);
190
+ const raw = settingsEnvValue(settings, percentKey);
191
+ const markerRaw = settingsEnvValue(settings, HARNESS_PERCENT_WRITTEN_KEY);
192
+ // The raw value is bounded HERE, at the point it would leave the module:
193
+ // deciding it once, at the source, means no caller can forget to map it.
194
+ return {
195
+ key: percentKey,
196
+ ...(raw === undefined ? {} : { rawNote: boundedRawNote(raw) }),
197
+ percent: parseHarnessCompactPercent(raw),
198
+ ownership: percentOwnershipOf({ fileRaw: raw, markerRaw })
199
+ };
200
+ }
@@ -0,0 +1,70 @@
1
+ /**
2
+ * The harness settings file, as a JSON object — the small shared read layer the
3
+ * threshold modules sit on.
4
+ *
5
+ * Why it is its own module: three of them (`-config`, `-verdict`, `-reset`) read
6
+ * the same file and must answer "cannot read it" identically. One copy here is
7
+ * what keeps a fourth reader from disagreeing about a corrupt file, and it is
8
+ * also what keeps each of those modules under the file-size cap.
9
+ *
10
+ * The READER is not a second copy. `readSettingsObject` and its shape already
11
+ * live in `harness-window-config.ts`, which had to answer the same question for
12
+ * the window sync; this module re-exports that one implementation so a corrupt
13
+ * file cannot be "readable" to one caller and "unreadable" to another. The
14
+ * helpers below are the threshold-specific view of it.
15
+ *
16
+ * Vendor neutrality: this knows about a JSON file with an `env` block and
17
+ * nothing else. The path and every key name are the caller's.
18
+ */
19
+ import { readSettingsObject, type SettingsFileShape } from './harness-window-config.js';
20
+ export { readSettingsObject };
21
+ export type { SettingsFileShape };
22
+ /**
23
+ * True when the settings path, or the DIRECTORY holding it, is a LINK (a
24
+ * symlink, or on Windows a junction — `lstat` reports both as
25
+ * `isSymbolicLink()`), which none of this slice's writers may write through.
26
+ *
27
+ * RE-EXPORTED, not re-implemented, from `../ide/shared/safe-path.ts` — the
28
+ * module that already owns settings-path safety (`assertSafeSettingsFile`) — so
29
+ * there is one spelling of "what is a link" and every threshold module reaches
30
+ * it through here, with no import cycle. See that module for why the directory
31
+ * is checked as well as the file, and why an absent path still counts as
32
+ * writable.
33
+ */
34
+ export { isLinkedSettingsFile } from '../ide/shared/safe-path.js';
35
+ /**
36
+ * True when the file is absent (editable) or a parseable JSON object.
37
+ *
38
+ * Exported because the reset path has to ask the same question before it
39
+ * decides a file is "unreadable and therefore untouchable" rather than
40
+ * "carrying nothing of peaks-loop's".
41
+ */
42
+ export declare function isEditableSettingsFile(settingsPath: string): boolean;
43
+ /** The `env` object of a parsed settings file, or `{}` — never a shared reference. */
44
+ export declare function envBlock(settings: SettingsFileShape | null): Record<string, unknown>;
45
+ /** One key out of a parsed settings file's `env` block; `undefined` when absent. */
46
+ export declare function settingsEnvValue(settings: SettingsFileShape | null, key: string): unknown;
47
+ /** `was X` for a value that was there, nothing when it was not. */
48
+ export declare function wasValue(value: number | null): string;
49
+ /**
50
+ * The MED-2 bounded vocabulary (see `harness-percent-ownership.ts`), re-exported
51
+ * so every caller reaches it through one path.
52
+ *
53
+ * THE INVARIANT IS STRUCTURAL, NOT A MAPPER'S JOB. Every service-layer result in
54
+ * this slice that can carry text read from the settings file carries a bounded
55
+ * NOTE (`previousRawNote` / `rawNote` / `windowRawNote` …) computed where the
56
+ * value is read. A result that never holds the plaintext cannot leak it,
57
+ * whichever consumer logs or persists it.
58
+ */
59
+ export { isPlainIntegerSpelling, boundedRawNote } from './harness-percent-ownership.js';
60
+ /**
61
+ * How a removed percent half is named — the number when it was one, and a
62
+ * fixed BOUNDED phrase (never the raw string, MED-2) when it was not.
63
+ */
64
+ export declare function percentClause(percent: {
65
+ readonly key: string;
66
+ readonly ownership: string;
67
+ readonly previousPercent: number | null;
68
+ }): string;
69
+ /** The one sentence for a rollback that found nothing of peaks-loop's. */
70
+ export declare function nothingToRemoveSentence(settingsPath: string, windowKey: string, percentKey: string): string;
@@ -0,0 +1,83 @@
1
+ /**
2
+ * The harness settings file, as a JSON object — the small shared read layer the
3
+ * threshold modules sit on.
4
+ *
5
+ * Why it is its own module: three of them (`-config`, `-verdict`, `-reset`) read
6
+ * the same file and must answer "cannot read it" identically. One copy here is
7
+ * what keeps a fourth reader from disagreeing about a corrupt file, and it is
8
+ * also what keeps each of those modules under the file-size cap.
9
+ *
10
+ * The READER is not a second copy. `readSettingsObject` and its shape already
11
+ * live in `harness-window-config.ts`, which had to answer the same question for
12
+ * the window sync; this module re-exports that one implementation so a corrupt
13
+ * file cannot be "readable" to one caller and "unreadable" to another. The
14
+ * helpers below are the threshold-specific view of it.
15
+ *
16
+ * Vendor neutrality: this knows about a JSON file with an `env` block and
17
+ * nothing else. The path and every key name are the caller's.
18
+ */
19
+ import { existsSync } from 'node:fs';
20
+ import { readSettingsObject } from './harness-window-config.js';
21
+ export { readSettingsObject };
22
+ /**
23
+ * True when the settings path, or the DIRECTORY holding it, is a LINK (a
24
+ * symlink, or on Windows a junction — `lstat` reports both as
25
+ * `isSymbolicLink()`), which none of this slice's writers may write through.
26
+ *
27
+ * RE-EXPORTED, not re-implemented, from `../ide/shared/safe-path.ts` — the
28
+ * module that already owns settings-path safety (`assertSafeSettingsFile`) — so
29
+ * there is one spelling of "what is a link" and every threshold module reaches
30
+ * it through here, with no import cycle. See that module for why the directory
31
+ * is checked as well as the file, and why an absent path still counts as
32
+ * writable.
33
+ */
34
+ export { isLinkedSettingsFile } from '../ide/shared/safe-path.js';
35
+ /**
36
+ * True when the file is absent (editable) or a parseable JSON object.
37
+ *
38
+ * Exported because the reset path has to ask the same question before it
39
+ * decides a file is "unreadable and therefore untouchable" rather than
40
+ * "carrying nothing of peaks-loop's".
41
+ */
42
+ export function isEditableSettingsFile(settingsPath) {
43
+ if (!existsSync(settingsPath))
44
+ return true;
45
+ return readSettingsObject(settingsPath) !== null;
46
+ }
47
+ /** The `env` object of a parsed settings file, or `{}` — never a shared reference. */
48
+ export function envBlock(settings) {
49
+ const env = settings?.env;
50
+ return typeof env === 'object' && env !== null && !Array.isArray(env) ? env : {};
51
+ }
52
+ /** One key out of a parsed settings file's `env` block; `undefined` when absent. */
53
+ export function settingsEnvValue(settings, key) {
54
+ return envBlock(settings)[key];
55
+ }
56
+ /** `was X` for a value that was there, nothing when it was not. */
57
+ export function wasValue(value) {
58
+ return value === null ? '' : ` (was ${String(value)})`;
59
+ }
60
+ /**
61
+ * The MED-2 bounded vocabulary (see `harness-percent-ownership.ts`), re-exported
62
+ * so every caller reaches it through one path.
63
+ *
64
+ * THE INVARIANT IS STRUCTURAL, NOT A MAPPER'S JOB. Every service-layer result in
65
+ * this slice that can carry text read from the settings file carries a bounded
66
+ * NOTE (`previousRawNote` / `rawNote` / `windowRawNote` …) computed where the
67
+ * value is read. A result that never holds the plaintext cannot leak it,
68
+ * whichever consumer logs or persists it.
69
+ */
70
+ export { isPlainIntegerSpelling, boundedRawNote } from './harness-percent-ownership.js';
71
+ /**
72
+ * How a removed percent half is named — the number when it was one, and a
73
+ * fixed BOUNDED phrase (never the raw string, MED-2) when it was not.
74
+ */
75
+ export function percentClause(percent) {
76
+ return percent.ownership === 'peaks-corrupt'
77
+ ? `${percent.key} (held a value that is not a percentage, not echoed here)`
78
+ : `${percent.key}${wasValue(percent.previousPercent)}`;
79
+ }
80
+ /** The one sentence for a rollback that found nothing of peaks-loop's. */
81
+ export function nothingToRemoveSentence(settingsPath, windowKey, percentKey) {
82
+ return `Nothing to remove — ${settingsPath} carries no ${windowKey}, no ${percentKey}, and no provenance marker peaks-loop wrote, so nothing was written and no opt-out row was recorded.`;
83
+ }