@principles/host-runtime 0.9.2 → 0.10.1

package/dist/behavior-example-pack-assembler.d.ts

@@ -0,0 +1,41 @@
+import type { BehaviorExamplePack } from '@principles/core/runtime-v2';
+import type { RuleHostEvidenceRow, RuleHostContextRow } from '@principles/core/trajectory-types';
+import type { ToolSemanticRegistry } from '@principles/core/runtime-v2';
+export interface BehaviorExampleDataSource {
+    getPainEventByCanonicalId(id: string): {
+        id: number;
+        sessionId: string;
+    } | null;
+    getRuleHostEvidenceRow(id: number): RuleHostEvidenceRow | null;
+    getRuleHostContextRowsBefore(sessionId: string, beforeId: number, limit: number): {
+        rows: readonly RuleHostContextRow[];
+        truncated: boolean;
+    };
+}
+export interface BehaviorExamplePackAssemblerOptions {
+    readonly source: BehaviorExampleDataSource;
+    readonly toolSemantics: ToolSemanticRegistry;
+}
+export interface BehaviorExamplePackAssemblerInput {
+    /** Canonical pain ID (e.g. pain_<ts>_<hash>) — entry point into pain lineage. */
+    readonly sourcePainId: string;
+    /** Owner's natural-language desired outcome — must be non-empty. */
+    readonly ownerDesiredOutcome: string;
+    /** Owner-selected call that demonstrates behaviour to block. */
+    readonly sourceNegativeToolCallId: number;
+    /** Owner-selected calls that demonstrate behaviour to allow (1..3). */
+    readonly positiveToolCallIds: readonly number[];
+    /**
+     * Project directory, used to detect absolute paths that should be redacted
+     * to relative/basename form in the assembled pack.
+     */
+    readonly projectDir: string;
+}
+export declare class BehaviorExamplePackAssembler {
+    private readonly db;
+    private readonly toolSemantics;
+    constructor(opts: BehaviorExamplePackAssemblerOptions);
+    /** Assemble only from explicit Owner labels; execution outcome is not a label. */
+    assemble(input: BehaviorExamplePackAssemblerInput): BehaviorExamplePack;
+    private buildSelectedCase;
+}

package/dist/behavior-example-pack-assembler.js

