principles-disciple 1.127.0 → 1.129.0

package/dist/core/workflow-funnel-loader.d.ts

@@ -0,0 +1,72 @@
+/**
+ * WorkflowFunnelLoader — Loads and watches workflows.yaml as the SSOT
+ * for WORKFLOW_FUNNELS definition table.
+ *
+ * D-01: workflows.yaml is the single source of truth (SSOT).
+ * D-02: workflows.yaml lives in .state/ directory per workspace.
+ * D-03: Developers manually maintain workflows.yaml (no auto-registration).
+ * D-04: Code only reads YAML, never writes it.
+ */
+/**
+ * A single stage in a workflow funnel.
+ * Policy fields are optional — existing stages without policy fields remain valid.
+ */
+export interface WorkflowStage {
+    name: string;
+    eventType: string;
+    eventCategory: string;
+    statsField: string;
+    timeoutMs?: number;
+    successCriteria?: string;
+    legacyDisabled?: boolean;
+    observability?: {
+        enabled?: boolean;
+        emitEvents?: string[];
+    };
+}
+/**
+ * Funnel-level policy that applies to all stages unless overridden per-stage.
+ */
+export interface FunnelPolicy {
+    timeoutMs?: number;
+    stageOrder?: 'strict' | 'relaxed';
+    legacyDisabled?: boolean;
+    observability?: {
+        enabled?: boolean;
+        emitEvents?: string[];
+        logLevel?: 'debug' | 'info' | 'warn' | 'error';
+    };
+}
+/**
+ * A workflow funnel definition.
+ */
+export interface WorkflowFunnel {
+    workflowId: string;
+    stages: WorkflowStage[];
+    policy?: FunnelPolicy;
+}
+/**
+ * Root of workflows.yaml schema.
+ */
+export interface WorkflowFunnelConfig {
+    version: string;
+    funnels: WorkflowFunnel[];
+}
+export declare class WorkflowFunnelLoader {
+    private readonly funnels;
+    private readonly fullFunnels;
+    private readonly configPath;
+    private watchHandle?;
+    private readonly warnings;
+    constructor(stateDir: string);
+    load(): void;
+    watch(): void;
+    dispose(): void;
+    getStages(workflowId: string): WorkflowStage[];
+    getFunnel(workflowId: string): WorkflowFunnel | undefined;
+    getAllFunnels(): Map<string, WorkflowStage[]>;
+    getAllFunnelsWithPolicy(): Map<string, WorkflowFunnel>;
+    getWarnings(): string[];
+    getConfigPath(): string;
+    private cloneFunnel;
+}

package/dist/core/workflow-funnel-loader.js

