@sequenceholdings/artifact-studio 0.4.0 → 0.6.1

package/dist/manifest-next.js

@@ -1,7 +1,9 @@
 import { storageScopesSchema } from '@sequenceholdings/storage';
+import { ontologyContractSchema } from '@sequenceholdings/orm/canonical';
 import { z } from 'zod';
 import { capabilityPinsSchema, customRolesBlockSchema, validateCapabilityPins } from './manifest-custom-roles.js';
-import { apiCapabilityPathAllowed, artifactStudioStaticManifestSchema, sidebarBadgeSchema } from './manifest-static.js';
+import { isManagedServerInvokePath } from './server/managed-server-path.js';
+import { apiCapabilityPathAllowed, artifactPresentationSchema, artifactStudioStaticManifestSchema, sidebarBadgeSchema, } from './manifest-static.js';
 /** Approved major/minor profile. Builds additionally record exact patch versions. */
 export const ARTIFACT_NEXT_RUNTIME = Object.freeze({ sdk: 'sequence', node: 24, react: 19, next: '16.3' });
 /** Admission policy for new development sessions and builds; retained releases keep their recorded toolchain. */
@@ -30,13 +32,34 @@ const ormTableRef = /^[a-z][a-z0-9_]{0,40}\/(?:[a-z][a-z0-9_]{0,62}|platformUser
 const ormOperationRef = /^[a-z][a-z0-9_]{0,40}\/ops\/[_A-Za-z][_0-9A-Za-z]*$/;
 const dataReadRef = boundedRef.refine((ref) => ormTableRef.test(ref), 'ORM read references use namespace/table');
 const dataWriteRef = boundedRef.refine((ref) => ormTableRef.test(ref) || ormOperationRef.test(ref), 'ORM write references use namespace/ops/Operation or namespace/table');
+const latticeProcessRef = z.string().min(2).max(128).regex(/^[A-Za-z0-9._-]+$/, 'Process references are Lattice process ids');
 const reachShape = {
     storage: storageScopesSchema.optional(),
     data: z.strictObject({ read: z.array(dataReadRef).max(256).default([]), write: z.array(dataWriteRef).max(256).default([]) }).prefault({}),
     api: z.strictObject({ read: z.array(apiPath).max(256).default([]), write: z.array(apiPath).max(256).default([]) }).prefault({}),
     functions: z.strictObject({ invoke: z.array(boundedRef).max(256).default([]) }).prefault({}),
+    // `start`: processes the server may start runs of. `read`: processes whose runs, template and
+    // the user's own steps it may read. `act`: processes whose human steps it may advance and
+    // reassign, and whose runs' viewers it may manage. All name exact process ids; the user's own
+    // Invoker / Viewer / Advancer / Owner grants decide what happens.
+    processes: z.strictObject({
+        start: z.array(latticeProcessRef).max(256).default([]),
+        read: z.array(latticeProcessRef).max(256).default([]),
+        act: z.array(latticeProcessRef).max(256).default([]),
+    }).prefault({}),
 };
-export const artifactNextServerCapabilitiesSchema = z.strictObject(reachShape).prefault({});
+/**
+ * Where the server's audit events (`client.audit.record`) go: an Atlas audit service id. Every
+ * application may record under `artifact_studio`; Atlas admits a first-party service, such as
+ * `application_portal`, only for the projects it registers for it. Server-only: browsers can't audit.
+ */
+export const artifactNextAuditCapabilitySchema = z.strictObject({
+    service: z.string().regex(/^[a-z][a-z0-9_]{0,63}$/, 'Audit services are Atlas audit service ids, such as artifact_studio'),
+});
+export const artifactNextServerCapabilitiesSchema = z.strictObject({
+    ...reachShape,
+    audit: artifactNextAuditCapabilitySchema.optional(),
+}).prefault({});
 // Reuse role semantics and validation; only the new manifest rejects unknown keys.
 const strictCustomRoles = customRolesBlockSchema.safeExtend({
     definitions: z.record(customRolesBlockSchema.shape.definitions.unwrap().keyType, customRolesBlockSchema.shape.definitions.unwrap().valueType.strict()).default({}),
@@ -83,6 +106,7 @@ export const artifactNextBuildConfigSchema = z.strictObject({
     public_fonts: z.array(artifactNextPublicFontSchema).max(8).refine((fonts) => new Set(fonts.map((font) => font.path)).size === fonts.length, 'Public font destination paths must be unique').default([]),
 }).prefault({});
 const hostname = z.string().max(253).regex(/^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?$/, 'Egress entries must be exact lowercase DNS hostnames without schemes, ports, paths, IPs, or wildcards').refine((host) => !host.endsWith('.localhost') && !host.endsWith('.local') && !host.endsWith('.internal'), 'Egress cannot target local or platform-internal hostnames');
+const managedServerInvokePath = z.string().refine(isManagedServerInvokePath, 'Lattice accept paths are exact origin-relative paths with no query or traversal');
 export const artifactNextServerSchema = z.strictObject({
     capabilities: artifactNextServerCapabilitiesSchema,
     service_account: serviceAccountRef.optional(),
@@ -90,6 +114,10 @@ export const artifactNextServerSchema = z.strictObject({
     egress: z.array(hostname).max(64).default([]),
     resources: artifactNextResourceLimitsSchema,
     cache: z.strictObject({ capacity_gb: z.number().int().min(1).max(16) }).optional(),
+    /** Paths Lattice may POST. Exact match only; omitted means Lattice cannot call this server. */
+    lattice: z.strictObject({
+        accept: z.array(managedServerInvokePath).max(32).default([]),
+    }).optional(),
 }).superRefine((server, ctx) => {
     if (new Set(server.secrets.map((secret) => secret.name)).size !== server.secrets.length) {
         ctx.addIssue({ code: 'custom', path: ['secrets'], message: 'Each secret environment name must be unique' });
@@ -97,6 +125,9 @@ export const artifactNextServerSchema = z.strictObject({
     if (new Set(server.egress).size !== server.egress.length) {
         ctx.addIssue({ code: 'custom', path: ['egress'], message: 'Egress hosts must be unique' });
     }
+    if (server.lattice && new Set(server.lattice.accept).size !== server.lattice.accept.length) {
+        ctx.addIssue({ code: 'custom', path: ['lattice', 'accept'], message: 'Lattice accept paths must be unique' });
+    }
 }).prefault({});
 const appRoot = z.string().min(1).max(512).refine((value) => {
     if (value === '.')
@@ -105,6 +136,7 @@ const appRoot = z.string().min(1).max(512).refine((value) => {
         value.split('/').every((part) => part !== '' && part !== '.' && part !== '..' && !part.startsWith('.') && part !== 'node_modules');
 }, 'app_root must be a relative source directory without traversal, hidden directories, or node_modules').default('.');
 export const artifactStudioNextManifestSchema = z.strictObject({
+    ontology: ontologyContractSchema.optional(),
     bundle: z.strictObject({ name: z.string().min(1).max(255), schema_version: z.literal(2) }),
     artifact: z.strictObject({
         project_id: artifactStudioStaticManifestSchema.shape.artifact.shape.project_id,
@@ -120,6 +152,7 @@ export const artifactStudioNextManifestSchema = z.strictObject({
     build: artifactNextBuildConfigSchema,
     server: artifactNextServerSchema,
     targets: z.record(z.string().min(1), z.strictObject({ url: z.string().url() })).default({}),
+    presentation: artifactPresentationSchema.optional(),
     sidebarIcon: z.string().max(64).optional(),
     sidebarBadge: sidebarBadgeSchema.strict().optional(),
 }).superRefine((manifest, ctx) => {

package/dist/manifest-static.d.ts

@@ -8,8 +8,30 @@ export declare const sidebarBadgeSchema: z.ZodObject<{
     }>>;
 }, z.core.$strip>;
 export type SidebarBadgeManifest = z.infer<typeof sidebarBadgeSchema>;
+export declare const artifactPresentationSchema: z.ZodObject<{
+    mobile: z.ZodOptional<z.ZodEnum<{
+        responsive: "responsive";
+    }>>;
+}, z.core.$strip>;
+export type ArtifactPresentation = z.infer<typeof artifactPresentationSchema>;
+export declare const artifactOfflineCapabilitySchema: z.ZodObject<{
+    mode: z.ZodEnum<{
+        read: "read";
+        "read-write": "read-write";
+    }>;
+    max_age_hours: z.ZodNumber;
+    policy_version: z.ZodNumber;
+}, z.core.$strip>;
+export type ArtifactOfflineCapability = z.infer<typeof artifactOfflineCapabilitySchema>;
 export declare function apiCapabilityPathAllowed(pathname: string, allowed: readonly string[]): boolean;
 export declare const artifactStudioStaticManifestSchema: z.ZodObject<{
+    ontology: z.ZodOptional<z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        read: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        write: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        produce: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        invoke: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
     bundle: z.ZodObject<{
         name: z.ZodString;
         schema_version: z.ZodDefault<z.ZodLiteral<1>>;
@@ -63,6 +85,19 @@ export declare const artifactStudioStaticManifestSchema: z.ZodObject<{
     targets: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         url: z.ZodString;
     }, z.core.$strict>>>;
+    presentation: z.ZodOptional<z.ZodObject<{
+        mobile: z.ZodOptional<z.ZodEnum<{
+            responsive: "responsive";
+        }>>;
+    }, z.core.$strip>>;
+    offline: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodEnum<{
+            read: "read";
+            "read-write": "read-write";
+        }>;
+        max_age_hours: z.ZodNumber;
+        policy_version: z.ZodNumber;
+    }, z.core.$strip>>;
     sidebarIcon: z.ZodOptional<z.ZodString>;
     sidebarBadge: z.ZodOptional<z.ZodObject<{
         endpoint: z.ZodString;

package/dist/manifest-static.js

@@ -1,4 +1,5 @@
 import { storageScopesSchema } from '@sequenceholdings/storage';
+import { ontologyContractSchema } from '@sequenceholdings/orm/canonical';
 import { z } from 'zod';
 import { capabilityPinsSchema, customRolesBlockSchema, validateCapabilityPins, } from './manifest-custom-roles.js';
 import { normalizeArtifactPath } from './paths.js';
@@ -13,6 +14,14 @@ export const sidebarBadgeSchema = z.object({
     endpoint: apiCapabilityPathSchema,
     tone: sidebarBadgeToneSchema.optional(),
 });
+export const artifactPresentationSchema = z.object({
+    mobile: z.enum(['responsive']).optional(),
+});
+export const artifactOfflineCapabilitySchema = z.object({
+    mode: z.enum(['read', 'read-write']),
+    max_age_hours: z.number().int().min(1),
+    policy_version: z.number().int().min(1),
+});
 function matchesApiCapabilityEntry(pathname, entry) {
     if (!entry.startsWith('/api/'))
         return false;
@@ -41,6 +50,7 @@ export function apiCapabilityPathAllowed(pathname, allowed) {
     return allowed.some((entry) => matchesApiCapabilityEntry(pathname, entry));
 }
 export const artifactStudioStaticManifestSchema = z.object({
+    ontology: ontologyContractSchema.optional(),
     bundle: z.object({
         name: z.string().min(1).max(255),
         schema_version: z.literal(1).default(1),
@@ -99,6 +109,8 @@ export const artifactStudioStaticManifestSchema = z.object({
     targets: z.record(z.string().min(1), z.object({
         url: z.string().url(),
     }).strict()).default({}),
+    presentation: artifactPresentationSchema.optional(),
+    offline: artifactOfflineCapabilitySchema.optional(),
     sidebarIcon: z.string().max(64).optional(),
     sidebarBadge: sidebarBadgeSchema.optional(),
 }).superRefine((manifest, ctx) => {

package/dist/manifest.d.ts

@@ -5,6 +5,13 @@ export * from './manifest-static.js';
 export * from './manifest-next.js';
 /** Versioned parsing keeps schema-v1 stripping/default behavior unchanged. */
 export declare const artifactStudioManifestSchema: z.ZodUnion<readonly [z.ZodObject<{
+    ontology: z.ZodOptional<z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        read: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        write: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        produce: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        invoke: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
     bundle: z.ZodObject<{
         name: z.ZodString;
         schema_version: z.ZodDefault<z.ZodLiteral<1>>;
@@ -58,6 +65,19 @@ export declare const artifactStudioManifestSchema: z.ZodUnion<readonly [z.ZodObj
     targets: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         url: z.ZodString;
     }, z.core.$strict>>>;
+    presentation: z.ZodOptional<z.ZodObject<{
+        mobile: z.ZodOptional<z.ZodEnum<{
+            responsive: "responsive";
+        }>>;
+    }, z.core.$strip>>;
+    offline: z.ZodOptional<z.ZodObject<{
+        mode: z.ZodEnum<{
+            read: "read";
+            "read-write": "read-write";
+        }>;
+        max_age_hours: z.ZodNumber;
+        policy_version: z.ZodNumber;
+    }, z.core.$strip>>;
     sidebarIcon: z.ZodOptional<z.ZodString>;
     sidebarBadge: z.ZodOptional<z.ZodObject<{
         endpoint: z.ZodString;
@@ -67,6 +87,13 @@ export declare const artifactStudioManifestSchema: z.ZodUnion<readonly [z.ZodObj
         }>>;
     }, z.core.$strip>>;
 }, z.core.$strip>, z.ZodObject<{
+    ontology: z.ZodOptional<z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        read: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        write: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        produce: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        invoke: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
     bundle: z.ZodObject<{
         name: z.ZodString;
         schema_version: z.ZodLiteral<2>;
@@ -115,6 +142,11 @@ export declare const artifactStudioManifestSchema: z.ZodUnion<readonly [z.ZodObj
         functions: z.ZodPrefault<z.ZodObject<{
             invoke: z.ZodDefault<z.ZodArray<z.ZodString>>;
         }, z.core.$strict>>;
+        processes: z.ZodPrefault<z.ZodObject<{
+            start: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            read: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            act: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
     }, z.core.$strict>>;
     build: z.ZodPrefault<z.ZodObject<{
         public_env: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
@@ -126,6 +158,9 @@ export declare const artifactStudioManifestSchema: z.ZodUnion<readonly [z.ZodObj
     }, z.core.$strict>>;
     server: z.ZodPrefault<z.ZodObject<{
         capabilities: z.ZodPrefault<z.ZodObject<{
+            audit: z.ZodOptional<z.ZodObject<{
+                service: z.ZodString;
+            }, z.core.$strict>>;
             storage: z.ZodOptional<z.ZodRecord<z.ZodUUID, z.ZodEnum<{
                 viewer: "viewer";
                 editor: "editor";
@@ -142,6 +177,11 @@ export declare const artifactStudioManifestSchema: z.ZodUnion<readonly [z.ZodObj
             functions: z.ZodPrefault<z.ZodObject<{
                 invoke: z.ZodDefault<z.ZodArray<z.ZodString>>;
             }, z.core.$strict>>;
+            processes: z.ZodPrefault<z.ZodObject<{
+                start: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                read: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                act: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            }, z.core.$strict>>;
         }, z.core.$strict>>;
         service_account: z.ZodOptional<z.ZodString>;
         secrets: z.ZodDefault<z.ZodArray<z.ZodObject<{
@@ -161,10 +201,18 @@ export declare const artifactStudioManifestSchema: z.ZodUnion<readonly [z.ZodObj
         cache: z.ZodOptional<z.ZodObject<{
             capacity_gb: z.ZodNumber;
         }, z.core.$strict>>;
+        lattice: z.ZodOptional<z.ZodObject<{
+            accept: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
     }, z.core.$strict>>;
     targets: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         url: z.ZodString;
     }, z.core.$strict>>>;
+    presentation: z.ZodOptional<z.ZodObject<{
+        mobile: z.ZodOptional<z.ZodEnum<{
+            responsive: "responsive";
+        }>>;
+    }, z.core.$strip>>;
     sidebarIcon: z.ZodOptional<z.ZodString>;
     sidebarBadge: z.ZodOptional<z.ZodObject<{
         endpoint: z.ZodString;

package/dist/next-build.d.ts

@@ -15,8 +15,9 @@ export declare function resolveNextRepositoryId({ spec, repository, baseUrl, tok
     baseUrl: string;
     token: string;
 }): Promise<string>;
-export declare function submitNextBuild({ root, manifest, projectId, baseUrl, getToken, provenance, repository, repositoryId, channel, out }: {
+export declare function submitNextBuild({ root, sourceRoot, manifest, projectId, baseUrl, getToken, provenance, repository, repositoryId, channel, out }: {
     root: string;
+    sourceRoot: string;
     manifest: ArtifactStudioNextManifest;
     projectId: string;
     baseUrl: string;

package/dist/next-build.js

@@ -58,12 +58,16 @@ export async function resolveNextRepositoryId({ spec, repository, baseUrl, token
             return match[1];
     }
     catch { /* Opaque labels/SSH origins are valid preview provenance but cannot attest a release. */ }
-    throw new Error('Official Next.js releases require a Git Service repository in this Atlas environment. Push the reviewed revision, then run artifact deploy --repo <namespace>/<name> --ref main --env <env>.');
+    throw new Error('Official Next.js releases require a Git Service repository in this Atlas environment. Push the reviewed revision, then run artifact deploy --repo <namespace>/<name> --ref main --env <env> (or --ref staging for a staging environment).');
 }
-/** A verified repository build names a commit; anything else uploads the committed source snapshot. */
-function nextBuildRequestBody({ manifest, files, commit, provenance, repository, repositoryId, channel }) {
+/**
+ * A verified repository build names a commit and the application's directory in it;
+ * anything else uploads the committed source snapshot. The repository root is omitted
+ * so the request stays valid for Atlas versions that predate `sourceRoot`.
+ */
+function nextBuildRequestBody({ manifest, files, commit, provenance, repository, repositoryId, sourceRoot, channel }) {
     if (repositoryId)
-        return { repositoryId, commit, idempotencyKey: randomUUID(), channel };
+        return { repositoryId, commit, ...(sourceRoot === '.' ? {} : { sourceRoot }), idempotencyKey: randomUUID(), channel };
     return {
         manifest,
         files: files.map(({ path, content, encoding }) => ({ path, content, encoding: encoding ?? 'utf8' })),
@@ -71,7 +75,7 @@ function nextBuildRequestBody({ manifest, files, commit, provenance, repository,
         idempotencyKey: randomUUID(), channel,
     };
 }
-export async function submitNextBuild({ root, manifest, projectId, baseUrl, getToken, provenance, repository, repositoryId, channel, out }) {
+export async function submitNextBuild({ root, sourceRoot, manifest, projectId, baseUrl, getToken, provenance, repository, repositoryId, channel, out }) {
     if (!provenance.gitCommit || !/^[a-f0-9]{40}$/i.test(provenance.gitCommit)) {
         throw new Error('Commit the application source before requesting a hosted build. Use artifact dev for uncommitted local development.');
     }
@@ -80,9 +84,10 @@ export async function submitNextBuild({ root, manifest, projectId, baseUrl, getT
     if (channel === 'active' && !repositoryId)
         throw new Error('An official release requires a verified Git Service repository.');
     const path = `/api/artifact-studio/projects/${encodeURIComponent(projectId)}/next`;
-    const body = nextBuildRequestBody({ manifest, files: source.files, commit: provenance.gitCommit, provenance, repository, repositoryId, channel });
+    const body = nextBuildRequestBody({ manifest, files: source.files, commit: provenance.gitCommit, provenance, repository, repositoryId, sourceRoot, channel });
     const response = operationSchema.parse(await postJson({ baseUrl, token: await getToken(), path: `${path}/builds${repositoryId ? '/from-repository' : ''}`, body }));
-    console.log(`[seq-studio] Atlas build ${response.operation.id} (${channel}) from ${provenance.gitCommit.slice(0, 12)}`);
+    const directory = repositoryId && sourceRoot !== '.' ? ` (${sourceRoot})` : '';
+    console.log(`[seq-studio] Atlas build ${response.operation.id} (${channel}) from ${provenance.gitCommit.slice(0, 12)}${directory}`);
     console.log(`${baseUrl}/artifact-studio/projects/${projectId}`);
     const controller = new AbortController();
     const onSignal = () => controller.abort();

package/dist/offline/cache.d.ts

@@ -0,0 +1,4 @@
+import type { EncryptedOfflineStore, OfflineCache } from './types.js';
+export declare function createOfflineCache({ store, }: {
+    store: EncryptedOfflineStore;
+}): OfflineCache;

package/dist/offline/cache.js

@@ -0,0 +1,7 @@
+export function createOfflineCache({ store, }) {
+    return {
+        read: ({ key }) => store.get({ store: 'cache', key }),
+        write: ({ key, entry }) => store.set({ store: 'cache', key, value: entry }),
+        remove: ({ key }) => store.delete({ store: 'cache', key }),
+    };
+}

package/dist/offline/connector.d.ts

@@ -0,0 +1,28 @@
+import type { SequenceOfflineRequest, SequenceOfflineRequestConnector } from '../sdk.js';
+import type { OfflineReplayEngine } from './replay.js';
+import type { OfflineCache, OfflineMutationPolicy, OfflineReadPolicy } from './types.js';
+export declare class OfflineDataUnavailableError extends Error {
+    readonly path: string;
+    constructor(path: string);
+}
+export declare class OfflineWriteBlockedError extends Error {
+    readonly path: string;
+    constructor(path: string);
+}
+export interface ArtifactOfflineConnector {
+    connector: SequenceOfflineRequestConnector;
+    flush(): Promise<void>;
+}
+export declare function createArtifactOfflineConnector({ cache, readPolicy, mutationPolicy, outbox, replay, isOnline, clock, onCacheWriteError, }: {
+    cache: OfflineCache;
+    readPolicy: OfflineReadPolicy;
+    mutationPolicy: OfflineMutationPolicy;
+    outbox: import('./types.js').OfflineOutbox;
+    replay: OfflineReplayEngine;
+    isOnline: () => boolean;
+    clock?: () => number;
+    onCacheWriteError?: (input: {
+        request: SequenceOfflineRequest;
+        error: unknown;
+    }) => void;
+}): ArtifactOfflineConnector;

package/dist/offline/connector.js

@@ -0,0 +1,122 @@
+export class OfflineDataUnavailableError extends Error {
+    path;
+    constructor(path) {
+        super('No offline data available');
+        this.name = 'OfflineDataUnavailableError';
+        this.path = path;
+    }
+}
+export class OfflineWriteBlockedError extends Error {
+    path;
+    constructor(path) {
+        super('Reconnect to complete this action');
+        this.name = 'OfflineWriteBlockedError';
+        this.path = path;
+    }
+}
+function canUseCachedFallback(response) {
+    return response.status === 408 || response.status === 429 || response.status >= 500;
+}
+export function createArtifactOfflineConnector({ cache, readPolicy, mutationPolicy, outbox, replay, isOnline, clock = () => Date.now(), onCacheWriteError, }) {
+    async function readCached({ request, key, }) {
+        const cached = await cache.read({ key });
+        if (!cached || cached.expiresAt < clock()) {
+            throw new OfflineDataUnavailableError(request.path);
+        }
+        // Cache entries are written from this same typed request. The durable
+        // store cannot retain the erased generic, so restore it at the boundary.
+        return cached.response;
+    }
+    async function queueMutation({ request, descriptor, requestId, }) {
+        const observed = await descriptor.capture?.({ request });
+        const entry = await outbox.enqueue({
+            ...(requestId === undefined ? {} : { id: requestId }),
+            request,
+            entity: descriptor.entity,
+            ...(observed === undefined ? {} : { observed }),
+        });
+        await descriptor.optimisticApply?.({ entry });
+        const optimistic = descriptor.optimisticResponse?.({ entry }) ?? {
+            ok: true,
+            status: 202,
+            body: { offlineQueued: true, requestId: entry.id },
+        };
+        // Mutation descriptors define the response shape expected by their own
+        // call site; the shared queue deliberately treats payloads as unknown.
+        return optimistic;
+    }
+    const connector = {
+        async execute({ request, network }) {
+            if (request.method === 'GET') {
+                const descriptor = readPolicy.match(request);
+                if (!descriptor) {
+                    if (!isOnline())
+                        throw new OfflineDataUnavailableError(request.path);
+                    return network(request);
+                }
+                if (!isOnline()) {
+                    return readCached({ request, key: descriptor.key });
+                }
+                try {
+                    const response = await network(request);
+                    if (response.ok) {
+                        const cachedAt = clock();
+                        try {
+                            await cache.write({
+                                key: descriptor.key,
+                                entry: {
+                                    response,
+                                    cachedAt,
+                                    expiresAt: cachedAt + descriptor.ttlMs,
+                                    entity: descriptor.entity,
+                                },
+                            });
+                        }
+                        catch (error) {
+                            if (onCacheWriteError) {
+                                onCacheWriteError({ request, error });
+                            }
+                            else {
+                                console.warn('[artifact-studio] offline cache write failed:', error);
+                            }
+                        }
+                        return response;
+                    }
+                    return canUseCachedFallback(response)
+                        ? readCached({ request, key: descriptor.key })
+                        : response;
+                }
+                catch {
+                    return readCached({ request, key: descriptor.key });
+                }
+            }
+            let replayableRequest = request;
+            let requestId;
+            if (isOnline()) {
+                requestId = request.headers?.['X-Request-Id'] ?? globalThis.crypto.randomUUID();
+                replayableRequest = {
+                    ...request,
+                    headers: { ...request.headers, 'X-Request-Id': requestId },
+                };
+                try {
+                    return await network(replayableRequest);
+                }
+                catch {
+                    // A transport failure is an offline transition. Only the explicit
+                    // mutation policy may decide whether this write is durable.
+                }
+            }
+            const descriptor = mutationPolicy.match(request);
+            if (!descriptor)
+                throw new OfflineWriteBlockedError(request.path);
+            return queueMutation({ request: replayableRequest, descriptor, requestId });
+        },
+        attach: ({ network }) => {
+            replay.attach({ network });
+        },
+    };
+    return {
+        connector,
+        flush: () => replay.flush(),
+    };
+}

package/dist/offline/crypto.d.ts

@@ -0,0 +1,5 @@
+import type { OfflineCrypto } from './types.js';
+export declare function generateOfflineEncryptionKey(): Promise<CryptoKey>;
+export declare function createOfflineCrypto({ key }: {
+    key: CryptoKey;
+}): OfflineCrypto;

package/dist/offline/crypto.js

@@ -0,0 +1,24 @@
+const AES_GCM_IV_BYTES = 12;
+export async function generateOfflineEncryptionKey() {
+    return globalThis.crypto.subtle.generateKey({ name: 'AES-GCM', length: 256 }, false, ['encrypt', 'decrypt']);
+}
+export function createOfflineCrypto({ key }) {
+    return {
+        async encrypt({ value }) {
+            const serialized = JSON.stringify(value);
+            if (serialized === undefined) {
+                throw new Error('Offline values must be JSON-serializable');
+            }
+            const iv = globalThis.crypto.getRandomValues(new Uint8Array(AES_GCM_IV_BYTES));
+            const ciphertext = await globalThis.crypto.subtle.encrypt({ name: 'AES-GCM', iv }, key, new TextEncoder().encode(serialized));
+            return {
+                iv: Array.from(iv),
+                ciphertext: Array.from(new Uint8Array(ciphertext)),
+            };
+        },
+        async decrypt({ record }) {
+            const plaintext = await globalThis.crypto.subtle.decrypt({ name: 'AES-GCM', iv: new Uint8Array(record.iv) }, key, new Uint8Array(record.ciphertext));
+            return JSON.parse(new TextDecoder().decode(plaintext));
+        },
+    };
+}

package/dist/offline/index.d.ts

@@ -0,0 +1,8 @@
+export { createArtifactOfflineConnector, OfflineDataUnavailableError, OfflineWriteBlockedError, type ArtifactOfflineConnector, } from './connector.js';
+export { createOfflineCrypto, generateOfflineEncryptionKey, } from './crypto.js';
+export { openOfflineIndexedDatabase, type OfflineIndexedDatabase, } from './indexed-db.js';
+export { createOfflineCache } from './cache.js';
+export { createOfflineOutbox } from './outbox.js';
+export { classifyOfflineReplayFailure, createOfflineReplayEngine, type OfflineReplayEngine, } from './replay.js';
+export { createEncryptedOfflineStore } from './secure-store.js';
+export type { EncryptedOfflineStore, OfflineCache, OfflineCacheEntry, OfflineConflictField, OfflineConflictInfo, OfflineCrypto, OfflineEncryptedRecord, OfflineFailureKind, OfflineKvStore, OfflineMutationDescriptor, OfflineMutationPolicy, OfflineOutbox, OfflineOutboxEntry, OfflineReadDescriptor, OfflineReadPolicy, OfflineStoreName, OfflineUnresolvedWrite, } from './types.js';

package/dist/offline/index.js

@@ -0,0 +1,7 @@
+export { createArtifactOfflineConnector, OfflineDataUnavailableError, OfflineWriteBlockedError, } from './connector.js';
+export { createOfflineCrypto, generateOfflineEncryptionKey, } from './crypto.js';
+export { openOfflineIndexedDatabase, } from './indexed-db.js';
+export { createOfflineCache } from './cache.js';
+export { createOfflineOutbox } from './outbox.js';
+export { classifyOfflineReplayFailure, createOfflineReplayEngine, } from './replay.js';
+export { createEncryptedOfflineStore } from './secure-store.js';

package/dist/offline/indexed-db.d.ts

@@ -0,0 +1,10 @@
+import type { OfflineKvStore } from './types.js';
+export interface OfflineIndexedDatabase {
+    kv: OfflineKvStore;
+    nextSequence(): Promise<number>;
+    getOrCreateEncryptionKey(): Promise<CryptoKey>;
+    close(): void;
+}
+export declare function openOfflineIndexedDatabase({ databaseName, }: {
+    databaseName: string;
+}): Promise<OfflineIndexedDatabase>;