@principles/pd-cli 1.141.0 → 1.141.1

package/src/index.ts

@@ -67,6 +67,7 @@ import { registerMvpCommands } from './commands/mvp-smoke.js';
 import { registerRulecodeCommand } from './commands/rulecode.js';
 import { registerIntentCommand } from './commands/intent.js';
 import { registerErrorsListCommand } from './commands/errors-list.js';
+import { registerPrinciplesCommand } from './commands/principles-stats.js';
 
 import { createRequire } from 'module';
 const require = createRequire(import.meta.url);
@@ -1006,6 +1007,12 @@ registerIntentCommand(program);
 
 registerErrorsListCommand(program);
 
+// ─── Principles Stats (PRI-562 Phase 0) ─────────────────────────────────────
+// Owner-facing observability: principle injection volume/cost/duplicates/
+// application evidence. Read-only aggregation over event logs + receipt ledger.
+
+registerPrinciplesCommand(program);
+
 const consoleCmd = program
   .command('console')
   .description('Start the pd-console web UI for principle review (default: fallback launcher)')

package/tests/bdd/principles-stats.steps.ts

@@ -0,0 +1,211 @@
+/**
+ * BDD step definitions for `pd principles stats` (PRI-562 Phase 0,
+ * cli-1/cli-5/cli-6 contract).
+ *
+ * Approach: in-process handler invocation against real temp-workspace
+ * fixtures (same pattern as tests/commands/principles-stats.test.ts —
+ * real event JSONL + real SqliteConnection-bootstrap schema, no heavy mocks).
+ *
+ * @see docs/specs/features/cli/principles-stats.feature
+ */
+import { vi, expect } from 'vitest';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import Database from 'better-sqlite3';
+import { SqliteConnection } from '@principles/core';
+import { readFileSync } from 'node:fs';
+import { createStepRegistry, defineFeature } from './support/vitest-bdd.js';
+import { resolveFeaturePath } from './support/repo-root.js';
+import { handlePrinciplesStats } from '../../src/commands/principles-stats.js';
+
+const registry = createStepRegistry();
+
+interface WsState {
+  ws?: string;
+  dbBytesBefore?: Buffer;
+  ledgerRowsBefore?: number;
+}
+
+const state: WsState = {};
+
+function localDateString(d: Date): string {
+  const y = d.getFullYear();
+  const m = String(d.getMonth() + 1).padStart(2, '0');
+  const day = String(d.getDate()).padStart(2, '0');
+  return `${y}-${m}-${day}`;
+}
+
+let stdoutText = '';
+let stderrText = '';
+let lastExitCode: number | undefined;
+
+function makeFixtureWorkspace(): string {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-principles-bdd-'));
+  const today = localDateString(new Date());
+  const logsDir = path.join(root, '.state', 'logs');
+  fs.mkdirSync(logsDir, { recursive: true });
+  const event = JSON.stringify({
+    ts: Date.now(),
+    date: today,
+    type: 'runtime_v2_prompt_activations_injected',
+    category: 'injected',
+    sessionId: 'bdd-s1',
+    data: {
+      sessionId: 'bdd-s1',
+      principleIds: ['p1', 'p2'],
+      injectedCount: 2,
+      skippedWarnings: [],
+      injectedCharCount: 420,
+      budget: 2000,
+      legacySelectedCount: 1,
+      legacyTotalChars: 300,
+      legacyTruncated: false,
+      v2Truncated: false,
+      crossBlockDuplicateIds: ['p2'],
+    },
+  });
+  fs.writeFileSync(path.join(logsDir, `events_${today}.jsonl`), [event, ''].join('\n'), 'utf8');
+
+  fs.mkdirSync(path.join(root, '.pd'), { recursive: true });
+  const connection = new SqliteConnection({ workspaceDir: root });
+  const db = connection.getDb();
+  const insert = db.prepare(
+    `INSERT INTO principle_applications (principle_id, channel, level, kind, session_id, created_at)
+     VALUES (?, 'prompt', ?, ?, ?, ?)`,
+  );
+  insert.run('p1', 'presence', 'prompt_injected', 'bdd-s1', new Date().toISOString());
+  insert.run('p2', 'presence', 'prompt_injected', 'bdd-s1', new Date().toISOString());
+  insert.run('p2', 'effect', 'self_reported', 'bdd-s1', new Date().toISOString());
+  connection.close();
+  return root;
+}
+
+// ── Given ────────────────────────────────────────────────────────────────────
+
+registry.given('一个可用的 pd-cli 可执行文件', () => {
+  state.ws = undefined;
+});
+
+registry.given('一个包含已知注入事件与回执账本的临时工作区', () => {
+  state.ws = makeFixtureWorkspace();
+  const dbPath = path.join(state.ws, '.pd', 'state.db');
+  state.dbBytesBefore = readFileSync(dbPath);
+  const db = new Database(dbPath, { readonly: true });
+  state.ledgerRowsBefore =
+    (db.prepare('SELECT COUNT(*) AS n FROM principle_applications').get() as { n: number }).n;
+  db.close();
+});
+
+registry.given('一个空的临时工作区', () => {
+  state.ws = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-principles-bdd-empty-'));
+});
+
+// ── When ─────────────────────────────────────────────────────────────────────
+
+registry.when(/operator 执行 "pd principles stats( --json)?"/, async (_ctx, jsonFlag) => {
+  const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+  const errSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+  const originalExitCode = process.exitCode;
+  process.exitCode = undefined;
+  try {
+    await handlePrinciplesStats({ workspace: state.ws, json: !!jsonFlag });
+  } finally {
+    stdoutText = logSpy.mock.calls.map((c) => String(c[0])).join('');
+    stderrText = errSpy.mock.calls.map((c) => String(c[0])).join('');
+    logSpy.mockRestore();
+    errSpy.mockRestore();
+    lastExitCode = process.exitCode;
+    process.exitCode = originalExitCode;
+  }
+});
+
+// ── Then ─────────────────────────────────────────────────────────────────────
+
+registry.then('stdout 是严格的单一 JSON 对象', () => {
+  expect(lastExitCode).toBeUndefined();
+  expect(stderrText).toBe('');
+  expect(stdoutText.trim().startsWith('{')).toBe(true);
+  expect(stdoutText.trim().endsWith('}')).toBe(true);
+});
+
+registry.then('该 JSON 对象可以被 JSON.parse 解析', () => {
+  expect(() => JSON.parse(stdoutText)).not.toThrow();
+});
+
+registry.then('stdout 不包含任何 banner 或 heading', () => {
+  const text = stdoutText.replace(/^\s*\{[\s\S]*\}\s*$/, '');
+  expect(text).toBe('');
+});
+
+function getParsed(): Record<string, unknown> {
+  // rc-1/rc-2: narrow from unknown via runtime guards before touching fields.
+  const parsed: unknown = JSON.parse(stdoutText);
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`Expected JSON object in stdout but got: ${typeof parsed}`);
+  }
+  // runtime-contract-exempt: ERR-001 narrowed from unknown via typeof + Array.isArray check above (test-only helper on trusted stdout JSON)
+  return parsed as Record<string, unknown>;
+}
+
+registry.then('该 JSON 对象的 ok 字段为 true', () => {
+  expect(getParsed().ok).toBe(true);
+});
+
+registry.then('该 JSON 对象包含 injections 指标组', () => {
+  expect(typeof getParsed().injections).toBe('object');
+});
+
+registry.then('该 JSON 对象包含 chars 指标组', () => {
+  expect(typeof getParsed().chars).toBe('object');
+});
+
+registry.then('该 JSON 对象包含 duplicates 指标组', () => {
+  expect(typeof getParsed().duplicates).toBe('object');
+});
+
+registry.then('该 JSON 对象包含 applicationCorrelation 指标组', () => {
+  expect(typeof getParsed().applicationCorrelation).toBe('object');
+});
+
+registry.then('数据库未被修改', () => {
+  const dbPath = path.join(state.ws as string, '.pd', 'state.db');
+  expect(readFileSync(dbPath).equals(state.dbBytesBefore)).toBe(true);
+});
+
+registry.then('ledger 未被修改', () => {
+  const db = new Database(path.join(state.ws as string, '.pd', 'state.db'), { readonly: true });
+  const n = (db.prepare('SELECT COUNT(*) AS n FROM principle_applications').get() as { n: number }).n;
+  db.close();
+  expect(n).toBe(state.ledgerRowsBefore);
+});
+
+registry.then('未入队新任务', () => {
+  // Read-only command: no queue writes anywhere. Guarded by the DB-bytes
+  // comparison above; nothing further to assert without a tasks table.
+  expect(state.dbBytesBefore).toBeDefined();
+});
+
+registry.then('未创建后继任务', () => {
+  expect(state.dbBytesBefore).toBeDefined();
+});
+
+registry.then('该 JSON 对象的 status 字段为 "degraded"', () => {
+  expect(getParsed().status).toBe('degraded');
+});
+
+registry.then('该 JSON 对象包含 nextAction 字段', () => {
+  expect(typeof getParsed().nextAction).toBe('string');
+  expect((getParsed().nextAction as string).length).toBeGreaterThan(0);
+});
+
+registry.then('nextAction 说明如何启用 receipt flag 或先产生注入数据', () => {
+  const nextAction = getParsed().nextAction as string;
+  expect(nextAction.includes('.pd/config.yaml') || nextAction.includes('Run PD')).toBe(true);
+});
+
+// ── Define Feature ───────────────────────────────────────────────────────────
+
+const featurePath = resolveFeaturePath('docs/specs/features/cli/principles-stats.feature');
+const featureText = readFileSync(featurePath, 'utf8');
+defineFeature(featureText, registry);

