@intentic/constants 1.239.0 → 1.242.0

package/README.md

@@ -13,10 +13,17 @@ The ports, paths and image references the daemon, the CLIs and the desktop app a
   values, and the install-script table. Isomorphic, imported by browser code, so nothing here may touch `node:fs`.
 - [src/node.mjs](src/node.mjs): `repoRoot()` and `packageRoot()`, behind the `@intentic/constants/node`
   subpath. Node-only, and hand-written JavaScript rather than compiled TypeScript.
+- [src/assertion-measure.mjs](src/assertion-measure.mjs), [src/contract-shrink.mjs](src/contract-shrink.mjs) and
+  [src/control-bytes.mjs](src/control-bytes.mjs): the three judgments the repository's checkout gates
+  (`_tools/checks/`) and the daemon both make, kept as one copy each. Hand-written JavaScript for the same
+  reason `node.mjs` is: a gate that runs before `pnpm install` imports them by relative path, and the daemon
+  imports them as subpaths of this package.
 
 ## How it fits
 
-The bottom of the dependency graph: it imports nothing and almost everything imports it. A port number that lives
+The bottom of the dependency graph: it imports nothing and almost everything imports it. That is also what
+makes it the home of the few pure judgments a pre-install script and the daemon have to share: anything else
+they could both import would need an install to resolve. A port number that lives
 in two files is a port number that will eventually be two different numbers, which is the entire argument for
 this package existing. The same argument covers the directory layouts: `/work`, `/history`, `.intentic`,
 `/opt/intentic`: which were previously typed out by hand across dozens of files with nothing linking the copies.
@@ -41,7 +48,7 @@ by nothing. Walking up to a marker has no such coupling, so a file can move anyw
   gets written. It is also why the root `package.json` depends on this package: without that link, scripts under
   `_tools/scripts/` cannot resolve it by name.
 - **The name only resolves once `pnpm install` has run**, because a bare specifier is looked up through
-  `node_modules`. The two callers that run before any install: `prepass.mjs --checks-only`, which the `pre-push`
+  `node_modules`. The two callers that run before any install: `_tools/checks/run.mjs`, which the `pre-push`
   hook and the CI `preflight` job invoke on a bare checkout: therefore import `../constants/src/node.mjs` by
   path. Same file, same single copy of the walk, no install required. Everything that runs after the install
   imports it by name.

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export declare const WORKSPACE_ROOT = "/work";
 export declare const HISTORY_ROOT = "/history";
 export declare const STATE_DIR = ".intentic";
 export declare const HOST_STATE_ROOT = "/opt/intentic";
-export declare const LEGAL_VERSION = "2026-08-13";
+export declare const LEGAL_VERSION = "2026-09-03";
 export declare const LEGAL_CONTACT_EMAIL = "contact@intentic.dev";
 export declare const LEGAL_ENTITY_NAME = "Artur Kurowski, trading as radarsu";
 export declare const LEGAL_ENTITY_COUNTRY = "Poland";

package/dist/index.js

@@ -3,7 +3,7 @@ export const WORKSPACE_ROOT = "/work";
 export const HISTORY_ROOT = "/history";
 export const STATE_DIR = ".intentic";
 export const HOST_STATE_ROOT = "/opt/intentic";
-export const LEGAL_VERSION = "2026-08-13";
+export const LEGAL_VERSION = "2026-09-03";
 export const LEGAL_CONTACT_EMAIL = "contact@intentic.dev";
 export const LEGAL_ENTITY_NAME = "Artur Kurowski, trading as radarsu";
 export const LEGAL_ENTITY_COUNTRY = "Poland";

package/dist/provider-logos.d.ts

