create-principles-disciple 1.89.0 → 1.91.0

package/plugin/dist/core/model-deployment-registry.js

@@ -1,502 +0,0 @@
-/**
- * Model Deployment Registry — Worker Profile → Checkpoint Binding & Routing Control
- * ===============================================================================
- *
- * PURPOSE: Establish auditable, reversible bindings between worker profiles and
- * trained model checkpoints so that routing decisions are code-governed and
- * rollback-safe.
- *
- * ARCHITECTURE:
- *   - Registry file: {stateDir}/.state/nocturnal/deployment-registry.json
- *   - File locking on all write operations
- *   - Immutable deployment records — rollback uses previousCheckpointId
- *   - Tight integration with model-training-registry for checkpoint validation
- *
- * PROFILE CONSTRAINTS (Phase 5 only):
- *   - local-reader  → must bind a checkpoint whose targetModelFamily is a "reader" family
- *   - local-editor  → must bind a checkpoint whose targetModelFamily is an "editor" family
- *   - No other profiles are accepted
- *
- * BINDING RULES:
- *   - Only a deployable checkpoint can be bound
- *   - The checkpoint's targetModelFamily must satisfy the profile's family constraint
- *   - binding sets routingEnabled = false; enableRoutingForProfile() must be called explicitly
- *   - rollbackDeployment() returns to previousCheckpointId (if any)
- *
- * DESIGN CONSTRAINTS:
- *   - No actual task routing execution (Phase 5 only)
- *   - No automatic promotion or failover
- *   - Registry is append-only for deployments; rollback creates a new binding
- */
-import * as fs from 'fs';
-import * as path from 'path';
-import * as crypto from 'crypto';
-import { withLock } from '../utils/file-lock.js';
-import { atomicWriteFileSync } from '../utils/io.js';
-import { getCheckpoint, isCheckpointDeployable, } from './model-training-registry.js';
-import { getPromotionState } from './promotion-gate.js';
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-const REGISTRY_FILE = '.state/nocturnal/deployment-registry.json';
-/**
- * The set of valid Phase 5 worker profile names.
- */
-export const SUPPORTED_PROFILES = ['local-reader', 'local-editor'];
-// ---------------------------------------------------------------------------
-// Profile–Family Constraint System
-// ---------------------------------------------------------------------------
-/**
- * Known model family name prefixes/suffixes recognized as "reader" families.
- * Any targetModelFamily string containing one of these tokens is considered a reader family.
- *
- * This is a first-iteration heuristic. Real systems may use explicit tag registries.
- */
-const READER_FAMILY_KEYWORDS = ['reader', 'read', 'claude-haiku', 'qwen-lite', 'phi-mini'];
-/**
- * Known model family name prefixes/suffixes recognized as "editor" families.
- * Any targetModelFamily string containing one of these tokens is considered an editor family.
- */
-const EDITOR_FAMILY_KEYWORDS = ['editor', 'edit', 'code', 'claude-sonnet', 'gpt-4o-mini'];
-/**
- * Determine whether a target model family name qualifies as a "reader" family.
- * Returns true if any known reader keyword appears in the family name (case-insensitive).
- */
-function isReaderFamily(targetModelFamily) {
-    const lower = targetModelFamily.toLowerCase();
-    return READER_FAMILY_KEYWORDS.some((kw) => lower.includes(kw));
-}
-/**
- * Determine whether a target model family name qualifies as an "editor" family.
- * Returns true if any known editor keyword appears in the family name (case-insensitive).
- */
-function isEditorFamily(targetModelFamily) {
-    const lower = targetModelFamily.toLowerCase();
-    return EDITOR_FAMILY_KEYWORDS.some((kw) => lower.includes(kw));
-}
-/**
- * Validate that a given targetModelFamily satisfies a worker's family constraint.
- *
- * @param profile - The worker profile requesting the binding
- * @param targetModelFamily - The checkpoint's target model family
- * @throws Error if the family is incompatible with the profile
- */
-function validateProfileFamilyConstraint(profile, targetModelFamily) {
-    if (profile === 'local-reader') {
-        if (!isReaderFamily(targetModelFamily)) {
-            throw new Error(`Family constraint violated: profile "${profile}" requires a reader-family checkpoint ` +
-                `but checkpoint targets "${targetModelFamily}". ` +
-                `Reader families must contain one of: ${READER_FAMILY_KEYWORDS.join(', ')}. ` +
-                `If you are deploying a new model family, update the READER_FAMILY_KEYWORDS or ` +
-                `EDITOR_FAMILY_KEYWORDS constants in model-deployment-registry.ts.`);
-        }
-    }
-    else if (profile === 'local-editor') {
-        if (!isEditorFamily(targetModelFamily)) {
-            throw new Error(`Family constraint violated: profile "${profile}" requires an editor-family checkpoint ` +
-                `but checkpoint targets "${targetModelFamily}". ` +
-                `Editor families must contain one of: ${EDITOR_FAMILY_KEYWORDS.join(', ')}. ` +
-                `If you are deploying a new model family, update the EDITOR_FAMILY_KEYWORDS constant ` +
-                `in model-deployment-registry.ts.`);
-        }
-    }
-}
-// ---------------------------------------------------------------------------
-// Registry Path
-// ---------------------------------------------------------------------------
-function getRegistryPath(stateDir) {
-    return path.join(stateDir, REGISTRY_FILE);
-}
-/**
- * Ensure the registry directory exists.
- */
-function ensureRegistryDir(stateDir) {
-    const registryPath = getRegistryPath(stateDir);
-    const dir = path.dirname(registryPath);
-    if (!fs.existsSync(dir)) {
-        fs.mkdirSync(dir, { recursive: true });
-    }
-}
-// ---------------------------------------------------------------------------
-// File Operations
-// ---------------------------------------------------------------------------
-/**
- * Read the registry from disk. Returns empty registry if missing.
- * Throws if the file exists but contains invalid JSON — fail-closed
- * to prevent silent data loss when a corrupt registry would otherwise
- * be overwritten on the next write.
- */
-function readRegistry(stateDir) {
-    const registryPath = getRegistryPath(stateDir);
-    if (!fs.existsSync(registryPath)) {
-        return { deployments: [] };
-    }
-    try {
-        const content = fs.readFileSync(registryPath, 'utf-8');
-        const registry = JSON.parse(content);
-        // Validate required structure — fail closed on malformed registry
-        if (!Array.isArray(registry.deployments)) {
-            throw new Error(`Corrupt deployment registry at "${registryPath}": missing or invalid "deployments" field`);
-        }
-        return registry;
-    }
-    catch (err) {
-        if (err instanceof SyntaxError || err instanceof Error) {
-            throw new Error(`Failed to read deployment registry from "${registryPath}": ${err.message}`, { cause: err });
-        }
-        throw err;
-    }
-}
-/**
- * Write the registry to disk atomically.
- * Caller must hold the registry lock.
- */
-function writeRegistry(stateDir, registry) {
-    ensureRegistryDir(stateDir);
-    const registryPath = getRegistryPath(stateDir);
-    atomicWriteFileSync(registryPath, JSON.stringify(registry, null, 2));
-}
-/**
- * Execute a read-modify-write under an exclusive file lock.
- */
-function withDeploymentRegistryLock(stateDir, fn) {
-    const registryPath = getRegistryPath(stateDir);
-    return withLock(registryPath, () => {
-        const registry = readRegistry(stateDir);
-        return fn(registry);
-    });
-}
-// ---------------------------------------------------------------------------
-// Profile Validation
-// ---------------------------------------------------------------------------
-/**
- * Validate that a worker profile name is supported in Phase 5.
- *
- * @throws Error if the profile is not in SUPPORTED_PROFILES
- */
-export function assertSupportedProfile(profile) {
-    if (!SUPPORTED_PROFILES.includes(profile)) {
-        throw new Error(`Unsupported worker profile: "${profile}". ` +
-            `Phase 5 only supports: ${SUPPORTED_PROFILES.join(', ')}. ` +
-            `Do not add new profiles in Phase 5.`);
-    }
-}
-// ---------------------------------------------------------------------------
-// Promotion Gate Integration (Phase 7)
-// ---------------------------------------------------------------------------
-/**
- * Check if a checkpoint has passed the promotion gate and can be deployed.
- *
- * This function checks:
- * 1. The checkpoint has an eval summary attached (lineage complete)
- * 2. The promotion state is 'shadow_ready' or 'promotable' (gate passed)
- *
- * @param stateDir - Workspace state directory
- * @param checkpointId - Checkpoint to verify
- * @returns true if the checkpoint can be deployed, false otherwise
- */
-export function hasPassedPromotionGate(stateDir, checkpointId) {
-    const checkpoint = getCheckpoint(stateDir, checkpointId);
-    if (!checkpoint)
-        return false;
-    // Must have eval summary attached
-    if (!checkpoint.lastEvalSummaryRef)
-        return false;
-    // Check promotion state
-    const state = getPromotionState(stateDir, checkpointId);
-    return state === 'shadow_ready' || state === 'promotable';
-}
-/**
- * Assert that a checkpoint has passed the promotion gate.
- * Throws if the checkpoint cannot be deployed.
- *
- * @param stateDir - Workspace state directory
- * @param checkpointId - Checkpoint to verify
- * @throws Error if the checkpoint has not passed the promotion gate
- */
-export function assertPromotionGatePassed(stateDir, checkpointId) {
-    if (!hasPassedPromotionGate(stateDir, checkpointId)) {
-        throw new Error(`Checkpoint "${checkpointId}" has not passed the promotion gate. ` +
-            `A checkpoint must pass the promotion gate (state: shadow_ready or promotable) ` +
-            `before it can be bound to a worker profile. ` +
-            `Ensure the promotion gate has been evaluated and approved.`);
-    }
-}
-// ---------------------------------------------------------------------------
-// Core Operations
-// ---------------------------------------------------------------------------
-/**
- * Bind a checkpoint to a worker profile, creating or updating the deployment record.
- *
- * BINDING RULE (fail-closed):
- *   Only a checkpoint that is marked deployable in the training registry may be bound.
- *
- * PROFILE-FAMILY CONSTRAINT:
- *   The checkpoint's targetModelFamily must satisfy the profile's family keyword constraint.
- *   See: validateProfileFamilyConstraint()
- *
- * @param stateDir - Workspace state directory
- * @param workerProfile - Target worker profile (local-reader | local-editor)
- * @param checkpointId - Checkpoint to bind (must be deployable)
- * @param note - Optional human-readable note
- * @returns The new or updated Deployment record
- *
- * @throws Error if checkpoint is not found or not deployable
- * @throws Error if checkpoint's targetModelFamily violates profile constraints
- */
-export function bindCheckpointToWorkerProfile(stateDir, workerProfile, checkpointId, note) {
-    assertSupportedProfile(workerProfile);
-    return withDeploymentRegistryLock(stateDir, (registry) => {
-        const now = new Date().toISOString();
-        // --- Validate checkpoint exists and is deployable ---
-        const checkpoint = getCheckpoint(stateDir, checkpointId);
-        if (!checkpoint) {
-            throw new Error(`bindCheckpointToWorkerProfile failed: checkpoint "${checkpointId}" not found ` +
-                `in training registry. Ensure the checkpoint has been registered via ` +
-                `registerCheckpoint() in model-training-registry.ts first.`);
-        }
-        if (!isCheckpointDeployable(stateDir, checkpointId)) {
-            throw new Error(`bindCheckpointToWorkerProfile failed: checkpoint "${checkpointId}" is not deployable. ` +
-                `Only checkpoints that have passed evaluation may be bound to a worker profile. ` +
-                `Use markCheckpointDeployable() in model-training-registry.ts after a successful eval.`);
-        }
-        // --- Phase 7: Validate promotion gate has passed ---
-        assertPromotionGatePassed(stateDir, checkpointId);
-        // --- Validate profile-family constraint ---
-        validateProfileFamilyConstraint(workerProfile, checkpoint.targetModelFamily);
-        // --- Find existing deployment for this profile (if any) ---
-        const existingIdx = registry.deployments.findIndex((d) => d.workerProfile === workerProfile);
-        const deploymentId = existingIdx >= 0
-            ? registry.deployments[existingIdx].deploymentId
-            : crypto.randomUUID();
-        const previousCheckpointId = existingIdx >= 0
-            ? registry.deployments[existingIdx].activeCheckpointId ?? null
-            : null;
-        const newDeployment = {
-            deploymentId,
-            workerProfile,
-            targetModelFamily: checkpoint.targetModelFamily,
-            activeCheckpointId: checkpointId,
-            // When re-binding (updating checkpoint), the old active becomes previous
-            previousCheckpointId,
-            // routingEnabled starts false — must be explicitly enabled
-            routingEnabled: false,
-            deployedAt: existingIdx >= 0
-                ? registry.deployments[existingIdx].deployedAt
-                : now,
-            updatedAt: now,
-            note: note ?? (existingIdx >= 0 ? registry.deployments[existingIdx].note : undefined),
-        };
-        if (existingIdx >= 0) {
-            registry.deployments[existingIdx] = newDeployment;
-        }
-        else {
-            registry.deployments.push(newDeployment);
-        }
-        writeRegistry(stateDir, registry);
-        return newDeployment;
-    });
-}
-/**
- * Retrieve the deployment record for a worker profile.
- *
- * @returns Deployment if found, null otherwise
- */
-export function getDeployment(stateDir, workerProfile) {
-    assertSupportedProfile(workerProfile);
-    const registry = readRegistry(stateDir);
-    return registry.deployments.find((d) => d.workerProfile === workerProfile) ?? null;
-}
-/**
- * List all deployments, optionally filtered.
- *
- * @param stateDir - Workspace state directory
- * @param filter - Optional filter criteria
- */
-export function listDeployments(stateDir, filter) {
-    const registry = readRegistry(stateDir);
-    let { deployments } = registry;
-    if (filter?.workerProfile) {
-        deployments = deployments.filter((d) => d.workerProfile === filter.workerProfile);
-    }
-    if (filter?.routingEnabled !== undefined) {
-        deployments = deployments.filter((d) => d.routingEnabled === filter.routingEnabled);
-    }
-    return deployments.sort((a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime());
-}
-/**
- * Enable routing for a worker profile.
- *
- * PRECONDITIONS (fail-closed):
- *   1. A deployment record must exist for this profile
- *   2. activeCheckpointId must not be null
- *
- * @throws Error if no deployment exists
- * @throws Error if activeCheckpointId is null (nothing to route to)
- */
-export function enableRoutingForProfile(stateDir, workerProfile) {
-    assertSupportedProfile(workerProfile);
-    return withDeploymentRegistryLock(stateDir, (registry) => {
-        const idx = registry.deployments.findIndex((d) => d.workerProfile === workerProfile);
-        if (idx === -1) {
-            throw new Error(`enableRoutingForProfile failed: no deployment found for profile "${workerProfile}". ` +
-                `Bind a checkpoint first using bindCheckpointToWorkerProfile().`);
-        }
-        const deployment = registry.deployments[idx];
-        if (!deployment.activeCheckpointId) {
-            throw new Error(`enableRoutingForProfile failed: deployment for "${workerProfile}" has no ` +
-                `active checkpoint (activeCheckpointId is null). ` +
-                `Bind a checkpoint before enabling routing.`);
-        }
-        // Double-check the active checkpoint is still deployable
-        if (!isCheckpointDeployable(stateDir, deployment.activeCheckpointId)) {
-            throw new Error(`enableRoutingForProfile failed: active checkpoint "${deployment.activeCheckpointId}" ` +
-                `for profile "${workerProfile}" is no longer marked deployable. ` +
-                `Revoke deployment or bind a new checkpoint before enabling routing.`);
-        }
-        registry.deployments[idx] = {
-            ...deployment,
-            routingEnabled: true,
-            updatedAt: new Date().toISOString(),
-        };
-        writeRegistry(stateDir, registry);
-        return registry.deployments[idx];
-    });
-}
-/**
- * Disable routing for a worker profile.
- * This is always safe — it does not unbind the checkpoint.
- *
- * @throws Error if no deployment exists for the profile
- */
-export function disableRoutingForProfile(stateDir, workerProfile) {
-    assertSupportedProfile(workerProfile);
-    return withDeploymentRegistryLock(stateDir, (registry) => {
-        const idx = registry.deployments.findIndex((d) => d.workerProfile === workerProfile);
-        if (idx === -1) {
-            throw new Error(`disableRoutingForProfile failed: no deployment found for profile "${workerProfile}".`);
-        }
-        registry.deployments[idx] = {
-            ...registry.deployments[idx],
-            routingEnabled: false,
-            updatedAt: new Date().toISOString(),
-        };
-        writeRegistry(stateDir, registry);
-        return registry.deployments[idx];
-    });
-}
-/**
- * Roll back the deployment for a worker profile to its previous checkpoint.
- *
- * ROLLBACK RULE:
- *   - Can only roll back if previousCheckpointId is not null
- *   - Sets activeCheckpointId = previousCheckpointId
- *   - The old activeCheckpointId becomes the new previousCheckpointId
- *   - routingEnabled is set to false (must be re-enabled explicitly)
- *
- * @throws Error if no deployment exists
- * @throws Error if no previous checkpoint is available
- */
-export function rollbackDeployment(stateDir, workerProfile, note) {
-    assertSupportedProfile(workerProfile);
-    return withDeploymentRegistryLock(stateDir, (registry) => {
-        const idx = registry.deployments.findIndex((d) => d.workerProfile === workerProfile);
-        if (idx === -1) {
-            throw new Error(`rollbackDeployment failed: no deployment found for profile "${workerProfile}".`);
-        }
-        const deployment = registry.deployments[idx];
-        if (!deployment.previousCheckpointId) {
-            throw new Error(`rollbackDeployment failed: no previous checkpoint available for profile ` +
-                `"${workerProfile}". The current deployment has no rollback target. ` +
-                `(activeCheckpointId="${deployment.activeCheckpointId}", ` +
-                `previousCheckpointId=null)`);
-        }
-        // Verify the rollback target checkpoint still exists and is deployable
-        const rollbackTarget = getCheckpoint(stateDir, deployment.previousCheckpointId);
-        if (!rollbackTarget) {
-            throw new Error(`rollbackDeployment failed: previous checkpoint "${deployment.previousCheckpointId}" ` +
-                `no longer exists in the training registry. Cannot roll back to a deleted checkpoint.`);
-        }
-        if (!isCheckpointDeployable(stateDir, deployment.previousCheckpointId)) {
-            throw new Error(`rollbackDeployment failed: previous checkpoint "${deployment.previousCheckpointId}" ` +
-                `is no longer deployable. Roll back to a passing checkpoint or re-bind a new one.`);
-        }
-        const now = new Date().toISOString();
-        // Chain the rollback: the old active becomes the new previous
-        const newPreviousCheckpointId = deployment.activeCheckpointId;
-        const rolledBack = {
-            ...deployment,
-            activeCheckpointId: deployment.previousCheckpointId,
-            previousCheckpointId: newPreviousCheckpointId,
-            routingEnabled: false, // Always disable routing after rollback — must re-enable
-            updatedAt: now,
-            note: note ?? `Rollback to ${deployment.previousCheckpointId}`,
-        };
-        registry.deployments[idx] = rolledBack;
-        writeRegistry(stateDir, registry);
-        return rolledBack;
-    });
-}
-// ---------------------------------------------------------------------------
-// Read-Only Query Helpers
-// ---------------------------------------------------------------------------
-/**
- * Check whether a worker profile currently has an enabled deployment
- * with an active checkpoint that is still deployable.
- *
- * GOVERNANCE: Even if routing was previously enabled, a checkpoint that
- * has been revoked (marked non-deployable via markCheckpointDeployable(false))
- * must not be used for routing. This prevents routing traffic to a
- * checkpoint that has been superseded or failed re-evaluation.
- */
-export function isRoutingEnabledForProfile(stateDir, workerProfile) {
-    const deployment = getDeployment(stateDir, workerProfile);
-    if (!deployment?.routingEnabled)
-        return false;
-    if (!deployment.activeCheckpointId)
-        return false;
-    // Re-check deployability on every routing decision — checkpoint may have been revoked
-    return isCheckpointDeployable(stateDir, deployment.activeCheckpointId);
-}
-/**
- * Get the active checkpoint ID for a worker profile.
- * Returns null if no deployment or no active checkpoint.
- */
-export function getActiveCheckpointForProfile(stateDir, workerProfile) {
-    const deployment = getDeployment(stateDir, workerProfile);
-    return deployment?.activeCheckpointId ?? null;
-}
-/**
- * Get the full deployment record with lineage context.
- * Returns null if no deployment exists.
- *
- * Lineage includes: deployment record, active checkpoint, parent training run, eval summary.
- */
-export function getDeploymentLineage(stateDir, workerProfile) {
-    const deployment = getDeployment(stateDir, workerProfile);
-    if (!deployment)
-        return null;
-    const activeCheckpoint = deployment.activeCheckpointId
-        ? getCheckpoint(stateDir, deployment.activeCheckpointId)
-        : null;
-    return { deployment, activeCheckpoint };
-}
-/**
- * Get the complete deployment registry (for debugging/admin purposes).
- */
-export function getFullDeploymentRegistry(stateDir) {
-    return readRegistry(stateDir);
-}
-/**
- * Compute stats for the deployment registry.
- */
-export function getDeploymentRegistryStats(stateDir) {
-    const registry = readRegistry(stateDir);
-    const { deployments } = registry;
-    return {
-        totalDeployments: deployments.length,
-        activeDeployments: deployments.filter((d) => d.routingEnabled).length,
-        profilesWithBindings: new Set(deployments.map((d) => d.workerProfile)).size,
-        profilesWithRoutingEnabled: deployments.filter((d) => d.routingEnabled).length,
-    };
-}