principles-disciple 1.11.0 → 1.13.0

package/src/core/nocturnal-compliance.ts

@@ -200,26 +200,17 @@ const READ_TOOLS: Set<string> = new Set([
  * Normalizes a file path to POSIX forward-slash format for consistent matching.
  * Handles Windows backslash paths on any platform.
  */
-function normalizePath(filePath: string): string {
+function normalizePathPosix(filePath: string): string {
   return filePath.replace(/\\/g, '/');
 }
 
-/**
- * Returns true if the file path matches any of the given patterns when normalized.
- */
-function pathMatches(filePath: string | undefined, patterns: RegExp[]): boolean {
-  if (!filePath) return false;
-  const normalized = normalizePath(filePath);
-  return patterns.some((p) => p.test(normalized));
-}
-
 // ---------------------------------------------------------------------------
 // Opportunity Detection
 // ---------------------------------------------------------------------------
 
 /**
  * Detects whether a given session presents an APPLICABLE OPPORTUNITY
- * for a specific T-xx principle.
+ * for a specific principle.
  *
  * An opportunity exists when the session context falls within the
  * principle's applicability scope — regardless of whether the agent
@@ -227,8 +218,28 @@ function pathMatches(filePath: string | undefined, patterns: RegExp[]): boolean
  *
  * IMPORTANT: This does NOT assess compliance. It only answers:
  *   "Could the principle have applied here?"
+ *
+ * #216: For P_* principles (not T-xx), uses generic detection based on
+ * pain events and tool calls — any session with a pain signal is considered
+ * an opportunity for a pain-derived principle.
  */
 export function detectOpportunity(principleId: string, session: SessionEvents): OpportunityMatch {
+  // #216: P_* principles (pain-derived) — generic opportunity detection
+  if (principleId.startsWith('P_')) {
+    // Any session with pain signals, tool failures, or gate blocks is an opportunity
+    // for a pain-derived principle. This is conservative: better to over-count
+    // opportunities than to miss real violations.
+    const hasPainSignal = session.painSignals.length > 0;
+    const hasToolFailure = session.toolCalls.some((tc) => tc.outcome === 'failure');
+    const hasGateBlock = session.gateBlocks.length > 0;
+    if (hasPainSignal || hasToolFailure || hasGateBlock) {
+      return { applicable: true, reason: `P_* principle — session has ${hasPainSignal ? 'pain signal' : hasToolFailure ? 'tool failure' : 'gate block'}` };
+    }
+    return { applicable: false, reason: `P_* principle — no pain/tool-failure/gate-block in session` };
+  }
+
+  // T-xx principles — specific deterministic detection
+  /* eslint-disable @typescript-eslint/no-use-before-define -- Reason: Mutual recursion between helper functions - reordering would break logical grouping */
   switch (principleId) {
     case 'T-01':
       return detectT01Opportunity(session);
@@ -276,7 +287,7 @@ function detectT01Opportunity(session: SessionEvents): OpportunityMatch {
 function detectT02Opportunity(session: SessionEvents): OpportunityMatch {
   const hasConstraintInteraction = session.toolCalls.some((call) => {
     if (!call.filePath) return false;
-    const normalized = normalizePath(call.filePath);
+    const normalized = normalizePathPosix(call.filePath);
     return (
       /\.(ts|tsx|js|jsx)$/.test(normalized) || // type-aware files
       /\b(test|spec|contract|schema|interface|type)\b/i.test(normalized)
@@ -364,6 +375,7 @@ function detectT05Opportunity(session: SessionEvents): OpportunityMatch {
     if (RISKY_TOOLS.has(call.toolName)) return true;
     // Check bash for dangerous patterns
     if (call.toolName === 'bash' && call.errorMessage) {
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- Reason: call.errorMessage guard above ensures truthiness
       return DANGEROUS_BASH_PATTERNS.some((p) => p.test(call.errorMessage!));
     }
     return false;
@@ -411,7 +423,8 @@ function detectT06Opportunity(session: SessionEvents): OpportunityMatch {
 function detectT07Opportunity(session: SessionEvents): OpportunityMatch {
   const filePaths = session.toolCalls
     .filter((call) => call.filePath !== undefined)
-    .map((call) => normalizePath(call.filePath!));
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- Reason: filter ensures filePath is defined
+    .map((call) => normalizePathPosix(call.filePath!));
   const uniqueFiles = new Set(filePaths);
   if (uniqueFiles.size >= 3) {
     return {
@@ -456,7 +469,8 @@ function detectT09Opportunity(session: SessionEvents): OpportunityMatch {
   const uniqueFiles = new Set(
     session.toolCalls
       .filter((call) => call.filePath !== undefined)
-      .map((call) => normalizePath(call.filePath!))
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- Reason: filter ensures filePath is defined
+      .map((call) => normalizePathPosix(call.filePath!))
   );
   const hasComplexity = toolCallCount >= 5 || uniqueFiles.size >= 3;
 
@@ -493,8 +507,37 @@ function detectT09Opportunity(session: SessionEvents): OpportunityMatch {
  * opportunity was applicable.
  *
  * Returns a ViolationMatch with violated=true if violation signals are present.
+ *
+ * #216: For P_* principles (pain-derived), violation is detected when the session
+ * has pain signals, tool failures, or gate blocks that match the principle's
+ * trigger pattern. Since P_* principles don't have T-xx specific detectors,
+ * we use the presence of negative signals as violation evidence.
  */
 export function detectViolation(principleId: string, session: SessionEvents): ViolationMatch {
+  // #216: P_* principles (pain-derived) — generic violation detection
+  if (principleId.startsWith('P_')) {
+    // For pain-derived principles, a violation is indicated when the session
+    // contains pain signals, tool failures, or gate blocks — these are the
+    // same signals that triggered principle creation in the first place.
+    // A principle was violated if the bad outcome recurred after it was created.
+    const painSignals = session.painSignals.filter((p) => p.score >= 50);
+    const toolFailures = session.toolCalls.filter((tc) => tc.outcome === 'failure');
+    const {gateBlocks} = session;
+
+    if (painSignals.length > 0) {
+      return { violated: true, reason: `P_* principle — ${painSignals.length} pain signal(s) detected (max score: ${Math.max(...painSignals.map(p => p.score))})` };
+    }
+    if (toolFailures.length > 0) {
+      return { violated: true, reason: `P_* principle — ${toolFailures.length} tool failure(s) detected` };
+    }
+    if (gateBlocks.length > 0) {
+      return { violated: true, reason: `P_* principle — ${gateBlocks.length} gate block(s) detected` };
+    }
+    return { violated: false, reason: `P_* principle — no violation signals in session` };
+  }
+
+  // T-xx principles — specific deterministic detection
+  /* eslint-disable @typescript-eslint/no-use-before-define -- Reason: Mutual recursion between helper functions - reordering would break logical grouping */
   switch (principleId) {
     case 'T-01':
       return detectT01Violation(session);
@@ -529,7 +572,8 @@ function detectT01Violation(session: SessionEvents): ViolationMatch {
   const readFiles = new Set(
     session.toolCalls
       .filter((call) => READ_TOOLS.has(call.toolName) && call.filePath !== undefined)
-      .map((call) => normalizePath(call.filePath!))
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- Reason: filter ensures filePath is defined
+      .map((call) => normalizePathPosix(call.filePath!))
   );
 
   // Find edits to files that were NOT read first
@@ -537,14 +581,14 @@ function detectT01Violation(session: SessionEvents): ViolationMatch {
     (call) =>
       EDIT_TOOLS.has(call.toolName) &&
       call.filePath !== undefined &&
-      !readFiles.has(normalizePath(call.filePath!))
+      !readFiles.has(normalizePathPosix(call.filePath))
   );
 
   // If there were edits to unread files AND pain/failure followed → T-01 likely violated
   if (unreadEdits.length > 0) {
     const painOnUnreadEdit = session.painSignals.some(
       (p) =>
-        unreadEdits.some((e) => e.filePath !== undefined && p.source.includes(e.filePath!)) ||
+        unreadEdits.some((e) => e.filePath !== undefined && p.source.includes(e.filePath)) ||
         /structure|architecture|dependency|context|before.*edit|survey/i.test(p.reason ?? '')
     );
 
@@ -722,7 +766,8 @@ function detectT07Violation(session: SessionEvents): ViolationMatch {
   const modifiedFiles = new Set(
     session.toolCalls
       .filter((call) => EDIT_TOOLS.has(call.toolName) && call.filePath !== undefined)
-      .map((call) => normalizePath(call.filePath!))
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- Reason: filter ensures filePath is defined
+      .map((call) => normalizePathPosix(call.filePath!))
   );
 
   const failures = session.toolCalls.filter((call) => call.outcome === 'failure');
@@ -778,7 +823,8 @@ function detectT09Violation(session: SessionEvents): ViolationMatch {
   const uniqueFiles = new Set(
     session.toolCalls
       .filter((call) => call.filePath !== undefined)
-      .map((call) => normalizePath(call.filePath!))
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- Reason: filter ensures filePath is defined
+      .map((call) => normalizePathPosix(call.filePath!))
   );
 
   // Only applies if the session was complex
@@ -940,6 +986,7 @@ function computeViolationTrend(
 /**
  * Builds a human-readable explanation for the compliance result.
  */
+// eslint-disable-next-line @typescript-eslint/max-params -- Reason: explanation builder requires all context parameters - refactoring would break API
 function buildExplanation(
   principleId: string,
   applicableOpportunityCount: number,
@@ -1016,6 +1063,7 @@ export function groupEventsIntoSessions(events: RawEventEntry[]): Map<string, Se
       });
     }
 
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- Reason: set() above guarantees get() returns non-null
     const session = sessionMap.get(sessionId)!;
 
     switch (event.type) {

package/src/core/nocturnal-dataset.ts

@@ -46,6 +46,18 @@ export type NocturnalReviewStatus =
   | 'rejected'
   | 'superseded';
 
+/**
+ * Sample classification for replay evaluation.
+ * Used by the ReplayEngine to select appropriate test samples.
+ * - 'pain-negative': samples that triggered pain signals or were blocked by gates
+ * - 'success-positive': samples that were successful interactions
+ * - 'principle-anchor': samples that embody core principle behavior
+ *
+ * Artifact kind is intentionally tracked outside this type so replay
+ * classification remains behavioral-only.
+ */
+export type SampleClassification = 'pain-negative' | 'success-positive' | 'principle-anchor';
+
 /**
  * A nocturnal dataset record — the immutable lineage entry for one sample.
  *
@@ -105,6 +117,13 @@ export interface NocturnalDatasetRecord {
    * Absolute path to the artifact file.
    */
   artifactPath: string;
+
+  /**
+   * Sample classification for replay evaluation.
+   * Used by ReplayEngine to select samples by category.
+   * Null means not yet classified for replay.
+   */
+  classification: SampleClassification | null;
 }
 
 /**
@@ -240,7 +259,8 @@ function writeRegistry(workspaceDir: string, records: NocturnalDatasetRecord[]):
  * Execute a read-modify-write on the registry under an exclusive lock.
  * This prevents concurrent writers from racing on the same file.
  */
-function withRegistryLock<T>(workspaceDir: string, fn: (records: NocturnalDatasetRecord[]) => T): T {
+/* eslint-disable no-unused-vars -- Reason: _records is a type signature parameter, unused by design in function type definition */
+function withRegistryLock<T>(workspaceDir: string, fn: (_records: NocturnalDatasetRecord[]) => T): T {
   const registryPath = getRegistryPath(workspaceDir);
   return withLock(registryPath, () => {
     const records = readRegistry(workspaceDir);
@@ -260,13 +280,16 @@ function withRegistryLock<T>(workspaceDir: string, fn: (records: NocturnalDatase
  * @param artifact - The approved NocturnalArtifact
  * @param artifactPath - Absolute path where the artifact file is stored
  * @param targetModelFamily - Model family binding (required for export-ready)
+ * @param classification - Optional replay classification
  * @returns RegisterSampleResult
  */
+// eslint-disable-next-line @typescript-eslint/max-params -- Reason: sample registration requires workspace + artifact + path + family - refactoring would break API
 export function registerSample(
   workspaceDir: string,
   artifact: NocturnalArtifact,
   artifactPath: string,
-  targetModelFamily: string | null = null
+  targetModelFamily: string | null = null,
+  classification: SampleClassification | null = null
 ): RegisterSampleResult {
   const fingerprint = generateFingerprintFromArtifact(artifact);
   const now = new Date().toISOString();
@@ -293,6 +316,7 @@ export function registerSample(
       createdAt: now,
       updatedAt: now,
       artifactPath: path.normalize(artifactPath),
+      classification,
     };
 
     records.push(record);
@@ -401,6 +425,7 @@ const VALID_TRANSITIONS: Record<NocturnalReviewStatus, NocturnalReviewStatus[]>
  * @returns Updated record, or null if not found
  * @throws Error if transition is invalid
  */
+// eslint-disable-next-line @typescript-eslint/max-params -- Reason: status update requires workspace + fingerprint + status - refactoring would break API
 export function updateReviewStatus(
   workspaceDir: string,
   sampleFingerprint: string,
@@ -666,3 +691,71 @@ export function migrateSampleArtifacts(
 
   return newCount;
 }
+
+// ---------------------------------------------------------------------------
+// Replay Classification Support
+// ---------------------------------------------------------------------------
+
+/**
+ * List samples filtered by replay classification.
+ *
+ * @param workspaceDir - Workspace directory
+ * @param classification - Classification to filter by
+ * @returns Records matching the classification, sorted by createdAt descending
+ */
+export function listSamplesByClassification(
+  workspaceDir: string,
+  classification: SampleClassification
+): NocturnalDatasetRecord[] {
+  const records = readRegistry(workspaceDir);
+  return records
+    .filter((r) => r.classification === classification)
+    .sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime());
+}
+
+/**
+ * Load and parse the artifact content for a given dataset record.
+ *
+ * @param workspaceDir - Workspace directory
+ * @param record - The dataset record whose artifact to load
+ * @returns The parsed artifact JSON content
+ * @throws Error if artifact file is missing or unreadable
+ */
+export function loadSampleContent(
+  workspaceDir: string,
+  record: NocturnalDatasetRecord
+): unknown {
+  if (!fs.existsSync(record.artifactPath)) {
+    throw new Error(`Artifact file missing for sample ${record.sampleFingerprint}: ${record.artifactPath}`);
+  }
+  const content = fs.readFileSync(record.artifactPath, 'utf-8');
+  return JSON.parse(content);
+}
+
+/**
+ * Update the classification of a dataset record.
+ *
+ * @param workspaceDir - Workspace directory
+ * @param sampleFingerprint - The fingerprint of the record to update
+ * @param classification - New classification value
+ * @returns Updated record
+ */
+export function updateSampleClassification(
+  workspaceDir: string,
+  sampleFingerprint: string,
+  classification: SampleClassification | null
+): NocturnalDatasetRecord {
+  return withRegistryLock(workspaceDir, (records) => {
+    const idx = records.findIndex((r) => r.sampleFingerprint === sampleFingerprint);
+    if (idx === -1) {
+      throw new Error(`Dataset record not found: ${sampleFingerprint}`);
+    }
+    records[idx] = {
+      ...records[idx],
+      classification,
+      updatedAt: new Date().toISOString(),
+    };
+    writeRegistry(workspaceDir, records);
+    return records[idx];
+  });
+}

package/src/core/nocturnal-executability.ts

@@ -203,7 +203,7 @@ function parseBoundedAction(text: string): BoundedAction | null {
 
   // Pattern: "Read/Check/Verify X" or "X. Read/Check/Verify Y"
   const boundedPattern = /^([A-Za-z]+)\s+(?:the\s+)?([^\s.,]+(?:\s+[^\s.,]+){0,5})/i;
-  const match = trimmed.match(boundedPattern);
+  const match = boundedPattern.exec(trimmed);
 
   if (match) {
     const verb = match[1].toLowerCase();
@@ -216,7 +216,7 @@ function parseBoundedAction(text: string): BoundedAction | null {
 
   // Pattern: "[Verb] the [target]" — e.g., "read the file"
   const thePattern = /^(read|check|verify|edit|write|delete|search|grep|look|examine|inspect|review)\s+(?:the\s+)?(.+)/i;
-  const theMatch = lower.match(thePattern);
+  const theMatch = thePattern.exec(lower);
   if (theMatch) {
     return { verb: theMatch[1], target: theMatch[2].trim(), fullText: trimmed };
   }
@@ -294,7 +294,6 @@ export function validateExecutability(artifact: {
 
   // Check betterDecision is executable
   const boundedAction = parseBoundedAction(artifact.betterDecision);
-  const lowerBetter = artifact.betterDecision.toLowerCase();
 
   // Check 1: Not a hollow pattern
   if (containsHollowPattern(artifact.betterDecision)) {

package/src/core/nocturnal-export.ts

@@ -96,12 +96,12 @@ export interface ORPOExportManifest {
   datasetFingerprint: string;
   exportPath: string;
   manifestPath: string;
-  samples: Array<{
+  samples: {
     sampleFingerprint: string;
     artifactId: string;
     sessionId: string;
     principleId: string;
-  }>;
+  }[];
 }
 
 /**
@@ -136,6 +136,7 @@ function computeDatasetFingerprint(sampleFingerprints: string[]): string {
  * Serialize a single dataset record + artifact to ORPO JSONL line.
  * Caller guarantees record.targetModelFamily is non-null.
  */
+// eslint-disable-next-line @typescript-eslint/max-params -- Reason: serialization requires record + artifact + export info - refactoring would break internal API
 function serializeORPOSample(
   record: NocturnalDatasetRecord,
   artifact: ReturnType<typeof readDatasetArtifact>,
@@ -182,7 +183,7 @@ function serializeORPOSample(
 export function exportORPOSamples(
   workspaceDir: string,
   targetModelFamily?: string | null,
-  _options: Record<string, never> = {}
+  _options: Record<string, never> = {} // eslint-disable-line @typescript-eslint/no-unused-vars, no-unused-vars -- Reason: options parameter intentionally unused
 ): ExportResult {
   const exportId = crypto.randomUUID();
   const now = new Date().toISOString();
@@ -194,6 +195,7 @@ export function exportORPOSamples(
     reviewStatus: 'approved_for_training',
   });
 
+  // eslint-disable-next-line @typescript-eslint/init-declarations -- assigned in both if/else branches
   let eligibleRecords: typeof allApprovedRecords;
 
   if (targetModelFamily !== undefined && targetModelFamily !== null) {
@@ -242,6 +244,7 @@ export function exportORPOSamples(
     }
 
     // Read artifact (throws on error — distinguishes read failure from missing artifact)
+    // eslint-disable-next-line @typescript-eslint/init-declarations -- assigned in try, catch continues to next iteration
     let artifact;
     try {
       artifact = readDatasetArtifact(workspaceDir, record.sampleFingerprint);

package/src/core/nocturnal-rule-implementation-validator.ts

@@ -0,0 +1,245 @@
+import { createRuleHostHelpers, type RuleHostHelpers } from './rule-host-helpers.js';
+import { loadRuleImplementationModule } from './rule-implementation-runtime.js';
+import type {
+  RuleHostDecision,
+  RuleHostInput,
+  RuleHostMeta,
+  RuleHostResult,
+} from './rule-host-types.js';
+
+export interface RuleImplementationValidationFailure {
+  code:
+    | 'forbidden-api'
+    | 'compile-error'
+    | 'missing-meta'
+    | 'invalid-meta'
+    | 'missing-evaluate'
+    | 'invalid-result';
+  message: string;
+  detail?: string;
+}
+
+export interface RuleImplementationValidationResult {
+  passed: boolean;
+  failures: RuleImplementationValidationFailure[];
+  helperUsage: string[];
+  normalizedSource?: string;
+  meta?: RuleHostMeta;
+}
+
+const FORBIDDEN_PATTERNS: { pattern: RegExp; label: string }[] = [
+  { pattern: /\beval\s*\(/, label: 'eval' },
+  { pattern: /\bFunction\s*\(/, label: 'Function' },
+  { pattern: /\bimport\s*\(/, label: 'dynamic import' },
+  { pattern: /\brequire\s*\(/, label: 'require' },
+  { pattern: /\bfetch\s*\(/, label: 'fetch' },
+  { pattern: /\bXMLHttpRequest\b/, label: 'XMLHttpRequest' },
+  { pattern: /\bchild_process\b/, label: 'child_process' },
+  { pattern: /\bprocess\b/, label: 'process' },
+  { pattern: /\bfs\b/, label: 'fs' },
+  { pattern: /\bhttp\b/, label: 'http' },
+  { pattern: /\bhttps\b/, label: 'https' },
+  { pattern: /\bnet\b/, label: 'net' },
+];
+
+const HELPER_NAMES: (keyof RuleHostHelpers)[] = [
+  'isRiskPath',
+  'getToolName',
+  'getEstimatedLineChanges',
+  'getBashRisk',
+  'hasPlanFile',
+  'getPlanStatus',
+  'getCurrentEpiTier',
+];
+
+function createValidationInput(): RuleHostInput {
+  return {
+    action: {
+      toolName: 'write',
+      normalizedPath: 'src/risk.ts',
+      paramsSummary: {},
+    },
+    workspace: {
+      isRiskPath: true,
+      planStatus: 'DRAFT',
+      hasPlanFile: true,
+    },
+    session: {
+      sessionId: 'validator-session',
+      currentGfi: 3,
+      recentThinking: false,
+    },
+    evolution: {
+      epTier: 2,
+    },
+    derived: {
+      estimatedLineChanges: 42,
+      bashRisk: 'normal',
+    },
+  };
+}
+
+function extractHelperUsage(sourceCode: string): string[] {
+  return HELPER_NAMES.filter((helperName) =>
+    new RegExp(`\\bhelpers\\.${helperName}\\b|\\b${helperName}\\s*\\(`).test(sourceCode)
+  );
+}
+
+function validateMeta(meta: unknown): RuleImplementationValidationFailure[] {
+  if (!meta || typeof meta !== 'object') {
+    return [
+      {
+        code: 'missing-meta',
+        message: 'Candidate must export a meta object.',
+      },
+    ];
+  }
+
+  const candidate = meta as Partial<RuleHostMeta>;
+  const failures: RuleImplementationValidationFailure[] = [];
+
+  if (typeof candidate.name !== 'string' || candidate.name.trim().length === 0) {
+    failures.push({
+      code: 'invalid-meta',
+      message: 'meta.name must be a non-empty string.',
+      detail: 'name',
+    });
+  }
+  if (typeof candidate.version !== 'string' || candidate.version.trim().length === 0) {
+    failures.push({
+      code: 'invalid-meta',
+      message: 'meta.version must be a non-empty string.',
+      detail: 'version',
+    });
+  }
+  if (typeof candidate.ruleId !== 'string' || candidate.ruleId.trim().length === 0) {
+    failures.push({
+      code: 'invalid-meta',
+      message: 'meta.ruleId must be a non-empty string.',
+      detail: 'ruleId',
+    });
+  }
+  if (
+    typeof candidate.coversCondition !== 'string' ||
+    candidate.coversCondition.trim().length === 0
+  ) {
+    failures.push({
+      code: 'invalid-meta',
+      message: 'meta.coversCondition must be a non-empty string.',
+      detail: 'coversCondition',
+    });
+  }
+
+  return failures;
+}
+
+function validateResult(result: unknown): RuleImplementationValidationFailure[] {
+  if (!result || typeof result !== 'object') {
+    return [
+      {
+        code: 'invalid-result',
+        message: 'evaluate must return a RuleHostResult object.',
+      },
+    ];
+  }
+
+  const candidate = result as Partial<RuleHostResult>;
+  const failures: RuleImplementationValidationFailure[] = [];
+  const allowedDecisions: RuleHostDecision[] = ['allow', 'block', 'requireApproval'];
+
+  if (!allowedDecisions.includes(candidate.decision as RuleHostDecision)) {
+    failures.push({
+      code: 'invalid-result',
+      message: 'evaluate.decision must be allow, block, or requireApproval.',
+      detail: 'decision',
+    });
+  }
+  if (typeof candidate.matched !== 'boolean') {
+    failures.push({
+      code: 'invalid-result',
+      message: 'evaluate.matched must be a boolean.',
+      detail: 'matched',
+    });
+  }
+  if (typeof candidate.reason !== 'string') {
+    failures.push({
+      code: 'invalid-result',
+      message: 'evaluate.reason must be a string.',
+      detail: 'reason',
+    });
+  }
+
+  return failures;
+}
+
+export function validateRuleImplementationCandidate(
+  sourceCode: string
+): RuleImplementationValidationResult {
+  const helperUsage = extractHelperUsage(sourceCode);
+  const failures: RuleImplementationValidationFailure[] = [];
+
+  for (const forbidden of FORBIDDEN_PATTERNS) {
+    if (forbidden.pattern.test(sourceCode)) {
+      failures.push({
+        code: 'forbidden-api',
+        message: `Candidate uses forbidden API: ${forbidden.label}.`,
+        detail: forbidden.label,
+      });
+    }
+  }
+
+  if (failures.length > 0) {
+    return {
+      passed: false,
+      failures,
+      helperUsage,
+    };
+  }
+
+  const normalizedSource = sourceCode;
+
+  try {
+    const moduleExports = loadRuleImplementationModule(normalizedSource, 'nocturnal-candidate.js') as {
+      meta?: unknown;
+      /* eslint-disable no-unused-vars -- Reason: type signature parameters, unused by design in function type definition */
+      evaluate?: (_input: RuleHostInput, _helpers: RuleHostHelpers) => unknown;
+    };
+
+    const metaFailures = validateMeta(moduleExports.meta);
+    failures.push(...metaFailures);
+
+    if (typeof moduleExports.evaluate !== 'function') {
+      failures.push({
+        code: 'missing-evaluate',
+        message: 'Candidate must export an evaluate function.',
+      });
+    } else {
+      const result = moduleExports.evaluate(
+        createValidationInput(),
+        createRuleHostHelpers(createValidationInput())
+      );
+      failures.push(...validateResult(result));
+    }
+
+    return {
+      passed: failures.length === 0,
+      failures,
+      helperUsage,
+      normalizedSource,
+      meta: metaFailures.length === 0 ? (moduleExports.meta as RuleHostMeta) : undefined,
+    };
+  } catch (error: unknown) {
+    return {
+      passed: false,
+      failures: [
+        {
+          code: 'compile-error',
+          message: 'Candidate could not be compiled with RuleHost-compatible semantics.',
+          detail: String(error),
+        },
+      ],
+      helperUsage,
+      normalizedSource,
+    };
+  }
+}