@principles/pd-cli 1.152.12 → 1.152.14

package/src/commands/runtime-canary.ts

@@ -1,395 +0,0 @@
-import * as path from 'path';
-import { createRequire } from 'module';
-import { OperatorHealthReadModel, SchemaConformanceReadModel, PruningReadModel, createInternalizationQueueReadModel, auditCandidateLedgerConsistency, buildGfiWorkspaceSnapshot, classifyGfiWorkspaceHealth } from '@principles/core/runtime-v2';
-import type { OperatorHealthSnapshot, SchemaConformanceResult, OrphanDetectionResult, InternalizationQueueSnapshot, GfiWorkspaceSnapshot, CandidateAuditResult } from '@principles/core/runtime-v2';
-import { resolveWorkspaceDir } from '../resolve-workspace.js';
-import { loadPdConfig, computeFlagsFromLoadResult } from '../services/pd-config-loader.js';
-
-export interface CanaryCheck {
-  name: string;
-  status: 'healthy' | 'degraded' | 'error';
-  summary: string;
-  details?: unknown;
-  error?: string;
-}
-
-export interface CanaryOutput {
-  overallStatus: 'healthy' | 'degraded' | 'error';
-  checks: CanaryCheck[];
-  recommendedNextActions: string[];
-  generatedAt: string;
-  internalizationQueueSummary?: InternalizationQueueSummary;
-}
-
-const require = createRequire(import.meta.url);
-
-function readCliVersion(): string {
-  const packageMetadata: unknown = require('../../package.json');
-  if (typeof packageMetadata === 'object' && packageMetadata !== null && Object.hasOwn(packageMetadata, 'version')) {
-    const version: unknown = Reflect.get(packageMetadata, 'version');
-    if (typeof version === 'string') return version;
-  }
-  return 'unknown';
-}
-
-export interface InternalizationQueueSummary {
-  readyCount: number;
-  retryWaitCount: number;
-  pendingCount: number;
-  nextReadyTaskKind: string | null;
-  nextReadyTaskId: string | null;
-  noReadyReason: string | null;
-}
-
-interface CanaryOptions {
-  workspace?: string;
-  json?: boolean;
-}
-
-function computeOverallStatus(checks: CanaryCheck[]): 'healthy' | 'degraded' | 'error' {
-  let hasError = false;
-  let hasDegraded = false;
-  for (const check of checks) {
-    if (check.status === 'error') hasError = true;
-    if (check.status === 'degraded') hasDegraded = true;
-  }
-  if (hasError) return 'error';
-  if (hasDegraded) return 'degraded';
-  return 'healthy';
-}
-
-function buildRecommendedActions(checks: CanaryCheck[]): string[] {
-  const actions: string[] = [];
-  for (const check of checks) {
-    if (check.status === 'healthy') continue;
-    switch (check.name) {
-      case 'schema_conformance':
-        actions.push('Run workspace initialization to migrate schema: open DB with writable SqliteConnection.');
-        break;
-      case 'candidate_audit':
-        actions.push('Run `pd candidate audit --workspace <path> --json` for details.');
-        break;
-      case 'gfi_snapshot': {
-        const gfiDetails = check.details as { warnings?: string[]; configPath?: string } | undefined;
-        if (gfiDetails && gfiDetails.warnings && gfiDetails.warnings.length > 0) {
-          actions.push(`Review .pd/config.yaml and rerun \`pd runtime features --workspace <path> --json\`.`);
-        } else {
-          actions.push('Investigate GFI sessions — consider cleanup or session lifecycle review.');
-        }
-        break;
-      }
-      case 'pruning_orphans':
-        actions.push('Run `pd runtime pruning orphans --workspace <path> --dry-run` to inspect orphan candidates.');
-        break;
-      case 'internalization_queue': {
-        const queueDetails = check.details as InternalizationQueueSnapshot | undefined;
-        if (queueDetails && queueDetails.noReadyTasks?.reason === 'no_candidates' && queueDetails.noReadyTasks.inspectedCount === 0) {
-          actions.push('No internalization tasks found. If candidates exist, run `pd candidate internalization backfill --dry-run` to check, then `--confirm` to create dreamer tasks.');
-        } else {
-          actions.push('Check internalization queue for blocked or dependency-failed tasks.');
-        }
-        break;
-      }
-      case 'runtime_health': {
-        const details = check.details as OperatorHealthSnapshot | undefined;
-        if (details && details.totalTaskCount === 0) {
-          actions.push('Runtime V2 pipeline has never been exercised. Run `pd pain record --reason "test" --workspace <path>` to trigger the pain-to-principle chain.');
-        } else if (details && details.painChain.lastSuccessfulChain === null) {
-          actions.push('Run `pd runtime uat --workspace <path> --count 3` to establish baseline.');
-        } else {
-          actions.push('Review runtime health snapshot for specific failure categories.');
-        }
-        break;
-      }
-      case 'pd_shim_info':
-        actions.push('Verify pd CLI installation and sync-plugin configuration.');
-        break;
-    }
-  }
-  return actions;
-}
-
-export async function runCanaryChecks(workspaceDir: string): Promise<CanaryOutput> {
-  const generatedAt = new Date().toISOString();
-
-  // Single canonical config load — shared across gfi_snapshot and internalization_queue checks (PRI-460).
-  const pdConfigResult = loadPdConfig(workspaceDir);
-  const pdFlags = computeFlagsFromLoadResult(pdConfigResult);
-
-  const checkPromises: Promise<CanaryCheck>[] = [
-    (async (): Promise<CanaryCheck> => {
-      try {
-        const model = new SchemaConformanceReadModel({ workspaceDir });
-        const result: SchemaConformanceResult = model.check();
-        const status = result.overallStatus === 'ok' ? 'healthy' : result.overallStatus === 'degraded' ? 'degraded' : 'error';
-        const missingCount = Object.values(result.tables).filter(t => !t.exists || t.missingColumns.length > 0).length;
-        return {
-          name: 'schema_conformance',
-          status,
-          summary: status === 'healthy'
-            ? 'All tables and columns conform to expected schema.'
-            : `${missingCount} table(s) have missing columns or do not exist. Migrations needed: ${result.migrationsNeeded.join(', ')}`,
-          details: result,
-        };
-      } catch (err) {
-        return { name: 'schema_conformance', status: 'error', summary: 'Schema conformance check failed.', error: String(err) };
-      }
-    })(),
-    (async (): Promise<CanaryCheck> => {
-      try {
-        const result: CandidateAuditResult = await auditCandidateLedgerConsistency(workspaceDir);
-        const status = result.status === 'ok' ? 'healthy' : result.status === 'degraded' ? 'degraded' : 'error';
-        return {
-          name: 'candidate_audit',
-          status,
-          summary: status === 'healthy'
-            ? 'Candidate/ledger consistency OK.'
-            : `Audit status: ${result.status}. Orphan candidates: ${result.orphanCandidateCount}, Missing ledger: ${result.missingLedgerCount}`,
-          details: result,
-        };
-      } catch (err) {
-        return { name: 'candidate_audit', status: 'error', summary: 'Candidate audit check failed.', error: String(err) };
-      }
-    })(),
-    (async (): Promise<CanaryCheck> => {
-      try {
-        const gfiFlag = pdFlags.flags.gfi;
-        if (!gfiFlag || !gfiFlag.enabled) {
-          if (pdFlags.warnings.length > 0) {
-            return {
-              name: 'gfi_snapshot',
-              status: 'degraded',
-              summary: `GFI disabled but config has warnings: ${pdFlags.warnings.join('; ')}`,
-              details: { warnings: pdFlags.warnings, configPath: pdConfigResult.configPath },
-            };
-          }
-          return {
-            name: 'gfi_snapshot',
-            status: 'healthy',
-            summary: 'GFI feature flag disabled — skipping snapshot.',
-          };
-        }
-        const sessionDir = path.join(workspaceDir, '.state', 'sessions');
-        const fs = await import('fs');
-        const sessions: { sessionId: string; currentGfi: number; lastActivityAt: number; consecutiveErrors: number }[] = [];
-        if (fs.existsSync(sessionDir)) {
-          for (const file of fs.readdirSync(sessionDir)) {
-            if (!file.endsWith('.json')) continue;
-            try {
-              const raw = fs.readFileSync(path.join(sessionDir, file), 'utf8');
-              const parsed = JSON.parse(raw);
-              if (parsed?.sessionId) {
-                sessions.push({
-                  sessionId: parsed.sessionId,
-                  currentGfi: parsed.currentGfi ?? 0,
-                  lastActivityAt: parsed.lastActivityAt ?? parsed.lastControlActivityAt ?? 0,
-                  consecutiveErrors: parsed.consecutiveErrors ?? 0,
-                });
-              }
-            } catch { /* skip malformed */ }
-          }
-        }
-        const snapshot: GfiWorkspaceSnapshot = buildGfiWorkspaceSnapshot({ sessions, nowMs: Date.now() });
-        const health = classifyGfiWorkspaceHealth(snapshot);
-        const {status} = health;
-        return {
-          name: 'gfi_snapshot',
-          status,
-          summary: status === 'healthy'
-            ? `GFI snapshot OK. ${snapshot.activeSessionCount} active, ${snapshot.staleSessionCount} stale sessions.`
-            : `GFI degraded: ${health.reason}`,
-          details: { ...snapshot, healthAssessment: health },
-        };
-      } catch (err) {
-        return { name: 'gfi_snapshot', status: 'error', summary: 'GFI snapshot check failed.', error: String(err) };
-      }
-    })(),
-    (async (): Promise<CanaryCheck> => {
-      try {
-        const model = new PruningReadModel({ workspaceDir });
-        const result: OrphanDetectionResult = model.getOrphanDerivedCandidates();
-        const status = result.candidates.length > 0 ? 'degraded' : 'healthy';
-        return {
-          name: 'pruning_orphans',
-          status,
-          summary: status === 'healthy'
-            ? 'No orphan derived candidates found.'
-            : `${result.candidates.length} orphan derived candidate(s) found. dbReadable: ${result.dbReadable}`,
-          details: { orphanDerivedCandidateCount: result.candidates.length, dbReadable: result.dbReadable, samples: result.candidates.slice(0, 5) },
-        };
-      } catch (err) {
-        return { name: 'pruning_orphans', status: 'error', summary: 'Pruning orphan check failed.', error: String(err) };
-      }
-    })(),
-    (async (): Promise<CanaryCheck> => {
-      try {
-        const enabledChannels = new Set(pdFlags.enabledChannels);
-        const { readModel, close } = await createInternalizationQueueReadModel({ workspaceDir, readonly: true, enabledChannels });
-        try {
-          const snapshot: InternalizationQueueSnapshot = await readModel.getSnapshot();
-          const hasBlocked = snapshot.blockedSummary.count > 0;
-          const hasDepFailed = snapshot.dependencyFailedSummary.count > 0;
-          const hasInvalid = snapshot.invalidMetadataCount > 0;
-          const hasLeaseConflicts = snapshot.leaseConflictSummary.count > 0;
-          // Suppressed tasks (disabled channels / non-MVP kinds) do NOT degrade health
-          const status = (hasBlocked || hasDepFailed || hasInvalid || hasLeaseConflicts) ? 'degraded' : 'healthy';
-          const suppressedNote = snapshot.suppressedTasks.length > 0
-            ? ` (${snapshot.suppressedTasks.length} suppressed non-MVP)`
-            : '';
-          return {
-            name: 'internalization_queue',
-            status,
-            summary: status === 'healthy'
-              ? `Queue OK. ${snapshot.readyTasks.length} ready, ${snapshot.pendingCount} pending, ${snapshot.retryWaitCount} retry_wait${suppressedNote}.`
-              : `Queue degraded: ${snapshot.blockedSummary.count} blocked, ${snapshot.dependencyFailedSummary.count} dep-failed, ${snapshot.invalidMetadataCount} invalid metadata, ${snapshot.leaseConflictSummary.count} lease conflicts${suppressedNote}.`,
-            details: snapshot,
-          };
-        } finally {
-          await close();
-        }
-      } catch (err) {
-        return { name: 'internalization_queue', status: 'error', summary: 'Internalization queue check failed.', error: String(err) };
-      }
-    })(),
-    (async (): Promise<CanaryCheck> => {
-      try {
-        const model = new OperatorHealthReadModel({ workspaceDir });
-        try {
-          const snapshot: OperatorHealthSnapshot = await model.getSnapshot();
-          // Priority: real errors (e.g. DB missing) must surface as 'error' and not be
-          // masked by the cold-start `totalTaskCount === 0` branch, which is only a
-          // 'degraded' signal. Check overallStatus==='error' first, then unexercised,
-          // then healthy/degraded.
-          const status = snapshot.overallStatus === 'error'
-            ? 'error'
-            : snapshot.totalTaskCount === 0
-            ? 'degraded'
-            : snapshot.overallStatus === 'healthy' ? 'healthy' : 'degraded';
-          return {
-            name: 'runtime_health',
-            status,
-            summary: snapshot.overallStatus === 'error'
-              ? `Runtime health: ${snapshot.overallStatus}. Actions: ${snapshot.recommendedActions.join('; ')}`
-              : snapshot.totalTaskCount === 0
-              ? 'Runtime pipeline has not been exercised yet.'
-              : status === 'healthy'
-              ? 'Runtime health OK.'
-              : `Runtime health: ${snapshot.overallStatus}. Actions: ${snapshot.recommendedActions.join('; ')}`,
-            details: snapshot,
-          };
-        } finally {
-          await model.close();
-        }
-      } catch (err) {
-        return { name: 'runtime_health', status: 'error', summary: 'Runtime health check failed.', error: String(err) };
-      }
-    })(),
-    (async (): Promise<CanaryCheck> => {
-      try {
-        const fs = await import('fs');
-        const cliPath = path.resolve(process.argv[1] ?? '');
-        const cliExists = fs.existsSync(cliPath);
-        const status = cliExists ? 'healthy' : 'degraded';
-        return {
-          name: 'pd_shim_info',
-          status,
-          summary: status === 'healthy'
-            ? `PD CLI accessible at ${cliPath}`
-            : 'PD CLI entrypoint not found — verify installation.',
-          details: { cliPath, exists: cliExists, version: readCliVersion() },
-        };
-      } catch (err) {
-        return { name: 'pd_shim_info', status: 'error', summary: 'PD shim check failed.', error: String(err) };
-      }
-    })(),
-  ];
-
-  const checkResults = await Promise.allSettled(checkPromises);
-  const checks: CanaryCheck[] = checkResults.map((result, index) => {
-    if (result.status === 'fulfilled') return result.value;
-    return {
-      name: `check_${index}`,
-      status: 'error' as const,
-      summary: 'Check failed unexpectedly.',
-      error: result.reason ? String(result.reason) : 'Unknown error',
-    };
-  });
-
-  const overallStatus = computeOverallStatus(checks);
-  const recommendedNextActions = buildRecommendedActions(checks);
-
-  const internalizationQueueCheck = checks.find(c => c.name === 'internalization_queue');
-  const internalizationQueueSummary: InternalizationQueueSummary | undefined =
-    internalizationQueueCheck && internalizationQueueCheck.details
-      ? (() => {
-          const snapshot = internalizationQueueCheck.details as InternalizationQueueSnapshot;
-          const firstReady = snapshot.readyTasks[0] ?? null;
-          return {
-            readyCount: snapshot.readyTasks.length,
-            retryWaitCount: snapshot.retryWaitCount,
-            pendingCount: snapshot.pendingCount,
-            nextReadyTaskKind: firstReady ? firstReady.taskKind : null,
-            nextReadyTaskId: firstReady ? firstReady.taskId : null,
-            noReadyReason: snapshot.noReadyTasks?.reason ?? null,
-          };
-        })()
-      : undefined;
-
-  return {
-    overallStatus,
-    checks,
-    recommendedNextActions,
-    generatedAt,
-    ...(internalizationQueueSummary ? { internalizationQueueSummary } : {}),
-  };
-}
-
-function formatTextOutput(output: CanaryOutput): string {
-  const lines: string[] = [];
-  const icon = output.overallStatus === 'healthy' ? '✓' : '✗';
-
-  lines.push('PD Control Plane Canary');
-  lines.push(`generatedAt: ${output.generatedAt}`);
-  lines.push(`OVERALL: ${icon} ${output.overallStatus.toUpperCase()}`);
-  lines.push('');
-
-  for (const check of output.checks) {
-    const checkIcon = check.status === 'healthy' ? '✓' : check.status === 'degraded' ? '⚠' : '✗';
-    lines.push(`  ${checkIcon} ${check.name}: ${check.summary}`);
-    if (check.error) {
-      lines.push(`    error: ${check.error}`);
-    }
-  }
-
-  if (output.recommendedNextActions.length > 0) {
-    lines.push('');
-    lines.push('Recommended next actions:');
-    for (const action of output.recommendedNextActions) {
-      lines.push(`  [!] ${action}`);
-    }
-  }
-
-  return lines.join('\n');
-}
-
-export async function handleRuntimeCanary(opts: CanaryOptions): Promise<void> {
-  const workspaceDir = opts.workspace
-    ? path.resolve(opts.workspace)
-    : resolveWorkspaceDir();
-
-  const output = await runCanaryChecks(workspaceDir);
-
-  if (opts.json) {
-    console.log(JSON.stringify(output, null, 2));
-  } else {
-    console.log(formatTextOutput(output));
-  }
-
-  if (output.overallStatus !== 'healthy') {
-    if (!opts.json) {
-      console.error('');
-      console.error(`FAIL: overallStatus=${output.overallStatus}`);
-    }
-    process.exitCode = 1;
-  }
-}

