@dzhechkov/harness-core 0.8.11 → 0.8.21

package/src/store-counts.ts

@@ -0,0 +1,154 @@
+/** Fast, readonly row counts for the two learning-store tiers. */
+import { createRequire } from 'node:module';
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+interface ReadonlyCountDb {
+  pragma: (s: string) => void;
+  prepare: (q: string) => { get: (...a: unknown[]) => unknown };
+  close: () => void;
+}
+
+export interface LearningStoreRowCounts {
+  readonly lexicalRows: number | 'unreadable';
+  /** Exact active quarantine labels in the selected lexical SQLite tier; absent for fallback/error paths. */
+  readonly lexicalQuarantinedRows?: number;
+  /** Physical lexical population counted; jsonl and SQLite maxima are not comparable. */
+  readonly lexicalSource: 'jsonl' | 'sqlite';
+  /** Exact selected physical source. SQLite wins when both stores coexist, matching runtime reads. */
+  readonly lexicalSourcePath: string;
+  /** Coexisting JSONL is deliberately excluded from the selected SQLite population. */
+  readonly lexicalIgnoredRows?: number | 'unreadable';
+  readonly lexicalIgnoredSourcePath?: string;
+  readonly vectorRows: number | 'unreadable';
+  /** Exact active quarantine labels on mirrored lesson rows; absent when the vector tier is missing/unreadable. */
+  readonly vectorQuarantinedRows?: number;
+  /** Present when the vector store file exists, including when its count is unreadable. */
+  readonly vectorSourcePath?: string;
+}
+
+function countJsonlRowsReadonly(path: string): number | 'unreadable' {
+  if (!existsSync(path)) return 0;
+  try {
+    return readFileSync(path, 'utf-8').split('\n').filter((line) => line.trim() !== '').length;
+  } catch {
+    return 'unreadable';
+  }
+}
+
+/** Best-effort readonly SQLite count with a short busy timeout. */
+export function countSqliteRowsReadonly(
+  sqlitePath: string,
+  table: 'memory_records' | 'reasoning_patterns',
+): number | undefined {
+  try {
+    const require = createRequire(import.meta.url);
+    const Database = require('better-sqlite3') as new (p: string, o?: object) => ReadonlyCountDb;
+    const db = new Database(sqlitePath, { readonly: true });
+    try {
+      db.pragma('busy_timeout = 100');
+      const row = db.prepare(`SELECT COUNT(*) as cnt FROM ${table}`).get() as { cnt?: unknown };
+      return typeof row?.cnt === 'number' ? row.cnt : undefined;
+    } finally {
+      db.close();
+    }
+  } catch {
+    return undefined;
+  }
+}
+
+interface SqliteRowsWithQuarantine {
+  readonly rows: number;
+  readonly quarantinedRows?: number;
+}
+
+/** One aggregate query on the healthy path; an unsupported metadata shape falls back to total-only. */
+function countSqliteRowsWithQuarantineReadonly(
+  sqlitePath: string,
+  table: 'memory_records' | 'reasoning_patterns',
+): SqliteRowsWithQuarantine | undefined {
+  try {
+    const require = createRequire(import.meta.url);
+    const Database = require('better-sqlite3') as new (p: string, o?: object) => ReadonlyCountDb;
+    const db = new Database(sqlitePath, { readonly: true });
+    try {
+      db.pragma('busy_timeout = 100');
+      try {
+        const sql = table === 'memory_records'
+          ? `SELECT COALESCE(SUM(n), 0) AS cnt,
+              COALESCE(SUM(CASE WHEN q_status = 'quarantined' THEN n ELSE 0 END), 0) AS quarantined
+            FROM (
+              SELECT CASE WHEN json_valid(metadata) THEN json_extract(metadata, '$.qStatus') END AS q_status,
+                COUNT(*) AS n
+              FROM memory_records GROUP BY 1
+            )`
+          : `WITH lesson_statuses AS (
+              SELECT CASE WHEN json_valid(metadata) THEN json_extract(metadata, '$.qStatus') END AS q_status,
+                COUNT(*) AS n
+              FROM reasoning_patterns
+              WHERE task_type IN ('dz-teach', 'dz-learning')
+              GROUP BY 1
+            )
+            SELECT (SELECT COUNT(*) FROM reasoning_patterns) AS cnt,
+              COALESCE(SUM(CASE WHEN q_status = 'quarantined' THEN n ELSE 0 END), 0) AS quarantined
+            FROM lesson_statuses`;
+        const row = db.prepare(sql).get() as { cnt?: unknown; quarantined?: unknown };
+        if (typeof row?.cnt !== 'number' || typeof row.quarantined !== 'number') return undefined;
+        return { rows: row.cnt, quarantinedRows: row.quarantined };
+      } catch {
+        const row = db.prepare(`SELECT COUNT(*) AS cnt FROM ${table}`).get() as { cnt?: unknown };
+        return typeof row?.cnt === 'number' ? { rows: row.cnt } : undefined;
+      }
+    } finally {
+      db.close();
+    }
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Count both protected store populations without opening either store writable.
+ * Missing tiers count as zero; an existing tier that cannot be counted is
+ * explicitly `unreadable`.
+ */
+export function countLearningStoreRowsReadonly(projectRoot: string): LearningStoreRowCounts {
+  const root = resolve(projectRoot);
+  const lexicalPath = join(root, '.dz', 'memory', 'patterns.sqlite');
+  const jsonlPath = join(root, '.dz', 'patterns.jsonl');
+  const vectorPath = join(root, '.dz', 'agentdb.db');
+  const vectorExists = existsSync(vectorPath);
+  const lexicalSource = existsSync(lexicalPath) ? 'sqlite' : 'jsonl';
+  const lexicalSqlite = lexicalSource === 'sqlite'
+    ? countSqliteRowsWithQuarantineReadonly(lexicalPath, 'memory_records')
+    : undefined;
+  let lexicalRows: number | 'unreadable';
+  if (lexicalSource === 'sqlite') {
+    lexicalRows = lexicalSqlite?.rows ?? 'unreadable';
+  } else {
+    lexicalRows = countJsonlRowsReadonly(jsonlPath);
+  }
+  const vectorSqlite = vectorExists
+    ? countSqliteRowsWithQuarantineReadonly(vectorPath, 'reasoning_patterns')
+    : undefined;
+  const ignoredJsonl = lexicalSource === 'sqlite' && existsSync(jsonlPath)
+    ? countJsonlRowsReadonly(jsonlPath)
+    : undefined;
+  return {
+    lexicalRows,
+    ...(lexicalSqlite?.quarantinedRows === undefined ? {} : {
+      lexicalQuarantinedRows: lexicalSqlite.quarantinedRows,
+    }),
+    lexicalSource,
+    lexicalSourcePath: lexicalSource === 'sqlite' ? lexicalPath : jsonlPath,
+    ...(ignoredJsonl === undefined ? {} : {
+      lexicalIgnoredRows: ignoredJsonl,
+      lexicalIgnoredSourcePath: jsonlPath,
+    }),
+    vectorRows: vectorExists ? (vectorSqlite?.rows ?? 'unreadable') : 0,
+    ...(vectorSqlite?.quarantinedRows === undefined ? {} : {
+      vectorQuarantinedRows: vectorSqlite.quarantinedRows,
+    }),
+    ...(vectorExists ? { vectorSourcePath: vectorPath } : {}),
+  };
+}

package/src/store-guard.ts

@@ -0,0 +1,388 @@
+/**
+ * Durable high-water mark for the two dz learning stores.
+ *
+ * The mark deliberately lives under the user's home directory, outside the
+ * project: deleting `<project>/.dz` must not delete the evidence that a store
+ * existed there.
+ *
+ * @packageDocumentation
+ */
+
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, join, resolve } from 'node:path';
+
+import { withNamedLockSync } from './named-lock.js';
+
+export const STORE_GUARD_VERSION = 1 as const;
+
+/**
+ * A fall of more than 10% from the lifetime maximum is anomalous. A second,
+ * absolute threshold below catches a sharp recent loss before it reaches 10%.
+ * Basis: across 55 days and 9 measured snapshots the counter never decreased
+ * (190 -> 1385), measured 2026-09-06.
+ */
+export const STORE_COLLAPSE_MAX_FRACTION = 0.10;
+
+/** See {@link STORE_COLLAPSE_MAX_FRACTION} for the measured basis. */
+export const STORE_COLLAPSE_LAST_ROWS = 50;
+
+/** Fractional collapse detection is too noisy below this observed population. */
+export const STORE_COLLAPSE_MIN_ROWS = 10;
+
+export interface AcceptedStoreShrink {
+  readonly at: string;
+  readonly reason: string;
+  /** Required on every receipt written by the source-aware guard; absent only on legacy marks. */
+  readonly command?: string;
+  readonly kind?: 'measured-deletion' | 'source-transition' | 'operator-reset' | 'cold-start-override';
+  readonly before?: StoreCountSnapshot;
+  readonly after?: StoreCountSnapshot;
+}
+
+export interface StoreResetReceipt {
+  readonly at: string;
+  readonly command: string;
+  readonly decision: 'manual operator decision';
+  readonly before: StoreCountSnapshot;
+  readonly after: StoreCountSnapshot;
+  readonly reason: string;
+}
+
+export type StoreCountSource = 'jsonl' | 'sqlite';
+
+export interface StoreCountSnapshot {
+  readonly lexicalRows: number;
+  readonly vectorRows: number;
+  readonly lexicalSource: StoreCountSource;
+}
+
+export interface StoreMark {
+  readonly project: string;
+  /** `unknown` is read-only compatibility for marks written before source tracking existed. */
+  readonly lexicalSource: StoreCountSource | 'unknown';
+  readonly lexicalMax: number;
+  readonly vectorMax: number;
+  readonly lexicalLast: number;
+  readonly vectorLast: number;
+  /** First lexical backend transition since the last explicit reset. */
+  readonly sourceChangedAt?: string;
+  /** Most recent explicit operator reset. */
+  readonly resetAt?: StoreResetReceipt;
+  /** Legacy v1 audit field. Readable for compatibility, never re-emitted or treated as authorization. */
+  readonly acceptedShrinkAt?: AcceptedStoreShrink;
+  readonly updatedAt: string;
+  readonly version: number;
+}
+
+export interface StoreMarkObservation {
+  readonly lexicalRows: number;
+  readonly vectorRows: number;
+  readonly lexicalSource: StoreCountSource;
+  readonly observedAt: string;
+  /** Command that produced the observation; diagnostic only, never authorization. */
+  readonly command?: string;
+}
+
+export interface StoreMarkWriteOptions {
+  /** Zero makes a reader's opportunistic mark refresh a single non-blocking acquisition attempt. */
+  readonly timeoutMs?: number;
+  /** Writer-preflight compare-and-set used to consume a source transition exactly once. */
+  readonly expectedPreviousLexicalSource?: StoreCountSource | 'unknown';
+}
+
+export type StoreRowCount = number | 'unreadable';
+
+export type StoreHealthVerdict = 'ok' | 'collapsed' | 'cold-start-over-existing' | 'source-changed' | 'unreadable' | 'no-mark';
+
+export interface StoreHealth {
+  readonly verdict: StoreHealthVerdict;
+  readonly reason: string;
+}
+
+export interface StoreHealthInput {
+  readonly projectRoot: string;
+  readonly lexicalRows: StoreRowCount;
+  readonly lexicalSource: StoreCountSource;
+  readonly vectorRows: StoreRowCount;
+  readonly mark: StoreMark | undefined;
+}
+
+function canonicalProjectRoot(projectRoot: string): string {
+  const absolute = resolve(projectRoot);
+  return existsSync(absolute) ? realpathSync(absolute) : absolute;
+}
+
+function projectHash(projectRoot: string): string {
+  return createHash('sha256').update(canonicalProjectRoot(projectRoot)).digest('hex').slice(0, 16);
+}
+
+/** External high-water-mark path for one canonical project root. */
+export function storeGuardPath(projectRoot: string): string {
+  return join(homedir(), '.dz-store-guard', `${projectHash(projectRoot)}.json`);
+}
+
+/** External directory populated by `scripts/dz-store-snapshot.sh` for this project. */
+export function storeSnapshotPath(projectRoot: string): string {
+  return join(homedir(), '.dz-store-snapshots', projectHash(projectRoot));
+}
+
+function isCount(value: unknown): value is number {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+
+function isStoreCountSource(value: unknown): value is StoreCountSource {
+  return value === 'jsonl' || value === 'sqlite';
+}
+
+function isStoreCountSnapshot(value: unknown): value is StoreCountSnapshot {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  const candidate = value as Partial<StoreCountSnapshot>;
+  return isCount(candidate.lexicalRows) && isCount(candidate.vectorRows)
+    && isStoreCountSource(candidate.lexicalSource);
+}
+
+function parseStoreMark(raw: string, path: string, projectRoot: string): StoreMark {
+  let value: unknown;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    throw new Error(`store guard mark is not valid JSON: ${path}`);
+  }
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new Error(`store guard mark is not an object: ${path}`);
+  }
+  const candidate = value as Partial<StoreMark>;
+  const canonical = canonicalProjectRoot(projectRoot);
+  if (candidate.project !== canonical) throw new Error(`store guard project mismatch in ${path}`);
+  if (!isCount(candidate.lexicalMax) || !isCount(candidate.vectorMax)
+    || !isCount(candidate.lexicalLast) || !isCount(candidate.vectorLast)) {
+    throw new Error(`store guard mark has invalid row counts: ${path}`);
+  }
+  if (typeof candidate.updatedAt !== 'string' || Number.isNaN(Date.parse(candidate.updatedAt))) {
+    throw new Error(`store guard mark has invalid updatedAt: ${path}`);
+  }
+  if (candidate.version !== STORE_GUARD_VERSION) {
+    throw new Error(`unsupported store guard version ${String(candidate.version)} in ${path}`);
+  }
+  if (candidate.lexicalSource !== undefined
+    && candidate.lexicalSource !== 'jsonl' && candidate.lexicalSource !== 'sqlite') {
+    throw new Error(`store guard mark has invalid lexicalSource: ${path}`);
+  }
+  if (candidate.acceptedShrinkAt !== undefined) {
+    const accepted = candidate.acceptedShrinkAt;
+    if (typeof accepted !== 'object' || accepted === null || Array.isArray(accepted)
+      || typeof accepted.at !== 'string' || Number.isNaN(Date.parse(accepted.at))
+      || typeof accepted.reason !== 'string' || accepted.reason.trim() === '') {
+      throw new Error(`store guard mark has invalid acceptedShrinkAt: ${path}`);
+    }
+    const structured = accepted.command !== undefined || accepted.kind !== undefined
+      || accepted.before !== undefined || accepted.after !== undefined;
+    if (structured && (typeof accepted.command !== 'string' || accepted.command.trim() === ''
+      || !['measured-deletion', 'source-transition', 'operator-reset', 'cold-start-override'].includes(accepted.kind ?? '')
+      || !isStoreCountSnapshot(accepted.before) || !isStoreCountSnapshot(accepted.after))) {
+      throw new Error(`store guard mark has invalid reconciliation receipt: ${path}`);
+    }
+  }
+  if (candidate.sourceChangedAt !== undefined
+    && (typeof candidate.sourceChangedAt !== 'string' || Number.isNaN(Date.parse(candidate.sourceChangedAt)))) {
+    throw new Error(`store guard mark has invalid sourceChangedAt: ${path}`);
+  }
+  if (candidate.resetAt !== undefined) {
+    const reset = candidate.resetAt;
+    if (typeof reset !== 'object' || reset === null || Array.isArray(reset)
+      || typeof reset.at !== 'string' || Number.isNaN(Date.parse(reset.at))
+      || typeof reset.command !== 'string' || reset.command.trim() === ''
+      || reset.decision !== 'manual operator decision'
+      || !isStoreCountSnapshot(reset.before) || !isStoreCountSnapshot(reset.after)
+      || typeof reset.reason !== 'string' || reset.reason.trim() === '') {
+      throw new Error(`store guard mark has invalid resetAt receipt: ${path}`);
+    }
+  }
+  return {
+    ...(candidate as StoreMark),
+    lexicalSource: candidate.lexicalSource ?? 'unknown',
+  };
+}
+
+/** Read the external mark; absence is the only condition represented by `undefined`. */
+export function readStoreMark(projectRoot: string): StoreMark | undefined {
+  const path = storeGuardPath(projectRoot);
+  if (!existsSync(path)) return undefined;
+  return parseStoreMark(readFileSync(path, 'utf8'), path, projectRoot);
+}
+
+function validateObservation(observation: StoreMarkObservation): void {
+  if (!isCount(observation.lexicalRows) || !isCount(observation.vectorRows)) {
+    throw new Error('store guard observation has invalid row counts');
+  }
+  if (typeof observation.observedAt !== 'string' || Number.isNaN(Date.parse(observation.observedAt))) {
+    throw new Error('store guard observation has invalid observedAt');
+  }
+  if (observation.lexicalSource !== 'jsonl' && observation.lexicalSource !== 'sqlite') {
+    throw new Error('store guard observation has invalid lexical source');
+  }
+  if (observation.command !== undefined && observation.command.trim() === '') {
+    throw new Error('store guard observation command must not be empty');
+  }
+}
+
+function persistStoreMark(path: string, mark: StoreMark): StoreMark {
+  const temp = `${path}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    writeFileSync(temp, `${JSON.stringify(mark, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    renameSync(temp, path);
+  } finally {
+    try { unlinkSync(temp); } catch { /* renamed or never created */ }
+  }
+  return mark;
+}
+
+/**
+ * Atomically record an ordinary observation. Both maxima are monotonic by
+ * construction: no command label, measured deletion, override, or source
+ * transition can lower them. A first source transition is recorded as
+ * metadata only; a later low-population transition requires an explicit reset.
+ */
+export function writeStoreMark(
+  projectRoot: string,
+  observation: StoreMarkObservation,
+  options: StoreMarkWriteOptions = {},
+): StoreMark {
+  const project = canonicalProjectRoot(projectRoot);
+  const path = storeGuardPath(project);
+  const guardRoot = dirname(path);
+  validateObservation(observation);
+  mkdirSync(guardRoot, { recursive: true, mode: 0o700 });
+
+  return withNamedLockSync(guardRoot, `store-guard-${basename(path, '.json')}`, () => {
+    const previous = readStoreMark(project);
+    if (options.expectedPreviousLexicalSource !== undefined
+      && previous?.lexicalSource !== options.expectedPreviousLexicalSource) {
+      throw new Error(`lexical source-change allowance was already consumed; expected ${options.expectedPreviousLexicalSource}, found ${previous?.lexicalSource ?? 'no mark'}`);
+    }
+    const sourceChanged = previous !== undefined && previous.lexicalSource !== 'unknown'
+      && previous.lexicalSource !== observation.lexicalSource;
+    if (sourceChanged && previous.sourceChangedAt !== undefined
+      && observation.lexicalRows < previous.lexicalMax) {
+      throw new Error('lexical source changed again below the recorded maximum; run dz store-guard --reset');
+    }
+    const next: StoreMark = {
+      project,
+      lexicalSource: observation.lexicalSource,
+      lexicalMax: Math.max(previous?.lexicalMax ?? 0, observation.lexicalRows),
+      vectorMax: Math.max(previous?.vectorMax ?? 0, observation.vectorRows),
+      lexicalLast: observation.lexicalRows,
+      vectorLast: observation.vectorRows,
+      ...(sourceChanged ? { sourceChangedAt: previous?.sourceChangedAt ?? observation.observedAt }
+        : previous?.sourceChangedAt === undefined ? {} : { sourceChangedAt: previous.sourceChangedAt }),
+      ...(previous?.resetAt === undefined ? {} : { resetAt: previous.resetAt }),
+      updatedAt: observation.observedAt,
+      version: STORE_GUARD_VERSION,
+    };
+    return persistStoreMark(path, next);
+  }, { ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }) });
+}
+
+/** Explicit lowering primitive. Callers must obtain operator confirmation first. */
+export function resetStoreMark(projectRoot: string, observation: StoreMarkObservation): StoreMark {
+  const project = canonicalProjectRoot(projectRoot);
+  const path = storeGuardPath(project);
+  const guardRoot = dirname(path);
+  validateObservation(observation);
+  if (observation.command?.trim() !== 'dz store-guard --reset') {
+    throw new Error('store guard reset requires command dz store-guard --reset');
+  }
+  mkdirSync(guardRoot, { recursive: true, mode: 0o700 });
+  return withNamedLockSync(guardRoot, `store-guard-${basename(path, '.json')}`, () => {
+    const previous = readStoreMark(project);
+    const before: StoreCountSnapshot = {
+      lexicalRows: previous?.lexicalMax ?? observation.lexicalRows,
+      vectorRows: previous?.vectorMax ?? observation.vectorRows,
+      lexicalSource: previous?.lexicalSource === 'jsonl' || previous?.lexicalSource === 'sqlite'
+        ? previous.lexicalSource
+        : observation.lexicalSource,
+    };
+    const after: StoreCountSnapshot = {
+      lexicalRows: observation.lexicalRows,
+      vectorRows: observation.vectorRows,
+      lexicalSource: observation.lexicalSource,
+    };
+    const resetAt: StoreResetReceipt = {
+      at: observation.observedAt,
+      command: 'dz store-guard --reset',
+      decision: 'manual operator decision',
+      before,
+      after,
+      reason: `dz store-guard --reset: manual operator decision; before lexical=${before.lexicalRows}, vector=${before.vectorRows}; after lexical=${after.lexicalRows}, vector=${after.vectorRows}`,
+    };
+    return persistStoreMark(path, {
+      project,
+      lexicalSource: observation.lexicalSource,
+      lexicalMax: observation.lexicalRows,
+      vectorMax: observation.vectorRows,
+      lexicalLast: observation.lexicalRows,
+      vectorLast: observation.vectorRows,
+      resetAt,
+      updatedAt: observation.observedAt,
+      version: STORE_GUARD_VERSION,
+    });
+  });
+}
+
+function collapsedTier(name: 'lexical' | 'vector', rows: number, maximum: number, last: number): string | undefined {
+  if (maximum >= STORE_COLLAPSE_MIN_ROWS && rows < maximum * (1 - STORE_COLLAPSE_MAX_FRACTION)) {
+    return `${name} rows ${rows} are more than ${STORE_COLLAPSE_MAX_FRACTION * 100}% below maximum ${maximum}`;
+  }
+  if (last - rows > STORE_COLLAPSE_LAST_ROWS) {
+    return `${name} rows ${rows} are more than ${STORE_COLLAPSE_LAST_ROWS} below previous ${last}`;
+  }
+  return undefined;
+}
+
+/** Pure classification of current row counts against the external mark. */
+export function checkStoreHealth(input: StoreHealthInput): StoreHealth {
+  const { projectRoot, lexicalRows, lexicalSource, vectorRows, mark } = input;
+  const unreadable = [
+    ...(lexicalRows === 'unreadable' ? ['lexical'] : []),
+    ...(vectorRows === 'unreadable' ? ['vector'] : []),
+  ];
+  if (unreadable.length > 0) {
+    return {
+      verdict: 'unreadable',
+      reason: `${unreadable.join(' and ')} store${unreadable.length > 1 ? 's are' : ' is'} unreadable`,
+    };
+  }
+  if (mark === undefined) return { verdict: 'no-mark', reason: 'no store mark exists for this project' };
+
+  const lexicalCount = lexicalRows as number;
+  const vectorCount = vectorRows as number;
+  const sourceChanged = mark.lexicalSource !== lexicalSource;
+
+  const cold: string[] = [];
+  if (mark.lexicalMax > 0 && lexicalCount === 0) cold.push(`lexical had ${mark.lexicalMax}`);
+  if (mark.vectorMax > 0 && vectorCount === 0) cold.push(`vector had ${mark.vectorMax}`);
+  if (cold.length > 0) {
+    return {
+      verdict: 'cold-start-over-existing',
+      reason: `${resolve(projectRoot)} is empty over an existing mark (${cold.join(', ')})`,
+    };
+  }
+
+  const repeatedLowSourceChange = sourceChanged && mark.sourceChangedAt !== undefined
+    && lexicalCount < mark.lexicalMax
+    ? `lexical source changed again after ${mark.sourceChangedAt} with rows ${lexicalCount} below maximum ${mark.lexicalMax}`
+    : undefined;
+  const collapse = repeatedLowSourceChange
+    ?? (sourceChanged ? undefined : collapsedTier('lexical', lexicalCount, mark.lexicalMax, mark.lexicalLast))
+    ?? collapsedTier('vector', vectorCount, mark.vectorMax, mark.vectorLast);
+  if (collapse !== undefined) return { verdict: 'collapsed', reason: collapse };
+  if (sourceChanged) {
+    return {
+      verdict: 'source-changed',
+      reason: `lexical source changed from ${mark.lexicalSource} to ${lexicalSource}; one writer may record the migration without lowering maximum ${mark.lexicalMax}, then use dz store-guard --reset if the new baseline is intentional`,
+    };
+  }
+  return { verdict: 'ok', reason: 'row counts are within the recorded high-water bounds' };
+}