@@ -0,0 +1,243 @@
+/**
+ * Shared Owner-labelled BehaviorExamplePack assembly (PRI-484 / PRI-992).
+ *
+ * Reads pain lineage + trajectory rows from TrajectoryDatabase and assembles
+ * a validated BehaviorExamplePack for the Artificer. Fail loud on any gap
+ * (missing pain, empty trajectory, invalid pack) — no silent fallback.
+ *
+ * Err-prevention:
+ *   - ERR-001: every DB row field validated as `unknown` (no `as` bypass on
+ *     parsed params_json or row casts).
+ *   - ERR-069: Artificer shared schema — invalid pack must fail loud.
+ *   - ERR-026: reuses production TrajectoryDatabase (no hand-written DDL).
+ *   - rc-2: structural type guards, no `as T` on parsed input.
+ *   - rc-5: Object.hasOwn over `in`.
+ *   - rc-9: every failure path throws a structured Error with a clear reason.
+ *   - PRI-980 review P2-1: trajectory STORE I/O failures throw the typed
+ *     `evidence_source_error` (readTrajectoryStore) so the readiness contract
+ *     preserves them as storage faults, not Owner evidence faults (§6.2).
+ *
+ * Spec: docs/superpowers/specs/2026-06-27-rulecode-context-vision-design.md §7.2
+ *
+ * Boundary: this module is I/O. Pure logic (type + validator) lives in
+ * `@principles/core/runtime-v2` → `behavior-example-pack.ts`.
+ */
+import { buildRuleHostAction } from '@principles/core/runtime-v2/internalization/rule-host-input-builder';
+import { computeBehaviorFacts } from '@principles/core/runtime-v2/internalization/rule-context-v2';
+import { validateBehaviorExamplePack } from '@principles/core/runtime-v2/internalization/behavior-example-pack';
+// Factory lives in evidence-readiness.ts (the classification authority); it is
+// consumed through its registered LEAF subpath. A VALUE import of the
+// runtime-v2 barrel on this satellite path re-pulls the whole LLM graph and
+// fails the satellite-purity guard (OPT-002, scripts/build/check-satellite-purity.mjs) —
+// the leaf is on core's exports allowlist for exactly this consumer.
+import { createOwnerEvidenceScopeError } from '@principles/core/runtime-v2/internalization/evidence-readiness';
+import { assembleBehaviorHistory } from './behavior-history.js';
+// ── internal constants ─────────────────────────────────────────────────────
+const MAX_POSITIVES = 3;
+const MAX_EVIDENCE_REFS = 5;
+const HISTORY_LIMIT = 100;
+const PROTO_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+/**
+ * PRI-980 review P2-1 (SPEC-PD-IAER-001 §6.2 case 3): the trajectory STORE
+ * throwing is an I/O/storage failure of the evidence source itself — it must
+ * surface as the typed `evidence_source_error` kind so the readiness contract
+ * preserves it as a storage fault instead of misreporting "Owner labelled bad
+ * evidence". Structural, never message sniffing: the store RETURNING no row
+ * is a data gap (the typed scope kinds below); the store THROWING is the I/O
+ * failure signal. Assembler-owned data-shape validation errors stay plain
+ * Errors (→ `invalid`), unchanged.
+ */
+function readTrajectoryStore(what, op) {
+    try {
+        return op();
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw createOwnerEvidenceScopeError('evidence_source_error', `[BehaviorExamplePackAssembler] trajectory store ${what} failed (evidence source error, SPEC-PD-IAER-001 §6.2): ${message}`);
+    }
+}
+// ── type guards (rc-2: no `as` bypass) ─────────────────────────────────────
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function hasNoProtoKeys(value) {
+    for (const key of Object.keys(value)) {
+        if (PROTO_KEYS.has(key))
+            return false;
+    }
+    return true;
+}
+// ── BehaviorExamplePackAssembler ───────────────────────────────────────────
+/**
+ * Host-neutral assembler: pain lineage + trajectory → validated BehaviorExamplePack.
+ *
+ * The caller owns source lifecycle and supplies the real host vocabulary.
+ */
+function validateOwnerSelection(input) {
+    if (!Number.isSafeInteger(input.sourceNegativeToolCallId) || input.sourceNegativeToolCallId <= 0) {
+        throw new Error('[BehaviorExamplePackAssembler] sourceNegativeToolCallId must be a positive integer');
+    }
+    if (!Array.isArray(input.positiveToolCallIds) || input.positiveToolCallIds.length === 0 || input.positiveToolCallIds.length > MAX_POSITIVES) {
+        throw new Error('[BehaviorExamplePackAssembler] positiveToolCallIds must contain 1 to at most 3 IDs');
+    }
+    const allIds = [input.sourceNegativeToolCallId, ...input.positiveToolCallIds];
+    if (allIds.some((id) => !Number.isSafeInteger(id) || id <= 0) || new Set(allIds).size !== allIds.length) {
+        throw new Error('[BehaviorExamplePackAssembler] selected tool call IDs must be unique positive integers');
+    }
+}
+function requireSelectedRow(row, id) {
+    if (!row) {
+        // PRI-983: typed scope classification → stable `owner_behavior_examples_stale`
+        // at the readiness contract (the referenced trajectory row does not exist).
+        throw createOwnerEvidenceScopeError('tool_call_not_found', `[BehaviorExamplePackAssembler] selected tool call id=${id} not found`);
+    }
+    return row;
+}
+// ── internal: case builder ─────────────────────────────────────────────────
+/**
+ * Build a GoldenTraceCaseInput from a trajectory tool_call row.
+ *
+ * ERR-001: parses params_json as unknown and structurally validates (must be
+ * a plain object without proto-pollution keys). Throws on malformed input
+ * (rc-9: no silent fallback).
+ */
+function buildCaseFromRow(row, kind, expectedDecision) {
+    if (typeof row.toolName !== 'string' || row.toolName.length === 0) {
+        throw new Error(`[BehaviorExamplePackAssembler] row id=${row.id}: toolName must be a non-empty string (rc-9 fail loud)`);
+    }
+    if (typeof row.paramsJson !== 'string') {
+        throw new Error(`[BehaviorExamplePackAssembler] row id=${row.id}: paramsJson must be a string (rc-9 fail loud)`);
+    }
+    let parsedParams;
+    try {
+        parsedParams = JSON.parse(row.paramsJson);
+    }
+    catch {
+        throw new Error(`[BehaviorExamplePackAssembler] row id=${row.id}: paramsJson is not valid JSON (rc-9 fail loud)`);
+    }
+    if (!isPlainObject(parsedParams)) {
+        throw new Error(`[BehaviorExamplePackAssembler] row id=${row.id}: paramsJson must parse to a non-array object (rc-9 fail loud)`);
+    }
+    if (!hasNoProtoKeys(parsedParams)) {
+        throw new Error(`[BehaviorExamplePackAssembler] row id=${row.id}: paramsJson must not carry prototype-pollution keys (ERR-076, rc-9 fail loud)`);
+    }
+    return {
+        caseId: `case-${kind}-${row.id}`,
+        kind,
+        toolName: row.toolName,
+        params: parsedParams,
+        expectedDecision,
+    };
+}
+/**
+ * Redact sensitive fields from tool call params before they enter the pack.
+ *
+ * First-version policy:
+ *   - Absolute paths outside the project tree → replaced with `<redacted:absolute-path>`
+ *   - String values that look like secrets (long base64 / AKIA-style keys / etc.)
+ *     → replaced with `<redacted:secret>`
+ *
+ * Records each redaction in `notes` so the Artificer and the owner can see
+ * what was stripped (spec §7.2: redactionNotes is part of the pack contract).
+ */
+function looksLikeAbsolutePath(value) {
+    // POSIX absolute path or Windows drive path
+    return value.startsWith('/') || /^[A-Za-z]:[\\/]/.test(value);
+}
+const SECRET_PATTERNS = [
+    /AKIA[0-9A-Z]{16}/, // AWS access key ID
+    /[A-Za-z0-9+/]{40,}/, // long base64-ish token (≥40 chars, no spaces)
+];
+function looksLikeSecret(value) {
+    if (value.length < 20)
+        return false; // too short to be a real secret
+    for (const pattern of SECRET_PATTERNS) {
+        if (pattern.test(value))
+            return true;
+    }
+    return false;
+}
+function redactParams(params, projectDir) {
+    const notes = [];
+    const redacted = {};
+    for (const key of Object.keys(params)) {
+        if (PROTO_KEYS.has(key))
+            continue; // defense in depth (ERR-076)
+        const value = params[key];
+        if (typeof value !== 'string') {
+            redacted[key] = value;
+            continue;
+        }
+        // Path-like values
+        if (looksLikeAbsolutePath(value) && !value.startsWith(projectDir)) {
+            redacted[key] = '<redacted:absolute-path>';
+            notes.push(`redacted absolute path in field "${key}" (outside project tree)`);
+            continue;
+        }
+        // Secret-like values (AWS keys, long base64 tokens, etc.)
+        if (looksLikeSecret(value)) {
+            redacted[key] = '<redacted:secret>';
+            notes.push(`redacted possible secret in field "${key}"`);
+            continue;
+        }
+        redacted[key] = value;
+    }
+    return { redacted, notes };
+}
+export class BehaviorExamplePackAssembler {
+    db;
+    toolSemantics;
+    constructor(opts) {
+        this.db = opts.source;
+        this.toolSemantics = opts.toolSemantics;
+    }
+    /** Assemble only from explicit Owner labels; execution outcome is not a label. */
+    assemble(input) {
+        const pain = readTrajectoryStore(`pain lineage read for canonical_pain_id="${input.sourcePainId}"`, () => this.db.getPainEventByCanonicalId(input.sourcePainId));
+        if (!pain) {
+            // PRI-983: typed scope classification (structural marker — the readiness
+            // contract maps this to the stable `owner_behavior_examples_stale`
+            // code; FR-03: an unresolvable pain reference must never be silently
+            // reused). Message text unchanged (historical audit signature).
+            throw createOwnerEvidenceScopeError('pain_not_found', `[BehaviorExamplePackAssembler] pain event not found for canonical_pain_id="${input.sourcePainId}" (ERR-069 fail loud)`);
+        }
+        validateOwnerSelection(input);
+        const negativeRow = requireSelectedRow(readTrajectoryStore(`evidence row read for id=${input.sourceNegativeToolCallId}`, () => this.db.getRuleHostEvidenceRow(input.sourceNegativeToolCallId)), input.sourceNegativeToolCallId);
+        const positiveRows = input.positiveToolCallIds.map((id) => requireSelectedRow(readTrajectoryStore(`evidence row read for id=${id}`, () => this.db.getRuleHostEvidenceRow(id)), id));
+        for (const row of [negativeRow, ...positiveRows]) {
+            if (row.sessionId !== pain.sessionId) {
+                // PRI-983: cross pain/session selection → typed scope error → stable
+                // `owner_behavior_examples_scope_mismatch` at the readiness contract.
+                throw createOwnerEvidenceScopeError('session_mismatch', `[BehaviorExamplePackAssembler] selected tool call ${row.id} session mismatch; all examples must belong to pain session ${pain.sessionId}`);
+            }
+        }
+        const redactionNotes = [];
+        const buildCtx = { projectDir: input.projectDir, redactionNotes };
+        const sourceNegativeCase = this.buildSelectedCase(negativeRow, 'negative', buildCtx);
+        const positiveCounterexamples = positiveRows.map((row) => this.buildSelectedCase(row, 'positive', buildCtx));
+        const pack = {
+            sourceNegativeCase,
+            ownerDesiredOutcome: input.ownerDesiredOutcome,
+            positiveCounterexamples,
+            evidenceRefs: [`pain:${pain.id}`, `tool_call:${negativeRow.id}`, ...positiveRows.map((row) => `tool_call:${row.id}`)].slice(0, MAX_EVIDENCE_REFS),
+            redactionNotes,
+        };
+        // ── 9. Validate — fail loud (ERR-069) ──
+        const validation = validateBehaviorExamplePack(pack);
+        if (!validation.valid) {
+            throw new Error(`[BehaviorExamplePackAssembler] assembled pack failed validateBehaviorExamplePack: ${validation.errors.join('; ')} (ERR-069 fail loud)`);
+        }
+        return pack;
+    }
+    buildSelectedCase(row, kind, ctx) {
+        const { projectDir, redactionNotes } = ctx;
+        const base = buildCaseFromRow(row, kind, kind === 'negative' ? 'block' : 'allow');
+        const redaction = redactParams(base.params, projectDir);
+        redactionNotes.push(...redaction.notes);
+        const historyResult = readTrajectoryStore(`context history read for session=${row.sessionId} before id=${row.id}`, () => this.db.getRuleHostContextRowsBefore(row.sessionId, row.id, HISTORY_LIMIT));
+        const history = assembleBehaviorHistory(historyResult.rows, historyResult.truncated, { projectDir, toolSemantics: this.toolSemantics });
+        const action = buildRuleHostAction(row.toolName, redaction.redacted, projectDir, { canonicalKind: this.toolSemantics.resolve(row.toolName) });
+        const ruleContext = { version: 2, history, facts: computeBehaviorFacts(history, action.normalizedPath || null, null) };
+        return { ...base, params: redaction.redacted, ruleContext };
+    }
+}

