productfoo 0.0.0-stage → 1.0.1

package/dist-public/src/discoveryReadiness.d.ts

@@ -0,0 +1,219 @@
+import { type DiscoveryBoundaryFailureReason, type DiscoveryConnectionRef, type DiscoveryHandoff, type DiscoveryLane, type DiscoveryServiceGrant, type DiscoverySubjectRef, type DiscoveryTargetRef } from "./discoveryConnections.js";
+import { type DiscoveryCapabilities, type DiscoverySourceAdapter } from "./discoverySources.js";
+export declare const READINESS_SCHEMA_VERSION = "0.1";
+export declare const READINESS_CONTRACT_VERSION = "discovery-contract-0.1";
+export declare const DISCOVERY_SERVICE_POLICY: {
+    readonly policy_version: "discovery-service-0.1";
+    readonly max_response_bytes: number;
+    readonly fetch_timeout_ms: 90000;
+    readonly max_model_input_tokens: 100000;
+    readonly max_list_sessions: 50;
+};
+export declare const SESSION_REF_TTL_MS: number;
+export type DiscoveryServiceFailureCode = "adapter_stale" | "not_connected" | "auth_expired" | "capability_missing" | "approval_missing" | "access_denied" | "network" | "provider_failure" | "service_bug";
+export type DiscoveryServiceError = {
+    code: DiscoveryServiceFailureCode;
+    message: string;
+    trace_id?: string;
+};
+export type DiscoveryServiceFailure = {
+    code: DiscoveryServiceFailureCode;
+    message: string;
+    trace_id: string;
+    resume_action: string;
+};
+export declare function boundaryFailureFor(reason: DiscoveryBoundaryFailureReason): {
+    status: DiscoveryServiceStatus;
+    code: DiscoveryServiceFailureCode;
+    message: string;
+    resume: string;
+};
+export type DiscoveryServiceStatus = "ready" | "processed" | "clean_no_op" | "not_connected" | "auth_expired" | "needs_source_approval" | "needs_service_grant" | "needs_service_verification" | "needs_provider_access" | "needs_provider_connector" | "awaiting_match" | "ambiguous_match" | "needs_research_proof" | "needs_local_apply" | "needs_review" | "result_lost" | "transcript_too_large" | "provider_timeout" | "revocation_pending" | "revoked" | "budget_exhausted" | "invalid";
+export type DiscoverySupportState = "contract_only" | "verified_live" | "degraded" | "unavailable";
+export type DiscoveryServiceResult = {
+    schema_version: "0.1";
+    operation: "discovery_connection_ready" | "discovery_list_sessions";
+    status: DiscoveryServiceStatus;
+    errors: DiscoveryServiceError[];
+    handoff: DiscoveryHandoff | null;
+    next_actions: string[];
+    coverage: Record<string, unknown>;
+};
+export type ObservedConnectionCapabilities = DiscoveryCapabilities;
+export type ObservedProviderConnection = {
+    state: "connected";
+    capabilities: ObservedConnectionCapabilities;
+} | {
+    state: "not_connected";
+} | {
+    state: "auth_expired";
+} | {
+    state: "revoked";
+};
+export interface DiscoveryListingSource<TRaw> {
+    readonly provider: string;
+    readonly connection_alias: string;
+    readonly contract_version: string;
+    readonly claimed_support_state: Exclude<DiscoverySupportState, "degraded" | "unavailable">;
+    readonly adapter: DiscoverySourceAdapter<TRaw>;
+    observeConnection(): Promise<ObservedProviderConnection> | ObservedProviderConnection;
+    listWithin(input: {
+        window: {
+            from: string;
+            to: string;
+        };
+        limit: number;
+    }): Promise<{
+        records: TRaw[];
+        truncated: boolean;
+    }>;
+}
+export type DiscoveryHostedConnectionState = "connected" | "not_connected" | "auth_expired" | "revoked";
+export type DiscoveryHostedConnection = {
+    state: "connected";
+    canonical_connection_key: string;
+} | {
+    state: "not_connected";
+} | {
+    state: "auth_expired";
+} | {
+    state: "revoked";
+};
+export type DiscoveryGrantLookup = {
+    grant: DiscoveryServiceGrant | null;
+    operations_used: number;
+};
+export interface DiscoveryReadinessService {
+    connectionState(input: {
+        subject_ref: DiscoverySubjectRef;
+        connection_ref: DiscoveryConnectionRef;
+    }): Promise<DiscoveryHostedConnection>;
+    grantForTarget(input: {
+        subject_ref: DiscoverySubjectRef;
+        target_ref: DiscoveryTargetRef;
+    }): Promise<DiscoveryGrantLookup>;
+}
+export type DiscoveryServiceKeys = {
+    source_fingerprint_key: string;
+    session_ref_key: Buffer;
+};
+export declare function deriveDiscoveryServiceKeys(root_key: string): DiscoveryServiceKeys;
+export declare function hostedDiscoverySourceFingerprint(input: {
+    subject_ref: DiscoverySubjectRef;
+    provider: string;
+    canonical_connection_key: string;
+    provider_session_identity: string;
+}, fingerprint_key: string): string;
+export type DiscoverySessionRefPayload = {
+    kind: "discovery_session_ref";
+    version: "v1";
+    subject_ref: DiscoverySubjectRef;
+    canonical_connection_key: string;
+    provider: string;
+    target_ref: DiscoveryTargetRef;
+    grant_digest: string;
+    provider_session_identity: string;
+    hosted_source_fingerprint: string;
+    revocation_epoch: number;
+    expires_at: string;
+};
+export type DiscoverySessionRefOpen = {
+    ok: true;
+    payload: DiscoverySessionRefPayload;
+} | {
+    ok: false;
+    reason: "malformed" | "wrong_key" | "tampered" | "expired" | "not_a_session_ref";
+};
+export declare function openDiscoverySessionRef(session_ref: string, key: Buffer, now: string): DiscoverySessionRefOpen;
+export type DiscoveryReadinessReport = {
+    service_reachable: boolean;
+    capability_source: "observed";
+    connection_state: DiscoveryHostedConnectionState;
+    support_state: DiscoverySupportState;
+    synthesis: {
+        available: boolean;
+    };
+    approval: {
+        state: "approved" | "missing" | "unregistered";
+        matches_grant: boolean | null;
+    };
+    grant: {
+        state: "active" | "missing" | "expired" | "stale_revocation_epoch" | "approval_mismatch" | "unregistered";
+        expires_at?: string;
+        budget?: {
+            max_operations: number;
+            used: number;
+            window: "day";
+        };
+    };
+    scheduler: {
+        mode: "manual";
+        armed: false;
+    };
+    policy: typeof DISCOVERY_SERVICE_POLICY;
+};
+export type DiscoveryConnectionReadyInput = {
+    subject_ref: DiscoverySubjectRef;
+    connection_ref: DiscoveryConnectionRef;
+    target_ref?: DiscoveryTargetRef;
+    local?: {
+        approval_digest: string | null;
+        revocation_epoch: number;
+        workspace_ref: string;
+        target_id: string;
+        lane: DiscoveryLane;
+    };
+    synthesis: {
+        available: boolean;
+    };
+    now: string;
+};
+export type DiscoveryReadinessDeps<TRaw> = {
+    service: DiscoveryReadinessService;
+    listing: DiscoveryListingSource<TRaw>;
+    keys: DiscoveryServiceKeys;
+};
+export type DiscoveryReadinessResult = DiscoveryServiceResult & {
+    operation: "discovery_connection_ready";
+    connection_ref?: DiscoveryConnectionRef;
+    target_ref?: DiscoveryTargetRef;
+    capabilities?: ObservedConnectionCapabilities;
+};
+export declare function discoverConnectionReady<TRaw>(input: DiscoveryConnectionReadyInput, deps: DiscoveryReadinessDeps<TRaw>): Promise<DiscoveryReadinessResult>;
+export type DiscoveryListSessionsInput = {
+    subject_ref: DiscoverySubjectRef;
+    connection_ref: DiscoveryConnectionRef;
+    target_ref: DiscoveryTargetRef;
+    window: {
+        from: string;
+        to: string;
+    };
+    local: {
+        approval_digest: string;
+        revocation_epoch: number;
+        workspace_ref: string;
+        target_id: string;
+        lane: DiscoveryLane;
+    };
+    now: string;
+};
+export type DiscoveryListSessionsResult = DiscoveryServiceResult & {
+    operation: "discovery_list_sessions";
+    connection_ref: DiscoveryConnectionRef;
+    target_ref: DiscoveryTargetRef;
+    sessions: DiscoveryListedSession[];
+};
+export type DiscoveryListedSession = {
+    schema_version: "0.1";
+    provider: string;
+    connection_alias: string;
+    completed_at: string;
+    completion_state: "completed";
+    title: string;
+    participants: string[];
+    stable_url?: string;
+    capabilities: DiscoveryCapabilities;
+    access: "available" | "denied";
+    session_ref: string;
+};
+export declare function discoverListSessions<TRaw>(input: DiscoveryListSessionsInput, deps: DiscoveryReadinessDeps<TRaw>): Promise<DiscoveryListSessionsResult>;