@ultrst-armada/kloks 1.2.1 → 1.4.0

package/packages/backend/dist/krnl-services.js

@@ -13,13 +13,13 @@ import {
   StorageServiceFacade,
   WorkspaceServiceDefinition,
   WorkspaceServiceFacade
-} from "./chunk-OYQKQAEF.js";
+} from "./chunk-CU7RZBMF.js";
+import "./chunk-IPP4VURQ.js";
 import "./chunk-J2J24JVC.js";
 import "./chunk-FZKBTF34.js";
 import "./chunk-25Y7AVTP.js";
 import "./chunk-QGHDJGYS.js";
 import "./chunk-3EPY34R6.js";
-import "./chunk-IPP4VURQ.js";
 export {
   AuthServiceDefinition,
   AuthServiceFacade,

package/packages/backend/dist/services/index.d.ts

@@ -63,4 +63,171 @@ declare class EndpointGenerator {
 declare function createBackend(name: string): CompositeBackend;
 declare function createCompositeService(name: string): CompositeBackend;
 
-export { CompositeBackend, EndpointGenerator, type GeneratedEndpointSummary, type LocalService, type RemoteServiceProxy, createBackend, createCompositeService, createLocalService, createRemoteService };
+/**
+ * @file types.ts
+ * @description Universal types for node graph document persistence, serialization, and storage sync.
+ */
+interface UniversalGraphNode {
+    id: string;
+    type?: string;
+    label?: string;
+    name?: string;
+    appId?: string;
+    deploymentId?: string;
+    position?: {
+        x: number;
+        y: number;
+    };
+    data?: Record<string, any>;
+    [key: string]: any;
+}
+interface UniversalGraphEdge {
+    id: string;
+    source: string;
+    target: string;
+    sourceSocket?: string;
+    targetSocket?: string;
+    appId?: string;
+    data?: Record<string, any>;
+    [key: string]: any;
+}
+interface UniversalAppEntity {
+    id: string;
+    name: string;
+    icon?: string;
+    description?: string;
+    publicLink?: string;
+    createdAt?: string;
+    updatedAt?: string;
+    [key: string]: any;
+}
+interface UniversalStorageConnection {
+    id: string;
+    provider: 'local_fs' | 'backblaze_b2' | 'cloudflare_r2' | 'aws_s3' | 'supabase' | string;
+    localFolderName?: string;
+    b2BucketName?: string;
+    s3BucketName?: string;
+    r2BucketName?: string;
+    supabaseBucketName?: string;
+    [key: string]: any;
+}
+interface UniversalNodeGraphDocument {
+    $schema?: string;
+    version: string;
+    appId: string;
+    appName: string;
+    appIcon?: string;
+    description?: string;
+    publicLink?: string;
+    createdAt: string;
+    updatedAt: string;
+    exportedAt: string;
+    author?: {
+        userId?: string;
+        username?: string;
+        email?: string;
+        name?: string;
+        role?: string;
+    };
+    viewport?: {
+        zoom: number;
+        pan: {
+            x: number;
+            y: number;
+        };
+    };
+    graph: {
+        nodes: UniversalGraphNode[];
+        edges: UniversalGraphEdge[];
+    };
+    deployments?: any[];
+    storageMetadata?: {
+        provider: string;
+        targetName: string;
+        targetPath: string;
+        storageConnectionId?: string;
+        checksum?: string;
+        syncedAt?: string;
+    };
+}
+interface NodeGraphValidationResult {
+    valid: boolean;
+    errors: string[];
+    document?: UniversalNodeGraphDocument;
+}
+interface SaveGraphOptions {
+    app: UniversalAppEntity;
+    nodes: UniversalGraphNode[];
+    edges: UniversalGraphEdge[];
+    deployments?: any[];
+    viewport?: {
+        zoom: number;
+        pan: {
+            x: number;
+            y: number;
+        };
+    };
+    storageConnection?: UniversalStorageConnection;
+}
+declare const LOCAL_STORAGE_GRAPHS_PREFIX = "depm_graph_doc_";
+
+/**
+ * @file helpers.ts
+ * @description Helper functions for validating, exporting, and parsing universal node graph documents.
+ */
+
+/**
+ * Validates a parsed JSON object to verify it matches the UniversalNodeGraphDocument schema.
+ */
+declare function validateGraphDocument(data: any): NodeGraphValidationResult;
+/**
+ * Triggers a browser download of the node graph as a portable JSON file.
+ */
+declare function exportGraphAsJsonFile(graphDoc: UniversalNodeGraphDocument): void;
+/**
+ * Reads and parses a graph JSON file from an input file element.
+ */
+declare function parseGraphJsonFile(file: File): Promise<NodeGraphValidationResult>;
+
+/**
+ * @file nodeGraphPersistence.ts
+ * @description Universal Node Graph Persistence Service.
+ * Manages serialization, schema validation, browser localStorage caching,
+ * and direct persistence to file system or cloud storage adapters.
+ */
+
+declare class NodeGraphPersistenceService {
+    /**
+     * Generates a fully compliant v1.0.0 JSON document representing the app's complete node graph.
+     */
+    createGraphDocument(options: SaveGraphOptions): UniversalNodeGraphDocument;
+    /**
+     * Validates a parsed JSON object to verify it matches the NodeGraphDocument schema.
+     */
+    validateGraphDocument(data: any): NodeGraphValidationResult;
+    /**
+     * Saves the node graph to the selected user storage option (Local Folder or Cloud Bucket)
+     * and caches it in LocalStorage.
+     */
+    saveGraphToStorage(options: SaveGraphOptions, customDirectoryHandle?: any): Promise<{
+        success: boolean;
+        document: UniversalNodeGraphDocument;
+        message: string;
+        targetPath: string;
+    }>;
+    /**
+     * Loads a cached or previously saved node graph document for an app.
+     */
+    loadSavedGraph(appId: string): UniversalNodeGraphDocument | null;
+    /**
+     * Triggers a browser download of the node graph as a portable JSON file.
+     */
+    exportGraphAsJsonFile(graphDoc: UniversalNodeGraphDocument): void;
+    /**
+     * Reads and parses a graph JSON file from an input file element.
+     */
+    parseGraphJsonFile(file: File): Promise<NodeGraphValidationResult>;
+}
+declare const nodeGraphPersistence: NodeGraphPersistenceService;
+
+export { CompositeBackend, EndpointGenerator, type GeneratedEndpointSummary, LOCAL_STORAGE_GRAPHS_PREFIX, type LocalService, NodeGraphPersistenceService, type NodeGraphValidationResult, type RemoteServiceProxy, type SaveGraphOptions, type UniversalAppEntity, type UniversalGraphEdge, type UniversalGraphNode, type UniversalNodeGraphDocument, type UniversalStorageConnection, createBackend, createCompositeService, createLocalService, createRemoteService, exportGraphAsJsonFile, nodeGraphPersistence, parseGraphJsonFile, validateGraphDocument };

package/packages/backend/dist/services/index.js

@@ -1,17 +1,29 @@
 import {
   CompositeBackend,
   EndpointGenerator,
+  LOCAL_STORAGE_GRAPHS_PREFIX,
+  NodeGraphPersistenceService,
   createBackend,
   createCompositeService,
   createLocalService,
-  createRemoteService
-} from "../chunk-P4HL4C6V.js";
+  createRemoteService,
+  exportGraphAsJsonFile,
+  nodeGraphPersistence,
+  parseGraphJsonFile,
+  validateGraphDocument
+} from "../chunk-BM4QMVPA.js";
 import "../chunk-IPP4VURQ.js";
 export {
   CompositeBackend,
   EndpointGenerator,
+  LOCAL_STORAGE_GRAPHS_PREFIX,
+  NodeGraphPersistenceService,
   createBackend,
   createCompositeService,
   createLocalService,
-  createRemoteService
+  createRemoteService,
+  exportGraphAsJsonFile,
+  nodeGraphPersistence,
+  parseGraphJsonFile,
+  validateGraphDocument
 };

package/packages/backend/dist/srkl/index.d.ts

@@ -96,6 +96,38 @@ interface AdaptedStorageConnection {
     s3Region?: string;
     s3Endpoint?: string;
 }
+interface KeyMaterial {
+    secretHex: string;
+    cipher: 'aes-256-gcm';
+    envelope: 'salt_iv_tag_ciphertext';
+}
+interface SrklVaultAccessResponse {
+    success: boolean;
+    appId: string;
+    workspaceId: string;
+    workspaceName: string;
+    folderPrefix: string;
+    storageProvider: 'backblaze_b2' | 'cloudflare_r2' | 'aws_s3' | string;
+    presignedUrl: string;
+    keyMaterial: KeyMaterial;
+    supportedServices: string[];
+    expiresAt: string;
+    ttlSeconds: number;
+}
+interface ServiceAccountEntry {
+    id: string;
+    serviceId: string;
+    name: string;
+    credentials: Record<string, any>;
+    status?: string;
+    lastSync?: string;
+    metadata?: Record<string, any>;
+    createdAt?: string;
+    updatedAt?: string;
+}
+interface CredentialRegistryMap {
+    [serviceId: string]: ServiceAccountEntry[];
+}
 
 /**
  * @file SrklClient.ts
@@ -188,4 +220,79 @@ interface UseSrklServicesResult {
 }
 declare function useSrklServices(options: UseSrklServicesOptions): UseSrklServicesResult;
 
-export { type AdaptedStorageConnection, type AppAccountManifest, type AppServiceDeclaration, CANONICAL_SRKL_URL, type EcosystemAccount, type EcosystemAccountsRequest, type EcosystemAccountsResponse, type EcosystemServiceCategory, SrklClient, type SrklClientOptions, type SrklEcosystemQueryOptions, type SrklEcosystemResponse, type SrklServiceAccount, type UseSrklServicesOptions, type UseSrklServicesResult, createSrklClient, getPrimarySrklDeploymentUrl, getSrklAccounts, srklListBackblazeBuckets, useSrklServices };
+declare function hexToBytes(hex: string): Uint8Array;
+/**
+ * Decrypt an AES-256-GCM vault envelope in browser memory using Web Crypto API.
+ */
+declare function decryptVaultBufferInBrowser(envelopeBuffer: ArrayBuffer | Uint8Array, secretHex: string): Promise<Uint8Array>;
+
+declare class SrklCredentialRegistry {
+    private registry;
+    constructor();
+    /**
+     * Populate the in-memory registry directly from an initialized sql.js Database instance.
+     * Performs the set intersection: DB.services ∩ DEPM.supported_services.
+     */
+    populateFromSqlite(db: any, supportedServices: string[]): void;
+    /**
+     * Register a service account in volatile memory (for manual entry or synced accounts)
+     */
+    registerServiceAccount(account: ServiceAccountEntry): void;
+    getAccountsForService(serviceId: string): ServiceAccountEntry[];
+    getPrimaryAccount(serviceId: string): ServiceAccountEntry | null;
+    hasCredentials(serviceId: string): boolean;
+    listAvailableServices(): string[];
+    toMap(): CredentialRegistryMap;
+    clear(): void;
+}
+declare const globalCredentialRegistry: SrklCredentialRegistry;
+
+interface VaultAccessClientOptions {
+    srklApiBaseUrl: string;
+    appId: string;
+    supportedServices: string[];
+}
+declare class SrklVaultAccessClient {
+    private readonly options;
+    private registry;
+    private activeGrant;
+    private sqlEngine;
+    constructor(options: VaultAccessClientOptions);
+    /**
+     * Initialize sql.js engine (WASM).
+     * Consumers can pass pre-loaded initSqlJs or let this load from window or CDN.
+     */
+    initSqlEngine(customInitSqlJs?: any): Promise<any>;
+    /**
+     * Full pipeline: Authorize → Presigned URL → Direct Download → Decrypt → SQLite Query → Registry.
+     */
+    loadCredentials(userSessionToken: string, workspaceId?: string, customInitSqlJs?: any): Promise<SrklCredentialRegistry>;
+    getRegistry(): SrklCredentialRegistry;
+    getActiveGrant(): SrklVaultAccessResponse | null;
+    clear(): void;
+}
+
+declare function syncSrklAccounts(userId: string, sessionToken: string, srklUrl?: string): Promise<{
+    success: boolean;
+    accounts?: any[];
+    error?: string;
+    sourceUrl?: string;
+}>;
+
+declare const srklService: {
+    name: string;
+    description: string;
+    runtime: {
+        VaultAccessClient: typeof SrklVaultAccessClient;
+        CredentialRegistry: typeof SrklCredentialRegistry;
+        decryptVaultBufferInBrowser: typeof decryptVaultBufferInBrowser;
+        hexToBytes: typeof hexToBytes;
+    };
+    deployment: {
+        target: string;
+        supportedEngines: string[];
+        version: string;
+    };
+};
+
+export { type AdaptedStorageConnection, type AppAccountManifest, type AppServiceDeclaration, CANONICAL_SRKL_URL, type CredentialRegistryMap, type EcosystemAccount, type EcosystemAccountsRequest, type EcosystemAccountsResponse, type EcosystemServiceCategory, type KeyMaterial, type ServiceAccountEntry, SrklClient, type SrklClientOptions, SrklCredentialRegistry, type SrklEcosystemQueryOptions, type SrklEcosystemResponse, type SrklServiceAccount, SrklVaultAccessClient, type SrklVaultAccessResponse, type UseSrklServicesOptions, type UseSrklServicesResult, type VaultAccessClientOptions, createSrklClient, decryptVaultBufferInBrowser, getPrimarySrklDeploymentUrl, getSrklAccounts, globalCredentialRegistry, hexToBytes, srklListBackblazeBuckets, srklService, syncSrklAccounts, useSrklServices };

package/packages/backend/dist/srkl/index.js

@@ -1,19 +1,33 @@
 import {
   CANONICAL_SRKL_URL,
   SrklClient,
+  SrklCredentialRegistry,
+  SrklVaultAccessClient,
   createSrklClient,
+  decryptVaultBufferInBrowser,
   getPrimarySrklDeploymentUrl,
   getSrklAccounts,
+  globalCredentialRegistry,
+  hexToBytes,
   srklListBackblazeBuckets,
+  srklService,
+  syncSrklAccounts,
   useSrklServices
-} from "../chunk-MN54ZIKZ.js";
+} from "../chunk-KX3OTBQ3.js";
 import "../chunk-4QEMALXF.js";
 export {
   CANONICAL_SRKL_URL,
   SrklClient,
+  SrklCredentialRegistry,
+  SrklVaultAccessClient,
   createSrklClient,
+  decryptVaultBufferInBrowser,
   getPrimarySrklDeploymentUrl,
   getSrklAccounts,
+  globalCredentialRegistry,
+  hexToBytes,
   srklListBackblazeBuckets,
+  srklService,
+  syncSrklAccounts,
   useSrklServices
 };

