instar 1.3.1160 → 1.3.1161

package/dist/data/standards-guard-index.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "generatedFrom": "source-tree",
   "registrySha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
-  "packageVersion": "1.3.1160",
+  "packageVersion": "1.3.1161",
   "guards": [
     {
       "ref": "docs/audits/phase-b/f10-triage.md",

package/dist/data/standards-guard-index.meta.json

@@ -1,5 +1,5 @@
 {
-  "sha256": "05daed4cc90fbaa0916c051d8cf8985aa11cdc27f15f50ea5a3ffeff29550857",
+  "sha256": "43851e9ac8b44d594fefed64286f3c7d1a9e5028b8b96934309d13cb50851fad",
   "registrySha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
-  "packageVersion": "1.3.1160"
+  "packageVersion": "1.3.1161"
 }

package/dist/data/standards-registry.meta.json

@@ -2,5 +2,5 @@
   "sha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
   "articleCount": 88,
   "generatedFrom": "docs/STANDARDS-REGISTRY.md",
-  "packageVersion": "1.3.1160"
+  "packageVersion": "1.3.1161"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.1160",
+  "version": "1.3.1161",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-08-15T04:54:47.730Z",
-  "instarVersion": "1.3.1160",
+  "generatedAt": "2026-08-15T05:03:51.309Z",
+  "instarVersion": "1.3.1161",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {

package/src/data/standards-guard-index.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "generatedFrom": "source-tree",
   "registrySha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
-  "packageVersion": "1.3.1160",
+  "packageVersion": "1.3.1161",
   "guards": [
     {
       "ref": "docs/audits/phase-b/f10-triage.md",

package/src/data/standards-guard-index.meta.json

@@ -1,5 +1,5 @@
 {
-  "sha256": "05daed4cc90fbaa0916c051d8cf8985aa11cdc27f15f50ea5a3ffeff29550857",
+  "sha256": "43851e9ac8b44d594fefed64286f3c7d1a9e5028b8b96934309d13cb50851fad",
   "registrySha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
-  "packageVersion": "1.3.1160"
+  "packageVersion": "1.3.1161"
 }

package/src/data/standards-registry.meta.json

@@ -2,5 +2,5 @@
   "sha256": "81b53363a440e832672618965540b3e507ae0d93adcc67ec2b93daf7933b3ab4",
   "articleCount": 88,
   "generatedFrom": "docs/STANDARDS-REGISTRY.md",
-  "packageVersion": "1.3.1160"
+  "packageVersion": "1.3.1161"
 }

package/upgrades/1.3.1161.md

@@ -0,0 +1,50 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Adds `tests/setup/nativeModuleHealth.globalSetup.ts`, wired into `vitest.config.ts`
+after `build-dist.globalSetup.ts`. It probes better-sqlite3 once (load AND open an
+in-memory DB) and, only when that fails, prints one line at setup and a single
+banner at TEARDOWN — which vitest renders after the run summary, beside the failure
+count.
+
+## What to Tell Your User
+
+None — internal change (no user-facing surface).
+
+## Summary of New Capabilities
+
+None — internal change (no user-facing surface).
+
+## Evidence
+
+- `tests/unit/native-module-health-banner.test.ts` — 11/11.
+- **Placement proven END-TO-END, not asserted**: the broken branch was forced by
+  mutation (count-asserted at exactly 1 — the first attempt applied 0 times and was
+  caught by that control), a suite was run, and the banner rendered AFTER the
+  `Test Files / Tests / Duration` summary. Source restored byte-exact, 0 markers.
+- Probe covers the incident's real signature — the module LOADS but cannot open a
+  database. A require-only probe would have reported healthy for the entire outage;
+  that case is pinned.
+- Over-block control: given a healthy probe it writes NOTHING and returns NO
+  teardown. It also cannot throw — a throwing probe is reported, not propagated,
+  because this runs before every suite.
+- `tsc --noEmit` exit 0 via the real binary; full lint chain exit 0.
+
+## Why
+
+Measured 2026-08-15: a local full suite reported 225 failing files; 108 were
+downstream of better-sqlite3 having no native binary in that checkout (the install
+had skipped its postinstall). instar diagnosed it correctly and printed the remedy
+**189 times**, and that did not help — 189 lines in a 21MB log is volume, not a
+signal. This does not add detection; it moves the existing diagnosis to where it is
+read.
+
+## Not closed
+
+Scoped to better-sqlite3 alone — deliberately, since generalising from one incident
+is the over-read that caused it. The install hygiene itself is unchanged; this makes
+its consequence legible, it does not prevent it.

package/upgrades/side-effects/native-module-health-banner.md

@@ -0,0 +1,60 @@
+# Side-effects review — native-module health banner
+
+## The change
+
+A vitest globalSetup that probes better-sqlite3 once and, only on failure, emits one
+setup line plus a single banner at teardown (rendered after the run summary). Adds no
+detection: it relocates a diagnosis instar already produces to where a reader looks.
+
+## Review answers
+
+1. **Over-block.** The dominant risk, because this runs before EVERY suite on every
+   machine. It writes nothing and returns no teardown on a healthy probe — pinned by a
+   control. It never fails, skips, or changes an exit code. And it cannot throw: the
+   probe is wrapped even though the default probe already catches internally, because
+   an exception here would take down every run — strictly worse than the degraded
+   state it describes.
+2. **Under-block.** It watches ONE module. A different native module breaking silently
+   gets no banner. That is deliberate: generalising to "native modules" from a single
+   incident would be inventing a class, which is the exact over-read that caused the
+   incident. It also cannot detect a module that loads, opens a DB, and misbehaves
+   later — the probe is a smoke test, not a health monitor.
+3. **Level-of-abstraction fit.** globalSetup is the right layer: a per-file check is
+   invisible to the next file (this file's sibling records that lesson explicitly),
+   and teardown is the only hook that runs after the summary.
+4. **Signal vs authority.** Pure signal. It gates nothing and rejects nothing.
+5. **Interactions.** Ordered AFTER `build-dist.globalSetup.ts`, so its teardown runs
+   FIRST (teardowns run in reverse) and the banner sits closest to the summary. It
+   shares no state with any other setup.
+6. **External surfaces.** None. Test-run stderr only; nothing ships to an agent or a
+   user, no file is written.
+7. **Multi-machine posture.** Machine-local BY DESIGN — it reports on THIS checkout's
+   node_modules. There is nothing to replicate; a peer's binary state is irrelevant to
+   a local run.
+8. **Rollback cost.** Remove the config entry, or delete the file. No migration, no
+   state, no consumer.
+
+## Class closure — what this does NOT close
+
+- **It does not prevent the cause.** An install that skips its postinstall still
+  produces a broken checkout; this only makes the consequence readable. The hygiene
+  fix (never installing with `--ignore-scripts`) is a habit, not code, and I am not
+  claiming otherwise.
+- **Only better-sqlite3**, and only at run start.
+- **Placement depends on vitest rendering teardown output after the summary.** That is
+  measured on vitest 2.1.9 here, not guaranteed by contract. If a future version
+  reorders it, the setup line still fires at the top — which is why both exist.
+
+## Evidence
+
+- 11/11 in `tests/unit/native-module-health-banner.test.ts`; `tsc --noEmit` exit 0 via
+  the real binary; full lint chain exit 0.
+- **Placement proven end-to-end.** The broken branch was forced by mutation and a real
+  suite was run; the banner rendered AFTER `Test Files / Tests / Duration`. **My first
+  mutation attempt applied 0 times and its own count control caught it** — that run
+  would have "passed" while proving nothing, which is the defect class this whole
+  change is about. Re-applied against the real line (count asserted at exactly 1),
+  re-run, restored byte-exact with 0 markers.
+- The incident's real signature is pinned: a module that LOADS but cannot open a
+  database is reported BROKEN. A require-only probe would have called the entire
+  outage healthy.