@kitman-sh/sdk 0.0.0-stage → 0.6.0

package/types/packages/core/src/delivery-policy.d.ts

@@ -0,0 +1,174 @@
+import type { ActorType } from './common';
+import type { RepoBindingProvider } from './repo-binding';
+declare const DeliveryPolicyTopologies: readonly ['epic_integration', 'direct_to_default'];
+export type DeliveryPolicyTopology = (typeof DeliveryPolicyTopologies)[number];
+export declare const DeliveryPolicyOperations: readonly ['create_branch', 'push_commit', 'create_change_request', 'update_target', 'request_review', 'record_review', 'update_description', 'reply_review_thread', 'set_draft_state', 'publish_check', 'set_change_request_state', 'enqueue_merge_queue', 'delete_merged_branch', 'merge_intermediate', 'create_final_change_request', 'merge_final', 'reconcile', 'revert'];
+export type DeliveryPolicyOperation = (typeof DeliveryPolicyOperations)[number];
+export declare const DeliveryAttemptStatuses: readonly ['prepared', 'running', 'succeeded', 'failed', 'blocked', 'canceled', 'unknown_reconciliation_required', 'superseded'];
+export type DeliveryAttemptStatus = (typeof DeliveryAttemptStatuses)[number];
+export declare const DeliveryReconciliationStates: readonly ['not_required', 'pending', 'reconciling', 'resolved', 'manual'];
+export type DeliveryReconciliationState = (typeof DeliveryReconciliationStates)[number];
+declare const DeliveryFinalReviewAuthorities: readonly ['human_required', 'qualified_independent_agent'];
+type DeliveryFinalReviewAuthority = (typeof DeliveryFinalReviewAuthorities)[number];
+type DeliveryDigest = string;
+type CommitSha = string;
+export interface DeliveryRepositoryIdentity {
+    readonly provider: RepoBindingProvider;
+    readonly host: string;
+    readonly providerRepositoryId: string;
+    readonly owner: string;
+    readonly repositoryName: string;
+}
+export interface DeliveryBranchPin {
+    readonly ref: string;
+    readonly sha: CommitSha;
+}
+export interface DeliveryIntegrationBranchPolicy {
+    readonly generatedRefTemplate: string;
+    readonly ref?: string;
+    readonly creationBase: DeliveryBranchPin;
+    readonly deletionForbiddenUntilEpicClosure: boolean;
+}
+interface DeliveryVerificationPolicy {
+    readonly commandProfileDigest: DeliveryDigest;
+    readonly requiredChecks: readonly string[];
+    readonly freshnessSeconds: number;
+    readonly bindSourceSha: boolean;
+    readonly bindTargetSha: boolean;
+    readonly missingCheck: 'block' | 'manual';
+    readonly staleCheck: 'block' | 'manual';
+}
+interface DeliveryReviewPolicy {
+    readonly requiredApprovals: number;
+    readonly reviewerQualification: string;
+    readonly excludeAuthorLineage: boolean;
+    readonly unresolvedThreads: 'block' | 'allow';
+}
+interface DeliveryFinalReviewPolicy extends DeliveryReviewPolicy {
+    readonly authority: DeliveryFinalReviewAuthority;
+    readonly qualification?: string;
+}
+interface DeliveryDirectDefaultRisk {
+    readonly explicitlyOptedIn: boolean;
+    readonly reason?: string;
+    readonly approverClass?: 'human_owner' | 'human_admin' | 'qualified_independent_agent';
+    readonly extraVerificationDigest?: DeliveryDigest;
+}
+export interface DeliveryPolicy {
+    readonly id: string;
+    readonly version: number;
+    readonly digest: DeliveryDigest;
+    readonly workspaceId: string;
+    readonly projectId?: string;
+    readonly repoBindingId: string;
+    readonly epicTaskId: string;
+    readonly childTaskId?: string;
+    readonly providerHostClass: 'gitlab_com' | 'gitlab_self_managed' | 'github_com' | 'github_enterprise_server';
+    readonly repositoryIdentity: DeliveryRepositoryIdentity;
+    readonly topology: DeliveryPolicyTopology;
+    readonly integrationBranch?: DeliveryIntegrationBranchPolicy;
+    readonly defaultBranch: DeliveryBranchPin;
+    readonly taskBranchNamespace: string;
+    readonly allowStackedBranches: boolean;
+    readonly operations: readonly DeliveryPolicyOperation[];
+    readonly verification: DeliveryVerificationPolicy;
+    readonly intermediateReview: DeliveryReviewPolicy;
+    readonly finalReview: DeliveryFinalReviewPolicy;
+    readonly directDefaultRisk: DeliveryDirectDefaultRisk;
+    readonly conflicts: Readonly<Record<string, 'block' | 'manual' | 'new_attempt'>>;
+    readonly maxActiveWriteAttempts: number;
+    readonly singleWriterIntegrationBranch: boolean;
+    readonly allowedDeliveryAgentIdentityId?: string;
+    readonly accountScopeReference: string;
+    readonly evidenceRetentionClass: string;
+    readonly createdByActorType: ActorType;
+    readonly createdByActorId: string;
+    readonly createdAt: string;
+}
+export interface DeliveryPolicyDraft extends Omit<DeliveryPolicy, 'digest'> {
+    readonly digest?: DeliveryDigest;
+}
+export interface DeliveryAttempt {
+    readonly id: string;
+    readonly workspaceId: string;
+    readonly projectId: string;
+    readonly taskId: string;
+    readonly deliveryId: string;
+    readonly workUnitId: string;
+    readonly attemptNumber: number;
+    readonly policyId: string;
+    readonly policyDigest: DeliveryDigest;
+    readonly snapshotDigest: DeliveryDigest;
+    readonly operation: DeliveryPolicyOperation;
+    readonly repositoryIdentity: DeliveryRepositoryIdentity;
+    readonly source: DeliveryBranchPin;
+    readonly target: DeliveryBranchPin;
+    readonly integrationBranch?: DeliveryBranchPin;
+    readonly verificationSnapshotDigest: DeliveryDigest;
+    readonly reviewPolicyDigest: DeliveryDigest;
+    readonly effectKeys: readonly string[];
+    readonly authorActorType: ActorType;
+    readonly authorActorId: string;
+    readonly authorAgentIdentityId?: string;
+    /** Immutable actor/AgentIdentity/Loop lineage used to exclude alternate author credentials. */
+    readonly authorLineage?: readonly string[];
+    readonly status: DeliveryAttemptStatus;
+    readonly reconciliationState: DeliveryReconciliationState;
+    readonly failureCode?: string;
+    readonly createdAt: string;
+}
+export interface DeliveryChangeRequest {
+    readonly id: string;
+    readonly deliveryAttemptId: string;
+    readonly workspaceId: string;
+    readonly projectId?: string;
+    readonly taskId: string;
+    readonly repoBindingId: string;
+    readonly provider: RepoBindingProvider;
+    readonly host: string;
+    readonly owner: string;
+    readonly repositoryName: string;
+    readonly providerRepositoryId: string;
+    readonly externalId: string;
+    readonly url: string;
+    readonly title: string;
+    readonly source: DeliveryBranchPin;
+    readonly target: DeliveryBranchPin;
+    readonly status: 'draft' | 'open' | 'closed' | 'merged';
+    readonly headSha: CommitSha;
+    readonly baseSha: CommitSha;
+    readonly verificationSnapshotDigest: DeliveryDigest;
+    readonly reviewSnapshotDigest: DeliveryDigest;
+    readonly reconciliationState: DeliveryReconciliationState;
+    readonly providerObjectDigest: DeliveryDigest;
+    readonly createdByActorType: ActorType;
+    readonly createdByActorId: string;
+    readonly createdAt: string;
+}
+export interface DeliveryReviewEvidence {
+    readonly reviewerActorType: string;
+    readonly reviewerActorId: string;
+    readonly reviewerAgentIdentityId?: string;
+    readonly sourceSha: CommitSha;
+    readonly targetSha: CommitSha;
+    readonly inspectedExactRevision: boolean;
+    readonly qualified: boolean;
+    readonly authorLineage: readonly string[];
+    readonly outcome: 'approved' | 'changes_requested' | 'commented';
+}
+export interface DeliveryGateEvidence {
+    readonly checksPassed: boolean;
+    readonly checksCurrent: boolean;
+    readonly noBlockingThreads: boolean;
+    readonly mergeable: boolean;
+    readonly targetSha: CommitSha;
+    readonly sourceSha: CommitSha;
+    readonly reviews: readonly DeliveryReviewEvidence[];
+}
+export declare function createDeliveryPolicy(draft: DeliveryPolicyDraft): DeliveryPolicy;
+export declare function assertDeliveryPolicy(policy: DeliveryPolicyDraft | DeliveryPolicy): void;
+export declare function assertTargetSha(attempt: DeliveryAttempt, observedTargetSha: CommitSha): void;
+export declare function assertIndependentReview(attempt: Pick<DeliveryAttempt, 'authorActorId' | 'authorAgentIdentityId' | 'authorActorType' | 'source' | 'target'>, review: DeliveryReviewEvidence): void;
+export declare function assertIntermediateMergeGate(policy: DeliveryPolicy, attempt: DeliveryAttempt, evidence: DeliveryGateEvidence): void;
+export declare function assertFinalMergeGate(policy: DeliveryPolicy, attempt: DeliveryAttempt, evidence: DeliveryGateEvidence): void;
+export {};

