@principles/core 1.284.9 → 1.284.11

package/dist/runtime-v2/internalization/rollout-reviewer-runner.js

@@ -22,6 +22,27 @@ export function resolveRolloutReviewerRunnerOptions(options) {
         outputLanguage: options.outputLanguage,
     };
 }
+/**
+ * PRI-720: resolves the review contract mode for a rollout task.
+ *
+ * - code_tool_hook/skill channels and any explicit `full_chain` override run
+ *   the legacy code-chain review (byte-compatible).
+ * - prompt/defer_archive chains in the STANDARD topology run the principle
+ *   semantic review — recognized structurally by a scribe dependency and the
+ *   ABSENCE of an evaluator dependency (the graph never creates one there).
+ * - A legacy (pre-PRI-720) prompt chain carries an evaluator dep; AC12 forbids
+ *   reinterpreting in-flight chains, so it keeps the code-chain contract.
+ */
+export function resolveRolloutReviewMode(channel, pipelineMode, dependencyTaskKinds) {
+    if (pipelineMode === 'full_chain')
+        return 'code_chain';
+    if (channel !== 'prompt' && channel !== 'defer_archive')
+        return 'code_chain';
+    const kinds = dependencyTaskKinds ?? [];
+    const hasEvaluatorDep = kinds.includes('evaluator');
+    const hasScribeDep = kinds.includes('scribe');
+    return !hasEvaluatorDep && hasScribeDep ? 'principle_semantic' : 'code_chain';
+}
 const ROLLOUT_REVIEWER_PERMANENT_ERROR_CATEGORIES = new Set([
     'storage_unavailable', 'workspace_invalid', 'capability_missing', 'cancelled', 'input_invalid', 'output_invalid',
 ]);
@@ -100,18 +121,20 @@ export class RolloutReviewerRunner {
             }
             const storeRunId = await this.resolveStoreRunId(taskId);
             this.phase = RunnerPhase.BuildingContext;
