@principles/host-runtime 0.1.0 → 0.2.0

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

@@ -1,5 +1,7 @@
 import Database from 'better-sqlite3';
 import type { HostEvent, HostEventResult } from '@principles/core/host';
+/** Shared with the governance admission path so both gate tool failures identically. */
+export declare const PRODUCTION_WRITE_TOOLS: ReadonlySet<string>;
 export interface PainEvidenceEntry {
     sourceRef: string;
     note: string;
@@ -16,9 +18,67 @@ export interface ProductionPainEnrichment {
 }
 export type PainEnrichmentProvider = (event: HostEvent) => unknown | Promise<unknown>;
 export type PainDatabaseFactory = (databasePath: string) => Database.Database;
+interface NormalizedOutcome {
+    failure: boolean;
+    exitCode: number;
+    error?: string;
+    durationMs?: number;
+    params: unknown;
+    result: unknown;
+}
+/** Structural input accepted by the canonical derivations (HostEvent satisfies it without a cast). */
+export interface ProductionToolEventFields {
+    workspaceDir: string;
+    sessionId: string;
+    turnId?: string;
+    toolName?: string;
+    toolInput?: unknown;
+    toolOutput?: unknown;
+    source: string;
+}
+export interface DerivedToolPainIdentity {
+    eventId: string;
+    painId: string;
+    outcome: NormalizedOutcome;
+    sanitizedParams: Record<string, unknown>;
+    paramsJson: string;
+    resultPreview: string | null;
+}
+/**
+ * The canonical tool-pain identity derivation, exposed for the governance
+ * admission path (Codex Governance Closure SPEC §10): the same normalized
+ * fields fed to the live production handler derive the same deterministic
+ * `pain_host_<sha256>` id, so live and observation-delivered admissions of one
+ * tool call converge on one canonical pain.
+ */
+export declare function deriveProductionToolPainIdentity(fields: ProductionToolEventFields & {
+    canonicalEventId?: string;
+}): DerivedToolPainIdentity;
+/**
+ * The canonical correction-pain identity derivation (SPEC §10/§12): deterministic,
+ * content-derived, retry-safe — replacing the legacy random `correction_<traceId>`
+ * ids. The identity is scoped by a stable OCCURRENCE identity supplied by the
+ * host (Codex hostTurnId / OpenClaw per-session turn index), so:
+ *   - a retry / live+transcript replay of the SAME real occurrence → same pain;
+ *   - the same correction text in a LATER real turn → a NEW pain occurrence.
+ * The raw text participates only in the in-memory hash — it is never persisted
+ * (the persistence boundary sanitizes it; see governance-signal-admission).
+ */
+export declare function deriveProductionCorrectionPainIdentity(fields: {
+    workspaceDir: string;
+    sessionId: string;
+    /** Stable occurrence identity of the real correction event (host turn id / per-session turn index). */
+    occurrenceId: string;
+    text: string;
+}): {
+    eventId: string;
+    painId: string;
+};
+declare function hasCanonicalSchema(db: Database.Database): boolean;
 export declare function createProductionPainEvidenceHandler(options?: {
     painEnrichmentProvider?: PainEnrichmentProvider;
     painDatabaseFactory?: PainDatabaseFactory;
 }): (event: HostEvent) => Promise<HostEventResult>;
 export declare function resetProductionPainCooldownForTest(): void;
 export declare function productionPainCooldownEntryCountForTest(): number;
+export { hasCanonicalSchema as hasProductionPainSchema };

package/dist/production-pain-evidence.js

@@ -4,6 +4,8 @@ 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']);
+/** Shared with the governance admission path so both gate tool failures identically. */
+export const PRODUCTION_WRITE_TOOLS = WRITE_TOOLS;
 const MAX_PREVIEW = 500;
 const PAIN_COOLDOWN_WINDOW_MS = 15 * 60 * 1000;
 const cooldowns = new Map();
@@ -16,7 +18,8 @@ function field(value, key) {
     return Object.getOwnPropertyDescriptor(value, key)?.value;
 }
 function normalizeOutcome(event) {
-    const envelope = event.context.toolOutput;
+    const context = 'context' in event ? event.context : event;
+    const envelope = context.toolOutput;
     const result = field(envelope, 'result') ?? envelope;
     const errorValue = field(envelope, 'error');
     const resultExit = field(result, 'exitCode');
@@ -29,7 +32,7 @@ function normalizeOutcome(event) {
         exitCode,
         ...(error ? { error: error.slice(0, MAX_PREVIEW) } : {}),
         ...(typeof durationValue === 'number' && Number.isFinite(durationValue) && durationValue >= 0 ? { durationMs: durationValue } : {}),
-        params: event.context.toolInput ?? {},
+        params: context.toolInput ?? {},
         result,
     };
 }
@@ -100,16 +103,16 @@ function preview(value) {
     }
 }
 function ids(input) {
-    const { event, outcome, sanitizedParams, canonicalEventId } = input;
+    const { 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,
+        workspaceDir: path.resolve(input.workspaceDir),
+        sessionId: input.sessionId,
+        turnId: input.turnId ?? null,
+        toolName: input.toolName,
+        source: input.source,
         suppliedEventId: canonicalEventId ?? null,
         params: sanitizedParams,
-        result: sanitizeValue(outcome.result, 0, event.context.workspaceDir),
+        result: sanitizeValue(outcome.result, 0, input.workspaceDir),
         error: outcome.error ?? null,
         exitCode: outcome.exitCode,
         failure: outcome.failure,
@@ -117,6 +120,56 @@ function ids(input) {
     const digest = createHash('sha256').update(canonical).digest('hex');
     return { eventId: `host_${digest}`, painId: `pain_host_${digest}` };
 }
+/**
+ * The canonical tool-pain identity derivation, exposed for the governance
+ * admission path (Codex Governance Closure SPEC §10): the same normalized
+ * fields fed to the live production handler derive the same deterministic
+ * `pain_host_<sha256>` id, so live and observation-delivered admissions of one
+ * tool call converge on one canonical pain.
+ */
+export function deriveProductionToolPainIdentity(fields) {
+    const outcome = normalizeOutcome(fields);
+    const sanitizedParams = sanitizeToolParams(outcome.params, fields.workspaceDir);
+    const { eventId, painId } = ids({
+        workspaceDir: fields.workspaceDir,
+        sessionId: fields.sessionId,
+        ...(fields.turnId !== undefined ? { turnId: fields.turnId } : {}),
+        ...(fields.toolName !== undefined ? { toolName: fields.toolName } : {}),
+        source: fields.source,
+        ...(fields.canonicalEventId !== undefined ? { canonicalEventId: fields.canonicalEventId } : {}),
+        outcome,
+        sanitizedParams,
+    });
+    return {
+        eventId,
+        painId,
+        outcome,
+        sanitizedParams,
+        paramsJson: stable(sanitizedParams),
+        resultPreview: preview({ eventId, result: sanitizeValue(outcome.result, 0, fields.workspaceDir) }),
+    };
+}
+/**
+ * The canonical correction-pain identity derivation (SPEC §10/§12): deterministic,
+ * content-derived, retry-safe — replacing the legacy random `correction_<traceId>`
+ * ids. The identity is scoped by a stable OCCURRENCE identity supplied by the
+ * host (Codex hostTurnId / OpenClaw per-session turn index), so:
+ *   - a retry / live+transcript replay of the SAME real occurrence → same pain;
+ *   - the same correction text in a LATER real turn → a NEW pain occurrence.
+ * The raw text participates only in the in-memory hash — it is never persisted
+ * (the persistence boundary sanitizes it; see governance-signal-admission).
+ */
+export function deriveProductionCorrectionPainIdentity(fields) {
+    const canonical = stable({
+        workspaceDir: path.resolve(fields.workspaceDir),
+        sessionId: fields.sessionId,
+        occurrenceId: fields.occurrenceId,
+        source: 'user_correction',
+        text: fields.text,
+    });
+    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' },
@@ -232,7 +285,16 @@ export function createProductionPainEvidenceHandler(options = {}) {
         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 { eventId, painId } = ids({
+            workspaceDir: event.context.workspaceDir,
+            sessionId: event.context.sessionId,
+            ...(event.context.turnId !== undefined ? { turnId: event.context.turnId } : {}),
+            ...(toolName !== undefined ? { toolName } : {}),
+            source: event.source,
+            ...(enrichment.eventId ? { canonicalEventId: enrichment.eventId } : {}),
+            outcome,
+            sanitizedParams,
+        });
         const createdAt = new Date().toISOString();
         const paramsJson = stable(sanitizedParams);
         const resultPreview = preview({ eventId, result: sanitizeValue(outcome.result, 0, event.context.workspaceDir) });
@@ -249,9 +311,16 @@ export function createProductionPainEvidenceHandler(options = {}) {
                 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}`;
+                    // Raw observation only (Pain Diagnosis Persistence SPEC §8): the
+                    // pain row must record WHAT happened, not WHY. Attribution
+                    // (People/Design/Assumption/Tooling) belongs to the Diagnostician.
+                    // confidence stays null — no attribution confidence exists at
+                    // detection time. origin remains 'system_infer' because origin is a
+                    // declared enum (event-types.ts: who reported the pain), not an
+                    // attribution claim.
+                    const reason = `tool=${toolName}; error=${outcome.error ?? `exit=${outcome.exitCode}`}; path=${relativePath}`;
                     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);
+                        .run(event.context.sessionId, sourceObservation.failureSource ?? 'tool_failure', painScore, reason, painScore >= 70 ? 'severe' : painScore >= 40 ? 'moderate' : 'mild', 'system_infer', null, enrichment.evidence?.map((entry) => `${entry.sourceRef}: ${entry.note}`).join('\n') ?? null, painId, null, createdAt);
                 }
             })();
             if (admitted && !duplicate) {
@@ -291,3 +360,4 @@ export function resetProductionPainCooldownForTest() {
 export function productionPainCooldownEntryCountForTest() {
     return cooldowns.size;
 }
+export { hasCanonicalSchema as hasProductionPainSchema };

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

@@ -10,7 +10,6 @@ export interface ProductionRuleContextRequest {
 export type RuleContextProvider = (request: ProductionRuleContextRequest) => unknown | Promise<unknown>;
 export interface RuleInputEnrichment {
     currentGfi: number;
-    recentThinking: boolean;
     epTier: number;
     bashRisk: 'safe' | 'normal' | 'dangerous' | 'unknown';
 }

package/dist/production-rulehost-gate.js

@@ -1,6 +1,7 @@
 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 { scanRetiredContractSymbols } from './legacy-rule-contract-symbols.js';
 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;
@@ -76,7 +77,7 @@ export function createProductionRuleHostGate(options = {}) {
         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' };
+        let enrichment = { currentGfi: 0, epTier: 0, bashRisk: 'unknown' };
         const request = {
             workspaceDir: event.context.workspaceDir, sessionId: event.context.sessionId,
             targetPath: action.normalizedPath, toolName: input.toolName, rawPayload: event.rawPayload,
@@ -85,9 +86,9 @@ export function createProductionRuleHostGate(options = {}) {
             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)
+                    && 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 };
+                    enrichment = { currentGfi: candidate.currentGfi, epTier: candidate.epTier, bashRisk: candidate.bashRisk };
                 }
                 else
                     addWarning(warnings, 'rule_input_enrichment_invalid', 'repair the host enrichment provider');
@@ -127,11 +128,25 @@ export function createProductionRuleHostGate(options = {}) {
         const connection = new SqliteConnection({ workspaceDir: event.context.workspaceDir, readonly: true, bootstrapIfMissing: false });
         const candidates = [];
         try {
+            const globalPause = connection.getDb().prepare(`
+        SELECT pause_id FROM global_rulecode_pauses WHERE status = 'paused' LIMIT 1
+      `).get();
+            if (globalPause !== undefined) {
+                return {
+                    decision: 'allow',
+                    source: event.source,
+                    warnings: [boundedWarning('global_rulecode_pause_active', 'review the incident in the Owner Console before releasing the global pause')],
+                    metadata: { evaluatedLiveRules: 0 },
+                };
+            }
             const rows = connection.getDb().prepare(`
         SELECT a.activation_id, a.artifact_id, a.target_ref, a.action,
+               c.enforcement, c.isolation_decision_id,
                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
+        FROM activations a
+        JOIN pi_artifacts p ON a.artifact_id = p.artifact_id
+        LEFT JOIN activation_control_states c ON a.activation_id = c.activation_id
         WHERE a.channel = 'code_tool_hook' AND a.deactivated_at IS NULL
         ORDER BY a.activated_at ASC
         LIMIT ?
@@ -158,6 +173,15 @@ export function createProductionRuleHostGate(options = {}) {
                         addWarning(warnings, 'activation_row_invalid', 'deactivate and recreate the malformed activation');
                         continue;
                     }
+                    const activationId = typeof row.activation_id === 'string' ? row.activation_id : 'unknown';
+                    if (row.enforcement === 'safety_isolated') {
+                        addWarning(warnings, `activation_safety_isolated: ${activationId}`, 'recover the activation to shadow after reviewing safety evidence');
+                        continue;
+                    }
+                    if (row.enforcement !== 'eligible') {
+                        addWarning(warnings, `activation_control_state_invalid: ${activationId}`, 'repair the activation control state before RuleCode enforcement');
+                        continue;
+                    }
                     const group = groups.get(row.target_ref) ?? [];
                     group.push(row);
                     groups.set(row.target_ref, group);
@@ -216,6 +240,23 @@ export function createProductionRuleHostGate(options = {}) {
                         }
                         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;
+                        // Retired-contract backstop (2026-08-19; host-liveness correction
+                        // 2026-08-21):
+                        // persisted LIVE RuleCode that references removed RuleHost
+                        // contract symbols can never run safely against the new contract
+                        // — reads silently resolve to undefined and change owner-approved
+                        // behavior. The incompatible activation is therefore skipped and
+                        // surfaced with an actionable warning. It must not turn a runtime
+                        // compatibility defect into a host-wide deny; healthy sibling
+                        // rules continue to evaluate. The scan is a local copy (see
+                        // legacy-rule-contract-symbols.ts) so the published bundle keeps
+                        // working against the currently published core.
+                        const retiredSymbols = scanRetiredContractSymbols(content.implementationCode);
+                        if (retiredSymbols.length > 0) {
+                            const nextAction = 'migrate the RuleCode off the retired contract symbols or deactivate the activation, then re-approve a migrated rule';
+                            addWarning(warnings, `legacy_rule_contract_dependency: ${retiredSymbols.join(', ')} (activation=${activationId})`, nextAction);
+                            continue;
+                        }
                         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 });
                     }
@@ -226,8 +267,8 @@ export function createProductionRuleHostGate(options = {}) {
             }
             const hostInput = {
                 action,
-                workspace: { isRiskPath: false, planStatus: 'NONE', hasPlanFile: false },
-                session: { sessionId: event.context.sessionId, currentGfi: enrichment.currentGfi, recentThinking: enrichment.recentThinking },
+                workspace: { isRiskPath: false },
+                session: { sessionId: event.context.sessionId, currentGfi: enrichment.currentGfi },
                 evolution: { epTier: enrichment.epTier },
                 derived: { estimatedLineChanges: estimateLineChanges({ toolName: input.toolName, params: input.params }), bashRisk: enrichment.bashRisk },
                 ...(context ? { context } : {}),

package/dist/rule-implementation-runtime.js

@@ -37,8 +37,6 @@ try {
         ' 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 });

package/dist/workspace-telemetry-emitter.d.ts

@@ -0,0 +1,15 @@
+import { StoreEventEmitter, type TelemetryEvent } from '@principles/core/runtime-v2';
+export type WorkspaceTelemetryPersistFailureSink = (detailJson: string) => void;
+export declare class WorkspaceTelemetryEmitter extends StoreEventEmitter {
+    private readonly upstream;
+    private readonly sinkFilePath;
+    private readonly onPersistFailure;
+    constructor(upstream: StoreEventEmitter, workspaceDir: string, onPersistFailure: WorkspaceTelemetryPersistFailureSink);
+    /**
+     * Validate + persist (allowlist) + forward upstream. Never throws —
+     * persistence errors degrade to the injected failure sink (the upstream
+     * emit semantics are preserved unchanged).
+     */
+    emitTelemetry(event: TelemetryEvent): true;
+    private persist;
+}

package/dist/workspace-telemetry-emitter.js

@@ -0,0 +1,74 @@
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { StoreEventEmitter } from '@principles/core/runtime-v2';
+/**
+ * PRI-634 A3 — workspace-scoped durable observability for critical runner
+ * telemetry (host-neutral; PRI-624 Slice C final integration).
+ *
+ * 背景：`StoreEventEmitter`（进程内单例）生产装配零订阅者、零持久化 ——
+ * `evaluator_adversarial_replay_skipped` 等关键事件发射即丢，事故（如
+ * 48371236 链）无法从日志取证。
+ *
+ * 为什么不是「给全局 storeEmitter 挂落盘订阅者」：singleton 的 telemetry
+ * payload 不含 workspaceDir，multi-workspace 进程下全局订阅者无法判断事件
+ * 归属，会重演 SystemLogger PRI-504 修过的 cross-workspace log leakage
+ * （ERR-092）。正确粒度是 **workspace-scoped**：本 emitter 在 consumer
+ * cycle 的 per-wake 装配处构造，只经手本 workspace runner 发出的事件。
+ *
+ * 持久化策略：**allowlist**，只落盘 4 类 critical events（与 telemetry-event
+ * schema 枚举同源），不做全量 telemetry 无差别写盘（日志量 + 隐私审计面
+ * 无谓扩大）：
+ *   - evaluator_adversarial_replay_skipped
+ *   - evaluator_adversarial_replay
+ *   - evaluator_rule_assembled
+ *   - evaluator_rule_assembly_failed
+ *
+ * 落点 `<workspaceDir>/.pd/telemetry/critical-events.jsonl`（JSONL，一行一
+ * 事件，含完整 TelemetryEvent）。同步 append：事件量小（allowlist 限流），
+ * 换取 crash 前落盘的 durable 语义。写失败绝不影响 runner —— 降级为
+ * `onPersistFailure` 回调（宿主注入的结构化告警口；OpenClaw 是
+ * SystemLogger，Companion worker 是自己的事件口）。
+ */
+const CRITICAL_EVENT_ALLOWLIST = new Set([
+    'evaluator_adversarial_replay_skipped',
+    'evaluator_adversarial_replay',
+    'evaluator_rule_assembled',
+    'evaluator_rule_assembly_failed',
+]);
+export class WorkspaceTelemetryEmitter extends StoreEventEmitter {
+    upstream;
+    sinkFilePath;
+    onPersistFailure;
+    constructor(upstream, workspaceDir, onPersistFailure) {
+        super();
+        this.upstream = upstream;
+        this.onPersistFailure = onPersistFailure;
+        this.sinkFilePath = join(workspaceDir, '.pd', 'telemetry', 'critical-events.jsonl');
+    }
+    /**
+     * Validate + persist (allowlist) + forward upstream. Never throws —
+     * persistence errors degrade to the injected failure sink (the upstream
+     * emit semantics are preserved unchanged).
+     */
+    emitTelemetry(event) {
+        if (CRITICAL_EVENT_ALLOWLIST.has(event.eventType)) {
+            this.persist(event);
+        }
+        return this.upstream.emitTelemetry(event);
+    }
+    persist(event) {
+        try {
+            mkdirSync(dirname(this.sinkFilePath), { recursive: true });
+            appendFileSync(this.sinkFilePath, `${JSON.stringify(event)}\n`, 'utf8');
+        }
+        catch (err) {
+            // Non-fatal by contract: losing a telemetry line must never break the
+            // runner. Surface once per occurrence through the injected host sink.
+            this.onPersistFailure(JSON.stringify({
+                eventType: event.eventType,
+                sinkFilePath: this.sinkFilePath,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@principles/host-runtime",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Shared host-neutral orchestration for Principles Disciple MVP-Core hook paths.",
   "type": "module",
   "main": "./dist/index.js",
@@ -22,16 +22,21 @@
   },
   "dependencies": {
     "@principles/core": "^1.74.1",
+    "@principles/install-layout": "0.1.0",
     "better-sqlite3": "^13.0.3",
     "js-yaml": "^5.2.0"
   },
   "devDependencies": {
-    "@types/better-sqlite3": "^7.6.13",
+    "@types/better-sqlite3": "^9.6.0",
     "@types/node": "^26.1.2",
     "@types/js-yaml": "^4.0.9",
     "typescript": "^7.0.2",
     "vite": "^8.0.16",
     "vitest": "^4.1.10"
   },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/csuzngjh/principles.git"
+  },
   "license": "MIT"
 }