principles-disciple 1.8.0 → 1.8.2

package/dist/core/model-deployment-registry.d.ts

@@ -1,218 +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 type { Checkpoint } from './model-training-registry.js';
-/**
- * Worker profiles supported in Phase 5.
- * Only these two profiles may be registered.
- */
-export type WorkerProfile = 'local-reader' | 'local-editor';
-/**
- * The set of valid Phase 5 worker profile names.
- */
-export declare const SUPPORTED_PROFILES: readonly WorkerProfile[];
-/**
- * A deployment record — binds a worker profile to a specific checkpoint
- * and controls whether routing is enabled for that profile.
- */
-export interface Deployment {
-    /** Unique identifier for this deployment record */
-    deploymentId: string;
-    /** Worker profile this deployment targets (local-reader | local-editor) */
-    workerProfile: WorkerProfile;
-    /**
-     * The model family this deployment targets.
-     * Derived from the bound checkpoint at bind time; stored for quick queries.
-     */
-    targetModelFamily: string;
-    /**
-     * The currently active checkpoint for this profile.
-     * null means the profile is bound but no checkpoint is active (e.g., after rollback).
-     */
-    activeCheckpointId: string | null;
-    /**
-     * The previously active checkpoint (before the current activeCheckpointId).
-     * Used for rollback. null if no previous checkpoint exists.
-     */
-    previousCheckpointId: string | null;
-    /**
-     * Whether routing to this worker profile is currently permitted.
-     * Must be explicitly enabled via enableRoutingForProfile().
-     * Cannot be true if activeCheckpointId is null.
-     */
-    routingEnabled: boolean;
-    /** ISO-8601 timestamp — when this binding was first created */
-    deployedAt: string;
-    /** ISO-8601 timestamp — when this binding was last updated (checkpoint change or flag toggle) */
-    updatedAt: string;
-    /**
-     * Optional human-readable note about this deployment.
-     * E.g., "initial deployment", "rollback from eval failure", "promoted after 30-day holdout".
-     */
-    note?: string;
-}
-/**
- * The complete deployment registry — all deployment records in one store.
- */
-export interface ModelDeploymentRegistry {
-    deployments: Deployment[];
-}
-/**
- * Validate that a worker profile name is supported in Phase 5.
- *
- * @throws Error if the profile is not in SUPPORTED_PROFILES
- */
-export declare function assertSupportedProfile(profile: string): asserts profile is WorkerProfile;
-/**
- * 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 declare function hasPassedPromotionGate(stateDir: string, checkpointId: string): boolean;
-/**
- * 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 declare function assertPromotionGatePassed(stateDir: string, checkpointId: string): void;
-/**
- * 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 declare function bindCheckpointToWorkerProfile(stateDir: string, workerProfile: WorkerProfile, checkpointId: string, note?: string): Deployment;
-/**
- * Retrieve the deployment record for a worker profile.
- *
- * @returns Deployment if found, null otherwise
- */
-export declare function getDeployment(stateDir: string, workerProfile: WorkerProfile): Deployment | null;
-/**
- * List all deployments, optionally filtered.
- *
- * @param stateDir - Workspace state directory
- * @param filter - Optional filter criteria
- */
-export declare function listDeployments(stateDir: string, filter?: {
-    workerProfile?: WorkerProfile;
-    routingEnabled?: boolean;
-}): Deployment[];
-/**
- * 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 declare function enableRoutingForProfile(stateDir: string, workerProfile: WorkerProfile): Deployment;
-/**
- * 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 declare function disableRoutingForProfile(stateDir: string, workerProfile: WorkerProfile): Deployment;
-/**
- * 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 declare function rollbackDeployment(stateDir: string, workerProfile: WorkerProfile, note?: string): Deployment;
-/**
- * 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 declare function isRoutingEnabledForProfile(stateDir: string, workerProfile: WorkerProfile): boolean;
-/**
- * Get the active checkpoint ID for a worker profile.
- * Returns null if no deployment or no active checkpoint.
- */
-export declare function getActiveCheckpointForProfile(stateDir: string, workerProfile: WorkerProfile): string | 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 declare function getDeploymentLineage(stateDir: string, workerProfile: WorkerProfile): {
-    deployment: Deployment;
-    activeCheckpoint: Checkpoint | null;
-} | null;
-/**
- * Get the complete deployment registry (for debugging/admin purposes).
- */
-export declare function getFullDeploymentRegistry(stateDir: string): ModelDeploymentRegistry;
-/**
- * Compute stats for the deployment registry.
- */
-export declare function getDeploymentRegistryStats(stateDir: string): {
-    totalDeployments: number;
-    activeDeployments: number;
-    profilesWithBindings: number;
-    profilesWithRoutingEnabled: number;
-};