@principles/host-runtime 0.1.1 → 0.2.0

package/dist/internalization-consumer-governance.js

@@ -0,0 +1,152 @@
+/**
+ * Internalization consumer governance wiring (host-neutral, PRI-624).
+ *
+ * Ported verbatim from openclaw-plugin `auto-consumer-governance-wiring.ts`
+ * (P0-D/E/F 生产接线) so the OpenClaw auto-consumer and the Companion
+ * workspace worker share ONE wiring implementation instead of copying it:
+ *   - evaluator: isRepairLoopEnabled + seedArtificerRepairTask (bounded repair)
+ *   - rollout_reviewer: dispatchActivation (approve_rollout → ActivationDispatcher,
+ *     低风险 auto_activate / 高风险 approvals.pending) + reopenRevisionTarget
+ *     (needs_revision → reopen scribe/artificer, 禁止入 approval)
+ *
+ * Everything is assembled from @principles/core stores/dispatchers; the only
+ * host knowledge is a structural logger. Idempotency (INV-08): dispatcher
+ * dedupes by `${artifactId}::${channel}`; reopen idempotency is owned by
+ * orchestrator.reopenTaskForRevision.
+ */
+import { ActivationDispatcher, PromptWriter, DeferArchiveWriter, RuleHostWriter, SqliteConnection, SqliteActivationStateStore, SqliteApprovalQueueStore, SqlitePIArtifactStore, createProductionGateDeps, createPITaskDiagnosticJson, computeFeatureFlagsFromConfig, isFeatureEnabled, } from '@principles/core/runtime-v2';
+import { loadPdConfigForPlugin } from './pd-config.js';
+function normalizeDecision(decision) {
+    if (decision.decision === 'activated') {
+        return { decision: decision.decision, activationId: decision.activationId };
+    }
+    if (decision.decision === 'already_activated') {
+        return { decision: decision.decision, reason: 'idempotent_redispatch' };
+    }
+    if (decision.decision === 'queued_for_approval') {
+        return { decision: decision.decision, reason: decision.approvalId };
+    }
+    // refused / would_* 家族
+    const reason = 'reason' in decision && typeof decision.reason === 'string' ? decision.reason : decision.decision;
+    return { decision: decision.decision, reason };
+}
+function makeFlagProbe(workspaceDir) {
+    const configResult = loadPdConfigForPlugin(workspaceDir);
+    if (!configResult.ok)
+        return () => false;
+    const flags = computeFeatureFlagsFromConfig(configResult.effective);
+    return (flagId) => isFeatureEnabled(flags, flagId);
+}
+/** rollout → ActivationDispatcher 的生产接线 (per dispatch 打开短连接, 与 Console 模式一致) */
+export async function dispatchRolloutActivation(workspaceDir, input, logger) {
+    const connection = new SqliteConnection(workspaceDir);
+    try {
+        const piArtifactStore = new SqlitePIArtifactStore(connection);
+        const artifactReadModel = {
+            getArtifactById: async (id) => {
+                const rec = await piArtifactStore.getArtifactById(id);
+                if (!rec)
+                    return null;
+                return {
+                    artifactId: rec.artifactId,
+                    artifactKind: rec.artifactKind,
+                    sourceTaskId: rec.sourceTaskId,
+                    sourcePrincipleId: rec.sourcePrincipleId,
+                    sourceRuleId: rec.sourceRuleId,
+                    lineageArtifactIds: rec.lineageArtifactIds,
+                    validationStatus: rec.validationStatus,
+                    contentJson: rec.contentJson,
+                    createdAt: rec.createdAt,
+                    updatedAt: rec.updatedAt,
+                };
+            },
+        };
+        const activationStateStore = new SqliteActivationStateStore(connection);
+        const approvalQueueStore = new SqliteApprovalQueueStore(connection);
+        const flagProbe = makeFlagProbe(workspaceDir);
+        const dispatcher = new ActivationDispatcher(artifactReadModel, activationStateStore, {
+            writers: [
+                new PromptWriter(),
+                new RuleHostWriter({ gateDeps: createProductionGateDeps(), featureFlagProbe: flagProbe }),
+                new DeferArchiveWriter(),
+            ],
+            approvalQueueStore,
+        });
+        const decision = await dispatcher.dispatch({
+            artifactId: input.artifactId,
+            channel: input.channel, // InternalizationChannel union; rollout 链的 channel 已由任务元数据校验
+            rolloutDecision: 'auto_activate',
+            actor: { kind: 'system', source: 'rollout_reviewer' },
+            now: new Date().toISOString(),
+            confirm: true,
+            confidence: input.confidence,
+        });
+        const outcome = normalizeDecision(decision);
+        logger?.info?.(`[PD:Consumer] rollout dispatch: artifact=${input.artifactId} channel=${input.channel} → ${outcome.decision}${outcome.activationId ? ` (${outcome.activationId})` : ''}${outcome.reason ? ` reason=${outcome.reason}` : ''}`);
+        return outcome;
+    }
+    finally {
+        try {
+            connection.close();
+        }
+        catch { /* best-effort */ }
+    }
+}
+/** flag 探针: config 异常 → 全 false (fail-closed, 不 throw) */
+/** evaluator repair deps (PRI-509 机制的生产接线; flag 语义保留为运行时开关) */
+export function createEvaluatorRepairDeps(workspaceDir, stateManager, logger) {
+    return {
+        isRepairLoopEnabled: () => {
+            // flag evaluator_artificer_repair_loop (registry 默认已改为 ON — 见
+            // feature-flag-contract.ts;此处读取 config 以保留运行时可关闭能力)
+            const configResult = loadPdConfigForPlugin(workspaceDir);
+            if (!configResult.ok)
+                return false;
+            const flags = computeFeatureFlagsFromConfig(configResult.effective);
+            return isFeatureEnabled(flags, 'evaluator_artificer_repair_loop');
+        },
+        seedArtificerRepairTask: async (params) => {
+            // P0-4: 确定性 revision identity — evaluatorTaskId + iteration 唯一定位
+            // 一个逻辑 repair 任务; 重放 (consumer 重复周期 / crash 恢复) reuse 而非再建。
+            const repairTaskId = `artificer-repair-${params.repairPayload.sourceEvaluatorTaskId}-r${params.repairPayload.repairIteration}`;
+            const existing = await stateManager.getTask(repairTaskId);
+            if (existing) {
+                logger?.info?.(`[PD:Consumer] repair task ${repairTaskId} already exists; reusing (idempotent seed)`);
+                return repairTaskId;
+            }
+            await stateManager.createTask({
+                taskId: repairTaskId,
+                taskKind: 'artificer',
+                status: 'pending',
+                attemptCount: 0,
+                maxAttempts: 3,
+                diagnosticJson: createPITaskDiagnosticJson({
+                    dependencyTaskIds: [...params.inheritedDependencyTaskIds],
+                    channel: params.inheritedChannel,
+                    timeoutMs: params.inheritedTimeoutMs,
+                    inputArtifactRefs: [...params.inheritedInputArtifactRefs],
+                    outputArtifactRefs: [],
+                    repairPayload: params.repairPayload,
+                }),
+            });
+            logger?.info?.(`[PD:Consumer] seeded artificer repair task ${repairTaskId} (iteration ${params.repairPayload.repairIteration})`);
+            return repairTaskId;
+        },
+    };
+}
+/** rollout reviewer 治理 deps: dispatch + revision reopen */
+export function createRolloutGovernanceDeps(workspaceDir, orchestrator, logger) {
+    return {
+        dispatchActivation: (input) => dispatchRolloutActivation(workspaceDir, input, logger),
+        reopenRevisionTarget: async (input) => {
+            const result = await orchestrator.reopenTaskForRevision(input.targetTaskId, {
+                revisionFeedback: input.revisionFeedback,
+                reason: `rollout_revision_iteration_${input.revisionIteration}`,
+                revisionCauseId: `rollout-${input.sourceRolloutTaskId}-r${input.revisionIteration}`,
+            });
+            return result.ok
+                ? { ok: true, reason: result.reason, reopenedTaskId: input.targetTaskId }
+                : { ok: false, reason: result.reason };
+        },
+    };
+}

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) });
@@ -298,3 +360,4 @@ export function resetProductionPainCooldownForTest() {
 export function productionPainCooldownEntryCountForTest() {
     return cooldowns.size;
 }
+export { hasCanonicalSchema as hasProductionPainSchema };

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.1",
+  "version": "0.2.0",
   "description": "Shared host-neutral orchestration for Principles Disciple MVP-Core hook paths.",
   "type": "module",
   "main": "./dist/index.js",