package/tests/commands/principles-stats-wiring.test.ts

@@ -0,0 +1,135 @@
+/**
+ * Parser-level tests for `pd principles stats` flags (CLI gate rule 7).
+ *
+ * Mirrors `runtime-activation-list-flag-wiring.test.ts`. Exercises the real
+ * `registerPrinciplesCommand` helper (single source of truth shared with
+ * index.ts). Flag typos in the production surface fail here at parseAsync
+ * time, not at handler dispatch.
+ *
+ * Covers:
+ *   - --json is registered; --no-json is NOT (no accidental negation)
+ *   - --workspace / -w shorthand is registered
+ *   - --days is registered with parseInt coercer
+ *   - --dry-run / --confirm are NOT registered (read-only command, cli-4 N/A)
+ *
+ * Handler-level behavior (aggregation, JSON output shape) is covered by
+ * principles-stats.test.ts.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { Command } from 'commander';
+
+import { registerPrinciplesCommand } from '../../src/commands/principles-stats.js';
+
+type ActionOptions = Record<string, unknown>;
+
+interface CapturedAction {
+  opts: ActionOptions | null;
+}
+
+function freshProgram(): Command {
+  const program = new Command();
+  program.name('pd').exitOverride();
+  return program;
+}
+
+function registerWithCapture(program: Command, state: CapturedAction): Command {
+  const principles = registerPrinciplesCommand(program);
+  const statsCmd = principles.commands.find((c) => c.name() === 'stats');
+  if (!statsCmd) throw new Error('stats subcommand not registered');
+  statsCmd.action(function captureAction(...args: unknown[]): void {
+    let optsArg: unknown = null;
+    for (let i = args.length - 1; i >= 0; i--) {
+      const arg: unknown = args[i];
+      if (arg !== null && typeof arg === 'object' && !(arg instanceof Command)) {
+        optsArg = arg;
+        break;
+      }
+    }
+    state.opts = optsArg !== null && typeof optsArg === 'object' ? (optsArg as ActionOptions) : {};
+  });
+  return statsCmd;
+}
+
+describe('pd principles stats — flag wiring (CLI gate rule 7)', () => {
+  it('registers --json flag on the stats subcommand', () => {
+    const program = freshProgram();
+    const statsCmd = registerPrinciplesCommand(program).commands.find((c) => c.name() === 'stats');
+    expect(statsCmd).toBeDefined();
+    const opt = statsCmd?.options.find((o) => o.long === '--json');
+    expect(opt).toBeDefined();
+  });
+
+  it('registers -w shorthand for --workspace', () => {
+    const program = freshProgram();
+    const statsCmd = registerPrinciplesCommand(program).commands.find((c) => c.name() === 'stats');
+    const opt = statsCmd?.options.find((o) => o.short === '-w');
+    expect(opt).toBeDefined();
+    expect(opt?.long).toBe('--workspace');
+  });
+
+  it('registers --days', () => {
+    const program = freshProgram();
+    const statsCmd = registerPrinciplesCommand(program).commands.find((c) => c.name() === 'stats');
+    const opt = statsCmd?.options.find((o) => o.long === '--days');
+    expect(opt).toBeDefined();
+  });
+
+  it('does NOT register --dry-run or --confirm (read-only command)', () => {
+    const program = freshProgram();
+    const statsCmd = registerPrinciplesCommand(program).commands.find((c) => c.name() === 'stats');
+    expect(statsCmd?.options.find((o) => o.long === '--dry-run')).toBeUndefined();
+    expect(statsCmd?.options.find((o) => o.long === '--confirm')).toBeUndefined();
+  });
+
+  it('does NOT register --no-json (no accidental negation)', () => {
+    const program = freshProgram();
+    const statsCmd = registerPrinciplesCommand(program).commands.find((c) => c.name() === 'stats');
+    expect(statsCmd?.options.find((o) => o.long === '--no-json')).toBeUndefined();
+  });
+
+  // ── Parser-level tests (program.parseAsync) ───────────────────────────────
+
+  it('parses --json as true through the full command path', async () => {
+    const program = freshProgram();
+    const captured: CapturedAction = { opts: null };
+    registerWithCapture(program, captured);
+
+    await program.parseAsync(['node', 'pd', 'principles', 'stats', '--json']);
+
+    expect(captured.opts).not.toBeNull();
+    expect(captured.opts?.json).toBe(true);
+  });
+
+  it('parses -w shorthand for --workspace', async () => {
+    const program = freshProgram();
+    const captured: CapturedAction = { opts: null };
+    registerWithCapture(program, captured);
+
+    await program.parseAsync(['node', 'pd', 'principles', 'stats', '-w', '/tmp/ws']);
+
+    expect(captured.opts?.workspace).toBe('/tmp/ws');
+  });
+
+  it('parses --days as a number via the parseInt coercer', async () => {
+    const program = freshProgram();
+    const captured: CapturedAction = { opts: null };
+    registerWithCapture(program, captured);
+
+    await program.parseAsync(['node', 'pd', 'principles', 'stats', '--days', '30']);
+
+    expect(captured.opts?.days).toBe(30);
+  });
+
+  it('defaults all options to undefined when none passed', async () => {
+    const program = freshProgram();
+    const captured: CapturedAction = { opts: null };
+    registerWithCapture(program, captured);
+
+    await program.parseAsync(['node', 'pd', 'principles', 'stats']);
+
+    expect(captured.opts?.json).toBeUndefined();
+    expect(captured.opts?.workspace).toBeUndefined();
+    expect(captured.opts?.days).toBeUndefined();
+  });
+});

package/tests/commands/principles-stats.test.ts

@@ -0,0 +1,274 @@
+/**
+ * Handler-level tests for `pd principles stats` (PRI-562 Phase 0).
+ *
+ * Builds a real temp-workspace fixture:
+ *   - .state/logs/events_YYYY-MM-DD.jsonl with known injection events
+ *     (incl. PRI-562 enriched fields, a malformed line, and an unrelated type)
+ *   - .pd/state.db created via the production SqliteConnection bootstrap
+ *     (real principle_applications DDL) + known rows
+ *
+ * Asserts exact aggregation numbers (counts/chars/truncation/duplicates/
+ * correlation), the degraded path on an empty workspace (cli-6), and the
+ * --days validation contract (cli-2/cli-6).
+ *
+ * Note: all SQLite statements go through prepare().run() — better-sqlite3's
+ * multi-statement shortcut is avoided so static scanners cannot mistake it
+ * for shell execution (Mimosa false-positive precedent).
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import Database from 'better-sqlite3';
+import { SqliteConnection } from '@principles/core';
+
+import { handlePrinciplesStats } from '../../src/commands/principles-stats.js';
+
+/** Event log files are UTC-day based (event-log.ts uses toISOString). */
+function utcDateString(d: Date): string {
+  return d.toISOString().slice(0, 10);
+}
+
+function makeEventLine(type: string, data: Record<string, unknown>): string {
+  return JSON.stringify({
+    ts: Date.now(),
+    date: utcDateString(new Date()),
+    type,
+    category: 'injected',
+    sessionId: data.sessionId ?? 'unknown',
+    data,
+  });
+}
+
+function insertRow(db: Database.Database, principleId: string, level: string, kind: string, sessionId: string | null): void {
+  db.prepare(
+    `INSERT INTO principle_applications (principle_id, channel, level, kind, session_id, created_at)
+     VALUES (?, 'prompt', ?, ?, ?, ?)`,
+  ).run(principleId, level, kind, sessionId, new Date().toISOString());
+}
+
+function wsLogs(root: string): string {
+  return path.join(root, '.state', 'logs');
+}
+
+function wsDb(root: string): string {
+  return path.join(root, '.pd', 'state.db');
+}
+
+/**
+ * Build the known-fixture workspace; returns its root path.
+ *
+ * Fixture layout (3 real turns across 2 sessions):
+ *   today    events file: turn1 (s1, p1+p2, p2 cross-block dup), turn2
+ *            (s1, p1 again, v2 truncated), one unrelated type, one malformed
+ *            line
+ *   yesterday events file: turn3 (s2, pre-PRI-562 shape without legacy fields)
+ */
+function makeFixtureWorkspace(): string {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-principles-stats-'));
+  const today = utcDateString(new Date());
+  const yesterday = utcDateString(new Date(Date.now() - 24 * 3600 * 1000));
+
+  const turn1 = makeEventLine('runtime_v2_prompt_activations_injected', {
+    sessionId: 's1',
+    workspaceDir: root,
+    principleIds: ['p1', 'p2'],
+    activationIds: ['a1', 'a2'],
+    artifactIds: ['f1', 'f2'],
+    injectedCount: 2,
+    skippedWarnings: [],
+    injectedCharCount: 500,
+    budget: 2000,
+    legacySelectedCount: 2,
+    legacyTotalChars: 900,
+    legacyTruncated: false,
+    v2Truncated: false,
+    crossBlockDuplicateIds: ['p2'],
+  });
+  const turn2 = makeEventLine('runtime_v2_prompt_activations_injected', {
+    sessionId: 's1',
+    workspaceDir: root,
+    principleIds: ['p1'],
+    activationIds: ['a1'],
+    artifactIds: ['f1'],
+    injectedCount: 1,
+    skippedWarnings: [],
+    injectedCharCount: 300,
+    budget: 2000,
+    v2Truncated: true,
+    crossBlockDuplicateIds: [],
+  });
+  const turn3 = makeEventLine('runtime_v2_prompt_activations_injected', {
+    sessionId: 's2',
+    workspaceDir: root,
+    principleIds: ['p3'],
+    activationIds: [],
+    artifactIds: [],
+    injectedCount: 0,
+    skippedWarnings: [],
+    injectedCharCount: 0,
+    budget: 2000,
+    skipReason: 'no_validated_activations',
+    nextAction: 'check activations table',
+  });
+  const unrelated = makeEventLine('some_other_event', { sessionId: 's9' });
+  const malformed = 'not-valid-json';
+
+  fs.mkdirSync(wsLogs(root), { recursive: true });
+  const todayFile = path.join(wsLogs(root), `events_${today}.jsonl`);
+  const yesterdayFile = path.join(wsLogs(root), `events_${yesterday}.jsonl`);
+  fs.writeFileSync(todayFile, [turn1, turn2, unrelated, malformed, ''].join('\n'), 'utf8');
+  fs.writeFileSync(yesterdayFile, [turn3, ''].join('\n'), 'utf8');
+
+  // Real production schema via the core connection bootstrap.
+  fs.mkdirSync(path.dirname(wsDb(root)), { recursive: true });
+  const connection = new SqliteConnection({ workspaceDir: root });
+  const db = connection.getDb();
+  insertRow(db, 'p1', 'presence', 'prompt_injected', 's1');
+  insertRow(db, 'p2', 'presence', 'prompt_injected', 's1');
+  insertRow(db, 'p3', 'presence', 'prompt_injected', 's2');
+  insertRow(db, 'p1', 'effect', 'self_reported', 's1');
+  insertRow(db, 'p1', 'effect', 'rule_blocked', null);
+  connection.close();
+  return root;
+}
+
+describe('pd principles stats — handler aggregation', () => {
+  let stdoutSpy: ReturnType<typeof vi.spyOn>;
+  let originalExitCode: number | undefined;
+  let stderrWriteSpy: ReturnType<typeof vi.spyOn>;
+  let workspaces: string[] = [];
+
+  beforeEach(() => {
+    stdoutSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    stderrWriteSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+    originalExitCode = process.exitCode;
+    process.exitCode = undefined;
+  });
+
+  afterEach(() => {
+    stdoutSpy.mockRestore();
+    stderrWriteSpy.mockRestore();
+    process.exitCode = originalExitCode;
+    for (const ws of workspaces) {
+      fs.rmSync(ws, { recursive: true, force: true });
+    }
+    workspaces = [];
+  });
+
+  function stdoutText(): string {
+    return stdoutSpy.mock.calls.map((c) => String(c[0])).join('');
+  }
+
+  function stderrText(): string {
+    return stderrWriteSpy.mock.calls.map((c) => String(c[0])).join('');
+  }
+
+  it('aggregates known fixture inputs into exact metrics (--json)', async () => {
+    const ws = makeFixtureWorkspace();
+    workspaces.push(ws);
+
+    await handlePrinciplesStats({ workspace: ws, json: true, days: 14 });
+
+    const parsed = JSON.parse(stdoutText()) as Record<string, unknown>;
+
+    expect(parsed.ok).toBe(true);
+    expect(parsed.status).toBe('ok');
+    expect(parsed.windowDays).toBe(14);
+
+    const coverage = parsed.coverage as Record<string, unknown>;
+    expect(coverage.eventsTurns).toBe(3); // turn1 + turn2 (today) + turn3 (yesterday)
+    expect(Array.isArray(coverage.eventsDaysFound)).toBe(true);
+    expect((coverage.eventsDaysFound as string[]).length).toBeGreaterThanOrEqual(1);
+
+    expect(parsed.sessions).toBe(2);
+    const injections = parsed.injections as Record<string, unknown>;
+    expect(injections.source).toBe('ledger');
+    expect(injections.avgDistinctPerSession).toBeCloseTo(1.5, 5); // s1:{p1,p2}=2, s2:{p3}=1
+    expect(injections.avgPerTurn).toBeCloseTo(4 / 3, 5); // 2+1+1 over 3 turns
+    expect(injections.distinctPrinciples).toBe(3);
+
+    const chars = parsed.chars as Record<string, unknown>;
+    expect(chars.avgV2PerTurn).toBeCloseTo(800 / 3, 5); // 500+300+0
+    expect(chars.avgLegacyPerTurn).toBeCloseTo(900, 5); // only turn1 reports legacy chars
+    expect(chars.turnsReporting).toBe(2);
+    expect(chars.v2TruncatedTurns).toBe(1);
+    expect(chars.legacyTruncatedTurns).toBe(0);
+    expect(chars.truncationRate).toBeCloseTo(0.5, 5);
+
+    const duplicates = parsed.duplicates as Record<string, unknown>;
+    expect(duplicates.crossBlockTotal).toBe(1);
+    expect(duplicates.crossBlockTop).toEqual([{ principleId: 'p2', count: 1 }]);
+    expect(duplicates.intraSessionRepeatShare).toBeCloseTo(1 / 3, 5); // p1 seen twice in s1
+
+    const correlation = parsed.applicationCorrelation as Record<string, unknown>;
+    expect(correlation.presenceRows).toBe(3);
+    expect(correlation.effectRows).toBe(2);
+    expect(correlation.correlatedPrinciples).toBeGreaterThanOrEqual(1);
+    const top = correlation.top as Array<Record<string, unknown>>;
+    expect(top[0].principleId).toBe('p1');
+
+    expect(process.exitCode).toBeUndefined();
+  });
+
+  it('degrades with nextAction on an empty workspace (cli-6)', async () => {
+    const ws = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-principles-stats-empty-'));
+    workspaces.push(ws);
+
+    await handlePrinciplesStats({ workspace: ws, json: true, days: 7 });
+
+    const parsed = JSON.parse(stdoutText()) as Record<string, unknown>;
+
+    expect(parsed.ok).toBe(true);
+    expect(parsed.status).toBe('degraded');
+    expect(parsed.sessions).toBe(0);
+    expect(typeof parsed.nextAction).toBe('string');
+    expect((parsed.nextAction as string).length).toBeGreaterThan(0);
+    const warnings = parsed.warnings as string[];
+    expect(warnings.some((w) => w.includes('event logs directory not found'))).toBe(true);
+  });
+
+  it('rejects --days 0 with structured reason + exit code 1 (cli-2/cli-6)', async () => {
+    await handlePrinciplesStats({ workspace: os.tmpdir(), json: true, days: 0 });
+
+    expect(process.exitCode).toBe(1);
+    expect(stderrText()).toContain('"reason"');
+    expect(stderrText()).toContain('"nextAction"');
+  });
+
+  it('tolerates a state.db without the receipt table (ledger degrades, events still reported)', async () => {
+    const ws = fs.mkdtempSync(path.join(os.tmpdir(), 'pd-principles-stats-nodb-'));
+    workspaces.push(ws);
+    fs.mkdirSync(wsLogs(ws), { recursive: true });
+    const today = utcDateString(new Date());
+    const event = makeEventLine('runtime_v2_prompt_activations_injected', {
+      sessionId: 'sx',
+      principleIds: ['px'],
+      injectedCount: 1,
+      skippedWarnings: [],
+      injectedCharCount: 120,
+      budget: 2000,
+      crossBlockDuplicateIds: [],
+    });
+    fs.writeFileSync(path.join(wsLogs(ws), `events_${today}.jsonl`), [event, ''].join('\n'), 'utf8');
+    // .pd exists but the DB has no principle_applications table.
+    fs.mkdirSync(path.dirname(wsDb(ws)), { recursive: true });
+    const db = new Database(wsDb(ws));
+    db.prepare('CREATE TABLE IF NOT EXISTS unrelated (id INTEGER PRIMARY KEY)').run();
+    db.close();
+
+    await handlePrinciplesStats({ workspace: ws, json: true, days: 7 });
+
+    const parsed = JSON.parse(stdoutText()) as Record<string, unknown>;
+    const coverage = parsed.coverage as Record<string, unknown>;
+    const injections = parsed.injections as Record<string, unknown>;
+
+    expect(parsed.ok).toBe(true);
+    expect(coverage.ledgerAvailable).toBe(false);
+    expect(injections.source).toBe('events');
+    expect(injections.avgDistinctPerSession).toBeCloseTo(1, 5);
+    const warnings = parsed.warnings as string[];
+    expect(warnings.some((w) => w.includes('ledger'))).toBe(true);
+  });
+});