@dzhechkov/harness-core 0.8.47 → 0.8.49

package/sbom.json

@@ -25,7 +25,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "f9d55e53e1eef25486bfcdc94126e015222b8a9f5073f4edf521531d6f908818"
+          "content": "f21bb94bff3cdda978c5309a39f76c280ac699c21fa231490192c6b9dcde1ba6"
         }
       ]
     },
@@ -4795,7 +4795,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "0e3777cdc50daa72fe229e3d50ca8461a41db5ea42969f9561c7487a45a6cd6b"
+          "content": "40975c8defdaf041e61135a2bd85b05ff45c95441cc6a6807d1ae6b1e455b6a5"
         }
       ]
     },
@@ -4805,7 +4805,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "997a853664455c7afec96ed3548067a8f8ab69068e051018a55e8d1823eeb44f"
+          "content": "1fd51135dbd973f5958177d1c1e2f44e8c7c5331af8bab3eb87ed83e0d7326f2"
         }
       ]
     },
@@ -4815,7 +4815,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "10415ffc127a23ba52aa8d295e10859cd9d2fe72a5103186fc73017a406af496"
+          "content": "9d6820cb54a7dc7355901c7c4efe0acbe694fa86c6cd8c2f3d529e35ceba2975"
         }
       ]
     },
@@ -5275,7 +5275,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "a015a9f318640511606c2f3f8debba215c9c2189877ebf1a18f2ff3b0766d2c2"
+          "content": "adab2e7a85dd1e745e2b20bd3574e64025a2d1946dc5124f59ac367f051cd677"
         }
       ]
     },
@@ -5285,7 +5285,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "4b2eaa030c836ebb7884e4c6b90e6f8fe317cfe92b463ddb246f71132cdaaff0"
+          "content": "a4607f5d06ee27c02f0167f202a4a81c11a61e1773ff2ab4914700575f5087cf"
         }
       ]
     },
@@ -5295,7 +5295,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "94bf10ad7df83b07b65c0ba15ccb75f00ec6310a4f321d3654bd0f7b0a719d3b"
+          "content": "f62708bb4eecba718eea02eaa5d78553bf2c8b9ecb93fd0858dff19ca94c1dd0"
         }
       ]
     },
@@ -5305,7 +5305,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "0a87ae82e71a5b7448869459891fdc35f2cefe22948e3939721c989b621dbfaf"
+          "content": "46215c2e0b6f6ce4762a1682f8db867752309640681470ab227776667e475e87"
         }
       ]
     },
@@ -6069,13 +6069,53 @@
         }
       ]
     },
+    {
+      "type": "file",
+      "name": "dist/setup-memory-deps.d.ts",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "20c587d44266b94bc946c25d66c1e53dbd57dfbbba49a56eb7e5080b89bffadb"
+        }
+      ]
+    },
+    {
+      "type": "file",
+      "name": "dist/setup-memory-deps.d.ts.map",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "28de3a30d51b04b29392175bdc69c8c47aa4b8bd314182b631343e14144ebadf"
+        }
+      ]
+    },
+    {
+      "type": "file",
+      "name": "dist/setup-memory-deps.js",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "7fe99dcd111bd4a644f126260fbb693c91b81d779b9e8b194482ccd9964b8ae8"
+        }
+      ]
+    },
+    {
+      "type": "file",
+      "name": "dist/setup-memory-deps.js.map",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "463f7984bde099d63e2b64c4373255160fba321ae8e6524191b547fe2a52b8e0"
+        }
+      ]
+    },
     {
       "type": "file",
       "name": "dist/setup.d.ts",
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "f83a15a0c183e2dc67d95323a3eae1eddfd8b375ca92a0de488081ec9d020603"
+          "content": "5bb08d77d90dfae60cfb117f0495cbe23739f03a209960a5292ed6680f214bee"
         }
       ]
     },
@@ -6085,7 +6125,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "3ecf9110097001cba535095de5a78cd9ca2703cfed15d921f368673b08ef6374"
+          "content": "a1b4f19126ab5175e78ea536fc474e8edd7d827c6598fe2b45bc3878ee973fd6"
         }
       ]
     },
