@principles/host-runtime 0.1.0

package/dist/active-principle-prompt.d.ts

@@ -0,0 +1,17 @@
+export interface ActivePrinciplePromptResult {
+    additionalContext: string;
+    principleIds: string[];
+    activationIds: string[];
+    artifactIds: string[];
+    warnings: string[];
+    budget: number;
+    truncated: boolean;
+    excludedPrincipleIds: string[];
+    excludedCount: number;
+    exclusionReason?: 'host_principle_overlap';
+    allValidatedPrinciplesExcluded: boolean;
+}
+export declare function buildActivePrinciplePromptContext(input: {
+    workspaceDir: string;
+    excludePrincipleIds?: ReadonlySet<string>;
+}): Promise<ActivePrinciplePromptResult>;

package/dist/active-principle-prompt.js

@@ -0,0 +1,102 @@
+import { RUNTIME_V2_PRINCIPLE_BUDGET, SqliteActivationStateStore, SqliteConnection, SqlitePIArtifactStore, computeFeatureFlagsFromConfig, filterPromptActivations, renderPrinciplesToDirectives, resolvePrincipleFromArtifact, } from '@principles/core/runtime-v2';
+import fs from 'node:fs';
+import path from 'node:path';
+import { escapeXml } from '@principles/core/prompt-builder';
+import { loadPdConfigForPlugin } from './pd-config.js';
+export async function buildActivePrinciplePromptContext(input) {
+    const warnings = [];
+    const principles = [];
+    const excludedPrincipleIds = [];
+    const config = loadPdConfigForPlugin(input.workspaceDir);
+    if (!config.ok) {
+        warnings.push(...config.errors.map((error) => `config_invalid: ${error.reason}; nextAction=${error.nextAction}`));
+    }
+    const promptFlag = computeFeatureFlagsFromConfig(config.effective).flags.prompt;
+    if (!promptFlag?.enabled) {
+        warnings.push('prompt_feature_disabled; nextAction=set features.prompt.enabled=true in .pd/config.yaml');
+        return { additionalContext: '', principleIds: [], activationIds: [], artifactIds: [], warnings, budget: RUNTIME_V2_PRINCIPLE_BUDGET, truncated: false, excludedPrincipleIds, excludedCount: 0, allValidatedPrinciplesExcluded: false };
+    }
+    let connection;
+    const stateDbPath = path.join(input.workspaceDir, '.pd', 'state.db');
+    if (!fs.existsSync(stateDbPath)) {
+        warnings.push('activation_db_not_found; nextAction=initialize_workspace_runtime_state');
+        return {
+            additionalContext: '', principleIds: [], activationIds: [], artifactIds: [], warnings,
+            budget: RUNTIME_V2_PRINCIPLE_BUDGET, truncated: false, excludedPrincipleIds,
+            excludedCount: 0, allValidatedPrinciplesExcluded: false,
+        };
+    }
+    try {
+        connection = new SqliteConnection({ workspaceDir: input.workspaceDir, readonly: true, bootstrapIfMissing: false });
+        const activations = filterPromptActivations(await new SqliteActivationStateStore(connection).listPromptActivations());
+        const artifactStore = new SqlitePIArtifactStore(connection);
+        for (const activation of activations) {
+            let artifact;
+            try {
+                artifact = await artifactStore.getArtifactById(activation.artifactId);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                warnings.push(`artifact_query_failed: artifactId=${activation.artifactId} reason=${message}; nextAction=check_pi_artifacts_table`);
+                continue;
+            }
+            if (artifact === null) {
+                warnings.push(`artifact_not_found: artifactId=${activation.artifactId}; nextAction=check_pi_artifacts_table_or_remove_stale_activation`);
+                continue;
+            }
+            const resolved = resolvePrincipleFromArtifact({
+                artifact_id: artifact.artifactId,
+                artifact_kind: artifact.artifactKind,
+                content_json: artifact.contentJson,
+                validation_status: artifact.validationStatus,
+            }, activation);
+            if (!resolved.ok) {
+                warnings.push(resolved.warning);
+                continue;
+            }
+            if (input.excludePrincipleIds?.has(resolved.principle.principleId)) {
+                excludedPrincipleIds.push(resolved.principle.principleId);
+            }
+            else {
+                principles.push(resolved.principle);
+            }
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        warnings.push(`activation_db_unreadable: ${message}; nextAction=check_workspace_pd_state_db`);
+    }
+    finally {
+        connection?.close();
+    }
+    const included = [];
+    let additionalContext = '';
+    let truncated = false;
+    for (const principle of principles) {
+        const candidate = [...included, principle];
+        const candidateContext = renderPrinciplesToDirectives(candidate, new Set(candidate.map((entry) => entry.principleId)), escapeXml);
+        if (candidateContext.length > RUNTIME_V2_PRINCIPLE_BUDGET) {
+            truncated = true;
+            break;
+        }
+        included.push(principle);
+        additionalContext = candidateContext;
+    }
+    if (truncated) {
+        warnings.push('prompt_context_truncated: production_prompt_cap; nextAction=reduce_active_prompt_principles');
+    }
+    const injectedIds = new Set(included.map((principle) => principle.principleId));
+    return {
+        additionalContext,
+        principleIds: [...injectedIds],
+        activationIds: included.map((principle) => principle.activationId),
+        artifactIds: included.map((principle) => principle.artifactId),
+        warnings,
+        budget: RUNTIME_V2_PRINCIPLE_BUDGET,
+        truncated,
+        excludedPrincipleIds,
+        excludedCount: excludedPrincipleIds.length,
+        allValidatedPrinciplesExcluded: excludedPrincipleIds.length > 0 && principles.length === 0,
+        ...(excludedPrincipleIds.length > 0 ? { exclusionReason: 'host_principle_overlap' } : {}),
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,45 @@
+import { type HostEvent, type HostEventResult } from '@principles/core/host';
+import { buildActivePrinciplePromptContext } from './active-principle-prompt.js';
+import { type RuleContextProvider, type RuleInputEnrichmentProvider } from './production-rulehost-gate.js';
+import type { RuleImplementationRuntime } from './rule-implementation-runtime.js';
+import { type PainDatabaseFactory, type PainEnrichmentProvider } 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 declare const HOST_RUNTIME_ROUTES: readonly ['before_prompt_build', 'before_tool_call', 'after_tool_call'];
+export type HostRuntimeRoute = (typeof HOST_RUNTIME_ROUTES)[number];
+export type HostRuntimePort = (event: HostEvent) => HostEventResult | Promise<HostEventResult>;
+export interface HostRuntimeOptions {
+    beforePromptBuild: HostRuntimePort;
+    beforeToolCall: HostRuntimePort;
+    afterToolCall: HostRuntimePort;
+}
+export interface HostRuntimeHealth {
+    ok: boolean;
+    workspaceDir: string;
+    routes: readonly HostRuntimeRoute[];
+    reason?: string;
+    nextAction?: string;
+}
+export interface HostRuntime {
+    dispatch(event: HostEvent): Promise<HostEventResult>;
+    health(workspaceDir: string): Promise<HostRuntimeHealth>;
+}
+export declare class HostRuntimeDispatchError extends Error {
+    readonly reason: 'invalid_host_event' | 'unsupported_host_event' | 'invalid_handler_result' | 'lineage_mismatch';
+    readonly nextAction: string;
+    constructor(reason: 'invalid_host_event' | 'unsupported_host_event' | 'invalid_handler_result' | 'lineage_mismatch', nextAction: string);
+}
+export declare function createHostRuntime(options: HostRuntimeOptions): HostRuntime;
+export declare function createProductionHostRuntime(options?: Partial<Pick<HostRuntimeOptions, 'afterToolCall'>> & {
+    beforeToolCall?: HostRuntimePort;
+    beforePromptBuild?: (event: HostEvent, prompt: Awaited<ReturnType<typeof buildActivePrinciplePromptContext>>) => HostEventResult | Promise<HostEventResult>;
+    promptExcludePrincipleIds?: (event: HostEvent) => ReadonlySet<string>;
+    ruleContextProvider?: RuleContextProvider;
+    ruleInputEnrichmentProvider?: RuleInputEnrichmentProvider;
+    ruleImplementationRuntime?: RuleImplementationRuntime;
+    painEnrichmentProvider?: PainEnrichmentProvider;
+    painDatabaseFactory?: PainDatabaseFactory;
+}): HostRuntime;

package/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/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/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/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/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/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>;

package/dist/production-rulehost-gate.js

@@ -0,0 +1,294 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { buildRuleHostAction, estimateLineChanges, mergeDecisions, SqliteConnection, UNAVAILABLE_RULE_CONTEXT, validateRuleContextV2, validateRuleHostResult, } from '@principles/core/runtime-v2';
+import { createNodeRuleImplementationRuntime, MAX_ACTIVE_RULES, RULE_BATCH_SOURCE_BYTES, RULE_SOURCE_BYTES, } from './rule-implementation-runtime.js';
+const WARNING_LIMIT = 500;
+const MAX_WARNINGS = 16;
+const GATE_DEADLINE_MS = 3_000;
+const ARTIFACT_CONTENT_BYTES = 512 * 1024;
+function boundedWarning(reason, nextAction) {
+    return `${reason}; nextAction=${nextAction}`.replace(/\s+/g, ' ').slice(0, WARNING_LIMIT);
+}
+function addWarning(warnings, reason, nextAction) {
+    if (warnings.length < MAX_WARNINGS)
+        warnings.push(boundedWarning(reason, nextAction));
+}
+function remainingGateMs(startedAt) {
+    return GATE_DEADLINE_MS - (Date.now() - startedAt);
+}
+function createDeadlinePromise(remaining) {
+    let timer;
+    const promise = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => reject(new Error('gate_deadline_exceeded')), remaining);
+        timer.unref?.();
+    });
+    return { promise, clear: () => { if (timer !== undefined)
+            clearTimeout(timer); } };
+}
+async function withinGateDeadline(value, startedAt) {
+    const remaining = remainingGateMs(startedAt);
+    if (remaining <= 0)
+        throw new Error('gate_deadline_exceeded');
+    const deadline = createDeadlinePromise(remaining);
+    try {
+        return await Promise.race([Promise.resolve(value), deadline.promise]);
+    }
+    finally {
+        deadline.clear();
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function readToolInput(rawPayload) {
+    if (!isRecord(rawPayload) || !Object.hasOwn(rawPayload, 'toolInput'))
+        return null;
+    const input = rawPayload.toolInput;
+    if (!isRecord(input) || typeof input.toolName !== 'string' || input.toolName.trim().length === 0)
+        return null;
+    const { params } = input;
+    if (!isRecord(params))
+        return null;
+    return { toolName: input.toolName, params };
+}
+function isRuleMeta(value) {
+    return isRecord(value) && typeof value.name === 'string' && typeof value.version === 'string'
+        && typeof value.ruleId === 'string' && typeof value.coversCondition === 'string';
+}
+function isRuleContext(value) {
+    return validateRuleContextV2(value).valid;
+}
+function isRuleResult(value) {
+    return validateRuleHostResult(value).valid;
+}
+export function createProductionRuleHostGate(options = {}) {
+    const implementationRuntime = options.implementationRuntime ?? createNodeRuleImplementationRuntime();
+    return async (event) => {
+        const startedAt = Date.now();
+        const warnings = [];
+        const input = readToolInput(event.rawPayload);
+        if (!input || input.toolName !== event.context.toolName) {
+            return { decision: 'allow', source: event.source, warnings: [boundedWarning('tool_input_invalid', 'decode and validate toolName and params before dispatch')] };
+        }
+        const isBash = new Set(['bash', 'exec', 'execute', 'run_shell_command']).has(input.toolName);
+        const isWrite = new Set(['write', 'write_file', 'edit', 'edit_file', 'replace', 'apply_patch']).has(input.toolName);
+        const action = buildRuleHostAction(input.toolName, input.params, event.context.workspaceDir, { isBashTool: isBash, isWriteTool: isWrite });
+        if (action.normalizedPath === null)
+            return { decision: 'allow', source: event.source, metadata: { evaluatedLiveRules: 0 } };
+        let context;
+        let enrichment = { currentGfi: 0, recentThinking: false, epTier: 0, bashRisk: 'unknown' };
+        const request = {
+            workspaceDir: event.context.workspaceDir, sessionId: event.context.sessionId,
+            targetPath: action.normalizedPath, toolName: input.toolName, rawPayload: event.rawPayload,
+        };
+        if (options.ruleInputEnrichmentProvider) {
+            try {
+                const candidate = await withinGateDeadline(options.ruleInputEnrichmentProvider(request), startedAt);
+                if (isRecord(candidate) && typeof candidate.currentGfi === 'number' && Number.isFinite(candidate.currentGfi)
+                    && typeof candidate.recentThinking === 'boolean' && typeof candidate.epTier === 'number' && Number.isFinite(candidate.epTier)
+                    && (candidate.bashRisk === 'safe' || candidate.bashRisk === 'normal' || candidate.bashRisk === 'dangerous' || candidate.bashRisk === 'unknown')) {
+                    enrichment = { currentGfi: candidate.currentGfi, recentThinking: candidate.recentThinking, epTier: candidate.epTier, bashRisk: candidate.bashRisk };
+                }
+                else
+                    addWarning(warnings, 'rule_input_enrichment_invalid', 'repair the host enrichment provider');
+            }
+            catch (error) {
+                addWarning(warnings, `rule_input_enrichment_failed: ${error instanceof Error ? error.message : String(error)}`, 'inspect the host enrichment provider');
+            }
+        }
+        if (options.ruleContextProvider) {
+            try {
+                const candidate = await withinGateDeadline(options.ruleContextProvider(request), startedAt);
+                if (candidate === undefined) {
+                    context = undefined;
+                }
+                else {
+                    const validation = validateRuleContextV2(candidate);
+                    if (isRuleContext(candidate))
+                        context = candidate;
+                    else {
+                        context = UNAVAILABLE_RULE_CONTEXT;
+                        addWarning(warnings, `rule_context_invalid: ${validation.errors.join('; ')}`, 'repair the host context provider');
+                    }
+                }
+            }
+            catch (error) {
+                context = UNAVAILABLE_RULE_CONTEXT;
+                addWarning(warnings, `rule_context_provider_failed: ${error instanceof Error ? error.message : String(error)}`, 'inspect the host context provider and retry');
+            }
+        }
+        const dbPath = path.join(event.context.workspaceDir, '.pd', 'state.db');
+        if (remainingGateMs(startedAt) <= 0) {
+            return { decision: 'allow', source: event.source, warnings: [boundedWarning('gate_deadline_exceeded', 'inspect host context providers and active RuleCode resource use')] };
+        }
+        if (!fs.existsSync(dbPath)) {
+            return { decision: 'allow', source: event.source, warnings: [boundedWarning('activation_db_not_found', 'initialize_workspace_runtime_state')] };
+        }
+        const connection = new SqliteConnection({ workspaceDir: event.context.workspaceDir, readonly: true, bootstrapIfMissing: false });
+        const candidates = [];
+        try {
+            const rows = connection.getDb().prepare(`
+        SELECT a.activation_id, a.artifact_id, a.target_ref, a.action,
+               p.source_rule_id, p.source_principle_id,
+               length(CAST(p.content_json AS BLOB)) AS content_bytes
+        FROM activations a JOIN pi_artifacts p ON a.artifact_id = p.artifact_id
+        WHERE a.channel = 'code_tool_hook' AND a.deactivated_at IS NULL
+        ORDER BY a.activated_at ASC
+        LIMIT ?
+      `).all(MAX_ACTIVE_RULES + 1);
+            if (!Array.isArray(rows)) {
+                addWarning(warnings, 'activation_query_invalid', 'inspect state.db schema and integrity');
+            }
+            else if (rows.length > MAX_ACTIVE_RULES) {
+                return { decision: 'allow', source: event.source, warnings: [boundedWarning(`active_rule_limit_exceeded: maximum ${MAX_ACTIVE_RULES}`, 'deactivate excess active RuleHost rules and retry')], metadata: { evaluatedLiveRules: 0 } };
+            }
+            else {
+                for (const row of rows) {
+                    if (!isRecord(row) || typeof row.content_bytes !== 'number' || !Number.isSafeInteger(row.content_bytes) || row.content_bytes < 0) {
+                        return { decision: 'allow', source: event.source, warnings: [boundedWarning('artifact_content_size_invalid', 'inspect state.db artifact content integrity')], metadata: { evaluatedLiveRules: 0 } };
+                    }
+                    if (row.content_bytes > ARTIFACT_CONTENT_BYTES) {
+                        const activation = typeof row.activation_id === 'string' ? row.activation_id : 'unknown';
+                        return { decision: 'allow', source: event.source, warnings: [boundedWarning(`artifact_content_budget_exceeded: activation=${activation} bytes=${row.content_bytes} maximum=${ARTIFACT_CONTENT_BYTES}`, 'reduce the active artifact envelope and reactivate the rule')], metadata: { evaluatedLiveRules: 0 } };
+                    }
+                }
+                const groups = new Map();
+                for (const row of rows) {
+                    if (!isRecord(row) || typeof row.target_ref !== 'string' || row.target_ref.length === 0) {
+                        addWarning(warnings, 'activation_row_invalid', 'deactivate and recreate the malformed activation');
+                        continue;
+                    }
+                    const group = groups.get(row.target_ref) ?? [];
+                    group.push(row);
+                    groups.set(row.target_ref, group);
+                }
+                for (const [targetRef, group] of groups) {
+                    if (group.length !== 1) {
+                        addWarning(warnings, `duplicate_active_activation: ${targetRef}`, 'deactivate all but one activation for this target_ref');
+                        continue;
+                    }
+                    const [row] = group;
+                    if (!row || row.action !== 'code_tool_hook_live_activate')
+                        continue;
+                    const activationId = row.activation_id;
+                    const artifactId = row.artifact_id;
+                    const expectedContentBytes = row.content_bytes;
+                    if (typeof activationId !== 'string' || typeof artifactId !== 'string' || typeof expectedContentBytes !== 'number') {
+                        addWarning(warnings, 'activation_required_fields_invalid', 'deactivate and recreate the activation');
+                        continue;
+                    }
+                    const contentRow = connection.getDb().prepare(`
+            SELECT content_json, length(CAST(content_json AS BLOB)) AS content_bytes
+            FROM pi_artifacts WHERE artifact_id = ?
+          `).get(artifactId);
+                    if (!isRecord(contentRow) || typeof contentRow.content_json !== 'string'
+                        || typeof contentRow.content_bytes !== 'number' || !Number.isSafeInteger(contentRow.content_bytes)) {
+                        addWarning(warnings, `activation_artifact_invalid: ${activationId}`, 'inspect state.db artifact content integrity');
+                        continue;
+                    }
+                    const contentJson = contentRow.content_json;
+                    const returnedContentBytes = Buffer.byteLength(contentJson, 'utf8');
+                    if (contentRow.content_bytes > ARTIFACT_CONTENT_BYTES || returnedContentBytes > ARTIFACT_CONTENT_BYTES) {
+                        return { decision: 'allow', source: event.source, warnings: [boundedWarning(`artifact_content_budget_exceeded: activation=${activationId} bytes=${Math.max(contentRow.content_bytes, returnedContentBytes)} maximum=${ARTIFACT_CONTENT_BYTES}`, 'reduce the active artifact envelope and reactivate the rule')], metadata: { evaluatedLiveRules: 0 } };
+                    }
+                    if (contentRow.content_bytes !== expectedContentBytes || returnedContentBytes !== contentRow.content_bytes) {
+                        return { decision: 'allow', source: event.source, warnings: [boundedWarning(`artifact_content_size_changed: activation=${activationId}`, 'retry after the active artifact update completes')], metadata: { evaluatedLiveRules: 0 } };
+                    }
+                    try {
+                        const content = JSON.parse(contentJson);
+                        if (!isRecord(content) || typeof content.implementationCode !== 'string' || content.implementationCode.length === 0) {
+                            addWarning(warnings, `activation_artifact_invalid: ${activationId}`, 'regenerate the rule artifact with implementationCode');
+                            continue;
+                        }
+                        const sourceBytes = Buffer.byteLength(content.implementationCode, 'utf8');
+                        if (sourceBytes > RULE_SOURCE_BYTES) {
+                            return { decision: 'allow', source: event.source, warnings: [boundedWarning(`rule_source_budget_exceeded: activation=${activationId} bytes=${sourceBytes}`, `reduce each RuleCode source below ${RULE_SOURCE_BYTES} bytes`)], metadata: { evaluatedLiveRules: 0 } };
+                        }
+                        if (Object.hasOwn(content, 'requiresContextVersion')) {
+                            if (content.requiresContextVersion !== 2) {
+                                addWarning(warnings, `unsupported_context_version: ${String(content.requiresContextVersion)}`, 'regenerate the rule artifact for context version 2');
+                                continue;
+                            }
+                            if (!context) {
+                                addWarning(warnings, 'rule_context_v2_unavailable', 'enable and wire the host rule context provider');
+                                continue;
+                            }
+                        }
+                        const ruleId = typeof content.ruleId === 'string' ? content.ruleId : typeof row.source_rule_id === 'string' ? row.source_rule_id : artifactId;
+                        const principleId = typeof content.principleId === 'string' ? content.principleId : typeof row.source_principle_id === 'string' ? row.source_principle_id : ruleId;
+                        const fallbackMeta = { name: activationId, version: '1', ruleId, coversCondition: 'all' };
+                        candidates.push({ implId: activationId, ruleId, principleId, meta: isRuleMeta(content.meta) ? content.meta : fallbackMeta, source: content.implementationCode });
+                    }
+                    catch (error) {
+                        addWarning(warnings, `implementation_unhealthy: ${error instanceof Error ? error.message : String(error)}`, 'fix the RuleCode and reactivate the rule');
+                    }
+                }
+            }
+            const hostInput = {
+                action,
+                workspace: { isRiskPath: false, planStatus: 'NONE', hasPlanFile: false },
+                session: { sessionId: event.context.sessionId, currentGfi: enrichment.currentGfi, recentThinking: enrichment.recentThinking },
+                evolution: { epTier: enrichment.epTier },
+                derived: { estimatedLineChanges: estimateLineChanges({ toolName: input.toolName, params: input.params }), bashRisk: enrichment.bashRisk },
+                ...(context ? { context } : {}),
+            };
+            const batchSourceBytes = candidates.reduce((sum, candidate) => sum + Buffer.byteLength(candidate.source, 'utf8'), 0);
+            if (batchSourceBytes > RULE_BATCH_SOURCE_BYTES) {
+                return { decision: 'allow', source: event.source, warnings: [boundedWarning(`rule_source_budget_exceeded: batchBytes=${batchSourceBytes}`, `reduce total active RuleCode below ${RULE_BATCH_SOURCE_BYTES} bytes`)], metadata: { evaluatedLiveRules: 0 } };
+            }
+            const batchSources = candidates.map((candidate) => ({ source: candidate.source, filename: `activation-${candidate.implId}` }));
+            const remaining = remainingGateMs(startedAt);
+            if (remaining <= 0) {
+                return { decision: 'allow', source: event.source, warnings: [boundedWarning('gate_deadline_exceeded', 'reduce active RuleCode count or source size and retry')], metadata: { evaluatedLiveRules: 0 } };
+            }
+            const batch = implementationRuntime.evaluateBatch(batchSources, hostInput, remaining);
+            if (!batch.ok || !batch.results) {
+                return { decision: 'allow', source: event.source, warnings: [boundedWarning(`${batch.reason ?? 'rule_batch_failed'}: ${batch.detail ?? 'unknown failure'}`, 'inspect active RuleCode resource use and repair or deactivate the unhealthy rule')], metadata: { evaluatedLiveRules: 0 } };
+            }
+            const timedOutChild = batch.results.find((candidate) => !candidate.ok && candidate.error?.includes('timed out'));
+            if (timedOutChild) {
+                return { decision: 'allow', source: event.source, warnings: [boundedWarning(`rule_batch_timeout: ${timedOutChild.error ?? 'unknown child timeout'}`, 'fix or deactivate the unhealthy RuleCode and retry')], metadata: { evaluatedLiveRules: 0 } };
+            }
+            const implementations = [];
+            for (let index = 0; index < candidates.length; index += 1) {
+                const candidate = candidates[index];
+                const batchResult = batch.results[index];
+                if (!candidate || !batchResult) {
+                    addWarning(warnings, 'rule_batch_result_missing', 'inspect the RuleCode runtime result contract');
+                    continue;
+                }
+                if (!batchResult.ok) {
+                    addWarning(warnings, `implementation_unhealthy: ${batchResult.error ?? 'unknown child error'}`, 'fix the RuleCode and reactivate the rule');
+                    continue;
+                }
+                const validation = validateRuleHostResult(batchResult.result);
+                if (!isRuleResult(batchResult.result)) {
+                    addWarning(warnings, `invalid RuleHostResult: ${validation.errors.join('; ')}`, 'fix the RuleCode result and reactivate the rule');
+                    continue;
+                }
+                const validatedResult = batchResult.result.matched
+                    ? { ...batchResult.result, ruleId: candidate.ruleId, principleId: candidate.principleId }
+                    : batchResult.result;
+                implementations.push({ ...candidate, evaluate: () => validatedResult });
+            }
+            const result = mergeDecisions(implementations, hostInput, {
+                warn(message) { addWarning(warnings, message, 'inspect the unhealthy activation and RuleCode output'); },
+            });
+            if (result?.decision === 'block') {
+                if (result.reason.trim().length === 0) {
+                    addWarning(warnings, 'deny_reason_missing', 'fix the RuleCode to return a non-empty block reason');
+                    return { decision: 'allow', source: event.source, warnings, metadata: { evaluatedLiveRules: implementations.length } };
+                }
+                return { decision: 'deny', reason: result.reason, source: event.source, ...(warnings.length ? { warnings } : {}), metadata: { evaluatedLiveRules: implementations.length, ruleId: result.ruleId, principleId: result.principleId } };
+            }
+            return { decision: 'allow', source: event.source, ...(warnings.length ? { warnings } : {}), metadata: { evaluatedLiveRules: implementations.length, ruleDecision: result?.decision ?? 'allow' } };
+        }
+        catch (error) {
+            addWarning(warnings, `activation_read_failed: ${error instanceof Error ? error.message : String(error)}`, 'inspect state.db schema and integrity');
+            return { decision: 'allow', source: event.source, warnings, metadata: { evaluatedLiveRules: 0 } };
+        }
+        finally {
+            connection.close();
+        }
+    };
+}

package/dist/rule-implementation-runtime.d.ts

@@ -0,0 +1,25 @@
+export declare const RULE_BATCH_TIMEOUT_MS = 2500;
+export declare const RULE_BATCH_OUTPUT_BYTES: number;
+export declare const RULE_SOURCE_BYTES: number;
+export declare const RULE_BATCH_SOURCE_BYTES: number;
+export declare const MAX_ACTIVE_RULES = 32;
+export interface RuleBatchSource {
+    source: string;
+    filename: string;
+}
+export interface RuleBatchResult {
+    ok: boolean;
+    result?: unknown;
+    error?: string;
+}
+export type RuleBatchFailureReason = 'rule_batch_timeout' | 'rule_batch_output_exceeded' | 'rule_batch_failed';
+export interface RuleBatchEvaluation {
+    ok: boolean;
+    results?: readonly RuleBatchResult[];
+    reason?: RuleBatchFailureReason;
+    detail?: string;
+}
+export interface RuleImplementationRuntime {
+    evaluateBatch(rules: readonly RuleBatchSource[], input: unknown, timeoutMs: number): RuleBatchEvaluation;
+}
+export declare function createNodeRuleImplementationRuntime(): RuleImplementationRuntime;

package/dist/rule-implementation-runtime.js

@@ -0,0 +1,114 @@
+import { spawnSync } from 'node:child_process';
+export const RULE_BATCH_TIMEOUT_MS = 2_500;
+export const RULE_BATCH_OUTPUT_BYTES = 64 * 1024;
+export const RULE_SOURCE_BYTES = 64 * 1024;
+export const RULE_BATCH_SOURCE_BYTES = 256 * 1024;
+export const MAX_ACTIVE_RULES = 32;
+const EVALUATION_PROCESS_SOURCE = String.raw `
+const vm = require('node:vm');
+const fs = require('node:fs');
+function normalize(sourceCode) {
+  const withoutExports = sourceCode
+    .replace(/export\s+const\s+meta\s*=/, 'const meta =')
+    .replace(/export\s+function\s+evaluate\s*\(/, 'function evaluate(');
+  return withoutExports + '\nglobalThis.__pdRuleModule = { meta: typeof meta === "undefined" ? undefined : meta, evaluate: typeof evaluate === "undefined" ? undefined : evaluate };';
+}
+function preview(error) { return String(error).slice(0, 500); }
+try {
+  const workerData = JSON.parse(fs.readFileSync(0, 'utf8'));
+  const results = [];
+  for (const rule of workerData.rules) {
+    try {
+      const context = vm.createContext(Object.create(null));
+      new vm.Script(normalize(rule.source), { filename: rule.filename }).runInContext(context, { timeout: 1000 });
+      if (!context.__pdRuleModule || typeof context.__pdRuleModule.evaluate !== 'function') throw new Error('compiled module has no evaluate function');
+      // Sandbox boundary: hand the context ONLY a primitive JSON string and
+      // build the call input + helpers with the context's own intrinsics.
+      // Passing host-realm objects (the parsed input, a host-built helpers
+      // object) would let rule source walk .constructor.constructor back to
+      // the host realm's Function constructor and reach the child process
+      // and require — a full sandbox escape with user privileges.
+      context.__pdInputJson = JSON.stringify(workerData.input);
+      new vm.Script(
+        'const __pdCallInput = JSON.parse(globalThis.__pdInputJson);' +
+        'delete globalThis.__pdInputJson;' +
+        'const __pdCallHelpers = Object.freeze({' +
+        ' isRiskPath: () => __pdCallInput.workspace.isRiskPath,' +
+        ' getToolName: () => __pdCallInput.action.toolName,' +
+        ' getEstimatedLineChanges: () => __pdCallInput.derived.estimatedLineChanges,' +
+        ' getBashRisk: () => __pdCallInput.derived.bashRisk,' +
+        ' hasPlanFile: () => __pdCallInput.workspace.hasPlanFile,' +
+        ' getPlanStatus: () => __pdCallInput.workspace.planStatus,' +
+        ' getEpTier: () => __pdCallInput.evolution.epTier' +
+        '});', { filename: rule.filename + '.bootstrap' }
+      ).runInContext(context, { timeout: 1000 });
+      const result = new vm.Script('__pdRuleModule.evaluate(__pdCallInput, __pdCallHelpers)', { filename: rule.filename + '.call' })
+        .runInContext(context, { timeout: 1000 });
+      results.push({ ok: true, result });
+    } catch (error) {
+      results.push({ ok: false, error: preview(error) });
+    }
+  }
+  process.stdout.write(JSON.stringify({ ok: true, results }));
+} catch (error) {
+  process.stdout.write(JSON.stringify({ ok: false, error: preview(error) }));
+  process.exitCode = 1;
+}
+`;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function parseBatchResults(value, expectedLength) {
+    if (!isRecord(value) || value.ok !== true || !Array.isArray(value.results) || value.results.length !== expectedLength)
+        return null;
+    const results = [];
+    for (const candidate of value.results) {
+        if (!isRecord(candidate) || typeof candidate.ok !== 'boolean')
+            return null;
+        if (candidate.ok) {
+            if (!Object.hasOwn(candidate, 'result'))
+                return null;
+            results.push({ ok: true, result: candidate.result });
+        }
+        else {
+            if (typeof candidate.error !== 'string')
+                return null;
+            results.push({ ok: false, error: candidate.error.slice(0, 500) });
+        }
+    }
+    return results;
+}
+export function createNodeRuleImplementationRuntime() {
+    return {
+        evaluateBatch(rules, input, timeoutMs) {
+            const child = spawnSync(process.execPath, ['--max-old-space-size=32', '-e', EVALUATION_PROCESS_SOURCE], {
+                input: JSON.stringify({ rules, input }), encoding: 'utf8', timeout: Math.max(1, Math.min(timeoutMs, RULE_BATCH_TIMEOUT_MS)),
+                maxBuffer: RULE_BATCH_OUTPUT_BYTES, windowsHide: true,
+            });
+            if (child.error) {
+                const code = isRecord(child.error) && typeof child.error.code === 'string' ? child.error.code : '';
+                if (code === 'ETIMEDOUT')
+                    return { ok: false, reason: 'rule_batch_timeout', detail: child.error.message.slice(0, 500) };
+                if (code === 'ENOBUFS')
+                    return { ok: false, reason: 'rule_batch_output_exceeded', detail: child.error.message.slice(0, 500) };
+                return { ok: false, reason: 'rule_batch_failed', detail: child.error.message.slice(0, 500) };
+            }
+            if (Buffer.byteLength(child.stdout, 'utf8') >= RULE_BATCH_OUTPUT_BYTES) {
+                return { ok: false, reason: 'rule_batch_output_exceeded', detail: 'child output reached the configured byte bound' };
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(child.stdout);
+            }
+            catch {
+                return { ok: false, reason: 'rule_batch_failed', detail: `child returned invalid JSON: ${child.stderr.trim().slice(0, 300)}` };
+            }
+            const results = parseBatchResults(parsed, rules.length);
+            if (!results) {
+                const detail = isRecord(parsed) && typeof parsed.error === 'string' ? parsed.error.slice(0, 500) : 'child result shape invalid';
+                return { ok: false, reason: 'rule_batch_failed', detail };
+            }
+            return { ok: true, results };
+        },
+    };
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@principles/host-runtime",
+  "version": "0.1.0",
+  "description": "Shared host-neutral orchestration for Principles Disciple MVP-Core hook paths.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "lint": "eslint \"src/**/*.ts\""
+  },
+  "dependencies": {
+    "@principles/core": "^1.74.1",
+    "better-sqlite3": "^13.0.3",
+    "js-yaml": "^5.2.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^26.1.2",
+    "@types/js-yaml": "^4.0.9",
+    "typescript": "^7.0.2",
+    "vite": "^8.0.16",
+    "vitest": "^4.1.10"
+  },
+  "license": "MIT"
+}