@jjanczur/tyran 0.1.30 → 0.1.32

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.
@@ -0,0 +1,254 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * ensure-gitleaks — remove the one prerequisite that blocks day one.
4
+ *
5
+ * The secrets gate refuses every commit and push until `gitleaks` exists, and
6
+ * it refuses rather than warning for a reason that has not changed: a check
7
+ * that passes when its scanner is missing is a check you disable by
8
+ * uninstalling a package.
9
+ *
10
+ * The unstated assumption in that design is that the operator can install a
11
+ * binary. Measured against the people actually adopting this: some have no
12
+ * Homebrew, no admin rights, or are on Windows. For them the realistic
13
+ * outcome of "install gitleaks and re-run" is not a safer repository — it is
14
+ * switching the hook off, or abandoning the tool. A gate nobody can satisfy
15
+ * protects nothing, which is the same argument `.tyran/config.yaml` being
16
+ * AUTO already rests on.
17
+ *
18
+ * So this fetches the scanner instead of asking someone else to. It is the
19
+ * same thing `.github/workflows/ci.yml` has always done — pinned version,
20
+ * pinned checksum — moved to where a user can reach it.
21
+ *
22
+ * ## Why a checksum table and not "download the latest"
23
+ *
24
+ * This writes an executable and something else later runs it. Version alone
25
+ * is not integrity: a tag can be moved, a mirror can lie, and a scanner that
26
+ * has been replaced reports clean on everything. The digests below are the
27
+ * ones GitHub publishes for 8.30.1, and a mismatch DELETES the download and
28
+ * refuses. The linux_x64 line is the same digest ci.yml already pins, which
29
+ * is the cross-check that this table was transcribed and not invented.
30
+ *
31
+ * Usage:
32
+ * node scripts/ensure-gitleaks.mjs [--check]
33
+ *
34
+ * Exit: 0 present or installed · 1 unavailable (reason printed) · 2 usage.
35
+ */
36
+ import { createHash } from 'node:crypto';
37
+ import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
38
+ import { execFileSync } from 'node:child_process';
39
+ import { join } from 'node:path';
40
+ import { homedir, tmpdir } from 'node:os';
41
+
42
+ /** The version this table describes. Bumping it means re-fetching every digest. */
43
+ export const GITLEAKS_VERSION = '8.30.1';
44
+
45
+ /**
46
+ * SHA-256 per platform, from the release's own `checksums.txt`.
47
+ *
48
+ * Keyed `<process.platform>-<process.arch>` so the lookup cannot drift from
49
+ * what Node reports. A platform absent from this table is a REFUSAL with
50
+ * instructions, never a silent skip — an unknown platform is exactly where a
51
+ * "best effort" download would install something unverified.
52
+ */
53
+ export const GITLEAKS_SHA256 = Object.freeze({
54
+ 'darwin-arm64': 'b40ab0ae55c505963e365f271a8d3846efbc170aa17f2607f13df610a9aeb6a5',
55
+ 'darwin-x64': 'dfe101a4db2255fc85120ac7f3d25e4342c3c20cf749f2c20a18081af1952709',
56
+ 'linux-arm64': 'e4a487ee7ccd7d3a7f7ec08657610aa3606637dab924210b3aee62570fb4b080',
57
+ // The digest ci.yml pins. If these two ever disagree, one of them is wrong.
58
+ 'linux-x64': '551f6fc83ea457d62a0d98237cbad105af8d557003051f41f3e7ca7b3f2470eb',
59
+ 'win32-arm64': 'b95f5e4f5c425cedca7ee203d9afd29597e692c4924a12ed42f970537c72cc0f',
60
+ 'win32-x64': 'd29144deff3a68aa93ced33dddf84b7fdc26070add4aa0f4513094c8332afc4e',
61
+ });
62
+
63
+ /**
64
+ * Where a managed scanner lives: under the operator's HOME, never the repo.
65
+ *
66
+ * The first shape of this put it in `<repo>/.tyran/bin/`, which is worse in a
67
+ * way worth recording: a path inside the repository travels with a clone, so
68
+ * a planted binary that reports clean on everything would arrive with the
69
+ * checkout — the attack the tracked-only rule for `.gitleaksignore` already
70
+ * exists to prevent, reopened through a file that is not even in a diff.
71
+ * Under the home directory the scanner is the operator's machine, exactly
72
+ * like anything on PATH, and one install serves every repository on it.
73
+ */
74
+ export const MANAGED_DIR = join(homedir(), '.tyran', 'bin');
75
+
76
+ const ASSET_ARCH = Object.freeze({ arm64: 'arm64', x64: 'x64' });
77
+
78
+ /** The release asset name for a platform key, or null if unsupported. */
79
+ export function assetFor(platform = process.platform, arch = process.arch) {
80
+ const a = ASSET_ARCH[arch];
81
+ if (a === undefined) return null;
82
+ if (platform === 'darwin') return `gitleaks_${GITLEAKS_VERSION}_darwin_${a}.tar.gz`;
83
+ if (platform === 'linux') return `gitleaks_${GITLEAKS_VERSION}_linux_${a}.tar.gz`;
84
+ if (platform === 'win32') return `gitleaks_${GITLEAKS_VERSION}_windows_${a}.zip`;
85
+ return null;
86
+ }
87
+
88
+ export const managedBinPath = (platform = process.platform) =>
89
+ join(MANAGED_DIR, platform === 'win32' ? 'gitleaks.exe' : 'gitleaks');
90
+
91
+ /** SHA-256 of a file on disk, hex. */
92
+ export function digestOf(path) {
93
+ return createHash('sha256').update(readFileSync(path)).digest('hex');
94
+ }
95
+
96
+ /**
97
+ * Is a usable `gitleaks` already reachable? Checks the operator's override
98
+ * first, then PATH — the two the gate itself consults, in the gate's order.
99
+ */
100
+ export function alreadyAvailable({ run = defaultRun } = {}) {
101
+ const explicit = process.env.TYRAN_GITLEAKS_BIN;
102
+ if (typeof explicit === 'string' && explicit !== '') {
103
+ return run(explicit, ['version']) === null ? null : { path: explicit, why: 'TYRAN_GITLEAKS_BIN' };
104
+ }
105
+ const version = run('gitleaks', ['version']);
106
+ return version === null ? null : { path: 'gitleaks', why: 'on PATH', version: version.trim() };
107
+ }
108
+
109
+ function defaultRun(bin, args) {
110
+ try {
111
+ return execFileSync(bin, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 10_000 });
112
+ } catch {
113
+ return null;
114
+ }
115
+ }
116
+
117
+ /**
118
+ * Download one URL to a path, following redirects. GitHub answers a release
119
+ * asset with a 302 to a CDN, so a client that does not follow them downloads
120
+ * an HTML document and hashes it — which fails the digest check rather than
121
+ * installing anything, but reports the wrong reason.
122
+ */
123
+ async function download(url, dest, { redirects = 5 } = {}) {
124
+ const { get } = await import('node:https');
125
+ const { createWriteStream } = await import('node:fs');
126
+ return new Promise((resolvePromise, reject) => {
127
+ get(url, { headers: { 'user-agent': 'tyran-ensure-gitleaks' } }, (res) => {
128
+ const { statusCode, headers } = res;
129
+ if (statusCode !== undefined && statusCode >= 300 && statusCode < 400 && headers.location) {
130
+ res.resume();
131
+ if (redirects === 0) return reject(new Error('too many redirects'));
132
+ return resolvePromise(download(headers.location, dest, { redirects: redirects - 1 }));
133
+ }
134
+ if (statusCode !== 200) {
135
+ res.resume();
136
+ return reject(new Error(`HTTP ${statusCode} from ${url}`));
137
+ }
138
+ const file = createWriteStream(dest);
139
+ res.pipe(file);
140
+ file.on('finish', () => file.close(() => resolvePromise(undefined)));
141
+ file.on('error', reject);
142
+ }).on('error', reject);
143
+ });
144
+ }
145
+
146
+ /**
147
+ * Fetch, verify and unpack the pinned scanner into `<dir>/bin/`.
148
+ *
149
+ * The digest is checked BEFORE anything is unpacked and before the file is
150
+ * made executable: an archive that fails is deleted and nothing it contained
151
+ * ever reaches the disk as a program.
152
+ *
153
+ * `tar` does the unpacking on every platform — bsdtar reads zip, and Windows
154
+ * has shipped it since 10 — so this needs no archive library and no
155
+ * dependency, which is the property that lets it ship inside a plugin.
156
+ */
157
+ export async function installGitleaks({ platform = process.platform, arch = process.arch, run = defaultRun } = {}) {
158
+ const key = `${platform}-${arch}`;
159
+ const asset = assetFor(platform, arch);
160
+ const expected = GITLEAKS_SHA256[key];
161
+ if (asset === null || expected === undefined) {
162
+ return { ok: false, reason: `no pinned build for ${key}`, unsupported: true };
163
+ }
164
+ const target = managedBinPath(platform);
165
+ if (existsSync(target) && digestOf(target) !== '' && run(target, ['version']) !== null) {
166
+ return { ok: true, path: target, already: true };
167
+ }
168
+ const url = `https://github.com/gitleaks/gitleaks/releases/download/v${GITLEAKS_VERSION}/${asset}`;
169
+ const staging = join(tmpdir(), `tyran-gitleaks-${process.pid}`);
170
+ mkdirSync(staging, { recursive: true });
171
+ const archive = join(staging, asset);
172
+ try {
173
+ await download(url, archive);
174
+ const actual = digestOf(archive);
175
+ if (actual !== expected) {
176
+ rmSync(staging, { recursive: true, force: true });
177
+ return {
178
+ ok: false,
179
+ reason: `checksum mismatch for ${asset}: expected ${expected}, got ${actual}. Nothing was installed.`,
180
+ };
181
+ }
182
+ execFileSync('tar', ['-xf', archive, '-C', staging], { stdio: 'ignore', timeout: 60_000 });
183
+ const unpacked = join(staging, platform === 'win32' ? 'gitleaks.exe' : 'gitleaks');
184
+ if (!existsSync(unpacked)) {
185
+ rmSync(staging, { recursive: true, force: true });
186
+ return { ok: false, reason: `the archive did not contain a gitleaks binary` };
187
+ }
188
+ mkdirSync(MANAGED_DIR, { recursive: true });
189
+ writeFileSync(target, readFileSync(unpacked));
190
+ if (platform !== 'win32') chmodSync(target, 0o755);
191
+ rmSync(staging, { recursive: true, force: true });
192
+ if (run(target, ['version']) === null) {
193
+ return { ok: false, reason: 'the installed binary did not run — the platform build may not match this machine' };
194
+ }
195
+ return { ok: true, path: target, installed: true, digest: expected };
196
+ } catch (error) {
197
+ rmSync(staging, { recursive: true, force: true });
198
+ return { ok: false, reason: String(error.message ?? error) };
199
+ }
200
+ }
201
+
202
+ const MANUAL =
203
+ 'Install it by hand and re-run:\n' +
204
+ ' macOS brew install gitleaks\n' +
205
+ ' Linux see https://github.com/gitleaks/gitleaks/releases (or your package manager)\n' +
206
+ 'or point TYRAN_GITLEAKS_BIN at an existing binary.';
207
+
208
+ function usage(message) {
209
+ if (message) console.error(`ensure-gitleaks: ${message}`);
210
+ console.error('usage: node scripts/ensure-gitleaks.mjs [--check]');
211
+ process.exit(2);
212
+ }
213
+
214
+ async function main(argv) {
215
+ const args = argv.slice(2);
216
+ for (const arg of args) {
217
+ if (arg.startsWith('--') && arg !== '--check') usage(`unknown flag ${arg}`);
218
+ }
219
+
220
+ const found = alreadyAvailable();
221
+ if (found !== null) {
222
+ console.log(`ensure-gitleaks: already available (${found.why})${found.version ? ` — ${found.version}` : ''}`);
223
+ process.exit(0);
224
+ }
225
+ const local = managedBinPath();
226
+ if (existsSync(local) && defaultRun(local, ['version']) !== null) {
227
+ console.log(`ensure-gitleaks: present at ${local}`);
228
+ process.exit(0);
229
+ }
230
+ if (args.includes('--check')) {
231
+ console.error('ensure-gitleaks: NOT available — the secrets gate refuses every commit and push until it is.');
232
+ console.error(MANUAL);
233
+ process.exit(1);
234
+ }
235
+
236
+ console.log(`ensure-gitleaks: fetching gitleaks ${GITLEAKS_VERSION} for ${process.platform}-${process.arch}…`);
237
+ const result = await installGitleaks();
238
+ if (!result.ok) {
239
+ console.error(`ensure-gitleaks: could not install it (${result.reason})`);
240
+ console.error(MANUAL);
241
+ process.exit(1);
242
+ }
243
+ console.log(`ensure-gitleaks: installed ${result.path}`);
244
+ console.log(`ensure-gitleaks: verified sha256 ${result.digest}`);
245
+ console.log('ensure-gitleaks: the secrets gate finds this automatically — nothing to add to your shell.');
246
+ process.exit(0);
247
+ }
248
+
249
+ if (import.meta.url === `file://${process.argv[1]}`) {
250
+ main(process.argv).catch((error) => {
251
+ console.error(`ensure-gitleaks: ${error.message}`);
252
+ process.exit(1);
253
+ });
254
+ }
@@ -83,6 +83,125 @@ export const DATA_REQUIRED = Object.freeze({
83
83
  error: ['class'],
84
84
  });
