@sequenceholdings/artifact-studio 0.4.0 → 0.5.0

package/dist/offline/secure-store.js

@@ -0,0 +1,51 @@
+function isEncryptedRecord(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    return ('iv' in value &&
+        'ciphertext' in value &&
+        Array.isArray(value.iv) &&
+        Array.isArray(value.ciphertext));
+}
+export function createEncryptedOfflineStore({ kv, crypto, namespace, }) {
+    if (namespace.length === 0 || namespace.includes('\n')) {
+        throw new Error('Offline storage namespace is required');
+    }
+    const prefix = `${namespace}:`;
+    const scopedKey = (key) => `${prefix}${key}`;
+    async function scopedKeys(store) {
+        return (await kv.keys({ store }))
+            .filter((key) => key.startsWith(prefix))
+            .map((key) => key.slice(prefix.length));
+    }
+    return {
+        async get({ store, key, }) {
+            const scoped = scopedKey(key);
+            const record = await kv.get({ store, key: scoped });
+            if (!isEncryptedRecord(record))
+                return undefined;
+            try {
+                // The caller owns each logical key's schema; the encrypted store is
+                // intentionally heterogeneous and cannot infer T after JSON decode.
+                return (await crypto.decrypt({ record }));
+            }
+            catch {
+                await kv.delete({ store, key: scoped });
+                return undefined;
+            }
+        },
+        async set({ store, key, value }) {
+            await kv.set({
+                store,
+                key: scopedKey(key),
+                value: await crypto.encrypt({ value }),
+            });
+        },
+        async delete({ store, key }) {
+            await kv.delete({ store, key: scopedKey(key) });
+        },
+        keys: ({ store }) => scopedKeys(store),
+        async clear({ store }) {
+            await Promise.all((await scopedKeys(store)).map((key) => kv.delete({ store, key: scopedKey(key) })));
+        },
+    };
+}

package/dist/offline/types.d.ts