package/types/packages/core/src/engineering-resources.d.ts

@@ -0,0 +1,26 @@
+import type { KitCreate } from './kit';
+declare const marketplace: {
+    readonly source: 'kitman-engineering-loop';
+    readonly publisher: 'Kitman Platform';
+    readonly visibility: 'public';
+    readonly trusted: true;
+    readonly reviewStatus: 'approved';
+    readonly installable: true;
+    readonly rollout: {
+        readonly channel: 'default';
+        readonly installDefault: true;
+        readonly preservesExistingInstallations: true;
+    };
+};
+type EngineeringKit = Omit<KitCreate, 'metadata' | 'kind'> & {
+    readonly kind: 'process' | 'technology';
+    readonly metadata: {
+        readonly marketplace: typeof marketplace;
+    };
+};
+export declare const MattPocockProcessKit: EngineeringKit;
+export declare const AddyOsmaniProcessKit: EngineeringKit;
+export declare const PonytailProcessKit: EngineeringKit;
+export declare const EngineeringTechnologyKitCatalog: readonly EngineeringKit[];
+export declare const EngineeringProcessKitCatalog: readonly EngineeringKit[];
+export {};

package/types/packages/core/src/enterprise-code-host.d.ts

@@ -0,0 +1,21 @@
+import type { CodeHostCapability } from './integration';
+type EnterpriseCodeHostSetup = {
+    readonly provider: 'github' | 'gitlab';
+    readonly host: string;
+    readonly administratorOwned: boolean;
+    readonly allowedHosts: readonly string[];
+    readonly tls: {
+        readonly verified: boolean;
+        readonly customCaRef?: string;
+    };
+    readonly capabilities: readonly CodeHostCapability[];
+};
+type EnterpriseSupportEvidence = {
+    readonly provider: 'github' | 'gitlab';
+    readonly host: string;
+    readonly capability: CodeHostCapability;
+    readonly support: 'certified' | 'detected' | 'unsupported';
+    readonly evidenceDigest: string;
+};
+export declare function certifyEnterpriseCodeHostSetup(setup: EnterpriseCodeHostSetup): readonly EnterpriseSupportEvidence[];
+export {};

