@principles/core 1.293.1 → 1.293.3

package/dist/runtime-v2/internalization/artificer-intent-preflight.d.ts

@@ -0,0 +1,154 @@
+import { type ScribeExecutionConditionsV1 } from './intent-contract.js';
+import type { StoreEventEmitter } from '../store/event-emitter.js';
+import type { RuntimeStateManager } from '../store/runtime-state-manager.js';
+import type { PIArtifactStore } from './pi-artifact.js';
+import type { PITaskRecord } from './peer-runner-contracts.js';
+import { SOURCE_FAULT_PERSISTENT_REASON_CODE, type IntentBasisVerificationRecordV1 } from './pitask-metadata.js';
+/** SPEC 7.2 four-state resolution, fixed field meanings (see pitask-metadata.ts). */
+export type { TrustedFactResolutionKind } from './pitask-metadata.js';
+export interface TrustedFactResolution {
+    readonly resolution: 'approved' | 'not_approved' | 'not_required' | 'unknown';
+    /** Bounded human-readable context (rc-8); never carries credentials. */
+    readonly detail?: string;
+}
+/**
+ * Host-injected trusted-facts port (SPEC 8.3 seam — the B2/B3 provider
+ * surface). ABSENT in production today (Codex has no trusted approval
+ * source); absence + a declared required fact is an UNSUPPORTED stop, not a
+ * transient error. Implementations must be side-effect free and must never
+ * accept facts from the generating model.
+ */
+export interface ArtificerTrustedFactsPort {
+    resolveRequiredFact(request: {
+        factKind: string;
+        taskId: string;
+    }): TrustedFactResolution;
+}
+/** Stable stop-point reason codes (Owner-facing vocabulary, SPEC 5.3). */
+export type IntentBasisStopReasonCode = 'scribe_dependency_unresolved' | 'scribe_artifact_unparseable' | 'intent_contract_missing' | 'intent_contract_invalid' | 'execution_conditions_missing' | 'execution_conditions_invalid' | 'required_fact_conflict' | 'upstream_material_unavailable' | 'approval_dependency_undeclared' | 'textual_basis_unanchored' | 'trusted_fact_provider_absent' | 'trusted_fact_unknown' | typeof SOURCE_FAULT_PERSISTENT_REASON_CODE;
+export type ArtificerIntentPreflightVerdict = {
+    readonly decision: 'executable';
+    readonly record: IntentBasisVerificationRecordV1;
+    /** Whether the record durably landed in task metadata (false = CAS lost to a concurrent writer). */
+    readonly recordPersisted: boolean;
+} | {
+    readonly decision: 'blocked';
+    /** SPEC 5.3 logical result (stable coarse vocabulary). */
+    readonly logicalResult: 'intent_unverified' | 'intent_conflict' | 'unsupported' | 'needs_evidence';
+    /** Specific stable reason code (the actionable form of logicalResult). */
+    readonly reasonCode: IntentBasisStopReasonCode;
+    readonly detail: string;
+    readonly nextAction: string;
+    /** Whether the needs_human_review transition durably landed (CAS + read-back). */
+    readonly reviewPersisted: boolean;
+} | {
+    /** Transient source I/O: task stays wake-eligible; bounded technical retry (Q21). */
+    readonly decision: 'source_error';
+    readonly reason: 'source_error';
+    readonly detail: string;
+    readonly nextAction: string;
+} | {
+    /** 3rd consecutive transient fault: auto-retry ends (Q22), reviewable terminal. */
+    readonly decision: 'source_fault_persistent';
+    readonly reasonCode: typeof SOURCE_FAULT_PERSISTENT_REASON_CODE;
+    readonly detail: string;
+    readonly nextAction: string;
+    readonly reviewPersisted: boolean;
+};
+export interface ArtificerIntentPreflightParams {
+    readonly taskId: string;
+    /** Hydrated task record (channel already resolved by the caller). */
+    readonly piTask: PITaskRecord;
+    /** Lease-owner label for telemetry sessionId. */
+    readonly owner: string;
+    readonly workspaceDir?: string;
+    readonly stateManager: Pick<RuntimeStateManager, 'getTask' | 'updateTaskIfDiagnosticJsonUnchanged'> & {
+        piArtifactStore: PIArtifactStore;
+    };
+    readonly eventEmitter: StoreEventEmitter;
+    /** Optional host trusted-facts port; absent = host capability gap. */
+    readonly trustedFacts?: ArtificerTrustedFactsPort;
+    /**
+     * Test seam for store-fault injection: overrides the artifact listing used
+     * to resolve the scribe artifact. Production never passes it.
+     */
+    readonly artifactStore?: Pick<PIArtifactStore, 'listBySourceTaskId'>;
+}
+/**
+ * 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 declare const ARTIFICER_INTENT_NHR_SOURCE_RUN_ID = "intent-preflight";
+type TaskWriteParams = Pick<ArtificerIntentPreflightParams, 'taskId' | 'piTask' | 'stateManager'>;
+/**
+ * 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 declare function collectUpstreamNormalisedText(getTask: (taskId: string) => Promise<{
+    taskKind: string;
+    status: string;
+} | null>, listBySourceTaskId: (sourceTaskId: string) => Promise<readonly {
+    contentJson: string;
+}[]>, scribeDependencyTaskIds: readonly string[]): Promise<{
+    normalisedText: string;
+} | null>;
+interface IntentAssessmentStop {
+    readonly status: 'intent_unverified' | 'intent_conflict' | 'unsupported' | 'needs_evidence';
+    readonly reasonCode: IntentBasisStopReasonCode;
+    readonly detail: string;
+    readonly nextAction: string;
+}
+interface IntentAssessmentExecutable {
+    readonly status: 'executable';
+    readonly conditions: ScribeExecutionConditionsV1;
+    readonly requiredFacts: readonly {
+        factKind: string;
+        resolution: TrustedFactResolution['resolution'];
+    }[];
+}
+type IntentAssessment = IntentAssessmentExecutable | IntentAssessmentStop;
+/**
+ * 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 declare function assessIntentBasis(input: {
+    scribeArtifact: {
+        artifactId: string;
+        contentJson: string;
+    } | null;
+    /** Upstream (philosopher) material pool. null = unresolvable → STOP (R3: the verdict may never rest on the scribe artifact alone). */
+    upstreamMaterial: {
+        normalisedText: string;
+    } | null;
+    trustedFacts?: ArtificerTrustedFactsPort;
+    taskId: string;
+}): IntentAssessment;
+/**
+ * Run the intent-basis preflight for one code_tool_hook Artificer task.
+ * The caller owns channel resolution; this module never re-guesses channels.
+ */
+export declare function preflightArtificerIntentBasis(params: ArtificerIntentPreflightParams): Promise<ArtificerIntentPreflightVerdict>;
+/**
+ * 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 declare function advanceSourceFaultBackoff(params: TaskWriteParams, faultDetail: string): Promise<boolean>;
+/**
+ * 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 declare function consumeSourceFaultBackoffSkip(taskId: string, piTask: PITaskRecord, stateManager: Pick<RuntimeStateManager, 'getTask' | 'updateTaskIfDiagnosticJsonUnchanged'>): Promise<boolean>;
+//# sourceMappingURL=artificer-intent-preflight.d.ts.map

package/dist/runtime-v2/internalization/artificer-intent-preflight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artificer-intent-preflight.d.ts","sourceRoot":"","sources":["../../../src/runtime-v2/internalization/artificer-intent-preflight.ts"],"names":[],"mappings":"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"}