@@ -0,0 +1,135 @@
+/**
+ * WorkflowFunnelLoader — Loads and watches workflows.yaml as the SSOT
+ * for WORKFLOW_FUNNELS definition table.
+ *
+ * D-01: workflows.yaml is the single source of truth (SSOT).
+ * D-02: workflows.yaml lives in .state/ directory per workspace.
+ * D-03: Developers manually maintain workflows.yaml (no auto-registration).
+ * D-04: Code only reads YAML, never writes it.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import yaml from 'js-yaml';
+// ─────────────────────────────────────────────────────────────────────────────
+// WorkflowFunnelLoader
+// ─────────────────────────────────────────────────────────────────────────────
+export class WorkflowFunnelLoader {
+    funnels = new Map();
+    fullFunnels = new Map();
+    configPath;
+    watchHandle;
+    warnings = [];
+    constructor(stateDir) {
+        this.configPath = path.join(stateDir, 'workflows.yaml');
+        this.load();
+    }
+    load() {
+        this.warnings.length = 0;
+        if (!fs.existsSync(this.configPath)) {
+            this.warnings.push('workflows.yaml file not found.');
+            this.funnels.clear();
+            this.fullFunnels.clear();
+            return;
+        }
+        try {
+            const content = fs.readFileSync(this.configPath, 'utf-8');
+            const config = yaml.load(content, { schema: yaml.DEFAULT_SCHEMA });
+            if (!config || typeof config.version !== 'string' || !Array.isArray(config.funnels)) {
+                const msg = 'workflows.yaml validation failed: missing version or funnels array. Preserving last valid config.';
+                console.warn(`[WorkflowFunnelLoader] ${msg}`);
+                this.warnings.push(msg);
+                return;
+            }
+            const newFunnels = new Map();
+            const newFullFunnels = new Map();
+            for (const funnel of config.funnels) {
+                if (funnel?.workflowId && typeof funnel.workflowId === 'string' && Array.isArray(funnel.stages)) {
+                    newFunnels.set(funnel.workflowId, funnel.stages);
+                    newFullFunnels.set(funnel.workflowId, funnel);
+                }
+                else {
+                    const msg = 'Skipping invalid funnel entry: missing workflowId or stages.';
+                    console.warn(`[WorkflowFunnelLoader] ${msg}`);
+                    this.warnings.push(msg);
+                }
+            }
+            this.funnels.clear();
+            this.fullFunnels.clear();
+            for (const [k, v] of newFunnels) {
+                this.funnels.set(k, v);
+            }
+            for (const [k, v] of newFullFunnels) {
+                this.fullFunnels.set(k, v);
+            }
+        }
+        catch (err) {
+            const msg = `Failed to parse workflows.yaml: ${String(err)}. Preserving last valid config.`;
+            console.warn(`[WorkflowFunnelLoader] ${msg}`);
+            this.warnings.push(msg);
+        }
+    }
+    watch() {
+        if (this.watchHandle)
+            return;
+        if (!fs.existsSync(this.configPath))
+            return;
+        let debounceTimer;
+        this.watchHandle = fs.watch(this.configPath, (eventType) => {
+            if (eventType !== 'change' && eventType !== 'rename')
+                return;
+            if (debounceTimer)
+                clearTimeout(debounceTimer);
+            debounceTimer = setTimeout(() => this.load(), 100);
+        });
+    }
+    dispose() {
+        if (this.watchHandle) {
+            this.watchHandle.close();
+            this.watchHandle = undefined;
+        }
+    }
+    getStages(workflowId) {
+        return this.funnels.get(workflowId) ?? [];
+    }
+    getFunnel(workflowId) {
+        const funnel = this.fullFunnels.get(workflowId);
+        if (!funnel)
+            return undefined;
+        return this.cloneFunnel(funnel);
+    }
+    getAllFunnels() {
+        const result = new Map();
+        for (const [k, v] of this.funnels) {
+            result.set(k, v.map(stage => ({ ...stage })));
+        }
+        return result;
+    }
+    getAllFunnelsWithPolicy() {
+        const result = new Map();
+        for (const [k, v] of this.fullFunnels) {
+            result.set(k, this.cloneFunnel(v));
+        }
+        return result;
+    }
+    getWarnings() {
+        return [...this.warnings];
+    }
+    getConfigPath() {
+        return this.configPath;
+    }
+    cloneFunnel(funnel) {
+        return {
+            ...funnel,
+            stages: funnel.stages.map(stage => ({ ...stage })),
+            policy: funnel.policy ? {
+                ...funnel.policy,
+                observability: funnel.policy.observability ? {
+                    ...funnel.policy.observability,
+                    emitEvents: funnel.policy.observability.emitEvents
+                        ? [...funnel.policy.observability.emitEvents]
+                        : undefined,
+                } : undefined,
+            } : undefined,
+        };
+    }
+}

package/dist/core/workspace-context.d.ts

@@ -0,0 +1,111 @@
+import type { PD_FILES } from './paths.js';
+import type { PainConfig } from './config.js';
+import type { EventLog } from './event-log.js';
+import type { PainDictionary } from './dictionary.js';
+import { HygieneTracker } from './hygiene/tracker.js';
+import { EvolutionReducerImpl } from './evolution-reducer.js';
+import type { TrajectoryDatabase } from './trajectory.js';
+import { PrincipleLifecycleService } from './principle-internalization/principle-lifecycle-service.js';
+import { type PrincipleSubtree } from './principle-tree-ledger.js';
+import type { Principle, PrincipleValueMetrics } from '../types/principle-tree-schema.js';
+import type { Principle as ActivePrinciple } from './evolution-types.js';
+interface PrincipleTreeLedgerAccessor {
+    getPrincipleSubtree(_principleId: string): PrincipleSubtree | undefined;
+    updatePrinciple(_principleId: string, updates: Partial<Principle>): Principle;
+    updatePrincipleValueMetrics(principleId: string, _metrics: PrincipleValueMetrics): PrincipleValueMetrics;
+}
+/**
+ * WorkspaceContext - Centralized management of workspace-specific paths and services.
+ * Implements a cached singleton pattern per workspace directory.
+ */
+export declare class WorkspaceContext {
+    private static readonly instances;
+    private static readonly pathResolver;
+    readonly workspaceDir: string;
+    readonly stateDir: string;
+    private _config?;
+    private _eventLog?;
+    private _dictionary?;
+    private _hygiene?;
+    private _evolutionReducer?;
+    private _trajectory?;
+    private _principleTreeLedger?;
+    private _principleLifecycle?;
+    private constructor();
+    /**
+     * Governance configuration for this workspace.
+     */
+    get config(): PainConfig;
+    /**
+     * Event logging service for this workspace.
+     */
+    get eventLog(): EventLog;
+    /**
+     * Pain dictionary service for this workspace.
+     */
+    get dictionary(): PainDictionary;
+    /**
+     * Hygiene tracking service for this workspace.
+     */
+    get hygiene(): HygieneTracker;
+    /**
+     * Evolution reducer singleton for this workspace.
+     */
+    get evolutionReducer(): EvolutionReducerImpl;
+    /**
+     * Trajectory database for analytics and sample curation.
+     */
+    get trajectory(): TrajectoryDatabase;
+    /**
+     * Locked ledger access for principle tree reads and metric writes in this workspace.
+     */
+    get principleTreeLedger(): PrincipleTreeLedgerAccessor;
+    /**
+     * Phase 15 lifecycle/read-model surface for metrics, assessments, and route recommendations.
+     */
+    get principleLifecycle(): PrincipleLifecycleService;
+    /**
+     * Retrieve active Principle -> Rule -> Implementation subtrees without bypassing reducer authority.
+     */
+    getActivePrincipleSubtrees(): {
+        principle: ActivePrinciple;
+        subtree: PrincipleSubtree;
+    }[];
+    private getTrajectoryOptions;
+    /**
+     * Creates or retrieves a WorkspaceContext instance from an OpenClaw hook context.
+     * Uses PathResolver to handle path normalization and fallback logic.
+     * @throws Error if workspaceDir is missing and no fallback available.
+     */
+    static fromHookContext(ctx: any): WorkspaceContext;
+    /**
+     * Creates a WorkspaceContext requiring explicit workspaceDir.
+     * For Runtime V2 entrypoints where implicit PathResolver fallback is unacceptable.
+     * @throws Error if workspaceDir is not provided in the context.
+     */
+    static fromHookContextExplicit(ctx: {
+        workspaceDir?: string;
+        logger?: {
+            error?: (...args: unknown[]) => void;
+            warn?: (...args: unknown[]) => void;
+            info?: (...args: unknown[]) => void;
+        };
+    }): WorkspaceContext;
+    /**
+     * Resolves a PD file path within the workspace.
+     */
+    resolve(fileKey: keyof typeof PD_FILES): string;
+    /**
+     * Resets internal caches for services and paths.
+     */
+    invalidate(): void;
+    /**
+     * Removes a workspace from the cache.
+     */
+    static dispose(workspaceDir: string): void;
+    /**
+     * Clears the instance cache (primarily for testing).
+     */
+    static clearCache(): void;
+}
+export {};