package/types/packages/core/src/epic-delivery.d.ts

@@ -0,0 +1,38 @@
+import { type DeliveryPolicy } from './delivery-policy';
+declare const EpicDeliveryFactKinds: readonly ['integration_branch_observed', 'task_branch_observed', 'task_change_request_opened', 'task_intermediate_merged', 'shared_branch_contribution_accepted', 'shared_branch_contribution_lost', 'task_failed', 'task_reverted', 'effect_unknown', 'target_moved', 'review_invalidated', 'final_change_request_opened', 'final_change_request_closed', 'final_merge_reconciled'];
+export type EpicDeliveryFactKind = (typeof EpicDeliveryFactKinds)[number];
+/** The immutable WorkUnit lease tuple required by every delivery mutation. */
+export interface DeliveryWorkUnitFence {
+    readonly leaseOwnerId: string;
+    readonly runnerReplicaId: string;
+    readonly leaseId: string;
+    readonly attempt: number;
+    readonly fencingToken: string;
+    readonly capacitySlot: string;
+    readonly leaseExpiresAt: string;
+}
+export interface EpicDeliveryWriterLease {
+    readonly key: string;
+    readonly workspaceId: string;
+    readonly projectId: string;
+    readonly epicTaskId: string;
+    readonly repoBindingId: string;
+    readonly provider: DeliveryPolicy['repositoryIdentity']['provider'];
+    readonly host: string;
+    readonly providerRepositoryId: string;
+    readonly policyDigest: string;
+    readonly integrationBranchRef: string;
+    readonly integrationBranchSha: string;
+    readonly ownerId: string;
+    readonly workUnitId: string;
+    readonly fence: DeliveryWorkUnitFence;
+    readonly resourceVersion: number;
+    readonly status: 'held' | 'released';
+    readonly expiresAt: string;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+}
+export type { DeliveryAttempt, DeliveryPolicy } from './delivery-policy';
+export type SafeDeliveryEvidence = {
+    readonly [key: string]: string | number | boolean | null;
+};