package/packages/backend/dist/workspace/index.d.ts

@@ -108,4 +108,122 @@ declare class WorkspaceCloneSyncEngine extends SkipoBase {
     }>;
 }
 
-export { type CloneReplicationResult, type ConflictPolicy, SyncEngine, type SyncState, WorkspaceCloneSyncEngine, type WorkspaceConfig, type WorkspaceDescriptor, WorkspaceFS, type WorkspaceSecondaryClone, type WorkspaceSyncSummary, formatCanonicalWorkspaceFolderName, sanitizeWorkspaceName };
+/**
+ * @file WorkspaceService.ts
+ * @description Canonical WorkspaceService interface contract for Kloks backend.
+ * Governs remote-first (DEPM) and local working-workspace (QWNSR) architectures.
+ * Conforms to Skipo Governance (< 200 lines).
+ */
+
+interface WorkspaceFileEntry {
+    path: string;
+    name: string;
+    sizeBytes?: number;
+    updatedAt?: string | number;
+    isFolder?: boolean;
+}
+interface WorkspaceLookupResult {
+    user?: any;
+    workspace: any;
+    connection?: any;
+}
+interface WorkspaceListResult {
+    success: boolean;
+    workspaces: any[];
+    activeWorkspaceId?: string | null;
+    storage_connections?: any[];
+}
+interface WorkspaceMutationResult {
+    success: boolean;
+    workspace?: any;
+    workspaces?: any[];
+}
+interface WorkspaceService {
+    readonly type: 'remote' | 'working';
+    findWorkspace(workspaceId: string, env?: Record<string, unknown>): Promise<WorkspaceLookupResult>;
+    listWorkspaces(userId?: string, env?: Record<string, unknown>): Promise<WorkspaceListResult>;
+    createWorkspace(userId: string, data: any, env?: Record<string, unknown>): Promise<WorkspaceMutationResult>;
+    updateWorkspace(userId: string, params: any, env?: Record<string, unknown>): Promise<WorkspaceMutationResult>;
+    deleteWorkspace(userId: string, workspaceId: string, env?: Record<string, unknown>): Promise<{
+        success: boolean;
+        workspaces?: any[];
+    }>;
+    readFile(workspaceId: string, filePath: string, env?: Record<string, unknown>): Promise<Uint8Array | string>;
+    writeFile(workspaceId: string, filePath: string, content: Uint8Array | string, env?: Record<string, unknown>): Promise<{
+        success: boolean;
+        path: string;
+        sizeBytes?: number;
+    }>;
+    deleteFile(workspaceId: string, filePath: string, env?: Record<string, unknown>): Promise<{
+        success: boolean;
+    }>;
+    listFiles(workspaceId: string, subfolder?: string, env?: Record<string, unknown>): Promise<WorkspaceFileEntry[]>;
+    sync?(workspaceId: string, options?: any, env?: Record<string, unknown>): Promise<WorkspaceSyncSummary>;
+}
+
+/**
+ * @file RemoteWorkspaceService.ts
+ * @description Remote-first WorkspaceService implementation for Kloks.
+ * Directly mediates with authoritative remote storage (Backblaze B2/S3/DB) without requiring local working files.
+ * Canonical choice for DEPM. Conforms to Skipo Governance (< 200 lines).
+ */
+
+declare class RemoteWorkspaceService implements WorkspaceService {
+    readonly type: "remote";
+    findWorkspace(workspaceId: string, env?: Record<string, unknown>): Promise<WorkspaceLookupResult>;
+    listWorkspaces(userId?: string, env?: Record<string, unknown>): Promise<WorkspaceListResult>;
+    createWorkspace(userId: string, data: any, env?: Record<string, unknown>): Promise<WorkspaceMutationResult>;
+    updateWorkspace(userId: string, params: any, env?: Record<string, unknown>): Promise<WorkspaceMutationResult>;
+    deleteWorkspace(userId: string, workspaceId: string, env?: Record<string, unknown>): Promise<{
+        success: boolean;
+        workspaces?: any[];
+    }>;
+    readFile(workspaceId: string, filePath: string, env?: Record<string, unknown>): Promise<Uint8Array | string>;
+    writeFile(workspaceId: string, filePath: string, content: Uint8Array | string, env?: Record<string, unknown>): Promise<{
+        success: boolean;
+        path: string;
+        sizeBytes?: number;
+    }>;
+    deleteFile(workspaceId: string, filePath: string, env?: Record<string, unknown>): Promise<{
+        success: boolean;
+    }>;
+    listFiles(workspaceId: string, subfolder?: string, env?: Record<string, unknown>): Promise<WorkspaceFileEntry[]>;
+}
+declare const remoteWorkspaceService: RemoteWorkspaceService;
+
+/**
+ * @file WorkingWorkspaceService.ts
+ * @description Local Working-Workspace implementation for Kloks.
+ * Operates on a local working directory for fast low-latency I/O and explicitly
+ * synchronizes with authoritative remote storage (Backblaze B2/S3/DB).
+ * Canonical choice for QWNSR. Conforms to Skipo Governance (< 200 lines).
+ */
+
+declare class WorkingWorkspaceService implements WorkspaceService {
+    private workingDirResolver?;
+    readonly type: "working";
+    constructor(workingDirResolver?: () => string);
+    getWorkingDir(): string;
+    findWorkspace(workspaceId: string, env?: Record<string, unknown>): Promise<WorkspaceLookupResult>;
+    listWorkspaces(userId?: string, env?: Record<string, unknown>): Promise<WorkspaceListResult>;
+    createWorkspace(userId: string, data: any, env?: Record<string, unknown>): Promise<WorkspaceMutationResult>;
+    updateWorkspace(userId: string, params: any, env?: Record<string, unknown>): Promise<WorkspaceMutationResult>;
+    deleteWorkspace(userId: string, workspaceId: string, env?: Record<string, unknown>): Promise<{
+        success: boolean;
+        workspaces?: any[];
+    }>;
+    readFile(_workspaceId: string, filePath: string): Promise<Uint8Array | string>;
+    writeFile(_workspaceId: string, filePath: string, content: Uint8Array | string): Promise<{
+        success: boolean;
+        path: string;
+        sizeBytes?: number;
+    }>;
+    deleteFile(_workspaceId: string, filePath: string): Promise<{
+        success: boolean;
+    }>;
+    listFiles(_workspaceId: string, subfolder?: string): Promise<WorkspaceFileEntry[]>;
+    sync(workspaceId: string, _options?: any, _env?: Record<string, unknown>): Promise<WorkspaceSyncSummary>;
+}
+declare const workingWorkspaceService: WorkingWorkspaceService;
+
+export { type CloneReplicationResult, type ConflictPolicy, RemoteWorkspaceService, SyncEngine, type SyncState, WorkingWorkspaceService, WorkspaceCloneSyncEngine, type WorkspaceConfig, type WorkspaceDescriptor, WorkspaceFS, type WorkspaceFileEntry, type WorkspaceListResult, type WorkspaceLookupResult, type WorkspaceMutationResult, type WorkspaceSecondaryClone, type WorkspaceService, type WorkspaceSyncSummary, formatCanonicalWorkspaceFolderName, remoteWorkspaceService, sanitizeWorkspaceName, workingWorkspaceService };

