docs(cli): re-anchor the dead tracker citations in lane files outside stage 14's list to the commits that decided them

.changeset/20594-cli-bin-provenance-anchors.md

@@ -0,0 +1,12 @@
+---
+'@objectstack/cli': patch
+---
+
+Provenance comments in `@objectstack/cli`'s `bin/run.js` were re-anchored
+
+Three docblock lines above `bin/run.js`'s `process.stderr` `error` listener
+cited a tracker number that no longer resolves on GitHub. They now cite the
+commit in this repository's history that made a failed stderr write non-fatal
+on the dev shim. The file ships because npm packs a `bin` target regardless of
+`files`, which is why this is a release note at all. Comment only: no command,
+flag, exit code, error code, export or runtime behaviour changes.

packages/cli/bin/run-dev.js

@@ -68,7 +68,7 @@ const STDERR_DRAIN_POLL_MS = 50;
  * OWN default `warning` handler, which stays attached and prints every warning
  * as well (#16691, drained run: 147 729 bytes over 179 writes, 111 751 of them
  * from `config.js`, 35 133 from `internal/process/warning.js`). Measured on the
- * #12964 repro with a reader that was not draining: the pipe delivered exactly
+ * repro commit e6fd1caf7 fixed, with a reader that was not draining: the pipe delivered exactly
  * one 64 KiB buffer and everything after it was lost — this diagnostic AND
  * oclif's own `command … not found`, which `handle()` writes a moment later and
  * which the same tear-down takes.