85
85
 
86
+ /**
87
+ * Per-type keys that some consumer actually READS. Descriptive, not enforced.
88
+ *
89
+ * `append` does not and must not check this: `data may always carry extra
90
+ * keys` is a promise this file makes, the evidence gate relies on it for four
91
+ * of its own keys, and every journal ever written would fail retroactively if
92
+ * it became a rule. Measured on one real install: 130 distinct (event, key)
93
+ * pairs across 39 initiatives, and the long tail is deliberate annotation —
94
+ * `init.created.hardware`, `retro.entry.proposed_as_diffs`, `spawn.stories`.
95
+ *
96
+ * What this map is FOR is the narrow case hiding in that tail: a key that was
97
+ * MEANT to be read and is not, because it was misspelled. `next_step` for
98
+ * `next_steps` is accepted, ignored, and leaves the resume surface empty while
99
+ * the agent that wrote it believes it recorded something. Doctor compares
100
+ * unread keys against this map and reports only the near-misses; the rest are
101
+ * counted, because they are the contract working rather than a defect.
102
+ *
103
+ * `null` means "free-form on purpose": the fold keeps the whole `data` object
104
+ * for these, so there is no such thing as a key it does not read.
105
+ */
106
+ export const DATA_KNOWN = Object.freeze({
107
+ 'init.created': null,
108
+ 'plan.accepted': null,
109
+ 'ticket.created': Object.freeze(['id', 'title', 'text', 'deps']),
110
+ 'ticket.status': Object.freeze(['ticket', 'column', 'reason', 'until']),
111
+ spawn: Object.freeze(['agent', 'role', 'model', 'ticket', 'worktree']),
112
+ report: Object.freeze(['agent', 'verdict', 'ticket', 'text', 'note', 'evidence', 'closed_by']),
113
+ progress: Object.freeze(['agent', 'state', 'ticket', 'detail', 'next']),
114
+ // Row two is the evidence gate's own, written on every SubagentStop; row
115
+ // three is `answer.mjs` closing an operator question. Both are Tyran writing
116
+ // to its own journal, so leaving either out would have every install report
117
+ // its own normal operation back at itself.
118
+ gate: Object.freeze([
119
+ 'kind', 'result', 'evidence', 'evidence_ref', 'ticket', 'question', 'recommendation', 'default',
120
+ 'reason', 'signals', 'code', 'would_be', 'initiative_inferred_from',
121
+ 'answer', 'answer_mode', 'decision', 'via',
122
+ ]),
123
+ review: Object.freeze(['ticket', 'verdict', 'by']),
124
+ merge: Object.freeze(['ticket', 'sha', 'mode']),
125
+ // `ask`/`ticket` come from `answer.mjs` closing an operator question;
126
+ // `signature`/`occurrences`/`path` from `mistakes.mjs` recording a promoted
127
+ // rule. Tyran's OWN writers, so leaving them out would have every install
128
+ // that has ever answered a question or run a retrospective report its own
129
+ // normal operation back at itself.
130
+ decision: Object.freeze(['id', 'text', 'ask', 'ticket', 'signature', 'occurrences', 'path']),
131
+ finding: Object.freeze(['area', 'claim', 'proof', 'id', 'ticket', 'confidence']),
132
+ // The expiry spellings doctor reads, plus the human description agents
133
+ // attach. Measured across every journal on a real machine, agents wrote
134
+ // `expiry` 33 times, `purpose` 28, `story` 21, `text` 21 — none of them
135
+ // known, so every lease an agent took the trouble to describe reported
136
+ // `journal-key-unread` back at its author. A schema that flags the fields
137
+ // its own agents naturally write is training them to write less.
138
+ 'lease.acquired': Object.freeze([
139
+ 'resource', 'holder', 'mode', 'expiry', 'expires', 'expires_at', 'until', 'purpose', 'story', 'text', 'note',
140
+ ]),
141
+ 'lease.released': Object.freeze(['resource', 'holder', 'text', 'note']),
142
+ checkpoint: Object.freeze(['phase', 'next_steps']),
143
+ 'retro.entry': Object.freeze(['kind', 'target', 'confidence']),
144
+ error: Object.freeze(['class', 'detail', 'ticket']),
145
+ });
146
+
147
+ /**
148
+ * Is `typo` one edit away from `known`? Insert, delete or substitute.
149
+ *
150
+ * Deliberately distance ONE and nothing looser. At two, `note` matches `next`
151
+ * and the check starts inventing typos in correct journals — and this feeds a
152
+ * finding that fails the check, so a false positive costs an operator a red
153
+ * doctor on a healthy repo, which is how a check gets switched off.
154
+ */
155
+ export function isOneEditApart(typo, known) {
156
+ if (typo === known) return false;
157
+ const [a, b] = typo.length <= known.length ? [typo, known] : [known, typo];
158
+ if (b.length - a.length > 1) return false;
159
+ let i = 0;
160
+ let j = 0;
161
+ let edits = 0;
162
+ while (i < a.length && j < b.length) {
163
+ if (a[i] === b[j]) { i += 1; j += 1; continue; }
164
+ if (++edits > 1) return false;
165
+ if (a.length === b.length) i += 1;
166
+ j += 1;
167
+ }
168
+ return edits + (b.length - j) + (a.length - i) <= 1;
169
+ }
170
+
171
+ /**
172
+ * Keys no consumer reads, split into the two that need different sentences.
173
+ *
174
+ * `nearMisses` are almost certainly misspellings of a key that IS read —
175
+ * the accept-then-ignore failure, worth a finding each. `unread` is everything
176
+ * else: counted, never dropped (ADR-19 correction 1), and not called a defect,
177
+ * because carrying extra keys is what the envelope promises.
178
+ *
179
+ * Short keys are exempt from the near-miss test: at three characters or fewer
180
+ * almost anything is one edit from something.
181
+ */
182
+ export function unreadDataKeys(events) {
183
+ const unread = new Map(); // "ev.key" -> count
184
+ const nearMisses = new Map(); // "ev.key" -> {ev, key, meant, count}
185
+ for (const event of events) {
186
+ const known = DATA_KNOWN[event?.ev];
187
+ if (known === undefined || known === null) continue;
188
+ const data = event.data;
189
+ if (typeof data !== 'object' || data === null || Array.isArray(data)) continue;
190
+ for (const key of Object.keys(data)) {
191
+ if (known.includes(key)) continue;
192
+ const id = `${event.ev}.${key}`;
193
+ unread.set(id, (unread.get(id) ?? 0) + 1);
194
+ if (key.length < 4) continue;
195
+ const meant = known.find((k) => k.length >= 4 && isOneEditApart(key, k));
196
+ if (meant === undefined) continue;
197
+ const hit = nearMisses.get(id) ?? { ev: event.ev, key, meant, count: 0 };
198
+ hit.count += 1;
199
+ nearMisses.set(id, hit);
200
+ }
201
+ }
202
+ return { unread, nearMisses: [...nearMisses.values()].sort((a, b) => (a.ev + a.key).localeCompare(b.ev + b.key)) };
203
+ }
204
+
86
205
  /**
87
206
  * Closed VALUE sets inside `data`, for the same reason the event set is
88
207
  * closed: an unknown value must be a loud rejection at append time, not a
@@ -331,6 +450,74 @@ export function pairSpawns(events) {
331
450
  return { open, orphanReports, badNames, pairs, unusable, ambiguous };
332
451
  }
333
452
 
453
+ /**
454
+ * The one `checkpoint.phase` value that MEANS something to a reader.
455
+ *
456
+ * `phase` is otherwise free text — the field carries epic labels (`E2`),
457
+ * lifecycle notes (`resumed`, `usage-limit-pause`) and whatever else a
458
+ * conductor finds useful, and it stays that way. This single value is
459
+ * reserved: it says the initiative is over, which is the one thing a
460
+ * projection cannot infer from any other event. Nothing in `EVENT_TYPES`
461
+ * closes an initiative, so before this an initiative could be wound up with
462
+ * its spawns still open, and every consumer went on calling those agents
463
+ * live for as long as the journal survived.
464
+ *
465
+ * Compared case-insensitively and trimmed, because it is written by hand.
466
+ */
467
+ export const CLOSED_PHASE = 'closed';
468
+
469
+ /** Does this checkpoint's phase declare the initiative over? */
470
+ export function isClosingPhase(phase) {
471
+ return typeof phase === 'string' && phase.trim().toLowerCase() === CLOSED_PHASE;
472
+ }
473
+
474
+ /**
475
+ * How long an open spawn may stand, in JOURNAL time, before it is stale.
476
+ *
477
+ * Lives here rather than in either consumer because both `doctor.mjs` and
478
+ * `project.mjs` have to answer the same question and neither may own it:
479
+ * doctor imports the projection, so the projection cannot import doctor back.
480
+ * It is the same reasoning `pairSpawns` above records — the projection used to
481
+ * compute "who is still working" with a rule of its own, and the operator got
482
+ * two contradictory pictures. Staleness was the half of that answer still
483
+ * written twice: doctor said an agent had been abandoned while the board went
484
+ * on calling it `running` forever.
485
+ */
486
+ export const DEFAULT_STALE_HOURS = 4;
487
+
488
+ /** Hours between two ISO timestamps, or null if either is unparseable. */
489
+ export function hoursBetween(fromTs, toTs) {
490
+ const from = Date.parse(fromTs);
491
+ const to = Date.parse(toTs);
492
+ if (Number.isNaN(from) || Number.isNaN(to)) return null;
493
+ return (to - from) / 3_600_000;
494
+ }
495
+
496
+ /**
497
+ * Is this open spawn stale, measured against the initiative's own movement?
498
+ *
499
+ * `reference` is the journal's latest timestamp, NOT the wall clock, and that
500
+ * is the whole point: staleness here means "the initiative moved on without
501
+ * it", which is a property of the recorded history and reads the same in six
502
+ * months as it does now. A wall-clock rule would instead call every agent in
503
+ * a finished initiative stale the moment you walked away from it.
504
+ *
505
+ * That also keeps `board.json` byte-exact under `--check`: the answer is
506
+ * derived from event timestamps, so two clones of one journal agree. The
507
+ * `age-fresh/warm/cold/dead` colours on the HTML page are a DIFFERENT
508
+ * question — "how long since it last spoke, right now, in the reader's own
509
+ * timezone" — computed client-side precisely because the artefact may not
510
+ * read a clock. An agent can be `age-dead` (quiet for hours) without being
511
+ * stale, and stale without being `age-dead`.
512
+ *
513
+ * Returns the age alongside the verdict so a caller that reports the number
514
+ * does not recompute it — the same additive shape `pairSpawns` returns.
515
+ */
516
+ export function spawnStaleness(spawnTs, reference, staleHours = DEFAULT_STALE_HOURS) {
517
+ const ageHours = reference === null || reference === undefined ? null : hoursBetween(spawnTs, reference);
518
+ return { ageHours, stale: ageHours !== null && ageHours >= staleHours, staleHours };
519
+ }
520
+
334
521
  /** Agents whose `spawn` has no matching `report` or `review` yet — the "still working" set. */