package/dist/behavior-history.d.ts

@@ -0,0 +1,6 @@
+import type { RuleHistoryWindow, ToolSemanticRegistry } from '@principles/core/runtime-v2';
+import type { RuleHostContextRow } from '@principles/core/trajectory-types';
+export declare function assembleBehaviorHistory(rows: readonly RuleHostContextRow[], truncated: boolean, options: {
+    projectDir: string;
+    toolSemantics: ToolSemanticRegistry;
+}): RuleHistoryWindow;

package/dist/behavior-history.js

@@ -0,0 +1,76 @@
+/** Shared validated history assembly; host vocabulary is supplied by its owner. */
+import { extractFilePathFromParams, normalizePathPure } from '@principles/core/runtime-v2/internalization/rule-host-input-builder';
+const VALID_OUTCOMES = new Set(['success', 'failure', 'blocked']);
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isRuleToolOutcome(value) {
+    return typeof value === 'string' && VALID_OUTCOMES.has(value);
+}
+function unavailable(reason) {
+    return {
+        status: 'unavailable',
+        unavailableReason: reason,
+        truncated: false,
+        calls: [],
+    };
+}
+export function assembleBehaviorHistory(rows, truncated, options) {
+    const { projectDir, toolSemantics } = options;
+    const records = [];
+    for (const row of rows) {
+        // ── validate tool_name (ERR-001: unknown) ──
+        const { toolName } = row;
+        if (typeof toolName !== 'string' || toolName.length === 0) {
+            return unavailable(`row id=${row.id}: tool_name must be a non-empty string`);
+        }
+        // ── validate outcome (ERR-001: unknown, enum check) ──
+        const { outcome } = row;
+        if (!isRuleToolOutcome(outcome)) {
+            return unavailable(`row id=${row.id}: outcome "${row.outcome}" is not a valid RuleToolOutcome`);
+        }
+        // ── validate & parse params_json (ERR-001: unknown) ──
+        const paramsJsonStr = row.paramsJson;
+        if (typeof paramsJsonStr !== 'string') {
+            return unavailable(`row id=${row.id}: params_json must be a string`);
+        }
+        let parsedParams;
+        try {
+            parsedParams = JSON.parse(paramsJsonStr);
+        }
+        catch {
+            return unavailable(`row id=${row.id}: params_json is not valid JSON`);
+        }
+        // Must be a non-array object (spec §5.2)
+        if (!isPlainObject(parsedParams)) {
+            return unavailable(`row id=${row.id}: params_json must parse to a non-array object`);
+        }
+        // ── build RuleToolCallRecord ──
+        // PRI-634-F: resolve through the supplied registry (baseline + host
+        // layer) instead of baseline-only canonicalizeToolKind — production tools
+        // like 'shell'/'cmd'/'delete_file' previously degraded to 'other' here
+        // while the gate classified them as bash/write (vocabulary drift).
+        const canonicalKind = toolSemantics.resolve(toolName);
+        // Extract normalized path using the same pure logic as buildRuleHostAction
+        // (avoids production/replay drift, spec §4.4)
+        const rawPath = extractFilePathFromParams(parsedParams, {
+            isBashTool: canonicalKind === 'execute',
+            isWriteTool: canonicalKind === 'write',
+            toolName,
+        });
+        const normalizedPath = normalizePathPure(rawPath, projectDir);
+        records.push({
+            sequenceId: row.id,
+            toolName,
+            canonicalKind,
+            normalizedPath: normalizedPath === '' ? null : normalizedPath,
+            paramsSummary: parsedParams,
+            outcome,
+        });
+    }
+    return {
+        status: 'available',
+        truncated,
+        calls: records,
+    };
+}

