@dzhechkov/harness-core 0.8.30 → 0.8.31

package/dist/agentdb-snapshot.js

@@ -0,0 +1,195 @@
+/**
+ * Consistent sqlite snapshot + restore for the pre-reindex undo point (feature
+ * `snapshot-wal-consistency`, FR-1..FR-4; fix round AM-1..AM-4).
+ *
+ * A WAL-mode sqlite database's committed data can live in TWO files: the main `dbFile` and its
+ * `-wal` sidecar (frames not yet checkpointed into the main file). The snapshot this module
+ * replaces was a bare `copyFileSync(dbFile, backupPath)` — one file, no `-wal` — so a reindex that
+ * ran while any writer held the WAL open (autocheckpoint disabled, or simply a live connection
+ * between commits) copied a "backup" that was MISSING committed rows. MEASURED (scratch repro,
+ * 2026-09-13, `node` + real `better-sqlite3`): a schema + one row checkpointed, then a second row
+ * inserted on a connection kept open (`wal_autocheckpoint = 0`) — `copyFileSync` alone yields a
+ * backup with 1 row; `VACUUM INTO` on a fresh read-only connection to the SAME live db yields 2.
+ * The live db's main file hash and `-wal` size are unchanged before/after the `VACUUM INTO` (the
+ * read-only connection never checkpoints or writes) — the safety property NFR-2 names.
+ *
+ * {@link snapshotSqliteDatabase} (FR-1/FR-2) takes the snapshot through `VACUUM INTO` on a fresh
+ * READ-ONLY connection — one self-contained output file with every committed transaction, WAL
+ * frames included. If `VACUUM INTO` cannot run (older sqlite, a locked/foreign file, no free disk)
+ * — or a caller forces it for a test — it falls back to copying `dbFile` plus its `-wal` sibling
+ * (present and non-empty) to `backupPath`/`backupPath-wal`; still strictly better than the old
+ * single-file copy, and the fallback is never silent: `method`/`note` name it honestly so a report
+ * downstream (`reindexAgentdbRows`'s `snapshotMethod`) never claims a guarantee it did not get.
+ *
+ * **AM-1 (fix round).** Codex review, Grade C: reusing a `backupPath` left a stale `-wal`/`-shm`
+ * sidecar from an EARLIER, unrelated snapshot family sitting next to the new one; `restoreSqliteSnapshot`
+ * used to decide whether to restore `-wal` by checking whether `backupPath-wal` merely EXISTS, so that
+ * stale sidecar could ride along onto a `vacuum-into` restore that never produced a matching `-wal` of
+ * its own. Fixed two ways: `snapshotSqliteDatabase` now clears any `backupPath-wal`/`-shm` sidecar
+ * BEFORE either strategy writes anything, and again right after a successful `VACUUM INTO` (whose
+ * output is one self-contained file and must never be shadowed); `restoreSqliteSnapshot` now takes the
+ * `method` the caller already knows and restores `-wal` ONLY when `method === 'copy+wal'` — never by
+ * re-deriving it from file presence.
+ *
+ * **AM-2 (fix round).** The old WAL-size probe was `existsSync` + best-effort `statSync` inside a
+ * `catch { walSize = 0 }` — ANY stat failure (`EACCES`, `EIO`, a raced deletion) was silently read as
+ * "no WAL", so a snapshot could report the honest-sounding `method: 'copy'` while actually having
+ * skipped a WAL it could not even check. {@link statSizeIfExists} now calls `statSync` directly and
+ * treats only a confirmed `ENOENT` as "does not exist" — every other error propagates and aborts the
+ * whole snapshot, so `reindexAgentdbRows` reports "snapshot failed", never a falsely-successful `copy`.
+ *
+ * **AM-4 (fix round).** `snapshotSqliteDatabase` used to happily write into (overwrite) an existing
+ * `backupPath`, silently discarding whatever it held — including, combined with AM-1's stale-sidecar
+ * bug, a backup that looked complete but carried a wrong-generation `-wal`. It now refuses up front
+ * (before `VACUUM INTO` or any copy) when `backupPath` already exists and is non-empty.
+ *
+ * {@link restoreSqliteSnapshot} (FR-4) is the paired rollback. MEASURED (same repro): copying the
+ * old main file back over `dbFile` WITHOUT removing a `-wal` left over from the aborted operation
+ * — reopening the "restored" db returned ZERO rows, not the restored one, because sqlite replayed
+ * the stale WAL frames (a since-superseded DELETE) on top of the reverted main file. Removing
+ * `dbFile-wal`/`dbFile-shm` as part of the restore fixed this: the reopened db then returned
+ * exactly the restored row. The caller MUST close its own write connection to `dbFile` before
+ * calling this — restoring a file sqlite still holds open is undefined behaviour.
+ *
+ * **AM-3 (fix round).** `restoreSqliteSnapshot` used to return `void` — a failing `copyFileSync`/
+ * `rmSync` inside it threw straight out of the best-effort `rollback()` wrapper in
+ * `agentdb-index.ts`, which swallowed it in an empty `catch` and reported nothing: "absence of a
+ * receipt is not success" applies to a rollback exactly as much as to a forward operation. It now
+ * returns `{ ok: true } | { ok: false, error }` so the caller can name a failed rollback as failed,
+ * never as restored.
+ *
+ * @packageDocumentation
+ */
+import { copyFileSync, existsSync, rmSync, statSync } from 'node:fs';
+/** Escape `path` as a single-quoted sqlite string literal (double any embedded `'`). */
+function sqlQuote(path) {
+    return `'${path.replace(/'/g, "''")}'`;
+}
+/**
+ * AM-2: the size of `path`, or `undefined` when it does not exist — but ONLY on a confirmed
+ * `ENOENT`. Any other stat error (`EACCES`, `EIO`, a raced deletion mid-call, …) propagates to the
+ * caller instead of being folded into "does not exist": a snapshot that cannot even determine
+ * whether a `-wal` sidecar exists must abort, not silently report the weaker `copy` method as if it
+ * had made an informed choice.
+ */
+function statSizeIfExists(path) {
+    try {
+        return statSync(path).size;
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT')
+            return undefined;
+        throw err;
+    }
+}
+/**
+ * AM-4: refuse to snapshot into an existing, non-empty `backupPath` — silently overwriting it would
+ * discard whatever it held (possibly itself a valid undo point) with no trace. An existing but EMPTY
+ * file is not a real prior snapshot and is allowed through untouched.
+ */
+function assertBackupTargetFree(backupPath) {
+    const size = statSizeIfExists(backupPath);
+    if (size !== undefined && size > 0) {
+        throw new Error(`snapshot target exists and is non-empty: ${backupPath}`);
+    }
+}
+/**
+ * AM-1: remove any `-wal`/`-shm` sidecar already sitting at `backupPath` — a leftover from an
+ * earlier, unrelated snapshot family that happened to reuse this name. Called BEFORE either strategy
+ * below writes anything, and again immediately after a successful `VACUUM INTO` (whose output is one
+ * self-contained file that must never be shadowed by a stale sidecar from a previous attempt at the
+ * same path).
+ */
+function clearBackupSidecars(backupPath) {
+    rmSync(`${backupPath}-wal`, { force: true });
+    rmSync(`${backupPath}-shm`, { force: true });
+}
+function copyWithWal(dbFile, backupPath, note) {
+    // AM-2: statSync directly; only a confirmed ENOENT means "no -wal to copy" — any other stat error
+    // propagates out of this function (and out of snapshotSqliteDatabase) as a thrown exception.
+    // Lead edit after re-review: the stat runs BEFORE the main file is copied, so a stat failure leaves
+    // no half-written target behind (which AM-4 would otherwise refuse on the retry).
+    const walSize = statSizeIfExists(`${dbFile}-wal`) ?? 0;
+    copyFileSync(dbFile, backupPath);
+    if (walSize > 0) {
+        copyFileSync(`${dbFile}-wal`, `${backupPath}-wal`);
+        return { method: 'copy+wal', note };
+    }
+    return { method: 'copy', note };
+}
+/**
+ * Take a consistent snapshot of `dbFile` into `backupPath` (FR-1/FR-2). Default: open `dbFile`
+ * READ-ONLY and run `VACUUM INTO <backupPath>` — one output file holding every committed
+ * transaction (including `-wal` frames), with no write to the live database (NFR-2 — MEASURED:
+ * main-file hash and `-wal` size are unchanged across the call). On any failure — an older sqlite
+ * without `VACUUM INTO`, a locked file, no disk space — or when `opts.strategy` forces it (tests),
+ * falls back to `copyFileSync(dbFile, backupPath)` plus a copy of `dbFile-wal` to `backupPath-wal`
+ * when the WAL sibling exists and is non-empty; `method` is `'copy+wal'` when the sibling was
+ * copied, `'copy'` when there was none to copy. `note` names the fallback reason (FR-2) — set even
+ * for a forced-strategy test call, so a caller never has to guess why the fast path was skipped.
+ * The read-only connection opened for `VACUUM INTO` is always closed before returning.
+ *
+ * Throws (no snapshot taken, or an incomplete one left in a fully-cleared state) when: `backupPath`
+ * already names an existing, non-empty file (AM-4); or a `-wal` stat probe hits a non-ENOENT error
+ * (AM-2, inside the fallback path). Never silently overwrites, never mis-reports a lesser guarantee
+ * as a stronger one.
+ */
+export function snapshotSqliteDatabase(Database, dbFile, backupPath, opts = {}) {
+    assertBackupTargetFree(backupPath); // AM-4 — before any write, on either strategy
+    clearBackupSidecars(backupPath); // AM-1 — clean slate before either strategy writes anything
+    if (opts.strategy === 'copy+wal') {
+        return copyWithWal(dbFile, backupPath, 'snapshotStrategy=copy+wal forced by caller');
+    }
+    try {
+        const db = new Database(dbFile, { readonly: true });
+        try {
+            db.exec(`VACUUM INTO ${sqlQuote(backupPath)}`);
+        }
+        finally {
+            db.close();
+        }
+        clearBackupSidecars(backupPath); // AM-1 — VACUUM INTO's output never has a matching -wal of its own
+        return { method: 'vacuum-into' };
+    }
+    catch (err) {
+        return copyWithWal(dbFile, backupPath, `VACUUM INTO failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/**
+ * Restore `dbFile` from a snapshot taken by {@link snapshotSqliteDatabase} (FR-4). The caller MUST
+ * close its write connection to `dbFile` BEFORE calling this — this restore is a plain file copy,
+ * not a sqlite-mediated rollback, and a live handle can reintroduce exactly the frames being undone.
+ *
+ * `method` is the EXACT {@link SnapshotMethod} the paired `snapshotSqliteDatabase` call returned
+ * (AM-1) — never re-derived from whether `backupPath-wal` happens to exist on disk, which a stale
+ * sidecar from an unrelated earlier snapshot at the same path could satisfy. Copies `backupPath`
+ * over `dbFile`; when `method === 'copy+wal'`, also restores `backupPath-wal` to `dbFile-wal`.
+ * Otherwise (`'vacuum-into'` or `'copy'`, neither of which produced a matching `-wal` of its own) any
+ * LIVE `dbFile-wal` — left over from the operation being undone — is removed instead: MEASURED,
+ * leaving it in place made a reopened "restored" db replay that WAL's frames (a since-superseded
+ * write) on top of the reverted main file, returning zero rows instead of the restored set.
+ * `dbFile-shm` is always removed — its offsets are valid only for the `-wal` that no longer matches.
+ *
+ * Returns `{ ok: true }`, or `{ ok: false, error }` (AM-3) when any step throws — a caller that
+ * reported a failed restore as a successful one would leave the store worse than before rollback was
+ * attempted, with nothing on record to say so.
+ */
+export function restoreSqliteSnapshot(dbFile, backupPath, method) {
+    try {
+        if (!existsSync(backupPath))
+            return { ok: false, error: `snapshot missing at ${backupPath}` };
+        copyFileSync(backupPath, dbFile);
+        if (method === 'copy+wal') {
+            copyFileSync(`${backupPath}-wal`, `${dbFile}-wal`);
+        }
+        else {
+            rmSync(`${dbFile}-wal`, { force: true });
+        }
+        rmSync(`${dbFile}-shm`, { force: true });
+        return { ok: true };
+    }
+    catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+//# sourceMappingURL=agentdb-snapshot.js.map

package/dist/agentdb-snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentdb-snapshot.js","sourceRoot":"","sources":["../src/agentdb-snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AAEH,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAwBrE,wFAAwF;AACxF,SAAS,QAAQ,CAAC,IAAY;IAC5B,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC;AACzC,CAAC;AAED;;;;;;GAMG;AACH,SAAS,gBAAgB,CAAC,IAAY;IACpC,IAAI,CAAC;QACH,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC;IAC7B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAK,GAA6B,EAAE,IAAI,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QACxE,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,SAAS,sBAAsB,CAAC,UAAkB;IAChD,MAAM,IAAI,GAAG,gBAAgB,CAAC,UAAU,CAAC,CAAC;IAC1C,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,GAAG,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,KAAK,CAAC,4CAA4C,UAAU,EAAE,CAAC,CAAC;IAC5E,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,SAAS,mBAAmB,CAAC,UAAkB;IAC7C,MAAM,CAAC,GAAG,UAAU,MAAM,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7C,MAAM,CAAC,GAAG,UAAU,MAAM,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;AAC/C,CAAC;AAED,SAAS,WAAW,CAAC,MAAc,EAAE,UAAkB,EAAE,IAAY;IACnE,kGAAkG;IAClG,6FAA6F;IAC7F,oGAAoG;IACpG,kFAAkF;IAClF,MAAM,OAAO,GAAG,gBAAgB,CAAC,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC;IACvD,YAAY,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACjC,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;QAChB,YAAY,CAAC,GAAG,MAAM,MAAM,EAAE,GAAG,UAAU,MAAM,CAAC,CAAC;QACnD,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;IACtC,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AAClC,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,sBAAsB,CACpC,QAAwB,EACxB,MAAc,EACd,UAAkB,EAClB,OAAkD,EAAE;IAEpD,sBAAsB,CAAC,UAAU,CAAC,CAAC,CAAC,8CAA8C;IAClF,mBAAmB,CAAC,UAAU,CAAC,CAAC,CAAC,4DAA4D;IAC7F,IAAI,IAAI,CAAC,QAAQ,KAAK,UAAU,EAAE,CAAC;QACjC,OAAO,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,4CAA4C,CAAC,CAAC;IACvF,CAAC;IACD,IAAI,CAAC;QACH,MAAM,EAAE,GAAG,IAAI,QAAQ,CAAC,MAAM,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;QACpD,IAAI,CAAC;YACH,EAAE,CAAC,IAAI,CAAC,eAAe,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;QACjD,CAAC;gBAAS,CAAC;YACT,EAAE,CAAC,KAAK,EAAE,CAAC;QACb,CAAC;QACD,mBAAmB,CAAC,UAAU,CAAC,CAAC,CAAC,mEAAmE;QACpG,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC;IACnC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,uBAAuB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACpH,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAc,EAAE,UAAkB,EAAE,MAAsB;IAC9F,IAAI,CAAC;QACH,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,uBAAuB,UAAU,EAAE,EAAE,CAAC;QAC9F,YAAY,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;QACjC,IAAI,MAAM,KAAK,UAAU,EAAE,CAAC;YAC1B,YAAY,CAAC,GAAG,UAAU,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,CAAC;QACrD,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,GAAG,MAAM,MAAM,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAC3C,CAAC;QACD,MAAM,CAAC,GAAG,MAAM,MAAM,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACzC,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;IACtB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;IAChF,CAAC;AACH,CAAC"}

package/dist/apply-leg.d.ts

@@ -0,0 +1,202 @@
+/**
+ * Apply-leg module (feature `setup-installs-apply-leg`, ADR-001 Decisions 1 and 2).
+ *
+ * The self-learning loop has three legs — COLLECT (session hooks → store), RANK (`dz teach` /
+ * `dz recall` / `dz consolidate`), APPLY (a `UserPromptSubmit` hook injects learned lessons back
+ * into the prompt via a resident embedding daemon). `dz setup` shipped the first two legs; the
+ * third lived ONLY as hand-committed files in this hub's own `.claude/helpers/` — a consumer who
+ * ran `dz setup --target claude-code --memory agentdb` got session hooks and a memory store, but no
+ * recall injection at all (00_complexity_assessment.md, MEASURED 2026-09-12: clean scratch installs
+ * on 0.8.10 and 0.8.22, with and without `--memory agentdb`, wrote no `UserPromptSubmit` entry).
+ *
+ * This module is the SOURCE of that third leg: the two helper files as versioned template
+ * generators (the same shape as `AGENTDB_WRITER_VERSION`/`generateAgentdbWriter` in `setup.ts`),
+ * the hook-registry entries `runSetup` merges into `settings.json`, and `applyLegStatus` — the ONE
+ * measurement `dz doctor` and `dz parity` both read, so neither can drift into declaring the leg
+ * present from a static capability table again (ADR-001 Decision 3, the "приборы врут" defect).
+ *
+ * Decision 2 (why `coreDistDir` is baked in, first candidate): a hook file lives in a CONSUMER
+ * project's `.claude/helpers/`, where `require('@dzhechkov/harness-core')` cannot resolve — Node
+ * resolves a bare specifier upward from the file, and the package is not above it in a global
+ * install. The old hard-coded `/usr/lib/node_modules/...` candidate assumed one specific npm
+ * prefix; a project set up from an nvm or `/usr/local` install found nothing. The fix mirrors
+ * `claude-hooks-assets.ts`'s destructive-guard hook: bake the INSTALLING copy's absolute `dist`
+ * directory into the generated body as the FIRST candidate (proven first at C-5), keep the
+ * project-local candidates as fallbacks for a consumer that vendors its own harness-core.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Version stamped into BOTH generated helper files as `// dz-apply-leg-version: N` (line 2, right
+ * after the shebang). Bump on ANY change to {@link recallHookSource} or {@link embedDaemonSource}'s
+ * output — `runSetup` regenerates a deployed helper whose stamp is older, without requiring
+ * `--force` (the same self-healing contract as `AGENTDB_WRITER_VERSION`).
+ *
+ * Bumped 2→3 (fix round 1, review Codex C, MEDIUM finding "hub twins непереносимы"):
+ * `recallHookSource`'s `loadCoreModule` candidate list is now built with a conditional spread so a
+ * `null` `coreDistDir` (the hub's own portable marker, C-6/finding-6) degrades cleanly to the
+ * project-relative fallbacks — the generated BYTES changed for every caller, hub and consumer alike.
+ */
+export declare const APPLY_LEG_VERSION = 3;
+/**
+ * Parse the `dz-apply-leg-version` stamp from a deployed helper file. Unlike
+ * `writerVersionOf` (which floors an absent stamp at `0`), this returns `-1` for "no stamp at
+ * all" per the plan contract (T1) — `0` is reserved for a future explicit `version 0` helper, and
+ * collapsing "never installed" into the same number as "installed at v0" would make
+ * `applyLegStatus` unable to tell the two apart.
+ */
+export declare function applyLegVersionOf(content: string): number;
+/**
+ * Read back the `coreDistDir` baked into a deployed `recall-hook.cjs` by {@link recallHookSource}
+ * (fix round 1, review Codex C, MEDIUM finding "переезд ядра"): `undefined` when the file carries no
+ * recognisable `const CORE_DIST_DIR = …;` line at all (e.g. a pre-feature or hand-edited file),
+ * `null` for the hub's own portable marker, otherwise the baked absolute path. `runSetup` compares
+ * this against the CURRENT `coreDistDir` so a project whose npm/nvm relocated `harness-core` gets
+ * its helper rewritten even when {@link APPLY_LEG_VERSION} did not change — a version-only staleness
+ * check missed exactly this case (MEASURED: a stale baked path degrades the hook to permanent
+ * silence, never a thrown error, so nothing else would ever surface it).
+ */
+export declare function bakedCoreDistDirOf(content: string): string | null | undefined;
+/**
+ * Generate `.claude/helpers/recall-hook.cjs`. `coreDistDir` is baked in as the FIRST resolve
+ * candidate in `loadCoreModule` (Decision 2, AC-6/C-5) — an absolute path, supplied by the
+ * installer (`dz setup`'s CLI caller resolves its own installed `@dzhechkov/harness-core`).
+ *
+ * `coreDistDir === null` is the HUB's OWN portable marker (fix round 1, review Codex C, MEDIUM
+ * finding "hub twins непереносимы"): a checked-in file that bakes an ABSOLUTE checkout path fails
+ * the twins byte-identity test in every clone but the one it was generated from. The hub instead
+ * regenerates its two `.claude/helpers/*` files with `null`, which renders `const CORE_DIST_DIR =
+ * null;` and — since `loadCoreModule`'s candidate list below SKIPS a falsy `CORE_DIST_DIR` — falls
+ * straight through to the project-relative fallback candidates, the SAME `<project>/packages/
+ * @dzhechkov/harness-core/dist/<file>` path the hub's own `coreDistDir` would have baked anyway
+ * (`PROJECT` resolves from `CLAUDE_PROJECT_DIR`/`cwd()` at hook RUNTIME, not at generation time, so
+ * it is correct in any clone). A real consumer install still gets its installer's absolute path
+ * baked in as before — this is additive, not a behavior change for that case.
+ *
+ * Behaviourally identical to the pre-existing hand-committed hub file except for: the version
+ * stamp (new, line 2) and the candidate list in `loadCoreModule` (baked path first when present,
+ * `/usr/lib/...` dropped — FR-3).
+ */
+export declare function recallHookSource(coreDistDir: string | null): string;
+/** `setTimeout`'s delay argument is a 32-bit signed int in Node — see {@link resolveIdleMs}. */
+export declare const IDLE_MS_INT32_MAX = 2147483647;
+/** Result of resolving a raw `DZ_EMBED_IDLE_MS` value into the daemon's actual idle-exit timer. */
+export interface ResolvedIdleMs {
+    /** `null` ⇒ the idle exit is disabled outright (0/NaN/negative). Otherwise the clamped ms value. */
+    readonly value: number | null;
+    /** True ⇒ `value` was clamped down from a raw value above {@link IDLE_MS_INT32_MAX}. */
+    readonly clamped: boolean;
+}
+/**
+ * Pure mirror of the `IDLE_MS` resolution inlined into {@link embedDaemonSource}'s generated body
+ * (AM-10, dz-harness-hub issue #10 defect 7). Extracted (fix round 1, review Codex C, LOW finding)
+ * so the clamp/disable rule is unit-testable directly — the review noted the only prior proof was a
+ * LIVE process observed via its first stderr log line, which shows the log fired but not that the
+ * underlying arithmetic is right for every input class.
+ *
+ * A template string cannot `import` this function into the daemon's own runtime (it is generated
+ * text, not compiled code), so {@link embedDaemonSource} keeps its OWN copy of the same three rules —
+ * `apply-leg-twins.test.ts` pins the generated body to the same `IDLE_MS_INT32_MAX` constant this
+ * module exports, so the two cannot drift apart silently.
+ */
+export declare function resolveIdleMs(raw: number): ResolvedIdleMs;
+/**
+ * Generate `.claude/helpers/dz-embed-daemon.mjs`. Behaviourally identical to the pre-existing
+ * hand-committed hub file except for: the version stamp (new, line 2) and `resolveDeps()`, which
+ * now tries `@huggingface/transformers` before falling back to `@xenova/transformers` — AM-3,
+ * dz-harness-hub issue #10 defect 3: `agentdb >= 3.0.0-alpha` depends on the former, and an older
+ * agentdb install still carries the latter, so probing only one name silently starved the daemon
+ * on either side of that agentdb version boundary.
+ */
+export declare function embedDaemonSource(): string;
+/** One Claude Code hook-registry entry in the matcher-group shape (no matcher — session/prompt events don't need one). */
+export interface ApplyLegHookEntry {
+    readonly hooks: readonly {
+        readonly type: 'command';
+        readonly command: string;
+    }[];
+}
+/**
+ * The two hook-registry entries `runSetup` merges into `.claude/settings.json` (FR-1). Commands
+ * match the hub's own `.claude/settings.json` verbatim (`grep`-diffed against it at authoring time):
+ * the recall hook is invoked with a swallowed non-zero exit (`|| true`) so a broken hook body never
+ * fails a prompt, and the embed daemon is spawned detached via `nohup` + a backgrounding `sh -c`
+ * so `SessionStart` never waits on model load.
+ */
+export declare function applyLegHookEntries(): {
+    readonly userPromptSubmit: ApplyLegHookEntry;
+    readonly sessionStart: ApplyLegHookEntry;
+};
+/** Version + presence of one deployed helper file. */
+export interface ApplyLegHelperStatus {
+    readonly path: string;
+    readonly exists: boolean;
+    /** {@link applyLegVersionOf} of the deployed file; `-1` when absent, unstamped, or unreadable. */
+    readonly version: number;
+    /** True only when the file EXISTS but could not be read (EISDIR, EACCES, …) — distinct from absent. */
+    readonly unreadable?: boolean;
+}
+/** Whether a hook-registry entry naming this helper was found in `.claude/settings.json`. */
+export interface ApplyLegHookPresence {
+    readonly present: boolean;
+}
+/**
+ * Why {@link ApplyLegStatus.installed} is `false`. Absent when `installed` is `true`.
+ *  - `'missing-helpers'` — at least one helper FILE does not exist.
+ *  - `'stale-version'` — both helpers exist and are readable, but at least one carries a
+ *    `dz-apply-leg-version` below {@link APPLY_LEG_VERSION}.
+ *  - `'hooks-missing'` — both helpers exist and are current, but `.claude/settings.json` does not
+ *    structurally wire one or both of them under the right event (fix round 1, HIGH finding 1).
+ *  - `'unreadable'` — a helper file EXISTS but could not be read (fix round 1, Q3 finding): reported
+ *    distinctly rather than silently folding into `missing-helpers`, which would tell a consumer to
+ *    re-run `dz setup` when the real problem is a broken/permission-denied file in the way.
+ */
+export type ApplyLegNotInstalledReason = 'missing-helpers' | 'stale-version' | 'hooks-missing' | 'unreadable';
+/** The ONE measurement `dz doctor` and `dz parity` both read (ADR-001 Decision 3) — never a static capability declaration. */
+export interface ApplyLegStatus {
+    /**
+     * True only when BOTH helper files exist, are READABLE, are at {@link APPLY_LEG_VERSION} or newer,
+     * AND both hook entries are structurally wired under the correct event — a partial or stale install
+     * is not installed (fix round 1, HIGH findings 1 and 2).
+     */
+    readonly installed: boolean;
+    /** Present exactly when `installed` is `false` — see {@link ApplyLegNotInstalledReason}. */
+    readonly reason?: ApplyLegNotInstalledReason;
+    readonly helpers: {
+        readonly recallHook: ApplyLegHelperStatus;
+        readonly embedDaemon: ApplyLegHelperStatus;
+    };
+    readonly hooks: {
+        readonly userPromptSubmit: ApplyLegHookPresence;
+        readonly sessionStart: ApplyLegHookPresence;
+    };
+    /** From `.dz/config.json`'s `memory.backend`; `'unknown'` when absent/unreadable/unrecognised. */
+    readonly backend: 'agentdb' | 'jsonl' | 'unknown';
+}
+/**
+ * ONE definition of "this command invokes our helper", shared by the installer (`setup.ts`
+ * `addIfMissing`) and the diagnostics (`applyLegStatus`) so they can never disagree (re-review
+ * Codex, third pass). A bare mention (`echo .claude/helpers/recall-hook.cjs`) is not an invocation:
+ * the helper path must follow a `node` word — directly, or inside the daemon's
+ * `sh -c 'nohup node "…"'` spawn. Forward slashes only: every command dz writes uses them.
+ */
+export declare function hookCommandInvokes(command: string, markerPath: string): boolean;
+/**
+ * Measure the apply leg's actual state in `root` — plain `fs` reads, no injection (mirrors
+ * `writerVersionOf`'s own read style): a diagnostic that needed dependency injection to be testable
+ * would be a diagnostic nobody could point at a REAL project either. Never throws (fix round 1, Q3):
+ * an unreadable helper is a named fact in the return value, not an exception that would otherwise
+ * blow through `dz doctor`'s outer try/catch (silence) or crash `dz parity` outright.
+ */
+export declare function applyLegStatus(root: string): ApplyLegStatus;
+/**
+ * Human remedy text shared VERBATIM between `dz doctor` and `dz parity` for the two reasons this
+ * fix round adds machinery for (fix round 1, HIGH finding 2 / Q3 finding 7): `stale-version` and
+ * `unreadable`. Both instruments read the SAME {@link ApplyLegStatus}; routing them through the same
+ * text-producing function is what makes "тексты совпадают по причине" a structural guarantee rather
+ * than two hand-written strings that happen to agree today. The `missing-helpers`/`hooks-missing`
+ * wording is deliberately NOT unified here — `dz doctor` and `dz parity` already carried different
+ * (pre-existing, tested) phrasing for that case before this fix round, and unifying it was not asked.
+ */
+export declare function applyLegReasonMessage(status: ApplyLegStatus): string;
+//# sourceMappingURL=apply-leg.d.ts.map

package/dist/apply-leg.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-leg.d.ts","sourceRoot":"","sources":["../src/apply-leg.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAMH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAEnC;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAGzD;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAW7E;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CA8YnE;AAED,gGAAgG;AAChG,eAAO,MAAM,iBAAiB,aAAgB,CAAC;AAE/C,mGAAmG;AACnG,MAAM,WAAW,cAAc;IAC7B,oGAAoG;IACpG,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,wFAAwF;IACxF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAIzD;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAwS1C;AAED,0HAA0H;AAC1H,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,SAAS;QAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACnF;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,IAAI;IAAE,QAAQ,CAAC,gBAAgB,EAAE,iBAAiB,CAAC;IAAC,QAAQ,CAAC,YAAY,EAAE,iBAAiB,CAAA;CAAE,CAehI;AAED,sDAAsD;AACtD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,kGAAkG;IAClG,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,uGAAuG;IACvG,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,6FAA6F;AAC7F,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,0BAA0B,GAAG,iBAAiB,GAAG,eAAe,GAAG,eAAe,GAAG,YAAY,CAAC;AAE9G,8HAA8H;AAC9H,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,4FAA4F;IAC5F,QAAQ,CAAC,MAAM,CAAC,EAAE,0BAA0B,CAAC;IAC7C,QAAQ,CAAC,OAAO,EAAE;QAChB,QAAQ,CAAC,UAAU,EAAE,oBAAoB,CAAC;QAC1C,QAAQ,CAAC,WAAW,EAAE,oBAAoB,CAAC;KAC5C,CAAC;IACF,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,gBAAgB,EAAE,oBAAoB,CAAC;QAChD,QAAQ,CAAC,YAAY,EAAE,oBAAoB,CAAC;KAC7C,CAAC;IACF,kGAAkG;IAClG,QAAQ,CAAC,OAAO,EAAE,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;CACnD;AAgBD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAG/E;AAmBD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAyD3D;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAYpE"}