@@ -6095,7 +6135,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "ffab1105dd844f20d5f8a6c385901f9bb6c714148a2f61a4e51afab0254021b2"
+          "content": "5eee98e8f377ae61f60197924941d41ba054c57d5c3b4d80216bd1a1c54f1eb7"
         }
       ]
     },
@@ -6105,7 +6145,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "363fa3f4e716a6e450a49f9f11b9c871baad68b30c825f3cdd4b27f471731572"
+          "content": "8b8c9428d6fcc874c64cc25e1d28046b96cecb3ff3e854eb941702876cf6e4a8"
         }
       ]
     },
@@ -6555,7 +6595,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "3b2fb3634c29372cff6e0bb2851d6ae8500420fbb0deb51cac01df857ec42484"
+          "content": "765d542b7e66403c575b8b1e4fa4096bf82591e71ad4a35ce4ec44f0f82762b3"
         }
       ]
     },
@@ -6565,7 +6605,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "54c32a41991eb072be7fd8d4ab78b94cd6bbb7a79dac745a66f692f0d84dcf30"
+          "content": "cb5895f0585ef30f4582b674c96ea17b3fe4f77979945d4727ad1059e9d11696"
         }
       ]
     },
@@ -6575,7 +6615,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "96f8ae3c7e3268ce44df3f0dd62f7d180079791803a2b5b870b5e61e79cc78cf"
+          "content": "8cbeb2a7f0c8667febce4f608d3aec85f1b6a046514ed261523b71c06f9cef15"
         }
       ]
     },
@@ -6585,7 +6625,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "a94d8f614828cc66724dee9b53d0ec86c3f87cc7dc34083522f2932acec8049e"
+          "content": "2a3512f82b2ed24802645d0048d300655d7990bb33c7d534865ddd490be74d7d"
         }
       ]
     },
@@ -7235,7 +7275,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "6bb2aba8860e19b09a3dc650e2d474a4c719c342de0105c850e3b73e3f0c4cb2"
+          "content": "c71f53acd6db19925e99d580dd9e90a082173a7fd0882cb8fce5202bbb63ce6a"
         }
       ]
     },
@@ -7245,7 +7285,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "563549dc76299043e9626af802e713e5924b922484b17ab48cd3393fef232d08"
+          "content": "a4a21c19d297256e4170c43f499df322ae25d633de0d11b19ef3e382accc2e4d"
         }
       ]
     },
@@ -7255,7 +7295,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "08b6be3e5e9f57a5772a4d8000fef179927a572c8e65a2b8a00a475bcee91bbe"
+          "content": "1d16db0711bfb03c89bf04a1ca87c3f19620554ff56df6bb6c1797814d919b81"
         }
       ]
     },
@@ -7265,7 +7305,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "a29a1d484ca33e47fb3be756634cc19b84fbeae562da55355eb512fad71c0f88"
+          "content": "fafeab618345a308eb1c32643bf6a740e122e281a69c4fa97d1040fcd6ad8396"
         }
       ]
     },
@@ -7595,7 +7635,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "4869672a14319b0bf722423c9a4fd09a9a206ba34632806f0a423da512269fe8"
+          "content": "6b264b0c6100053392988e917714cb626666b13134052286f462080cfde7e992"
         }
       ]
     },
@@ -7605,7 +7645,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "45042aae85a9b5ca697133cc04ed33b8e4640450aba1a118eca10d6254a6880e"
+          "content": "a9b6461415716a7fa2d4fc8e8465bfaf7b6ed2b580902a27f5dc89530d400b4c"
         }
       ]
     },
@@ -7615,7 +7655,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "121b00a331d74bf1d0406d60a45aa3b2a47d57021a51f9f8a787ff11e56212e0"
+          "content": "b39a7168fb7c07f6e8a5b4e8b3d6d5f40276b18eeac3d25019cf195e5bf7dc0d"
         }
       ]
     },
@@ -7625,7 +7665,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "3ae9d9bda38209a80fbdaba994c35e191a5824ef1bc33db0c3d48acc3c4473b1"
+          "content": "e97da7f04971b4771e2060b89fa3659cd4796ea9f92c03fe4eb5d1305398ef8e"
         }
       ]
     },