package/dist/index.d.ts

@@ -85,3 +85,6 @@ export declare function createProductionHostRuntime(options?: Partial<Pick<HostR
      */
     events?: HostEventEmitter;
 }): HostRuntime;
+export * from './behavior-example-pack-assembler.js';
+export * from './behavior-history.js';
+export * from './workspace-behavior-evidence.js';

package/dist/index.js

@@ -265,3 +265,6 @@ export function createProductionHostRuntime(options = {}) {
         },
     });
 }
+export * from './behavior-example-pack-assembler.js';
+export * from './behavior-history.js';
+export * from './workspace-behavior-evidence.js';

package/dist/internalization-consumer-cycle.d.ts

@@ -20,7 +20,7 @@
  * Hosts inject: a logger, a structured-event sink, their tool catalog, and an
  * env getter. Everything else is the existing production path.
  */
-import { type ToolSemanticRegistry, type BehaviorEvidencePort } from '@principles/core/runtime-v2';
+import { type ToolSemanticRegistry, type BehaviorEvidencePort, type ArtificerTrustedFactsPort } from '@principles/core/runtime-v2';
 import { type ConsumerGovernanceLogger } from './internalization-consumer-governance.js';
 export declare const INTERNALIZATION_AUTO_CONSUMER_FLAG_ID = "internalization_auto_consumer";
 /** Structural logger port — OpenClaw PluginLogger and worker loggers satisfy this. */