@@ -5,6 +5,8 @@ export declare const PROVIDER_BRAND_PATHS: {
     readonly kimi: `M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z`;
     readonly gemini: `M11.04 19.32Q12 21.51 12 24q0-2.49.93-4.68.96-2.19 2.58-3.81t3.81-2.55Q21.51 12 24 12q-2.49 0-4.68-.93a12.3 12.3 0 0 1-3.81-2.58 12.3 12.3 0 0 1-2.58-3.81Q12 2.49 12 0q0 2.49-.96 4.68-.93 2.19-2.55 3.81a12.3 12.3 0 0 1-3.81 2.58Q2.49 12 0 12q2.49 0 4.68.96 2.19.93 3.81 2.55t2.55 3.81`;
     readonly cursor: `M11.503.131 1.891 5.678a.84.84 0 0 0-.42.726v11.188c0 .3.162.575.42.724l9.609 5.55a1 1 0 0 0 .998 0l9.61-5.55a.84.84 0 0 0 .42-.724V6.404a.84.84 0 0 0-.42-.726L12.497.131a1.01 1.01 0 0 0-.996 0M2.657 6.338h18.55c.263 0 .43.287.297.515L12.23 22.918c-.062.107-.229.064-.229-.06V12.335a.59.59 0 0 0-.295-.51l-9.11-5.257c-.109-.063-.064-.23.061-.23`;
+    readonly meta: `M6.915 4.03c-1.968 0-3.683 1.28-4.871 3.113C.704 9.208 0 11.883 0 14.449c0 .706.07 1.369.21 1.973a6.624 6.624 0 0 0 .265.86 5.297 5.297 0 0 0 .371.761c.696 1.159 1.818 1.927 3.593 1.927 1.497 0 2.633-.671 3.965-2.444.76-1.012 1.144-1.626 2.663-4.32l.756-1.339.186-.325c.061.1.121.196.183.3l2.152 3.595c.724 1.21 1.665 2.556 2.47 3.314 1.046.987 1.992 1.22 3.06 1.22 1.075 0 1.876-.355 2.455-.843a3.743 3.743 0 0 0 .81-.973c.542-.939.861-2.127.861-3.745 0-2.72-.681-5.357-2.084-7.45-1.282-1.912-2.957-2.93-4.716-2.93-1.047 0-2.088.467-3.053 1.308-.652.57-1.257 1.29-1.82 2.05-.69-.875-1.335-1.547-1.958-2.056-1.182-.966-2.315-1.303-3.454-1.303zm10.16 2.053c1.147 0 2.188.758 2.992 1.999 1.132 1.748 1.647 4.195 1.647 6.4 0 1.548-.368 2.9-1.839 2.9-.58 0-1.027-.23-1.664-1.004-.496-.601-1.343-1.878-2.832-4.358l-.617-1.028a44.908 44.908 0 0 0-1.255-1.98c.07-.109.141-.224.211-.327 1.12-1.667 2.118-2.602 3.358-2.602zm-10.201.553c1.265 0 2.058.791 2.675 1.446.307.327.737.871 1.234 1.579l-1.02 1.566c-.757 1.163-1.882 3.017-2.837 4.338-1.191 1.649-1.81 1.817-2.486 1.817-.524 0-1.038-.237-1.383-.794-.263-.426-.464-1.13-.464-2.046 0-2.221.63-4.535 1.66-6.088.454-.687.964-1.226 1.533-1.533a2.264 2.264 0 0 1 1.088-.285z`;
+    readonly zai: `M12.105 2L9.927 4.953H.653L2.83 2h9.276zM23.254 19.048L21.078 22h-9.242l2.174-2.952h9.244zM24 2L9.264 22H0L14.736 2H24z`;
 };
 export type ProviderBrand = keyof typeof PROVIDER_BRAND_PATHS;
 export declare const providerFillRule: (brand: ProviderBrand) => "evenodd" | undefined;

package/dist/provider-logos.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"provider-logos.d.ts","sourceRoot":"","sources":["../src/provider-logos.ts"],"names":[],"mappings":"AAWA,eAAO,MAAM,oBAAoB;aAC7B,MAAM,EAAE,qxDAAqxD;aAC7xD,KAAK,EAAE,s7CAAs7C;aAC77C,IAAI,EAAE,8iBAA8iB;aAGpjB,IAAI,EAAE,iDAAiD;aACvD,MAAM,EAAE,8RAA8R;aAGtS,MAAM,EAAE,0VAA0V;CAC5V,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,oBAAoB,CAAC;AAG9D,eAAO,MAAM,gBAAgB,UAAW,aAAa,KAAG,SAAS,GAAG,SAAuD,CAAC"}
+{"version":3,"file":"provider-logos.d.ts","sourceRoot":"","sources":["../src/provider-logos.ts"],"names":[],"mappings":"AAiBA,eAAO,MAAM,oBAAoB;aAC7B,MAAM,EAAE,qxDAAqxD;aAC7xD,KAAK,EAAE,s7CAAs7C;aAC77C,IAAI,EAAE,8iBAA8iB;aAGpjB,IAAI,EAAE,iDAAiD;aACvD,MAAM,EAAE,8RAA8R;aAGtS,MAAM,EAAE,0VAA0V;aAGlW,IAAI,EAAE,ksCAAksC;aAIxsC,GAAG,EAAE,yHAAyH;CACxH,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,oBAAoB,CAAC;AAS9D,eAAO,MAAM,gBAAgB,UAAW,aAAa,KAAG,SAAS,GAAG,SAAgE,CAAC"}

package/dist/provider-logos.js