package/types/packages/core/src/extension.d.ts

@@ -0,0 +1,35 @@
+import * as Schema from 'effect/Schema';
+import { SafeJson } from './run';
+export declare const NativeExtensionTarget: Schema.Literals<readonly ["runner_backend", "harness", "sandbox"]>;
+export type NativeExtensionTarget = (typeof NativeExtensionTarget)['Type'];
+/**
+ * Authoring-side reference to a namespaced, versioned native extension. Unknown
+ * identities stay valid so optional payloads survive round trips until a
+ * supporting implementation is selected.
+ */
+export declare const NativeExtensionRef: Schema.Struct<{
+    readonly extensionId: Schema.String;
+    readonly version: Schema.Int;
+    readonly policy: Schema.Literals<readonly ["optional", "required"]>;
+    readonly requiredCapabilities: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    readonly configuration: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<SafeJson, SafeJson, never, never>>>;
+}>;
+export type NativeExtensionRef = (typeof NativeExtensionRef)['Type'];
+/**
+ * Implementation-side descriptor. Exported from implementation-specific modules
+ * only; generic Agents, Steps, Loops, and Kits never import these values.
+ */
+export declare const NativeExtensionDescriptor: Schema.Struct<{
+    readonly extensionId: Schema.String;
+    readonly version: Schema.Int;
+    readonly target: Schema.Literals<readonly ["runner_backend", "harness", "sandbox"]>;
+    readonly requiredCapabilities: Schema.$Array<Schema.String>;
+    readonly configurationSchema: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<SafeJson, SafeJson, never, never>>>;
+    readonly resultSchema: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<SafeJson, SafeJson, never, never>>>;
+    readonly observability: Schema.Struct<{
+        readonly transcriptPolicy: Schema.Literal<"metadata_only">;
+        readonly maxMetadataChars: Schema.optionalKey<Schema.Int>;
+    }>;
+}>;
+export type NativeExtensionDescriptor = (typeof NativeExtensionDescriptor)['Type'];
+export declare function nativeExtensionIdentity(ref: Pick<NativeExtensionRef, 'extensionId' | 'version'>): string;

package/types/packages/core/src/external-effect.d.ts