@@ -71,6 +71,15 @@ export interface InternalizationConsumerCyclePorts {
      * and the runner is never constructed evidence-less.
      */
     readonly behaviorEvidence?: BehaviorEvidencePort;
+    /**
+     * SPEC-RULECODE-QUALITY-001 A1 (PRI-995): host-injected trusted-facts port
+     * for the artificer intent-basis preflight (SPEC 8.3 seam). Optional:
+     * absent + a scribe-declared required fact degrades OBSERVABLY
+     * (trusted_fact_provider_absent needs_human_review) and the runner is
+     * never constructed — a host capability gap never reads as an Owner fault
+     * or a transient error.
+     */
+    readonly trustedFacts?: ArtificerTrustedFactsPort;
     /** Log label used in human log prefixes ('AutoConsumer' | 'CodexWorker' | …). */
     readonly logLabel: string;
     readonly envGetter?: (name: string) => string | undefined;

package/dist/internalization-consumer-cycle.js

@@ -23,7 +23,7 @@
 import { createRuntimeStateHandle, InternalizationOrchestrator, DreamerRunner, PhilosopherRunner, ScribeRunner, ArtificerRunner, buildArtificerHostSemanticContext, EvaluatorRunner, RolloutReviewerRunner, DefaultDreamerValidator, DefaultPhilosopherValidator, DefaultScribeValidator, DefaultArtificerValidator, DefaultEvaluatorValidator, DefaultRolloutReviewerValidator, PiAiRuntimeAdapter, L2AgentLoopAdapter, ArtificerL2Adapter, buildL2PrincipleReaderFromLedger, OpenClawCliRuntimeAdapter, storeEmitter, createProductionGateDeps, resolveRuntimeConfigFromPdConfig, resolveRuntimeConfigForAgent, AGENT_NAME_FOR_TASK_KIND, isRuntimeConfigError, computeConsumerDecision, FULL_CHAIN_CONSUMER_RUNNER_KINDS, DEFAULT_CONSUMER_RUNNER_KINDS, InternalizationQueueReadModel, MVP_CORE_TASK_KINDS, SqliteConnection, SqliteReconciliationCursorStore, SUCCEEDED_TRANSITIONS_SCOPE, PrincipleTreeLedgerAdapter, 
 // PRI-714: resolve outputLanguage from the same effective config the
 // runners already receive (EP-07: canonical resolved value, not raw input).
-resolveOutputLanguage, hydratePITaskRecord, preflightArtificerOwnerEvidence, } from '@principles/core/runtime-v2';
+resolveOutputLanguage, hydratePITaskRecord, preflightArtificerOwnerEvidence, preflightArtificerIntentBasis, consumeSourceFaultBackoffSkip, advanceSourceFaultBackoff, } from '@principles/core/runtime-v2';
 import { loadLedger } from '@principles/core/principle-tree-ledger';
 import { loadPdConfigForPlugin, loadFeatureFlagFromConfig } from './pd-config.js';
 import { createEvaluatorRepairDeps, createRolloutGovernanceDeps } from './internalization-consumer-governance.js';
@@ -384,6 +384,21 @@ export async function runInternalizationConsumerCycle(workspaceDir, ports) {
                             preflightSkipReason = 'code_rule_capability_disabled';
                             continue;
                         }