@@ -5,6 +5,9 @@ export const PROVIDER_BRAND_PATHS = {
     kimi: `M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z`,
     gemini: `M11.04 19.32Q12 21.51 12 24q0-2.49.93-4.68.96-2.19 2.58-3.81t3.81-2.55Q21.51 12 24 12q-2.49 0-4.68-.93a12.3 12.3 0 0 1-3.81-2.58 12.3 12.3 0 0 1-2.58-3.81Q12 2.49 12 0q0 2.49-.96 4.68-.93 2.19-2.55 3.81a12.3 12.3 0 0 1-3.81 2.58Q2.49 12 0 12q2.49 0 4.68.96 2.19.93 3.81 2.55t2.55 3.81`,
     cursor: `M11.503.131 1.891 5.678a.84.84 0 0 0-.42.726v11.188c0 .3.162.575.42.724l9.609 5.55a1 1 0 0 0 .998 0l9.61-5.55a.84.84 0 0 0 .42-.724V6.404a.84.84 0 0 0-.42-.726L12.497.131a1.01 1.01 0 0 0-.996 0M2.657 6.338h18.55c.263 0 .43.287.297.515L12.23 22.918c-.062.107-.229.064-.229-.06V12.335a.59.59 0 0 0-.295-.51l-9.11-5.257c-.109-.063-.064-.23.061-.23`,
+    meta: `M6.915 4.03c-1.968 0-3.683 1.28-4.871 3.113C.704 9.208 0 11.883 0 14.449c0 .706.07 1.369.21 1.973a6.624 6.624 0 0 0 .265.86 5.297 5.297 0 0 0 .371.761c.696 1.159 1.818 1.927 3.593 1.927 1.497 0 2.633-.671 3.965-2.444.76-1.012 1.144-1.626 2.663-4.32l.756-1.339.186-.325c.061.1.121.196.183.3l2.152 3.595c.724 1.21 1.665 2.556 2.47 3.314 1.046.987 1.992 1.22 3.06 1.22 1.075 0 1.876-.355 2.455-.843a3.743 3.743 0 0 0 .81-.973c.542-.939.861-2.127.861-3.745 0-2.72-.681-5.357-2.084-7.45-1.282-1.912-2.957-2.93-4.716-2.93-1.047 0-2.088.467-3.053 1.308-.652.57-1.257 1.29-1.82 2.05-.69-.875-1.335-1.547-1.958-2.056-1.182-.966-2.315-1.303-3.454-1.303zm10.16 2.053c1.147 0 2.188.758 2.992 1.999 1.132 1.748 1.647 4.195 1.647 6.4 0 1.548-.368 2.9-1.839 2.9-.58 0-1.027-.23-1.664-1.004-.496-.601-1.343-1.878-2.832-4.358l-.617-1.028a44.908 44.908 0 0 0-1.255-1.98c.07-.109.141-.224.211-.327 1.12-1.667 2.118-2.602 3.358-2.602zm-10.201.553c1.265 0 2.058.791 2.675 1.446.307.327.737.871 1.234 1.579l-1.02 1.566c-.757 1.163-1.882 3.017-2.837 4.338-1.191 1.649-1.81 1.817-2.486 1.817-.524 0-1.038-.237-1.383-.794-.263-.426-.464-1.13-.464-2.046 0-2.221.63-4.535 1.66-6.088.454-.687.964-1.226 1.533-1.533a2.264 2.264 0 0 1 1.088-.285z`,
+    zai: `M12.105 2L9.927 4.953H.653L2.83 2h9.276zM23.254 19.048L21.078 22h-9.242l2.174-2.952h9.244zM24 2L9.264 22H0L14.736 2H24z`,
 };
-export const providerFillRule = (brand) => (brand === `grok` ? `evenodd` : undefined);
+const EVENODD_BRANDS = new Set([`grok`, `zai`]);
+export const providerFillRule = (brand) => (EVENODD_BRANDS.has(brand) ? `evenodd` : undefined);
 //# sourceMappingURL=provider-logos.js.map

package/dist/provider-logos.js.map