@@ -0,0 +1,313 @@
+import * as Schema from 'effect/Schema';
+import type { JsonValue } from './runtime-type';
+declare const ExternalEffectStates: readonly ['prepared', 'executing', 'confirmed_applied', 'confirmed_absent', 'unknown', 'reconciling', 'manual'];
+declare const EffectIntentKinds: readonly ['start_loop_workflow', 'wake_loop_workflow', 'publish_work_unit', 'schedule_wake', 'reconcile_external_effect', 'publish_live_projection', 'quota_revalidate'];
+declare const EffectIntentPublicationStatuses: readonly ['pending', 'claimed', 'executing', 'applied', 'retryable', 'unknown', 'blocked'];
+declare const EffectReservationPhases: readonly ['claimed', 'executing', 'reconciling', 'settled', 'fenced'];
+declare const EffectObservationKinds: readonly ['provider_response', 'provider_lookup', 'local_not_started_proof', 'publisher_target_read', 'timeout', 'cancellation', 'lease_loss', 'cleanup', 'reservation_claimed'];
+declare const EffectObservationClassifications: readonly ['one_matching', 'none_authoritative', 'ambiguous', 'forbidden', 'unavailable', 'malformed', 'not_started'];
+declare const EffectEvidenceGrades: readonly ['authoritative', 'strong', 'supporting', 'none'];
+declare const EffectLookupModes: readonly ['provider_resource', 'provider_idempotency_key', 'provider_query_fingerprint', 'none'];
+declare const EffectOwnerKinds: readonly ['publisher', 'runner', 'reconciler', 'operator'];
+declare const ExternalEffectState: Schema.Literals<readonly ["prepared", "executing", "confirmed_applied", "confirmed_absent", "unknown", "reconciling", "manual"]>;
+export declare const EffectIntentKind: Schema.Literals<readonly ["start_loop_workflow", "wake_loop_workflow", "publish_work_unit", "schedule_wake", "reconcile_external_effect", "publish_live_projection", "quota_revalidate"]>;
+export declare const EffectIntentPublicationStatus: Schema.Literals<readonly ["pending", "claimed", "executing", "applied", "retryable", "unknown", "blocked"]>;
+export declare const EffectReservationPhase: Schema.Literals<readonly ["claimed", "executing", "reconciling", "settled", "fenced"]>;
+export declare const EffectObservationKind: Schema.Literals<readonly ["provider_response", "provider_lookup", "local_not_started_proof", "publisher_target_read", "timeout", "cancellation", "lease_loss", "cleanup", "reservation_claimed"]>;
+export declare const EffectObservationClassification: Schema.Literals<readonly ["one_matching", "none_authoritative", "ambiguous", "forbidden", "unavailable", "malformed", "not_started"]>;
+export declare const EffectEvidenceGrade: Schema.Literals<readonly ["authoritative", "strong", "supporting", "none"]>;
+export declare const EffectLookupMode: Schema.Literals<readonly ["provider_resource", "provider_idempotency_key", "provider_query_fingerprint", "none"]>;
+export declare const EffectOwnerKind: Schema.Literals<readonly ["publisher", "runner", "reconciler", "operator"]>;
+export declare const ExternalEffectProviderTargetIdentity: Schema.Struct<{
+    readonly providerPath: Schema.String;
+    readonly providerHostRef: Schema.String;
+    readonly accountScopeDigest: Schema.String;
+    readonly resourceKind: Schema.String;
+    readonly providerResourceId: Schema.optionalKey<Schema.String>;
+    readonly repositoryOrProjectId: Schema.optionalKey<Schema.String>;
+    readonly refOrBranch: Schema.optionalKey<Schema.String>;
+    readonly parentResourceId: Schema.optionalKey<Schema.String>;
+    readonly sourceBranch: Schema.optionalKey<Schema.String>;
+    readonly targetBranch: Schema.optionalKey<Schema.String>;
+    readonly sourceSha: Schema.optionalKey<Schema.String>;
+    readonly targetSha: Schema.optionalKey<Schema.String>;
+    readonly effectMarker: Schema.optionalKey<Schema.String>;
+    readonly targetIdentityVersion: Schema.String;
+}>;
+export declare const ExternalEffectLookupIdentity: Schema.Struct<{
+    readonly providerPath: Schema.String;
+    readonly providerAdapterVersion: Schema.String;
+    readonly accountScopeDigest: Schema.String;
+    readonly lookupMode: Schema.Literals<readonly ["provider_resource", "provider_idempotency_key", "provider_query_fingerprint", "none"]>;
+    readonly providerTargetIdentity: Schema.Struct<{
+        readonly providerPath: Schema.String;
+        readonly providerHostRef: Schema.String;
+        readonly accountScopeDigest: Schema.String;
+        readonly resourceKind: Schema.String;
+        readonly providerResourceId: Schema.optionalKey<Schema.String>;
+        readonly repositoryOrProjectId: Schema.optionalKey<Schema.String>;
+        readonly refOrBranch: Schema.optionalKey<Schema.String>;
+        readonly parentResourceId: Schema.optionalKey<Schema.String>;
+        readonly sourceBranch: Schema.optionalKey<Schema.String>;
+        readonly targetBranch: Schema.optionalKey<Schema.String>;
+        readonly sourceSha: Schema.optionalKey<Schema.String>;
+        readonly targetSha: Schema.optionalKey<Schema.String>;
+        readonly effectMarker: Schema.optionalKey<Schema.String>;
+        readonly targetIdentityVersion: Schema.String;
+    }>;
+    readonly providerIdempotencyKey: Schema.optionalKey<Schema.String>;
+    readonly queryFingerprint: Schema.optionalKey<Schema.String>;
+    readonly lookupSchemaDigest: Schema.String;
+}>;
+export declare const ExternalEffectProof: Schema.Struct<{
+    readonly kind: Schema.Literals<readonly ["provider_response", "provider_lookup", "publisher_target_read"]>;
+    readonly classification: Schema.Literals<readonly ["one_matching", "none_authoritative", "ambiguous", "forbidden", "unavailable", "malformed", "not_started"]>;
+    readonly requestDigest: Schema.String;
+    readonly providerTargetDigest: Schema.String;
+    readonly lookupIdentityDigest: Schema.String;
+    readonly responseDigest: Schema.optionalKey<Schema.String>;
+    readonly evidenceGrade: Schema.Literals<readonly ["authoritative", "strong", "supporting", "none"]>;
+}>;
+export declare const EffectReservationFence: Schema.Struct<{
+    readonly reservationId: Schema.String;
+    readonly ownerId: Schema.String;
+    readonly ownerReplicaId: Schema.optionalKey<Schema.String>;
+    readonly attempt: Schema.Finite;
+    readonly fencingToken: Schema.String;
+    readonly expectedResourceVersion: Schema.Finite;
+}>;
+type ExternalEffectState = (typeof ExternalEffectStates)[number];
+export type EffectIntentKind = (typeof EffectIntentKinds)[number];
+export type EffectIntentPublicationStatus = (typeof EffectIntentPublicationStatuses)[number];
+export type EffectReservationPhase = (typeof EffectReservationPhases)[number];
+export type EffectObservationKind = (typeof EffectObservationKinds)[number];
+export type EffectObservationClassification = (typeof EffectObservationClassifications)[number];
+export type EffectEvidenceGrade = (typeof EffectEvidenceGrades)[number];
+export type EffectLookupMode = (typeof EffectLookupModes)[number];
+export type EffectOwnerKind = (typeof EffectOwnerKinds)[number];
+export type ExternalEffectProviderTargetIdentity = (typeof ExternalEffectProviderTargetIdentity)['Type'];
+export type ExternalEffectLookupIdentity = (typeof ExternalEffectLookupIdentity)['Type'];
+export type ExternalEffectProof = (typeof ExternalEffectProof)['Type'];
+export type EffectReservationFence = (typeof EffectReservationFence)['Type'];
+export interface ExternalEffectOutcome {
+    readonly kind: 'applied' | 'absent' | 'unknown' | 'manual';
+    readonly observationId?: string;
+    readonly reasonCode?: string;
+    readonly responseDigest?: string;
+}
+export interface ExternalEffect {
+    readonly id: string;
+    readonly workspaceId: string;
+    readonly projectId: string | null;
+    readonly rootRunId: string;
+    readonly runId: string;
+    readonly workUnitId: string;
+    readonly stepKey: string | null;
+    readonly participantKey: string | null;
+    readonly workUnitKind: string;
+    readonly effectSlot: string;
+    readonly operationFamily: string;
+    readonly snapshotDigest: string;
+    readonly authorityDigest: string;
+    readonly budgetDigest: string;
+    readonly effectKeyDigest: string;
+    readonly requestDigest: string;
+    readonly providerTargetIdentity: ExternalEffectProviderTargetIdentity;
+    readonly providerTargetDigest: string;
+    readonly lookupMode: EffectLookupMode;
+    readonly lookupIdentity: ExternalEffectLookupIdentity;
+    readonly lookupIdentityDigest: string;
+    readonly providerIdempotencyKey: string | null;
+    readonly providerIdempotencyScope: string | null;
+    readonly providerIdempotencyRetentionSeconds: number | null;
+    readonly state: ExternalEffectState;
+    readonly resourceVersion: number;
+    readonly lastReasonCode: string | null;
+    readonly currentReservationId: string | null;
+    readonly attemptCount: number;
+    readonly reconciliationCount: number;
+    readonly availableAt: string;
+    readonly executeBy: string;
+    readonly reservationExpiresAt: string | null;
+    readonly reconcileBy: string;
+    readonly manualBy: string;
+    readonly outcome: ExternalEffectOutcome | null;
+}
+export interface EffectIntent {
+    readonly id: string;
+    readonly workspaceId: string;
+    readonly projectId: string | null;
+    readonly kind: EffectIntentKind;
+    readonly intentKey: string;
+    readonly payloadDigest: string;
+    readonly externalEffectId: string | null;
+    readonly snapshotDigest: string | null;
+    readonly targetRef: EffectTargetReference;
+    readonly availableAt: string;
+    readonly executeBy: string;
+    readonly reconcileBy: string;
+    readonly publicationStatus: EffectIntentPublicationStatus;
+    readonly resourceVersion: number;
+    readonly attemptCount: number;
+    readonly currentReservationId: string | null;
+    readonly lastReasonCode: string | null;
+}
+export interface EffectReservation {
+    readonly id: string;
+    readonly workspaceId: string;
+    readonly externalEffectId: string | null;
+    readonly effectIntentId: string | null;
+    readonly attempt: number;
+    readonly ownerKind: EffectOwnerKind;
+    readonly ownerId: string;
+    readonly ownerReplicaId: string | null;
+    readonly leaseId: string | null;
+    readonly fencingToken: string;
+    readonly expectedResourceVersion: number;
+    readonly reservedAt: string;
+    readonly expiresAt: string;
+    readonly releasedAt: string | null;
+    readonly phase: EffectReservationPhase;
+    readonly reasonCode: string | null;
+}
+export interface EffectObservation {
+    readonly id: string;
+    readonly workspaceId: string;
+    readonly externalEffectId: string | null;
+    readonly effectIntentId: string | null;
+    readonly reservationId: string | null;
+    readonly kind: EffectObservationKind;
+    readonly providerPath: string | null;
+    readonly accountScopeDigest: string | null;
+    readonly adapterVersion: string | null;
+    readonly observedAt: string;
+    readonly providerTimestamp: string | null;
+    readonly classification: EffectObservationClassification | null;
+    readonly requestDigest: string | null;
+    readonly responseDigest: string | null;
+    readonly lookupIdentityDigest: string | null;
+    readonly evidenceGrade: EffectEvidenceGrade;
+    readonly safeData: EffectObservationEvidence;
+}
+type EffectTargetReference = {
+    readonly [field: string]: JsonValue;
+};
+type EffectObservationEvidence = {
+    readonly [field: string]: JsonValue;
+};
+type NormalizedProviderRequest = {
+    readonly [field: string]: JsonValue;
+};
+interface EffectKeyInput {
+    readonly contract: 'external-effect-reconciliation.v1';
+    readonly workspaceId: string;
+    readonly rootRunId: string;
+    readonly runId: string;
+    readonly snapshotDigest: string;
+    readonly workUnitKind: string;
+    readonly stepKey?: string;
+    readonly participantKey?: string;
+    readonly effectSlot: string;
+    readonly operationFamily: string;
+}
+export interface RequestDigestInput {
+    readonly contract: 'external-effect-reconciliation.v1';
+    readonly providerPath: string;
+    readonly providerAdapterVersion: string;
+    readonly providerRequestSchemaDigest: string;
+    readonly operation: string;
+    readonly providerTargetIdentity: ExternalEffectProviderTargetIdentity;
+    readonly normalizedRequest: NormalizedProviderRequest;
+    readonly secretReferencePlaceholders: readonly string[];
+    readonly semanticIdempotencyMode: EffectLookupMode;
+}
+export declare function effectKeyDigest(input: EffectKeyInput): string;
+export declare function requestDigest(input: RequestDigestInput): string;
+export declare function lookupIdentityDigest(input: ExternalEffectLookupIdentity): string;
+export declare function providerTargetDigest(input: ExternalEffectProviderTargetIdentity): string;
+export declare function providerIdempotencyKey(providerPath: string, accountScopeDigest: string, effectKey: string): string;
+declare const ExternalEffectInvariantError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "ExternalEffectInvariantError";
+} & Readonly<A>;
+export declare class ExternalEffectInvariantError extends ExternalEffectInvariantError_base<{
+    readonly code: string;
+    readonly message: string;
+}> {
+    constructor(code: string, message: string);
+}
+type ExternalEffectTransition = {
+    readonly kind: 'begin_executing';
+    readonly reservation: EffectReservation;
+    readonly expectedResourceVersion: number;
+    readonly now: string;
+} | {
+    readonly kind: 'record_applied';
+    readonly reservation: EffectReservation;
+    readonly expectedResourceVersion: number;
+    readonly proof: ExternalEffectProof;
+    readonly now: string;
+} | {
+    readonly kind: 'record_absent';
+    readonly reservation: EffectReservation;
+    readonly expectedResourceVersion: number;
+    readonly proof: ExternalEffectProof;
+    readonly now: string;
+} | {
+    readonly kind: 'record_unknown';
+    readonly reservation: EffectReservation;
+    readonly expectedResourceVersion: number;
+    readonly reasonCode: string;
+    readonly now: string;
+} | {
+    readonly kind: 'begin_reconciliation';
+    readonly reservation: EffectReservation;
+    readonly expectedResourceVersion: number;
+    readonly now: string;
+} | {
+    readonly kind: 'record_lookup';
+    readonly reservation: EffectReservation;
+    readonly expectedResourceVersion: number;
+    readonly proof: ExternalEffectProof;
+    readonly now: string;
+} | {
+    readonly kind: 'prepare_retry';
+    readonly reservation: EffectReservation;
+    readonly expectedResourceVersion: number;
+    readonly now: string;
+} | {
+    readonly kind: 'manual';
+    readonly reservation?: EffectReservation;
+    readonly expectedResourceVersion: number;
+    readonly reasonCode: string;
+    readonly now: string;
+};
+export declare function assertExternalEffectProof(effect: ExternalEffect, proof: ExternalEffectProof, classification: EffectObservationClassification): void;
+export declare function transitionExternalEffect(effect: ExternalEffect, transition: ExternalEffectTransition): ExternalEffect;
+type EffectIntentTransition = {
+    readonly kind: 'claim';
+    readonly reservation: EffectReservation;
+    readonly expectedResourceVersion: number;
+} | {
+    readonly kind: 'begin_executing';
+    readonly reservation: EffectReservation;
+    readonly expectedResourceVersion: number;
+} | {
+    readonly kind: 'applied';
+    readonly reservation: EffectReservation;
+    readonly expectedResourceVersion: number;
+} | {
+    readonly kind: 'retryable';
+    readonly reservation: EffectReservation;
+    readonly expectedResourceVersion: number;
+} | {
+    readonly kind: 'record_unknown';
+    readonly reservation: EffectReservation;
+    readonly expectedResourceVersion: number;
+    readonly reasonCode: string;
+} | {
+    readonly kind: 'blocked';
+    readonly expectedResourceVersion: number;
+    readonly reasonCode: string;
+};
+export declare function transitionEffectIntent(intent: EffectIntent, transition: EffectIntentTransition): EffectIntent;
+export {};