clinkx 0.2.3 → 1.0.0

package/clinkx-workflows/dist/engine.d.ts

@@ -63,12 +63,28 @@
  * workflow engine treats as a transient failure eligible for retry.
  */
 import type { NormalizedWorkflowDefinition } from "./definition-normalizer.js";
+import type { PlanReviewCallBinding } from "./plan-review/run-state.js";
+import { type CouncilPlanReviewError } from "./plan-review/publication.js";
 import { type ChildFailureMetadata } from "./errors.js";
 import { type FidelityReport } from "./fidelity.js";
 import type { CallState, FailureClass, RunStatus } from "./state-schema.js";
 import type { ClinkBackend } from "./backend.js";
 import type { ValidatorRegistry } from "./validators/index.js";
 import { type ArtifactRecord } from "./artifacts.js";
+import type { PlanReviewContextPolicy, PlanReviewContextProvenance } from "./plan-review/run-state.js";
+import type { ContextBuilderMetricsShape, ContextBuilderRunner, LightCallerProvenance, PreflightContextResult, WorkflowContext } from "./context-preflight.js";
+import { type WorkflowContextPolicy, type WorkflowContextRequestedMode, type WorkflowContextEffectiveMode } from "./context-mode-resolver.js";
+/**
+ * Maps a runner's {@link PreflightContextResult} to the persisted {@link WorkflowContext}.
+ * Single source of truth for this mapping: the transient `receipt` field is dropped, and
+ * optional `delegate` metadata is spread only when present.
+ */
+export declare function mapPreflightResultToWorkflowContext(result: PreflightContextResult, contextMode?: WorkflowContextEffectiveMode | undefined, lightCaller?: LightCallerProvenance | undefined): WorkflowContext;
+export type PreflightPartialClassification = {
+    readonly severity: "benign" | "degraded";
+    readonly partial_reason: "omissions_only" | "cap_or_truncation";
+};
+export declare function classifyPreflightPartial(metrics: ContextBuilderMetricsShape): PreflightPartialClassification;
 export interface ExecutedCall {
     readonly stageId: string;
     readonly callId: string;
@@ -96,7 +112,9 @@ export interface EngineResumeState {
         readonly stageId: string;
         readonly callId: string;
         readonly error: string;
+        readonly terminal: boolean;
     }> | undefined;
+    readonly nextRetryCounts?: ReadonlyMap<string, number> | undefined;
 }
 type HookResult = Promise<void> | void;
 export interface EngineRunStateChange {
@@ -107,6 +125,7 @@ export interface EngineRunStateChange {
     readonly completedAt?: string | undefined;
     readonly error?: string | undefined;
     readonly failureClass?: FailureClass | undefined;
+    readonly planReviewError?: CouncilPlanReviewError | undefined;
 }
 export interface EngineCallPreparedEvent {
     readonly runId: string;
@@ -167,12 +186,20 @@ export interface EngineHooks {
     readonly onRetryScheduled?: ((event: EngineRetryEvent) => HookResult) | undefined;
     readonly onProgress?: ((event: EngineProgressEvent) => HookResult) | undefined;
 }
+export type EngineTerminalResultPolicy = {
+    readonly kind: "final_call";
+} | {
+    readonly kind: "plan_review_artifacts";
+    readonly project: () => Promise<string>;
+};
 export interface WorkflowEngineOptions {
     readonly definition: NormalizedWorkflowDefinition;
     readonly session: ClinkBackend;
     readonly variables: Readonly<Record<string, unknown>>;
     readonly validatorRegistry: ValidatorRegistry;
     readonly runId: string;
+    /** Portable generation used only for session-log journal ownership. */
+    readonly sessionLogGeneration?: string | undefined;
     readonly runDir: string;
     readonly signal?: AbortSignal | undefined;
     readonly maxParallel?: number | undefined;
@@ -182,13 +209,48 @@ export interface WorkflowEngineOptions {
     readonly allowedRoots?: readonly string[] | undefined;
     readonly hooks?: EngineHooks | undefined;
     readonly resume?: EngineResumeState | undefined;
+    readonly contextBuilderRunner?: ContextBuilderRunner | undefined;
+    readonly contextDefault?: WorkflowContextRequestedMode | undefined;
+    readonly defaultCurator?: string | undefined;
+    readonly commitPreflightContext?: ((input: {
+        readonly variables: Readonly<Record<string, unknown>>;
+        readonly workflow_context: WorkflowContext;
+    }) => Promise<void>) | undefined;
+    /** Persisted workflow_context is the sole resume proof that preflight committed. */
+    readonly restoredWorkflowContext?: WorkflowContext | undefined;
+    /** Fail closed when resumed context is absent and an enabled mode has no runner. */
+    readonly requireContextPreflight?: boolean | undefined;
+    /** Admission-time policy replayed unchanged across execution and resume. */
+    readonly initialContextPolicy?: WorkflowContextPolicy | undefined;
+    /**
+     * Non-overridable plan-review context policy (A-7). Present only for
+     * `plan-review-receipts` runs. When set, the enforced exclusions are folded
+     * into the curator's input BEFORE dispatch and the finalized selection is
+     * post-filtered — the caller cannot re-admit the plan via globs or focus.
+     */
+    readonly planReviewContextPolicy?: PlanReviewContextPolicy | undefined;
+    /** Verified call bindings persisted by plan-review admission and resume. */
+    readonly planReviewCallBindings?: readonly PlanReviewCallBinding[] | undefined;
+    /**
+     * Canonical text of the verified plan snapshot (A-6/D9). Set on resume, where
+     * a persisted prepared retry replays its prompt verbatim and `buildCallInput`
+     * never re-runs the expander — this is what that prompt is checked against.
+     * Omitting it while a bound call has a persisted prepared input fails closed.
+     */
+    readonly planReviewSnapshotText?: string | undefined;
+    /** Records that the policy was enforced, for resume replay (A-7). */
+    readonly commitPlanReviewContextProvenance?: ((provenance: PlanReviewContextProvenance) => Promise<void>) | undefined;
+    /** Narrow opt-in terminal projection. All existing workflows use final_call. */
+    readonly terminalResultPolicy?: EngineTerminalResultPolicy | undefined;
 }
 export declare class WorkflowEngine {
     private readonly definition;
     private readonly session;
     private readonly variables;
+    private effectiveVariables;
     private readonly validatorRegistry;
     private readonly runId;
+    private readonly sessionLogGeneration;
     private readonly runDir;
     private readonly signal;
     private readonly queueDepth;
@@ -199,21 +261,100 @@ export declare class WorkflowEngine {
     private readonly resumeCompletedCalls;
     private readonly resumePreparedInputs;
     private readonly resumeFailedCalls;
+    private readonly resumeNextRetryCounts;
     private readonly contextProducingCalls;
+    private readonly planReviewDeliveredAliases;
     private readonly artifactStore;
+    private readonly contextBuilderRunner;
+    private readonly contextDefault;
+    private readonly defaultCurator;
+    private readonly commitPreflightContext;
+    private readonly restoredWorkflowContext;
+    private readonly requireContextPreflight;
+    private readonly initialContextPolicy;
+    private readonly planReviewContextPolicy;
+    private readonly planReviewCallBindings;
+    private readonly commitPlanReviewContextProvenance;
+    private readonly terminalResultPolicy;
     constructor(options: WorkflowEngineOptions);
     execute(): Promise<WorkflowExecutionResult>;
+    /**
+     * Complete the workflow context gate without dispatching a provider call.
+     * Resume uses this before backend construction when workflow_context is absent.
+     */
+    prepareContextPreflight(signal: AbortSignal): Promise<void>;
+    private resolveTerminalResult;
     private executeParallelStage;
     private executeSequentialStage;
     private executeSingleCall;
+    /**
+     * F4: bounded corrective suffix for the next already-scheduled retry after
+     * a JSON/schema-shaped failure. Returns undefined (no suffix) unless ALL of:
+     * - the call declares a JSON contract (mirrors the expect_json derivation
+     *   in buildCallInput);
+     * - the run is NOT typed plan review (identity: the plan-review-receipts
+     *   workflow name on the
+     *   normalized definition, plus the plan-review runtime signals as
+     *   defense-in-depth — plan-review dispatch bytes are pinned);
+     * - the failure is JSON/schema-shaped (SchemaValidationError,
+     *   OutputSizeError as the second correctable class, or a child
+     *   invalid_json_output rejection);
+     * - appending stays inside the same prompt-budget ceiling the dispatch-time
+     *   gate enforces (best-effort re-estimate; skip with a warn on overflow or
+     *   estimator failure — never a new failure mode).
+     * The suffix is always derived from the ORIGINAL prompt, so it can never
+     * stack across attempts, and it is never persisted to state.
+     */
+    private buildCorrectiveRetrySuffix;
     private invokeCall;
     private maybeWriteArtifact;
     private resolveDynamicPaths;
+    private resolveDynamicPathVariable;
+    private setEffectiveVariable;
+    /**
+     * Derive the engine-computed `context_available` template variable after
+     * context-builder preflight has had a chance to append to
+     * `context_bundle_files`. True when the union of the effective
+     * `context_files` and `context_bundle_files` path lists is non-empty.
+     * Stored as the STRING "true"/"false" since the template engine stringifies
+     * variable values. Engine-derived; setting it is expected.
+     */
+    private deriveContextAvailable;
+    /**
+     * Build the citation allowlist for a post-processor run: the union of files
+     * parsed from the `diff_context` variable, the resolved `context_files`, and
+     * the resolved `context_bundle_files`. Both full paths and basenames are
+     * stored so citation matching is lenient.
+     */
+    private buildPostProcessorAllowlist;
+    /**
+     * Resolve a path-list variable to absolute paths without enforcing allowed
+     * roots (the post-processor allowlist is advisory, not a security boundary).
+     * Both the raw and resolved forms are returned so basename matching works
+     * regardless of how a citation spells the file.
+     */
+    private resolvePathListLenient;
+    private runContextBuilderPreflight;
+    /**
+     * Strip every force-excluded plan path from the effective context path
+     * variables (A-7). Idempotent and safe to call on any path — no policy means
+     * no-op, so non-plan-review runs are byte-unchanged.
+     *
+     * Returns the paths that were removed, for provenance.
+     */
+    private enforcePlanReviewContextExclusions;
+    private buildWorkflowContext;
+    private resolveContextPolicy;
+    private readOptionalStringVariable;
+    private readOptionalNumberVariable;
+    private readOptionalBooleanVariable;
+    private readStringArrayVariable;
     private createDeadlineController;
     private throwIfAborted;
     private validateFinalStage;
     private validateAdvertisedCliNames;
     private defaultAllowedRoots;
+    private recordPlanReviewDeliveredAliases;
     private buildCallInput;
     private materializeUnexpectedFailure;
     private emitRunStateChange;