@deksden-com/cpa-kit 0.0.0-stage → 0.1.4

package/dist/server/index.d.ts

@@ -0,0 +1,317 @@
+import { ErrorCode, ErrorDto, Command, Actor, OperationDto, Capabilities, CredentialDto, ReleaseDto, ModelsDto, AcceptResult, StatusDto, ModelDto, ListDto, ImportPreviewDto } from '../contracts/index.js';
+import 'zod';
+
+declare class CpaError extends Error {
+    code: ErrorCode;
+    retryable: boolean;
+    retryAt: string | null;
+    constructor(code: ErrorCode, message: string, retryable?: boolean, retryAt?: string | null);
+}
+declare function safeError(error: unknown, operationId?: string | null): ErrorDto;
+declare function redactText(text: string): string;
+declare function safeResult(value: Record<string, unknown>): Record<string, unknown>;
+declare function canonical(value: unknown): string;
+declare const hash: (value: unknown) => string;
+declare const newId: () => `${string}-${string}-${string}-${string}-${string}`;
+declare function confined(root: string, name: string): string;
+declare function protectedDir(path: string): Promise<void>;
+declare function atomicJson(path: string, value: unknown): Promise<void>;
+/** POSIX advisory lock: held by a child until stdin closes, survives lease expiry but not process death. */
+declare function osLock(path: string, timeoutMs?: number, options?: {
+    mode?: 0o600 | 0o660;
+}): Promise<() => Promise<void>>;
+
+interface StoredOperation {
+    dto: OperationDto;
+    command: Command;
+    actor: Actor;
+    payloadHash: string;
+    fence: number;
+    leaseUntil: string | null;
+    owner: string | null;
+    privateState: Record<string, unknown>;
+}
+interface OperationStore {
+    accept(command: Command, actor: Actor): Promise<{
+        operation: StoredOperation;
+        reused: boolean;
+    }>;
+    get(id: string): Promise<StoredOperation | null>;
+    list(): Promise<StoredOperation[]>;
+    update(id: string, revision: number, fn: (value: StoredOperation) => void): Promise<StoredOperation>;
+    writer<T>(action: () => Promise<T>): Promise<T>;
+    reap(now?: number): Promise<void>;
+}
+declare function createFsOperationStore(options: {
+    root: string;
+    clock?: () => number;
+    lockTimeoutMs?: number;
+}): OperationStore;
+
+interface Credential {
+    id: string;
+    provider: string;
+    body: Record<string, unknown>;
+    digest: string;
+}
+interface Candidate {
+    id: string;
+    actorId: string;
+    instanceId: string;
+    createdAt: number;
+    expiresAt: number;
+    credentials: Credential[];
+    skipped: number;
+    reasons: Record<string, number>;
+    preview?: {
+        revision: string;
+        expiresAt: number;
+        mode: "merge" | "replace";
+        overwriteIds: string[];
+    };
+}
+interface UploadFile {
+    name: string;
+    data: Uint8Array;
+}
+declare const defaultLimits: {
+    uploadBytes: number;
+    entries: number;
+    jsonBytes: number;
+    acceptedBytes: number;
+    expandedBytes: number;
+    ratio: number;
+    parseMs: number;
+};
+type ImportLimits = typeof defaultLimits;
+declare function parseCredential(data: Uint8Array, limits?: {
+    uploadBytes: number;
+    entries: number;
+    jsonBytes: number;
+    acceptedBytes: number;
+    expandedBytes: number;
+    ratio: number;
+    parseMs: number;
+}): Credential | null;
+declare function importFiles(files: UploadFile[], limits?: ImportLimits, duplicatePolicy?: "collapse" | "reject"): Promise<{
+    credentials: Credential[];
+    skipped: number;
+    reasons: Record<string, number>;
+}>;
+interface StagingStore {
+    upload(files: UploadFile[], actorId: string, instanceId: string): Promise<string>;
+    stage(uploadId: string, actorId: string, instanceId: string): Promise<Candidate>;
+    get(id: string, actorId: string, instanceId: string, admin?: boolean): Promise<Candidate>;
+    save(candidate: Candidate): Promise<void>;
+    remove(id: string): Promise<void>;
+    reap(protectedIds: Set<string>): Promise<void>;
+}
+declare function createFsStagingStore(options: {
+    root: string;
+    limits?: ImportLimits;
+    clock?: () => number;
+    duplicatePolicy?: "collapse" | "reject";
+}): StagingStore;
+/** Trusted CLI only: never expose directory paths as HTTP inputs. */
+declare function readCredentialDirectory(root: string, limits?: {
+    uploadBytes: number;
+    entries: number;
+    jsonBytes: number;
+    acceptedBytes: number;
+    expandedBytes: number;
+    ratio: number;
+    parseMs: number;
+}): Promise<UploadFile[]>;
+
+interface Snapshot {
+    revision: string;
+    credentials: CredentialDto[];
+}
+interface ApplyInput {
+    credentials: Credential[];
+    mode: "merge" | "replace";
+    overwriteIds: string[];
+    confirmedRemovals: string[];
+    expectedRevision: string;
+}
+interface BackendContext {
+    phase(phase: "prepare" | "switch" | "verify" | "commit", state?: Record<string, unknown>): Promise<void>;
+    check(): Promise<void>;
+}
+interface Backend {
+    capabilities: Capabilities;
+    managementAvailability: "available" | "unavailable" | "unknown";
+    snapshot(): Promise<Snapshot>;
+    apply(input: ApplyInput, ctx: BackendContext): Promise<Record<string, unknown>>;
+    delete(id: string, expectedRevision: string, ctx: BackendContext): Promise<Record<string, unknown>>;
+    recover(state: Record<string, unknown>): Promise<"verified" | "rolled_back" | "unknown">;
+}
+interface RuntimeLifecycle {
+    stop(): Promise<void>;
+    start(): Promise<void>;
+    inspect(): Promise<{
+        version: string | null;
+        state: "running" | "stopped" | "unknown";
+    }>;
+}
+declare function createReadOnlyBackend(): Backend;
+declare function createInferenceCatalog(options: {
+    baseUrl: string;
+    secret: () => Promise<string>;
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+}): () => Promise<{
+    id: string;
+    capabilities: string[];
+}[]>;
+declare function createManagedFileBackend(options: {
+    root: string;
+    activePath: string;
+    lifecycle: RuntimeLifecycle;
+    verify: () => Promise<void>;
+    allowUnknownDeletion?: boolean;
+}): Backend;
+interface ManagementTransport {
+    request(path: string, init?: RequestInit): Promise<unknown>;
+}
+declare function createManagementTransport(options: {
+    baseUrl: string;
+    secret: () => Promise<string>;
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+}): ManagementTransport;
+declare function createPostgresManagementBackend(options: {
+    transport: ManagementTransport;
+    singleController: boolean;
+    verifiedProtocol: boolean;
+    allowUnknownDeletion?: boolean;
+}): Backend;
+
+interface Authorization {
+    check(actor: Actor, instanceId: string, action: string): Promise<boolean>;
+}
+interface Maintenance {
+    enter(operationId: string, timeoutMs: number): Promise<void>;
+    leave(operationId: string): Promise<void>;
+}
+interface ReleaseAdapter {
+    list(): Promise<ReleaseDto[]>;
+    discover(): Promise<Record<string, unknown>>;
+    install(id: string, ctx: BackendContext): Promise<Record<string, unknown>>;
+    activate(id: string, ctx: BackendContext): Promise<Record<string, unknown>>;
+    delete(id: string): Promise<Record<string, unknown>>;
+    rollback(id: string, ctx: BackendContext): Promise<Record<string, unknown>>;
+    recover(state: Record<string, unknown>): Promise<"verified" | "rolled_back" | "unknown">;
+}
+interface ManagerConfig {
+    instanceId: string;
+    connection: {
+        baseUrl: string;
+        secretReference: string;
+        wireCapabilities: string[];
+    };
+    modelTtlMs?: number;
+    drainTimeoutMs?: number;
+}
+interface ManagerAdapters {
+    store: OperationStore;
+    staging: StagingStore;
+    backend: Backend;
+    authorization: Authorization;
+    lifecycle?: RuntimeLifecycle;
+    catalog?: () => Promise<{
+        id: string;
+        capabilities: string[];
+    }[]>;
+    probe?: (input: {
+        modelId: string;
+        protocol: string;
+        reasoningProfile: string | null;
+    }, signal: AbortSignal) => Promise<Record<string, unknown>>;
+    maintenance?: Maintenance;
+    releases?: ReleaseAdapter;
+    clock?: () => number;
+    onAudit?: (event: {
+        operationId: string;
+        kind: string;
+        state: string;
+    }) => Promise<void>;
+    modelCache?: {
+        get(): Promise<ModelsDto | null>;
+        put(value: ModelsDto): Promise<void>;
+    };
+}
+declare function createCpaManager(config: ManagerConfig, adapters: ManagerAdapters): {
+    connectionDescriptor: () => {
+        wireCapabilities: string[];
+        baseUrl: string;
+        secretReference: string;
+    };
+    accept: (input: unknown, actor: Actor) => Promise<AcceptResult>;
+    status: (actor: Actor) => Promise<StatusDto>;
+    credentials: (actor: Actor) => Promise<{
+        apiVersion: 1;
+        instanceId: string;
+        items: CredentialDto[];
+        nextCursor: null;
+    }>;
+    models: (actor: Actor) => Promise<{
+        stale: boolean;
+        apiVersion: 1;
+        instanceId: string;
+        models: ModelDto[];
+        fetchedAt: string | null;
+        expiresAt: string | null;
+        revision: string;
+    }>;
+    releases: (actor: Actor) => Promise<ListDto<ReleaseDto>>;
+    operations: (actor: Actor, options?: {
+        limit?: number;
+        cursor?: string;
+    }) => Promise<ListDto<OperationDto>>;
+    operation: (id: string, actor: Actor) => Promise<OperationDto>;
+    preview: (candidateId: string, actor: Actor, options?: {
+        mode?: "merge" | "replace";
+        overwriteIds?: string[];
+    }) => Promise<ImportPreviewDto>;
+    upload: (files: UploadFile[], actor: Actor) => Promise<{
+        apiVersion: 1;
+        uploadId: string;
+    }>;
+    executeOperation: (id: string) => Promise<OperationDto | undefined>;
+    recoverOperations: () => Promise<void>;
+    reapStaging: () => Promise<void>;
+};
+type CpaManager = ReturnType<typeof createCpaManager>;
+declare const executeOperation: (manager: CpaManager, id: string) => Promise<OperationDto | undefined>;
+declare const recoverOperations: (manager: CpaManager) => Promise<void>;
+declare const reapStaging: (manager: CpaManager) => Promise<void>;
+
+declare function createLinuxRuntimeLifecycle(options: {
+    helperPath: string;
+    version: () => Promise<string | null>;
+    timeoutMs?: number;
+}): RuntimeLifecycle;
+interface ApprovedRelease {
+    id: string;
+    version: string;
+    url: string;
+    sha256: string;
+    asset: "binary" | "tar.gz";
+    binaryName?: string;
+}
+interface ApprovedReleaseSource {
+    discover(): Promise<ApprovedRelease[]>;
+    allowedHosts: string[];
+}
+declare function createManagedReleaseAdapter(options: {
+    root: string;
+    activePath: string;
+    source: ApprovedReleaseSource;
+    runtime: RuntimeLifecycle;
+    verify: () => Promise<void>;
+    fetch?: typeof fetch;
+    maxDownloadBytes?: number;
+}): ReleaseAdapter;
+
+export { type ApplyInput, type ApprovedRelease, type ApprovedReleaseSource, type Authorization, type Backend, type BackendContext, type Candidate, CpaError, type CpaManager, type Credential, type ImportLimits, type Maintenance, type ManagementTransport, type ManagerAdapters, type ManagerConfig, type OperationStore, type ReleaseAdapter, type RuntimeLifecycle, type Snapshot, type StagingStore, type StoredOperation, type UploadFile, atomicJson, canonical, confined, createCpaManager, createFsOperationStore, createFsStagingStore, createInferenceCatalog, createLinuxRuntimeLifecycle, createManagedFileBackend, createManagedReleaseAdapter, createManagementTransport, createPostgresManagementBackend, createReadOnlyBackend, defaultLimits, executeOperation, hash, importFiles, newId, osLock, parseCredential, protectedDir, readCredentialDirectory, reapStaging, recoverOperations, redactText, safeError, safeResult };