+                        // SPEC-RULECODE-QUALITY-001 §9 (Q21): a pending source-fault backoff
+                        // consumes one skip cycle per encounter — the task stays pending,
+                        // zero model cost, and the technical retry happens only after the
+                        // bounded 1-then-2-cycle backoff elapses (restart-durable).
+                        if (await consumeSourceFaultBackoffSkip(candidate.taskId, leasedPiTask, stateManager)) {
+                            const backoffInfo = JSON.stringify({
+                                reason: 'source_fault_backoff_skip',
+                                taskId: candidate.taskId,
+                                nextAction: 'Transient source fault backoff in effect; the task retries automatically at zero model cost.',
+                            });
+                            emitEvent('INTERNALIZATION_CONSUMER_SKIP', backoffInfo);
+                            logger.info(`[PD:${logLabel}] Artificer task ${candidate.taskId} skipped this cycle: source-fault backoff.`);
+                            preflightSkipReason = 'source_fault_backoff_skip';
+                            continue;
+                        }
                         artificerEvidence = await preflightArtificerOwnerEvidence({
                             taskId: candidate.taskId,
                             piTask: leasedPiTask,
@@ -415,16 +430,21 @@ export async function runInternalizationConsumerCycle(workspaceDir, ports) {
                             // assembly at zero model cost), the runner is never constructed,
                             // and the preflight already emitted the structured degradation
                             // telemetry (reason=evidence_source_error, reviewPersisted=false).
+                            // SPEC-RULECODE-QUALITY-001 §9 (Q21/Q22): the transient fault now
+                            // advances the SHARED bounded source-fault backoff (restart-
+                            // durable counter; 3rd consecutive fault ends auto-retry in a
+                            // source_fault_persistent review terminal — never an Owner label).
+                            const persistentFault = await advanceSourceFaultBackoff({ taskId: candidate.taskId, piTask: leasedPiTask, stateManager }, `evidence source error: ${artificerEvidence.detail ?? 'trajectory store I/O fault'}`);
                             const storageInfo = JSON.stringify({
-                                reason: 'evidence_source_error',
+                                reason: persistentFault ? 'source_fault_persistent' : 'evidence_source_error',
                                 taskId: candidate.taskId,
                                 taskKind: candidate.taskKind,
                                 nextAction: artificerEvidence.nextAction,
                                 ...(artificerEvidence.detail !== undefined ? { detail: artificerEvidence.detail } : {}),
                             });
                             emitEvent('INTERNALIZATION_CONSUMER_SKIP', storageInfo);
-                            logger.warn(`[PD:${logLabel}] Artificer task ${candidate.taskId} skipped: evidence source error (storage fault preserved; task stays wake-eligible).`);
-                            preflightSkipReason = 'evidence_source_error';
+                            logger.warn(`[PD:${logLabel}] Artificer task ${candidate.taskId} skipped: evidence source error (storage fault preserved; task stays wake-eligible${persistentFault ? '; auto-retry ended after repeated faults' : ''}).`);
+                            preflightSkipReason = persistentFault ? 'source_fault_persistent' : 'evidence_source_error';
                             continue;
                         }
                         if (artificerEvidence.decision === 'blocked') {
@@ -444,6 +464,61 @@ export async function runInternalizationConsumerCycle(workspaceDir, ports) {
                             preflightSkipReason = 'artificer_blocked_on_owner_evidence';
                             continue;
                         }
+                        // SPEC-RULECODE-QUALITY-001 A1 (Q01/Q20): intent-basis preflight —
+                        // evidence-ready is necessary but NOT sufficient. The scribe
+                        // artifact must carry a valid intentContract AND machine-readable
+                        // executionConditions, and every declared required trusted fact
+                        // must be resolvable through ports.trustedFacts. Any stop verdict
+                        // moves the task to needs_human_review with a stable reasonCode
+                        // and the runner is NEVER constructed (zero generation calls).
+                        // The gate re-derives from the scribe artifact every run — a
+                        // stored verification record is never a pass token.
+                        const intentBasis = await preflightArtificerIntentBasis({
+                            taskId: candidate.taskId,
+                            piTask: leasedPiTask,
+                            owner,
+                            workspaceDir,
+                            stateManager,
+                            eventEmitter: workspaceEmitter,
+                            ...(ports.trustedFacts !== undefined ? { trustedFacts: ports.trustedFacts } : {}),
+                        });
+                        if (intentBasis.decision === 'source_error') {
+                            // Q21: transient artifact-store fault — the preflight already
+                            // advanced the shared bounded backoff; task stays wake-eligible.
+                            emitEvent('INTERNALIZATION_CONSUMER_SKIP', JSON.stringify({
+                                reason: 'intent_source_error',
+                                taskId: candidate.taskId,
+                                nextAction: intentBasis.nextAction,
+                                detail: intentBasis.detail,
+                            }));
+                            logger.warn(`[PD:${logLabel}] Artificer task ${candidate.taskId} skipped: intent-basis source error (transient; bounded backoff applies).`);
+                            preflightSkipReason = 'intent_source_error';
+                            continue;
+                        }
+                        if (intentBasis.decision === 'source_fault_persistent') {
+                            emitEvent('INTERNALIZATION_CONSUMER_INTENT_BLOCKED', JSON.stringify({
+                                taskId: candidate.taskId,
+                                reasonCode: intentBasis.reasonCode,
+                                nextAction: intentBasis.nextAction,
+                                detail: intentBasis.detail,
+                                reviewPersisted: intentBasis.reviewPersisted,
+                            }));
+                            logger.warn(`[PD:${logLabel}] Artificer task ${candidate.taskId} blocked: repeated source faults ended auto-retry (${intentBasis.reasonCode}).`);
+                            preflightSkipReason = 'source_fault_persistent';
+                            continue;
+                        }
+                        if (intentBasis.decision === 'blocked') {
+                            emitEvent('INTERNALIZATION_CONSUMER_INTENT_BLOCKED', JSON.stringify({
+                                taskId: candidate.taskId,
+                                reasonCode: intentBasis.reasonCode,
+                                nextAction: intentBasis.nextAction,
+                                detail: intentBasis.detail,
+                                reviewPersisted: intentBasis.reviewPersisted,
+                            }));
+                            logger.warn(`[PD:${logLabel}] Artificer task ${candidate.taskId} blocked on intent basis (${intentBasis.reasonCode}, reviewPersisted=${intentBasis.reviewPersisted}).`);
+                            preflightSkipReason = 'artificer_blocked_on_intent_basis';
+                            continue;
+                        }
                     }
                 }
                 wakeResult = candidate;
@@ -643,6 +718,12 @@ export async function runInternalizationConsumerCycle(workspaceDir, ports) {
                     ...(artificerEvidence !== null && artificerEvidence.decision === 'ready'
                         ? { behaviorExamplePack: artificerEvidence.pack }
                         : {}),
+                    // SPEC-RULECODE-QUALITY-001 A1 (Owner review P2): the SAME
+                    // trusted-facts port the intent preflight used must ride into the
+                    // runner so the defensive mirror sees the same fact resolutions —
+                    // without this, a port-resolved task would pass the entry gate and
+                    // then be refused by the runner's "provider absent" guard.
+                    ...(ports.trustedFacts !== undefined ? { trustedFacts: ports.trustedFacts } : {}),
                 }, 
                 // PRI-741: thread the host semantic projection into generation.
                 { ...runnerOptions, ...(artificerHostSemanticContext !== undefined ? { hostSemanticContext: artificerHostSemanticContext } : {}) });