package/{src/core/workspace-context.ts → dist/core/workspace-context.js}

@@ -1,235 +1,184 @@
-import type { PD_FILES } from './paths.js';
 import { resolvePdPath } from './paths.js';
 import { PathResolver } from './path-resolver.js';
 import { validateWorkspaceDir } from './workspace-dir-validation.js';
 import { ConfigService } from './config-service.js';
-import type { PainConfig } from './config.js';
-import type { EventLog } from './event-log.js';
 import { EventLogService } from './event-log.js';
 import { DictionaryService } from './dictionary-service.js';
-import type { PainDictionary } from './dictionary.js';
 import { HygieneTracker } from './hygiene/tracker.js';
 import { EvolutionReducerImpl } from './evolution-reducer.js';
-import type { TrajectoryDatabase, TrajectoryDatabaseOptions } from './trajectory.js';
 import { TrajectoryRegistry } from './trajectory.js';
 import { PrincipleLifecycleService } from './principle-internalization/principle-lifecycle-service.js';
-import {
-    getPrincipleSubtree,
-    updatePrinciple,
-    updatePrincipleValueMetrics,
-    type PrincipleSubtree,
-} from './principle-tree-ledger.js';
-import type { Principle, PrincipleValueMetrics } from '../types/principle-tree-schema.js';
-import type { Principle as ActivePrinciple } from './evolution-types.js';
-
- 
-interface PrincipleTreeLedgerAccessor {
-    getPrincipleSubtree(_principleId: string): PrincipleSubtree | undefined;
-    updatePrinciple(_principleId: string, updates: Partial<Principle>): Principle;
-    updatePrincipleValueMetrics(principleId: string, _metrics: PrincipleValueMetrics): PrincipleValueMetrics;
-}
- 
-
+import { getPrincipleSubtree, updatePrinciple, updatePrincipleValueMetrics, } from './principle-tree-ledger.js';
 /**
  * WorkspaceContext - Centralized management of workspace-specific paths and services.
  * Implements a cached singleton pattern per workspace directory.
  */
 export class WorkspaceContext {
-    private static readonly instances = new Map<string, WorkspaceContext>();
-    private static readonly pathResolver = new PathResolver();
-
-    public readonly workspaceDir: string;
-    public readonly stateDir: string;
-
-    private _config?: PainConfig;
-    private _eventLog?: EventLog;
-    private _dictionary?: PainDictionary;
-    private _hygiene?: HygieneTracker;
-    private _evolutionReducer?: EvolutionReducerImpl;
-    private _trajectory?: TrajectoryDatabase;
-    private _principleTreeLedger?: PrincipleTreeLedgerAccessor;
-    private _principleLifecycle?: PrincipleLifecycleService;
-
-    private constructor(workspaceDir: string, stateDir: string) {
+    static instances = new Map();
+    static pathResolver = new PathResolver();
+    workspaceDir;
+    stateDir;
+    _config;
+    _eventLog;
+    _dictionary;
+    _hygiene;
+    _evolutionReducer;
+    _trajectory;
+    _principleTreeLedger;
+    _principleLifecycle;
+    constructor(workspaceDir, stateDir) {
         this.workspaceDir = workspaceDir;
         this.stateDir = stateDir;
     }
-
     /**
      * Governance configuration for this workspace.
      */
-    get config(): PainConfig {
+    get config() {
         if (!this._config) {
             this._config = ConfigService.get(this.stateDir);
         }
         return this._config;
     }
-
     /**
      * Event logging service for this workspace.
      */
-    get eventLog(): EventLog {
+    get eventLog() {
         if (!this._eventLog) {
             this._eventLog = EventLogService.get(this.stateDir);
         }
         return this._eventLog;
     }
-
     /**
      * Pain dictionary service for this workspace.
      */
-    get dictionary(): PainDictionary {
+    get dictionary() {
         if (!this._dictionary) {
             this._dictionary = DictionaryService.get(this.stateDir);
         }
         return this._dictionary;
     }
-
     /**
      * Hygiene tracking service for this workspace.
      */
-    get hygiene(): HygieneTracker {
+    get hygiene() {
         if (!this._hygiene) {
             this._hygiene = new HygieneTracker(this.stateDir);
         }
         return this._hygiene;
     }
-
-
     /**
      * Evolution reducer singleton for this workspace.
      */
-    get evolutionReducer(): EvolutionReducerImpl {
+    get evolutionReducer() {
         if (!this._evolutionReducer) {
             this._evolutionReducer = new EvolutionReducerImpl({ workspaceDir: this.workspaceDir, stateDir: this.stateDir });
         }
         return this._evolutionReducer;
     }
-
     /**
      * Trajectory database for analytics and sample curation.
      */
-    get trajectory(): TrajectoryDatabase {
+    get trajectory() {
         if (!this._trajectory) {
             this._trajectory = TrajectoryRegistry.get(this.workspaceDir, this.getTrajectoryOptions());
         }
         return this._trajectory;
     }
-
     /**
      * Locked ledger access for principle tree reads and metric writes in this workspace.
      */
-    get principleTreeLedger(): PrincipleTreeLedgerAccessor {
+    get principleTreeLedger() {
         if (!this._principleTreeLedger) {
             this._principleTreeLedger = {
-                getPrincipleSubtree: (principleId: string) => getPrincipleSubtree(this.stateDir, principleId),
-                updatePrinciple: (principleId: string, updates: Partial<Principle>) =>
-                    updatePrinciple(this.stateDir, principleId, updates),
-                updatePrincipleValueMetrics: (principleId: string, metrics: PrincipleValueMetrics) =>
-                    updatePrincipleValueMetrics(this.stateDir, principleId, metrics),
+                getPrincipleSubtree: (principleId) => getPrincipleSubtree(this.stateDir, principleId),
+                updatePrinciple: (principleId, updates) => updatePrinciple(this.stateDir, principleId, updates),
+                updatePrincipleValueMetrics: (principleId, metrics) => updatePrincipleValueMetrics(this.stateDir, principleId, metrics),
             };
         }
         return this._principleTreeLedger;
     }
-
     /**
      * Phase 15 lifecycle/read-model surface for metrics, assessments, and route recommendations.
      */
-    get principleLifecycle(): PrincipleLifecycleService {
+    get principleLifecycle() {
         if (!this._principleLifecycle) {
             this._principleLifecycle = new PrincipleLifecycleService(this.workspaceDir, this.stateDir);
         }
         return this._principleLifecycle;
     }
-
     /**
      * Retrieve active Principle -> Rule -> Implementation subtrees without bypassing reducer authority.
      */
-    getActivePrincipleSubtrees(): { principle: ActivePrinciple; subtree: PrincipleSubtree }[] {
+    getActivePrincipleSubtrees() {
         return this.evolutionReducer
             .getActivePrinciples()
             .map((principle) => {
-                const subtree = this.principleTreeLedger.getPrincipleSubtree(principle.id);
-                return subtree ? { principle, subtree } : null;
-            })
-            .filter(
-                (entry): entry is { principle: ActivePrinciple; subtree: PrincipleSubtree } => entry !== null,
-            );
+            const subtree = this.principleTreeLedger.getPrincipleSubtree(principle.id);
+            return subtree ? { principle, subtree } : null;
+        })
+            .filter((entry) => entry !== null);
     }
-
-    private getTrajectoryOptions(): Omit<TrajectoryDatabaseOptions, 'workspaceDir'> {
+    getTrajectoryOptions() {
         const inlineThreshold = Number(this.config.get('trajectory.blob_inline_threshold_bytes'));
         const busyTimeoutMs = Number(this.config.get('trajectory.busy_timeout_ms'));
         const orphanBlobGraceDays = Number(this.config.get('trajectory.orphan_blob_grace_days'));
-
         return {
             blobInlineThresholdBytes: Number.isFinite(inlineThreshold) && inlineThreshold > 0 ? inlineThreshold : undefined,
             busyTimeoutMs: Number.isFinite(busyTimeoutMs) && busyTimeoutMs >= 0 ? busyTimeoutMs : undefined,
             orphanBlobGraceDays: Number.isFinite(orphanBlobGraceDays) && orphanBlobGraceDays >= 0 ? orphanBlobGraceDays : undefined,
         };
     }
-
     /**
      * Creates or retrieves a WorkspaceContext instance from an OpenClaw hook context.
      * Uses PathResolver to handle path normalization and fallback logic.
      * @throws Error if workspaceDir is missing and no fallback available.
      */
-     
-    static fromHookContext(ctx: any): WorkspaceContext {
-        const {logger} = ctx;
-        const log = (msg: string) => logger?.info?.(msg);
-        const logWarn = (msg: string) => logger?.warn?.(msg);
-
-        let {workspaceDir} = ctx;
-        
+    static fromHookContext(ctx) {
+        const { logger } = ctx;
+        const log = (msg) => logger?.info?.(msg);
+        const logWarn = (msg) => logger?.warn?.(msg);
+        let { workspaceDir } = ctx;
         if (!workspaceDir) {
             logWarn('[PD:WorkspaceContext] workspaceDir not provided in context, using PathResolver fallback');
             workspaceDir = this.pathResolver.getWorkspaceDir();
             log(`[PD:WorkspaceContext] Resolved workspaceDir to: ${workspaceDir}`);
-        } else {
+        }
+        else {
             const normalized = this.pathResolver.normalizeWorkspacePath(workspaceDir);
             if (normalized !== workspaceDir) {
                 log(`[PD:WorkspaceContext] Normalized workspaceDir: ${workspaceDir} -> ${normalized}`);
                 workspaceDir = normalized;
             }
         }
-
         const validationIssue = validateWorkspaceDir(workspaceDir);
         if (validationIssue !== null) {
-            logWarn(
-                `[PD:WorkspaceContext] LEGACY_PATH_RESOLVER_FALLBACK: ${validationIssue}. ` +
-                'This is a legacy discovery path; explicit workspaceDir should be provided in the hook context.',
-            );
+            logWarn(`[PD:WorkspaceContext] LEGACY_PATH_RESOLVER_FALLBACK: ${validationIssue}. ` +
+                'This is a legacy discovery path; explicit workspaceDir should be provided in the hook context.');
         }
-
         const existing = this.instances.get(workspaceDir);
-        if (existing) return existing;
-
-        let {stateDir} = ctx;
+        if (existing)
+            return existing;
+        let { stateDir } = ctx;
         if (!stateDir) {
             stateDir = resolvePdPath(workspaceDir, 'STATE_DIR');
             log(`[PD:WorkspaceContext] Computed stateDir: ${stateDir}`);
         }
-
         const instance = new WorkspaceContext(workspaceDir, stateDir);
         this.instances.set(workspaceDir, instance);
-        
         log(`[PD:WorkspaceContext] Created new context for workspace: ${workspaceDir}`);
-        
         return instance;
     }
-
     /**
      * Creates a WorkspaceContext requiring explicit workspaceDir.
      * For Runtime V2 entrypoints where implicit PathResolver fallback is unacceptable.
      * @throws Error if workspaceDir is not provided in the context.
      */
-    static fromHookContextExplicit(ctx: { workspaceDir?: string; logger?: { error?: (...args: unknown[]) => void; warn?: (...args: unknown[]) => void; info?: (...args: unknown[]) => void } }): WorkspaceContext {
+    static fromHookContextExplicit(ctx) {
         const { logger } = ctx;
         let { workspaceDir } = ctx;
         if (!workspaceDir || !workspaceDir.trim()) {
             const error = {
-                ok: false as const,
+                ok: false,
                 reason: 'workspace_dir_missing',
                 message: 'workspaceDir is required for Runtime V2 entrypoints. Provide it explicitly in the hook context.',
                 nextAction: 'Ensure the OpenClaw hook context includes workspaceDir, or use PD_WORKSPACE_DIR env var.',
@@ -245,7 +194,7 @@ export class WorkspaceContext {
         const validationIssue = validateWorkspaceDir(workspaceDir);
         if (validationIssue !== null) {
             const error = {
-                ok: false as const,
+                ok: false,
                 reason: 'workspace_dir_invalid',
                 message: `workspaceDir validation failed for Runtime V2 entrypoint: ${validationIssue}`,
                 nextAction: 'Provide a valid workspaceDir that is not the home directory, root, or empty.',
@@ -255,18 +204,16 @@ export class WorkspaceContext {
         }
         return this.fromHookContext({ ...ctx, workspaceDir });
     }
-
     /**
      * Resolves a PD file path within the workspace.
      */
-    resolve(fileKey: keyof typeof PD_FILES): string {
+    resolve(fileKey) {
         return resolvePdPath(this.workspaceDir, fileKey);
     }
-
     /**
      * Resets internal caches for services and paths.
      */
-    invalidate(): void {
+    invalidate() {
         this._config = undefined;
         this._eventLog = undefined;
         this._dictionary = undefined;
@@ -275,11 +222,10 @@ export class WorkspaceContext {
         this._principleTreeLedger = undefined;
         this._principleLifecycle = undefined;
     }
-
     /**
      * Removes a workspace from the cache.
      */
-    static dispose(workspaceDir: string): void {
+    static dispose(workspaceDir) {
         const normalized = this.pathResolver.normalizeWorkspacePath(workspaceDir);
         const instance = this.instances.get(normalized);
         if (instance) {
@@ -288,11 +234,10 @@ export class WorkspaceContext {
         }
         TrajectoryRegistry.dispose(normalized);
     }
-
     /**
      * Clears the instance cache (primarily for testing).
      */
-    static clearCache(): void {
+    static clearCache() {
         for (const instance of this.instances.values()) {
             instance.invalidate();
         }

package/dist/core/workspace-dir-validation.d.ts

@@ -0,0 +1,11 @@
+/**
+ * WorkspaceDir Validation Utilities
+ *
+ * This module only validates candidate workspace directories. Runtime hook
+ * resolution policy lives at the I/O boundary in utils/workspace-resolver.ts.
+ */
+export interface WorkspaceResolutionContext {
+    workspaceDir?: string;
+    agentId?: string;
+}
+export declare function validateWorkspaceDir(dir: string | undefined): string | null;