@sequenceholdings/artifact-studio 0.4.0 → 0.6.1

package/dist/server/broker-contract.js

@@ -1,4 +1,6 @@
 import { z } from 'zod';
+import { ORM_LOSSLESS_JSON_SCALARS } from '../orm-json-scalars.js';
+export { ORM_JSON_SCALARS_HEADER, ORM_LOSSLESS_JSON_SCALARS } from '../orm-json-scalars.js';
 export const artifactServerMethodSchema = z.enum(['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE']);
 export const artifactServerModeSchema = z.enum(['user', 'service']).default('user');
 /** Reject paths that intermediaries can normalize into a different authorization target. */
@@ -21,13 +23,152 @@ const path = z.string().min(6).max(8192).refine(isArtifactApiPath, 'Expected a c
 const method = artifactServerMethodSchema;
 const mode = artifactServerModeSchema;
 const id = z.string().min(1).max(255).regex(/^[a-zA-Z0-9_-]+$/);
+// Lattice ids become FGA object ids, so they keep to the FGA-safe class.
+const latticeId = z.string().min(2).max(128).regex(/^[A-Za-z0-9._-]+$/);
+// A process version is the registry's own label (the bundle hash prefix today); FGA-safe class.
+const latticeVersion = z.string().min(1).max(128).regex(/^[A-Za-z0-9._-]+$/);
+/** A Lattice run's lifecycle status, as `GET /api/lattice/runs` filters it. */
+export const ARTIFACT_PROCESS_RUN_STATUSES = ['pending', 'running', 'completed', 'failed', 'cancelled', 'timed_out'];
+/** Lattice lists at most this many runs per call. */
+export const ARTIFACT_PROCESS_RUNS_LIMIT = 500;
+/** Which of the user's human steps to list: parked and waiting on them, or already done. */
+export const ARTIFACT_PROCESS_TASK_VIEWS = ['active', 'completed'];
+/** Lattice lists at most this many human steps per call, as its own inbox does. */
+export const ARTIFACT_PROCESS_TASKS_LIMIT = 500;
+/** A grant or revocation names at most this many users and groups together. */
+export const ARTIFACT_PROCESS_PRINCIPALS_PER_CALL = 100;
+/** A principal search returns at most this many users and groups together, as Lattice's own picker. */
+export const ARTIFACT_PROCESS_PRINCIPAL_SEARCH_LIMIT = 50;
+export const ARTIFACT_PROCESS_PRINCIPAL_TYPES = ['user', 'group'];
+// A user's Auth0 `sub` or a chat group id, as FGA subjects are keyed: no whitespace, `:`, `#` or `*`.
+const principalId = z.string().min(1).max(255).regex(/^[^\s:#*]+$/);
+/** The users and groups a grant, revocation or reassignment names: at least one principal, bounded. */
+const principalSet = {
+    users: z.array(principalId).max(ARTIFACT_PROCESS_PRINCIPALS_PER_CALL).optional(),
+    groups: z.array(principalId).max(ARTIFACT_PROCESS_PRINCIPALS_PER_CALL).optional(),
+};
+function namesPrincipals(value) {
+    const count = (value.users?.length ?? 0) + (value.groups?.length ?? 0);
+    return count > 0 && count <= ARTIFACT_PROCESS_PRINCIPALS_PER_CALL;
+}
+const PRINCIPAL_SET_MESSAGE = `Between 1 and ${ARTIFACT_PROCESS_PRINCIPALS_PER_CALL} users and groups`;
+/** A start seeds assignments for at most this many human nodes. */
+export const ARTIFACT_PROCESS_START_ASSIGNMENT_NODES = 64;
+// A human node of the started run (`execute`), or one inside a nested subprocess (`application::qa_review`).
+const assignmentNodeKey = z.string().min(1).max(255).regex(/^[A-Za-z0-9._-]+(?:::[A-Za-z0-9._-]+)*$/);
+/**
+ * Per-run default assignees for human nodes, as `POST /api/lattice/runs` takes them: each node's
+ * principals become its advancers when the run reaches it. Atlas refuses principals it has tombstoned.
+ */
+const runAssignments = z.record(assignmentNodeKey, z.object(principalSet).strict().refine(namesPrincipals, PRINCIPAL_SET_MESSAGE))
+    .refine((value) => Object.keys(value).length > 0 && Object.keys(value).length <= ARTIFACT_PROCESS_START_ASSIGNMENT_NODES, `Between 1 and ${ARTIFACT_PROCESS_START_ASSIGNMENT_NODES} assigned nodes`);
+const entityRef = z.string().min(1).max(255);
+// Unleash feature names are URL-safe.
+const flagName = z.string().min(1).max(255).regex(/^[A-Za-z0-9._~-]+$/);
+export const ARTIFACT_FLAGS_PER_REQUEST = 32;
+/** The audit actions an application may record. Sign-in, identity merges and webhooks stay Atlas's. */
+export const ARTIFACT_AUDIT_ACTIONS = [
+    'view', 'search', 'create', 'update', 'delete', 'download', 'upload', 'export', 'import', 'share', 'submit', 'approve', 'reject', 'execute',
+];
+/** One bulk action (archive the 100 selected applications) is one event naming each of them. */
+export const ARTIFACT_AUDIT_RESOURCES_PER_EVENT = 100;
+export const ARTIFACT_AUDIT_METADATA_KEYS = 32;
+// Resource types are identifiers, as Atlas's own (`application`, `applicationDocument`), so an
+// application that takes over a product's routes can keep the types its audit queries filter on.
+const auditResourceType = z.string().regex(/^[A-Za-z][A-Za-z0-9_]{0,63}$/);
+const auditMetadataKey = z.string().regex(/^[A-Za-z][A-Za-z0-9_]{0,63}$/);
+const auditEvent = {
+    /** Names the logical event. A retry of the same event reuses it, so the audit sink keeps one copy. */
+    eventId: z.uuid(),
+    action: z.enum(ARTIFACT_AUDIT_ACTIONS),
+    /** What happened, as the product names it (`applications.view`). Recorded as the event's `action_detail`. */
+    detail: z.string().regex(/^[a-z][a-z0-9_.-]{0,95}$/),
+    // None for an event about no one record (a list or a settings view), as Atlas's own list events.
+    resources: z.array(z.object({ type: auditResourceType, id: z.string().min(1).max(255) }).strict())
+        .max(ARTIFACT_AUDIT_RESOURCES_PER_EVENT),
+    // Scalars only: an audit record names what happened, it doesn't copy payloads.
+    metadata: z.record(auditMetadataKey, z.union([z.string().max(256), z.number(), z.boolean(), z.null()]))
+        .refine(value => Object.keys(value).length <= ARTIFACT_AUDIT_METADATA_KEYS, `At most ${ARTIFACT_AUDIT_METADATA_KEYS} metadata keys`)
+        .optional(),
+};
 /** Atlas validates these operations against current manifest, bindings and principal grants. */
 export const artifactServerRequestSchema = z.discriminatedUnion('operation', [
     z.object({ operation: z.literal('api'), mode, method, path, body: z.unknown().optional() }).strict(),
-    z.object({ operation: z.literal('orm'), mode, namespace: id, op: z.string().regex(/^sha256:[a-f0-9]{64}$/), variables: z.record(z.string(), z.unknown()).optional() }).strict(),
+    // jsonScalars asks the data plane for exact numeric and bigint strings; Atlas forwards it as
+    // the data plane's own header and passes the acknowledgment back.
+    z.object({
+        operation: z.literal('orm'), mode, namespace: id, op: z.string().regex(/^sha256:[a-f0-9]{64}$/),
+        variables: z.record(z.string(), z.unknown()).optional(), jsonScalars: z.literal(ORM_LOSSLESS_JSON_SCALARS).optional(),
+    }).strict(),
     z.object({ operation: z.literal('storage'), mode, method, path: path.refine(value => {
             const pathname = value.split('?')[0];
             return pathname === '/api/storage' || pathname.startsWith('/api/storage/');
         }, 'Expected a Storage API path'), body: z.unknown().optional() }).strict(),
     z.object({ operation: z.literal('function'), mode, id, params: z.record(z.string(), z.unknown()).optional() }).strict(),
+    // Starts a run of a declared process, as `POST /api/lattice/runs` does: the application names the
+    // run, passes its input and may seed who works each human node. The start node, version and
+    // engine stay with the process and its owning routes.
+    z.object({
+        operation: z.literal('lattice'), mode, process: latticeId, runId: latticeId.optional(),
+        title: z.string().max(500).optional(),
+        entity: z.object({ type: entityRef, id: entityRef }).strict().optional(),
+        metadata: z.record(z.string(), z.unknown()).optional(),
+        assignments: runAssignments.optional(),
+    }).strict(),
+    // Lists runs of a declared process, as `GET /api/lattice/runs` does: newest first, only the runs
+    // the user may view. Soft-archived runs are excluded unless `archived` is set.
+    z.object({
+        operation: z.literal('lattice_runs'), mode, process: latticeId,
+        status: z.enum(ARTIFACT_PROCESS_RUN_STATUSES).optional(),
+        entity: z.object({ type: entityRef, id: entityRef.optional() }).strict().optional(),
+        limit: z.number().int().min(1).max(ARTIFACT_PROCESS_RUNS_LIMIT).optional(),
+        archived: z.boolean().optional(),
+    }).strict(),
+    // Reads one run the user may view, as `GET /api/lattice/runs/[runId]` does: the run, its steps, the
+    // collapsed per-node states and the event cursor to resume its stream from.
+    z.object({ operation: z.literal('lattice_run'), mode, runId: latticeId }).strict(),
+    // Describes a declared process — the applied template its runs are filled in from: nodes, edges and
+    // what a person working each human step is shown. The active version, or the one a run pinned.
+    z.object({ operation: z.literal('lattice_process'), mode, process: latticeId, version: latticeVersion.optional() }).strict(),
+    // Lists the user's own human steps across declared processes (a subset, or every declared one),
+    // as `GET /api/lattice/inbox` does for the Tasks app: newest first, from the assignment index.
+    z.object({
+        operation: z.literal('lattice_tasks'), mode,
+        processes: z.array(latticeId).min(1).max(256).optional(),
+        view: z.enum(ARTIFACT_PROCESS_TASK_VIEWS).optional(),
+        limit: z.number().int().min(1).max(ARTIFACT_PROCESS_TASKS_LIMIT).optional(),
+    }).strict(),
+    // Completes one of the user's parked human steps on a run of a process declared under
+    // `processes.act`, as `POST /api/lattice/runs/[runId]/advance` does. The user's own step
+    // `advancer` grant decides; the application cannot complete it as someone else.
+    z.object({
+        operation: z.literal('lattice_advance'), mode, runId: latticeId,
+        stepId: latticeId.optional(), edgeId: z.string().min(1).max(255).optional(),
+        payload: z.record(z.string(), z.unknown()).optional(),
+    }).strict(),
+    // Reassigns a parked human step to users and groups, as `POST .../steps/[stepId]/assign` does.
+    // The user's run `owner` relation decides; the node's assignee allowlist still applies.
+    z.object({ operation: z.literal('lattice_assign'), mode, runId: latticeId, stepId: latticeId, ...principalSet }).strict()
+        .refine(namesPrincipals, PRINCIPAL_SET_MESSAGE),
+    // The explicit viewer grants on a run, for its owner.
+    z.object({ operation: z.literal('lattice_viewers'), mode, runId: latticeId }).strict(),
+    // Shares a run with users and groups (grants `viewer`), or takes a share back. Owner-gated;
+    // grants Atlas has tombstoned (disabled users, deleted groups) are refused.
+    z.object({ operation: z.literal('lattice_viewer_grant'), mode, runId: latticeId, ...principalSet }).strict()
+        .refine(namesPrincipals, PRINCIPAL_SET_MESSAGE),
+    z.object({ operation: z.literal('lattice_viewer_revoke'), mode, runId: latticeId, ...principalSet }).strict()
+        .refine(namesPrincipals, PRINCIPAL_SET_MESSAGE),
+    // Finds users in the user's own tenant and groups they may see, to name in an assignment or a
+    // share. The user is the directory's own, so no manifest binding beyond `processes.act` applies.
+    z.object({
+        operation: z.literal('lattice_principals'), mode, q: z.string().trim().max(200),
+        types: z.array(z.enum(ARTIFACT_PROCESS_PRINCIPAL_TYPES)).min(1).max(2).optional(),
+        limit: z.number().int().min(1).max(ARTIFACT_PROCESS_PRINCIPAL_SEARCH_LIMIT).optional(),
+    }).strict(),
+    // Evaluates feature flags as Atlas evaluates its own: for the user, or with no user in service mode.
+    // A read: it needs no manifest declaration, as the browser bridge's flags.isEnabled needs none.
+    z.object({ operation: z.literal('flags'), mode, names: z.array(flagName).min(1).max(ARTIFACT_FLAGS_PER_REQUEST) }).strict(),
+    // Records an audit event for the request's user, under the service `server.capabilities.audit`
+    // declares. It changes no data, so read-only and stale contexts may record what they read.
+    z.object({ operation: z.literal('audit'), mode, ...auditEvent }).strict(),
 ]);

package/dist/server/client.d.ts

@@ -1,20 +1,17 @@
 import { storageClient } from '@sequenceholdings/storage';
 import { type OperationExecutor } from '@sequenceholdings/orm/client';
-import type { SequenceApiFetchResponse } from '../sdk.js';
-import { type ArtifactServerMode, type ArtifactServerRequest } from './broker-contract.js';
+import { type ArtifactAuditAction, type ArtifactServerMode } from './broker-contract.js';
+import { type ArtifactServerProcesses } from './processes.js';
+import { type ArtifactOrmJsonScalars } from '../orm-json-scalars.js';
 import { createArtifactLogger, type ArtifactLogRecord } from './logger.js';
-import { type ArtifactRequestContext } from './request-context.js';
+import { type ArtifactRequestContext, type RequestContextV2External } from './request-context.js';
+import { type ArtifactExternalAccept } from './external-context.js';
+import { createApiClient } from './api-client.js';
+import { type ArtifactPrincipal } from './principal.js';
 import { type ArtifactRuntimeConfig, type ArtifactRequestHeaders } from './runtime-config.js';
-export declare class ArtifactServerError extends Error {
-    readonly status: number;
-    readonly code: string;
-    constructor(status: number, code: string, message: string);
-}
-export interface ArtifactServerFetchOptions {
-    method?: 'GET' | 'HEAD' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
-    body?: unknown;
-    signal?: AbortSignal;
-}
+export { ArtifactPrincipalError, ArtifactServerError, INSUFFICIENT_USER_AUTHENTICATION, stepUpResponse } from './errors.js';
+export type * from './processes.js';
+export type { ArtifactServerFetchOptions } from './api-client.js';
 /**
  * The namespace's generated operations.manifest.json. Only each operation's persisted hash
  * is read, so the file can be passed as imported: a JSON import types `kind` as string.
@@ -29,8 +26,54 @@ export interface ArtifactOrmOperations {
         readonly requires?: unknown;
     }>>;
 }
-export interface ArtifactServerClient {
-    context: ArtifactRequestContext;
+export interface ArtifactOrmOptions {
+    namespace: string;
+    manifest: ArtifactOrmOperations;
+    /**
+     * `lossless-v1` returns numeric and bigint values as strings instead of JSON numbers,
+     * so money and large ids survive a read-then-write. The executor refuses any successful
+     * result Atlas does not acknowledge in that form. Omit it for the JSON-number default.
+     */
+    jsonScalars?: ArtifactOrmJsonScalars;
+}
+/**
+ * Feature flags, evaluated by Atlas for this request's user (with no user in service mode), the
+ * same evaluation Atlas routes make. Any flag may be read, as in the browser's `seq.flags`. A
+ * refused or failed request rejects with ArtifactServerError; treat that as off where a flag gates
+ * a change.
+ */
+export interface ArtifactServerFlags {
+    isEnabled(flagName: string): Promise<boolean>;
+    /** Up to ARTIFACT_FLAGS_PER_REQUEST flags in one broker call. */
+    evaluate(flagNames: readonly string[]): Promise<Record<string, boolean>>;
+}
+/** One audit event, recorded for this request's user under the manifest's `server.capabilities.audit` service. */
+export interface ArtifactAuditEvent {
+    action: ArtifactAuditAction;
+    /** What happened, as the product names it (`applications.view`). Recorded as the event's `action_detail`. */
+    detail: string;
+    /** What it happened to, at most ARTIFACT_AUDIT_RESOURCES_PER_EVENT: `{ type: 'application', id }`. Empty for a list. */
+    resources: ReadonlyArray<{
+        type: string;
+        id: string;
+    }>;
+    /** Scalars that qualify the event (counts, kinds, outcomes). Never payloads, document contents or secrets. */
+    metadata?: Readonly<Record<string, string | number | boolean | null>>;
+    /** Names the logical event; one is generated when omitted. Pass the same id to retry the same event. */
+    eventId?: string;
+}
+/**
+ * Audit events, delivered before `record` resolves. A refused or undeliverable event rejects with
+ * ArtifactServerError; decide per route whether that should fail the request.
+ */
+export interface ArtifactServerAudit {
+    record(event: ArtifactAuditEvent): Promise<void>;
+}
+export type ArtifactServerContext = ArtifactRequestContext | RequestContextV2External;
+export interface ArtifactServerClient<TContext extends ArtifactServerContext = ArtifactRequestContext> {
+    context: TContext;
+    /** Who the request acts for. An `external` principal reaches platform services only through `asService()`. */
+    principal: ArtifactPrincipal;
     mode: ArtifactServerMode;
     log: ReturnType<typeof createArtifactLogger>;
     api: ReturnType<typeof createApiClient>;
@@ -38,44 +81,36 @@ export interface ArtifactServerClient {
     functions: {
         invoke<TOutput = unknown>(id: string, params?: Record<string, unknown>): Promise<TOutput>;
     };
-    orm(input: {
-        namespace: string;
-        manifest: ArtifactOrmOperations;
-    }): OperationExecutor;
-    asService(): ArtifactServerClient;
+    processes: ArtifactServerProcesses;
+    flags: ArtifactServerFlags;
+    audit: ArtifactServerAudit;
+    orm(input: ArtifactOrmOptions): OperationExecutor;
+    asService(): ArtifactServerClient<TContext>;
 }
-/** One instance per incoming request. Never cache it at module scope. */
-export declare function createArtifactServerClient({ headers, runtime, fetch: fetcher, method, path, logSink }: {
+export interface ArtifactServerClientOptions {
     headers: ArtifactRequestHeaders;
     /** Optional explicit platform config; otherwise reads SEQUENCE_ARTIFACT_RUNTIME_FILE. */
     runtime?: ArtifactRuntimeConfig;
     fetch?: typeof globalThis.fetch;
+    /** Required, with `path`, to accept an external caller. */
     method?: string;
     path?: string;
     logSink?: (record: ArtifactLogRecord) => void;
+}
+/**
+ * One instance per incoming request. Never cache it at module scope.
+ *
+ * Accepts Atlas-user and platform-service contexts. A handler that also serves external callers
+ * names their ingresses in `accept`; its client then carries an external context, whose
+ * `principal` reaches platform services only through `asService()`.
+ */
+export declare function createArtifactServerClient(options: ArtifactServerClientOptions & {
+    accept?: undefined;
 }): Promise<ArtifactServerClient>;
-type ClientArguments = {
-    context: ArtifactRequestContext;
-    token: string;
-    getRuntime: () => Promise<ArtifactRuntimeConfig>;
-    fetcher: typeof globalThis.fetch;
-    mode: ArtifactServerMode;
-    logSink?: (record: ArtifactLogRecord) => void;
-};
-type BrokerTransport = ReturnType<typeof createBrokerTransport>;
-declare function createBrokerTransport({ context, token, getRuntime, fetcher }: ClientArguments): (input: ArtifactServerRequest, signal?: AbortSignal) => Promise<Response>;
-declare function createApiClient({ mode, request, json }: {
-    mode: ArtifactServerMode;
-    request: BrokerTransport;
-    json: (operation: ArtifactServerRequest, signal?: AbortSignal) => Promise<unknown>;
-}): {
-    request: (path: string, options?: ArtifactServerFetchOptions) => Promise<Response>;
-    fetch<TBody = unknown>(path: string, options?: ArtifactServerFetchOptions): Promise<SequenceApiFetchResponse<TBody>>;
-    stream(path: string, options?: ArtifactServerFetchOptions): Promise<ReadableStream<Uint8Array<ArrayBuffer>>>;
-    get: <T = unknown>(path: string) => Promise<T>;
-    post: <T = unknown>(path: string, body?: unknown) => Promise<T>;
-    put: <T = unknown>(path: string, body?: unknown) => Promise<T>;
-    patch: <T = unknown>(path: string, body?: unknown) => Promise<T>;
-    delete: <T = unknown>(path: string, body?: unknown) => Promise<T>;
-};
-export {};
+export declare function createArtifactServerClient(options: ArtifactServerClientOptions & {
+    accept: ArtifactExternalAccept;
+}): Promise<ArtifactServerClient<ArtifactServerContext>>;
+/** For a helper that forwards an optional `accept`: the context may be either version. */
+export declare function createArtifactServerClient(options: ArtifactServerClientOptions & {
+    accept?: ArtifactExternalAccept;
+}): Promise<ArtifactServerClient<ArtifactServerContext>>;

package/dist/server/client.js

@@ -1,33 +1,42 @@
+import { randomUUID } from 'node:crypto';
 import { StorageApiError, storageClient, storageErrorSchema } from '@sequenceholdings/storage';
 import { OrmOperationError } from '@sequenceholdings/orm/client';
 import { z } from 'zod';
 import { artifactServerRequestSchema } from './broker-contract.js';
+import { createArtifactProcessesClient } from './processes.js';
+import { assertJsonScalarsAcknowledged, ORM_JSON_SCALARS_HEADER } from '../orm-json-scalars.js';
 import { createArtifactLogger } from './logger.js';
 import { ARTIFACT_REQUEST_CONTEXT_HEADER, ARTIFACT_RUNTIME_TOKEN_HEADER, ARTIFACT_SERVER_REQUEST_PATH, verifyArtifactRequestContext } from './request-context.js';
+import { verifyArtifactExternalContext } from './external-context.js';
+import { isExternalContextToken } from './internal/signed-token.js';
+import { createApiClient } from './api-client.js';
+import { pause, transientConnectionCode } from './connection-retry.js';
+import { principalFromContext } from './principal.js';
 import { artifactRuntimeConfigSchema, readArtifactRuntimeConfig } from './runtime-config.js';
-export class ArtifactServerError extends Error {
-    status;
-    code;
-    constructor(status, code, message) {
-        super(message);
-        this.status = status;
-        this.code = code;
-        this.name = 'ArtifactServerError';
-    }
-}
+import { ArtifactPrincipalError, ArtifactServerError, refusalFromResponse, stepUpError, stepUpErrorFromResponse } from './errors.js';
+export { ArtifactPrincipalError, ArtifactServerError, INSUFFICIENT_USER_AUTHENTICATION, stepUpResponse } from './errors.js';
 const graphqlResponseSchema = z.object({
     data: z.unknown().optional(),
     errors: z.array(z.object({ message: z.string(), extensions: z.object({ code: z.string().optional() }).passthrough().optional() })).optional(),
 });
-const responseHeaders = ['content-type', 'content-disposition', 'content-length', 'retry-after'];
+const flagsResponseSchema = z.object({ flags: z.record(z.string(), z.boolean()) });
 const maxBodyBytes = 1024 * 1024;
-/** One instance per incoming request. Never cache it at module scope. */
-export async function createArtifactServerClient({ headers, runtime, fetch: fetcher = globalThis.fetch, method, path, logSink }) {
+/** A read whose connection failed is sent at most three times, pausing up to 100 ms, then up to 200 ms. */
+const reconnect = { attempts: 3, baseDelayMs: 100 };
+export async function createArtifactServerClient({ headers, runtime, fetch: fetcher = globalThis.fetch, method, path, logSink, accept }) {
     const config = runtime ? artifactRuntimeConfigSchema.parse(runtime) : await readArtifactRuntimeConfig();
     if (!config)
         throw new ArtifactServerError(401, 'runtime_not_connected', 'Run seq-studio artifact dev to connect platform services, or use a hosted preview.');
     const token = headers.get(ARTIFACT_REQUEST_CONTEXT_HEADER);
-    const context = verifyArtifactRequestContext({ token, publicKeys: config.publicKeys, projectId: config.projectId, environment: config.environment, method, path });
+    let context;
+    if (accept && isExternalContextToken(token)) {
+        if (!method || !path)
+            throw new ArtifactServerError(401, 'invalid_request_context', 'An external request context is verified only against the route method and path');
+        context = verifyArtifactExternalContext({ token, publicKeys: config.publicKeys, projectId: config.projectId, environment: config.environment, method, path, accept });
+    }
+    else {
+        context = verifyArtifactRequestContext({ token, publicKeys: config.publicKeys, projectId: config.projectId, environment: config.environment, method, path });
+    }
     if (!token || (config.devSessionId && context.devSessionId !== config.devSessionId) ||
         (config.deploymentId && context.deploymentId !== config.deploymentId))
         throw new ArtifactServerError(401, 'invalid_runtime_session', 'Artifact request does not belong to this runtime');
@@ -37,29 +46,42 @@ export async function createArtifactServerClient({ headers, runtime, fetch: fetc
             throw new ArtifactServerError(401, 'runtime_changed', 'Artifact runtime disconnected or changed; reload the preview');
         return current;
     };
-    return buildClient({ context, token, getRuntime, fetcher, mode: 'user', logSink });
+    return buildClient({ context, principal: principalFromContext(context), token, getRuntime, fetcher, mode: 'user', logSink });
 }
 function buildClient(args) {
-    const { context, mode, logSink } = args;
-    const request = createBrokerTransport(args);
+    const { context, principal, mode, logSink } = args;
+    const log = createArtifactLogger({ context, sink: logSink });
+    const request = createBrokerTransport({ ...args, log });
     const json = async (operation, signal) => {
-        const response = await request(operation, signal);
+        const response = await request(operation, { signal });
+        // One read of the body: a step-up refusal keeps reason and maxAge, any other keeps Atlas's { detail, code }.
         if (!response.ok)
-            throw new ArtifactServerError(response.status, 'platform_request_failed', `Atlas rejected the ${operation.operation} request (${response.status})`);
+            throw await refusalFromResponse({ response, operation: operation.operation });
         return response.status === 204 ? undefined : response.json();
     };
     // storageClient retries replay-safe calls on 503 permissions_pending / storage_busy, so Storage
     // failures keep the envelope's status and code rather than collapsing into platform_request_failed.
     const storageJson = async (operation) => {
         const response = await request(operation);
-        if (!response.ok)
-            throw await storageApiError(response);
+        if (!response.ok) {
+            // A step-up refusal keeps its reason and maxAge; storageApiError reads the body, hence the clone.
+            throw (response.status === 401 ? await stepUpErrorFromResponse(response.clone()) : null) ?? await storageApiError(response);
+        }
         return response.status === 204 ? undefined : response.json();
     };
+    const evaluateFlags = async (flagNames) => {
+        const names = [...new Set(flagNames)];
+        const parsed = flagsResponseSchema.safeParse(await json(artifactServerRequestSchema.parse({ operation: 'flags', mode, names })));
+        if (!parsed.success)
+            throw new ArtifactServerError(502, 'invalid_response', 'Atlas returned a malformed flags response');
+        // A flag Atlas didn't answer reads off rather than undefined.
+        return Object.fromEntries(names.map(name => [name, parsed.data.flags[name] === true]));
+    };
     return {
         context,
+        principal,
         mode,
-        log: createArtifactLogger({ context, sink: logSink }),
+        log,
         api: createApiClient({ mode, request, json }),
         storage: storageClient({ request: (method, path, body) => storageJson(artifactServerRequestSchema.parse({ operation: 'storage', mode, method, path, body })) }),
         functions: {
@@ -68,18 +90,32 @@ function buildClient(args) {
                 return await json(artifactServerRequestSchema.parse({ operation: 'function', mode, id, params }));
             },
         },
-        orm: ({ namespace, manifest }) => ({
+        processes: createArtifactProcessesClient({ mode, json }),
+        flags: {
+            evaluate: evaluateFlags,
+            isEnabled: async (flagName) => (await evaluateFlags([flagName]))[flagName] === true,
+        },
+        audit: { record: (event) => recordAuditEvent({ request, mode, event }) },
+        orm: ({ namespace, manifest, jsonScalars }) => ({
             async execute(op, variables = {}) {
-                const hash = op.startsWith('sha256:') ? op : manifest.operations[op]?.hash;
+                const listed = op.startsWith('sha256:') ? Object.values(manifest.operations).find(entry => entry.hash === op) : manifest.operations[op];
+                const hash = op.startsWith('sha256:') ? op : listed?.hash;
                 if (!hash)
                     throw new ArtifactServerError(400, 'unknown_orm_operation', 'ORM operation is not in the generated manifest; run seq-studio orm generate');
-                const response = await request(artifactServerRequestSchema.parse({ operation: 'orm', mode, namespace, op: hash, variables }));
-                const parsed = graphqlResponseSchema.safeParse(await response.json().catch(() => null));
+                const response = await request(artifactServerRequestSchema.parse({ operation: 'orm', mode, namespace, op: hash, variables, ...(jsonScalars ? { jsonScalars } : {}) }), 
+                // Only an operation the manifest lists as a query is known to change nothing.
+                { replaySafe: listed?.kind === 'query' });
+                const body = await response.json().catch(() => null);
+                const stepUp = stepUpError(response.status, body);
+                if (stepUp)
+                    throw stepUp;
+                const parsed = graphqlResponseSchema.safeParse(body);
                 if (!parsed.success)
                     throw new OrmOperationError('Malformed Data API response', response.status, 'invalid_response');
                 const first = parsed.data.errors?.[0];
                 if (!response.ok || first)
                     throw new OrmOperationError(first?.message ?? `Data API request failed (${response.status})`, response.status, first?.extensions?.code ?? null, parsed.data.errors);
+                assertJsonScalarsAcknowledged({ requested: jsonScalars, acknowledged: response.headers.get(ORM_JSON_SCALARS_HEADER), status: response.status });
                 if (parsed.data.data === undefined || parsed.data.data === null)
                     throw new OrmOperationError('Malformed Data API response: missing data', response.status, 'invalid_response');
                 // Mirrors the generated ORM executor contract: consumers provide their generated result type.
@@ -94,13 +130,66 @@ function buildClient(args) {
         },
     };
 }
+/**
+ * Sends one audit event, and once more with the same event id when Atlas couldn't confirm delivery
+ * (503, or no answer): Atlas derives the stored event id from it and the request, so the audit sink
+ * keeps one copy whichever attempt landed.
+ */
+async function recordAuditEvent({ request, mode, event }) {
+    const { eventId = randomUUID(), ...rest } = event;
+    const operation = artifactServerRequestSchema.parse({ operation: 'audit', mode, eventId, ...rest });
+    let failure;
+    for (let attempt = 0; attempt < 2; attempt++) {
+        let response;
+        try {
+            response = await request(operation);
+        }
+        catch (error) {
+            // A local refusal (expired context, oversized body) won't change on a retry.
+            if (error instanceof ArtifactServerError)
+                throw error;
+            failure = new ArtifactServerError(503, 'audit_unavailable', 'Atlas did not answer the audit request');
+            continue;
+        }
+        // A step-up refusal is the broker's answer, not a lost delivery: never resent.
+        const stepUp = await stepUpErrorFromResponse(response);
+        if (stepUp)
+            throw stepUp;
+        if (!response.bodyUsed)
+            await response.body?.cancel();
+        if (response.ok)
+            return;
+        failure = new ArtifactServerError(response.status, response.status === 503 ? 'audit_unavailable' : 'platform_request_failed', `Atlas rejected the audit request (${response.status})`);
+        if (response.status !== 503)
+            break;
+    }
+    throw failure;
+}
 /** Mirrors createStorageClient: Storage's `{ error: { code, message } }` envelope survives the broker. */
 async function storageApiError(response) {
     const envelope = storageErrorSchema.safeParse(await response.json().catch(() => undefined));
     return new StorageApiError(response.status, envelope.success ? envelope.data.error.code : 'request_failed', envelope.success ? envelope.data.error.message : `Storage request failed (${response.status})`);
 }
-function createBrokerTransport({ context, token, getRuntime, fetcher }) {
-    return async (input, signal) => {
+/**
+ * Broker operations that change nothing in Atlas. An ORM call's caller decides from its manifest
+ * kind; function invokes and process starts can act, and audit delivery resends on its own terms.
+ */
+function isReadOperation(operation) {
+    switch (operation.operation) {
+        case 'api':
+        case 'storage':
+            return operation.method === 'GET' || operation.method === 'HEAD';
+        case 'flags':
+            return true;
+        default:
+            return false;
+    }
+}
+function createBrokerTransport({ context, principal, token, getRuntime, fetcher, log }) {
+    const send = async (input, signal) => {
+        // The one choke point for every broker operation: an external caller never acts as a user.
+        if (input.mode === 'user' && principal.kind === 'external')
+            throw new ArtifactPrincipalError('external_requires_service');
         if (context.exp <= Math.floor(Date.now() / 1000))
             throw new ArtifactServerError(401, 'request_context_expired', 'Artifact request context expired; begin a new request');
         const operation = artifactServerRequestSchema.parse(input);
@@ -124,36 +213,26 @@ function createBrokerTransport({ context, token, getRuntime, fetcher }) {
             signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(60_000)]) : AbortSignal.timeout(60_000),
         });
     };
-}
-function createApiClient({ mode, request, json }) {
-    const operation = (path, options = {}) => artifactServerRequestSchema.parse({ operation: 'api', mode, method: options.method ?? 'GET', path, body: options.body });
-    const fetchResponse = (path, options = {}) => request(operation(path, options), options.signal);
-    const typedJson = async (path, options = {}) => {
-        // Explicit caller result types match the existing browser SDK; the server validates endpoint schemas.
-        return await json(operation(path, options), options.signal);
-    };
-    return {
-        request: fetchResponse,
-        async fetch(path, options = {}) {
-            const response = await fetchResponse(path, options);
-            const contentType = response.headers.get('content-type') ?? '';
-            const body = response.status === 204 ? undefined : contentType.includes('json') ? await response.json() : await response.arrayBuffer();
-            // The caller declares the endpoint's response type, consistent with SequenceApiFetchResponse.
-            return { ok: response.ok, status: response.status, body: body, headers: Object.fromEntries(responseHeaders.flatMap(key => {
-                    const value = response.headers.get(key);
-                    return value === null ? [] : [[key, value]];
-                })) };
-        },
-        async stream(path, options = {}) {
-            const response = await fetchResponse(path, options);
-            if (!response.ok || !response.body)
-                throw new ArtifactServerError(response.status, 'stream_unavailable', 'Atlas did not return a readable response');
-            return response.body;
-        },
-        get: (path) => typedJson(path),
-        post: (path, body) => typedJson(path, { method: 'POST', body }),
-        put: (path, body) => typedJson(path, { method: 'PUT', body }),
-        patch: (path, body) => typedJson(path, { method: 'PATCH', body }),
-        delete: (path, body) => typedJson(path, { method: 'DELETE', body }),
+    /**
+     * Sends a read again when its connection to Atlas failed before Atlas answered: such failures
+     * clear within moments, and a read changes nothing by arriving twice. A write is never sent
+     * again, because a reset can come after Atlas acted on it. A response, whatever its status, is
+     * Atlas's answer and is returned as is.
+     */
+    return async (input, { signal, replaySafe = isReadOperation(input) } = {}) => {
+        for (let attempt = 1;; attempt++) {
+            try {
+                return await send(input, signal);
+            }
+            catch (error) {
+                const code = replaySafe && attempt < reconnect.attempts ? transientConnectionCode(error) : null;
+                if (code === null)
+                    throw error;
+                log.warn('broker.reconnect', { operationId: input.operation, errorCode: code, count: attempt });
+                // Equal jitter, so the reads of one burst don't all reconnect at the same moment.
+                const ceiling = reconnect.baseDelayMs * 2 ** (attempt - 1);
+                await pause({ ms: ceiling / 2 + (Math.random() * ceiling) / 2, signal });
+            }
+        }
     };
 }

package/dist/server/connection-retry.d.ts

@@ -0,0 +1,12 @@
+/** Recognising a lost connection to Atlas, and waiting before a broker read is resent. */
+/**
+ * The transient connection code behind a failed fetch, or null. Node's fetch throws
+ * `TypeError: fetch failed` with the socket error as its cause. When every address of the host
+ * failed to connect, that cause is an AggregateError carrying the first address's code.
+ */
+export declare function transientConnectionCode(error: unknown): string | null;
+/** Resolves after `ms`, or rejects with the caller's abort reason as soon as it aborts. */
+export declare function pause({ ms, signal }: {
+    ms: number;
+    signal?: AbortSignal;
+}): Promise<void>;