@@ -149,7 +149,7 @@ async function announceInvocationFailure(error) {
 
 /**
  * Every module-load failure oclif reported while building its command table
- * (#12964), in emission order. Filled by the listener attached below.
+ * (commit e6fd1caf7), in emission order. Filled by the listener attached below.
  *
  * It HAS to be collected as it happens. `findCommand` `import()`s every command
  * module while `Config.load()` runs, warns on each one that will not load, and
@@ -359,7 +359,7 @@ if (!process.env.TSX_TSCONFIG_PATH) {
       env: { ...process.env, TSX_TSCONFIG_PATH: CLI_TSCONFIG },
     });
     if (!child.error) {
-      // A signalled child is reported as a signal, never as an exit code: #14715
+      // A signalled child is reported as a signal, never as an exit code: commit accb9231c
       // pinned that this CLI answers 2 for a failed run, and laundering a
       // SIGKILL into some number would make a killed child indistinguishable
       // from one that decided.
@@ -374,7 +374,7 @@ if (!process.env.TSX_TSCONFIG_PATH) {
 
 /**
  * Make a FAILED stderr write non-fatal, so a caller whose read end is gone
- * still gets this CLI's own exit status instead of a crash. #14858.
+ * still gets this CLI's own exit status instead of a crash. Commit 0c5e97368.
  *
  * `process.stderr` is an `EventEmitter`, and an `error` event with nothing
  * listening IS an uncaught exception. With the parent's read end DESTROYED
@@ -397,7 +397,7 @@ if (!process.env.TSX_TSCONFIG_PATH) {
  *
  * Every OTHER reader of the same child answers **2** — drained (1209-1217 ms,
  * 147699 bytes delivered) and never-read (16178-16471 ms) both did, in the same
- * conditions. 2 is what oclif's `handle()` produces, and #14715 pinned it for
+ * conditions. 2 is what oclif's `handle()` produces, and commit accb9231c pinned it for
  * the never-read reader. So the closed reader was the one shape that could not
  * tell "the command failed" from "the CLI crashed", on the only channel it had
  * left.
@@ -463,7 +463,7 @@ const running = run(process.argv.slice(2), import.meta.url);
 // `process.listenerCount('warning') <= 1`, i.e. only node's own default is
 // attached. A collector attached before `run()` makes that count 2, oclif
 // silently declines to install, and every failing run through this shim quietly
-// loses those blocks (measured on the #12964 repro: 1518 lines of report became
+// loses those blocks (measured on the repro commit e6fd1caf7 fixed: 1518 lines of report became
 // 476, with nothing saying why).
 //
 // `run()` reaches `Config.load()` — and `displayWarnings()` inside it — in its

packages/cli/bin/run.js

@@ -160,12 +160,12 @@ try {
 
 /**
  * Make a FAILED stderr write non-fatal, so a caller whose read end is gone
- * still gets this CLI's own exit status instead of a crash. #14858, reached on
+ * still gets this CLI's own exit status instead of a crash. The crash class commit 0c5e97368 fixed, reached on
  * THIS entry point by the #15564 measurement.
  *
  * `process.stderr` is an `EventEmitter`, and an `error` event with nothing
  * listening IS an uncaught exception. `bin/run-dev.js` has carried this
- * listener since #14858; the published entry did not, and #15564 was filed
+ * listener since commit 0c5e97368; the published entry did not, and #15564 was filed
  * NOT REPRODUCED because the two probes that had been run against it — a
  * bad command id, and `OBJECTSTACK_DEBUG=1` over an unbuilt `@objectstack/spec`
  * — both answered exit 2 with no `uncaughtException`. Re-run here, they still
@@ -217,7 +217,7 @@ try {
  *           at afterWriteDispatched (node:internal/stream_base_commons:159:15)
  *     exit  code=1
  *
- * 3 of 3 runs, 3049-3433 ms in — the same frame and the same status #14858
+ * 3 of 3 runs, 3049-3433 ms in — the same frame and the same status commit 0c5e97368's card
  * traced on the dev shim. The same child read by a draining parent boots and
  * serves, exit 0 at a 20 s SIGTERM, having written 7926 bytes over 16.6 s. So
  * the crash costs the run at its FIRST diagnostic line and 20 of its 21 stderr

packages/cli/scripts/check-app-nav-i18n.mjs

@@ -109,7 +109,7 @@ const CLI_ROOT = join(HERE, '..');
 
 // ---------------------------------------------------------------------------
 // THE POPULATION — which apps this gate judges, and the criterion that decides
-// it (#17891)
+// it (commit ca9d9d361)
 // ---------------------------------------------------------------------------
 //
 // An app belongs here iff BOTH halves hold. The criterion is what a future
@@ -145,7 +145,7 @@ const CLI_ROOT = join(HERE, '..');
 //
 // `account` satisfied both halves all along and was invisible anyway:
 // `@objectstack/mcp` contributes `nav_connect_agent` into
-// `grp_account_developer` (`connect-ui.ts`, #16746) and #17759 supplied its
+// `grp_account_developer` (`connect-ui.ts`, #16746) and commit c744c0af3 supplied its
 // label in all four locales — while this gate printed a BYTE-IDENTICAL
 // `OK (…)` line before and after that landing, because every site below
 // narrowed to one app name. Widening the three obvious filters is NOT the fix:
@@ -218,7 +218,7 @@ export function contributorsWithNoNavIds(contributions) {
  * contributes into both `setup` and `account`, so a union keeps it passing on
  * its `account` id alone after its `setup` contribution has silently stopped,
  * which is the exact "fewer ids means fewer checks" false green this invariant
- * exists to catch, restated one app wider (#17891). `--self-test` carries that
+ * exists to catch, restated one app wider (commit ca9d9d361). `--self-test` carries that
  * union as a negative control.
  *
  * A declared app with no bucket at all reads as ZERO ids, never as "not
@@ -234,8 +234,8 @@ export function contributionsForApp(contributions, appName) {
 /**
  * The pass line, as a VALUE so `--self-test` can pin it.
  *
- * Per-app counts are not cosmetics. #17891's whole measurement was a DIFF of
- * THIS LINE across #17759's landing, and the finding was that it came back
+ * Per-app counts are not cosmetics. The whole measurement behind commit ca9d9d361 was a DIFF of
+ * THIS LINE across commit c744c0af3's landing, and the finding was that it came back
  * byte-identical because one app's counts were all it carried. A summary that
  * collapses the apps back into one total rebuilds precisely that: a number that
  * moves for reasons the reader cannot attribute, and — worse — one that fails
@@ -256,9 +256,9 @@ export function summaryText(contributorCount, localeCount, perApp) {
  * ⛔ The app is a parameter, never this file's former single constant: the
  * bundles are keyed `apps.<app>.navigation.<id>`, one namespace per app, so
  * `apps.setup.navigation.nav_connect_agent` never answers for the same id under
- * `apps.account.navigation` (#17759). A widened gate whose verdict still said
+ * `apps.account.navigation` (commit c744c0af3). A widened gate whose verdict still said
  * `apps.setup.navigation` would send whoever it fails on to the wrong subtree
- * — a confident diagnosis pointing somewhere innocent (#17891).
+ * — a confident diagnosis pointing somewhere innocent (commit ca9d9d361).
  */
 function renderMissing(appName, locale, missing, declaredBy) {
   const lines = missing.map((id) => {
@@ -286,7 +286,7 @@ function renderMissing(appName, locale, missing, declaredBy) {
 // whose shell nobody registers has no merged navigation for the contributions
 // to merge into, so widening the filters without booting `@objectstack/account`
 // would have reported "the `account` app is not registered at all" instead of
-// judging a single label (#17891).
+// judging a single label (commit ca9d9d361).
 // ---------------------------------------------------------------------------
 
 const CONTRIBUTORS = [
@@ -299,7 +299,7 @@ const CONTRIBUTORS = [
     },
   },
   {
-    // The Account SHELL (#17891). `AccountAppPlugin.start` registers
+    // The Account SHELL (commit ca9d9d361). `AccountAppPlugin.start` registers
     // `ACCOUNT_APP` through the `manifest` service — the same seam every other
     // entry here uses — so the fake `ctx` below already serves it and no
     // credential fixture is needed. Its kernel `dependencies` name
@@ -499,7 +499,7 @@ function selfTest() {
   expect('#5750 verdict names the fallback literal', rendered.includes('HTTP Deliveries'), rendered);
   expect('#5750 verdict names the locale', rendered.includes('zh-CN'), rendered);
 
-  // ── The POPULATION, and the one way widening it goes wrong (#17891) ──
+  // ── The POPULATION, and the one way widening it goes wrong (commit ca9d9d361) ──
   //
   // The gate judges more than one app now. The half that can be widened WRONG
   // is the per-contributor invariant: flattening each contributor's ids into a
@@ -534,7 +534,7 @@ function selfTest() {
 
   // The verdict must name the APP as well as the id: one namespace per app, so
   // `apps.setup.navigation.nav_connect_agent` does not answer for the same id
-  // under `apps.account.navigation` (#17759). A verdict naming only the id
+  // under `apps.account.navigation` (commit c744c0af3). A verdict naming only the id
   // sends the reader to whichever subtree they guessed.
   const renderedAccount = renderMissing(
     'account',
@@ -549,7 +549,7 @@ function selfTest() {
     renderedAccount,
   );
 
-  // The pass line. #17891's whole measurement was a DIFF of this line across a
+  // The pass line. The whole measurement behind commit ca9d9d361 was a DIFF of this line across a
   // landing, and it came back byte-identical because one app's counts were all
   // it carried.
   const summary = summaryText(11, 4, [{ app: 'setup', ids: 54 }, { app: 'account', ids: 12 }]);
@@ -703,7 +703,7 @@ if (process.argv.includes('--self-test')) {
  * into the red while the code beside it was already correct.)
  */
 function checkBuildPrerequisite() {
-  // ONE PROBE PER APP SHELL (#17891). A probe hard-coded to `@objectstack/setup`
+  // ONE PROBE PER APP SHELL (commit ca9d9d361). A probe hard-coded to `@objectstack/setup`
   // answers for one app in a population of two: with Account unbuilt it returns
   // happily, and the missing build arrives eleven lines further down as
   // `COULD NOT BOOT — @objectstack/account`, which is a finding about a plugin

packages/cli/vitest-tiers.fixtures.ts

@@ -191,7 +191,7 @@ export const PREDICATE_CASES: PredicateCase[] = [
 
   // -------------------------------------------------------------------------
   // The false positives the predicate was tuned against — every one of these
-  // was a real miscount of the text-match census #13504 replaced.
+  // was a real miscount of the text-match census commit 44813ba57 replaced.
   // -------------------------------------------------------------------------
   {
     name: 'a type-only driver import',

packages/cli/vitest-tiers.ts

@@ -2,7 +2,7 @@
 
 /**
  * The `unit` / `integration` tier predicate for this package's suite, and the
- * DERIVATION of the integration population from it (#13504, #14554).
+ * DERIVATION of the integration population from it (commit 44813ba57, #14554).
  *
  * `vitest.config.ts` imports `integrationTestFiles()` and hands the result
  * straight to the two projects; `test/vitest-tiers-partition.test.ts` imports
@@ -64,7 +64,7 @@
  *   INTEGRATION = SPAWN ∨ KERNEL.
  *
  * ⛔ THE PREDICATE IS WHAT A FILE DOES, NOT WHAT IT IS CALLED — the `.e2e`
- * name and the behaviour disagree on 5 files here, and the ACCEPT on #13504
+ * name and the behaviour disagree on 5 files here, and the ACCEPT on commit 44813ba57's card
  * measured 18 of 220 disagreeing under the name-and-text census this replaced.
  *
  * Value imports only: `import type { … } from '@objectstack/driver-sql'` loads

packages/plugins/plugin-hono-server/objectstack.config.ts

@@ -16,14 +16,14 @@ const HonoServerPlugin: ObjectStackManifest = {
   scope: 'project',
   description: 'HTTP server adapter using Hono framework. Exposes ObjectStack Runtime Protocol via REST API endpoints.',
 
-  // `configuration` and `capabilities` were retired (#11332, ADR-0049
+  // `configuration` and `capabilities` were retired (commit dce5cd4f0, ADR-0049
   // enforce-or-remove): nothing ever read either container. The port and
   // static-root settings this adapter needs are passed by the host that
   // composes it (the options object handed to its constructor), and
   // protocol/capability discovery never consulted the declaration —
   // dependency resolution runs off top-level `dependencies`.
 
-  // `contributes.events` was retired (#10724, ADR-0049): the declaration drove
+  // `contributes.events` was retired (commit be21955ba, ADR-0049): the declaration drove
   // nothing — this plugin already subscribes to `kernel:ready` / `kernel:listening`
   // imperatively in its own code, which is the enforced channel.
 };