intentdna 1.9.0 → 1.9.1

package/dist/runtime/executable-run-plan.d.ts

@@ -0,0 +1,328 @@
+import { type CanonicalJsonValue } from "./canonical-json.js";
+export declare const EXECUTABLE_RUN_PLAN_SCHEMA_VERSION = "intentdna.executable_run_plan.v1";
+export declare const STORED_EXECUTABLE_RUN_PLAN_SCHEMA_VERSION = "intentdna.stored_executable_run_plan.v1";
+export declare const EXECUTABLE_RETRYABLE_OUTCOME_VALUES: readonly ["non_zero_exit", "malformed_result", "timeout", "cancelled", "signal", "launch_error"];
+export type ExecutableRetryableOutcome = typeof EXECUTABLE_RETRYABLE_OUTCOME_VALUES[number];
+export declare const EXECUTABLE_ARTIFACT_KIND_VALUES: readonly ["file", "directory", "test_result", "git_commit", "summary", "state"];
+export type ExecutableArtifactKind = typeof EXECUTABLE_ARTIFACT_KIND_VALUES[number];
+export type Sha256Digest = `sha256:${string}`;
+export type JsonObject = {
+    readonly [key: string]: CanonicalJsonValue;
+};
+export interface RunInputDefinition {
+    readonly name: string;
+    readonly type: "string" | "number" | "boolean" | "json" | "reference" | "trusted_verifier_command";
+    readonly required: boolean;
+    readonly sensitive: boolean;
+    readonly description: string;
+    readonly default_value?: CanonicalJsonValue;
+}
+export interface RunInputContract {
+    readonly inputs: readonly RunInputDefinition[];
+    readonly allow_unknown_inputs: false;
+}
+export interface ExecutableNodeBase {
+    readonly node_id: string;
+    readonly depends_on: readonly string[];
+}
+export interface WorkerHandoffInputContract {
+    readonly name: string;
+    readonly source: "handoff" | "external";
+    readonly mode: "reference" | "quote" | "structured";
+    readonly artifact_kind: ExecutableArtifactKind;
+    readonly required: boolean;
+    readonly description: string;
+    readonly relative_path_template: string | null;
+    readonly schema_ref: string | null;
+}
+export interface WorkerOutputContract {
+    readonly name: string;
+    readonly kind: "reference" | "text" | "structured";
+    readonly artifact_kind: ExecutableArtifactKind;
+    readonly required: boolean;
+    readonly description: string;
+    readonly relative_path_template: string | null;
+    readonly schema_ref: string | null;
+}
+export type WorkerResponseContract = {
+    readonly kind: "none";
+} | {
+    readonly kind: "named";
+    readonly schema_ref: string;
+} | {
+    readonly kind: "document";
+    readonly relative_path_template: string | null;
+    readonly required_sections: readonly string[];
+    readonly format: "markdown" | "pdf" | "docx" | "xlsx" | "json" | "csv" | null;
+    readonly converter_command: string | null;
+};
+export interface WorkerNode extends ExecutableNodeBase {
+    readonly kind: "worker";
+    readonly role: string;
+    readonly packet_template: {
+        readonly standalone_prompt: string;
+        readonly constraints: readonly string[];
+        readonly runtime_input_names: readonly string[];
+        readonly handoff_inputs: readonly WorkerHandoffInputContract[];
+        readonly output_contract: readonly WorkerOutputContract[];
+        readonly response_contract: WorkerResponseContract;
+    };
+    readonly workspace: {
+        readonly isolation: "none" | "worktree";
+        readonly relative_working_directory: string;
+        readonly read_only: boolean;
+        readonly readable_path_templates: readonly string[];
+        readonly writable_path_templates: readonly string[];
+        readonly scope_relaxation: {
+            readonly from_iteration: number;
+            readonly effect: "disable_path_scope";
+        } | null;
+    };
+    readonly tool_policy: {
+        readonly allow: readonly string[] | null;
+        readonly deny: readonly string[];
+    };
+    readonly attempt_policy: {
+        readonly timeout_ms: number | null;
+        readonly cancellation_grace_ms: number;
+        readonly max_attempts: number;
+        readonly backoff: "none" | "linear" | "exponential";
+        readonly initial_delay_ms: number;
+        readonly max_delay_ms: number | null;
+        readonly retryable_outcomes: readonly ExecutableRetryableOutcome[];
+        readonly retry_segment_id: string | null;
+    };
+}
+export interface SystemInputPort {
+    readonly name: string;
+    readonly source: "run_input" | "handoff";
+}
+export interface SystemResultOutputMapping {
+    readonly source_output_name: string;
+    readonly output_name: string;
+}
+export interface SystemSealCandidate {
+    readonly required_node_ids: readonly string[];
+    readonly outputs: readonly ({
+        readonly source_node_id: string;
+    } & SystemResultOutputMapping)[];
+}
+export type SystemOperation = {
+    readonly kind: "import_result";
+    readonly source_plan_input: string;
+    readonly source_result_input: string;
+    readonly output_name: string;
+} | {
+    readonly kind: "adopt_artifact";
+    readonly source_reference_input: string;
+    readonly expected_digest_input: string;
+    readonly output_name: string;
+} | {
+    readonly kind: "resolve_diagnosis_source";
+    readonly mode_input: string;
+    readonly output_name: string;
+} | {
+    readonly kind: "adopt_artifact_bundle";
+    readonly artifacts: readonly {
+        readonly source_reference_input: string;
+        readonly expected_digest_input: string;
+        readonly output_name: string;
+        readonly artifact_kind: "file" | "directory";
+    }[];
+} | {
+    readonly kind: "import_result_bundle";
+    readonly source_plan_input: string;
+    readonly source_result_input: string;
+    readonly required_outputs: readonly SystemResultOutputMapping[];
+} | {
+    readonly kind: "import_review";
+    readonly source_plan_input: string;
+    readonly source_diagnosis_result_input: string;
+    readonly source_review_result_input: string;
+    readonly policy_id: string;
+    readonly required_outputs: readonly SystemResultOutputMapping[];
+} | {
+    readonly kind: "seal_result_bundle";
+    readonly origin_output_name?: string;
+    readonly candidates: readonly SystemSealCandidate[];
+} | {
+    readonly kind: "materialize_handoff";
+    readonly handoff_id: string;
+};
+export interface SystemNode extends ExecutableNodeBase {
+    readonly kind: "system";
+    readonly input_ports: readonly SystemInputPort[];
+    readonly output_contract?: readonly WorkerOutputContract[];
+    readonly operation: SystemOperation;
+}
+export interface GateNode extends ExecutableNodeBase {
+    readonly kind: "gate";
+    readonly verifier_ids: readonly string[];
+    readonly pass_route_ids: readonly string[];
+    readonly fail_route_id: string;
+}
+export interface DecisionNode extends ExecutableNodeBase {
+    readonly kind: "decision";
+    readonly source: {
+        readonly node_id: string;
+        readonly output_name: string;
+        readonly json_pointer: string;
+    };
+    readonly allowed_values: readonly string[];
+}
+export interface InteractionNode extends ExecutableNodeBase {
+    readonly kind: "interaction";
+    readonly interaction_id: string;
+    readonly prompt: string;
+    readonly response_schema_ref: string;
+    readonly requires_attested_human: true;
+}
+export interface TerminalNode extends ExecutableNodeBase {
+    readonly kind: "terminal";
+    readonly terminal_id: string;
+}
+export type ExecutableNode = WorkerNode | SystemNode | GateNode | DecisionNode | InteractionNode | TerminalNode;
+export type RouteCondition = {
+    readonly kind: "always";
+} | {
+    readonly kind: "gate";
+    readonly gate_node_id: string;
+    readonly outcome: "pass" | "fail";
+} | {
+    readonly kind: "decision";
+    readonly decision_node_id: string;
+    readonly value: string;
+} | {
+    readonly kind: "interaction";
+    readonly interaction_node_id: string;
+    readonly outcome: "submitted" | "cancelled";
+};
+export interface TypedRoute {
+    readonly route_id: string;
+    readonly from_node_id: string;
+    readonly to_node_id: string;
+    readonly condition: RouteCondition;
+}
+export interface RetrySegment {
+    readonly retry_segment_id: string;
+    readonly node_ids: readonly string[];
+    readonly retry_from_node_id: string;
+    readonly max_rounds: number;
+    readonly backoff: "none" | "linear" | "exponential";
+    readonly initial_delay_ms: number;
+    readonly max_delay_ms: number | null;
+    readonly retryable_outcomes: readonly ExecutableRetryableOutcome[];
+    /** A typed decision route that schedules the next segment round until exhausted. */
+    readonly continue_route_id?: string;
+}
+export interface TerminalDefinition {
+    readonly terminal_id: string;
+    readonly status: "succeeded" | "failed" | "cancelled" | "unsupported";
+    readonly reason_code: string;
+}
+interface VerifierDefinitionBase {
+    readonly verifier_id: string;
+    readonly subject_node_id: string;
+}
+export type VerifierDefinition = VerifierDefinitionBase & {
+    readonly kind: "artifact_exists" | "artifact_non_empty";
+    readonly relative_path_template: string;
+} | VerifierDefinitionBase & {
+    readonly kind: "artifact_contains";
+    readonly relative_path_template: string;
+    readonly pattern: string;
+} | VerifierDefinitionBase & {
+    readonly kind: "evaluator_result";
+    readonly relative_path_template: string;
+    readonly require_score: boolean;
+} | VerifierDefinitionBase & {
+    readonly kind: "structured_output";
+    readonly node_id: string;
+    readonly output_name: string;
+    readonly schema_ref: string;
+} | VerifierDefinitionBase & {
+    readonly kind: "command";
+    readonly command: string;
+    readonly relative_working_directory: string;
+    readonly observation_policy?: "historical_execution" | "current_provenance";
+} | VerifierDefinitionBase & {
+    readonly kind: "checkpoint";
+    readonly assertion: string;
+    readonly command: string | null;
+    readonly message: string;
+    readonly action: "block" | "warn";
+    readonly observation_policy?: "historical_execution" | "current_provenance";
+};
+export interface HandoffDefinition {
+    readonly handoff_id: string;
+    readonly from_node_id: string;
+    readonly output_name: string;
+    readonly to_node_id: string;
+    readonly input_name: string;
+    readonly mode: "reference" | "quote" | "structured";
+    readonly artifact_kind: ExecutableArtifactKind;
+    readonly required: boolean;
+    readonly schema_ref: string | null;
+}
+export interface WorkspacePolicy {
+    readonly default_isolation: "none" | "worktree";
+    readonly relative_workspace_root: string;
+    readonly allow_network: boolean;
+    readonly readable_path_templates: readonly string[];
+    readonly writable_path_templates: readonly string[];
+}
+export interface DriverCapabilities {
+    readonly worktree_isolation: boolean;
+    readonly parallelism: boolean;
+    readonly cancellation: boolean;
+    readonly hook_identity: boolean;
+    readonly caller_attestation: boolean;
+    readonly human_interaction: boolean;
+    readonly direct_structured_submission: boolean;
+    readonly network_policy_enforcement: boolean;
+}
+export interface PlanSourceProvenance {
+    readonly compiler: {
+        readonly name: string;
+        readonly version: string;
+    };
+    readonly sources: readonly {
+        readonly source_id: string;
+        readonly relative_ref: string;
+        readonly content_digest: Sha256Digest;
+    }[];
+}
+export interface ExecutableRunPlanPayload {
+    readonly schema_version: typeof EXECUTABLE_RUN_PLAN_SCHEMA_VERSION;
+    readonly target: {
+        readonly kind: "workflow" | "controller";
+        readonly key: string;
+    };
+    readonly input_contract: RunInputContract;
+    readonly nodes: readonly ExecutableNode[];
+    readonly routes: readonly TypedRoute[];
+    readonly retry_segments: readonly RetrySegment[];
+    readonly terminals: readonly TerminalDefinition[];
+    readonly verifier_plan: readonly VerifierDefinition[];
+    readonly handoff_plan: readonly HandoffDefinition[];
+    readonly workspace_policy: WorkspacePolicy;
+    readonly required_capabilities: DriverCapabilities;
+    readonly source_provenance: PlanSourceProvenance;
+}
+export interface StoredExecutableRunPlan {
+    readonly schema_version: typeof STORED_EXECUTABLE_RUN_PLAN_SCHEMA_VERSION;
+    readonly plan_id: Sha256Digest;
+    readonly plan_digest: Sha256Digest;
+    readonly plan: ExecutableRunPlanPayload;
+}
+export declare class ExecutableRunPlanError extends TypeError {
+    readonly path: string;
+    constructor(path: string, message: string);
+}
+export declare function deriveWorkerRuntimeInputNames(worker: WorkerNode, verifiers: readonly VerifierDefinition[], handoffs: readonly HandoffDefinition[], path?: string): readonly string[];
+export declare function assertExecutableRunPlanPayload(value: unknown): asserts value is ExecutableRunPlanPayload;
+export declare function parseExecutableRunPlanPayload(value: unknown): ExecutableRunPlanPayload;
+export declare function executableRunPlanDigest(plan: ExecutableRunPlanPayload): Sha256Digest;
+export declare function createStoredExecutableRunPlan(plan: ExecutableRunPlanPayload): StoredExecutableRunPlan;
+export declare function parseStoredExecutableRunPlan(value: unknown): StoredExecutableRunPlan;
+export {};