@@ -7635,7 +7675,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "c659b5c0ac2edbf61f50f4724ca58f1282bdfa8608e355cc336c81d1afcb91b2"
+          "content": "8460d23b0032130ab34bc9cfd7bcdfbe897a7c40b3ca03665bb1de519851c961"
         }
       ]
     },
@@ -7645,7 +7685,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "a03ce8f428c4fa40bc09d6094cb25cb9e5e4d1085ff8e96029c628d49c0cbbcb"
+          "content": "d755ce82e6640ac232ad21006e2165fff690b38fe52f43ce98a0c64ed9b0e00d"
         }
       ]
     },
@@ -7655,7 +7695,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "fa9b09ee9bdac1296526b6155e408bcad964d4a1e1ee5c115d0ba42175ad48f7"
+          "content": "c594a2f15f0ee53ffee51c92dc7fb96ba276d192c7492ef9b5d3a62089524bb9"
         }
       ]
     },
@@ -7665,7 +7705,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "7e2c5909d302552acbd0dd5929ac3aa568f033cea23c6a3c28066ed4b33e17bd"
+          "content": "7f5da97933113d32eaf6ef6735f39b2536dd1f3479f43439b7250789c3143d17"
         }
       ]
     },
@@ -7759,7 +7799,7 @@
         },
         {
           "name": "dz:canonical-json-sha256-v2",
-          "value": "2f2efddbf98d512bf925a3639a76f8e3ff75a9beb0dc56bdb1a8a27fc3031480"
+          "value": "c4f5afb2d6c68fe4fd7ba0cfec67e61ed72f39967fcccee82c16a9c1aac4f88a"
         }
       ]
     },
@@ -8979,7 +9019,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "65662c369cc20c75ff6645bcf834c0336e3c3f6caa875d38d8bf44c0facc06ba"
+          "content": "4903437dd0411b2379dff11823124a07001100334b986908c91f19b6671e5308"
         }
       ]
     },
@@ -9109,7 +9149,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "07ee047f3fd9904fd13ddea2e95e0a0ff9a6544a754fbd19f3da6cbfff6ea087"
+          "content": "b4fa02f244f59bfc02f69d3b9894e48b080bca5e30ae8dda6d695a09fb45705b"
         }
       ]
     },
@@ -9313,13 +9353,23 @@
         }
       ]
     },
+    {
+      "type": "file",
+      "name": "src/setup-memory-deps.ts",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "ba01380f84272b0f3384f3902908b839d55ae2e787f9b4da7381a20a8ad1e4d7"
+        }
+      ]
+    },
     {
       "type": "file",
       "name": "src/setup.ts",
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "9041565e0c4f79a66edd8fed57e5e75029d1bd0c9b276fc86cbd2718b2fec6d8"
+          "content": "bc10eae3bac47dcd387a9f2618df27e2e93a0eacf3809141a02484ebe1719121"
         }
       ]
     },
@@ -9449,7 +9499,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "b68d687765592406520b3d565e6a917295141fc4cd4186154e7103a6d357dc3c"
+          "content": "c6ed5f1b7f0ea3b5088c4f54a93360ca1455254cf76661535e0bef7b8f8cb2fc"
         }
       ]
     },
@@ -9619,7 +9669,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "564306fcbbf6a53216000637f239e98688f6a6cd4150ad5390cd44dda92a5d9e"
+          "content": "31b8bc15d0783461fb9d6d0ec9bb6f971f30dc830690410fa1cf0ee09c236222"
         }
       ]
     },
@@ -9709,7 +9759,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "fb1686da93c94dfa64075b62223dffe05e57231f73a82f2c646c7c5fccfbd770"
+          "content": "ac72cb4f5fa62cb9d135b1218896e5bec418415fbaffad4c885790e1db52104a"
         }
       ]
     },
@@ -9719,7 +9769,7 @@
       "hashes": [
         {
           "alg": "SHA-256",
-          "content": "620c0f2436a249129acbea305567f888919fcc4343d4778f50a7d1e137ce74cb"
+          "content": "c1ecd9dbe1fbcccd016a708656378d2701119644d4be2c815a24a6800d60b7be"
         }
       ]
     },

package/src/publish.ts