@@ -1 +1 @@
-{"version":3,"file":"provider-logos.js","sourceRoot":"","sources":["../src/provider-logos.ts"],"names":[],"mappings":"AAWA,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAChC,MAAM,EAAE,qxDAAqxD;IAC7xD,KAAK,EAAE,s7CAAs7C;IAC77C,IAAI,EAAE,8iBAA8iB;IAGpjB,IAAI,EAAE,iDAAiD;IACvD,MAAM,EAAE,8RAA8R;IAGtS,MAAM,EAAE,0VAA0V;CAC5V,CAAC;AAKX,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,KAAoB,EAAyB,EAAE,CAAC,CAAC,KAAK,KAAK,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC"}
+{"version":3,"file":"provider-logos.js","sourceRoot":"","sources":["../src/provider-logos.ts"],"names":[],"mappings":"AAiBA,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAChC,MAAM,EAAE,qxDAAqxD;IAC7xD,KAAK,EAAE,s7CAAs7C;IAC77C,IAAI,EAAE,8iBAA8iB;IAGpjB,IAAI,EAAE,iDAAiD;IACvD,MAAM,EAAE,8RAA8R;IAGtS,MAAM,EAAE,0VAA0V;IAGlW,IAAI,EAAE,ksCAAksC;IAIxsC,GAAG,EAAE,yHAAyH;CACxH,CAAC;AAUX,MAAM,cAAc,GAA+B,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC;AAC5E,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,KAAoB,EAAyB,EAAE,CAAC,CAAC,cAAc,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentic/constants",
-  "version": "1.239.0",
+  "version": "1.242.0",
   "description": "Shared constants for the intentic packages, ports, paths, and image references the daemon, CLIs and desktop app all agree on",
   "license": "MIT",
   "type": "module",
@@ -13,7 +13,13 @@
   "files": [
     "dist",
     "src/node.mjs",
-    "src/node.d.mts"
+    "src/node.d.mts",
+    "src/assertion-measure.mjs",
+    "src/assertion-measure.d.mts",
+    "src/contract-shrink.mjs",
+    "src/contract-shrink.d.mts",
+    "src/control-bytes.mjs",
+    "src/control-bytes.d.mts"
   ],
   "exports": {
     ".": {
@@ -30,6 +36,18 @@
     "./node": {
       "types": "./src/node.d.mts",
       "default": "./src/node.mjs"
+    },
+    "./assertion-measure": {
+      "types": "./src/assertion-measure.d.mts",
+      "default": "./src/assertion-measure.mjs"
+    },
+    "./contract-shrink": {
+      "types": "./src/contract-shrink.d.mts",
+      "default": "./src/contract-shrink.mjs"
+    },
+    "./control-bytes": {
+      "types": "./src/control-bytes.d.mts",
+      "default": "./src/control-bytes.mjs"
     }
   },
   "devDependencies": {

package/src/assertion-measure.d.mts

@@ -0,0 +1,14 @@
+// Types for assertion-measure.mjs, so the daemon's agreement test (agent-tests.test.ts) can import it by path.
+export interface AssertionMeasure {
+    readonly exact: number;
+    readonly loose: number;
+    readonly chars: number;
+    readonly tests: number;
+}
+export type Weakening = "downgrade" | "narrowing";
+export const NARROWING: number;
+export const EXACT: readonly string[];
+export const LOOSE: readonly string[];
+export function measure(source: string): AssertionMeasure;
+export function weakened(before: AssertionMeasure | undefined, after: AssertionMeasure): Weakening | undefined;
+export function describeWeakening(path: string, shape: Weakening, before: AssertionMeasure, after: AssertionMeasure): string;

package/src/assertion-measure.mjs

@@ -0,0 +1,244 @@
+/* HOW STRONG A TEST FILE'S ASSERTIONS ARE, as three numbers, and whether a second version of the file is weaker.
+ *
+ * The pure half of the assertion ratchet, shared by the push gate (_tools/scripts/assertion-ratchet.mjs, which
+ * runs it over a commit range or the working tree, importing this file by relative path because a pre-push hook
+ * runs on a clone that may never have installed) and by the daemon's turn-ending check
+ * (_sandbox/sandbox/src/agent/agent-tests.ts, importing it as @intentic/constants/assertion-measure), which asks
+ * the same question of the test files a turn touched and tells the model while it can still act. One copy, so
+ * the two readers cannot disagree.
+ *
+ * WHY. On 2026-08-31 eight commits in fifty minutes "relaxed" about 180 test files. `toEqual({ …, message:
+ * "Reached Example, authenticated as ada." })` became `toMatchObject({ … })` plus `toContain("ada")`; `"9 of 12
+ * files still in your workspace"` became `toContain("9")` and `toContain("12")`; `"Start your first agent"`
+ * became `"first agent"`. Every suite stayed green, every gate said yes, and each of those tests can now barely
+ * fail. AGENTS.md forbids exactly this ("an assertion that cannot fail is worse than no test") and no linter can
+ * enforce it: the shape of a weak `toContain` is the shape of a strong one. What CAN be seen is the direction
+ * of travel between two versions of the same file, which is what this measures.
+ *
+ * THREE NUMBERS PER FILE: EXACT matchers (toBe, toEqual, toStrictEqual, toHaveLength, toHaveBeenCalledWith,
+ * snapshots…), LOOSE matchers (toContain, toMatch, toMatchObject, toBeTruthy, toBeGreaterThan, expect.any…), and
+ * the characters of literal text the assertions pin down (every string, regex and template run inside a
+ * matcher's argument list, comments excluded). A file is weaker in either of two shapes:
+ *
+ *   · a DOWNGRADE: fewer exact matchers and more loose ones AND no more asserted text than before, the
+ *     `toEqual` → `toMatchObject` move. That third clause is what tells the move from its opposite. The move
+ *     always SHEDS pinned text — it replaces a whole expected object with a fragment of one — so a file that
+ *     ends up pinning more text than it did is doing something else, whatever its matcher mix did. Without the
+ *     clause the rule read absolute counts with no sense of scale, and a suite that grew by five tests and 247
+ *     characters of expectation was refused for turning one `toEqual({})` — an exact matcher asserting that a
+ *     result is EMPTY — into `toMatchObject({ permissionDecision: "deny" })`, which pins a value the old
+ *     assertion could not see. One matcher moved from the exact column to the loose one and the file got
+ *     stronger. Over the 400 commits before this clause was written it changes exactly one verdict, and that
+ *     one was wrong.
+ *   · a NARROWING: the asserted text shrinks by more than a quarter while the file keeps as many tests as it had,
+ *     the "first agent" move. Tests removed with their text are not a narrowing, and the test count says so.
+ *     Deliberately left on absolute ratio with no floor and no exemption for a file whose matcher mix improved:
+ *     both were tried against the same 400 commits and both cost more than they bought. A floor big enough to
+ *     excuse an 85→52 character file exempts 60% of the repository's test files, because the median test file
+ *     pins only 110 characters; and exempting "the exact count went up while the loose count went down" lets a
+ *     commit gut six text assertions and buy the exemption with one added `toBe`, which is a real commit
+ *     (daf77486) this would then have missed. Of the 62 narrowings in that range, 60 sit on commits whose own
+ *     subject says they relaxed assertions. The two that do not are a `toEqual({…})` replaced by
+ *     `toBeUndefined()` and a 33-character trim — both worth a reviewer's eye, which is all a flag asks for.
+ *
+ * A HEURISTIC, AND SAID TO BE ONE. A refactor that replaces twenty `toBe` lines with one `toEqual` of a whole
+ * object reads as fewer exact matchers; a suite that switches from asserting prose to asserting structure reads
+ * as narrowing. Both are legitimate, and both are exactly the changes a reviewer should be told about, which is
+ * why the gate refuses only an UNDECLARED weakening and the turn-ending check reports rather than refuses.
+ *
+ * Deliberately regex over source, not an AST: this runs from a pre-push hook on a clone that may never have
+ * installed, so it can import nothing, and the matchers it counts are names, which a regex reads as well as a
+ * parser does. It cannot see a matcher called through a helper (`expectRow(row).toBe(…)` counts, `check(row)`
+ * does not), which is the direction of error that under-reports rather than nags. */
+
+// Asserted text that shrinks past this fraction of what it was, with no test removed, is a narrowing.
+export const NARROWING = 0.75;
+
+/* The vocabulary. Exact matchers pin a value; loose ones admit a family of them. `toThrow` and `toHaveProperty`
+ * are both depending on their arguments (a message or a value makes them exact) and are counted as neither, so
+ * a file that trades between them moves no number. Asymmetric matchers (`expect.any`, `objectContaining`) loosen
+ * whatever exact matcher they sit inside, so each one counts as loose. */
+export const EXACT = [
+    "toBe",
+    "toEqual",
+    "toStrictEqual",
+    "toHaveLength",
+    "toHaveBeenCalledWith",
+    "toHaveBeenLastCalledWith",
+    "toHaveBeenNthCalledWith",
+    "toHaveBeenCalledTimes",
+    "toHaveBeenCalledOnce",
+    "toHaveReturnedWith",
+    "toHaveLastReturnedWith",
+    "toMatchInlineSnapshot",
+    "toMatchSnapshot",
+    "toMatchFileSnapshot",
+    "toThrowErrorMatchingInlineSnapshot",
+    "toThrowErrorMatchingSnapshot",
+    "toBeNull",
+    "toBeUndefined",
+    "toBeNaN",
+    "toBeCloseTo",
+];
+export const LOOSE = [
+    "toContain",
+    "toContainEqual",
+    "toMatch",
+    "toMatchObject",
+    "toBeTruthy",
+    "toBeFalsy",
+    "toBeDefined",
+    "toBeGreaterThan",
+    "toBeGreaterThanOrEqual",
+    "toBeLessThan",
+    "toBeLessThanOrEqual",
+    "toBeInstanceOf",
+    "toBeTypeOf",
+    "toSatisfy",
+    "toHaveBeenCalled",
+    "toHaveReturned",
+    "toBeOneOf",
+];
+const exact = new Set(EXACT);
+const loose = new Set(LOOSE);
+const ASYMMETRIC = /\bexpect\.(any|anything|stringContaining|stringMatching|objectContaining|arrayContaining|closeTo)\s*\(/g;
+const MATCHER = /\.(to[A-Z][A-Za-z]*)\s*\(/g;
+const TEST_CASE = /^\s*(?:test|it)(?:\.(?:each|skip|only|concurrent|todo|fails|skipIf|runIf))?\s*\(/gm;
+
+/* The literal text a matcher's argument list pins down: from the `(` that opens it to the `)` that closes it,
+ * every string literal's characters, every regex's source, and every static run of a template. Walked by hand
+ * because a matcher's argument is routinely a multi-line object with nested calls, which no single regex can
+ * bound.
+ *
+ * COMMENTS ARE SKIPPED FIRST, and that is not tidiness. Assertions here are routinely commented one by one,
+ * the prose says "the owner's" and "the agent's", and to a walker that reads an apostrophe as an opening quote
+ * that comment is a string running to the next apostrophe — over the `)` that closes the matcher, over the
+ * tests below it, to the end of the file. The number that came back was not an overcount of one file's text so
+ * much as a coin flip on how many apostrophes the prose happened to hold, and editing a comment landed a
+ * "narrowing" on a file whose assertions nobody had touched.
+ *
+ * A TEMPLATE'S STATIC RUNS COUNT, only its `${…}` does not. `${STATE_DIR}/config/safety.md` pins seventeen
+ * characters of path and one interpolation, and reading the whole literal as computed made every assertion in
+ * a repository that composes its paths from constants — which this one requires, see _tools/checks/path-literals.mjs —
+ * look like an assertion about nothing. */
+// Past a template's `${…}`, by brace depth: the expression inside is computed, so none of it is asserted text.
+const pastInterpolation = (source, from) => {
+    let braces = 1;
+    let i = from + 2;
+    for (; i < source.length && braces > 0; i += 1) {
+        braces += source[i] === "{" ? 1 : 0;
+        braces -= source[i] === "}" ? 1 : 0;
+    }
+    return i;
+};
+
+// A template literal, from its opening backtick: the characters of its static runs, and where it ends.
+const templateChars = (source, from) => {
+    let chars = 0;
+    let run = from + 1;
+    let i = run;
+    while (i < source.length && source[i] !== "`") {
+        if (source[i] === "\\") {
+            i += 2;
+        } else if (source[i] === "$" && source[i + 1] === "{") {
+            chars += i - run;
+            i = pastInterpolation(source, i);
+            run = i;
+        } else {
+            i += 1;
+        }
+    }
+    return { chars: chars + Math.min(i, source.length) - run, end: i };
+};
+
+const assertedChars = (source, from) => {
+    let depth = 0;
+    let chars = 0;
+    for (let i = from; i < source.length; i += 1) {
+        const ch = source[i];
+        if (ch === "/" && source[i + 1] === "/") {
+            const end = source.indexOf("\n", i);
+            if (end === -1) {
+                return chars;
+            }
+            i = end;
+        } else if (ch === "/" && source[i + 1] === "*") {
+            const end = source.indexOf("*/", i + 2);
+            if (end === -1) {
+                return chars;
+            }
+            i = end + 1;
+        } else if (ch === "(") {
+            depth += 1;
+        } else if (ch === ")") {
+            depth -= 1;
+            if (depth === 0) {
+                return chars;
+            }
+        } else if (ch === '"' || ch === "'") {
+            const quote = ch;
+            let j = i + 1;
+            for (; j < source.length && source[j] !== quote; j += 1) {
+                if (source[j] === "\\") {
+                    j += 1;
+                }
+            }
+            chars += j - i - 1;
+            i = j;
+        } else if (ch === "`") {
+            const template = templateChars(source, i);
+            chars += template.chars;
+            i = template.end;
+        } else if (ch === "/" && /[(,\s=]/.test(source[i - 1] ?? "(")) {
+            // A regex literal in argument position: its source is asserted text like a string's.
+            let j = i + 1;
+            for (; j < source.length && source[j] !== "/" && source[j] !== "\n"; j += 1) {
+                if (source[j] === "\\") {
+                    j += 1;
+                }
+            }
+            chars += j - i - 1;
+            i = j;
+        }
+    }
+    return chars;
+};
+
+// The three numbers, and the test count that tells a narrowing from a deletion.
+export const measure = (source) => {
+    let exactCount = 0;
+    let looseCount = 0;
+    let chars = 0;
+    for (const match of source.matchAll(MATCHER)) {
+        const name = match[1];
+        if (exact.has(name)) {
+            exactCount += 1;
+        } else if (loose.has(name)) {
+            looseCount += 1;
+        }
+        chars += assertedChars(source, match.index + match[0].length - 1);
+    }
+    looseCount += [...source.matchAll(ASYMMETRIC)].length;
+    const tests = [...source.matchAll(TEST_CASE)].length;
+    return { exact: exactCount, loose: looseCount, chars, tests };
+};
+
+// Weaker, in either of the two shapes the header names. `before` absent (a new file) can only be stronger.
+export const weakened = (before, after) => {
+    if (before === undefined) {
+        return undefined;
+    }
+    // The third clause is the scale the first two have none of: see the header. A file that pins MORE text than
+    // it did is not making the `toEqual` → `toMatchObject` move, whichever way its matcher counts went.
+    if (after.exact < before.exact && after.loose > before.loose && after.chars <= before.chars) {
+        return "downgrade";
+    }
+    if (before.chars > 0 && after.chars < before.chars * NARROWING && after.tests >= before.tests) {
+        return "narrowing";
+    }
+    return undefined;
+};
+
+// One line per weakened file, the numbers a reader needs to judge the heuristic for themselves.
+export const describeWeakening = (path, shape, before, after) =>
+    `${path}: ${shape} (exact ${before.exact}→${after.exact}, loose ${before.loose}→${after.loose}, asserted chars ${before.chars}→${after.chars}, tests ${before.tests}→${after.tests})`;

package/src/contract-shrink.d.mts

@@ -0,0 +1,3 @@
+// Types for contract-shrink.mjs, the wire-contract shrink comparison the checkout gate and the daemon share.
+export function shrunkSurfaces(base: unknown, head: unknown, at?: string, out?: string[], named?: boolean): string[];
+export function lockShrinkage(baseText: string, headText: string): string[];

package/src/contract-shrink.mjs

@@ -0,0 +1,76 @@
+/* WHAT A WIRE-CONTRACT LOCK LOST, as one comparison shared by everything that asks it.
+ *
+ * contract.lock.json is the sandbox-contract package's exported schemas as one comparable document
+ * (_sandbox/sandbox-contract/src/contract-lock.ts explains the pair). Three readers ask what a newer lock no
+ * longer offers: the checkout gate that refuses an undeclared shrink at the push (_tools/checks/contract-shrink.mjs),
+ * the landing drafter that forces the `!` and the Breaking-Note into the commit message
+ * (_sandbox/sandbox/src/git/contract-shrink.ts), and the tests that hold both to the same judgment. One
+ * implementation here, hand-written JavaScript rather than compiled TypeScript for the same reason node.mjs
+ * beside it is: the gate runs before `pnpm install`, so it imports this file by relative path and nothing else.
+ *
+ * ADDITIONS NEVER APPEAR IN THE RESULT. Every reader of the wire parses loosely, so growth breaks nobody, and a
+ * detector that flagged growth would put a false `!` on ordinary work.
+ *
+ * ARRAYS ARE THE SCHEMA'S COLLECTIONS (`oneOf` alternatives, `enum` values, `required` names) and the lock
+ * writer keeps them in declaration order rather than sorting, so a position means nothing on its own: every
+ * base element must be matched by SOME head element, and extras pass in silence exactly like a new property
+ * does. An element that merely changed reads as removed: the same verdict either way.
+ *
+ * `description` AS A KEYWORD IS PROSE, AND PROSE IS NOT A PROMISE. zod's `.describe()` rides into the lock
+ * beside the shape, so re-wording a help sentence used to read as "a surface changed" and demand a `!` commit.
+ * Nothing on the wire moves when it does. It is skipped ONLY as a keyword: 78 schemas in this lock carry a
+ * real field NAMED `description`, and losing one of those is a genuine break, so the walk tracks whether the
+ * object it is reading is a name map (keys are fields) or a schema (keys are keywords). */
+
+// The JSON Schema keywords whose value is a map of NAME to schema: inside one a key is a field the wire
+// carries, everywhere else a key is a keyword. The lock's own root is one too (its keys are the exported
+// schema names), which is why the walk starts `named`.
+const NAME_MAPS = new Set(["properties", "patternProperties", "$defs", "definitions"]);
+
+const dotted = (at, key) => (at === "" ? key : `${at}.${key}`);
+
+// Every surface `base` offers that `head` no longer does, as dotted paths.
+export const shrunkSurfaces = (base, head, at = "", out = [], named = true) => {
+    if (Array.isArray(base) || Array.isArray(head)) {
+        if (!Array.isArray(base) || !Array.isArray(head)) {
+            out.push(at);
+            return out;
+        }
+        for (const [index, item] of base.entries()) {
+            const itemAt = typeof item === "object" && item !== null ? `${at}[${index}]` : `${at} ${JSON.stringify(item)}`;
+            const offered = head.some((candidate) => shrunkSurfaces(item, candidate, itemAt, [], false).length === 0);
+            if (!offered) {
+                out.push(itemAt);
+            }
+        }
+        return out;
+    }
+    if (typeof base !== "object" || base === null || typeof head !== "object" || head === null) {
+        if (JSON.stringify(base) !== JSON.stringify(head)) {
+            out.push(at);
+        }
+        return out;
+    }
+    for (const key of Object.keys(base)) {
+        if (!named && key === "description") {
+            continue;
+        }
+        if (key in head) {
+            shrunkSurfaces(base[key], head[key], dotted(at, key), out, !named && NAME_MAPS.has(key));
+        } else {
+            out.push(dotted(at, key));
+        }
+    }
+    return out;
+};
+
+// The same comparison over the two texts of a lock file. Either side failing to parse yields NO shrink rather
+// than a throw: one reader feeds a commit-message draft, and a mangled lock is the contract-lock test's failure
+// to report, not a reason to draft nothing.
+export const lockShrinkage = (baseText, headText) => {
+    try {
+        return shrunkSurfaces(JSON.parse(baseText), JSON.parse(headText));
+    } catch {
+        return [];
+    }
+};

package/src/control-bytes.d.mts

@@ -0,0 +1,7 @@
+// Types for control-bytes.mjs, the byte-level text invariant every control-character reader shares.
+export const BINARY_EXTENSIONS: ReadonlySet<string>;
+export function isBinaryPath(path: string): boolean;
+export function isForbiddenByte(byte: number): boolean;
+export function firstForbiddenByte(bytes: Uint8Array): { readonly offset: number; readonly line: number; readonly column: number; readonly byte: number } | undefined;
+export function byteName(byte: number): string;
+export function escapeFor(byte: number): string;

package/src/control-bytes.mjs

@@ -0,0 +1,65 @@
+/* THE BYTES THAT MAKE A TEXT FILE BINARY, named once for everything that polices them: the checkout gate
+ * (_tools/checks/control-chars.mjs, every tracked file), and the daemon's per-edit reader (the `bytes-edit`
+ * rule's script), which asks the same question of one file the moment it is written.
+ *
+ * A NUL typed straight into a string literal is invisible in an editor and decisive everywhere else: git, grep,
+ * `file`, code review and every diff viewer sniff for one and call the whole file binary. The escape
+ * (backslash-u-0000) is the same code point at runtime and leaves the file text, so every reader here asks for
+ * it and nothing else. Hand-written JavaScript rather than compiled TypeScript so a pre-push hook on a clone
+ * that never installed can import it by relative path. */
+
+// What is allowed to hold arbitrary bytes. Extensions, not paths: an image is an image wherever it lands.
+// Genuinely binary content is skipped by extension rather than by sniffing, because sniffing is exactly the
+// thing that goes wrong here: a source file that LOOKS binary is the bug, not the exemption.
+export const BINARY_EXTENSIONS = new Set([
+    "png",
+    "jpg",
+    "jpeg",
+    "gif",
+    "webp",
+    "avif",
+    "ico",
+    "icns",
+    "pdf",
+    "woff",
+    "woff2",
+    "ttf",
+    "otf",
+    "eot",
+    "zip",
+    "gz",
+    "tgz",
+    "br",
+    "wasm",
+    "mp4",
+    "webm",
+    "mp3",
+    "wav",
+    "bin",
+    "node",
+    "keystore",
+    "jks",
+]);
+
+export const isBinaryPath = (path) => BINARY_EXTENSIONS.has(path.split(".").pop()?.toLowerCase() ?? "");
+
+// C0 controls minus the three every text file legitimately contains (tab, newline, carriage return). DEL rides
+// along: it is as invisible as the rest and has no business in source either.
+export const isForbiddenByte = (byte) => byte <= 0x08 || byte === 0x0b || byte === 0x0c || (byte >= 0x0e && byte <= 0x1f) || byte === 0x7f;
+
+// The first forbidden byte in a buffer as `{ offset, line, column, byte }`, or undefined for a clean file.
+// One report per file is enough to send someone to it. Sliced only for a byte already known to be bad, so
+// the clean file, the overwhelmingly common case, pays for one linear scan and nothing else.
+export const firstForbiddenByte = (bytes) => {
+    for (let at = 0; at < bytes.length; at++) {
+        if (isForbiddenByte(bytes[at])) {
+            const upto = bytes.subarray(0, at).toString("utf8");
+            return { offset: at, line: upto.split("\n").length, column: upto.length - upto.lastIndexOf("\n"), byte: bytes[at] };
+        }
+    }
+    return undefined;
+};
+
+// How a byte is named in a report, and how it should be spelled in the file instead.
+export const byteName = (byte) => (byte === 0x00 ? "NUL" : `0x${byte.toString(16).padStart(2, "0")}`);
+export const escapeFor = (byte) => `\\u${byte.toString(16).padStart(4, "0")}`;

package/src/node.mjs

@@ -14,15 +14,15 @@ import { fileURLToPath } from "node:url";
  * packages, or be symlinked in, and still get the same answer.
  *
  * WHY THIS FILE IS HAND-WRITTEN JAVASCRIPT rather than TypeScript compiled to dist, in a package where
- * everything else is compiled: the earliest callers run BEFORE anything is built. `prepass.mjs` is the script
- * that performs the build, and the byte check and the path guard both run ahead of it in `pnpm check`. A
+ * everything else is compiled: the earliest callers run BEFORE anything is built. `emit-declarations.mjs` is the script
+ * that performs the build, and the byte check and the path guard both run ahead of it in `pnpm checks`. A
  * helper those three had to import from `dist/` would be a helper they could not import on a clean checkout,
  * which is exactly how the second copy of this walk gets written. Plain .mjs with a hand-written .d.mts beside
  * it is importable at every point in the build, so there only has to be one.
  *
  * A caller that runs before `pnpm install` has one more constraint: `@intentic/constants/node` is a BARE
  * specifier and bare specifiers resolve through node_modules, which a bare checkout has none of. Those callers
- * (`prepass.mjs`, run by the pre-push hook and by CI's preflight job) import THIS FILE by relative path
+ * (`_tools/checks/*.mjs`, run by the pre-push hook and by CI's preflight job) import THIS FILE by relative path
  * instead. Still one walk; only the way in differs.
  *
  * NOT EXPORTED FROM THE PACKAGE INDEX, and that is deliberate: the index is imported by browser code