intentdna 1.9.0 → 1.9.3

package/dist/runtime/canonical-run-service.d.ts

@@ -0,0 +1,454 @@
+import { type ActivationId, type AttemptExecutor, type AttemptId, type CanonicalActivationRecord, type CanonicalAttemptClaim, type CanonicalAttemptOutcome, type CanonicalAttemptRecord, type CanonicalCommittedResult, type CanonicalEvidenceRef, type CanonicalResultDigest, type CanonicalResultOutput, type CanonicalVerifierEvidenceRef, type CanonicalVerifierExecutionReceipt, type CanonicalWorkspaceAllocation, type CanonicalWorkspacePlan, type ClaimToken, type HandoffBinding, type JsonValue, type RunId, type StepPacket, type WorkerSessionId } from "./run-contracts.js";
+import type { DriverCapabilities, ExecutableRunPlanPayload, Sha256Digest, StoredExecutableRunPlan } from "./executable-run-plan.js";
+import { type StoredRunBinding } from "./run-binding.js";
+import { DurablePlanStore } from "./plan-store.js";
+import { DurableRunStore, type CanonicalRunRecord, type CanonicalRunStoreSnapshot } from "./run-store.js";
+import { ImmutableCanonicalResultStore } from "./result-store.js";
+import { ArtifactStore, type ArtifactCaptureRef, type ArtifactKind } from "./artifact-store.js";
+import { type VerifierCommandExecutionResult } from "./verifier.js";
+import { type AttemptExecutionAuthorityPort } from "./execution-authority.js";
+import { type StructuredOutputSchemaRegistry } from "./structured-output-validator.js";
+export type CanonicalRunServiceErrorCode = "invalid_request" | "run_not_found" | "run_terminal" | "no_attempt_available" | "lease_not_found" | "lease_expired" | "stale_lease" | "attempt_state_conflict" | "submission_conflict" | "unsupported" | "verification_failed" | "observation_limit_exceeded" | "source_drift" | "workspace_conflict" | "concurrent_update";
+export declare class CanonicalRunServiceError extends Error {
+    readonly code: CanonicalRunServiceErrorCode;
+    constructor(code: CanonicalRunServiceErrorCode, message: string, options?: ErrorOptions);
+}
+export interface CanonicalRunClock {
+    now(): Date;
+}
+export type CanonicalIdentityKind = "run" | "activation" | "attempt" | "claim" | "worker_session" | "result" | "event";
+export interface CanonicalIdentityFactory {
+    create(kind: CanonicalIdentityKind, seed: string): string;
+}
+export type SubmittedAttemptOutput = {
+    readonly name: string;
+    readonly kind: "reference";
+    readonly artifact_kind: ArtifactKind;
+    readonly source_path: string;
+} | {
+    readonly name: string;
+    readonly kind: "text";
+    readonly text: string;
+} | {
+    readonly name: string;
+    readonly kind: "structured";
+    readonly value: JsonValue;
+    readonly schema_ref: string | null;
+};
+export interface AttemptExecutionSubmission {
+    readonly executor: AttemptExecutor;
+    readonly started_at: string;
+    readonly completed_at: string;
+    readonly outcome: CanonicalAttemptOutcome;
+    readonly outputs: readonly SubmittedAttemptOutput[];
+    readonly workspace: {
+        readonly root: string;
+        readonly workspace_id: string;
+    };
+    readonly stdout_reference?: CanonicalEvidenceRef | null;
+    readonly stderr_reference?: CanonicalEvidenceRef | null;
+}
+export interface CaptureAttemptOutputsRequest {
+    readonly run_id: RunId;
+    readonly activation_id: ActivationId;
+    readonly attempt_id: AttemptId;
+    readonly execution: AttemptExecutionSubmission;
+}
+export interface CapturedAttemptOutputs {
+    readonly outputs: readonly CanonicalResultOutput[];
+    readonly captures: readonly ArtifactCaptureRef[];
+    /** Re-read mutable sources and reject drift before ledger authority is granted. */
+    revalidate(): Promise<void>;
+}
+export interface CanonicalOutputCapturePort {
+    capture(request: CaptureAttemptOutputsRequest): Promise<CapturedAttemptOutputs>;
+}
+export interface CanonicalVerifierResult {
+    readonly verifier_id: string;
+    readonly passed: boolean;
+    readonly reason_code: string;
+    readonly evidence_refs?: readonly CanonicalVerifierEvidenceRef[];
+    readonly domain_value?: JsonValue;
+}
+export interface VerifyAttemptRequest {
+    readonly plan: StoredExecutableRunPlan;
+    readonly run: CanonicalRunRecord;
+    readonly activation: CanonicalActivationRecord;
+    readonly attempt: CanonicalAttemptRecord;
+    readonly execution: AttemptExecutionSubmission;
+    readonly workspace_allocation: CanonicalWorkspaceAllocation;
+    readonly captured_outputs: readonly CanonicalResultOutput[];
+    readonly handoff_bindings: readonly HandoffBinding[];
+}
+export interface CanonicalVerifierPort {
+    verify(request: VerifyAttemptRequest): Promise<readonly CanonicalVerifierResult[]>;
+}
+export interface CanonicalVerifierExecutionRequest {
+    readonly request_digest: CanonicalResultDigest;
+    readonly descriptor: {
+        readonly schema_version: "intentdna.verifier_execution_request.v1";
+        readonly plan_id: CanonicalResultDigest;
+        readonly verifier_id: string;
+        readonly verifier_definition_digest: CanonicalResultDigest;
+        readonly raw_command_digest: CanonicalResultDigest;
+        readonly cwd: CanonicalVerifierExecutionReceipt["cwd_identity"];
+        readonly supplied_environment: {
+            readonly binding_digest: CanonicalResultDigest;
+            readonly variable_names: readonly string[];
+            readonly inherit_parent: false;
+            readonly startup_files: false;
+        };
+        readonly shell: CanonicalVerifierExecutionReceipt["shell_policy"];
+        readonly timeout_ms: number;
+        readonly requested_at: string;
+        readonly network_mode: "deny_all" | "allow";
+        readonly expected_authority_descriptor_digest: CanonicalResultDigest;
+    };
+    readonly plan_id: CanonicalResultDigest;
+    readonly verifier_id: string;
+    readonly verifier_definition_digest: CanonicalResultDigest;
+    readonly resolved_command: string;
+    readonly resolved_command_digest: CanonicalResultDigest;
+    readonly cwd: string;
+    readonly cwd_identity: CanonicalVerifierExecutionReceipt["cwd_identity"];
+    readonly environment: Readonly<Record<string, string>>;
+    readonly environment_binding_digest: CanonicalResultDigest;
+    readonly timeout_ms: number;
+    readonly requested_at: string;
+    readonly network_policy: "deny_all" | "allow";
+    readonly inherit_parent_environment: false;
+    readonly load_startup_files: false;
+}
+export interface CanonicalVerifierExecutionAuthorityReceipt {
+    readonly authority_instance_id: string;
+    readonly request_digest: CanonicalResultDigest;
+    readonly authority_descriptor_digest: CanonicalResultDigest;
+    readonly launch_descriptor_digest: CanonicalResultDigest;
+    readonly process_tree_drained: true;
+    readonly network_enforced: boolean;
+    readonly enforcement_kind: "configured_adapter" | "not_required";
+    readonly enforcement_digest: CanonicalResultDigest | null;
+    readonly enforcement_descriptor: CanonicalVerifierExecutionReceipt["network_policy"]["enforcement_descriptor"];
+}
+export interface CanonicalVerifierExecutionAuthorityDescriptor {
+    readonly schema_version: "intentdna.verifier_execution_authority.v1";
+    readonly authority_instance_id: string;
+    readonly adapter_kind: string;
+    readonly adapter_version: string;
+    readonly configuration_digest: CanonicalResultDigest;
+    readonly process_tree_containment: boolean;
+    readonly network_policies: readonly ("deny_all" | "allow")[];
+}
+export interface CanonicalVerifierExecutionPort {
+    readonly authority_descriptor: CanonicalVerifierExecutionAuthorityDescriptor;
+    execute(request: CanonicalVerifierExecutionRequest): Promise<{
+        readonly execution: VerifierCommandExecutionResult;
+        readonly authority: CanonicalVerifierExecutionAuthorityReceipt;
+    }>;
+}
+export declare function canonicalVerifierEnvironment(supplied: Readonly<Record<string, string>>, platform?: NodeJS.Platform, hostEnvironment?: NodeJS.ProcessEnv): Readonly<Record<string, string>>;
+export interface AllocateAttemptWorkspaceRequest {
+    readonly plan: StoredExecutableRunPlan;
+    readonly run: CanonicalRunRecord;
+    readonly activation: CanonicalActivationRecord;
+    readonly attempt: CanonicalAttemptRecord;
+}
+export interface CommittedWorkspaceAuthorityRequest {
+    readonly allocation: CanonicalWorkspaceAllocation;
+    readonly purpose: "prepare_inputs" | "finalize_result" | "reconcile_published_result";
+    readonly require_clean_worktree: boolean;
+}
+export interface WorkspaceMutationAuthority {
+    readonly workspace_id: string;
+    readonly workspace_allocation_digest: CanonicalResultDigest;
+    readonly authority_instance_id: string;
+    readonly fencing_epoch: number;
+}
+export interface AttemptWorkspaceAuthorityPort {
+    plan(request: AllocateAttemptWorkspaceRequest): Promise<CanonicalWorkspacePlan>;
+    ensureWithExclusiveAuthority<T>(plan: CanonicalWorkspacePlan, operation: (allocation: CanonicalWorkspaceAllocation) => Promise<T>): Promise<T>;
+    withExclusiveMutationAuthority<T>(request: CommittedWorkspaceAuthorityRequest, operation: (authority: WorkspaceMutationAuthority) => Promise<T>): Promise<T>;
+}
+export interface CanonicalRunServiceHooks {
+    after_output_capture?(request: CaptureAttemptOutputsRequest): Promise<void> | void;
+    after_verification?(request: VerifyAttemptRequest): Promise<void> | void;
+    after_result_publish?(result: CanonicalCommittedResult): Promise<void> | void;
+}
+export interface CanonicalRunServiceOptions {
+    readonly plan_store: DurablePlanStore;
+    readonly run_store: DurableRunStore;
+    readonly artifact_store: ArtifactStore;
+    readonly result_store: ImmutableCanonicalResultStore;
+    readonly clock?: CanonicalRunClock;
+    readonly identities?: CanonicalIdentityFactory;
+    readonly output_capture?: CanonicalOutputCapturePort;
+    readonly verifier?: CanonicalVerifierPort;
+    readonly verifier_execution_port?: CanonicalVerifierExecutionPort;
+    readonly workspace_authority?: AttemptWorkspaceAuthorityPort;
+    readonly execution_authority?: AttemptExecutionAuthorityPort;
+    readonly structured_output_schema_registry?: StructuredOutputSchemaRegistry;
+    readonly handoff_root_directory?: string;
+    readonly hooks?: CanonicalRunServiceHooks;
+    readonly lease_duration_ms?: number;
+    readonly default_execution_timeout_ms?: number;
+    readonly service_instance_id?: string;
+}
+export interface StartRunRequest {
+    readonly plan_payload: ExecutableRunPlanPayload;
+    readonly run_binding: StoredRunBinding;
+    readonly metadata?: JsonValue;
+    readonly run_id?: RunId;
+}
+export interface RunView {
+    readonly run: CanonicalRunRecord;
+    readonly plan: StoredExecutableRunPlan;
+    readonly activations: readonly CanonicalActivationRecord[];
+    readonly attempts: readonly CanonicalAttemptRecord[];
+    readonly claims: readonly PublicAttemptClaim[];
+    readonly results: CanonicalRunStoreSnapshot["result_refs"];
+    readonly record_version: number;
+}
+export interface RunAuditView extends RunView {
+    readonly events: CanonicalRunStoreSnapshot["events"];
+    readonly ledger: {
+        readonly created_at: string;
+        readonly updated_at: string;
+        readonly record_version: number;
+    };
+}
+export interface StartRunResponse {
+    readonly run_id: RunId;
+    readonly plan_id: Sha256Digest;
+    readonly view: RunView;
+}
+export interface AcquireAttemptRequest {
+    readonly run_id: RunId;
+    readonly driver_id: string;
+    readonly recover_running?: boolean;
+}
+export interface AttemptLease {
+    readonly run_id: RunId;
+    readonly step_id: string;
+    readonly activation_id: ActivationId;
+    readonly attempt_id: AttemptId;
+    readonly attempt_number: number;
+    readonly claim_token: ClaimToken;
+    readonly claim_epoch: number;
+    readonly owner_id: string;
+    readonly claim_expires_at: string;
+    readonly execution_deadline_at: string;
+}
+export interface AttemptRecovery {
+    readonly worker_session_id: WorkerSessionId;
+    readonly execution_claim_epoch: number;
+}
+export type PublicAttemptClaim = Omit<CanonicalAttemptClaim, "claim_token">;
+export type AttemptLeaseView = Omit<AttemptLease, "claim_token">;
+export type AcquireAttemptResponse = {
+    readonly kind: "attempt";
+    readonly lease: AttemptLease;
+    readonly recovery: AttemptRecovery | null;
+} | {
+    readonly kind: "wait";
+    readonly reason_code: string;
+    readonly run: RunView;
+} | {
+    readonly kind: "terminal";
+    readonly run: RunView;
+};
+export interface AttachAttemptRequest {
+    readonly lease_token: ClaimToken;
+    readonly owner_id: string;
+    readonly worker_identity: AttemptExecutor | string;
+    readonly capabilities: Partial<DriverCapabilities>;
+}
+export interface AttemptView {
+    readonly lease: AttemptLeaseView;
+    readonly attempt: CanonicalAttemptRecord;
+    readonly activation: CanonicalActivationRecord;
+    readonly packet: StepPacket | null;
+}
+export interface HeartbeatRequest {
+    readonly lease_token: ClaimToken;
+    readonly owner_id: string;
+}
+export interface LeaseView extends AttemptLeaseView {
+    readonly heartbeat_at: string;
+}
+export interface SubmitAttemptRequest {
+    readonly lease_token: ClaimToken;
+    readonly owner_id: string;
+    readonly submission_key: string;
+    readonly execution: AttemptExecutionSubmission;
+    readonly evidence_refs?: readonly CanonicalEvidenceRef[];
+}
+export interface FailAttemptRequest {
+    readonly lease_token: ClaimToken;
+    readonly owner_id: string;
+    readonly submission_key: string;
+    readonly outcome: CanonicalAttemptOutcome;
+    readonly completed_at?: string;
+    readonly evidence_refs?: readonly CanonicalEvidenceRef[];
+}
+export interface SettleDriverFailureRequest {
+    readonly lease_token: ClaimToken;
+    readonly owner_id: string;
+    readonly failure_key: string;
+    readonly reason_code: string;
+    readonly message: string | null;
+}
+export interface SubmitResponse {
+    readonly result: CanonicalCommittedResult;
+    readonly replayed: boolean;
+    readonly run: RunView;
+}
+export interface CancelRunRequest {
+    readonly run_id: RunId;
+    readonly reason?: string | null;
+}
+export declare class LocalVerifierExecutionPort implements CanonicalVerifierExecutionPort {
+    private readonly clock;
+    readonly authority_descriptor: {
+        schema_version: "intentdna.verifier_execution_authority.v1";
+        authority_instance_id: string;
+        adapter_kind: string;
+        adapter_version: string;
+        configuration_digest: `sha256:${string}`;
+        process_tree_containment: boolean;
+        network_policies: readonly ["allow"];
+    };
+    constructor(clock: CanonicalRunClock, authorityInstanceId?: string);
+    execute(request: CanonicalVerifierExecutionRequest): Promise<{
+        execution: VerifierCommandExecutionResult;
+        authority: {
+            authority_instance_id: string;
+            request_digest: `sha256:${string}`;
+            authority_descriptor_digest: `sha256:${string}`;
+            launch_descriptor_digest: `sha256:${string}`;
+            process_tree_drained: true;
+            network_enforced: boolean;
+            enforcement_kind: "not_required";
+            enforcement_digest: null;
+            enforcement_descriptor: null;
+        };
+    }>;
+}
+export declare class CanonicalRunService {
+    private readonly planStore;
+    private readonly runStore;
+    private readonly resultStore;
+    private readonly artifactStore;
+    private readonly artifactMaterializer;
+    private readonly clock;
+    private readonly identities;
+    private readonly outputCapture;
+    private readonly verifier;
+    private readonly additionalVerifier;
+    private readonly verifierExecutionPort;
+    private readonly verifierAuthorityDescriptor;
+    private readonly verifierAuthorityDescriptorDigest;
+    private readonly workspaceAuthority;
+    private readonly executionAuthority;
+    private readonly handoffRootDirectory;
+    private readonly hooks;
+    private readonly leaseDurationMs;
+    private readonly defaultExecutionTimeoutMs;
+    private readonly serviceInstanceId;
+    private readonly structuredOutputSchemaRegistry;
+    constructor(options: CanonicalRunServiceOptions);
+    start(request: StartRunRequest): Promise<StartRunResponse>;
+    acquireAttempt(request: AcquireAttemptRequest): Promise<AcquireAttemptResponse>;
+    attachAttempt(request: AttachAttemptRequest): Promise<AttemptView>;
+    private attachWorkerAttempt;
+    heartbeat(request: HeartbeatRequest): Promise<LeaseView>;
+    submitAttempt(request: SubmitAttemptRequest): Promise<SubmitResponse>;
+    failAttempt(request: FailAttemptRequest): Promise<SubmitResponse>;
+    settleDriverFailure(request: SettleDriverFailureRequest): Promise<RunView>;
+    private assertDriverFailureReplay;
+    inspect(runId: RunId): Promise<RunView>;
+    inspectAudit(runId: RunId): Promise<RunAuditView>;
+    resume(runId: RunId): Promise<RunView>;
+    cancel(runIdOrRequest: RunId | CancelRunRequest, reason?: string | null): Promise<RunView>;
+    private systemInput;
+    private requireOriginResult;
+    private captureImportedOutput;
+    private validateSystemOutputs;
+    private currentRunResult;
+    private systemRequirementSatisfied;
+    private executeSystemOperation;
+    private beginSystemAttempt;
+    private attachSystemAttempt;
+    private reconcilePublishedSystemResult;
+    private completeSystemAttempt;
+    private drainReadySystemNodes;
+    private now;
+    private activationId;
+    private activationRoundId;
+    private requireSnapshot;
+    private requirePinnedPlan;
+    private toView;
+    private claimsFor;
+    private assertCurrentClaim;
+    private attemptRecovery;
+    private runningAttemptIsRecoverable;
+    private createClaim;
+    private toLease;
+    private toLeaseView;
+    private recoverExpiredAttempt;
+    private locateLease;
+    private assertRunAttachable;
+    private assertCapabilities;
+    private commandVerifiers;
+    private assertVerifierExecutionSupported;
+    private validateCommandVerifierReceipts;
+    private serviceVerifierIds;
+    private validateVerificationLanes;
+    private validateSubmittedOutputs;
+    private validateCallerAttestationIndependence;
+    private workspaceAllocation;
+    private workspacePlan;
+    private validateWorkspaceAllocation;
+    private requireCommittedWorkspace;
+    private planWorkspace;
+    private withWorkspaceAuthority;
+    private workspaceError;
+    private stopIntentFor;
+    private stopIdentity;
+    private persistStopIntents;
+    private prepareFailurePeerStops;
+    private prepareTerminalPeerStops;
+    private continueDurableStops;
+    private cancellationStopSpecifications;
+    private confirmDurableStop;
+    private confirmAlreadyDurableStop;
+    private confirmNeverLaunchedStop;
+    private aggregateDurableStops;
+    private requestWorkerStop;
+    private withStoppedExecution;
+    private materializePacket;
+    private verifierHandoffBindings;
+    private handoffResolutionEvents;
+    private findReplay;
+    private submissionEvidence;
+    private workerStopReceipt;
+    private outputsPreserveAuthority;
+    private revalidateWorkspaceObservations;
+    private reconcilePublishedResults;
+    private reconcilePublishedResult;
+    private loadDecisionOutputs;
+    private buildSubmissionUpdate;
+    private buildNonlaunchFailureUpdate;
+    private reduceAfterSuccess;
+    private latestActivationForStep;
+    private cancelConcurrentAttempts;
+    private reduceWithoutResult;
+    private terminalRun;
+    private retryDelay;
+    private retrySegmentDelay;
+    private jsonPointer;
+    private validateDecisionOutputs;
+    private activationEvent;
+    private runTerminalEvent;
+    private event;
+    private isVersionConflict;
+}