principles-disciple 1.10.0 → 1.12.0

package/src/service/nocturnal-service.ts

@@ -31,20 +31,18 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { randomUUID } from 'crypto';
+import type { RecentPainContext } from './evolution-worker.js';
 import {
-  NocturnalTrajectoryExtractor,
   createNocturnalTrajectoryExtractor,
   computeThinkingModelDelta,
   type NocturnalSessionSnapshot,
 } from '../core/nocturnal-trajectory-extractor.js';
 import {
   NocturnalTargetSelector,
-  selectNocturnalTarget,
   type NocturnalSelectionResult,
   type SkipReason,
 } from './nocturnal-target-selector.js';
 import {
-  validateArtifact,
   parseAndValidateArtifact,
   validateTrinityDraft,
   type NocturnalArtifact,
@@ -69,7 +67,29 @@ import {
   type ThresholdSignals,
 } from '../core/adaptive-thresholds.js';
 import {
-  checkWorkspaceIdle,
+  parseArtificerOutput,
+  resolveArtificerTargetRule,
+  shouldRunArtificer,
+  type ArtificerOutput,
+  type ArtificerTargetRuleResolution,
+} from '../core/nocturnal-artificer.js';
+import { validateRuleImplementationCandidate } from '../core/nocturnal-rule-implementation-validator.js';
+import { refreshPrincipleLifecycle } from '../core/principle-internalization/lifecycle-refresh.js';
+import {
+  createImplementationAssetDir,
+  deleteImplementationAssetDir,
+  getImplementationAssetRoot,
+  type CodeImplementationLineageMetadata,
+} from '../core/code-implementation-storage.js';
+import {
+  appendCandidateArtifactLineageRecord,
+  appendArtifactLineageRecord,
+} from '../core/nocturnal-artifact-lineage.js';
+import {
+  createImplementation,
+  deleteImplementation,
+} from '../core/principle-tree-ledger.js';
+import {
   checkPreflight,
   recordRunStart,
   recordRunEnd,
@@ -78,6 +98,7 @@ import {
 } from './nocturnal-runtime.js';
 import { NocturnalPathResolver } from '../core/nocturnal-paths.js';
 import { registerSample } from '../core/nocturnal-dataset.js';
+import type { Implementation } from '../types/principle-tree-schema.js';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -131,6 +152,27 @@ export interface NocturnalRunDiagnostics {
   persisted: boolean;
   /** Persistence path (if persisted) */
   persistedPath?: string;
+  /** Code-candidate sidecar diagnostics */
+  artificer: NocturnalArtificerDiagnostics;
+}
+
+export interface NocturnalArtificerDiagnostics {
+  status: 'skipped' | 'validation_failed' | 'persisted_candidate';
+  reason?:
+    | 'behavioral_artifact_unavailable'
+    | 'no_deterministic_rule'
+    | 'insufficient_signal_density'
+    | 'missing_scribe_input'
+    | 'parse_failed'
+    | 'rule_mismatch'
+    | 'validator_rejected'
+    | 'persistence_failed';
+  ruleResolution: ArtificerTargetRuleResolution | null;
+  validationFailures: string[];
+  implementationId?: string;
+  artifactId?: string;
+  ruleId?: string;
+  persistedPath?: string;
 }
 
 /**
@@ -179,7 +221,27 @@ export interface NocturnalServiceOptions {
    * When provided, the target selector uses it for ranking bias and diagnostics enrichment.
    * This threads recent pain signals into sleep_reflection targeting without merging task kinds.
    */
-  painContext?: import('../service/evolution-worker.js').RecentPainContext;
+  painContext?: RecentPainContext;
+
+  /**
+   * Override the principleId (skip Selector stage).
+   * When provided with snapshotOverride, the Selector stage is skipped and the provided
+   * principleId and snapshot are used directly for Trinity execution.
+   * This unifies NocturnalWorkflowManager with executeNocturnalReflectionAsync.
+   */
+  principleIdOverride?: string;
+
+  /**
+   * Override the snapshot (skip Selector stage).
+   * Must be provided together with principleIdOverride to skip Selector.
+   */
+  snapshotOverride?: NocturnalSessionSnapshot;
+
+  /**
+   * Override the Artificer JSON output (for testing).
+   * When omitted, a deterministic local candidate is synthesized.
+   */
+  artificerOutputOverride?: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -209,8 +271,11 @@ function invokeStubReflector(
   const hasGateBlocks = snapshot.stats.totalGateBlocks > 0;
 
   // Detect what kind of signal is available and craft appropriate artifact
+  // eslint-disable-next-line @typescript-eslint/init-declarations -- assigned in all if/else branches
   let badDecision: string;
+  // eslint-disable-next-line @typescript-eslint/init-declarations -- assigned in all if/else branches
   let betterDecision: string;
+  // eslint-disable-next-line @typescript-eslint/init-declarations -- assigned in all if/else branches
   let rationale: string;
 
   if (hasGateBlocks) {
@@ -283,6 +348,272 @@ function persistArtifact(
   return artifactPath;
 }
 
+function buildPainRefs(snapshot: NocturnalSessionSnapshot): string[] {
+  return snapshot.painEvents.map(
+    (painEvent) =>
+      `pain:${painEvent.source}:${painEvent.createdAt}:${(painEvent.reason ?? '').trim()}`
+  );
+}
+
+function buildGateBlockRefs(snapshot: NocturnalSessionSnapshot): string[] {
+  return snapshot.gateBlocks.map(
+    (gateBlock) =>
+      `gate:${gateBlock.toolName}:${gateBlock.createdAt}:${gateBlock.reason.trim()}`
+  );
+}
+
+/* eslint-disable @typescript-eslint/max-params -- Reason: Function signature requires all parameters for type-safe artifact construction */
+function buildDefaultArtificerOutput(
+  ruleId: string,
+  artifact: NocturnalArtifact,
+  sourceSnapshotRef: string,
+  sourcePainIds: string[],
+  sourceGateBlockIds: string[]
+): ArtificerOutput {
+  return {
+    ruleId,
+    implementationType: 'code',
+    candidateSource: [
+      'export const meta = {',
+      `  name: ${JSON.stringify(`nocturnal-${ruleId.toLowerCase()}`)},`,
+      '  version: "1.0.0",',
+      `  ruleId: ${JSON.stringify(ruleId)},`,
+      `  coversCondition: ${JSON.stringify(artifact.betterDecision)},`,
+      '};',
+      '',
+      'export function evaluate(input, helpers) {',
+      '  const riskPath = helpers.isRiskPath();',
+      '  const toolName = helpers.getToolName();',
+      '  const planStatus = helpers.getPlanStatus();',
+      "  if (riskPath && toolName === 'write' && planStatus !== 'READY') {",
+      '    return {',
+      "      decision: 'requireApproval',",
+      '      matched: true,',
+      `      reason: ${JSON.stringify(artifact.rationale)},`,
+      '    };',
+      '  }',
+      '  return {',
+      "    decision: 'allow',",
+      '    matched: false,',
+      "    reason: 'not-applicable',",
+      '  };',
+      '}',
+    ].join('\n'),
+    helperUsage: ['isRiskPath', 'getToolName', 'getPlanStatus'],
+    expectedDecision: 'requireApproval',
+    rationale: artifact.rationale,
+    lineage: {
+      artifactKind: 'rule-implementation-candidate',
+      sourceSnapshotRef,
+      sourcePainIds,
+      sourceGateBlockIds,
+    },
+  };
+}
+
+/* eslint-disable @typescript-eslint/max-params -- Reason: Function signature requires all parameters for type-safe candidate persistence */
+function persistCodeCandidate(
+  workspaceDir: string,
+  stateDir: string,
+  artifact: NocturnalArtifact,
+  selectedPrincipleId: string,
+  selectedSessionId: string,
+  parsedArtificer: ArtificerOutput
+): NocturnalArtificerDiagnostics {
+  const implementationId = `IMPL-${randomUUID()}`;
+  const artifactId = `artifact-${randomUUID()}`;
+  const now = new Date().toISOString();
+  const assetRoot = getImplementationAssetRoot(stateDir, implementationId);
+  const entryPath = path.join(assetRoot, 'entry.js');
+  const lineage: CodeImplementationLineageMetadata = {
+    principleId: selectedPrincipleId,
+    ruleId: parsedArtificer.ruleId,
+    sourceSnapshotRef: artifact.sourceSnapshotRef,
+    sourcePainIds: [...parsedArtificer.lineage.sourcePainIds],
+    sourceGateBlockIds: [...parsedArtificer.lineage.sourceGateBlockIds],
+    sourceSessionId: selectedSessionId,
+    artificerArtifactId: artifactId,
+  };
+
+  const implementation: Implementation = {
+    id: implementationId,
+    ruleId: parsedArtificer.ruleId,
+    type: 'code',
+    path: entryPath,
+    version: now,
+    coversCondition: parsedArtificer.rationale,
+    coveragePercentage: 0,
+    lifecycleState: 'candidate',
+    createdAt: now,
+    updatedAt: now,
+  };
+
+  try {
+    createImplementation(stateDir, implementation);
+    createImplementationAssetDir(stateDir, implementationId, now, {
+      entrySource: parsedArtificer.candidateSource,
+      lineage,
+    });
+    appendCandidateArtifactLineageRecord(workspaceDir, {
+      artifactId,
+      principleId: selectedPrincipleId,
+      ruleId: parsedArtificer.ruleId,
+      sessionId: selectedSessionId,
+      sourceSnapshotRef: artifact.sourceSnapshotRef,
+      sourcePainIds: lineage.sourcePainIds,
+      sourceGateBlockIds: lineage.sourceGateBlockIds,
+      storagePath: assetRoot,
+      implementationId,
+      createdAt: now,
+    });
+    refreshPrincipleLifecycle(workspaceDir, stateDir);
+    return {
+      status: 'persisted_candidate',
+      ruleResolution: {
+        status: 'selected',
+        ruleId: parsedArtificer.ruleId,
+        reason: 'evidence-winner',
+        scores: [],
+      },
+      validationFailures: [],
+      implementationId,
+      artifactId,
+      ruleId: parsedArtificer.ruleId,
+      persistedPath: assetRoot,
+    };
+  } catch (error: unknown) {
+    deleteImplementationAssetDir(stateDir, implementationId);
+    try {
+      deleteImplementation(stateDir, implementationId);
+    } catch {
+      // Best effort cleanup to avoid leaving a half-created candidate discoverable.
+    }
+    return {
+      status: 'validation_failed',
+      reason: 'persistence_failed',
+      ruleResolution: {
+        status: 'selected',
+        ruleId: parsedArtificer.ruleId,
+        reason: 'evidence-winner',
+        scores: [],
+      },
+      validationFailures: [String(error)],
+      ruleId: parsedArtificer.ruleId,
+    };
+  }
+}
+
+/* eslint-disable @typescript-eslint/max-params -- Reason: Function signature requires all parameters for type-safe candidate persistence */
+function maybePersistArtificerCandidate(
+  workspaceDir: string,
+  stateDir: string,
+  selectedPrincipleId: string,
+  selectedSessionId: string,
+  snapshot: NocturnalSessionSnapshot,
+  artifact: NocturnalArtifact,
+  options: NocturnalServiceOptions
+): NocturnalArtificerDiagnostics {
+  const ruleResolution = resolveArtificerTargetRule(
+    stateDir,
+    selectedPrincipleId,
+    snapshot
+  );
+
+  if (ruleResolution.status !== 'selected') {
+    return {
+      status: 'skipped',
+      reason: 'no_deterministic_rule',
+      ruleResolution,
+      validationFailures: [],
+    };
+  }
+
+  // #219: Detect fallback data source and warn about potential signal inaccuracy
+  const validationFailures: string[] = [];
+  if (snapshot._dataSource === 'pain_context_fallback') {
+    validationFailures.push('fallback_snapshot: stats derived from pain context only (trajectory extractor failed) - signal counts may be undercounted');
+  }
+
+  if (!shouldRunArtificer(snapshot, ruleResolution)) {
+    return {
+      status: 'skipped',
+      reason: 'insufficient_signal_density',
+      ruleResolution,
+      validationFailures,
+      ruleId: ruleResolution.ruleId,
+    };
+  }
+
+  if (!artifact.betterDecision || !artifact.rationale) {
+    return {
+      status: 'skipped',
+      reason: 'missing_scribe_input',
+      ruleResolution,
+      validationFailures: [],
+      ruleId: ruleResolution.ruleId,
+    };
+  }
+
+  const sourcePainIds = buildPainRefs(snapshot);
+  const sourceGateBlockIds = buildGateBlockRefs(snapshot);
+  const parsedArtificer =
+    options.artificerOutputOverride !== undefined
+      ? parseArtificerOutput(options.artificerOutputOverride)
+      : buildDefaultArtificerOutput(
+          ruleResolution.ruleId,
+          artifact,
+          artifact.sourceSnapshotRef,
+          sourcePainIds,
+          sourceGateBlockIds
+        );
+
+  if (!parsedArtificer) {
+    return {
+      status: 'validation_failed',
+      reason: 'parse_failed',
+      ruleResolution,
+      validationFailures: ['Artificer output could not be parsed.'],
+      ruleId: ruleResolution.ruleId,
+    };
+  }
+
+  if (parsedArtificer.ruleId !== ruleResolution.ruleId) {
+    return {
+      status: 'validation_failed',
+      reason: 'rule_mismatch',
+      ruleResolution,
+      validationFailures: [
+        `Resolved rule ${ruleResolution.ruleId} did not match candidate rule ${parsedArtificer.ruleId}.`,
+      ],
+      ruleId: ruleResolution.ruleId,
+    };
+  }
+
+  const validation = validateRuleImplementationCandidate(parsedArtificer.candidateSource);
+  if (!validation.passed) {
+    return {
+      status: 'validation_failed',
+      reason: 'validator_rejected',
+      ruleResolution,
+      validationFailures: validation.failures.map((failure) => failure.message),
+      ruleId: ruleResolution.ruleId,
+    };
+  }
+
+  const persisted = persistCodeCandidate(
+    workspaceDir,
+    stateDir,
+    artifact,
+    selectedPrincipleId,
+    selectedSessionId,
+    parsedArtificer
+  );
+  return {
+    ...persisted,
+    ruleResolution,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Main Orchestrator
 // ---------------------------------------------------------------------------
@@ -320,6 +651,11 @@ export function executeNocturnalReflection(
     arbiterResult: null,
     executabilityResult: null,
     persisted: false,
+    artificer: {
+      status: 'skipped',
+      ruleResolution: null,
+      validationFailures: [],
+    },
   };
 
   // -------------------------------------------------------------------------
@@ -407,10 +743,11 @@ export function executeNocturnalReflection(
   // -------------------------------------------------------------------------
   // Step 5: Artifact generation (Trinity or single-reflector)
   // -------------------------------------------------------------------------
+  // eslint-disable-next-line no-useless-assignment -- Reason: initial value unused due to immediate reassignment in all branches
   let trinityArtifact: TrinityDraftArtifact | null = null;
   let trinityResult: TrinityResult | null = null;
+  // eslint-disable-next-line @typescript-eslint/init-declarations -- assigned in all branches before use at line 884
   let rawJson: string;
-  let chainModeUsed: 'trinity' | 'single-reflector' = 'single-reflector';
 
   if (options.skipReflector) {
     // Caller provided explicit artifact — used for testing arbiter/executability
@@ -430,7 +767,6 @@ export function executeNocturnalReflection(
     diagnostics.trinityAttempted = true;
     diagnostics.trinityResult = trinityResult;
     diagnostics.chainModeUsed = trinityResult.success ? 'trinity' : 'single-reflector';
-    chainModeUsed = trinityResult.success ? 'trinity' : 'single-reflector';
 
     if (!trinityResult.success) {
       // Trinity failed — fail closed (same semantics as production)
@@ -457,7 +793,7 @@ export function executeNocturnalReflection(
       // Validate Trinity draft
       const draftValidation = validateTrinityDraft(trinityResult.artifact);
       if (!draftValidation.valid) {
-        const failures = draftValidation.failures;
+        const {failures} = draftValidation;
         void recordRunEnd(stateDir, 'failed', { reason: `Trinity draft invalid: ${failures.join('; ')}` }).catch((err) => {
           console.warn(`[nocturnal-service] Failed to record run end: ${String(err)}`);
         });
@@ -477,7 +813,7 @@ export function executeNocturnalReflection(
           diagnostics,
         };
       }
-      trinityArtifact = trinityResult.artifact!;
+      trinityArtifact = trinityResult.artifact!; // eslint-disable-line @typescript-eslint/no-non-null-assertion -- Reason: artifact is validated by validateTrinityDraft which returns valid: true when artifact exists
       // Convert Trinity draft to arbiter-compatible artifact
       const artifactData = draftToArtifact(trinityArtifact);
       rawJson = JSON.stringify(artifactData);
@@ -502,14 +838,13 @@ export function executeNocturnalReflection(
       trinityResult = runTrinity({ snapshot, principleId: selectedPrincipleId, config: effectiveConfig });
       diagnostics.trinityResult = trinityResult;
       diagnostics.chainModeUsed = trinityResult.success ? 'trinity' : 'single-reflector';
-      chainModeUsed = trinityResult.success ? 'trinity' : 'single-reflector';
 
       if (trinityResult.success) {
         // Validate Trinity draft
         const draftValidation = validateTrinityDraft(trinityResult.artifact);
         if (!draftValidation.valid) {
           // Trinity draft invalid — fail closed
-          const failures = draftValidation.failures;
+          const {failures} = draftValidation;
           void recordRunEnd(stateDir, 'failed', { reason: `Trinity draft invalid: ${failures.join('; ')}` }).catch((err) => {
             console.warn(`[nocturnal-service] Failed to record run end: ${String(err)}`);
           });
@@ -529,7 +864,7 @@ export function executeNocturnalReflection(
             diagnostics,
           };
         }
-        trinityArtifact = trinityResult.artifact!;
+        trinityArtifact = trinityResult.artifact!; // eslint-disable-line @typescript-eslint/no-non-null-assertion -- Reason: artifact is validated by validateTrinityDraft which returns valid: true when artifact exists
         // Convert Trinity draft to arbiter-compatible artifact
         const artifactData = draftToArtifact(trinityArtifact);
         rawJson = JSON.stringify(artifactData);
@@ -631,6 +966,7 @@ export function executeNocturnalReflection(
     boundedAction: execResult.boundedAction,
   };
 
+  // eslint-disable-next-line @typescript-eslint/init-declarations -- assigned in try, catch has early return
   let persistedPath: string;
   try {
     persistedPath = persistArtifact(workspaceDir, artifactWithBoundedAction);
@@ -663,6 +999,34 @@ export function executeNocturnalReflection(
     console.warn(`[nocturnal-service] Failed to register sample in dataset registry: ${String(err)}`);
   }
 
+  try {
+    appendArtifactLineageRecord(workspaceDir, {
+      artifactKind: 'behavioral-sample',
+      artifactId: arbiterResult.artifact.artifactId,
+      principleId: selectedPrincipleId,
+      ruleId: null,
+      sessionId: selectedSessionId,
+      sourceSnapshotRef: arbiterResult.artifact.sourceSnapshotRef,
+      sourcePainIds: buildPainRefs(snapshot),
+      sourceGateBlockIds: buildGateBlockRefs(snapshot),
+      storagePath: persistedPath,
+      implementationId: null,
+      createdAt: arbiterResult.artifact.createdAt,
+    });
+  } catch (err) {
+    console.warn(`[nocturnal-service] Failed to append behavioral artifact lineage: ${String(err)}`);
+  }
+
+  diagnostics.artificer = maybePersistArtificerCandidate(
+    workspaceDir,
+    stateDir,
+    selectedPrincipleId,
+    selectedSessionId,
+    snapshot,
+    arbiterResult.artifact,
+    options
+  );
+
   // -------------------------------------------------------------------------
   // Step 9: Record run success
   // -------------------------------------------------------------------------
@@ -726,6 +1090,7 @@ export async function executeNocturnalReflectionAsync(
 
   // If runtime adapter is provided, use async Trinity path
   if (options.runtimeAdapter) {
+    // eslint-disable-next-line @typescript-eslint/no-use-before-define -- Reason: mutual recursion between helper functions - reordering would break logical grouping
     return executeNocturnalReflectionWithAdapter(workspaceDir, stateDir, options);
   }
 
@@ -752,6 +1117,11 @@ async function executeNocturnalReflectionWithAdapter(
     arbiterResult: null,
     executabilityResult: null,
     persisted: false,
+    artificer: {
+      status: 'skipped',
+      ruleResolution: null,
+      validationFailures: [],
+    },
   };
 
   // Step 1: Pre-flight check
@@ -768,51 +1138,93 @@ async function executeNocturnalReflectionWithAdapter(
     return { success: false, noTargetSelected: false, validationFailed: false, validationFailures: [], diagnostics };
   }
 
-  // Step 2: Target selection
-  const extractor = createNocturnalTrajectoryExtractor(workspaceDir, stateDir);
-  const selector = new NocturnalTargetSelector(workspaceDir, stateDir, extractor, {
-    idleCheckOverride: options.idleCheckOverride,
-    recentPainContext: options.painContext,
-  });
+  // Step 2: Target selection (or use override to skip)
+  // eslint-disable-next-line @typescript-eslint/init-declarations -- Reason: assigned immediately in all branches before use
+  let selectedPrincipleId: string | undefined;
+  // eslint-disable-next-line @typescript-eslint/init-declarations -- Reason: assigned immediately in all branches before use
+  let selectedSessionId: string | undefined;
+  // eslint-disable-next-line no-useless-assignment -- Reason: initial value unused due to immediate reassignment in all branches
+  let snapshot: NocturnalSessionSnapshot | null = null;
+
+  if (options.principleIdOverride && options.snapshotOverride) {
+    // Skip Selector: use provided principleId and snapshot directly
+    selectedPrincipleId = options.principleIdOverride;
+    selectedSessionId = options.snapshotOverride.sessionId;
+    snapshot = options.snapshotOverride;
+    // Calculate violation density from snapshot stats for meaningful diagnostics
+    const snapStats = options.snapshotOverride.stats;
+    const totalToolCalls = snapStats?.totalToolCalls ?? 0;
+    const failureCount = snapStats?.failureCount ?? 0;
+    const violationDensity = totalToolCalls > 0 ? failureCount / totalToolCalls : 0;
+    diagnostics.selection = {
+      decision: 'selected',
+      selectedPrincipleId,
+      selectedSessionId,
+      skipReason: undefined,
+      diagnostics: {
+        totalEvaluablePrinciples: 1,  // We provided one principle via override
+        filteredByCooldown: 0,
+        passedPrinciples: [selectedPrincipleId],
+        violatingSessionCount: 1,  // The session we're using
+        selectedSessionViolationDensity: violationDensity,
+        selectedPrincipleScore: 100,  // Override means high priority
+        scoringBreakdown: { override: 100 },
+        idleCheckPassed: true,
+        cooldownCheckPassed: true,
+        quotaCheckPassed: true,
+      },
+    };
+    diagnostics.idle = { isIdle: true, mostRecentActivityAt: 0, idleForMs: 0, userActiveSessions: 0, abandonedSessionIds: [], trajectoryGuardrailConfirmsIdle: true, reason: 'selector skipped (override provided)' };
+  } else {
+    // Normal Selector path
+    const extractor = createNocturnalTrajectoryExtractor(workspaceDir, stateDir);
+    const selector = new NocturnalTargetSelector(workspaceDir, stateDir, extractor, {
+      idleCheckOverride: options.idleCheckOverride,
+      recentPainContext: options.painContext,
+    });
 
-  const selection = selector.select();
-  diagnostics.selection = selection;
+    const selection = selector.select();
+    diagnostics.selection = selection;
 
-  if (selection.decision === 'skip') {
-    return {
-      success: false,
-      noTargetSelected: true,
-      skipReason: selection.skipReason,
-      validationFailed: false,
-      validationFailures: [],
-      diagnostics,
-    };
-  }
+    if (selection.decision === 'skip') {
+      return {
+        success: false,
+        noTargetSelected: true,
+        skipReason: selection.skipReason,
+        validationFailed: false,
+        validationFailures: [],
+        diagnostics,
+      };
+    }
 
-  const { selectedPrincipleId, selectedSessionId } = selection;
+    // eslint-disable-next-line @typescript-eslint/prefer-destructuring -- Reason: selectedPrincipleId/selectedSessionId are reassignable outer lets - destructuring would shadow
+    selectedPrincipleId = selection.selectedPrincipleId;
+    // eslint-disable-next-line @typescript-eslint/prefer-destructuring -- Reason: selectedPrincipleId/selectedSessionId are reassignable outer lets - destructuring would shadow
+    selectedSessionId = selection.selectedSessionId;
 
-  if (!selectedPrincipleId || !selectedSessionId) {
-    return {
-      success: false,
-      noTargetSelected: true,
-      validationFailed: false,
-      validationFailures: [],
-      diagnostics,
-    };
-  }
+    if (!selectedPrincipleId || !selectedSessionId) {
+      return {
+        success: false,
+        noTargetSelected: true,
+        validationFailed: false,
+        validationFailures: [],
+        diagnostics,
+      };
+    }
 
-  const snapshot = extractor.getNocturnalSessionSnapshot(selectedSessionId);
-  if (!snapshot) {
-    return {
-      success: false,
-      noTargetSelected: true,
-      skipReason: 'insufficient_snapshot_data',
-      validationFailed: false,
-      validationFailures: [],
-      diagnostics,
-    };
+    snapshot = extractor.getNocturnalSessionSnapshot(selectedSessionId);
+    if (!snapshot) {
+      return {
+        success: false,
+        noTargetSelected: true,
+        skipReason: 'insufficient_snapshot_data',
+        validationFailed: false,
+        validationFailures: [],
+        diagnostics,
+      };
+    }
+    diagnostics.idle = { isIdle: true, mostRecentActivityAt: 0, idleForMs: 0, userActiveSessions: 0, abandonedSessionIds: [], trajectoryGuardrailConfirmsIdle: true, reason: 'preflight passed' };
   }
-  diagnostics.idle = { isIdle: true, mostRecentActivityAt: 0, idleForMs: 0, userActiveSessions: 0, abandonedSessionIds: [], trajectoryGuardrailConfirmsIdle: true, reason: 'preflight passed' };
 
   // Step 3: Record run start
   void recordRunStart(stateDir, selectedPrincipleId).catch((err) => {
@@ -820,10 +1232,11 @@ async function executeNocturnalReflectionWithAdapter(
   });
 
   // Step 4: Trinity execution via adapter (async)
+  // eslint-disable-next-line no-useless-assignment -- Reason: initial value unused due to immediate reassignment in all branches
   let trinityArtifact: TrinityDraftArtifact | null = null;
   let trinityResult: TrinityResult | null = null;
+  // eslint-disable-next-line @typescript-eslint/init-declarations -- assigned in all branches before use
   let rawJson: string;
-  let chainModeUsed: 'trinity' | 'single-reflector' = 'single-reflector';
 
   if (options.skipReflector) {
     if (!options.reflectorOutputOverride) {
@@ -841,7 +1254,6 @@ async function executeNocturnalReflectionWithAdapter(
     diagnostics.trinityAttempted = true;
     diagnostics.trinityResult = trinityResult;
     diagnostics.chainModeUsed = trinityResult.success ? 'trinity' : 'single-reflector';
-    chainModeUsed = trinityResult.success ? 'trinity' : 'single-reflector';
 
     if (!trinityResult.success) {
       const failures = trinityResult.failures.map((f) => `${f.stage}: ${f.reason}`);
@@ -851,7 +1263,7 @@ async function executeNocturnalReflectionWithAdapter(
       adjustThresholdsFromSignals(stateDir, { malformedRate: 1.0, arbiterRejectRate: 0.0, executabilityRejectRate: 0.0, qualityDelta: 0.0 });
       return { success: false, noTargetSelected: false, validationFailed: true, validationFailures: [`Trinity override failed: ${failures.join('; ')}`], snapshot, diagnostics };
     }
-    trinityArtifact = trinityResult.artifact!;
+    trinityArtifact = trinityResult.artifact!; // eslint-disable-line @typescript-eslint/no-non-null-assertion -- Reason: artifact is validated by validateTrinityDraft which returns valid: true when artifact exists
     const artifactData = draftToArtifact(trinityArtifact);
     rawJson = JSON.stringify(artifactData);
   } else {
@@ -867,19 +1279,18 @@ async function executeNocturnalReflectionWithAdapter(
       trinityResult = await runTrinityAsync({ snapshot, principleId: selectedPrincipleId, config: trinityConfig });
       diagnostics.trinityResult = trinityResult;
       diagnostics.chainModeUsed = trinityResult.success ? 'trinity' : 'single-reflector';
-      chainModeUsed = trinityResult.success ? 'trinity' : 'single-reflector';
 
       if (trinityResult.success) {
         const draftValidation = validateTrinityDraft(trinityResult.artifact);
         if (!draftValidation.valid) {
-          const failures = draftValidation.failures;
+          const {failures} = draftValidation;
           void recordRunEnd(stateDir, 'failed', { reason: `Trinity draft invalid: ${failures.join('; ')}` }).catch((err) => {
             console.warn(`[nocturnal-service] Failed to record run end: ${String(err)}`);
           });
           adjustThresholdsFromSignals(stateDir, { malformedRate: 1.0, arbiterRejectRate: 0.0, executabilityRejectRate: 0.0, qualityDelta: 0.0 });
           return { success: false, noTargetSelected: false, validationFailed: true, validationFailures: failures, snapshot, diagnostics };
         }
-        trinityArtifact = trinityResult.artifact!;
+        trinityArtifact = trinityResult.artifact!; // eslint-disable-line @typescript-eslint/no-non-null-assertion -- Reason: artifact is validated by validateTrinityDraft which returns valid: true when artifact exists
         const artifactData = draftToArtifact(trinityArtifact);
         rawJson = JSON.stringify(artifactData);
       } else {
@@ -929,6 +1340,7 @@ async function executeNocturnalReflectionWithAdapter(
 
   // Step 7: Persist artifact
   const artifactWithBoundedAction = { ...arbiterResult.artifact, boundedAction: execResult.boundedAction };
+  // eslint-disable-next-line @typescript-eslint/init-declarations -- assigned in try, catch has early return
   let persistedPath: string;
   try {
     persistedPath = persistArtifact(workspaceDir, artifactWithBoundedAction);
@@ -948,6 +1360,34 @@ async function executeNocturnalReflectionWithAdapter(
     console.warn(`[nocturnal-service] Failed to register sample in dataset registry: ${String(err)}`);
   }
 
+  try {
+    appendArtifactLineageRecord(workspaceDir, {
+      artifactKind: 'behavioral-sample',
+      artifactId: arbiterResult.artifact.artifactId,
+      principleId: selectedPrincipleId,
+      ruleId: null,
+      sessionId: selectedSessionId,
+      sourceSnapshotRef: arbiterResult.artifact.sourceSnapshotRef,
+      sourcePainIds: buildPainRefs(snapshot),
+      sourceGateBlockIds: buildGateBlockRefs(snapshot),
+      storagePath: persistedPath,
+      implementationId: null,
+      createdAt: arbiterResult.artifact.createdAt,
+    });
+  } catch (err) {
+    console.warn(`[nocturnal-service] Failed to append behavioral artifact lineage: ${String(err)}`);
+  }
+
+  diagnostics.artificer = maybePersistArtificerCandidate(
+    workspaceDir,
+    stateDir,
+    selectedPrincipleId,
+    selectedSessionId,
+    snapshot,
+    arbiterResult.artifact,
+    options
+  );
+
   // Step 9: Record run success
   void recordRunEnd(stateDir, 'success', { sampleCount: 1 }).catch((err) => {
     console.warn(`[nocturnal-service] Failed to record run end (success): ${String(err)}`);
@@ -982,9 +1422,9 @@ async function executeNocturnalReflectionWithAdapter(
  */
 export function listApprovedNocturnalArtifacts(
   workspaceDir: string
-): Array<NocturnalArtifact & { persistedAt: string; boundedAction?: BoundedAction }> {
+): (NocturnalArtifact & { persistedAt: string; boundedAction?: BoundedAction })[] {
   const samplePaths = NocturnalPathResolver.listApprovedSamples(workspaceDir);
-  const artifacts: Array<NocturnalArtifact & { persistedAt: string; boundedAction?: BoundedAction }> = [];
+  const artifacts: (NocturnalArtifact & { persistedAt: string; boundedAction?: BoundedAction })[] = [];
 
   for (const samplePath of samplePaths) {
     try {