create-principles-disciple 1.104.2 → 1.105.0

package/host-runtime/dist/index.js

@@ -0,0 +1,148 @@
+import { isHostEvent, isHostEventResult, } from '@principles/core/host';
+import { buildActivePrinciplePromptContext } from './active-principle-prompt.js';
+import { createProductionRuleHostGate } from './production-rulehost-gate.js';
+import { createProductionPainEvidenceHandler } from './production-pain-evidence.js';
+export * from './active-principle-prompt.js';
+export * from './pd-config.js';
+export * from './production-rulehost-gate.js';
+export * from './rule-implementation-runtime.js';
+export * from './production-pain-evidence.js';
+export const HOST_RUNTIME_ROUTES = [
+    'before_prompt_build',
+    'before_tool_call',
+    'after_tool_call',
+];
+export class HostRuntimeDispatchError extends Error {
+    reason;
+    nextAction;
+    constructor(reason, nextAction) {
+        super(`${reason}: ${nextAction}`);
+        this.reason = reason;
+        this.nextAction = nextAction;
+        this.name = 'HostRuntimeDispatchError';
+    }
+}
+function portFor(event, options) {
+    switch (event.kind) {
+        case 'before_prompt_build':
+            return options.beforePromptBuild;
+        case 'before_tool_call':
+            return options.beforeToolCall;
+        case 'after_tool_call':
+            return options.afterToolCall;
+        default:
+            throw new HostRuntimeDispatchError('unsupported_host_event', `Only ${HOST_RUNTIME_ROUTES.join(', ')} are supported by the MVP host runtime`);
+    }
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+function isAbsoluteWorkspace(value) {
+    return value.startsWith('/') || value.startsWith('\\\\') || /^[A-Za-z]:[\\/]/.test(value);
+}
+function hasValidRouteSemantics(event) {
+    if (!isNonEmptyString(event.context.workspaceDir) || !isAbsoluteWorkspace(event.context.workspaceDir))
+        return false;
+    if (!isNonEmptyString(event.context.sessionId) || !isNonEmptyString(event.source))
+        return false;
+    if (event.kind === 'before_tool_call' || event.kind === 'after_tool_call') {
+        return isNonEmptyString(event.context.toolName);
+    }
+    return true;
+}
+function hasNonEmptyOptionalString(value) {
+    return value === undefined || isNonEmptyString(value);
+}
+function hasValidResultSemantics(event, result) {
+    if (result.warnings !== undefined && (!Array.isArray(result.warnings) || !result.warnings.every(isNonEmptyString)))
+        return false;
+    if (result.metadata !== undefined && (typeof result.metadata !== 'object' || result.metadata === null || Array.isArray(result.metadata)))
+        return false;
+    if (!isNonEmptyString(result.source) || !hasNonEmptyOptionalString(result.reason) || !hasNonEmptyOptionalString(result.additionalContext)) {
+        return false;
+    }
+    const hasReason = result.reason !== undefined;
+    const hasModifiedInput = result.modifiedInput !== undefined;
+    const hasAdditionalContext = result.additionalContext !== undefined;
+    switch (event.kind) {
+        case 'before_prompt_build':
+            return (result.decision === 'allow' || result.decision === 'modify') && !hasReason && !hasModifiedInput;
+        case 'before_tool_call':
+            if (result.decision === 'observe')
+                return false;
+            if (result.decision === 'deny')
+                return hasReason && !hasModifiedInput && !hasAdditionalContext;
+            if (hasReason)
+                return false;
+            return !hasModifiedInput || result.decision === 'modify';
+        case 'after_tool_call':
+            return result.decision === 'observe' && !hasReason && !hasModifiedInput && !hasAdditionalContext;
+        default:
+            return false;
+    }
+}
+export function createHostRuntime(options) {
+    return {
+        async dispatch(event) {
+            if (!isHostEvent(event) || !hasValidRouteSemantics(event)) {
+                throw new HostRuntimeDispatchError('invalid_host_event', 'Decode and validate the host event before dispatch');
+            }
+            const result = await portFor(event, options)(event);
+            if (!isHostEventResult(result) || !hasValidResultSemantics(event, result)) {
+                throw new HostRuntimeDispatchError('invalid_handler_result', `Handler for ${event.kind} must return a valid HostEventResult`);
+            }
+            if (result.source !== event.source) {
+                throw new HostRuntimeDispatchError('lineage_mismatch', `Handler result source must match event source ${event.source}`);
+            }
+            return result;
+        },
+        async health(workspaceDir) {
+            if (workspaceDir.trim().length === 0) {
+                return {
+                    ok: false,
+                    workspaceDir,
+                    routes: HOST_RUNTIME_ROUTES,
+                    reason: 'workspace_dir_missing',
+                    nextAction: 'Resolve an absolute workspace directory before probing host runtime health',
+                };
+            }
+            if (!isAbsoluteWorkspace(workspaceDir)) {
+                return {
+                    ok: false,
+                    workspaceDir,
+                    routes: HOST_RUNTIME_ROUTES,
+                    reason: 'workspace_dir_invalid',
+                    nextAction: 'Resolve an absolute workspace directory before probing host runtime health',
+                };
+            }
+            return { ok: true, workspaceDir, routes: HOST_RUNTIME_ROUTES };
+        },
+    };
+}
+export function createProductionHostRuntime(options = {}) {
+    const productionGate = createProductionRuleHostGate({
+        ...(options.ruleContextProvider ? { ruleContextProvider: options.ruleContextProvider } : {}),
+        ...(options.ruleInputEnrichmentProvider ? { ruleInputEnrichmentProvider: options.ruleInputEnrichmentProvider } : {}),
+        ...(options.ruleImplementationRuntime ? { implementationRuntime: options.ruleImplementationRuntime } : {}),
+    });
+    return createHostRuntime({
+        afterToolCall: options.afterToolCall ?? createProductionPainEvidenceHandler({
+            ...(options.painEnrichmentProvider ? { painEnrichmentProvider: options.painEnrichmentProvider } : {}),
+            ...(options.painDatabaseFactory ? { painDatabaseFactory: options.painDatabaseFactory } : {}),
+        }),
+        beforeToolCall: options.beforeToolCall ?? productionGate,
+        async beforePromptBuild(event) {
+            const prompt = await buildActivePrinciplePromptContext({
+                workspaceDir: event.context.workspaceDir,
+                excludePrincipleIds: options.promptExcludePrincipleIds?.(event),
+            });
+            if (options.beforePromptBuild)
+                return options.beforePromptBuild(event, prompt);
+            return {
+                decision: prompt.additionalContext.length > 0 ? 'modify' : 'allow',
+                source: event.source,
+                ...(prompt.additionalContext.length > 0 ? { additionalContext: prompt.additionalContext } : {}),
+            };
+        },
+    });
+}

package/host-runtime/dist/pd-config.d.ts

@@ -0,0 +1,36 @@
+import { type EffectivePdConfig } from '@principles/core/runtime-v2';
+export declare const PD_CONFIG_DIR = ".pd";
+export declare const PD_CONFIG_FILENAME = "config.yaml";
+export interface PluginConfigLoadResult {
+    ok: boolean;
+    effective: EffectivePdConfig;
+    source: 'defaults' | 'user_config' | 'malformed';
+    configPath: string;
+    warnings: string[];
+    errors: {
+        path: string;
+        reason: string;
+        nextAction: string;
+    }[];
+}
+export type PdWorkspaceResolution = {
+    ok: true;
+    workspaceDir: string;
+    configPath: string;
+    source: 'nearest' | 'legacy_fallback';
+} | {
+    ok: false;
+    cwd: string;
+    reason: 'cwd_not_absolute' | 'config_not_found';
+    nextAction: string;
+};
+export declare function getPdConfigPath(workspaceDir: string): string;
+export declare function resolveNearestPdWorkspace(cwd: string, legacyFallback?: string): PdWorkspaceResolution;
+export declare function loadPdConfigForPlugin(workspaceDir: string): PluginConfigLoadResult;
+export declare function loadFeatureFlagFromConfig(workspaceDir: string, flagId: string, logger?: {
+    warn?: (message: string) => void;
+    info?: (message: string) => void;
+}): {
+    enabled: boolean;
+    source: string;
+};

package/host-runtime/dist/pd-config.js

@@ -0,0 +1,98 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import * as yaml from 'js-yaml';
+import { computeEffectivePdConfig, computeFeatureFlagsFromConfig, validatePdConfig, } from '@principles/core/runtime-v2';
+export const PD_CONFIG_DIR = '.pd';
+export const PD_CONFIG_FILENAME = 'config.yaml';
+export function getPdConfigPath(workspaceDir) {
+    return path.join(workspaceDir, PD_CONFIG_DIR, PD_CONFIG_FILENAME);
+}
+/**
+ * A config candidate counts only when stat still sees a regular file.
+ * stat alone (no existsSync+stat pair) closes the TOCTOU window: the
+ * installer replaces .pd/config.yaml via atomic rename, and a hook that
+ * resolves the workspace mid-replacement would otherwise see exists=true
+ * then throw from statSync — crashing the hook before its fail-open
+ * handling instead of returning a structured resolution result.
+ */
+function isConfigFileAt(dir) {
+    try {
+        return fs.statSync(getPdConfigPath(dir)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+export function resolveNearestPdWorkspace(cwd, legacyFallback) {
+    if (!path.isAbsolute(cwd)) {
+        return { ok: false, cwd, reason: 'cwd_not_absolute', nextAction: 'Provide an absolute cwd before resolving the PD Workspace' };
+    }
+    let current = path.resolve(cwd);
+    while (true) {
+        if (isConfigFileAt(current)) {
+            return { ok: true, workspaceDir: current, configPath: getPdConfigPath(current), source: 'nearest' };
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    if (legacyFallback && path.isAbsolute(legacyFallback)) {
+        const workspaceDir = path.resolve(legacyFallback);
+        if (isConfigFileAt(workspaceDir)) {
+            return { ok: true, workspaceDir, configPath: getPdConfigPath(workspaceDir), source: 'legacy_fallback' };
+        }
+    }
+    return {
+        ok: false,
+        cwd,
+        reason: 'config_not_found',
+        nextAction: 'Create .pd/config.yaml in the Workspace or provide an absolute legacy fallback containing it',
+    };
+}
+export function loadPdConfigForPlugin(workspaceDir) {
+    const configPath = getPdConfigPath(workspaceDir);
+    if (!fs.existsSync(configPath)) {
+        const effective = computeEffectivePdConfig(null);
+        return { ok: true, effective, source: 'defaults', configPath, warnings: effective.warnings, errors: [] };
+    }
+    let raw;
+    try {
+        raw = fs.readFileSync(configPath, 'utf8');
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            ok: false, effective: computeEffectivePdConfig(null), source: 'malformed', configPath, warnings: [],
+            errors: [{ path: '', reason: `Failed to read .pd/config.yaml: ${message}`, nextAction: 'Check file permissions for .pd/config.yaml' }],
+        };
+    }
+    let parsed;
+    try {
+        parsed = yaml.load(raw, { schema: yaml.JSON_SCHEMA });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            ok: false, effective: computeEffectivePdConfig(null), source: 'malformed', configPath, warnings: [],
+            errors: [{ path: '', reason: `YAML parse error in .pd/config.yaml: ${message}`, nextAction: 'Fix YAML syntax in .pd/config.yaml' }],
+        };
+    }
+    const validation = validatePdConfig(parsed);
+    if (!validation.ok) {
+        return {
+            ok: false, effective: computeEffectivePdConfig(null), source: 'malformed', configPath, warnings: [],
+            errors: validation.errors.map(({ path: errorPath, reason, nextAction }) => ({ path: errorPath, reason, nextAction })),
+        };
+    }
+    const effective = computeEffectivePdConfig(validation.value);
+    return { ok: true, effective, source: 'user_config', configPath, warnings: effective.warnings, errors: [] };
+}
+export function loadFeatureFlagFromConfig(workspaceDir, flagId, logger) {
+    const result = loadPdConfigForPlugin(workspaceDir);
+    const flag = computeFeatureFlagsFromConfig(result.effective).flags[flagId];
+    if (!result.ok) {
+        logger?.warn?.(`[PD:Config] Config validation failed: ${result.errors.map((error) => error.reason).join('; ')} — using defaults`);
+    }
+    return { enabled: flag?.enabled ?? false, source: result.source };
+}

package/host-runtime/dist/production-pain-evidence.d.ts

@@ -0,0 +1,24 @@
+import Database from 'better-sqlite3';
+import type { HostEvent, HostEventResult } from '@principles/core/host';
+export interface PainEvidenceEntry {
+    sourceRef: string;
+    note: string;
+}
+export interface ProductionPainEnrichment {
+    eventId?: string;
+    painScore?: number;
+    isRisky?: boolean;
+    consecutiveErrors?: number;
+    relativePath?: string;
+    agentId?: string;
+    errorHash?: string;
+    evidence?: readonly PainEvidenceEntry[];
+}
+export type PainEnrichmentProvider = (event: HostEvent) => unknown | Promise<unknown>;
+export type PainDatabaseFactory = (databasePath: string) => Database.Database;
+export declare function createProductionPainEvidenceHandler(options?: {
+    painEnrichmentProvider?: PainEnrichmentProvider;
+    painDatabaseFactory?: PainDatabaseFactory;
+}): (event: HostEvent) => Promise<HostEventResult>;
+export declare function resetProductionPainCooldownForTest(): void;
+export declare function productionPainCooldownEntryCountForTest(): number;

package/host-runtime/dist/production-pain-evidence.js

@@ -0,0 +1,293 @@
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import Database from 'better-sqlite3';
+import { buildToolFailureObservation, evaluateTriage, evaluateTriggerController, resolveSourceKind, sanitizeToolParams, sanitizeValue, } from '@principles/core/runtime-v2';
+const WRITE_TOOLS = new Set(['write', 'edit', 'apply_patch', 'write_file', 'edit_file', 'replace']);
+const MAX_PREVIEW = 500;
+const PAIN_COOLDOWN_WINDOW_MS = 15 * 60 * 1000;
+const cooldowns = new Map();
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function field(value, key) {
+    if (!isRecord(value) || !Object.hasOwn(value, key))
+        return undefined;
+    return Object.getOwnPropertyDescriptor(value, key)?.value;
+}
+function normalizeOutcome(event) {
+    const envelope = event.context.toolOutput;
+    const result = field(envelope, 'result') ?? envelope;
+    const errorValue = field(envelope, 'error');
+    const resultExit = field(result, 'exitCode');
+    const detailsExit = field(field(result, 'details'), 'exitCode');
+    const exitCode = typeof resultExit === 'number' ? resultExit : typeof detailsExit === 'number' ? detailsExit : 0;
+    const error = errorValue === undefined || errorValue === null || errorValue === '' ? undefined : String(errorValue);
+    const durationValue = field(envelope, 'durationMs');
+    return {
+        failure: error !== undefined || exitCode !== 0,
+        exitCode,
+        ...(error ? { error: error.slice(0, MAX_PREVIEW) } : {}),
+        ...(typeof durationValue === 'number' && Number.isFinite(durationValue) && durationValue >= 0 ? { durationMs: durationValue } : {}),
+        params: event.context.toolInput ?? {},
+        result,
+    };
+}
+function isEvidence(value) {
+    return Array.isArray(value) && value.length <= 8 && value.every((entry) => isRecord(entry) && typeof field(entry, 'sourceRef') === 'string' && String(field(entry, 'sourceRef')).trim().length > 0
+        && String(field(entry, 'sourceRef')).length <= 300 && typeof field(entry, 'note') === 'string' && String(field(entry, 'note')).length <= 200);
+}
+function parseEnrichment(value) {
+    if (value === undefined)
+        return {};
+    if (!isRecord(value))
+        return null;
+    const painScore = field(value, 'painScore');
+    const isRisky = field(value, 'isRisky');
+    const consecutiveErrors = field(value, 'consecutiveErrors');
+    const evidence = field(value, 'evidence');
+    const eventId = field(value, 'eventId');
+    const relativePath = field(value, 'relativePath');
+    const agentId = field(value, 'agentId');
+    const errorHash = field(value, 'errorHash');
+    if (painScore !== undefined && (typeof painScore !== 'number' || !Number.isFinite(painScore) || painScore < 0 || painScore > 100))
+        return null;
+    if (isRisky !== undefined && typeof isRisky !== 'boolean')
+        return null;
+    if (consecutiveErrors !== undefined && (typeof consecutiveErrors !== 'number' || !Number.isInteger(consecutiveErrors) || consecutiveErrors < 0))
+        return null;
+    for (const key of ['eventId', 'relativePath', 'agentId', 'errorHash']) {
+        const candidate = field(value, key);
+        if (candidate !== undefined && (typeof candidate !== 'string' || candidate.trim().length === 0 || candidate.length > 500))
+            return null;
+    }
+    if (evidence !== undefined && !isEvidence(evidence))
+        return null;
+    return {
+        ...(typeof eventId === 'string' ? { eventId } : {}),
+        ...(typeof painScore === 'number' ? { painScore } : {}),
+        ...(typeof isRisky === 'boolean' ? { isRisky } : {}),
+        ...(typeof consecutiveErrors === 'number' ? { consecutiveErrors } : {}),
+        ...(typeof relativePath === 'string' ? { relativePath } : {}),
+        ...(typeof agentId === 'string' ? { agentId } : {}),
+        ...(typeof errorHash === 'string' ? { errorHash } : {}),
+        ...(isEvidence(evidence) ? { evidence } : {}),
+    };
+}
+function stable(value, seen = new WeakSet()) {
+    if (value === null || typeof value !== 'object') {
+        if (typeof value === 'string')
+            return JSON.stringify(value.slice(0, 2_000));
+        if (typeof value === 'number' || typeof value === 'boolean')
+            return JSON.stringify(value);
+        return JSON.stringify(String(value));
+    }
+    if (seen.has(value))
+        return '"[circular]"';
+    seen.add(value);
+    if (Array.isArray(value))
+        return `[${value.slice(0, 50).map((item) => stable(item, seen)).join(',')}]`;
+    const keys = Object.keys(value).sort().slice(0, 50);
+    return `{${keys.map((key) => `${JSON.stringify(key)}:${stable(field(value, key), seen)}`).join(',')}}`;
+}
+function preview(value) {
+    try {
+        const text = stable(value);
+        return text.length > MAX_PREVIEW ? `${text.slice(0, MAX_PREVIEW - 3)}...` : text;
+    }
+    catch {
+        return '[result_preview_unavailable]';
+    }
+}
+function ids(input) {
+    const { event, outcome, sanitizedParams, canonicalEventId } = input;
+    const canonical = stable({
+        workspaceDir: path.resolve(event.context.workspaceDir),
+        sessionId: event.context.sessionId,
+        turnId: event.context.turnId ?? null,
+        toolName: event.context.toolName,
+        source: event.source,
+        suppliedEventId: canonicalEventId ?? null,
+        params: sanitizedParams,
+        result: sanitizeValue(outcome.result, 0, event.context.workspaceDir),
+        error: outcome.error ?? null,
+        exitCode: outcome.exitCode,
+        failure: outcome.failure,
+    });
+    const digest = createHash('sha256').update(canonical).digest('hex');
+    return { eventId: `host_${digest}`, painId: `pain_host_${digest}` };
+}
+const REQUIRED_COLUMNS = {
+    sessions: { session_id: 'TEXT', started_at: 'TEXT', updated_at: 'TEXT' },
+    tool_calls: { session_id: 'TEXT', tool_name: 'TEXT', outcome: 'TEXT', duration_ms: 'INTEGER', exit_code: 'INTEGER', error_type: 'TEXT', error_message: 'TEXT', gfi_before: 'REAL', gfi_after: 'REAL', params_json: 'TEXT', result_preview: 'TEXT', created_at: 'TEXT' },
+    pain_events: { session_id: 'TEXT', source: 'TEXT', score: 'REAL', reason: 'TEXT', severity: 'TEXT', origin: 'TEXT', confidence: 'REAL', text: 'TEXT', canonical_pain_id: 'TEXT', runtime_task_id: 'TEXT', created_at: 'TEXT' },
+};
+function pragmaField(row, key) {
+    return isRecord(row) && Object.hasOwn(row, key) ? Object.getOwnPropertyDescriptor(row, key)?.value : undefined;
+}
+function hasCanonicalIndexPredicate(db) {
+    const row = db.prepare("SELECT sql FROM sqlite_master WHERE type = 'index' AND name = ?").get('idx_pain_events_canonical_pain_id');
+    const sql = pragmaField(row, 'sql');
+    if (typeof sql !== 'string' || sql.length === 0 || sql.length > 2_000)
+        return false;
+    const normalized = sql
+        .replace(/["'`]/g, '')
+        .replace(/\[|\]/g, '')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .replace(/;$/, '')
+        .toUpperCase();
+    const whereIndex = normalized.indexOf(' WHERE ');
+    return whereIndex >= 0 && normalized.slice(whereIndex + 7) === 'CANONICAL_PAIN_ID IS NOT NULL';
+}
+function hasCanonicalSchema(db) {
+    for (const [table, required] of Object.entries(REQUIRED_COLUMNS)) {
+        const rows = db.prepare(`PRAGMA table_info(${table})`).all();
+        const actual = new Map();
+        for (const row of rows) {
+            const name = pragmaField(row, 'name');
+            const type = pragmaField(row, 'type');
+            if (typeof name !== 'string' || typeof type !== 'string')
+                return false;
+            actual.set(name, type.toUpperCase());
+        }
+        for (const [name, type] of Object.entries(required)) {
+            if (actual.get(name) !== type)
+                return false;
+        }
+    }
+    const indexes = db.prepare('PRAGMA index_list(pain_events)').all();
+    const canonical = indexes.find((row) => pragmaField(row, 'name') === 'idx_pain_events_canonical_pain_id');
+    if (pragmaField(canonical, 'unique') !== 1 || pragmaField(canonical, 'partial') !== 1)
+        return false;
+    if (!hasCanonicalIndexPredicate(db))
+        return false;
+    const indexColumns = db.prepare('PRAGMA index_info(idx_pain_events_canonical_pain_id)').all();
+    if (indexColumns.length !== 1 || pragmaField(indexColumns[0], 'name') !== 'canonical_pain_id')
+        return false;
+    // Preparing the exact production statements proves syntax/column readiness
+    // without executing mutation or invoking host enrichment side effects.
+    db.prepare('SELECT 1 FROM tool_calls WHERE session_id = ? AND tool_name = ? AND params_json = ? AND outcome = ? AND exit_code IS ? AND error_message IS ? AND result_preview IS ?');
+    db.prepare('SELECT 1 FROM pain_events WHERE canonical_pain_id = ?');
+    db.prepare('INSERT INTO sessions (session_id, started_at, updated_at) VALUES (?, ?, ?) ON CONFLICT(session_id) DO UPDATE SET updated_at = excluded.updated_at');
+    db.prepare('INSERT INTO tool_calls (session_id, tool_name, outcome, duration_ms, exit_code, error_type, error_message, gfi_before, gfi_after, params_json, result_preview, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)');
+    db.prepare('INSERT INTO pain_events (session_id, source, score, reason, severity, origin, confidence, text, canonical_pain_id, runtime_task_id, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)');
+    return true;
+}
+export function createProductionPainEvidenceHandler(options = {}) {
+    return async (event) => {
+        const dbPath = path.join(event.context.workspaceDir, '.state', 'trajectory.db');
+        if (!fs.existsSync(dbPath)) {
+            return { decision: 'observe', source: event.source, warnings: ['trajectory_db_not_found'], metadata: { outcome: 'unavailable', admitted: false, duplicate: false, nextAction: 'initialize the selected PD workspace before retrying the hook' } };
+        }
+        let db;
+        try {
+            db = options.painDatabaseFactory ? options.painDatabaseFactory(dbPath) : new Database(dbPath);
+            db.pragma('busy_timeout = 5000');
+            if (!hasCanonicalSchema(db)) {
+                db.close();
+                db = undefined;
+                return { decision: 'observe', source: event.source, warnings: ['trajectory_schema_invalid'], metadata: { outcome: 'unavailable', admitted: false, duplicate: false, nextAction: 'run the supported PD workspace migration' } };
+            }
+        }
+        catch (error) {
+            try {
+                db?.close();
+            }
+            catch { /* best-effort cleanup of an unusable handle */ }
+            return { decision: 'observe', source: event.source, warnings: [`trajectory_database_unavailable:${error instanceof Error ? error.message.slice(0, 200) : String(error).slice(0, 200)}`], metadata: { outcome: 'unavailable', admitted: false, duplicate: false, nextAction: 'inspect or repair the selected PD trajectory database' } };
+        }
+        const warnings = [];
+        let enrichment;
+        try {
+            enrichment = parseEnrichment(await options.painEnrichmentProvider?.(event));
+        }
+        catch (error) {
+            warnings.push(`pain_enrichment_failed:${error instanceof Error ? error.message.slice(0, 200) : String(error).slice(0, 200)}`);
+            enrichment = null;
+        }
+        if (!enrichment) {
+            try {
+                db.close();
+            }
+            catch { /* no business write occurred */ }
+            return { decision: 'observe', source: event.source, warnings: warnings.length > 0 ? warnings : ['pain_enrichment_invalid'], metadata: { outcome: 'unavailable', admitted: false, duplicate: false, nextAction: 'inspect host pain enrichment input' } };
+        }
+        const outcome = normalizeOutcome(event);
+        const sanitizedParams = sanitizeToolParams(outcome.params, event.context.workspaceDir);
+        const toolName = event.context.toolName ?? '';
+        const sourceObservation = buildToolFailureObservation({ toolName, error: outcome.error, exitCode: outcome.exitCode });
+        const sourceKind = resolveSourceKind({
+            observedAt: new Date().toISOString(), workspaceId: event.context.workspaceDir,
+            sessionId: event.context.sessionId, toolName, failureSource: sourceObservation.failureSource,
+            toolNotFound: sourceObservation.toolNotFound, nonZeroExit: outcome.exitCode !== 0,
+        });
+        const relativePath = enrichment.relativePath ?? String(field(outcome.params, 'file_path') ?? field(outcome.params, 'path') ?? 'unknown').slice(0, 500);
+        const isRisky = enrichment.isRisky ?? (path.isAbsolute(relativePath) && !path.resolve(relativePath).startsWith(`${path.resolve(event.context.workspaceDir)}${path.sep}`));
+        const painScore = enrichment.painScore ?? Math.min(100, (outcome.exitCode !== 0 ? 70 : 0) + (isRisky ? 20 : 0));
+        const errorHash = enrichment.errorHash ?? createHash('sha256').update(outcome.error ?? String(outcome.exitCode)).digest('hex');
+        const cooldownKey = `${path.resolve(event.context.workspaceDir)}:${event.context.sessionId}:${sourceObservation.failureSource}:${errorHash}`;
+        const last = cooldowns.get(cooldownKey);
+        const cooldownActive = last !== undefined && Date.now() - last < PAIN_COOLDOWN_WINDOW_MS;
+        const triage = evaluateTriage({ sourceKind, score: painScore, consecutiveErrors: enrichment.consecutiveErrors, isRisky });
+        const trigger = evaluateTriggerController({ triageResult: triage, isOwnerManual: false, isCooldownActive: cooldownActive, isValid: true, score: painScore, sessionId: event.context.sessionId });
+        const admitted = outcome.failure && WRITE_TOOLS.has(toolName) && trigger.shouldCreateDiagnosticTask;
+        const { eventId, painId } = ids({ event, outcome, sanitizedParams, ...(enrichment.eventId ? { canonicalEventId: enrichment.eventId } : {}) });
+        const createdAt = new Date().toISOString();
+        const paramsJson = stable(sanitizedParams);
+        const resultPreview = preview({ eventId, result: sanitizeValue(outcome.result, 0, event.context.workspaceDir) });
+        let duplicate = false;
+        let duplicateAdmitted = false;
+        try {
+            db.transaction(() => {
+                if (db.prepare('SELECT 1 FROM tool_calls WHERE session_id = ? AND tool_name = ? AND params_json = ? AND outcome = ? AND exit_code IS ? AND error_message IS ? AND result_preview IS ?').get(event.context.sessionId, toolName, paramsJson, outcome.failure ? 'failure' : 'success', outcome.exitCode, outcome.error ?? null, resultPreview)) {
+                    duplicate = true;
+                    duplicateAdmitted = db.prepare('SELECT 1 FROM pain_events WHERE canonical_pain_id = ?').get(painId) !== undefined;
+                    return;
+                }
+                db.prepare(`INSERT INTO sessions (session_id, started_at, updated_at) VALUES (?, ?, ?) ON CONFLICT(session_id) DO UPDATE SET updated_at = excluded.updated_at`).run(event.context.sessionId, createdAt, createdAt);
+                db.prepare(`INSERT INTO tool_calls (session_id, tool_name, outcome, duration_ms, exit_code, error_type, error_message, gfi_before, gfi_after, params_json, result_preview, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                    .run(event.context.sessionId, toolName, outcome.failure ? 'failure' : 'success', outcome.durationMs ?? null, outcome.exitCode, outcome.error ? outcome.error.split(/[\s:]/, 1)[0] : null, outcome.error ?? null, null, null, paramsJson, resultPreview, createdAt);
+                if (admitted) {
+                    const reason = `Tool ${toolName} failed on ${relativePath}; diagnosticGate=${trigger.reason}`;
+                    db.prepare(`INSERT INTO pain_events (session_id, source, score, reason, severity, origin, confidence, text, canonical_pain_id, runtime_task_id, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                        .run(event.context.sessionId, sourceObservation.failureSource ?? 'tool_failure', painScore, reason, painScore >= 70 ? 'severe' : painScore >= 40 ? 'moderate' : 'mild', 'system_infer', 1, enrichment.evidence?.map((entry) => `${entry.sourceRef}: ${entry.note}`).join('\n') ?? null, painId, null, createdAt);
+                }
+            })();
+            if (admitted && !duplicate) {
+                const admittedAt = Date.now();
+                // Bound the module-level cooldown map in long-lived host processes
+                // (OpenClaw): keys carry sessionId + errorHash, so unbounded retention
+                // grows monotonically. Evict entries outside the cooldown window —
+                // they can never be consulted again.
+                for (const [staleKey, staleAt] of cooldowns) {
+                    if (admittedAt - staleAt >= PAIN_COOLDOWN_WINDOW_MS)
+                        cooldowns.delete(staleKey);
+                }
+                cooldowns.set(cooldownKey, admittedAt);
+            }
+        }
+        catch (error) {
+            return { decision: 'observe', source: event.source, warnings: [`trajectory_write_failed:${error instanceof Error ? error.message.slice(0, 200) : String(error).slice(0, 200)}`], metadata: { outcome: outcome.failure ? 'failure' : 'success', admitted: false, duplicate: false, nextAction: 'inspect the workspace trajectory database and retry' } };
+        }
+        finally {
+            try {
+                db.close();
+            }
+            catch { /* write result already determined; cleanup is best-effort */ }
+        }
+        const effectiveAdmitted = admitted || duplicateAdmitted;
+        return { decision: 'observe', source: event.source, metadata: {
+                eventId, painId: effectiveAdmitted ? painId : null, outcome: outcome.failure ? 'failure' : 'success', admitted: effectiveAdmitted, duplicate,
+                sourceKind, failureSource: sourceObservation.failureSource ?? null, triggerOutcome: trigger.outcome,
+                triggerReason: trigger.reason, painScore, isRisky, relativePath, agentId: enrichment.agentId ?? null,
+                evidence: enrichment.evidence ?? [],
+            } };
+    };
+}
+export function resetProductionPainCooldownForTest() {
+    cooldowns.clear();
+}
+export function productionPainCooldownEntryCountForTest() {
+    return cooldowns.size;
+}

package/host-runtime/dist/production-rulehost-gate.d.ts

@@ -0,0 +1,23 @@
+import type { HostEvent, HostEventResult } from '@principles/core/host';
+import { type RuleImplementationRuntime } from './rule-implementation-runtime.js';
+export interface ProductionRuleContextRequest {
+    workspaceDir: string;
+    sessionId: string;
+    targetPath: string;
+    toolName: string;
+    rawPayload: unknown;
+}
+export type RuleContextProvider = (request: ProductionRuleContextRequest) => unknown | Promise<unknown>;
+export interface RuleInputEnrichment {
+    currentGfi: number;
+    recentThinking: boolean;
+    epTier: number;
+    bashRisk: 'safe' | 'normal' | 'dangerous' | 'unknown';
+}
+export type RuleInputEnrichmentProvider = (request: ProductionRuleContextRequest) => unknown | Promise<unknown>;
+export interface ProductionRuleHostGateOptions {
+    ruleContextProvider?: RuleContextProvider;
+    ruleInputEnrichmentProvider?: RuleInputEnrichmentProvider;
+    implementationRuntime?: RuleImplementationRuntime;
+}
+export declare function createProductionRuleHostGate(options?: ProductionRuleHostGateOptions): (event: HostEvent) => Promise<HostEventResult>;