-            const { contextHash, evaluatorArtifact, sourceEvaluatorArtifactId } = await this.buildContext(taskId);
-            if (!evaluatorArtifact || !sourceEvaluatorArtifactId) {
+            const { contextHash, sourceArtifact, sourceArtifactId, reviewMode } = await this.buildContext(taskId);
+            if (!sourceArtifact || !sourceArtifactId) {
                 return this.retryOrFail({
                     taskId,
                     task: leasedTask,
                     errorCategory: 'input_invalid',
-                    failureReason: sourceEvaluatorArtifactId ? 'Evaluator dependency artifact not found' : 'Evaluator dependency artifact ID not resolved',
+                    failureReason: reviewMode === 'principle_semantic'
+                        ? 'Scribe dependency artifact not found'
+                        : 'Evaluator dependency artifact not found',
                 });
             }
-            this.emitRolloutReviewerEvent('rollout_reviewer_context_built', taskId, { contextHash });
+            this.emitRolloutReviewerEvent('rollout_reviewer_context_built', taskId, { contextHash, reviewMode });
             this.phase = RunnerPhase.Invoking;
-            const runHandle = await this.invokeRuntime({ taskId, contextHash, evaluatorArtifact, sourceEvaluatorArtifactId });
+            const runHandle = await this.invokeRuntime({ taskId, contextHash, sourceArtifact, sourceArtifactId, reviewMode });
             this.emitRolloutReviewerEvent('rollout_reviewer_run_started', taskId, {
                 runtimeKind: this.resolvedOptions.runtimeKind,
             });
@@ -123,18 +146,24 @@ export class RolloutReviewerRunner {
             this.phase = RunnerPhase.FetchingOutput;
             const output = await this.fetchAndParseOutput(runHandle.runId);
             // Lineage echo reconciliation (PRI-272 / ERR-004 / ERR-008 class):
-            // taskId and sourceEvaluatorArtifactId are runner-owned lineage
-            // metadata whose authoritative sources are the task record and the
-            // artifact store read in buildContext(). LLMs routinely truncate or
+            // taskId and the mode-specific source artifact id are runner-owned
+            // lineage metadata whose authoritative sources are the task record and
+            // the artifact store read in buildContext(). LLMs routinely truncate or
             // alter long IDs when echoing them back, and a mismatch fails
             // validation as output_invalid — a permanent error with no retry —
             // dead-ending the candidate before it can reach the approval queue.
             // Overwrite the echoed lineage with the authoritative values before
             // validation; emit telemetry whenever an echo differed so the
             // correction rate stays observable (rc-9-no-silent-fallback).
-            this.reconcileLineageEcho(taskId, output, sourceEvaluatorArtifactId);
+            this.reconcileLineageEcho(taskId, output, {
+                authoritativeSourceArtifactId: sourceArtifactId,
+                reviewMode,
+            });
             this.phase = RunnerPhase.Validating;
-            const validationResult = await this.validator.validate(output, taskId, sourceEvaluatorArtifactId ?? undefined);
+            const validationResult = await this.validator.validate(output, taskId, {
+                expectedSourceArtifactId: sourceArtifactId,
+                reviewMode,
+            });
             if (!validationResult.valid) {
                 return await this.handleValidationError({
                     taskId,
@@ -153,7 +182,9 @@ export class RolloutReviewerRunner {
                 output,
                 task: leasedTask,
                 contextHash,
-                sourceEvaluatorArtifactId,
+                ...(reviewMode === 'principle_semantic'
+                    ? { reviewMode, sourceScribeArtifactId: sourceArtifactId }
+                    : { reviewMode, sourceEvaluatorArtifactId: sourceArtifactId }),
                 channel: hydratePITaskRecord(leasedTask)?.channel,
             });
         }
@@ -168,33 +199,42 @@ export class RolloutReviewerRunner {
      * BasePeerRunner, so it calls the shared helper directly and emits its own
      * telemetry (no automatic runnerName prefix).
      *
-     * The prompt asks the model to copy taskId / sourceEvaluatorArtifactId /
-     * sourceTrace.evaluatorArtifactId verbatim, but long artifact IDs are
-     * routinely truncated or altered on echo. Because a mismatch is classified
-     * output_invalid (a permanent error — no retry), a bad echo permanently
-     * blocks the candidate from reaching the approval queue. Lineage is
-     * runner-owned metadata (rc-6): the authoritative values come from the
-     * task record and the artifact store read in buildContext().
+     * The prompt asks the model to copy taskId / the mode-specific source
+     * artifact id / its sourceTrace counterpart verbatim, but long artifact IDs
+     * are routinely truncated or altered on echo. Because a mismatch is
+     * classified output_invalid (a permanent error — no retry), a bad echo
+     * permanently blocks the candidate from reaching the approval queue.
+     * Lineage is runner-owned metadata (rc-6): the authoritative values come
+     * from the task record and the artifact store read in buildContext().
+     * PRI-720: in principle semantic mode the reviewed source is the scribe
+     * artifact, so the reconciled fields are sourceScribeArtifactId /
+     * sourceTrace.scribeArtifactId.
      *
      * Whenever an echo differed (or sourceTrace was missing), a
      * rollout_reviewer_lineage_echo_corrected telemetry event is emitted so
      * the correction rate stays observable (rc-9-no-silent-fallback).
      */
-    reconcileLineageEcho(taskId, output, authoritativeEvaluatorArtifactId) {
+    reconcileLineageEcho(taskId, output, params) {
+        const principleSemantic = params.reviewMode === 'principle_semantic';
         const correctedFields = reconcileLineageEcho(output, {
             topFields: [
                 { field: 'taskId', authoritativeValue: taskId },
-                { field: 'sourceEvaluatorArtifactId', authoritativeValue: authoritativeEvaluatorArtifactId },
+                principleSemantic
+                    ? { field: 'sourceScribeArtifactId', authoritativeValue: params.authoritativeSourceArtifactId }
+                    : { field: 'sourceEvaluatorArtifactId', authoritativeValue: params.authoritativeSourceArtifactId },
             ],
             trace: {
                 traceField: 'sourceTrace',
-                fields: [{ field: 'evaluatorArtifactId', authoritativeValue: authoritativeEvaluatorArtifactId }],
+                fields: [principleSemantic
+                        ? { field: 'scribeArtifactId', authoritativeValue: params.authoritativeSourceArtifactId }
+                        : { field: 'evaluatorArtifactId', authoritativeValue: params.authoritativeSourceArtifactId }],
             },
         });
         if (correctedFields.length > 0) {
             this.emitRolloutReviewerEvent('rollout_reviewer_lineage_echo_corrected', taskId, {
                 correctedFields,
-                authoritativeSourceEvaluatorArtifactId: authoritativeEvaluatorArtifactId,
+                authoritativeSourceArtifactId: params.authoritativeSourceArtifactId,
+                reviewMode: params.reviewMode,
             });
         }
     }
@@ -206,14 +246,23 @@ export class RolloutReviewerRunner {
         const piTask = hydratePITaskRecord(task);
         const deps = piTask?.dependencyTaskIds ?? [];
         if (deps.length === 0) {
-            this.emitRolloutReviewerEvent('rollout_reviewer_no_dependencies', taskId, {});
-            return { contextHash: 'empty', evaluatorArtifact: null, sourceEvaluatorArtifactId: null };
-        }
+            const emptyMode = resolveRolloutReviewMode(piTask?.channel, piTask?.pipelineMode);
+            this.emitRolloutReviewerEvent('rollout_reviewer_no_dependencies', taskId, { reviewMode: emptyMode });
+            return { contextHash: 'empty', sourceArtifact: null, sourceArtifactId: null, reviewMode: emptyMode };
+        }
+        // Fetch dep tasks once; the review mode is structural (PRI-720/AC12):
+        // a scribe dep without an evaluator dep = principle semantic review; an
+        // evaluator dep (legacy or full_chain chain) = code-chain review.
+        const depEntries = [];
         for (const depId of deps) {
             const depTask = await this.stateManager.getTask(depId);
-            if (!depTask)
-                continue;
-            if (depTask.taskKind !== 'evaluator')
+            if (depTask)
+                depEntries.push({ depId, task: depTask });
+        }
+        const reviewMode = resolveRolloutReviewMode(piTask?.channel, piTask?.pipelineMode, depEntries.map((d) => d.task.taskKind));
+        const wantedDepKind = reviewMode === 'principle_semantic' ? 'scribe' : 'evaluator';
+        for (const { depId, task: depTask } of depEntries) {
+            if (depTask.taskKind !== wantedDepKind)
                 continue;
             if (depTask.status !== 'succeeded') {
                 this.emitRolloutReviewerEvent('rollout_reviewer_dependency_not_succeeded', taskId, {
@@ -227,20 +276,33 @@ export class RolloutReviewerRunner {
                 const [firstArtifact] = artifacts;
                 if (!firstArtifact)
                     continue;
-                const artifactRef = firstArtifact.artifactId;
-                this.emitRolloutReviewerEvent('rollout_reviewer_evaluator_dep_selected', taskId, {
-                    depTaskId: depId,
-                    artifactId: firstArtifact.artifactId,
-                });
+                if (reviewMode === 'principle_semantic') {
+                    this.emitRolloutReviewerEvent('rollout_reviewer_scribe_dep_selected', taskId, {
+                        depTaskId: depId,
+                        artifactId: firstArtifact.artifactId,
+                    });
+                }
+                else {
+                    this.emitRolloutReviewerEvent('rollout_reviewer_evaluator_dep_selected', taskId, {
+                        depTaskId: depId,
+                        artifactId: firstArtifact.artifactId,
+                    });
+                }
                 return {
-                    contextHash: RolloutReviewerRunner.hashContextRefs([artifactRef]),
-                    evaluatorArtifact: firstArtifact.contentJson,
-                    sourceEvaluatorArtifactId: firstArtifact.artifactId,
+                    contextHash: RolloutReviewerRunner.hashContextRefs([firstArtifact.artifactId]),
+                    sourceArtifact: firstArtifact.contentJson,
+                    sourceArtifactId: firstArtifact.artifactId,
+                    reviewMode,
                 };
             }
         }
-        this.emitRolloutReviewerEvent('rollout_reviewer_no_evaluator_artifact', taskId, {});
-        return { contextHash: 'empty', evaluatorArtifact: null, sourceEvaluatorArtifactId: null };
+        if (reviewMode === 'principle_semantic') {
+            this.emitRolloutReviewerEvent('rollout_reviewer_no_scribe_artifact', taskId, { reviewMode });
+        }
+        else {
+            this.emitRolloutReviewerEvent('rollout_reviewer_no_evaluator_artifact', taskId, { reviewMode });
+        }
+        return { contextHash: 'empty', sourceArtifact: null, sourceArtifactId: null, reviewMode };
     }
     static hashContextRefs(refs) {
         if (refs.length === 0)
@@ -261,21 +323,23 @@ export class RolloutReviewerRunner {
         return latestRun.runId;
     }
     async invokeRuntime(params) {
-        let parsedEvaluatorArtifact = null;
-        if (params.evaluatorArtifact) {
+        let parsedSourceArtifact = null;
+        if (params.sourceArtifact) {
             try {
-                parsedEvaluatorArtifact = JSON.parse(params.evaluatorArtifact);
+                parsedSourceArtifact = JSON.parse(params.sourceArtifact);
             }
             catch {
-                parsedEvaluatorArtifact = params.evaluatorArtifact;
+                parsedSourceArtifact = params.sourceArtifact;
             }
         }
         const builder = new RolloutReviewerPromptBuilder();
         const { message, systemPrompt } = builder.buildPrompt({
             taskId: params.taskId,
             contextHash: params.contextHash,
-            evaluatorArtifact: parsedEvaluatorArtifact,
-            sourceEvaluatorArtifactId: params.sourceEvaluatorArtifactId,
+            reviewMode: params.reviewMode,
+            ...(params.reviewMode === 'principle_semantic'
+                ? { sourceScribeArtifactId: params.sourceArtifactId, scribeArtifact: parsedSourceArtifact }
+                : { sourceEvaluatorArtifactId: params.sourceArtifactId, evaluatorArtifact: parsedSourceArtifact }),
             // PRI-714: language directive for review fields (undefined = none).
             outputLanguage: this.resolvedOptions.outputLanguage,
         });
@@ -557,6 +621,51 @@ export class RolloutReviewerRunner {
         }
         return acc;
     }
+    /**
+     * PRI-720 C3: flip the exact reviewed scribe principle artifact to
+     * `validated` on semantic approve. Mirrors the evaluator's approved-path
+     * behavior (evaluator-runner.ts): idempotent updateValidationStatus;
+     * a `false` return is a deterministic store inconsistency surfaced via
+     * structured telemetry (the activation resolver then fails closed to
+     * needs_human_review); a store throw retries (the write is a required
+     * effect of the approve verdict — resume replays it, never a second LLM
+     * verdict).
+     */
+    async validateReviewedScribeArtifactOrThrow(ctx) {
+        const principleArtifactId = ctx.sourceScribeArtifactId;
+        if (!principleArtifactId) {
+            // No reviewed scribe artifact on the context — the validator already
+            // required it, so this is an invariant breach; fail loud (retryOrFail
+            // treats input_invalid as permanent and the approval queue stays honest).
+            throw new PDRuntimeError('input_invalid', `principle semantic approve requires sourceScribeArtifactId on task ${ctx.taskId}`);
+        }
+        try {
+            const updated = await this.artifactStore.updateValidationStatus(principleArtifactId, 'validated');
+            if (!updated) {
+                this.emitRolloutReviewerEvent('rollout_principle_validation_update_not_found', ctx.taskId, {
+                    runId: ctx.runId,
+                    sourceArtifactId: principleArtifactId,
+                    reason: 'scribe_principle_artifact_not_found_in_store',
+                    nextAction: 'verify_artifact_lineage_and_store_consistency',
+                });
+                return;
+            }
+            this.emitRolloutReviewerEvent('rollout_principle_validated', ctx.taskId, {
+                runId: ctx.runId,
+                sourceArtifactId: principleArtifactId,
+                validatedBy: 'rollout_reviewer_principle_semantic_approve',
+            });
+        }
+        catch (updateErr) {
+            this.emitRolloutReviewerEvent('rollout_principle_validation_update_failed', ctx.taskId, {
+                runId: ctx.runId,
+                sourceArtifactId: principleArtifactId,
+                errorMessage: updateErr instanceof Error ? updateErr.message : String(updateErr),
+                nextAction: 'task_will_retry; repeated validated write is idempotent',
+            });
+            throw updateErr;
+        }
+    }
     /**
      * P0-2 (外部复核): dispatch + 结果分类。
      * 返回 true = governance transition 完成 (activated / already_activated /
@@ -692,7 +801,8 @@ export class RolloutReviewerRunner {
     }
     /**
      * 解析修订目标任务 (只读遍历 dep 链):
-     *   rollout → evaluator → artificer → scribe
+     *   rollout → evaluator → artificer → scribe (code 链);
+     *   rollout → scribe (PRI-720 principle 语义链: scribe 是直接依赖)。
      * code_tool_hook → artificer; 其他 → scribe (走到底)。
      */
     async resolveRevisionTarget(taskId, channel) {
@@ -729,8 +839,19 @@ export class RolloutReviewerRunner {
                     break;
             }
         }
-        if (!artificerTaskId)
+        if (!artificerTaskId) {
+            // PRI-720 (C4): principle semantic chain — the scribe is a DIRECT dep of
+            // the rollout (the graph never created an artificer/evaluator). Route
+            // the revision straight back to the authoring scribe instead of
+            // dead-ending in needs_human_review.
+            for (const depId of firstHop) {
+                const dep = await this.stateManager.getTask(depId);
+                if (!dep || dep.taskKind !== 'scribe')
+                    continue;
+                return { taskId: dep.taskId, kind: 'scribe' };
+            }
             return null;
+        }
         if (channel === 'code_tool_hook') {
             return { taskId: artificerTaskId, kind: 'artificer' };
         }
@@ -892,6 +1013,17 @@ export class RolloutReviewerRunner {
     decisionOverride) {
         const decision = decisionOverride ?? ctx.output.review.decision;
         if (decision === 'approve_rollout') {
+            // ── PRI-720 C3: validated 翻转归属转移 ──
+            // In principle semantic mode the evaluator (the legacy validated writer,
+            // evaluator-runner.ts approved path) does not exist on the chain, so the
+            // semantic review's approve owns flipping the EXACT reviewed scribe
+            // artifact to validated. Idempotent (crash-resume re-applies without
+            // contradiction) and identity-preserving: reviewed = validated = approved
+            // = PromptWriter-consumed artifact. Runs inside applyDecisionEffects so
+            // resume replays it as part of the same governance effects.
+            if (ctx.reviewMode === 'principle_semantic') {
+                await this.validateReviewedScribeArtifactOrThrow(ctx);
+            }
             const { candidateId, rejectionDetail } = await this.resolveActivationCandidate(ctx);
             if (!candidateId) {
                 // PRI-634: rejectionDetail 透传给 Owner —— 说明候选为何不合格
@@ -938,6 +1070,23 @@ export class RolloutReviewerRunner {
             throw err;
         }
     }
+    /**
+     * PRI-720: dep-aware review mode for a hydrated task (resume/owner-override
+     * paths, where buildContext did not run). Structural rule — see
+     * resolveRolloutReviewMode: a scribe dep without an evaluator dep is a
+     * principle semantic chain; anything else keeps the code-chain contract.
+     */
+    async resolveReviewModeForTask(piTask) {
+        if (!piTask)
+            return 'code_chain';
+        const kinds = [];
+        for (const depId of piTask.dependencyTaskIds) {
+            const dep = await this.stateManager.getTask(depId);
+            if (dep)
+                kinds.push(dep.taskKind);
+        }
+        return resolveRolloutReviewMode(piTask.channel, piTask.pipelineMode, kinds);
+    }
     /**
      * 入口恢复门: pending completion intent (同 epoch) 是 recovery authority。
      * 返回非 null = 本次 run 以 resume 完成 (LLM 未被调用);
@@ -996,13 +1145,16 @@ export class RolloutReviewerRunner {
             });
         }
         const output = await this.recoverIntentOutput(taskId, intent.sourceRunId);
+        const reviewMode = await this.resolveReviewModeForTask(piTask);
         const ctx = {
             taskId,
             runId: intent.sourceRunId,
             output,
             task: leasedTask,
             contextHash: `resume-${intent.sourceRunId}`,
-            sourceEvaluatorArtifactId: output.sourceEvaluatorArtifactId,
+            ...(reviewMode === 'principle_semantic'
+                ? { reviewMode, sourceScribeArtifactId: output.sourceScribeArtifactId }
+                : { reviewMode, sourceEvaluatorArtifactId: output.sourceEvaluatorArtifactId }),
             channel: piTask.channel,
         };
         const artifactId = `pi-art-${taskId}-${intent.sourceRunId}`;
@@ -1060,14 +1212,18 @@ export class RolloutReviewerRunner {
         if (output.review.decision !== resolution.machineDecision) {
             throw new PDRuntimeError('storage_unavailable', `owner resolution output mismatch for task ${taskId}: recovered decision '${output.review.decision}' != recorded machine decision '${resolution.machineDecision}'`);
         }
+        const overridePiTask = hydratePITaskRecord(leasedTask);
+        const overrideReviewMode = await this.resolveReviewModeForTask(overridePiTask ?? undefined);
         const ctx = {
             taskId,
             runId: resolution.sourceRunId,
             output,
             task: leasedTask,
             contextHash: `owner-override-${resolution.resolutionId}`,
-            sourceEvaluatorArtifactId: output.sourceEvaluatorArtifactId,
-            channel: hydratePITaskRecord(leasedTask)?.channel,
+            ...(overrideReviewMode === 'principle_semantic'
+                ? { reviewMode: overrideReviewMode, sourceScribeArtifactId: output.sourceScribeArtifactId }
+                : { reviewMode: overrideReviewMode, sourceEvaluatorArtifactId: output.sourceEvaluatorArtifactId }),
+            channel: overridePiTask?.channel,
         };
         const artifactId = `pi-art-${taskId}-${resolution.sourceRunId}`;
         const resultRef = `rollout-reviewer://${resolution.sourceRunId}`;
@@ -1182,13 +1338,19 @@ export class RolloutReviewerRunner {
         // validate + lineage echo reconciliation,这里是对存储腐坏的防御)
         let echoedArtifactId;
         if (typeof parsed === 'object' && parsed !== null) {
-            const v = parsed.sourceEvaluatorArtifactId;
+            const v = parsed.sourceEvaluatorArtifactId
+                ?? parsed.sourceScribeArtifactId;
             if (typeof v === 'string')
                 echoedArtifactId = v;
         }
         // runtime-contract-exempt: ERR-001 minimal shape check then full validator.validate — same pattern as fetchAndParseOutput; the cast only narrows post-validation
         const candidate = parsed;
-        const vr = await this.validator.validate(candidate, taskId, echoedArtifactId);
+        const rawTask = await this.stateManager.getTask(taskId);
+        const reviewMode = await this.resolveReviewModeForTask(rawTask ? hydratePITaskRecord(rawTask) ?? undefined : undefined);
+        const vr = await this.validator.validate(candidate, taskId, {
+            expectedSourceArtifactId: echoedArtifactId,
+            reviewMode,
+        });
         if (!vr.valid) {
             throw new PDRuntimeError('storage_unavailable', `completion intent output unrecoverable: run ${sourceRunId} of task ${taskId} failed revalidation (${vr.errors.join('; ')})`);
         }