@@ -0,0 +1,162 @@
+import type { SequenceApiFetchResponse, SequenceOfflineNetwork, SequenceOfflineRequest } from '../sdk.js';
+export type OfflineStoreName = 'cache' | 'outbox' | 'accesslog';
+export interface OfflineKvStore {
+    get(input: {
+        store: OfflineStoreName;
+        key: string;
+    }): Promise<unknown>;
+    set(input: {
+        store: OfflineStoreName;
+        key: string;
+        value: unknown;
+    }): Promise<void>;
+    delete(input: {
+        store: OfflineStoreName;
+        key: string;
+    }): Promise<void>;
+    keys(input: {
+        store: OfflineStoreName;
+    }): Promise<string[]>;
+}
+export interface OfflineEncryptedRecord {
+    iv: number[];
+    ciphertext: number[];
+}
+export interface OfflineCrypto {
+    encrypt(input: {
+        value: unknown;
+    }): Promise<OfflineEncryptedRecord>;
+    decrypt(input: {
+        record: OfflineEncryptedRecord;
+    }): Promise<unknown>;
+}
+export interface EncryptedOfflineStore {
+    get<T = unknown>(input: {
+        store: OfflineStoreName;
+        key: string;
+    }): Promise<T | undefined>;
+    set(input: {
+        store: OfflineStoreName;
+        key: string;
+        value: unknown;
+    }): Promise<void>;
+    delete(input: {
+        store: OfflineStoreName;
+        key: string;
+    }): Promise<void>;
+    keys(input: {
+        store: OfflineStoreName;
+    }): Promise<string[]>;
+    clear(input: {
+        store: OfflineStoreName;
+    }): Promise<void>;
+}
+export type OfflineFailureKind = 'transient' | 'invalid' | 'auth' | 'conflict';
+export type OfflineOutboxStatus = 'pending' | 'inflight' | 'failed' | 'conflict';
+export interface OfflineConflictField {
+    key: string;
+    mine: unknown;
+    theirs: unknown;
+}
+export interface OfflineConflictInfo {
+    fields: OfflineConflictField[];
+    observedAt?: string;
+    serverUpdatedAt?: string;
+}
+export interface OfflineOutboxEntry {
+    id: string;
+    sequence: number;
+    request: SequenceOfflineRequest;
+    entity: string;
+    capturedAt: string;
+    attempts: number;
+    status: OfflineOutboxStatus;
+    observed?: Record<string, unknown>;
+    optimisticId?: string;
+    failureKind?: OfflineFailureKind;
+    lastError?: string;
+    conflict?: OfflineConflictInfo;
+    force?: boolean;
+}
+export interface OfflineOutbox {
+    enqueue(input: {
+        id?: string;
+        request: SequenceOfflineRequest;
+        entity: string;
+        observed?: Record<string, unknown>;
+        optimisticId?: string;
+    }): Promise<OfflineOutboxEntry>;
+    list(): Promise<OfflineOutboxEntry[]>;
+    update(input: {
+        id: string;
+        patch: Partial<OfflineOutboxEntry>;
+    }): Promise<void>;
+    remove(input: {
+        id: string;
+    }): Promise<void>;
+}
+export interface OfflineReadDescriptor {
+    key: string;
+    ttlMs: number;
+    entity: string;
+}
+export interface OfflineReadPolicy {
+    match(request: SequenceOfflineRequest): OfflineReadDescriptor | null;
+}
+export interface OfflineCacheEntry {
+    response: SequenceApiFetchResponse;
+    cachedAt: number;
+    expiresAt: number;
+    entity: string;
+}
+export interface OfflineCache {
+    read(input: {
+        key: string;
+    }): Promise<OfflineCacheEntry | undefined>;
+    write(input: {
+        key: string;
+        entry: OfflineCacheEntry;
+    }): Promise<void>;
+    remove(input: {
+        key: string;
+    }): Promise<void>;
+}
+export interface OfflineMutationDescriptor {
+    entity: string;
+    label(entry: OfflineOutboxEntry): string;
+    capture?(input: {
+        request: SequenceOfflineRequest;
+    }): Promise<Record<string, unknown> | undefined>;
+    optimisticApply?(input: {
+        entry: OfflineOutboxEntry;
+    }): Promise<void> | void;
+    optimisticResponse?(input: {
+        entry: OfflineOutboxEntry;
+    }): SequenceApiFetchResponse;
+    fetchCurrent?(input: {
+        entry: OfflineOutboxEntry;
+        network: SequenceOfflineNetwork;
+    }): Promise<unknown>;
+    detectConflict?(input: {
+        entry: OfflineOutboxEntry;
+        current: unknown;
+    }): OfflineConflictInfo | null;
+    reconcile?(input: {
+        entry: OfflineOutboxEntry;
+        response: SequenceApiFetchResponse;
+    }): Promise<void> | void;
+    rollback?(input: {
+        entry: OfflineOutboxEntry;
+    }): Promise<void> | void;
+}
+export interface OfflineMutationPolicy {
+    match(request: SequenceOfflineRequest): OfflineMutationDescriptor | null;
+}
+export interface OfflineUnresolvedWrite {
+    id: string;
+    label: string;
+    capturedAt: string;
+    kind: OfflineFailureKind;
+    error?: string;
+    conflict?: OfflineConflictInfo;
+}

package/dist/offline/types.js

@@ -0,0 +1 @@
+export {};

package/dist/orm-json-scalars.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The ORM data plane's opt-in exact-number wire form (orm-data-plane/src/protocol.ts).
+ * By default numeric and bigint values come back as JSON numbers, which JavaScript
+ * rounds past 15-17 significant digits. With `lossless-v1` they come back as strings
+ * ("250000.00", "9007199254740993"), and a successful response acknowledges the form
+ * with the same header. Variables may carry numeric and bigint values as decimal
+ * strings in either form.
+ */
+export declare const ORM_JSON_SCALARS_HEADER = "x-sequence-orm-json-scalars";
+export declare const ORM_LOSSLESS_JSON_SCALARS = "lossless-v1";
+export type ArtifactOrmJsonScalars = typeof ORM_LOSSLESS_JSON_SCALARS;
+/**
+ * An executor that asked for exact numbers refuses a successful result the platform
+ * did not acknowledge, because its numbers may already be rounded. Failed responses
+ * never acknowledge and keep their own error.
+ */
+export declare function assertJsonScalarsAcknowledged({ requested, acknowledged, status }: {
+    requested: ArtifactOrmJsonScalars | undefined;
+    acknowledged: string | null | undefined;
+    status: number;
+}): void;

package/dist/orm-json-scalars.js

