principles-disciple 1.126.0 → 1.128.0

package/dist/core/rule-host.js

@@ -0,0 +1,311 @@
+/**
+ * Rule Host — Constrained execution layer for active code implementations
+ *
+ * PURPOSE: Load active code implementations from the SQLite activations table
+ * (code_tool_hook channel), execute them in a constrained node:vm context,
+ * and merge their decisions.
+ *
+ * ARCHITECTURE (PRI-436):
+ *   - SQLite is the SOLE production source of active RuleCode
+ *   - No filesystem ledger or implementation asset reads occur during evaluation
+ *   - Constructor takes stateDir for API compatibility (no longer used for impl loading)
+ *   - workspaceDir enables reading code_tool_hook activations from SQLite
+ *   - evaluate(input) loads active code implementations and runs them
+ *   - Each implementation executes in an isolated vm context with minimal helpers
+ *   - Decision merge: block short-circuits, requireApproval collects, allow is implicit
+ *
+ * SECURITY CONSTRAINTS (T-12-01, T-12-04):
+ *   - Candidate code loads through a dedicated vm context, not the host realm
+ *   - No importModuleDynamically callback
+ *   - Helpers are a frozen object — implementations cannot modify the helper surface
+ *
+ * CONSERVATIVE DEGRADATION (T-12-02, D-08):
+ *   - On ANY host error (load failure, eval error, vm error): return undefined
+ *   - Never throw, never bypass downstream gates (Progressive Gate, Edit Verification)
+ */
+import { createRuleHostHelpers } from '@principles/core/runtime-v2';
+import { mergeDecisions } from '@principles/core/runtime-v2';
+import { validateRuleHostResult } from '@principles/core/runtime-v2';
+import { SqliteConnection } from '@principles/core/runtime-v2';
+import { loadRuleImplementationModule } from './rule-implementation-runtime.js';
+import { EventLogService } from './event-log.js';
+/**
+ * Type guard for RuleHostMeta from untrusted module exports.
+ * Validates all four required string fields (EP-01: no `as` bypass at trust boundary).
+ */
+function isRuleHostMeta(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return false;
+    }
+    const v = value;
+    return (typeof v['name'] === 'string' &&
+        typeof v['version'] === 'string' &&
+        typeof v['ruleId'] === 'string' &&
+        typeof v['coversCondition'] === 'string');
+}
+export class RuleHost {
+    stateDir;
+    logger;
+    workspaceDir;
+    implementationSources = new Map();
+    constructor(stateDir, logger = console, options) {
+        this.stateDir = stateDir;
+        this.logger = logger;
+        this.workspaceDir = options?.workspaceDir ?? null;
+    }
+    /**
+     * Evaluate the input against all active code implementations.
+     *
+     * Returns:
+     *   - undefined when no active code implementations exist (no opinion)
+     *   - undefined when all implementations return allow or matched=false
+     *   - { decision: 'block', ... } when any implementation returns block (short-circuits)
+     *   - { decision: 'requireApproval', ... } when any implementation returns requireApproval
+     */
+    evaluate(input) {
+        try {
+            const activeImpls = this._loadActiveCodeImplementations();
+            return mergeDecisions(activeImpls, input, {
+                warn: this.logger.warn,
+                onImplementationUnhealthy: (impl, reason) => {
+                    const source = this.implementationSources.get(impl.implId);
+                    if (!source) {
+                        this.logger.warn?.(`[RuleHost] No source mapping for implId=${impl.implId}, cannot record unhealthy event`);
+                        return;
+                    }
+                    this._recordUnhealthy(source.activationId, source.artifactId, source.ruleId, reason, 'Fix the RuleCode runtime error or return shape, then re-activate the rule');
+                },
+            });
+        }
+        catch (hostError) {
+            // Conservative degradation: log and return undefined (D-08)
+            this.logger.warn?.(`[RuleHost] Host evaluation failed, degrading conservatively: ${String(hostError)}`);
+            return undefined;
+        }
+    }
+    /**
+     * Load active code implementations from the SQLite activations table.
+     *
+     * PRI-436: SQLite is the SOLE production source. The filesystem ledger
+     * (principle-tree-ledger) and implementation asset paths have been deleted.
+     * No fallback, no dual-source, no deprecated adapter.
+     *
+     * Source: activations table (code_tool_hook channel, deactivated_at IS NULL)
+     *   → JOIN pi_artifacts for content_json → extract implementationCode → compile
+     */
+    _loadActiveCodeImplementations() {
+        if (!this.workspaceDir) {
+            return [];
+        }
+        try {
+            return this._loadFromActivationsTable(this.workspaceDir);
+        }
+        catch (activationError) {
+            this.logger.warn?.(`[RuleHost] Failed to load code_tool_hook activations: ${String(activationError)}`);
+            return [];
+        }
+    }
+    /**
+     * Load active code implementations from the activations table (code_tool_hook channel).
+     *
+     * For each activation record:
+     *   1. Query the pi_artifacts table for the artifact content
+     *   2. Parse content_json to extract implementationCode (treated as unknown, EP-01)
+     *   3. Compile via loadRuleImplementationModule (isolated vm context)
+     *
+     * PRI-436 invariant: at most one active activation per rule (target_ref).
+     * Duplicate active activations for the same target_ref are ALL skipped
+     * (zero executions) and emit structured unhealthy evidence via logger.warn
+     * (Runtime Contract Rule 9: graceful degradation includes a reason).
+     *
+     * All data from SQLite is treated as unknown and validated before use.
+     */
+    _loadFromActivationsTable(workspaceDir) {
+        this.implementationSources.clear();
+        const sqliteConn = new SqliteConnection(workspaceDir);
+        try {
+            const db = sqliteConn.getDb();
+            const rows = db.prepare(`
+        SELECT a.activation_id, a.artifact_id, a.target_ref,
+               p.content_json, p.source_rule_id
+        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
+      `).all();
+            if (!Array.isArray(rows)) {
+                this.logger.warn?.('[RuleHost] Activations table query returned non-array, skipping');
+                return [];
+            }
+            // PRI-436: Group active rows by target_ref to detect duplicates.
+            // At most one active activation per rule (target_ref) is allowed.
+            // Duplicate groups are skipped entirely (zero executions) and emit
+            // structured unhealthy evidence. Non-duplicate rows proceed to compilation.
+            const rowsByTargetRef = new Map();
+            for (const row of rows) {
+                if (!row || typeof row !== 'object') {
+                    continue;
+                }
+                const r = row;
+                const targetRef = typeof r['target_ref'] === 'string' ? r['target_ref'] : '';
+                const activationId = typeof r['activation_id'] === 'string' ? r['activation_id'] : '';
+                if (!targetRef) {
+                    this.logger.warn?.(`[RuleHost] Activation ${activationId}: missing target_ref, skipping`);
+                    continue;
+                }
+                const group = rowsByTargetRef.get(targetRef);
+                if (group) {
+                    group.push(r);
+                }
+                else {
+                    rowsByTargetRef.set(targetRef, [r]);
+                }
+            }
+            // Emit structured unhealthy evidence for duplicate groups; collect valid (non-duplicate) rows.
+            const validRows = [];
+            for (const [targetRef, group] of rowsByTargetRef) {
+                if (group.length > 1) {
+                    const activationIds = [];
+                    const artifactIds = [];
+                    for (const r of group) {
+                        if (typeof r['activation_id'] === 'string')
+                            activationIds.push(r['activation_id']);
+                        if (typeof r['artifact_id'] === 'string')
+                            artifactIds.push(r['artifact_id']);
+                    }
+                    this.logger.warn?.(`[RuleHost] Duplicate active activations detected — skipping all executions for this rule. ` +
+                        `targetRef=${targetRef} count=${group.length} ` +
+                        `activationIds=[${activationIds.join(', ')}] ` +
+                        `artifactIds=[${artifactIds.join(', ')}] ` +
+                        `reason=at most one active activation per rule is allowed ` +
+                        `nextAction=deactivate all but one activation for this target_ref`);
+                    for (const r of group) {
+                        const activationId = typeof r['activation_id'] === 'string' ? r['activation_id'] : '';
+                        const artifactId = typeof r['artifact_id'] === 'string' ? r['artifact_id'] : '';
+                        if (activationId && artifactId) {
+                            this._recordUnhealthy(activationId, artifactId, targetRef, `duplicate active activation for target_ref ${targetRef}`, 'Deactivate all but one activation for this target_ref');
+                        }
+                    }
+                }
+                else {
+                    validRows.push(group[0]);
+                }
+            }
+            const loaded = [];
+            for (const r of validRows) {
+                const activationId = typeof r['activation_id'] === 'string' ? r['activation_id'] : '';
+                const artifactId = typeof r['artifact_id'] === 'string' ? r['artifact_id'] : '';
+                const contentJson = typeof r['content_json'] === 'string' ? r['content_json'] : '';
+                const sourceRuleId = typeof r['source_rule_id'] === 'string' ? r['source_rule_id'] : null;
+                if (!activationId || !artifactId || !contentJson) {
+                    this.logger.warn?.(`[RuleHost] Activation row missing required fields, skipping`);
+                    continue;
+                }
+                try {
+                    const content = JSON.parse(contentJson);
+                    if (!content || typeof content !== 'object' || Array.isArray(content)) {
+                        this.logger.warn?.(`[RuleHost] Activation ${activationId}: content_json is not an object, skipping`);
+                        continue;
+                    }
+                    const contentObj = content;
+                    const implementationCode = contentObj['implementationCode'];
+                    if (typeof implementationCode !== 'string' || implementationCode.length === 0) {
+                        this.logger.warn?.(`[RuleHost] Activation ${activationId}: no implementationCode in artifact, skipping`);
+                        continue;
+                    }
+                    const ruleId = typeof contentObj['ruleId'] === 'string'
+                        ? contentObj['ruleId']
+                        : (sourceRuleId ?? artifactId);
+                    const implId = `act-impl-${activationId}`;
+                    const moduleExports = loadRuleImplementationModule(implementationCode, implId);
+                    if (!moduleExports || typeof moduleExports.callEvaluate !== 'function') {
+                        const reason = 'compiled module has no evaluate function';
+                        this.logger.warn?.(`[RuleHost] Activation ${activationId}: ${reason}, skipping`);
+                        this._recordUnhealthy(activationId, artifactId, ruleId, reason, 'Fix the RuleCode to export an evaluate(input, helpers) function, then re-activate');
+                        continue;
+                    }
+                    const fallbackMeta = {
+                        name: implId,
+                        version: '1',
+                        ruleId,
+                        coversCondition: 'all',
+                    };
+                    const meta = isRuleHostMeta(moduleExports.meta)
+                        ? moduleExports.meta
+                        : fallbackMeta;
+                    // PRI-437: Use callEvaluate (vm-context-bounded) instead of raw evaluate.
+                    // callEvaluate runs the invocation INSIDE the vm context with a time
+                    // boundary, terminating infinite loops and excessive computation.
+                    const boundedCallEvaluate = moduleExports.callEvaluate;
+                    this.implementationSources.set(implId, { activationId, artifactId, ruleId });
+                    loaded.push({
+                        implId,
+                        ruleId,
+                        meta,
+                        evaluate: (input) => {
+                            const frozenHelpers = createRuleHostHelpers(input);
+                            // PRI-437: Execute inside vm context with timeout boundary.
+                            const rawResult = boundedCallEvaluate(input, frozenHelpers);
+                            const validation = validateRuleHostResult(rawResult);
+                            if (!validation.valid) {
+                                throw new Error(`[RuleHost] Activation ${activationId} returned invalid RuleHostResult: ${validation.errors.join('; ')}`);
+                            }
+                            const result = rawResult;
+                            if (result.matched && (result.decision === 'block' || result.decision === 'requireApproval')) {
+                                result.ruleId = ruleId;
+                                result.principleId = meta.ruleId ?? ruleId;
+                            }
+                            return result;
+                        },
+                    });
+                }
+                catch (loadError) {
+                    const reason = `compilation failed: ${String(loadError)}`;
+                    this.logger.warn?.(`[RuleHost] Failed to load activation ${activationId}: ${reason}`);
+                    // ruleId is declared inside the try block and may not be assigned yet;
+                    // fall back to sourceRuleId or artifactId (both available in scope)
+                    this._recordUnhealthy(activationId, artifactId, sourceRuleId ?? artifactId, reason, 'Fix the RuleCode syntax/compilation error, then re-activate the rule');
+                }
+            }
+            return loaded;
+        }
+        finally {
+            try {
+                sqliteConn.close();
+            }
+            catch {
+                // best-effort cleanup
+            }
+        }
+    }
+    /**
+     * PRI-437: Record an unhealthy activation state to EventLog.
+     *
+     * This makes compile/load failures visible to CLI (pd runtime health) and
+     * Console API — NOT just a logger.warn that's silently skipped.
+     *
+     * ERR-002: degradation includes a reason and nextAction (not silent).
+     * Failures in EventLog recording are caught and logged (never throw).
+     */
+    _recordUnhealthy(activationId, artifactId, ruleId, reason, nextAction) {
+        try {
+            // Pass undefined as logger: RuleHostLogger only has warn(), but EventLog
+            // calls this.logger.error() without optional chaining. Passing the
+            // RuleHostLogger directly would cause TypeError if EventLog tried to
+            // log an internal error. EventLog's logger is optional; RuleHost already
+            // logs its own warnings for the unhealthy event.
+            const eventLog = EventLogService.get(this.stateDir);
+            eventLog.recordRuleHostUnhealthy({
+                activationId,
+                artifactId,
+                ruleId,
+                reason,
+                nextAction,
+            });
+        }
+        catch (recordError) {
+            // EventLog recording must never break RuleHost evaluation
+            this.logger.warn?.(`[RuleHost] Failed to record unhealthy event for activation ${activationId}: ${String(recordError)}`);
+        }
+    }
+}

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

