create-principles-disciple 1.145.6 → 1.145.7

package/core/dist/runtime-v2/internalization/artificer-intent-preflight.js

@@ -0,0 +1,686 @@
+/**
+ * SPEC-RULECODE-QUALITY-001 A1 (PRI-995) — artificer intent-basis preflight.
+ *
+ * The authoritative PRE-MODEL gate for the INTENT BASIS of Artificer tasks on
+ * the `code_tool_hook` channel, invoked by the shared consumer cycle AFTER
+ * the Owner-evidence preflight and BEFORE any runner construction:
+ *
+ *   1. resolve the scribe artifact the artificer would consume (the SAME
+ *      dependency-walk semantics as ArtificerRunner.buildContext);
+ *   2. verify the intent basis deterministically:
+ *        - intentContract present + valid (the prose anchor);
+ *        - executionConditions present + valid (the machine-readable
+ *          declaration of which trusted external facts the principle's
+ *          enforcement depends on);
+ *        - every declared required fact resolvable through a host
+ *          trusted-facts port (SPEC 7.2 four states);
+ *   3. verdict mapping (SPEC 5.3):
+ *        executable                     → generation may proceed; a versioned
+ *                                         derived record lands in task metadata
+ *        intent_unverified / intent_conflict / unsupported /
+ *        needs_evidence                 → atomic needs_human_review stop point
+ *                                         with a stable reasonCode; ZERO
+ *                                         generation calls (Q01/Q20)
+ *        source_error                   → transient store I/O: bounded
+ *                                         technical retry with restart-durable
+ *                                         backoff, ZERO model cost, NEVER an
+ *                                         Owner-fault label (Q21)
+ *        source_fault_persistent        → 3rd consecutive transient fault:
+ *                                         auto-retry ends in a reviewable
+ *                                         terminal that names the source fault
+ *                                         (Q22)
+ *
+ * The stored `intentBasisVerification` record is DERIVED EVIDENCE, never a
+ * pass token: every invocation re-derives the assessment from the CURRENT
+ * scribe artifact, so any material change invalidates a prior record (Q13)
+ * and the generator can never self-declare its own gate satisfied (Q20 —
+ * the gate reads the scribe artifact from the store, not model output).
+ *
+ * A defensive mirror of the executable/stop decision lives inside
+ * ArtificerRunner.invokeRuntime (PRI-981 precedent) so direct run-once/CLI
+ * invocation cannot bypass the entry gate.
+ */
+/* eslint-disable @typescript-eslint/no-use-before-define -- helper functions declared after the main entry, matching the adversarial-loop.ts convention */
+import { createHash } from 'node:crypto';
+import { extractIntentContract, extractExecutionConditions } from './intent-contract.js';
+import { buildArtificerRunCorrelation } from './artificer-run-correlation.js';
+import { PDRuntimeError } from '../error-categories.js';
+import { createPITaskDiagnosticJson, hydratePITaskRecord, mergePITaskMetadata, SOURCE_FAULT_MAX_CONSECUTIVE_FAILURES, SOURCE_FAULT_PERSISTENT_REASON_CODE, } from './pitask-metadata.js';
+/**
+ * Lineage marker for intent NHR transitions (honest by construction — same
+ * convention as ARTIFICER_EVIDENCE_NHR_SOURCE_RUN_ID: no lease-minted run
+ * exists for a pure preflight block).
+ */
+export const ARTIFICER_INTENT_NHR_SOURCE_RUN_ID = 'intent-preflight';
+const WAKE_ELIGIBLE_STATUSES = ['pending', 'retry_wait'];
+/** rc-8: bounded single-line detail for metadata/telemetry payloads. */
+function boundedDetail(value, max = 480) {
+    const flat = value.replace(/\s+/g, ' ').trim();
+    return flat.length > max ? `${flat.slice(0, max)}…[truncated]` : flat;
+}
+function withNhrOutEdge(nextAction) {
+    return `${nextAction} Out-edge once the intent basis is repaired (or to abandon this review): pd runtime internalization retry --confirm.`;
+}
+function sha256Of(value) {
+    return `sha256:${createHash('sha256').update(JSON.stringify(value), 'utf8').digest('hex')}`;
+}
+function readDiagnosticJson(task) {
+    const raw = task.diagnosticJson;
+    return typeof raw === 'string' && raw.trim() !== '' ? raw : null;
+}
+/**
+ * Atomic needs_human_review transition (evidence-preflight precedent): status
+ * + humanReviewContext (+ any same-write metadata overrides) in ONE
+ * CAS-guarded write, then the read-back invariant. Idempotent for a task
+ * already in needs_human_review (Q14: a repeat stop never duplicates or
+ * rewrites the review context — the lost CAS returns the durable state).
+ */
+async function transitionToNeedsHumanReview(params, context, metadataOverrides = {}) {
+    const { taskId, piTask, stateManager } = params;
+    const merged = mergePITaskMetadata(piTask, { humanReviewContext: context, ...metadataOverrides });
+    const patch = {
+        status: 'needs_human_review',
+        diagnosticJson: createPITaskDiagnosticJson(merged),
+    };
+    const expectedDiagnosticJson = readDiagnosticJson(piTask);
+    let updated = null;
+    for (const expectedStatus of WAKE_ELIGIBLE_STATUSES) {
+        updated = await stateManager.updateTaskIfDiagnosticJsonUnchanged(taskId, expectedDiagnosticJson, patch, { expectedStatus });
+        if (updated !== null)
+            break;
+    }
+    if (!updated) {
+        const current = await stateManager.getTask(taskId);
+        return current?.status === 'needs_human_review';
+    }
+    const current = await stateManager.getTask(taskId);
+    if (!current || current.status !== 'needs_human_review') {
+        throw new PDRuntimeError('storage_unavailable', `needs_human_review effect not durable for task ${taskId} (read-back status: ${current?.status ?? 'task_missing'})`);
+    }
+    return true;
+}
+/** Best-effort metadata patch from a WAKE-ELIGIBLE state; false = CAS lost (observable, never fabricated). */
+async function patchTaskMetadata(params, overrides) {
+    const { taskId, piTask, stateManager } = params;
+    const merged = mergePITaskMetadata(piTask, overrides);
+    for (const expectedStatus of WAKE_ELIGIBLE_STATUSES) {
+        const updated = await stateManager.updateTaskIfDiagnosticJsonUnchanged(taskId, readDiagnosticJson(piTask), { diagnosticJson: createPITaskDiagnosticJson(merged) }, { expectedStatus });
+        if (updated !== null)
+            return true;
+    }
+    return false;
+}
+/**
+ * Resolve the scribe artifact with the SAME dependency-walk semantics as
+ * ArtificerRunner.buildContext: dependencyTaskIds → succeeded scribe task →
+ * first artifact. Store errors bubble as source faults; a clean absence
+ * returns null (unresolved dependency — a material stop, not transient).
+ */
+async function resolveScribeArtifact(params) {
+    const { piTask, stateManager, artifactStore } = params;
+    for (const depId of piTask.dependencyTaskIds) {
+        const depTask = await stateManager.getTask(depId);
+        if (!depTask || depTask.taskKind !== 'scribe' || depTask.status !== 'succeeded')
+            continue;
+        const store = artifactStore ?? stateManager.piArtifactStore;
+        const artifacts = await store.listBySourceTaskId(depId);
+        const [first] = artifacts;
+        if (first !== undefined) {
+            // The scribe task's OWN dependencies carry the upstream intent material
+            // (philosopher stage) — the second, independent leg of the intent basis
+            // (Owner review R3: a verdict may never rest on the scribe artifact
+            // alone, because every audited surface would then come from one model
+            // output).
+            const hydrated = hydratePITaskRecord(depTask);
+            const scribeDependencyTaskIds = hydrated?.dependencyTaskIds ?? [];
+            return { artifactId: first.artifactId, contentJson: first.contentJson, scribeDependencyTaskIds };
+        }
+    }
+    return null;
+}
+/**
+ * Resolve the UPSTREAM intent material (philosopher stage) — the independent
+ * second leg the intent verdict must be bound to. Walks the scribe task's
+ * dependencies for a succeeded philosopher task and flattens its artifact's
+ * string content into a normalised material pool. Returns null when no
+ * philosopher artifact is resolvable — a condition the caller must treat as a
+ * STOP (a generation verdict that rests on the scribe artifact alone is
+ * exactly the under-reporting shape the R3 review reproduced).
+ */
+async function resolveUpstreamMaterial(params, scribeDependencyTaskIds) {
+    const { stateManager, artifactStore } = params;
+    const store = artifactStore ?? stateManager.piArtifactStore;
+    return collectUpstreamNormalisedText(async (depId) => stateManager.getTask(depId), (sourceTaskId) => store.listBySourceTaskId(sourceTaskId), scribeDependencyTaskIds);
+}
+/**
+ * Shared upstream-material resolver (entry preflight AND the runner's
+ * defensive mirror use the SAME walk so the mirror can never be weaker than
+ * the gate).
+ */
+export async function collectUpstreamNormalisedText(getTask, listBySourceTaskId, scribeDependencyTaskIds) {
+    for (const depId of scribeDependencyTaskIds) {
+        const depTask = await getTask(depId);
+        if (!depTask || depTask.taskKind !== 'philosopher' || depTask.status !== 'succeeded')
+            continue;
+        const artifacts = await listBySourceTaskId(depId);
+        const [first] = artifacts;
+        if (first === undefined)
+            continue;
+        const parsed = safeParseJson(first.contentJson);
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+            return null;
+        const texts = [];
+        // Only intent-bearing fields count as upstream material. Artifact IDs
+        // and timestamps cannot turn an empty/corrupt analysis into evidence.
+        // `analysis` retains the existing compact philosopher material shape.
+        for (const key of ['thesis', 'principleCandidate', 'risks', 'analysis']) {
+            if (Object.hasOwn(parsed, key))
+                collectAllStrings(Reflect.get(parsed, key), texts, 0);
+        }
+        const normalisedText = normaliseForAnchor(texts.join(' '));
+        return normalisedText.length > 0 ? { normalisedText } : null;
+    }
+    return null;
+}
+function safeParseJson(contentJson) {
+    try {
+        return JSON.parse(contentJson);
+    }
+    catch {
+        return null;
+    }
+}
+/** Depth-bounded string collector for the upstream material pool (rc-8 bound). */
+function collectAllStrings(value, out, depth) {
+    if (depth > 6 || out.length > 400)
+        return;
+    if (typeof value === 'string') {
+        if (value.trim() !== '')
+            out.push(value);
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const entry of value)
+            collectAllStrings(entry, out, depth + 1);
+        return;
+    }
+    if (typeof value === 'object' && value !== null) {
+        for (const key of Object.keys(value)) {
+            collectAllStrings(value[key], out, depth + 1);
+        }
+    }
+}
+/**
+ * Normalise text for anchoring: lowercase, collapse whitespace, strip
+ * punctuation to a comparable spine. Deliberately language-mixed (the scribe
+ * contract can carry zh-CN or en material).
+ */
+function normaliseForAnchor(text) {
+    return text.toLowerCase().replace(/[\s`'"“”‘’、，。：；！？（）\]{}()【】,.;:!?\-—_/\\*#]+/gu, '');
+}
+/** Approval-semantics signal vocabulary (substring, EN+ZH). */
+const APPROVAL_SIGNAL_WORDS = ['confirm', 'approv', '批准', '确认'];
+/** Which vocabulary words appear in a raw text (for upstream audit detail). */
+function approvalSignalsInText(text) {
+    if (typeof text !== 'string' || text.length === 0)
+        return [];
+    const lower = text.toLowerCase();
+    return APPROVAL_SIGNAL_WORDS.filter((word) => lower.includes(word));
+}
+/**
+ * Collect the intent-distillation material from the parsed scribe artifact:
+ * the four Owner-intent contract fields plus the principle draft statement —
+ * exactly the surfaces the scribe instructions require to be grounded in
+ * Owner-attributed text. Absent/ill-typed fields are skipped (the
+ * intentContract presence itself is already a precondition upstream).
+ */
+function collectIntentMaterial(parsed) {
+    const fields = [];
+    const push = (name, value) => {
+        if (typeof value === 'string' && value.trim() !== '')
+            fields.push({ name, text: value });
+    };
+    if (typeof parsed === 'object' && parsed !== null) {
+        const record = parsed;
+        const draft = typeof record.principleDraft === 'object' && record.principleDraft !== null
+            ? record.principleDraft
+            : {};
+        push('principleDraft.statement', draft.statement);
+        if (typeof record.intentContract === 'object' && record.intentContract !== null) {
+            const contract = record.intentContract;
+            push('intentContract.ownerIntent', contract.ownerIntent);
+            push('intentContract.targetBehavior', contract.targetBehavior);
+            push('intentContract.forbiddenBehavior', contract.forbiddenBehavior);
+            push('intentContract.validationExpectation', contract.validationExpectation);
+        }
+    }
+    const normalisedText = normaliseForAnchor(fields.map((field) => field.text).join(' '));
+    const approvalSignalFields = fields
+        .filter((field) => APPROVAL_SIGNAL_WORDS.some((word) => field.text.toLowerCase().includes(word)))
+        .map((field) => field.name);
+    return {
+        normalisedText,
+        approvalSignalFields,
+        hasApprovalSignal: approvalSignalFields.length > 0,
+    };
+}
+/**
+ * A declared basis is anchored when a bounded normalised prefix of it appears
+ * in the normalised intent material (quote-or-precise-cite contract). Very
+ * short bases (<8 normalised chars) must appear in full — too little text to
+ * trust a partial anchor.
+ */
+function isTextualBasisAnchored(textualBasis, normalisedMaterial) {
+    const normalisedBasis = normaliseForAnchor(textualBasis);
+    if (normalisedBasis.length < 4)
+        return false;
+    if (normalisedMaterial.length === 0)
+        return false;
+    const anchor = normalisedBasis.length >= 8 ? normalisedBasis.slice(0, 12) : normalisedBasis;
+    return normalisedMaterial.includes(anchor);
+}
+/**
+ * The pure decision core (no I/O): assess the intent basis from the resolved
+ * scribe artifact. Deterministic — no LLM, no keyword approval detection; the
+ * condition basis is the scribe's structured declaration, never prose parsed
+ * at this gate.
+ */
+export function assessIntentBasis(input) {
+    const { scribeArtifact, upstreamMaterial, trustedFacts } = input;
+    if (scribeArtifact === null) {
+        return {
+            status: 'intent_unverified',
+            reasonCode: 'scribe_dependency_unresolved',
+            detail: 'no succeeded scribe dependency artifact resolvable for this artificer task',
+            nextAction: 'Inspect the task lineage; the scribe stage must succeed and persist its artifact before code generation.',
+        };
+    }
+    // Owner review R3 — UPSTREAM BINDING: every audited surface below would be
+    // one model output grading itself if the scribe artifact were the only
+    // material. No philosopher material → no verdict.
+    if (upstreamMaterial === null || upstreamMaterial.normalisedText.trim() === '') {
+        return {
+            status: 'intent_unverified',
+            reasonCode: 'upstream_material_unavailable',
+            detail: "no valid, non-empty philosopher material resolvable from the scribe task's dependencies — missing, malformed, or empty upstream artifacts cannot establish the intent basis",
+            nextAction: 'Inspect the task lineage and philosopher artifact content; restore valid non-empty intent material before retrying generation.',
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(scribeArtifact.contentJson);
+    }
+    catch (error) {
+        return {
+            status: 'intent_unverified',
+            reasonCode: 'scribe_artifact_unparseable',
+            detail: `scribe artifact ${scribeArtifact.artifactId} contentJson is not parseable JSON: ${error instanceof Error ? error.message : String(error)}`,
+            nextAction: 'Inspect and repair the scribe artifact row; a corrupted anchor must not reach generation.',
+        };
+    }
+    const intentContract = extractIntentContract(parsed);
+    if (intentContract === null) {
+        const hadKey = typeof parsed === 'object' && parsed !== null && Object.hasOwn(parsed, 'intentContract');
+        return {
+            status: 'intent_unverified',
+            reasonCode: hadKey ? 'intent_contract_invalid' : 'intent_contract_missing',
+            detail: hadKey
+                ? `scribe artifact ${scribeArtifact.artifactId} carries a malformed intentContract`
+                : `scribe artifact ${scribeArtifact.artifactId} predates the intent contract (no intentContract key)`,
+            nextAction: 'Re-run the scribe stage so the Owner-intent contract is distilled and carried on the artifact.',
+        };
+    }
+    const { conditions, corrupted } = extractExecutionConditions(parsed);
+    if (conditions === null) {
+        return {
+            status: 'intent_unverified',
+            reasonCode: corrupted ? 'execution_conditions_invalid' : 'execution_conditions_missing',
+            detail: corrupted
+                ? `scribe artifact ${scribeArtifact.artifactId} carries a malformed executionConditions declaration`
+                : `scribe artifact ${scribeArtifact.artifactId} predates executionConditions (legacy material cannot support pre-generation verification)`,
+            nextAction: 'Re-run the scribe stage so the machine-readable execution conditions are declared (requiredFacts: [] is valid when no trusted external fact is needed).',
+        };
+    }
+    // Conflict check: same factKind declared with contradictory `required` flags.
+    const requiredByKind = new Map();
+    for (const fact of conditions.requiredFacts) {
+        const previous = requiredByKind.get(fact.factKind);
+        if (previous !== undefined && previous !== fact.required) {
+            return {
+                status: 'intent_conflict',
+                reasonCode: 'required_fact_conflict',
+                detail: `executionConditions declare contradictory requirements for factKind '${fact.factKind}'`,
+                nextAction: 'Re-run the scribe stage; the contradictory declarations must be resolved at the source, never by the generator.',
+            };
+        }
+        requiredByKind.set(fact.factKind, fact.required);
+    }
+    // SPEC-RULECODE-QUALITY-001 A1 (Owner review R2/R3) — two-direction audit
+    // of the declaration against BOTH material pools (scribe + upstream).
+    // 口径 (R3 exact-bypass fix): only required:true declarations count as
+    // claimed — a required:false entry is semantically unclaimed (downstream
+    // filters it out), so design_approval + required:false must NOT satisfy
+    // the name check and then filter to an empty dependency set.
+    // The keyword sweep is a SECONDARY, stop-only layer; the PRIMARY guarantee
+    // is the upstream binding above. Known disclosed boundary (NOT closed):
+    // synonym phrasings absent from the small vocabulary can evade the sweep
+    // when BOTH layers use them — the structural answers are the upstream
+    // binding and the structured declaration, not vocabulary growth.
+    const scribeMaterial = collectIntentMaterial(parsed);
+    const effectiveFacts = conditions.requiredFacts.filter((fact) => fact.required);
+    const effectiveFactKinds = effectiveFacts.map((fact) => fact.factKind.toLowerCase()).join(' ');
+    const upstreamSignalFields = approvalSignalsInText(upstreamMaterial.normalisedText);
+    const pools = [
+        { label: 'scribe', hasSignal: scribeMaterial.hasApprovalSignal, fields: scribeMaterial.approvalSignalFields },
+        { label: 'upstream', hasSignal: upstreamSignalFields.length > 0, fields: upstreamSignalFields },
+    ];
+    for (const pool of pools) {
+        if (pool.hasSignal && !/approv/.test(effectiveFactKinds)) {
+            return {
+                status: 'intent_unverified',
+                reasonCode: 'approval_dependency_undeclared',
+                detail: `${pool.label} material carries approval semantics (signal in: ${pool.fields.join(', ')}) but executionConditions declare no REQUIRED approval-kind fact — an under-reported approval dependency must not reach generation`,
+                nextAction: 'Re-run the scribe stage: declare the approval dependency in executionConditions (factKind e.g. design_approval with required: true) with its textual basis, or correct the material if it overstates the requirement.',
+            };
+        }
+    }
+    // textualBasis anchoring — same required:true口径; the anchor pool is the
+    // UNION of the scribe intent material and the upstream material, so a fact
+    // requirement can be bound to the upstream intent it was distilled from.
+    const combinedPool = scribeMaterial.normalisedText + ' ' + upstreamMaterial.normalisedText;
+    for (const fact of effectiveFacts) {
+        if (!isTextualBasisAnchored(fact.textualBasis, combinedPool)) {
+            return {
+                status: 'intent_unverified',
+                reasonCode: 'textual_basis_unanchored',
+                detail: `required fact '${fact.factKind}' textualBasis ("${fact.textualBasis.replace(/\s+/g, ' ').slice(0, 120)}") cannot be anchored in the intent material (scribe intentContract + statement + upstream philosopher material)`,
+                nextAction: 'Re-run the scribe stage: quote or precisely cite the Owner-attributed text the fact requirement was read from.',
+            };
+        }
+    }
+    const requiredFacts = effectiveFacts;
+    if (requiredFacts.length > 0 && trustedFacts === undefined) {
+        return {
+            status: 'unsupported',
+            reasonCode: 'trusted_fact_provider_absent',
+            detail: `executionConditions require trusted fact(s) [${requiredFacts.map((fact) => fact.factKind).join(', ')}] but this host injects no trusted-facts provider`,
+            nextAction: 'Host capability gap, not a transient error: generation waits until a trusted-facts source exists (SPEC §9 缺provider).',
+        };
+    }
+    const resolutions = [];
+    for (const fact of requiredFacts) {
+        const outcome = trustedFacts?.resolveRequiredFact({ factKind: fact.factKind, taskId: input.taskId });
+        if (outcome === undefined || outcome.resolution === 'unknown') {
+            return {
+                status: 'needs_evidence',
+                reasonCode: 'trusted_fact_unknown',
+                detail: `trusted fact '${fact.factKind}' resolved to unknown${outcome?.detail !== undefined ? `: ${outcome.detail}` : ''}`,
+                nextAction: 'The trusted-facts source cannot confirm this fact yet; generation waits for the authoritative material.',
+            };
+        }
+        resolutions.push({ factKind: fact.factKind, resolution: outcome.resolution });
+    }
+    return { status: 'executable', conditions, requiredFacts: resolutions };
+}
+/**
+ * Run the intent-basis preflight for one code_tool_hook Artificer task.
+ * The caller owns channel resolution; this module never re-guesses channels.
+ */
+export async function preflightArtificerIntentBasis(params) {
+    const { taskId, piTask, owner, workspaceDir, eventEmitter, trustedFacts } = params;
+    let scribeArtifact;
+    try {
+        scribeArtifact = await resolveScribeArtifact(params);
+    }
+    catch (error) {
+        // Source I/O fault: bounded technical retry, never an Owner label (Q21/Q22).
+        const faultDetail = `artifact store read failed: ${error instanceof Error ? error.message : String(error)}`;
+        return applySourceFault(params, faultDetail);
+    }
+    // Owner review R3: resolve the UPSTREAM (philosopher) material — the second
+    // independent leg. Store I/O on this leg is a source fault like any other
+    // (Q21); a clean unresolvable result is a material stop, handled inside
+    // assessIntentBasis.
+    let upstreamMaterial = null;
+    if (scribeArtifact !== null) {
+        try {
+            upstreamMaterial = await resolveUpstreamMaterial(params, scribeArtifact.scribeDependencyTaskIds);
+        }
+        catch (error) {
+            const faultDetail = `upstream artifact read failed: ${error instanceof Error ? error.message : String(error)}`;
+            return applySourceFault(params, faultDetail);
+        }
+    }
+    // The assessment re-derives from the CURRENT artifact on every run — a
+    // stored record is never consulted as a pass token (Q13/Q20).
+    const assessment = assessIntentBasis({ scribeArtifact, upstreamMaterial, trustedFacts, taskId });
+    eventEmitter.emitTelemetry({
+        eventType: 'artificer_intent_basis_checked',
+        traceId: taskId,
+        timestamp: new Date().toISOString(),
+        sessionId: owner,
+        agentId: 'artificer',
+        payload: {
+            ...buildArtificerRunCorrelation({
+                taskId,
+                attemptNumber: piTask.attemptCount,
+                executionMode: 'preflight',
+                reasonCode: assessment.status === 'executable' ? 'executable' : assessment.reasonCode,
+                workspaceDir,
+            }),
+            channel: 'code_tool_hook',
+            gateStatus: assessment.status,
+            ...(assessment.status !== 'executable' ? { detail: boundedDetail(assessment.detail) } : {}),
+        },
+    });
+    // A successful read clears any lingering technical-fault state (§9) — in
+    // the SAME metadata write as the record / review context (atomic).
+    const backoffExisted = piTask.sourceFaultBackoff !== undefined;
+    const clearBackoff = backoffExisted ? { sourceFaultBackoff: undefined } : {};
+    if (assessment.status === 'executable') {
+        const parsed = scribeArtifact !== null ? safeParse(scribeArtifact.contentJson) : null;
+        const intentContract = parsed !== null ? extractIntentContract(parsed) : null;
+        const record = {
+            version: 1,
+            checkedAt: new Date().toISOString(),
+            checkedBy: 'deterministic-preflight',
+            sourceScribeArtifactId: scribeArtifact?.artifactId ?? '',
+            scribeArtifactDigest: sha256Of(scribeArtifact?.contentJson ?? ''),
+            ...(intentContract !== null ? { intentContractDigest: sha256Of(intentContract) } : {}),
+            ...(assessment.conditions !== undefined ? { executionConditionsDigest: sha256Of(assessment.conditions) } : {}),
+            requiredFacts: assessment.requiredFacts,
+            result: 'executable',
+        };
+        const recordPersisted = await patchTaskMetadata(params, { intentBasisVerification: record, ...clearBackoff });
+        // rc-9: a lost record CAS (concurrent writer) degrades observably — the
+        // verdict carries recordPersisted and the telemetry payload repeats it,
+        // so a silent "recorded" is never implied.
+        eventEmitter.emitTelemetry({
+            eventType: 'artificer_intent_basis_checked',
+            traceId: taskId,
+            timestamp: new Date().toISOString(),
+            sessionId: owner,
+            agentId: 'artificer',
+            payload: {
+                ...buildArtificerRunCorrelation({ taskId, attemptNumber: piTask.attemptCount, executionMode: 'preflight', reasonCode: 'executable', workspaceDir }),
+                channel: 'code_tool_hook',
+                gateStatus: 'executable',
+                recordPersisted,
+                scribeArtifactDigest: record.scribeArtifactDigest,
+            },
+        });
+        return { decision: 'executable', record, recordPersisted };
+    }
+    const reviewContext = {
+        reasonCode: assessment.reasonCode,
+        sourceRunId: ARTIFICER_INTENT_NHR_SOURCE_RUN_ID,
+        revisionEpoch: piTask.revisionCount ?? 0,
+        detail: boundedDetail(assessment.detail),
+        createdAt: new Date().toISOString(),
+    };
+    const reviewPersisted = await transitionToNeedsHumanReview(params, reviewContext, clearBackoff);
+    eventEmitter.emitTelemetry({
+        eventType: 'artificer_blocked_on_intent_basis',
+        traceId: taskId,
+        timestamp: new Date().toISOString(),
+        sessionId: owner,
+        agentId: 'artificer',
+        payload: {
+            ...buildArtificerRunCorrelation({
+                taskId,
+                attemptNumber: piTask.attemptCount,
+                executionMode: 'preflight',
+                reasonCode: assessment.reasonCode,
+                workspaceDir,
+            }),
+            detail: boundedDetail(assessment.detail),
+            nextAction: withNhrOutEdge(assessment.nextAction),
+            reviewPersisted,
+        },
+    });
+    return {
+        decision: 'blocked',
+        logicalResult: assessment.status,
+        reasonCode: assessment.reasonCode,
+        detail: assessment.detail,
+        nextAction: withNhrOutEdge(assessment.nextAction),
+        reviewPersisted,
+    };
+}
+function safeParse(contentJson) {
+    try {
+        return JSON.parse(contentJson);
+    }
+    catch {
+        return null;
+    }
+}
+/** Apply one transient source fault: bounded counter + backoff, or the persistent terminal (Q21/Q22). */
+async function applySourceFault(params, faultDetail) {
+    const { taskId, piTask, owner, workspaceDir, eventEmitter } = params;
+    const backoff = buildBackoffRecord((piTask.sourceFaultBackoff?.consecutiveFailures ?? 0) + 1, faultDetail);
+    eventEmitter.emitTelemetry({
+        eventType: 'artificer_intent_basis_checked',
+        traceId: taskId,
+        timestamp: new Date().toISOString(),
+        sessionId: owner,
+        agentId: 'artificer',
+        payload: {
+            ...buildArtificerRunCorrelation({
+                taskId,
+                attemptNumber: piTask.attemptCount,
+                executionMode: 'preflight',
+                reasonCode: backoff.consecutiveFailures >= SOURCE_FAULT_MAX_CONSECUTIVE_FAILURES
+                    ? SOURCE_FAULT_PERSISTENT_REASON_CODE
+                    : 'source_error',
+                workspaceDir,
+            }),
+            channel: 'code_tool_hook',
+            gateStatus: 'source_error',
+            consecutiveFailures: backoff.consecutiveFailures,
+            detail: boundedDetail(faultDetail),
+        },
+    });
+    const persistent = await advanceSourceFaultBackoff(params, faultDetail);
+    if (persistent) {
+        eventEmitter.emitTelemetry({
+            eventType: 'artificer_blocked_on_intent_basis',
+            traceId: taskId,
+            timestamp: new Date().toISOString(),
+            sessionId: owner,
+            agentId: 'artificer',
+            payload: {
+                ...buildArtificerRunCorrelation({
+                    taskId,
+                    attemptNumber: piTask.attemptCount,
+                    executionMode: 'preflight',
+                    reasonCode: SOURCE_FAULT_PERSISTENT_REASON_CODE,
+                    workspaceDir,
+                }),
+                detail: boundedDetail(faultDetail),
+                nextAction: 'Auto-retry ended after repeated transient source faults; inspect the artifact/trajectory store, then recover via pd runtime internalization retry --confirm.',
+                reviewPersisted: true,
+            },
+        });
+        return {
+            decision: 'source_fault_persistent',
+            reasonCode: SOURCE_FAULT_PERSISTENT_REASON_CODE,
+            detail: faultDetail,
+            nextAction: 'Auto-retry ended after repeated transient source faults; inspect the artifact/trajectory store, then recover via pd runtime internalization retry --confirm.',
+            reviewPersisted: true,
+        };
+    }
+    return {
+        decision: 'source_error',
+        reason: 'source_error',
+        detail: faultDetail,
+        nextAction: 'Transient source fault; the task stays pending and later consumer cycles retry at zero model cost with a bounded backoff.',
+    };
+}
+/**
+ * Shared bounded source-fault advancement (SPEC §9) — used by the intent
+ * preflight AND the consumer cycle's evidence_source_error branch, so BOTH
+ * pre-model source faults share one restart-durable counter/terminal. Pure
+ * state layer: telemetry belongs to the caller.
+ *
+ * Returns true when the fault count reached the cap and the task durably
+ * landed in the source_fault_persistent needs_human_review terminal (the
+ * final backoff record rides the SAME atomic write); false while the task
+ * stays wake-eligible with an incremented counter and 1-then-2-cycle backoff.
+ */
+export async function advanceSourceFaultBackoff(params, faultDetail) {
+    const { piTask } = params;
+    const consecutiveFailures = (piTask.sourceFaultBackoff?.consecutiveFailures ?? 0) + 1;
+    const backoff = buildBackoffRecord(consecutiveFailures, faultDetail);
+    if (consecutiveFailures >= SOURCE_FAULT_MAX_CONSECUTIVE_FAILURES) {
+        const reviewContext = {
+            reasonCode: SOURCE_FAULT_PERSISTENT_REASON_CODE,
+            sourceRunId: ARTIFICER_INTENT_NHR_SOURCE_RUN_ID,
+            revisionEpoch: piTask.revisionCount ?? 0,
+            detail: boundedDetail(`${SOURCE_FAULT_PERSISTENT_REASON_CODE}: ${SOURCE_FAULT_MAX_CONSECUTIVE_FAILURES} consecutive transient source faults; last: ${faultDetail}`),
+            createdAt: new Date().toISOString(),
+        };
+        // The final backoff record rides the SAME atomic NHR write (metadata
+        // overrides), so the terminal state is self-describing and the restart
+        // reads the full count (Q22). The CAS expected value stays the ORIGINAL
+        // diagnosticJson — the merge happens inside the transition.
+        return transitionToNeedsHumanReview(params, reviewContext, { sourceFaultBackoff: backoff });
+    }
+    const persisted = await patchTaskMetadata(params, { sourceFaultBackoff: backoff });
+    if (!persisted) {
+        // CAS lost to a concurrent writer — the counter stays at its previous
+        // value; the caller's telemetry still shows the fault (rc-9: observable,
+        // never fabricated). The next attempt re-reads current state (rc-7).
+    }
+    return false;
+}
+function buildBackoffRecord(consecutiveFailures, faultDetail) {
+    return {
+        version: 1,
+        consecutiveFailures,
+        skipCycles: consecutiveFailures,
+        lastReason: boundedDetail(faultDetail, 240),
+        updatedAt: new Date().toISOString(),
+    };
+}
+/**
+ * Consume one backoff skip cycle (consumer-cycle entry point): returns true
+ * when the task must be SKIPPED this cycle (a skip was pending and has been
+ * durably decremented). A failed decrement (CAS loss) reads as "do not skip"
+ * — the next preflight re-assesses with fresh state (rc-7).
+ */
+export async function consumeSourceFaultBackoffSkip(taskId, piTask, stateManager) {
+    const backoff = piTask.sourceFaultBackoff;
+    if (backoff === undefined || backoff.skipCycles <= 0)
+        return false;
+    const merged = mergePITaskMetadata(piTask, {
+        sourceFaultBackoff: { ...backoff, skipCycles: backoff.skipCycles - 1, updatedAt: new Date().toISOString() },
+    });
+    for (const expectedStatus of WAKE_ELIGIBLE_STATUSES) {
+        const updated = await stateManager.updateTaskIfDiagnosticJsonUnchanged(taskId, readDiagnosticJson(piTask), { diagnosticJson: createPITaskDiagnosticJson(merged) }, { expectedStatus });
+        if (updated !== null)
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=artificer-intent-preflight.js.map