package/src/commands/runtime-compatibility-scan.ts

@@ -1,105 +0,0 @@
-/**
- * pd runtime compatibility-scan — scan active RuleCode for retired
- * RuleHost contract dependencies (2026-08-19).
- *
- * Read-only operator command and the installer's upgrade preflight entry
- * point. Loads ACTIVE code_tool_hook activations (activations ⋈ pi_artifacts
- * from .pd/state.db) and reports every rule whose implementationCode still
- * references a contract symbol this runtime removed (recentThinking,
- * planStatus, hasPlanFile, getPlanStatus(), hasPlanFile()).
- *
- * Output contract (cli-1 strict-json, cli-5 no mutation, cli-6 nextAction):
- * - --json emits exactly one parseable JSON object on stdout.
- * - clean / no_state_db → exit 0; legacy_dependency / scan_failed → exit 1
- *   with reason + nextAction. The command never writes to the workspace.
- *
- * ERR refs: ERR-001/ERR-005 (rows validated from unknown), ERR-002 (every
- * refusal carries reason + nextAction), ERR-014 (bounded JSON output of
- * known shapes).
- */
-
-import * as path from 'path';
-import type { Command } from 'commander';
-import {
-  ActivationCompatibilityReadModel,
-  formatLegacyRuleContractRemediation,
-  type ActivationCompatibilityScanResult,
-  type LegacyRuleContractFinding,
-} from '@principles/core/runtime-v2';
-import { resolveWorkspaceDir } from '../resolve-workspace.js';
-import { emitResult, emitError } from '../services/cli-output.js';
-
-function formatFinding(f: LegacyRuleContractFinding): string {
-  const rule = f.ruleId ?? f.artifactId;
-  const activation = f.activationId ? ` (activation ${f.activationId})` : '';
-  return `  ${rule}${activation}: ${f.symbol}`;
-}
-
-function formatTextOutput(output: ActivationCompatibilityScanResult): string {
-  const lines: string[] = [];
-  lines.push('PD Runtime Compatibility Scan');
-  lines.push(`workspace: ${output.workspaceDir}`);
-  lines.push(`status: ${output.status}`);
-  lines.push(`scannedActivations: ${output.scannedActivations}`);
-  lines.push('');
-  if (output.findings.length > 0) {
-    lines.push('Retired-contract dependencies (these rules will NOT execute on this runtime):');
-    for (const f of output.findings) lines.push(formatFinding(f));
-  } else {
-    lines.push('No active rule references a retired RuleHost contract symbol.');
-  }
-  if (output.reason) lines.push(`reason: ${output.reason}`);
-  if (output.nextAction) lines.push(`nextAction: ${output.nextAction}`);
-  return lines.join('\n');
-}
-
-export interface RuntimeCompatibilityScanOptions {
-  workspace?: string;
-  json?: boolean;
-}
-
-export async function handleRuntimeCompatibilityScan(opts: RuntimeCompatibilityScanOptions): Promise<void> {
-  const workspaceDir = opts.workspace
-    ? path.resolve(opts.workspace)
-    : resolveWorkspaceDir();
-
-  try {
-    const output = new ActivationCompatibilityReadModel({ workspaceDir }).scan();
-    if (output.status === 'legacy_dependency') {
-      // Surface the full remediation text in the payload (cli-6) while
-      // keeping --json a single parseable object.
-      const enriched = { ...output, remediation: formatLegacyRuleContractRemediation(output.findings) };
-      emitResult(enriched, { json: opts.json ?? false, formatText: formatTextOutput });
-      process.exitCode = 1; // cli-2: exit code only, no process.exit()
-      return;
-    }
-    emitResult(output, { json: opts.json ?? false, formatText: formatTextOutput });
-    if (!output.ok) {
-      process.exitCode = 1;
-    }
-  } catch (err) {
-    process.exitCode = emitError(err, {
-      json: opts.json ?? false,
-      nextAction: 'Check workspace directory and permissions, then retry.',
-    });
-  }
-}
-
-/**
- * Register the compatibility-scan subcommand on the `pd runtime` command
- * group. Exported so parser-level wiring tests exercise the same
- * registration index.ts uses (cli-7).
- */
-export function registerRuntimeCompatibilityScanCommand(runtimeCmd: Command): void {
-  runtimeCmd
-    .command('compatibility-scan', { hidden: true })
-    .description('Scan active RuleCode for retired RuleHost contract dependencies (read-only; used by the installer upgrade preflight)')
-    .option('-w, --workspace <path>', 'Workspace directory')
-    .option('--json', 'Output raw JSON')
-    .action(async (opts: { workspace?: string; json?: boolean }) => {
-      await handleRuntimeCompatibilityScan({
-        workspace: opts.workspace,
-        json: opts.json === true,
-      });
-    });
-}