@@ -0,0 +1,21 @@
+import { OrmOperationError } from '@sequenceholdings/orm/client';
+/**
+ * The ORM data plane's opt-in exact-number wire form (orm-data-plane/src/protocol.ts).
+ * By default numeric and bigint values come back as JSON numbers, which JavaScript
+ * rounds past 15-17 significant digits. With `lossless-v1` they come back as strings
+ * ("250000.00", "9007199254740993"), and a successful response acknowledges the form
+ * with the same header. Variables may carry numeric and bigint values as decimal
+ * strings in either form.
+ */
+export const ORM_JSON_SCALARS_HEADER = 'x-sequence-orm-json-scalars';
+export const ORM_LOSSLESS_JSON_SCALARS = 'lossless-v1';
+/**
+ * An executor that asked for exact numbers refuses a successful result the platform
+ * did not acknowledge, because its numbers may already be rounded. Failed responses
+ * never acknowledge and keep their own error.
+ */
+export function assertJsonScalarsAcknowledged({ requested, acknowledged, status }) {
+    if (requested === undefined || acknowledged === requested)
+        return;
+    throw new OrmOperationError(`Atlas did not confirm ${requested} numbers for this ORM response, so its numeric and bigint values may be rounded; update Atlas before relying on exact numbers`, status, 'LOSSLESS_TRANSPORT_UNAVAILABLE');
+}

package/dist/runtime-contracts.d.ts