package/dist/production-rulehost-gate.js

@@ -85,6 +85,13 @@ export function createProductionRuleHostGate(options = {}) {
         if (action.normalizedPath === null)
             return { decision: 'allow', source: event.source, metadata: { evaluatedLiveRules: 0 } };
         let context;
+        /**
+         * SPEC-RULECODE-QUALITY-001 A3 (Q10): the precise reason a v2 rule is
+         * suspended — carried into the skip warning so each fault kind (absent /
+         * undefined / invalid / failed / unavailable) is distinguishable in host
+         * telemetry instead of merging into one opaque 'unavailable'.
+         */
+        let contextFault;
         let enrichment = { currentGfi: 0, epTier: 0, bashRisk: 'unknown' };
         const request = {
             workspaceDir: event.context.workspaceDir, sessionId: event.context.sessionId,
@@ -110,6 +117,7 @@ export function createProductionRuleHostGate(options = {}) {
                 const candidate = await withinGateDeadline(options.ruleContextProvider(request), startedAt);
                 if (candidate === undefined) {
                     context = undefined;
+                    contextFault = 'provider_returned_undefined';
                 }
                 else {
                     const validation = validateRuleContextV2(candidate);
@@ -117,18 +125,27 @@ export function createProductionRuleHostGate(options = {}) {
                         context = candidate;
                     else {
                         context = UNAVAILABLE_RULE_CONTEXT;
+                        contextFault = 'provider_invalid';
                         addWarning(warnings, `rule_context_invalid: ${validation.errors.join('; ')}`, 'repair the host context provider');
                     }
                 }
             }
             catch (error) {
                 context = UNAVAILABLE_RULE_CONTEXT;
+                contextFault = 'provider_failed';
                 addWarning(warnings, `rule_context_provider_failed: ${error instanceof Error ? error.message : String(error)}`, 'inspect the host context provider and retry');
             }
         }
+        else {
+            contextFault = 'provider_absent';
+        }
         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')] };
+            // SPEC-RULECODE-QUALITY-001 Q24: a deadline-exhausted allow must be
+            // observable as "no rule executed" (evaluatedLiveRules=0), never read
+            // as successful governance — isolated probe finding (the early return
+            // previously carried no evaluation facts at all).
+            return { decision: 'allow', source: event.source, warnings: [boundedWarning('gate_deadline_exceeded', 'inspect host context providers and active RuleCode resource use')], metadata: { evaluatedLiveRules: 0 } };
         }
         if (!fs.existsSync(dbPath)) {
             // Security audit run-1 (gate-failopen-allow-on-state-corruption):
@@ -308,8 +325,28 @@ export function createProductionRuleHostGate(options = {}) {
                                 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');
+                            // SPEC-RULECODE-QUALITY-001 A3 / §7.1 (Q10): MANDATORY runtime
+                            // suspension of context-dependent rules. A v2 rule may only
+                            // execute when the provider resolved a schema-valid context
+                            // whose history.status is 'available'. The old check (`!context`)
+                            // let the truthy UNAVAILABLE_RULE_CONTEXT sentinel (provider
+                            // invalid/thrown) and schema-valid unavailable contexts through,
+                            // so a v2 rule without its own self-protection still executed on
+                            // untrusted input. Skipping happens per-call, per-rule — healthy
+                            // sibling rules (v1 or well-fed v2) keep evaluating, and no
+                            // governance state changes. Intentional behavior change vs the
+                            // pre-fix "legal unavailable still executed" path.
+                            if (context === undefined || context.history.status !== 'available') {
+                                // Reference identity against the frozen sentinel distinguishes
+                                // "the provider faulted" from "the provider legitimately
+                                // declared history unavailable" (same wire shape, different
+                                // fault class — Q10 asserts them separately).
+                                const fault = context === undefined
+                                    ? (contextFault ?? 'provider_absent')
+                                    : context === UNAVAILABLE_RULE_CONTEXT
+                                        ? (contextFault ?? 'provider_invalid')
+                                        : 'history_unavailable';
+                                addWarning(warnings, `rule_context_v2_unavailable: ${fault} (activation=${activationId})`, 'enable and wire the host rule context provider, or regenerate the rule without context dependence');
                                 continue;
                             }
                         }

package/dist/workspace-behavior-evidence.d.ts

@@ -0,0 +1,3 @@
+import type { BehaviorEvidencePort, ToolSemanticRegistry } from '@principles/core/runtime-v2';
+/** Lazy storage access: missing labels need no DB, and a failed open remains observable. */
+export declare function createWorkspaceBehaviorEvidencePort(workspaceDir: string, toolSemantics?: ToolSemanticRegistry): BehaviorEvidencePort;

package/dist/workspace-behavior-evidence.js

@@ -0,0 +1,74 @@
+/** Read-only adapter over the canonical trajectory store; never creates/migrates it. */
+import path from 'node:path';
+import Database from 'better-sqlite3';
+import { createOwnerEvidenceScopeError } from '@principles/core/runtime-v2/internalization/evidence-readiness';
+import { BehaviorExamplePackAssembler } from './behavior-example-pack-assembler.js';
+import { resolveWorkspaceHostToolSemantics } from './host-tool-semantic-resolver.js';
+function record(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function contextRow(value) {
+    if (!record(value) || typeof value.id !== 'number' || !Number.isSafeInteger(value.id)
+        || typeof value.tool_name !== 'string' || typeof value.outcome !== 'string' || typeof value.params_json !== 'string') {
+        throw new Error('Malformed trajectory context row');
+    }
+    const params = JSON.parse(value.params_json);
+    if (!record(params))
+        throw new Error('Malformed trajectory params object');
+    if (Object.keys(params).some((key) => key === '__proto__' || key === 'constructor' || key === 'prototype')) {
+        throw new Error('Unsafe keys in persisted trajectory params');
+    }
+    return { id: value.id, toolName: value.tool_name, outcome: value.outcome, paramsJson: value.params_json };
+}
+function source(db) {
+    return {
+        getPainEventByCanonicalId(id) {
+            const row = db.prepare('SELECT id, session_id FROM pain_events WHERE canonical_pain_id = ? LIMIT 1').get(id);
+            if (row === undefined)
+                return null;
+            if (!record(row) || typeof row.id !== 'number' || typeof row.session_id !== 'string')
+                throw new Error('Malformed pain lineage row');
+            return { id: row.id, sessionId: row.session_id };
+        },
+        getRuleHostEvidenceRow(id) {
+            const row = db.prepare('SELECT id, session_id, tool_name, outcome, params_json FROM tool_calls WHERE id = ? LIMIT 1').get(id);
+            if (row === undefined)
+                return null;
+            if (!record(row) || typeof row.session_id !== 'string')
+                throw new Error('Malformed trajectory evidence row');
+            return { ...contextRow(row), sessionId: row.session_id };
+        },
+        getRuleHostContextRowsBefore(sessionId, beforeId, limit) {
+            const rows = db.prepare('SELECT id, tool_name, outcome, params_json FROM tool_calls WHERE session_id = ? AND id < ? ORDER BY id DESC LIMIT ?').all(sessionId, beforeId, limit + 1);
+            return { rows: rows.slice(0, limit).reverse().map(contextRow), truncated: rows.length > limit };
+        },
+    };
+}
+/** Lazy storage access: missing labels need no DB, and a failed open remains observable. */
+export function createWorkspaceBehaviorEvidencePort(workspaceDir, toolSemantics) {
+    return {
+        assemble(selection) {
+            const resolved = toolSemantics === undefined ? resolveWorkspaceHostToolSemantics(workspaceDir) : null;
+            if (resolved !== null && !resolved.ok)
+                throw createOwnerEvidenceScopeError('evidence_source_error', resolved.reason);
+            const semantics = toolSemantics ?? (resolved !== null && resolved.ok ? resolved.registry : undefined);
+            if (semantics === undefined)
+                throw createOwnerEvidenceScopeError('evidence_source_error', 'Host tool semantics unavailable');
+            let db;
+            try {
+                db = new Database(path.join(workspaceDir, '.state', 'trajectory.db'), { readonly: true, fileMustExist: true });
+            }
+            catch (error) {
+                throw createOwnerEvidenceScopeError('evidence_source_error', `Trajectory evidence unavailable: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            try {
+                // One read snapshot prevents a pack combining different trajectory revisions.
+                return db.transaction(() => new BehaviorExamplePackAssembler({ source: source(db), toolSemantics: semantics })
+                    .assemble({ ...selection, projectDir: workspaceDir }))();
+            }
+            finally {
+                db.close();
+            }
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@principles/host-runtime",
-  "version": "0.9.2",
+  "version": "0.10.1",
   "description": "Shared host-neutral orchestration for Principles Disciple MVP-Core hook paths.",
   "type": "module",
   "main": "./dist/index.js",
@@ -10,7 +10,15 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./behavior-example-pack-assembler": {
+      "types": "./dist/behavior-example-pack-assembler.d.ts",
+      "default": "./dist/behavior-example-pack-assembler.js"
+    },
+    "./behavior-history": {
+      "types": "./dist/behavior-history.d.ts",
+      "default": "./dist/behavior-history.js"
+    }
   },
   "files": [
     "dist",
@@ -23,8 +31,8 @@
     "lint": "eslint \"src/**/*.ts\""
   },
   "dependencies": {
-    "@principles/core": "^1.292.2",
-    "@principles/install-layout": "^0.3.1",
+    "@principles/core": "^1.293.2",
+    "@principles/install-layout": "^0.4.0",
     "better-sqlite3": "^13.0.3",
     "js-yaml": "^5.4.3"
   },