principles-disciple 1.8.1 → 1.8.2

package/src/core/nocturnal-export.ts

@@ -0,0 +1,390 @@
+/**
+ * Nocturnal ORPO Export — Approved Dataset to Decision-Point JSONL
+ * =================================================================
+ *
+ * PURPOSE: Export approved nocturnal samples as ORPO-formatted decision-point
+ * training JSONL, strictly separated from legacy correction export.
+ *
+ * ARCHITECTURE:
+ *   - Export output: .state/exports/orpo/{exportId}.jsonl
+ *   - Export manifest: .state/exports/orpo/{exportId}-manifest.json
+ *   - Legacy corrections: untouched, separate path
+ *
+ * ORPO FORMAT (each line):
+ *   {
+ *     sampleFingerprint: string,
+ *     artifactId: string,
+ *     sessionId: string,
+ *     principleId: string,
+ *     targetModelFamily: string,
+ *     prompt: string,        // badDecision (the wrong choice)
+ *     chosen: string,        // betterDecision (the right choice)
+ *     rejected: string,       // badDecision (for ORPO)
+ *     rationale: string,
+ *     datasetMetadata: {
+ *       sampleFingerprint: string,
+ *       artifactPath: string,
+ *       createdAt: string,
+ *       exportedAt: string,
+ *       exportId: string,
+ *       datasetFingerprint: string
+ *     }
+ *   }
+ *
+ * EXPORT GATING (fail-closed):
+ *   - reviewStatus === 'approved_for_training'
+ *   - targetModelFamily matches requested target (or any if not specified)
+ *   - Lineage fields complete (sampleFingerprint, artifactId, sessionId, principleId)
+ *   - Source artifact file exists and is approved
+ *
+ * DESIGN CONSTRAINTS:
+ *   - No trainer invocation
+ *   - No automatic training
+ *   - No checkpoint deploy
+ *   - Export is read-only from dataset perspective
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as crypto from 'crypto';
+import {
+  listDatasetRecords,
+  readDatasetArtifact,
+  type NocturnalDatasetRecord,
+} from './nocturnal-dataset.js';
+import { NocturnalPathResolver } from './nocturnal-paths.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * A single ORPO training sample in JSONL format.
+ */
+export interface ORPOSample {
+  sampleFingerprint: string;
+  artifactId: string;
+  sessionId: string;
+  principleId: string;
+  targetModelFamily: string;
+  /** The suboptimal decision (what the agent did wrong) */
+  prompt: string;
+  /** The correct decision (what should have been done) */
+  chosen: string;
+  /** The suboptimal decision (same as prompt, for ORPO structure) */
+  rejected: string;
+  rationale: string;
+  datasetMetadata: {
+    sampleFingerprint: string;
+    artifactPath: string;
+    createdAt: string;
+    exportedAt: string;
+    exportId: string;
+    datasetFingerprint: string;
+  };
+}
+
+/**
+ * Export manifest containing metadata about the entire export.
+ */
+export interface ORPOExportManifest {
+  exportId: string;
+  createdAt: string;
+  sampleCount: number;
+  targetModelFamily: string;
+  /** SHA-256 of all sample fingerprints, sorted — for reproducibility */
+  datasetFingerprint: string;
+  exportPath: string;
+  manifestPath: string;
+  samples: Array<{
+    sampleFingerprint: string;
+    artifactId: string;
+    sessionId: string;
+    principleId: string;
+  }>;
+}
+
+/**
+ * Result of an export operation.
+ */
+export interface ExportResult {
+  success: boolean;
+  manifest?: ORPOExportManifest;
+  error?: string;
+  emptyReason?: 'no_approved_samples' | 'family_mismatch' | 'all_samples_missing_artifacts';
+}
+
+// ---------------------------------------------------------------------------
+// Dataset Fingerprint (for reproducibility)
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute a deterministic dataset fingerprint from a sorted list of sample fingerprints.
+ * This allows reproducible exports — same dataset always produces same fingerprint.
+ */
+function computeDatasetFingerprint(sampleFingerprints: string[]): string {
+  const sorted = [...sampleFingerprints].sort();
+  const combined = sorted.join('|');
+  return crypto.createHash('sha256').update(combined, 'utf8').digest('hex');
+}
+
+// ---------------------------------------------------------------------------
+// Individual Sample Serialization
+// ---------------------------------------------------------------------------
+
+/**
+ * Serialize a single dataset record + artifact to ORPO JSONL line.
+ * Caller guarantees record.targetModelFamily is non-null.
+ */
+function serializeORPOSample(
+  record: NocturnalDatasetRecord,
+  artifact: ReturnType<typeof readDatasetArtifact>,
+  exportId: string,
+  datasetFingerprint: string
+): ORPOSample {
+  const now = new Date().toISOString();
+
+  return {
+    sampleFingerprint: record.sampleFingerprint,
+    artifactId: record.artifactId,
+    sessionId: record.sessionId,
+    principleId: record.principleId,
+    targetModelFamily: record.targetModelFamily as string, // validated non-null by caller
+    // For ORPO: prompt = badDecision, chosen = betterDecision, rejected = badDecision
+    // This teaches the model to prefer betterDecision over badDecision
+    prompt: artifact.badDecision,
+    chosen: artifact.betterDecision,
+    rejected: artifact.badDecision,
+    rationale: artifact.rationale,
+    datasetMetadata: {
+      sampleFingerprint: record.sampleFingerprint,
+      artifactPath: record.artifactPath,
+      createdAt: record.createdAt,
+      exportedAt: now,
+      exportId,
+      datasetFingerprint,
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Core Export Function
+// ---------------------------------------------------------------------------
+
+/**
+ * Export approved nocturnal samples as ORPO decision-point JSONL.
+ *
+ * @param workspaceDir - Workspace directory
+ * @param targetModelFamily - Specific model family to export, or undefined for all
+ * @param options - Additional export options
+ * @returns ExportResult
+ */
+export function exportORPOSamples(
+  workspaceDir: string,
+  targetModelFamily?: string | null,
+  _options: Record<string, never> = {}
+): ExportResult {
+  const exportId = crypto.randomUUID();
+  const now = new Date().toISOString();
+
+  // Step 1: Collect eligible records
+  // Use listDatasetRecords directly to have full control over the family filter
+  // (listExportReadyRecords uses ?? which maps null→undefined, losing the null distinction)
+  const allApprovedRecords = listDatasetRecords(workspaceDir, {
+    reviewStatus: 'approved_for_training',
+  });
+
+  let eligibleRecords: typeof allApprovedRecords;
+
+  if (targetModelFamily !== undefined && targetModelFamily !== null) {
+    // Specific family: check if ANY records (regardless of status) have this family
+    const allRecords = listDatasetRecords(workspaceDir);
+    const hasAnyWithFamily = allRecords.some((r) => r.targetModelFamily === targetModelFamily);
+    if (!hasAnyWithFamily) {
+      // Family doesn't exist in any record
+      return {
+        success: false,
+        error: 'No samples found for the requested target model family',
+        emptyReason: 'family_mismatch',
+      };
+    }
+    // Family exists but none are approved
+    eligibleRecords = allApprovedRecords.filter((r) => r.targetModelFamily === targetModelFamily);
+  } else {
+    // All families
+    eligibleRecords = allApprovedRecords;
+  }
+
+  // Step 2: Validate we have records
+  if (eligibleRecords.length === 0) {
+    return {
+      success: false,
+      error: 'No approved samples found for export',
+      emptyReason: 'no_approved_samples',
+    };
+  }
+
+  // Step 3: Verify lineage completeness and read artifacts
+  const orpoSamples: ORPOSample[] = [];
+  const failedFingerprints: string[] = [];
+
+  for (const record of eligibleRecords) {
+    // Enforce targetModelFamily binding — samples without a family cannot enter training
+    if (record.targetModelFamily === null) {
+      failedFingerprints.push(record.sampleFingerprint);
+      continue;
+    }
+
+    // Verify lineage completeness
+    if (!record.sampleFingerprint || !record.artifactId || !record.sessionId || !record.principleId) {
+      failedFingerprints.push(record.sampleFingerprint);
+      continue;
+    }
+
+    // Read artifact (throws on error — distinguishes read failure from missing artifact)
+    let artifact;
+    try {
+      artifact = readDatasetArtifact(workspaceDir, record.sampleFingerprint);
+    } catch {
+      failedFingerprints.push(record.sampleFingerprint);
+      continue;
+    }
+
+    // Serialize
+    orpoSamples.push(serializeORPOSample(record, artifact, exportId, ''));
+  }
+
+  // Step 4: Fail if all samples failed validation
+  if (orpoSamples.length === 0) {
+    return {
+      success: false,
+      error: `All ${eligibleRecords.length} eligible samples failed validation (missing artifacts or lineage)`,
+      emptyReason: 'all_samples_missing_artifacts',
+    };
+  }
+
+  // Step 5: Compute dataset fingerprint for manifest
+  const datasetFingerprint = computeDatasetFingerprint(
+    orpoSamples.map((s) => s.sampleFingerprint)
+  );
+
+  // Step 6: Fill in dataset fingerprint in all samples
+  for (const sample of orpoSamples) {
+    sample.datasetMetadata.datasetFingerprint = datasetFingerprint;
+  }
+
+  // Step 7: Write JSONL file
+  const exportsDir = NocturnalPathResolver.exportsDir(workspaceDir);
+  const jsonlPath = path.join(exportsDir, `${exportId}.jsonl`);
+  const lines = orpoSamples.map((s) => JSON.stringify(s)).join('\n') + '\n';
+  fs.writeFileSync(jsonlPath, lines, 'utf-8');
+
+  // Step 8: Write manifest
+  const manifest: ORPOExportManifest = {
+    exportId,
+    createdAt: now,
+    sampleCount: orpoSamples.length,
+    targetModelFamily: targetModelFamily ?? 'all',
+    datasetFingerprint,
+    exportPath: jsonlPath,
+    manifestPath: path.join(exportsDir, `${exportId}-manifest.json`),
+    samples: orpoSamples.map((s) => ({
+      sampleFingerprint: s.sampleFingerprint,
+      artifactId: s.artifactId,
+      sessionId: s.sessionId,
+      principleId: s.principleId,
+    })),
+  };
+
+  fs.writeFileSync(manifest.manifestPath, JSON.stringify(manifest, null, 2), 'utf-8');
+
+  return {
+    success: true,
+    manifest,
+  };
+}
+
+/**
+ * Verify an existing export by re-computing its dataset fingerprint.
+ * Returns true if the export is intact and reproducible.
+ */
+export function verifyExportIntegrity(
+  workspaceDir: string,
+  exportId: string
+): { valid: boolean; computedFingerprint: string; manifestFingerprint: string } | null {
+  const exportsDir = NocturnalPathResolver.exportsDir(workspaceDir);
+  const manifestPath = path.join(exportsDir, `${exportId}-manifest.json`);
+
+  if (!fs.existsSync(manifestPath)) {
+    return null;
+  }
+
+  try {
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8')) as ORPOExportManifest;
+    const computedFingerprint = computeDatasetFingerprint(
+      manifest.samples.map((s) => s.sampleFingerprint)
+    );
+
+    return {
+      valid: computedFingerprint === manifest.datasetFingerprint,
+      computedFingerprint,
+      manifestFingerprint: manifest.datasetFingerprint,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * List all exports in the exports directory.
+ */
+export function listExports(workspaceDir: string): ORPOExportManifest[] {
+  const exportsDir = NocturnalPathResolver.exportsDir(workspaceDir);
+  if (!fs.existsSync(exportsDir)) {
+    return [];
+  }
+
+  try {
+    const files = fs.readdirSync(exportsDir);
+    const manifests: ORPOExportManifest[] = [];
+
+    for (const file of files) {
+      if (!file.endsWith('-manifest.json')) continue;
+      try {
+        const manifest = JSON.parse(
+          fs.readFileSync(path.join(exportsDir, file), 'utf-8')
+        ) as ORPOExportManifest;
+        manifests.push(manifest);
+      } catch {
+        // Skip malformed manifest
+      }
+    }
+
+    return manifests.sort(
+      (a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime()
+    );
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Read an export manifest by ID.
+ */
+export function getExportManifest(
+  workspaceDir: string,
+  exportId: string
+): ORPOExportManifest | null {
+  const exportsDir = NocturnalPathResolver.exportsDir(workspaceDir);
+  const manifestPath = path.join(exportsDir, `${exportId}-manifest.json`);
+
+  if (!fs.existsSync(manifestPath)) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(fs.readFileSync(manifestPath, 'utf-8')) as ORPOExportManifest;
+  } catch {
+    return null;
+  }
+}

package/{dist/core/nocturnal-paths.js → src/core/nocturnal-paths.ts}

@@ -24,14 +24,18 @@
  *   import { NocturnalPathResolver, NOCTURNAL_DIRS, NOCTURNAL_FILES } from './nocturnal-paths.js';
  *   const sampleDir = NocturnalPathResolver.samplesDir(workspaceDir);
  */
+
 import * as path from 'path';
 import * as fs from 'fs';
+
 // ---------------------------------------------------------------------------
 // Directory Constants
 // ---------------------------------------------------------------------------
+
 export const NOCTURNAL_DIRS = {
     /** Root directory for all nocturnal reflection artifacts */
     ROOT: '.state/nocturnal',
+
     /**
      * Structured decision-point samples from nocturnal reflection.
      * Each file is a JSON artifact containing:
@@ -41,28 +45,33 @@ export const NOCTURNAL_DIRS = {
      *   - arbiter approval status
      */
     SAMPLES: '.state/nocturnal/samples',
+
     /**
      * Short-term operator-facing reflection memory.
      * Written by nocturnal service, NOT injected into prompts directly.
      * Consumed by operator on next session start.
      */
     MEMORY: '.state/nocturnal/memory',
+
     /**
      * Nocturnal runtime bookkeeping (cooldowns, quotas).
      * NOTE: nocturnal-runtime.json is written to stateDir directly
      * (not under NOCTURNAL_DIRS.ROOT) for simpler migration.
      */
     // RUNTIME is in {stateDir}/nocturnal-runtime.json (not here)
+
     /**
      * Approved training pairs ready for export.
      * Immutable once written — never modified in place.
      * Consumed by external trainer (not the plugin).
      */
     EXPORTS: '.state/exports/orpo',
-};
+} as const;
+
 // ---------------------------------------------------------------------------
 // File Path Constants (within their respective directories)
 // ---------------------------------------------------------------------------
+
 export const NOCTURNAL_FILES = {
     /**
      * Arbiter review queue for pending samples.
@@ -70,20 +79,23 @@ export const NOCTURNAL_FILES = {
      * Format: JSON array of sample refs pending approval.
      */
     REVIEW_QUEUE: '.state/nocturnal/review-queue.json',
+
     /**
      * Lineage metadata for all samples.
      * Written alongside each sample file for traceability.
      */
     LINEAGE_INDEX: '.state/nocturnal/samples/lineage-index.json',
-};
+} as const;
+
 // ---------------------------------------------------------------------------
 // Path Resolution
 // ---------------------------------------------------------------------------
+
 /**
  * Cross-platform path join for workspace-relative paths.
  * Handles Windows vs POSIX differences.
  */
-function joinWorkspacePath(workspaceDir, relativePath) {
+function joinWorkspacePath(workspaceDir: string, relativePath: string): string {
     const normalized = relativePath.replace(/\\/g, '/');
     if (/^[A-Za-z]:/.test(workspaceDir)) {
         // Windows
@@ -91,77 +103,89 @@ function joinWorkspacePath(workspaceDir, relativePath) {
     }
     return path.posix.join(workspaceDir, ...normalized.split('/'));
 }
+
 /**
  * Resolves a nocturnal directory path within a workspace.
  */
-export function resolveNocturnalDir(workspaceDir, dirKey) {
+export function resolveNocturnalDir(workspaceDir: string, dirKey: keyof typeof NOCTURNAL_DIRS): string {
     return joinWorkspacePath(workspaceDir, NOCTURNAL_DIRS[dirKey]);
 }
+
 /**
  * Resolves a nocturnal file path within a workspace.
  */
-export function resolveNocturnalFile(workspaceDir, fileKey) {
+export function resolveNocturnalFile(workspaceDir: string, fileKey: keyof typeof NOCTURNAL_FILES): string {
     return joinWorkspacePath(workspaceDir, NOCTURNAL_FILES[fileKey]);
 }
+
 // ---------------------------------------------------------------------------
 // NocturnalPathResolver — Fluent API for common resolutions
 // ---------------------------------------------------------------------------
+
 export const NocturnalPathResolver = {
     /**
      * Returns the samples directory path.
      * Creates the directory if it does not exist.
      */
-    samplesDir(workspaceDir) {
+    samplesDir(workspaceDir: string): string {
         const dir = resolveNocturnalDir(workspaceDir, 'SAMPLES');
         if (!fs.existsSync(dir)) {
             fs.mkdirSync(dir, { recursive: true });
         }
         return dir;
     },
+
     /**
      * Returns the memory directory path.
      * Creates the directory if it does not exist.
      */
-    memoryDir(workspaceDir) {
+    memoryDir(workspaceDir: string): string {
         const dir = resolveNocturnalDir(workspaceDir, 'MEMORY');
         if (!fs.existsSync(dir)) {
             fs.mkdirSync(dir, { recursive: true });
         }
         return dir;
     },
+
     /**
      * Returns the exports directory path.
      * Creates the directory if it does not exist.
      */
-    exportsDir(workspaceDir) {
+    exportsDir(workspaceDir: string): string {
         const dir = resolveNocturnalDir(workspaceDir, 'EXPORTS');
         if (!fs.existsSync(dir)) {
             fs.mkdirSync(dir, { recursive: true });
         }
         return dir;
     },
+
     /**
      * Returns the path for a named sample file.
      * File is NOT created — caller decides when to write.
      */
-    samplePath(workspaceDir, sampleId) {
+    samplePath(workspaceDir: string, sampleId: string): string {
         const dir = resolveNocturnalDir(workspaceDir, 'SAMPLES');
         // Sanitize sampleId for filesystem
         const safeId = sampleId.replace(/[/\\:]/g, '_');
         return path.join(dir, `${safeId}.json`);
     },
+
     /**
      * Returns the path for nocturnal reflection memory.
      * This is the operator-facing summary written after each nocturnal run.
      */
-    reflectionMemoryPath(workspaceDir) {
-        return path.join(resolveNocturnalDir(workspaceDir, 'MEMORY'), 'reflection-memory.md');
+    reflectionMemoryPath(workspaceDir: string): string {
+        return path.join(
+            resolveNocturnalDir(workspaceDir, 'MEMORY'),
+            'reflection-memory.md'
+        );
     },
+
     /**
      * Lists all sample files in the samples directory.
      * Returns absolute paths sorted by modification time (newest first).
      */
-    listSamples(workspaceDir) {
+    listSamples(workspaceDir: string): string[] {
         const dir = resolveNocturnalDir(workspaceDir, 'SAMPLES');
         if (!fs.existsSync(dir)) {
             return [];
@@ -171,42 +195,44 @@ export const NocturnalPathResolver = {
                 .filter(f => f.endsWith('.json'))
                 .map(f => path.join(dir, f))
                 .sort((a, b) => fs.statSync(b).mtime.getTime() - fs.statSync(a).mtime.getTime());
-        }
-        catch {
+        } catch {
             return [];
         }
     },
+
     /**
      * Lists all approved sample files ready for export.
      * Filters to samples with status === 'approved'.
      */
-    listApprovedSamples(workspaceDir) {
+    listApprovedSamples(workspaceDir: string): string[] {
         return this.listSamples(workspaceDir).filter(samplePath => {
             try {
                 const content = fs.readFileSync(samplePath, 'utf-8');
                 const sample = JSON.parse(content);
                 return sample.status === 'approved';
-            }
-            catch {
+            } catch {
                 return false;
             }
         });
     },
-};
+} as const;
+
 // ---------------------------------------------------------------------------
 // Constants for documentation / external reference
 // ---------------------------------------------------------------------------
+
 /**
  * Complete path map for reference.
  * These mirror the keys in NOCTURNAL_DIRS and NOCTURNAL_FILES.
  */
-export const NOCTURNAL_PATH_DESCRIPTIONS = {
-    '.state/nocturnal/samples/': 'Structured decision-point JSON artifacts (not injected into prompts)',
-    '.state/nocturnal/memory/': 'Short-term operator-facing reflection memory (not prompt-injected)',
-    '.state/exports/orpo/': 'Approved training pairs, immutable after export',
+export const NOCTURNAL_PATH_DESCRIPTIONS: Record<string, string> = {
+    '.state/nocturnal/samples/':      'Structured decision-point JSON artifacts (not injected into prompts)',
+    '.state/nocturnal/memory/':       'Short-term operator-facing reflection memory (not prompt-injected)',
+    '.state/exports/orpo/':           'Approved training pairs, immutable after export',
     '.state/nocturnal/review-queue.json': 'Pending sample review queue',
-    'memory/reflection-log.md': 'Operator-facing human-readable lessons (INJECTED into prompts)',
+    'memory/reflection-log.md':       'Operator-facing human-readable lessons (INJECTED into prompts)',
 };
+
 /**
  * IMPORTANT: memory/reflection-log.md is NOT a nocturnal artifact.
  * It is the pre-existing operator-facing reflection log, defined in paths.ts.