@@ -72,9 +72,9 @@ export declare const artifactOperationSchema: z.ZodDiscriminatedUnion<[z.ZodObje
     projectId: z.ZodString;
     environment: z.ZodString;
     kind: z.ZodEnum<{
-        preview: "preview";
         build: "build";
         deploy: "deploy";
+        preview: "preview";
         rollback: "rollback";
         suspend: "suspend";
         delete: "delete";
@@ -92,9 +92,9 @@ export declare const artifactOperationSchema: z.ZodDiscriminatedUnion<[z.ZodObje
     projectId: z.ZodString;
     environment: z.ZodString;
     kind: z.ZodEnum<{
-        preview: "preview";
         build: "build";
         deploy: "deploy";
+        preview: "preview";
         rollback: "rollback";
         suspend: "suspend";
         delete: "delete";
@@ -109,9 +109,9 @@ export declare const artifactOperationSchema: z.ZodDiscriminatedUnion<[z.ZodObje
     projectId: z.ZodString;
     environment: z.ZodString;
     kind: z.ZodEnum<{
-        preview: "preview";
         build: "build";
         deploy: "deploy";
+        preview: "preview";
         rollback: "rollback";
         suspend: "suspend";
         delete: "delete";
@@ -130,9 +130,9 @@ export declare const artifactOperationSchema: z.ZodDiscriminatedUnion<[z.ZodObje
     projectId: z.ZodString;
     environment: z.ZodString;
     kind: z.ZodEnum<{
-        preview: "preview";
         build: "build";
         deploy: "deploy";
+        preview: "preview";
         rollback: "rollback";
         suspend: "suspend";
         delete: "delete";
@@ -147,9 +147,9 @@ export declare const artifactOperationSchema: z.ZodDiscriminatedUnion<[z.ZodObje
     projectId: z.ZodString;
     environment: z.ZodString;
     kind: z.ZodEnum<{
-        preview: "preview";
         build: "build";
         deploy: "deploy";
+        preview: "preview";
         rollback: "rollback";
         suspend: "suspend";
         delete: "delete";
@@ -164,9 +164,9 @@ export declare const artifactRuntimeSessionSchema: z.ZodObject<{
     projectId: z.ZodString;
     environment: z.ZodString;
     mode: z.ZodEnum<{
+        local: "local";
         preview: "preview";
         published: "published";
-        local: "local";
     }>;
     origin: z.ZodString;
     parentOrigin: z.ZodString;
@@ -187,12 +187,12 @@ export declare const artifactLocalDevSessionSchema: z.ZodObject<{
     sourceRevision: z.ZodOptional<z.ZodString>;
     revision: z.ZodNumber;
     state: z.ZodEnum<{
+        offline: "offline";
         failed: "failed";
         starting: "starting";
         compiling: "compiling";
         ready: "ready";
         reconnecting: "reconnecting";
-        offline: "offline";
         revoked: "revoked";
         expired: "expired";
     }>;

package/dist/sdk-orm.d.ts

@@ -1,4 +1,5 @@
 import { type OperationExecutor } from '@sequenceholdings/orm/client';
+import { type ArtifactOrmJsonScalars } from './orm-json-scalars.js';
 import { type SequenceApi } from './sdk.js';
 export interface ArtifactOrmExecutorConfig {
     namespace: string;
@@ -8,6 +9,11 @@ export interface ArtifactOrmExecutorConfig {
     sdk?: {
         api: Pick<SequenceApi, 'fetch'>;
     };
+    /**
+     * `lossless-v1` returns numeric and bigint values as strings instead of JSON numbers.
+     * The executor refuses any successful result the host does not acknowledge in that form.
+     */
+    jsonScalars?: ArtifactOrmJsonScalars;
 }
 /**
  * Execute persisted operations as the signed-in Artifact user. The host owns
@@ -15,4 +21,4 @@ export interface ArtifactOrmExecutorConfig {
  * Declare the namespace path in capabilities.api.write (queries also use POST).
  * Namespace grants, capabilities, row policies, and write checks still apply.
  */
-export declare function createArtifactOrmExecutor({ namespace, manifest, sdk }: ArtifactOrmExecutorConfig): OperationExecutor;
+export declare function createArtifactOrmExecutor({ namespace, manifest, sdk, jsonScalars }: ArtifactOrmExecutorConfig): OperationExecutor;

package/dist/sdk-orm.js

@@ -1,4 +1,5 @@
 import { createOperationExecutorWithTransport, OrmClientError } from '@sequenceholdings/orm/client';
+import { assertJsonScalarsAcknowledged, ORM_JSON_SCALARS_HEADER } from './orm-json-scalars.js';
 import { seq } from './sdk.js';
 /**
  * Execute persisted operations as the signed-in Artifact user. The host owns
@@ -6,16 +7,22 @@ import { seq } from './sdk.js';
  * Declare the namespace path in capabilities.api.write (queries also use POST).
  * Namespace grants, capabilities, row policies, and write checks still apply.
  */
-export function createArtifactOrmExecutor({ namespace, manifest, sdk = seq }) {
+export function createArtifactOrmExecutor({ namespace, manifest, sdk = seq, jsonScalars }) {
     if (!sdk || typeof sdk.api?.fetch !== 'function') {
         throw new OrmClientError('Artifact ORM requires the authenticated Artifact Studio host; open the deployed artifact or its Preview');
     }
     return createOperationExecutorWithTransport({
         namespace,
         manifest,
-        transport: ({ namespace: target, op, variables }) => sdk.api.fetch(`/api/data/v2/${target}`, {
-            method: 'POST',
-            body: { op, variables },
-        }),
+        transport: async ({ namespace: target, op, variables, idempotencyKey }) => {
+            const response = await sdk.api.fetch(`/api/data/v2/${target}`, {
+                method: 'POST',
+                body: { op, variables, ...(idempotencyKey === undefined ? {} : { idempotencyKey }) },
+                ...(jsonScalars ? { headers: { [ORM_JSON_SCALARS_HEADER]: jsonScalars } } : {}),
+            });
+            if (response.ok)
+                assertJsonScalarsAcknowledged({ requested: jsonScalars, acknowledged: response.headers?.[ORM_JSON_SCALARS_HEADER], status: response.status });
+            return response;
+        },
     });
 }

package/dist/sdk.d.ts

@@ -1,5 +1,6 @@
 import { type StartStorageUpload, type StorageUploadSession } from '@sequenceholdings/storage';
 export { createArtifactOrmExecutor, type ArtifactOrmExecutorConfig } from './sdk-orm.js';
+export type { ArtifactOrmJsonScalars } from './orm-json-scalars.js';
 export interface SequenceStorageOptions {
     signal?: AbortSignal;
     timeoutMs?: number;
@@ -48,6 +49,54 @@ export interface SequenceApi {
     patch<TBody = unknown>(path: string, body?: unknown): Promise<TBody>;
     delete<TBody = unknown>(path: string, body?: unknown): Promise<TBody>;
 }
+export type SequenceOfflineRequestMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+export interface SequenceOfflineRequest {
+    method: SequenceOfflineRequestMethod;
+    path: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+}
+export interface SequenceOfflineConnectorExecution<TBody = unknown> {
+    request: SequenceOfflineRequest;
+    /**
+     * Invoke the authenticated Artifact Studio bridge. Authentication remains
+     * host-owned and is never exposed to the connector or durable storage.
+     */
+    network: (request: SequenceOfflineRequest) => Promise<SequenceApiFetchResponse<TBody>>;
+}
+export interface SequenceOfflineNetwork {
+    execute<TBody = unknown>(request: SequenceOfflineRequest): Promise<SequenceApiFetchResponse<TBody>>;
+}
+export interface SequenceOfflineRequestConnector {
+    execute<TBody = unknown>(execution: SequenceOfflineConnectorExecution<TBody>): Promise<SequenceApiFetchResponse<TBody>>;
+    /**
+     * Receives a capability-gated bridge executor for durable outbox replay.
+     * It carries no bearer token and remains subject to the active manifest.
+     */
+    attach?(context: {
+        network: SequenceOfflineNetwork;
+    }): void | (() => void);
+}
+export interface SequenceOffline {
+    /**
+     * Install the artifact's request policy beneath seq.api. Returns a disposer
+     * that restores the network-only default when it still owns registration.
+     */
+    registerConnector(registration: {
+        connector: SequenceOfflineRequestConnector;
+    }): () => void;
+    /** Cache the current artifact shell on this device after the user's opt-in. */
+    enroll(options?: {
+        maxAgeHours?: number;
+    }): Promise<void>;
+    /** Remove this artifact's cached shell. App-owned data should be wiped too. */
+    remove(): Promise<void>;
+    status(): Promise<{
+        enabled: boolean;
+        enrolled: boolean;
+        expiresAt?: number;
+    }>;
+}
 export interface SequenceFunctions {
     invoke<TOutput = unknown>(id: string, params?: Record<string, unknown>, traceAction?: {
         id: string;
@@ -135,6 +184,7 @@ export interface SequenceHost {
 export interface SequenceArtifactSdk {
     storage: SequenceStorage;
     api: SequenceApi;
+    offline: SequenceOffline;
     ai: {
         fetch(path: string, options?: SequenceApiFetchOptions): Promise<Response>;
     };
@@ -211,6 +261,73 @@ export declare function createArtifactStorageClient(sdk?: SequenceArtifactSdk):
                 versionId: string | null;
                 maxBytes: number;
             }>;
+            startBatch: (items: StartStorageUpload[]) => Promise<{
+                items: {
+                    id: string;
+                    fileId: string;
+                    uploadUrl: string | null;
+                    expiresAt: string;
+                    state: "pending" | "complete" | "aborted";
+                    versionId: string | null;
+                    maxBytes: number;
+                }[];
+            }>;
+            list: () => Promise<{
+                items: {
+                    id: string;
+                    fileId: string;
+                    name: string;
+                    state: "pending" | "complete" | "aborted";
+                    expiresAt: string;
+                    maxBytes: number;
+                    expectedSize: number | null;
+                    versionId: string | null;
+                }[];
+                limits: {
+                    perPrincipal: number;
+                    perWorkspace: number;
+                };
+            }>;
+            reconcile: (input?: {
+                abortIncomplete?: boolean;
+            }) => Promise<{
+                completed: {
+                    id: string;
+                    fileId: string;
+                    name: string;
+                    state: "pending" | "complete" | "aborted";
+                    expiresAt: string;
+                    maxBytes: number;
+                    expectedSize: number | null;
+                    versionId: string | null;
+                    code: string;
+                    message: string;
+                }[];
+                aborted: {
+                    id: string;
+                    fileId: string;
+                    name: string;
+                    state: "pending" | "complete" | "aborted";
+                    expiresAt: string;
+                    maxBytes: number;
+                    expectedSize: number | null;
+                    versionId: string | null;
+                    code: string;
+                    message: string;
+                }[];
+                pending: {
+                    id: string;
+                    fileId: string;
+                    name: string;
+                    state: "pending" | "complete" | "aborted";
+                    expiresAt: string;
+                    maxBytes: number;
+                    expectedSize: number | null;
+                    versionId: string | null;
+                    code: string;
+                    message: string;
+                }[];
+            }>;
         };
         get: () => Promise<{
             id: string;
@@ -489,6 +606,15 @@ export declare function createArtifactStorageClient(sdk?: SequenceArtifactSdk):
     capabilities: () => Promise<{
         canProvision: boolean;
         uploadMethods: string[];
+        pendingUploads: {
+            perPrincipal: number;
+            perWorkspace: number;
+        };
+        uploadBatchLimit: number;
+        importConcurrency: {
+            default: number;
+            max: number;
+        };
     }>;
     list: (options?: import("@sequenceholdings/storage").StorageListOptions) => Promise<{
         items: {