@@ -161,7 +161,7 @@ export interface PublishReport {
   readonly skipped: number;
   readonly errors: number;
   readonly dryRun: boolean;
-  /** Repo-relative README paths whose first joint core/CLI release line was rewritten. */
+  /** Repo-relative README paths whose first explicitly marked joint core/CLI release line was rewritten. */
   readonly releaseLineSynced: readonly string[];
   readonly releaseLineReport: readonly ReleaseLineReport[];
   /** Post-publication sync failures are warnings: registry-confirmed packages cannot be unpublished. */
@@ -677,8 +677,8 @@ function isInstallPinContext(line: string, tokenStart: number): boolean {
  * bare "X" in a sentence) rewrote by default until someone thought to deny it too. An allowlist has
  * no such gap: an unrecognised shape is history by default, not by enumeration.
  *
- *  1. a release-line token — `` `harness-core vX` · `harness-cli vY` `` and any generalised
- *     `` `<name> vX` `` on the same line, including a trailing `` · `memory vZ` `` segment
+ *  1. an explicitly marked current release-line token — `` `harness-core vX` · `harness-cli vY` `` and any generalised
+ *     `` `<name> vX` `` in its contiguous chain, including a trailing `` · `memory vZ` `` segment
  *     (release-line.ts `isReleaseLineToken`/`GENERIC_RELEASE_TOKEN_RE`).
  *  2. a current-release FOOTER prefix (`FOOTER_STAMP_PREFIX_RE`) — position-aware, so only the
  *     token immediately after the label is allowed.

package/src/release-line.ts

@@ -1,3 +1,5 @@
+import { maskMarkdown } from './markdown-masker.js';
+
 export const RELEASE_LINE_RE = /`harness-core v(\d+\.\d+\.\d+)` · `harness-cli v(\d+\.\d+\.\d+)`/;
 
 export interface ReleaseLineToken {
@@ -22,8 +24,15 @@ export interface ReleaseLineMatch extends ReleaseLineParse {
 
 export function findReleaseLine(text: string): ReleaseLineMatch | null {
   const lines = text.split('\n');
+  // A closed leading opt-in is metadata, not an HTML example block. Blank only
+  // that exact marker before masking, retaining offsets and all enclosing blocks.
+  const maskInput = text.replace(/^ {0,3}<!-- dz:version -->/gm, (marker) => ' '.repeat(marker.length));
+  const visible = String(maskMarkdown(maskInput, { unclosed: 'hide' })).split('\n');
   for (let index = 0; index < lines.length; index++) {
     const line = lines[index]!;
+    // A joint pair is structural history until the author opts this physical line in.
+    // Masked examples cannot supply current metadata to the writer, report, or guard.
+    if (!line.includes('<!-- dz:version -->') || !RELEASE_LINE_RE.test(visible[index]!)) continue;
     const parsed = parseReleaseLine(line);
     if (parsed !== null) {
       return { index, line, core: parsed.tokens[0]!.version, cli: parsed.tokens[1]!.version, ...parsed };
@@ -89,19 +98,8 @@ export function parseReleaseLine(line: string): ReleaseLineParse | null {
   return { tokens, chainEnd, wrapped: /\s*·\s*$/.test(line.slice(chainEnd)) };
 }
 
-/**
- * Is the OLD-VERSION occurrence at `[start, end)` in `line` sitting inside a `` `<name> vX` ``
- * backtick token? A POSITIVE override for `planReadmeVersionSync`'s citation heuristic: a token
- * this shape matches is a release-line stamp, never a historical citation, even where it sits next
- * to punctuation ("/", "on ") the citation heuristic would otherwise read as a citation cue.
- */
+/** A marked current joint chain grants token permission only through its structural boundary. */
 export function isReleaseLineToken(line: string, start: number, end: number): boolean {
-  // Codex r2 HIGH (lead): a `` `<name> vX` `` token is a release-line stamp ONLY on a line that carries
-  // the JOINT release-line shape (`RELEASE_LINE_RE`); an isolated `` `memory v0.8.25` `` in a
-  // historical sentence is history and must not move.
-  // Codex r3 HIGH (lead): the permission is the joint pair PLUS the CONTIGUOUS ` · `<name> vX``
-  // chain that follows it — not the whole line. `` `harness-core vX` · `harness-cli vY` — historically
-  // `memory vZ` `` moves the first two and keeps the third (prose broke the chain).
-  const p = parseReleaseLine(line);
+  const p = findReleaseLine(line);
   return p !== null && p.tokens[0]!.start <= start && end <= p.chainEnd;
 }

package/src/setup-memory-deps.ts

@@ -0,0 +1,166 @@
+/** Exact consumer npm persistence and local native readiness. No ancestor/global installs. */
+import { existsSync, readFileSync, writeFileSync, rmSync, realpathSync } from 'node:fs';
+import { join } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { isDeepStrictEqual } from 'node:util';
+
+export const MEMORY_DEFAULTS = { agentdb: '3.0.0-alpha.20', 'better-sqlite3': '11.10.0' } as const;
+const names = Object.keys(MEMORY_DEFAULTS) as (keyof typeof MEMORY_DEFAULTS)[];
+const sections = ['dependencies', 'devDependencies', 'optionalDependencies'] as const;
+type Json = Record<string, any>;
+export interface MemoryDependencyResult {
+  readonly ready: boolean;
+  readonly changedManifest: boolean;
+  readonly changedLock: boolean;
+  readonly detail: string;
+}
+const object = (value: unknown): value is Json => value !== null && typeof value === 'object' && !Array.isArray(value);
+const same = (a: unknown, b: unknown) => isDeepStrictEqual(a, b);
+const bytes = (path: string) => existsSync(path) ? readFileSync(path, 'utf8') : null;
+function json(path: string): Json {
+  const value: unknown = JSON.parse(readFileSync(path, 'utf8'));
+  if (!object(value)) throw Error(`${path}: expected a JSON object`);
+  return value;
+}
+export function supportedMemoryVersion(name: keyof typeof MEMORY_DEFAULTS, value: unknown): value is string {
+  const number = '(?:0|[1-9][0-9]*)';
+  return typeof value === 'string' && new RegExp(name === 'agentdb'
+    ? `^(?:3\\.${number}\\.${number}|3\\.0\\.0-alpha\\.${number})$`
+    : `^11\\.${number}\\.${number}$`).test(value);
+}
+function installed(root: string, name: string): string | null {
+  const path = join(root, 'node_modules', name, 'package.json');
+  if (!existsSync(path)) return null;
+  const pkg = json(path);
+  if (pkg['name'] !== name || typeof pkg['version'] !== 'string') throw Error(`${name}: malformed installed package metadata`);
+  return pkg['version'];
+}
+function lockVersion(lock: Json | null, name: string): string | null {
+  const item = lock?.['packages']?.[`node_modules/${name}`] ?? lock?.['dependencies']?.[name];
+  return item?.version ?? null;
+}
+function selectVersions(root: string, pkg: Json, lock: Json | null): Record<string, string> {
+  for (const section of [...sections, 'peerDependencies']) {
+    if (pkg[section] !== undefined && !object(pkg[section])) throw Error(`package.json: malformed ${section}`);
+  }
+  const versions: Record<string, string> = {};
+  for (const name of names) {
+    if (Object.hasOwn(pkg['peerDependencies'] ?? {}, name)) throw Error(`${name}: peer declaration is outside exact persistence repair`);
+    const declared = sections.flatMap(section => Object.hasOwn(pkg[section] ?? {}, name) ? [pkg[section][name]] : []);
+    if (declared.some(value => !supportedMemoryVersion(name, value)) || new Set(declared).size > 1) throw Error(`${name}: conflicting or non-exact/unsupported saved declaration; original files preserved`);
+    if (declared.length) { versions[name] = declared[0]; continue; }
+    const local = installed(root, name), locked = lockVersion(lock, name);
+    if (local !== null) {
+      if (!supportedMemoryVersion(name, local)) throw Error(`${name}: unsupported installed-only version ${local}`);
+      if (locked !== null && locked !== local) throw Error(`${name}: installed-only and orphan lock versions conflict`);
+      versions[name] = local;
+    } else if (locked !== null) throw Error(`${name}: incomplete legacy lock-only state; original files preserved`);
+    else versions[name] = MEMORY_DEFAULTS[name];
+  }
+  return versions;
+}
+function persisted(pkg: Json, lock: Json | null, versions: Record<string, string>): boolean {
+  return names.every(name => pkg['devDependencies']?.[name] === versions[name]
+    && !Object.hasOwn(pkg['dependencies'] ?? {}, name) && !Object.hasOwn(pkg['optionalDependencies'] ?? {}, name)
+    && lockVersion(lock, name) === versions[name] && lock?.['packages']?.['']?.['devDependencies']?.[name] === versions[name]
+    && !Object.hasOwn(lock?.['packages']?.['']?.['dependencies'] ?? {}, name)
+    && !Object.hasOwn(lock?.['packages']?.['']?.['optionalDependencies'] ?? {}, name));
+}
+function protectedManifest(pkg: Json): Json {
+  const copy: Json = JSON.parse(JSON.stringify(pkg));
+  for (const section of sections) {
+    if (!object(copy[section])) continue;
+    for (const name of names) delete copy[section][name];
+    if (!Object.keys(copy[section]).length) delete copy[section];
+  }
+  return copy;
+}
+function resolutions(lock: Json | null): Record<string, string> {
+  const result: Record<string, string> = {};
+  if (object(lock?.['packages'])) for (const [path, item] of Object.entries(lock['packages'])) {
+    if (path && !names.some(name => path === `node_modules/${name}`) && object(item) && typeof item['version'] === 'string') result[path] = item['version'];
+  }
+  else if (object(lock?.['dependencies'])) for (const [name, item] of Object.entries(lock['dependencies'])) {
+    if (!names.includes(name as keyof typeof MEMORY_DEFAULTS) && object(item) && typeof item['version'] === 'string') result[`node_modules/${name}`] = item['version'];
+  }
+  return result;
+}
+function npm(root: string, args: string[]): void {
+  execFileSync(process.platform === 'win32' ? 'npm.cmd' : 'npm', args, {
+    cwd: root, timeout: 300000, maxBuffer: 8 * 1024 * 1024, stdio: 'pipe', shell: process.platform === 'win32',
+  });
+}
+export function probeMemoryNative(root: string): string | null {
+  try {
+    for (const name of names) if (installed(root, name) === null) return `${name}: local package missing`;
+    const script = `const {createRequire}=require('node:module'),fs=require('node:fs'),path=require('node:path');
+const root=process.argv[1],r=createRequire(path.join(root,'package.json')),local=fs.realpathSync(path.join(root,'node_modules'));
+const resolved=fs.realpathSync(r.resolve('better-sqlite3')); if(path.relative(local,resolved).startsWith('..'))throw Error('native module resolved outside project');
+const Sqlite=r('better-sqlite3'),db=new Sqlite(':memory:');try{if(db.prepare('SELECT 42 AS answer').get().answer!==42)throw Error('native SELECT failed');}finally{db.close();}
+process.stdout.write('native-sql-ready');`;
+    const output = execFileSync(process.execPath, ['-e', script, realpathSync(root)], { cwd: root, timeout: 60000, maxBuffer: 4 * 1024 * 1024, stdio: 'pipe', encoding: 'utf8' });
+    return output === 'native-sql-ready' ? null : 'native SQL readiness stdout not established';
+  } catch (error) { return `native SQLite unavailable: ${error instanceof Error ? error.message : String(error)}`; }
+}
+export function reconcileMemoryDependencies(projectRoot: string, repair = true): MemoryDependencyResult {
+  const pkgPath = join(projectRoot, 'package.json'), lockPath = join(projectRoot, 'package-lock.json');
+  const beforePkg = bytes(pkgPath), beforeLock = bytes(lockPath);
+  let stage = 'validate', repaired = false;
+  const result = (ready: boolean, detail: string): MemoryDependencyResult => ({ ready, changedManifest: bytes(pkgPath) !== beforePkg, changedLock: bytes(lockPath) !== beforeLock, detail });
+  try {
+    const pkg = beforePkg === null ? { name: 'dz-harness-project', private: true, version: '0.0.0' } : json(pkgPath);
+    const lock = beforeLock === null ? null : json(lockPath);
+    const versions = selectVersions(projectRoot, pkg, lock);
+    const localCurrent = names.every(name => installed(projectRoot, name) === versions[name]);
+    const savedCurrent = persisted(pkg, lock, versions);
+    if (!repair && (!savedCurrent || !localCurrent)) return result(false, 'saved/local dependency state is inconsistent; run setup to repair exact devDependencies');
+    const nativeBefore = localCurrent ? probeMemoryNative(projectRoot) : 'local package versions need repair';
+    if (!repair && nativeBefore) return result(false, nativeBefore);
+    if (!savedCurrent || !localCurrent) {
+      stage = 'npm persistence repair';
+      const protectedFields = protectedManifest(pkg), protectedLock = resolutions(lock);
+      try {
+        // npm can retain an existing optional declaration despite --save-dev. Selection and
+        // conflicts were validated above; normalize ONLY the two memory declarations first.
+        const canonical: Json = JSON.parse(JSON.stringify(pkg));
+        for (const section of sections) {
+          if (!object(canonical[section])) continue;
+          let removed = false;
+          for (const name of names) if (Object.hasOwn(canonical[section], name)) { delete canonical[section][name]; removed = true; }
+          if (removed && !Object.keys(canonical[section]).length) delete canonical[section];
+        }
+        canonical['devDependencies'] = { ...(canonical['devDependencies'] ?? {}), ...versions };
+        if (beforePkg === null || !same(canonical, pkg)) writeFileSync(pkgPath, JSON.stringify(canonical, null, 2) + '\n');
+        npm(projectRoot, ['install', ...names.map(name => `${name}@${versions[name]}`), '--save-dev', '--save-exact', '--no-audit', '--no-fund', '--loglevel=error']);
+        const after = json(pkgPath), afterLock = json(lockPath), afterResolutions = resolutions(afterLock);
+        if (!same(protectedManifest(after), protectedFields) || Object.entries(protectedLock).some(([path, version]) => afterResolutions[path] !== version)) {
+          throw Error('npm changed protected unrelated manifest fields/lock resolutions');
+        }
+        if (!persisted(after, afterLock, versions) || !names.every(name => installed(projectRoot, name) === versions[name])) throw Error('npm did not establish requested exact manifest/lock/local versions');
+        repaired = true;
+      } catch (error) {
+        // npm is not a whole-project transaction. Restore only protected manifest/lock files.
+        let changedProtected = false;
+        try {
+          const after = existsSync(pkgPath) ? json(pkgPath) : {};
+          const afterResolutions = resolutions(existsSync(lockPath) ? json(lockPath) : null);
+          changedProtected = !same(protectedManifest(after), protectedFields) || Object.entries(protectedLock).some(([path, version]) => afterResolutions[path] !== version);
+        } catch { changedProtected = true; }
+        if (changedProtected) {
+          if (beforePkg === null) rmSync(pkgPath, { force: true }); else writeFileSync(pkgPath, beforePkg);
+          if (beforeLock === null) rmSync(lockPath, { force: true }); else writeFileSync(lockPath, beforeLock);
+          throw Error(`protected manifest/lock restored after npm changed unrelated state; local modules may be incomplete: ${String(error)}`);
+        }
+        throw error;
+      }
+    } else if (repair && nativeBefore) {
+      stage = 'native rebuild'; npm(projectRoot, ['rebuild', 'better-sqlite3', '--no-audit', '--no-fund', '--loglevel=error']); repaired = true;
+    }
+    stage = 'native SQL probe';
+    const nativeError = probeMemoryNative(projectRoot);
+    if (nativeError) return result(false, `INCOMPLETE ${stage}: ${nativeError}; package.json ${bytes(pkgPath) === beforePkg ? 'unchanged' : 'changed'}, package-lock.json ${bytes(lockPath) === beforeLock ? 'unchanged' : 'changed'}`);
+    return result(true, `${repaired ? 'repaired exact devDependencies/local readiness' : 'already current exact devDependencies and native SQLite'}; package.json ${bytes(pkgPath) === beforePkg ? 'unchanged' : 'changed'}, package-lock.json ${bytes(lockPath) === beforeLock ? 'unchanged' : 'changed'}; ${names.map(name => `${name}@${versions[name]}`).join(', ')}; native SELECT 42 passed`);
+  } catch (error) {
+    return result(false, `INCOMPLETE ${stage}: ${error instanceof Error ? error.message : String(error)}; package.json ${bytes(pkgPath) === beforePkg ? 'unchanged' : 'changed'}, package-lock.json ${bytes(lockPath) === beforeLock ? 'unchanged' : 'changed'}`);
+  }
+}