@@ -0,0 +1,18 @@
+export interface RuleImplementationModuleExports {
+    meta?: unknown;
+    evaluate?: unknown;
+    /**
+     * Call evaluate(input, helpers) INSIDE the vm context with a time boundary.
+     *
+     * PRI-437: The evaluate() function extracted from a vm context executes in
+     * the vm realm, but a direct host-realm call has NO timeout protection —
+     * an infinite loop in RuleCode would hang the host process forever.
+     *
+     * callEvaluate runs the invocation inside the vm context via
+     * Script.runInContext({ timeout }), which terminates infinite loops.
+     *
+     * Throws on timeout, compilation error, or if evaluate is missing.
+     */
+    callEvaluate?: (input: unknown, helpers: unknown) => unknown;
+}
+export declare function loadRuleImplementationModule(sourceCode: string, filename: string): RuleImplementationModuleExports;

package/dist/core/rule-implementation-runtime.js

@@ -0,0 +1,112 @@
+import { nodeVm } from '../utils/node-vm-polyfill.js';
+import { spawnSync } from 'node:child_process';
+/** Timeout (ms) for compiling RuleCode (defining evaluate + meta). */
+const COMPILE_TIMEOUT_MS = 1000;
+/** Timeout (ms) for executing evaluate(input, helpers) inside the vm. */
+const EVALUATE_PROCESS_TIMEOUT_MS = 3000;
+const EVALUATE_PROCESS_OUTPUT_BYTES = 1024 * 1024;
+const EVALUATION_PROCESS_SOURCE = String.raw `
+const vm = require('node:vm');
+try {
+  const workerData = JSON.parse(require('node:fs').readFileSync(0, 'utf8'));
+  const context = vm.createContext(Object.create(null));
+  new vm.Script(workerData.source, { filename: workerData.filename }).runInContext(context, { timeout: 1000 });
+  const input = workerData.input;
+  const helpers = Object.freeze({
+    isRiskPath: () => input.workspace.isRiskPath,
+    getToolName: () => input.action.toolName,
+    getEstimatedLineChanges: () => input.derived.estimatedLineChanges,
+    getBashRisk: () => input.derived.bashRisk,
+    hasPlanFile: () => input.workspace.hasPlanFile,
+    getPlanStatus: () => input.workspace.planStatus,
+    getEpTier: () => input.evolution.epTier,
+  });
+  context.__pdCallInput = input;
+  context.__pdCallHelpers = helpers;
+  const result = new vm.Script('__pdRuleModule.evaluate(__pdCallInput, __pdCallHelpers)', { filename: workerData.filename + '.call' })
+    .runInContext(context, { timeout: 1000 });
+  process.stdout.write(JSON.stringify({ ok: true, result }));
+} catch (error) {
+  process.stdout.write(JSON.stringify({ ok: false, error: String(error) }));
+  process.exitCode = 1;
+}
+`;
+function normalizeImplementationSource(sourceCode) {
+    const withoutExports = sourceCode
+        .replace(/export\s+const\s+meta\s*=/, 'const meta =')
+        .replace(/export\s+function\s+evaluate\s*\(/, 'function evaluate(');
+    return `${withoutExports}
+globalThis.__pdRuleModule = {
+  meta: typeof meta === 'undefined' ? undefined : meta,
+  evaluate: typeof evaluate === 'undefined' ? undefined : evaluate,
+};`;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function loadRuleImplementationModule(sourceCode, filename) {
+    const context = nodeVm.createContext(Object.create(null));
+    const script = new nodeVm.Script(normalizeImplementationSource(sourceCode), {
+        filename,
+    });
+    // Compile phase: define evaluate + meta (timeout-bounded)
+    script.runInContext(context, {
+        timeout: COMPILE_TIMEOUT_MS,
+        displayErrors: true,
+    });
+    const moduleExports = context.__pdRuleModule;
+    // Note: keep __pdRuleModule on the context so callEvaluate can reference it.
+    // We do NOT delete it here — it's needed for subsequent evaluate calls.
+    const hasEvaluate = typeof moduleExports?.evaluate === 'function';
+    const meta = moduleExports?.meta;
+    if (!hasEvaluate) {
+        // No evaluate function — return early with no callEvaluate
+        return { meta, evaluate: moduleExports?.evaluate };
+    }
+    // PRI-437: Create a context-aware caller that runs evaluate INSIDE the vm
+    // context with a time boundary. This terminates infinite loops and
+    // excessive computation that would otherwise hang the host process.
+    //
+    // The callEvaluate function:
+    //   1. Sets input and helpers as context globals (sandboxed)
+    //   2. Compiles a tiny call script
+    //   3. Runs it in the context with EVALUATE_TIMEOUT_MS
+    //   4. Cleans up globals
+    //   5. Returns the raw result (validation happens in the caller)
+    const normalizedSource = normalizeImplementationSource(sourceCode);
+    const callEvaluate = (input, _helpers) => {
+        const child = spawnSync(process.execPath, [
+            '--max-old-space-size=32',
+            '-e',
+            EVALUATION_PROCESS_SOURCE,
+        ], {
+            input: JSON.stringify({ source: normalizedSource, filename, input }),
+            encoding: 'utf8',
+            timeout: EVALUATE_PROCESS_TIMEOUT_MS,
+            maxBuffer: EVALUATE_PROCESS_OUTPUT_BYTES,
+            windowsHide: true,
+        });
+        if (child.error) {
+            throw new Error(`RuleCode process failed: ${child.error.message}`);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(child.stdout);
+        }
+        catch {
+            const stderr = child.stderr.trim().slice(0, 500);
+            throw new Error(`RuleCode process exited without a valid result${stderr ? `: ${stderr}` : ''}`);
+        }
+        if (!isRecord(parsed) || !Object.hasOwn(parsed, 'ok') || parsed['ok'] !== true || !Object.hasOwn(parsed, 'result')) {
+            const reason = isRecord(parsed) && Object.hasOwn(parsed, 'error') && typeof parsed['error'] === 'string'
+                ? parsed['error'] : 'RuleCode process failed';
+            throw new Error(reason);
+        }
+        return parsed['result'];
+    };
+    return {
+        meta,
+        evaluate: moduleExports?.evaluate,
+        callEvaluate,
+    };
+}

package/dist/core/runtime-v2-prompt-activation-reader.d.ts

@@ -0,0 +1,22 @@
+import type { ActivatedPrinciple, PromptActivationReaderResult } from '@principles/core/runtime-v2';
+export { RUNTIME_V2_PRINCIPLE_BUDGET } from '@principles/core/runtime-v2';
+export type { ActivatedPrinciple, PromptActivationReaderResult };
+export interface PromptActivationReaderDeps {
+    logger?: {
+        warn?: (msg: string) => void;
+        info?: (msg: string) => void;
+        error?: (msg: string) => void;
+    };
+}
+export declare class PromptActivationReader {
+    private readonly workspaceDir;
+    private readonly deps;
+    constructor(workspaceDir: string, deps?: PromptActivationReaderDeps);
+    readActivatedPrinciples(): Promise<PromptActivationReaderResult>;
+    private queryArtifactRow;
+    /**
+     * PRI-305/PRI-307: Load feature flags from .pd/config.yaml instead of .pd/feature-flags.yaml.
+     * Uses the shared plugin config loader for consistency.
+     */
+    private loadFeatureFlags;
+}

package/dist/core/runtime-v2-prompt-activation-reader.js

@@ -0,0 +1,99 @@
+import { SqliteConnection, SqliteActivationStateStore, computeFeatureFlagsFromConfig, filterPromptActivations, resolvePrincipleFromArtifact } from '@principles/core/runtime-v2';
+import { loadPdConfigForPlugin } from './pd-config-loader.js';
+export { RUNTIME_V2_PRINCIPLE_BUDGET } from '@principles/core/runtime-v2';
+export class PromptActivationReader {
+    workspaceDir;
+    deps;
+    constructor(workspaceDir, deps) {
+        this.workspaceDir = workspaceDir;
+        this.deps = deps ?? {};
+    }
+    async readActivatedPrinciples() {
+        const warnings = [];
+        const principles = [];
+        const flags = this.loadFeatureFlags();
+        const promptFlag = flags.flags['prompt'];
+        if (!promptFlag || !promptFlag.enabled) {
+            this.deps.logger?.info?.(`[PD:RuntimeV2] Prompt feature flag disabled — skipping Runtime V2 activation read`);
+            return { principles, warnings: ['prompt_feature_disabled'], source: 'runtime_v2' };
+        }
+        let sqliteConn = null;
+        try {
+            sqliteConn = new SqliteConnection(this.workspaceDir);
+            const store = new SqliteActivationStateStore(sqliteConn);
+            const allActivations = await store.listPromptActivations();
+            const promptActivations = filterPromptActivations(allActivations);
+            for (const activation of promptActivations) {
+                let artifactRow;
+                try {
+                    artifactRow = this.queryArtifactRow(sqliteConn, activation.artifactId);
+                }
+                catch (e) {
+                    const msg = e instanceof Error ? e.message : String(e);
+                    const warning = `artifact_query_failed: artifactId=${activation.artifactId} reason=${msg}; nextAction=check_pi_artifacts_table`;
+                    warnings.push(warning);
+                    this.deps.logger?.warn?.(`[PD:RuntimeV2] ${warning}`);
+                    continue;
+                }
+                if (artifactRow === null) {
+                    const warning = `artifact_not_found: artifactId=${activation.artifactId}; nextAction=check_pi_artifacts_table_or_remove_stale_activation`;
+                    warnings.push(warning);
+                    this.deps.logger?.info?.(`[PD:RuntimeV2] ${warning}`);
+                    continue;
+                }
+                const result = resolvePrincipleFromArtifact(artifactRow, activation);
+                if (result.ok) {
+                    principles.push(result.principle);
+                }
+                else {
+                    warnings.push(result.warning);
+                    this.deps.logger?.warn?.(`[PD:RuntimeV2] ${result.warning}`);
+                }
+            }
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            const warning = `activation_db_unreadable: ${msg}; nextAction=check_workspace_pd_state_db`;
+            warnings.push(warning);
+            this.deps.logger?.warn?.(`[PD:RuntimeV2] ${warning}`);
+        }
+        finally {
+            try {
+                sqliteConn?.close();
+            }
+            catch {
+                // best-effort
+            }
+        }
+        return { principles, warnings, source: 'runtime_v2' };
+    }
+    queryArtifactRow(sqliteConn, artifactId) {
+        try {
+            const db = sqliteConn.getDb();
+            const row = db.prepare(`
+        SELECT artifact_id, artifact_kind, content_json, validation_status
+        FROM pi_artifacts
+        WHERE artifact_id = ?
+      `).get(artifactId);
+            return row ?? null;
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            throw new Error(`artifact_query_failed: artifactId=${artifactId} reason=${msg}; nextAction=check_pi_artifacts_table`);
+        }
+    }
+    /**
+     * PRI-305/PRI-307: Load feature flags from .pd/config.yaml instead of .pd/feature-flags.yaml.
+     * Uses the shared plugin config loader for consistency.
+     */
+    loadFeatureFlags() {
+        const result = loadPdConfigForPlugin(this.workspaceDir);
+        const flags = computeFeatureFlagsFromConfig(result.effective);
+        if (!result.ok) {
+            for (const err of result.errors) {
+                this.deps.logger?.warn?.(`[PD:RuntimeV2] Config error at ${err.path}: ${err.reason}`);
+            }
+        }
+        return flags;
+    }
+}

package/{src/core/schema/db-types.ts → dist/core/schema/db-types.d.ts}

@@ -2,15 +2,10 @@
  * Shared type definitions for database operations.
  * Kept separate to avoid circular dependencies between schema-definitions and migration-runner.
  */
-
- 
-
 /** Minimal interface for better-sqlite3 Database instances. */
 export interface Db {
-  exec(_sql: string): unknown;
-
-  get<T = unknown>(_sql: string, ..._params: unknown[]): T | undefined;
-
-  run(_sql: string, ..._params: unknown[]): unknown;
-  close(): void;
+    exec(_sql: string): unknown;
+    get<T = unknown>(_sql: string, ..._params: unknown[]): T | undefined;
+    run(_sql: string, ..._params: unknown[]): unknown;
+    close(): void;
 }

package/dist/core/schema/db-types.js

@@ -0,0 +1,5 @@
+/**
+ * Shared type definitions for database operations.
+ * Kept separate to avoid circular dependencies between schema-definitions and migration-runner.
+ */
+export {};

package/{src/core/schema/index.ts → dist/core/schema/index.d.ts}

@@ -10,17 +10,8 @@
  *   node scripts/db-migrate.mjs status
  *   node scripts/db-migrate.mjs run
  */
-
 export { MigrationRunner, ensureDatabaseSchema } from './migration-runner.js';
 export { SCHEMAS, getCatalog, DB_TYPES } from './schema-definitions.js';
 export { ALL_MIGRATIONS } from './migrations/index.js';
-
 export type { Db } from './db-types.js';
-export type {
-  Migration,
-  DbType,
-  TableDefinition,
-  ViewDefinition,
-  FtsDefinition,
-  SchemaCatalog,
-} from './migration-runner.js';
+export type { Migration, DbType, TableDefinition, ViewDefinition, FtsDefinition, SchemaCatalog, } from './migration-runner.js';

package/dist/core/schema/index.js

@@ -0,0 +1,15 @@
+/**
+ * Schema Management — Unified database schema definitions and migrations.
+ *
+ * Usage:
+ *   // In a database class constructor:
+ *   import { ensureDatabaseSchema } from './schema';
+ *   ensureDatabaseSchema(db, 'trajectory.db');
+ *
+ * CLI:
+ *   node scripts/db-migrate.mjs status
+ *   node scripts/db-migrate.mjs run
+ */
+export { MigrationRunner, ensureDatabaseSchema } from './migration-runner.js';
+export { SCHEMAS, getCatalog, DB_TYPES } from './schema-definitions.js';
+export { ALL_MIGRATIONS } from './migrations/index.js';