335
522
  export function openSpawns(file) {
336
523
  const { open } = pairSpawns(readJournal(file).events);
@@ -506,6 +693,35 @@ function appendUnderLock(file, event, preread = null) {
506
693
  if (issuePrefix !== undefined && isDataObject(stamped.data) && (stamped.data.id === undefined || stamped.data.id === '')) {
507
694
  // a fresh object: the `data` the caller passed in stays the caller's
508
695
  stamped.data = { ...stamped.data, id: nextIdFrom(read().events, issuePrefix) };
696
+ } else if (issuePrefix !== undefined && isDataObject(stamped.data) && typeof stamped.data.id === 'string') {
697
+ // A caller-supplied id that is ALREADY TAKEN is refused.
698
+ //
699
+ // Measured in the field: two implementers running in parallel each passed
700
+ // an id they had worked out for themselves, and both were honoured — the
701
+ // ledger then held two `F-7`s, and "see F-7" is ambiguous forever, because
702
+ // history is append-only and nothing detects it later.
703
+ //
704
+ // The narrow fix, not the broad one. Refusing EVERY caller-supplied id was
705
+ // the first proposal and it removes a documented capability — the comment
706
+ // above says an explicit id still wins, and a test pins it — to prevent a
707
+ // failure that only ever occurs on COLLISION. So collision is what this
708
+ // refuses, and a fresh explicit id still passes untouched.
709
+ //
710
+ // Inside the lock, on the same read as the mint above: a check outside it
711
+ // would let two concurrent writers both pass and both append, which is the
712
+ // exact race being closed.
713
+ const taken = read().events.some(
714
+ (e) => e?.ev === stamped.ev && typeof e?.data?.id === 'string' && e.data.id === stamped.data.id,
715
+ );
716
+ if (taken) {
717
+ throw new Error(
718
+ `invalid event: ${q(stamped.ev)} id ${q(stamped.data.id)} is already used in ${q(file)}.\n` +
719
+ ' Two events under one id make every later reference to it ambiguous, and the journal is\n' +
720
+ ' append-only, so nothing can disambiguate them afterwards.\n' +
721
+ ` Omit "id" and ${q('append')} issues the next free one, which is what it is for — or run\n` +
722
+ ` node scripts/journal.mjs next-id ${q(file)} ${q(issuePrefix)}`,
723
+ );
724
+ }
509
725
  }
510
726
  const errors = validateEvent(stamped);
511
727
  if (errors.length > 0) {
@@ -143,6 +143,60 @@ export function renderBrief(selected, matched, { budget = DEFAULT_BUDGET, dir =
143
143
  return [header, ...lines, ...tail].join('\n') + '\n';
144
144
  }
145
145
 
146
+ /**
147
+ * Which entries can never reach a handoff, and why.
148
+ *
149
+ * The budget is deliberately the pressure that keeps entries scoped, and the
150
+ * omission line names the cost of every individual brief. What nothing did
151
+ * was AGGREGATE that: measured on a real install, `brief '**'` returned **1
152
+ * of 31 entries** and the other thirty were dropped by the 4000-codepoint
153
+ * budget. Ninety kilobytes of measured detail — migration-number races,
154
+ * TEST/PROD schema drift — accumulated for months and reached nobody.
155
+ *
156
+ * That is the opposite of the failure people expect. The store is not
157
+ * expensive to read; it is unread, while growing without bound, and the
158
+ * pressure the budget applies lands on nothing because no one is looking at
159
+ * the total.
160
+ *
161
+ * So this reports the whole store against the budget at once. It is a
162
+ * MEASUREMENT, never an edit: pruning needs judgement about which of two
163
+ * overlapping entries is the true one, and a script that guessed would delete
164
+ * exactly the hard-won detail this exists to protect.
165
+ *
166
+ * `alone` is the diagnostic that matters most: an entry that does not fit the
167
+ * budget even as the ONLY entry can never appear in any brief, under any
168
+ * paths, ever. It is not competing for space — it is unreachable.
169
+ */
170
+ export function auditEntries(entries, { budget = DEFAULT_BUDGET } = {}) {
171
+ const sized = entries.map((entry) => {
172
+ const cost = Array.from(entryLine(entry)).length + 1;
173
+ return { id: entry.id, kind: entry.kind, confidence: entry.confidence, cost, alone: cost > budget };
174
+ });
175
+ // Ranked the way `brief` ranks, so "would reach a brief" means what a brief
176
+ // would actually do rather than what this function finds convenient.
177
+ const ranked = [...sized].sort((a, b) => (b.confidence ?? 0) - (a.confidence ?? 0));
178
+ let used = 0;
179
+ let reachable = 0;
180
+ for (const entry of ranked) {
181
+ if (used + entry.cost > budget && reachable > 0) break;
182
+ used += entry.cost;
183
+ reachable += 1;
184
+ }
185
+ const total = sized.reduce((sum, e) => sum + e.cost, 0);
186
+ return {
187
+ budget,
188
+ entries: sized.length,
189
+ // How many a single widest-possible brief could carry.
190
+ reachable,
191
+ unreachable: sized.length - reachable,
192
+ // Entries too large to appear even alone — the ones pruning must address
193
+ // first, because no budget any caller passes will rescue them.
194
+ aloneTooBig: sized.filter((e) => e.alone).map((e) => ({ id: e.id, cost: e.cost })),
195
+ totalCost: total,
196
+ widest: sized.slice().sort((a, b) => b.cost - a.cost).slice(0, 5).map((e) => ({ id: e.id, cost: e.cost })),
197
+ };
198
+ }
199
+
146
200
  // ---------------------------------------------------------------- CLI
147
201
 
148
202
  const VALUE_FLAGS = ['dir', 'kinds', 'limit', 'budget'];
@@ -190,8 +244,10 @@ function parseArgs(argv) {
190
244
 
191
245
  function main() {
192
246
  const [command, ...rest] = process.argv.slice(2);
193
- const usage = 'usage: knowledge.mjs brief [<path>...] [--dir <knowledge-dir>] [--kinds k,k] [--limit N] [--budget CHARS] [--json]';
194
- if (command !== 'brief') {
247
+ const usage =
248
+ 'usage: knowledge.mjs brief [<path>...] [--dir <knowledge-dir>] [--kinds k,k] [--limit N] [--budget CHARS] [--json]\n' +
249
+ ' knowledge.mjs audit [--dir <knowledge-dir>] [--budget CHARS] [--json]';
250
+ if (command !== 'brief' && command !== 'audit') {
195
251
  console.error(usage);
196
252
  process.exit(2);
197
253
  }
@@ -232,6 +288,37 @@ function main() {
232
288
  return;
233
289
  }
234
290
 
291
+ if (command === 'audit') {
292
+ const report = auditEntries(entries, { budget: flags.budget });
293
+ if (flags.json) {
294
+ console.log(jsonEscapeInvisible(JSON.stringify(report, null, 2)));
295
+ process.exitCode = 0;
296
+ return;
297
+ }
298
+ const out = [
299
+ `knowledge audit (${escapeInvisible(flags.dir)})`,
300
+ ` ${report.entries} entries, ${report.totalCost} codepoints total`,
301
+ ` ${report.reachable} could reach one brief at the ${report.budget}-codepoint budget; ` +
302
+ `${report.unreachable} could not`,
303
+ ];
304
+ if (report.aloneTooBig.length > 0) {
305
+ const n = report.aloneTooBig.length;
306
+ out.push(` ${n} entr${n === 1 ? 'y' : 'ies'} cannot appear in ANY brief, even alone:`);
307
+ for (const e of report.aloneTooBig) out.push(` ${escapeInvisible(e.id)} — ${e.cost} codepoints`);
308
+ }
309
+ if (report.widest.length > 0) {
310
+ out.push(' widest:');
311
+ for (const e of report.widest) out.push(` ${escapeInvisible(e.id)} — ${e.cost}`);
312
+ }
313
+ // A measurement, never an edit: which of two overlapping entries is the
314
+ // true one is a judgement, and a script that guessed would delete the
315
+ // hard-won detail this exists to protect.
316
+ out.push(' This reports; it never edits. /tyran:retro consolidates, writing a NEW file for review.');
317
+ process.stdout.write(out.join('\n') + '\n');
318
+ process.exitCode = 0;
319
+ return;
320
+ }
321
+
235
322
  const { selected, matched, limited } = selectEntries(entries, { paths: normalized, kinds: flags.kinds, limit: flags.limit });
236
323
  if (flags.json) {
237
324
  const payload = selected.map(({ id, kind, confidence, text, applies_to, file }) => ({