package/packages/backend/dist/workspace/index.js

@@ -1,16 +1,24 @@
 import {
+  RemoteWorkspaceService,
   SyncEngine,
+  WorkingWorkspaceService,
   WorkspaceCloneSyncEngine,
-  WorkspaceFS
-} from "../chunk-KTLD7Z4L.js";
+  WorkspaceFS,
+  remoteWorkspaceService,
+  workingWorkspaceService
+} from "../chunk-DZ4ZGIZM.js";
 import {
   formatCanonicalWorkspaceFolderName,
   sanitizeWorkspaceName
 } from "../chunk-FZKBTF34.js";
 export {
+  RemoteWorkspaceService,
   SyncEngine,
+  WorkingWorkspaceService,
   WorkspaceCloneSyncEngine,
   WorkspaceFS,
   formatCanonicalWorkspaceFolderName,
-  sanitizeWorkspaceName
+  remoteWorkspaceService,
+  sanitizeWorkspaceName,
+  workingWorkspaceService
 };

package/packages/client/dist/index.d.ts

@@ -0,0 +1,154 @@
+/**
+ * @file queueContracts.ts
+ * @description Pure browser-safe command, job, queue, and execution contracts.
+ * ZERO Node/server/BullMQ dependency closure.
+ * Conforms to Skipo Governance (< 200 lines).
+ */
+interface CorrelationMetadata {
+    correlationId: string;
+    idempotencyKey?: string;
+    timestamp: number;
+    source?: string;
+    traceId?: string;
+}
+interface BackendCommand<TPayload = unknown> {
+    id: string;
+    type: string;
+    payload: TPayload;
+    metadata?: Record<string, unknown>;
+    correlationId: string;
+    idempotencyKey?: string;
+    createdAt: number;
+}
+type JobStatus = 'QUEUED' | 'RUNNING' | 'COMPLETED' | 'FAILED' | 'RETRYING';
+type JobPriority = 'LOW' | 'NORMAL' | 'HIGH' | 'CRITICAL';
+interface RetryPolicy {
+    maxAttempts: number;
+    backoffMs: number;
+}
+interface ExecutionJob<TPayload = unknown> {
+    id: string;
+    correlationId: string;
+    command: BackendCommand<TPayload>;
+    status: JobStatus;
+    priority: JobPriority;
+    retryPolicy?: RetryPolicy;
+    attemptsMade: number;
+    createdAt: number;
+    completedAt?: number;
+}
+interface NormalizedResult<TData = unknown> {
+    correlationId: string;
+    status: 'COMPLETED' | 'FAILED';
+    data?: TData;
+    error?: string;
+    executionTimestamp: number;
+}
+interface QueueTransportOptions {
+    gatewayUrl?: string;
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+}
+interface QueueGatewayContract {
+    enqueue<T = unknown>(command: BackendCommand<T>): Promise<{
+        jobId: string;
+        correlationId: string;
+    }>;
+    checkStatus(jobId: string): Promise<NormalizedResult>;
+}
+interface WorkspaceDescriptor {
+    id: string;
+    name: string;
+    ownerId: string;
+    createdAt: number;
+    updatedAt: number;
+}
+interface WorkspaceSyncSummary {
+    success: boolean;
+    workspaceId: string;
+    folderKey: string;
+    workingDir?: string;
+    persistenceType: string;
+    targetLocation: string;
+    syncedFiles: Array<{
+        fileName: string;
+        action: string;
+        sizeBytes?: number;
+    }>;
+    uploadedCount: number;
+    downloadedCount: number;
+    syncedAt: string;
+    error?: string;
+}
+interface WorkspaceLookupResult {
+    user?: any;
+    workspace: any;
+    connection?: any;
+}
+interface WorkspaceListResult {
+    success: boolean;
+    workspaces: any[];
+    activeWorkspaceId?: string | null;
+    storage_connections?: any[];
+}
+interface WorkspaceMutationResult {
+    success: boolean;
+    workspace?: any;
+    workspaces?: any[];
+}
+interface WorkspaceFileEntry {
+    path: string;
+    name: string;
+    sizeBytes?: number;
+    updatedAt?: string | number;
+    isFolder?: boolean;
+}
+interface WorkspaceServiceContract {
+    readonly type: 'remote' | 'working';
+    findWorkspace(workspaceId: string): Promise<WorkspaceLookupResult>;
+    listWorkspaces(userId?: string): Promise<WorkspaceListResult>;
+    createWorkspace(userId: string, data: any): Promise<WorkspaceMutationResult>;
+    updateWorkspace(userId: string, params: any): Promise<WorkspaceMutationResult>;
+    deleteWorkspace(userId: string, workspaceId: string): Promise<{
+        success: boolean;
+        workspaces?: any[];
+    }>;
+    readFile(workspaceId: string, filePath: string): Promise<Uint8Array | string>;
+    writeFile(workspaceId: string, filePath: string, content: Uint8Array | string): Promise<{
+        success: boolean;
+        path: string;
+        sizeBytes?: number;
+    }>;
+    deleteFile(workspaceId: string, filePath: string): Promise<{
+        success: boolean;
+    }>;
+    listFiles(workspaceId: string, subfolder?: string): Promise<WorkspaceFileEntry[]>;
+    sync?(workspaceId: string, options?: any): Promise<WorkspaceSyncSummary>;
+}
+
+/**
+ * @file browserExecutionClient.ts
+ * @description Browser-safe execution client for SKIPO applications.
+ * Dispatches commands across the queue transport boundary to the backend queue gateway.
+ * Conforms to Skipo Governance (< 200 lines).
+ */
+
+declare class BrowserExecutionClient implements QueueGatewayContract {
+    private gatewayUrl;
+    private headers;
+    private timeoutMs;
+    constructor(options?: QueueTransportOptions);
+    createCommand<T = unknown>(type: string, payload: T, options?: {
+        correlationId?: string;
+        idempotencyKey?: string;
+        metadata?: Record<string, unknown>;
+    }): BackendCommand<T>;
+    enqueue<T = unknown>(command: BackendCommand<T>): Promise<{
+        jobId: string;
+        correlationId: string;
+    }>;
+    checkStatus(jobId: string): Promise<NormalizedResult>;
+}
+declare function createBrowserExecutionClient(options?: QueueTransportOptions): BrowserExecutionClient;
+
+export { type BackendCommand, BrowserExecutionClient, type CorrelationMetadata, type ExecutionJob, type JobPriority, type JobStatus, type NormalizedResult, type QueueGatewayContract, type QueueTransportOptions, type RetryPolicy, type WorkspaceDescriptor, type WorkspaceFileEntry, type WorkspaceListResult, type WorkspaceLookupResult, type WorkspaceMutationResult, type WorkspaceServiceContract, type WorkspaceSyncSummary, createBrowserExecutionClient };