@sequenceholdings/artifact-studio 0.4.0 → 0.5.0

package/dist/server/client.js

@@ -1,26 +1,31 @@
+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 { ArtifactServerError, platformRequestError } from './errors.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 { 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';
-    }
-}
+export { ArtifactServerError } 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 flagsResponseSchema = z.object({ flags: z.record(z.string(), z.boolean()) });
 const responseHeaders = ['content-type', 'content-disposition', 'content-length', 'retry-after'];
 const maxBodyBytes = 1024 * 1024;
+/** 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 };
+/**
+ * Socket and DNS errors after which Atlas never answered, and which clear by themselves: the
+ * route to Atlas was briefly gone (an egress NAT out of ports drops new connections, which Node
+ * reports as EHOSTUNREACH), Atlas's edge refused or reset the connection, or a lookup failed
+ * transiently. Timeouts aren't here: a call that waited out its timeout shouldn't wait it out again.
+ */
+const transientConnectionCodes = new Set(['ECONNREFUSED', 'ECONNRESET', 'EHOSTUNREACH', 'ENETUNREACH', 'EADDRNOTAVAIL', 'EPIPE', 'EAI_AGAIN', 'UND_ERR_SOCKET']);
 /** One instance per incoming request. Never cache it at module scope. */
 export async function createArtifactServerClient({ headers, runtime, fetch: fetcher = globalThis.fetch, method, path, logSink }) {
     const config = runtime ? artifactRuntimeConfigSchema.parse(runtime) : await readArtifactRuntimeConfig();
@@ -41,11 +46,12 @@ export async function createArtifactServerClient({ headers, runtime, fetch: fetc
 }
 function buildClient(args) {
     const { context, mode, logSink } = args;
-    const request = createBrokerTransport(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 });
         if (!response.ok)
-            throw new ArtifactServerError(response.status, 'platform_request_failed', `Atlas rejected the ${operation.operation} request (${response.status})`);
+            throw await platformRequestError({ response, operation: operation.operation });
         return response.status === 204 ? undefined : response.json();
     };
     // storageClient retries replay-safe calls on 503 permissions_pending / storage_busy, so Storage
@@ -56,10 +62,18 @@ function buildClient(args) {
             throw 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,
         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 +82,28 @@ 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 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 parsed = graphqlResponseSchema.safeParse(await response.json().catch(() => null));
                 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 +118,90 @@ 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;
+        }
+        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;
+    }
+}
+/**
+ * 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.
+ */
+function transientConnectionCode(error) {
+    let current = error;
+    for (let depth = 0; depth < 8 && typeof current === 'object' && current !== null; depth++) {
+        if ('code' in current && typeof current.code === 'string' && transientConnectionCodes.has(current.code))
+            return current.code;
+        current = 'cause' in current ? current.cause : undefined;
+    }
+    return null;
+}
+/** Resolves after `ms`, or rejects with the caller's abort reason as soon as it aborts. */
+function pause({ ms, signal }) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason);
+            return;
+        }
+        const aborted = () => {
+            clearTimeout(timer);
+            reject(signal?.reason);
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', aborted);
+            resolve();
+        }, ms);
+        signal?.addEventListener('abort', aborted, { once: true });
+    });
+}
+function createBrokerTransport({ context, token, getRuntime, fetcher, log }) {
+    const send = async (input, signal) => {
         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,10 +225,32 @@ function createBrokerTransport({ context, token, getRuntime, fetcher }) {
             signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(60_000)]) : AbortSignal.timeout(60_000),
         });
     };
+    /**
+     * 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 });
+            }
+        }
+    };
 }
 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 fetchResponse = (path, options = {}) => request(operation(path, options), { signal: 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);

package/dist/server/errors.d.ts

@@ -0,0 +1,26 @@
+/**
+ * What Atlas's error envelope said about a refusal, when the response carried one. Atlas routes
+ * answer `{ detail, code? }`: `detail` is the human-readable reason, `code` the route's machine
+ * code when it has one (`RUN_TERMINAL`, `EDGE_ID_MISMATCH`, `WORKFLOW_NOT_RUNNING`, …), so an
+ * application can branch on a refusal the way a caller of the route itself would.
+ */
+export interface ArtifactAtlasRefusal {
+    code: string | null;
+    detail: string | null;
+}
+export declare class ArtifactServerError extends Error {
+    readonly status: number;
+    readonly code: string;
+    /** Atlas's own account of the refusal; both null when the response had no readable envelope. */
+    readonly atlas: ArtifactAtlasRefusal;
+    constructor(status: number, code: string, message: string, atlas?: ArtifactAtlasRefusal);
+}
+/**
+ * A refused broker call, keeping what Atlas said: the message carries the route's `detail`
+ * and `error.atlas` its machine `code`, so a consumer can branch on a Lattice refusal
+ * (`EDGE_ID_MISMATCH`, `WORKFLOW_NOT_RUNNING`, …) the way a caller of the route itself would.
+ */
+export declare function platformRequestError({ response, operation }: {
+    response: Response;
+    operation: string;
+}): Promise<ArtifactServerError>;

package/dist/server/errors.js

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+const NO_REFUSAL = { code: null, detail: null };
+export class ArtifactServerError extends Error {
+    status;
+    code;
+    /** Atlas's own account of the refusal; both null when the response had no readable envelope. */
+    atlas;
+    constructor(status, code, message, atlas = NO_REFUSAL) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = 'ArtifactServerError';
+        this.atlas = atlas;
+    }
+}
+/** Atlas answers a refusal as `{ detail, code? }`; anything else (a proxy page, an empty body) reads as no envelope. */
+const atlasRefusalSchema = z.object({ detail: z.string().optional(), code: z.string().optional() });
+/**
+ * A refused broker call, keeping what Atlas said: the message carries the route's `detail`
+ * and `error.atlas` its machine `code`, so a consumer can branch on a Lattice refusal
+ * (`EDGE_ID_MISMATCH`, `WORKFLOW_NOT_RUNNING`, …) the way a caller of the route itself would.
+ */
+export async function platformRequestError({ response, operation }) {
+    const envelope = atlasRefusalSchema.safeParse(await response.json().catch(() => undefined));
+    const detail = envelope.success ? envelope.data.detail ?? null : null;
+    const code = envelope.success ? envelope.data.code ?? null : null;
+    const message = `Atlas rejected the ${operation} request (${response.status})${detail ? `: ${detail}` : ''}`;
+    return new ArtifactServerError(response.status, 'platform_request_failed', message, { code, detail });
+}

package/dist/server/managed-server-path.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Exact origin-relative path a Lattice `managed_server` node may POST.
+ * No wildcards, query strings, or traversal. Keep this identical to
+ * `atlas/lattice/src/define/managed-server-path.ts`.
+ */
+export declare function isManagedServerInvokePath(path: string): boolean;

package/dist/server/managed-server-path.js

@@ -0,0 +1,14 @@
+/**
+ * Exact origin-relative path a Lattice `managed_server` node may POST.
+ * No wildcards, query strings, or traversal. Keep this identical to
+ * `atlas/lattice/src/define/managed-server-path.ts`.
+ */
+export function isManagedServerInvokePath(path) {
+    if (path.length < 2 || path.length > 512 || !path.startsWith('/') || path.includes('//')) {
+        return false;
+    }
+    if (/[?#\\]/.test(path))
+        return false;
+    const segments = path.slice(1).split('/');
+    return segments.every((segment) => segment !== '.' && segment !== '..' && /^[A-Za-z0-9._~-]+$/.test(segment));
+}

package/dist/server/processes.d.ts

@@ -0,0 +1,290 @@
+import { type ArtifactProcessPrincipalType, type ArtifactProcessRunStatus, type ArtifactProcessTaskView, type ArtifactServerMode, type ArtifactServerRequest } from './broker-contract.js';
+/** A run of a process declared under `server.capabilities.processes.start`. */
+export interface ArtifactProcessStart {
+    process: string;
+    /** Idempotency key: starting the same run id again returns the existing run. */
+    runId?: string;
+    title?: string;
+    entity?: {
+        type: string;
+        id: string;
+    };
+    /** The run's input, readable by the process as `ctx.run.metadata`. */
+    metadata?: Record<string, unknown>;
+    /**
+     * Who works each human node of this run, keyed by node id (`execute`) or by a path into a
+     * nested subprocess (`application::qa_review`): the node's advancers when the run reaches it,
+     * over the process's own defaults. Users are Auth0 subjects, groups are chat group ids; Atlas
+     * refuses principals it has tombstoned. Reassign a parked step later with `assign`.
+     */
+    assignments?: Record<string, ArtifactProcessPrincipals>;
+}
+export interface ArtifactProcessRun {
+    run_id: string;
+    process_id: string;
+    process_version: string;
+    status: 'pending' | 'existing';
+    idempotent_replay: boolean;
+    /**
+     * created: a new run was dispatched · replayed: an undispatched run with this id was dispatched ·
+     * existing: the run already ran or is running, so nothing was dispatched · unclaimed: a run with
+     * this id exists and was not taken over · queued: the process is at its concurrency limit; the run
+     * is `pending` and starts when a slot frees.
+     */
+    outcome: 'created' | 'replayed' | 'existing' | 'unclaimed' | 'queued';
+}
+/** Which runs of a process declared under `server.capabilities.processes.read` to list. */
+export interface ArtifactProcessRunsQuery {
+    process: string;
+    status?: ArtifactProcessRunStatus;
+    /** Runs about one entity type, or one entity. */
+    entity?: {
+        type: string;
+        id?: string;
+    };
+    /** Newest first; Lattice caps a page at ARTIFACT_PROCESS_RUNS_LIMIT and defaults to 50. */
+    limit?: number;
+    /** Soft-archived runs only, instead of the default active ones. */
+    archived?: boolean;
+}
+/**
+ * The stable fields of a Lattice run row as the read API serves it (Atlas may serve more).
+ * `metadata` (the run's input) is redacted on read for every viewer, so an application keeps the
+ * data it needs back in its own ORM namespace. Timestamps are ISO strings.
+ */
+export interface ArtifactProcessRunRecord {
+    id: string;
+    processId: string;
+    processVersion: string;
+    status: ArtifactProcessRunStatus;
+    title: string | null;
+    entityType: string | null;
+    entityId: string | null;
+    startNodeId: string | null;
+    startedBy: string | null;
+    startedAt: string;
+    completedAt: string | null;
+    archivedAt: string | null;
+    error: string | null;
+    output: unknown;
+    /** Node-produced run state; its access boundary is the run's Viewer relation. */
+    state: Record<string, unknown>;
+}
+/** The stable fields of one step attempt of a run. Wait-token credentials and runner plumbing are redacted. */
+export interface ArtifactProcessStepRecord {
+    id: string;
+    runId: string;
+    nodeId: string;
+    kind: string;
+    attempt: number;
+    status: string;
+    startedAt: string;
+    completedAt: string | null;
+    input: unknown;
+    output: unknown;
+    error: string | null;
+    nextEdgeId: string | null;
+    waitTokenId: string | null;
+}
+/** The collapsed lifecycle of one node: its latest attempt with finished-branch events applied. */
+export type ArtifactProcessNodeState = 'pending' | 'running' | 'completed' | 'failed' | 'skipped' | 'cancelled' | 'timed_out';
+/** One run as `GET /api/lattice/runs/[runId]` serves it. */
+export interface ArtifactProcessRunSnapshot {
+    run: ArtifactProcessRunRecord;
+    /** Raw step rows, one per attempt / fan-out branch. */
+    steps: ArtifactProcessStepRecord[];
+    states: Record<string, ArtifactProcessNodeState>;
+    /** Pass to the run's event stream as `?since=` to receive everything after this snapshot. */
+    event_cursor: string | null;
+}
+/** Which applied version of a process declared under `processes.read` to describe. */
+export interface ArtifactProcessDescribeQuery {
+    process: string;
+    /** A run's `processVersion`, to see the template that run was started from. Default: the active version. */
+    version?: string;
+}
+export interface ArtifactProcessEdge {
+    id: string;
+    /** The node this edge routes to. */
+    to: string;
+}
+/** A static Artifact Studio (or uri) reference a human node renders as its work surface. */
+export interface ArtifactProcessArtifactRef {
+    provider: string;
+    artifact_id: string;
+    project: string | null;
+    role: string | null;
+    uri: string | null;
+    metadata: Record<string, unknown>;
+}
+export interface ArtifactProcessNodeBase {
+    id: string;
+    kind: 'automation' | 'agent' | 'human' | 'parallel' | 'subprocess' | 'delay' | 'managed_function' | 'managed_server' | (string & {});
+    title: string;
+    description: string | null;
+    outgoing_edges: ArtifactProcessEdge[];
+}
+/** A human node as the people who work it see it; the engine's own node configuration is not part of this. */
+export interface ArtifactProcessHumanNode extends ArtifactProcessNodeBase {
+    kind: 'human';
+    /** The manual advance choices: `outgoing_edges` less any dedicated timeout route. */
+    advance_edges: ArtifactProcessEdge[];
+    /** The author's label for the single completion action, or null for the surface's default. */
+    complete_label: string | null;
+    /** The author's app-facing metadata (`metadata` on `defineHumanNode`): surface hints, form fields, … */
+    metadata: Record<string, unknown>;
+    comments_enabled: boolean;
+    /** Static refs only; refs a mapper resolves per run are not listed. */
+    artifact_refs: ArtifactProcessArtifactRef[];
+}
+export type ArtifactProcessNode = ArtifactProcessNodeBase | ArtifactProcessHumanNode;
+/**
+ * One applied version of a process: the template its runs are filled in from. Automation, agent,
+ * managed-function, subprocess and parallel internals are the process's own and are never served here.
+ */
+export interface ArtifactProcessDefinition {
+    id: string;
+    name: string;
+    description: string | null;
+    version: string;
+    bundle_hash: string;
+    /** Process-level switch: `processes.start` is refused while set. */
+    new_runs_disabled: boolean;
+    start_node_id: string;
+    /** JSON Schema for the `metadata` a start accepts, when the author declared one. */
+    input_schema: Record<string, unknown> | null;
+    tags: string[];
+    /** Every node, flattened: a human node inside a parallel branch is listed beside the top-level nodes. */
+    nodes: ArtifactProcessNode[];
+}
+/** Which of the user's human steps to list, across processes declared under `processes.read`. */
+export interface ArtifactProcessTasksQuery {
+    /** A subset of the declared processes; default every declared one. */
+    processes?: string[];
+    /** `active` (default): parked and waiting on the user. `completed`: steps they were assigned that are done. */
+    view?: ArtifactProcessTaskView;
+    /** Newest first; Lattice caps a page at ARTIFACT_PROCESS_TASKS_LIMIT and defaults to 100. */
+    limit?: number;
+}
+/** One human step of the user's, with what the node's template says about working it. Timestamps are ISO strings. */
+export interface ArtifactProcessTask {
+    step_id: string;
+    run_id: string;
+    node_id: string;
+    process_id: string;
+    process_version: string;
+    process_name: string | null;
+    title: string;
+    description: string | null;
+    entity: {
+        type: string;
+        id: string;
+    } | null;
+    run_title: string | null;
+    advance_edges: ArtifactProcessEdge[];
+    complete_label: string | null;
+    metadata: Record<string, unknown>;
+    /** How the step reached the user: assigned to them, to one of their groups, or reassigned by them. */
+    assigned_via: 'user' | 'group' | 'reassigned';
+    started_at: string;
+    due_at: string | null;
+    /** Completed view only. */
+    completed_at?: string | null;
+    /** Completed view only: `completed`, or `timed_out` for a step that expired instead of being worked. */
+    step_status?: string;
+    /** Completed view only: the run's status at read time. */
+    run_status?: string;
+    /** The node's template could not be loaded; identity fields are still exact. */
+    template_unavailable?: boolean;
+}
+/** Completing one of the user's parked human steps on a run of a process declared under `processes.act`. */
+export interface ArtifactProcessAdvance {
+    runId: string;
+    /** Which parked step; required when a parallel block has several human branches parked at once. */
+    stepId?: string;
+    /** One of the node's `advance_edges`; omitted on a terminal human node. */
+    edgeId?: string;
+    /** The step's output: the node's form fields, as the process reads them. */
+    payload?: Record<string, unknown>;
+}
+export interface ArtifactProcessAdvanceResult {
+    step_id: string;
+    node_id: string;
+    edge_id: string | null;
+    /** The step had already been completed with this decision; nothing was re-run. */
+    idempotent_replay: boolean;
+}
+/** Users (Auth0 `sub`) and chat groups (group id) to name in an assignment or a share. */
+export interface ArtifactProcessPrincipals {
+    users?: string[];
+    groups?: string[];
+}
+/** Reassigning a parked human step: the step's advancers become exactly these principals. */
+export interface ArtifactProcessAssign extends ArtifactProcessPrincipals {
+    runId: string;
+    stepId: string;
+}
+export interface ArtifactProcessAssignResult {
+    step_id: string;
+    node_id: string;
+    assigned: {
+        users: string[];
+        groups: string[];
+    };
+}
+/** The explicit `viewer` grants stored on a run; access derived from the process or a step is not listed. */
+export interface ArtifactProcessRunViewers {
+    run_id: string;
+    users: string[];
+    groups: string[];
+}
+export interface ArtifactProcessRunViewerChange extends ArtifactProcessPrincipals {
+    runId: string;
+}
+export interface ArtifactProcessPrincipalSearch {
+    /** Empty browses the first `limit` users; 1–2 characters match groups only; 3+ search the directory. */
+    q: string;
+    /** Default both. */
+    types?: ArtifactProcessPrincipalType[];
+    /** Users and groups together; Lattice caps at ARTIFACT_PROCESS_PRINCIPAL_SEARCH_LIMIT, default 20. */
+    limit?: number;
+}
+/** A principal the user may name. `id` is the value `assign` and the viewer grants consume. */
+export interface ArtifactProcessPrincipal {
+    type: ArtifactProcessPrincipalType;
+    id: string;
+    name: string;
+    email?: string;
+    picture?: string;
+    /** Groups: active members. */
+    memberCount?: number;
+}
+export interface ArtifactServerProcesses {
+    /** Start a run of a process declared under `processes.start`; the user's Invoker grant decides. */
+    start(input: ArtifactProcessStart): Promise<ArtifactProcessRun>;
+    /** List the runs of a process declared under `processes.read` that the user may view. */
+    listRuns(query: ArtifactProcessRunsQuery): Promise<ArtifactProcessRunRecord[]>;
+    /** Read one run of a process declared under `processes.read`; the user's Viewer relation on the run decides. */
+    getRun(runId: string): Promise<ArtifactProcessRunSnapshot>;
+    /** Describe a process declared under `processes.read`; the user's Viewer relation on the process decides. */
+    describe(query: ArtifactProcessDescribeQuery): Promise<ArtifactProcessDefinition>;
+    /** The user's own human steps across processes declared under `processes.read`. */
+    listTasks(query?: ArtifactProcessTasksQuery): Promise<ArtifactProcessTask[]>;
+    /** Complete a parked human step on a run of a process declared under `processes.act`; the user's own `advancer` grant decides. */
+    advance(input: ArtifactProcessAdvance): Promise<ArtifactProcessAdvanceResult>;
+    /** Reassign a parked human step; the user's `owner` relation on the run decides. */
+    assign(input: ArtifactProcessAssign): Promise<ArtifactProcessAssignResult>;
+    /** The explicit viewer grants on a run of a process declared under `processes.act`; owner-gated. */
+    listViewers(runId: string): Promise<ArtifactProcessRunViewers>;
+    /** Share a run with users and groups; owner-gated, additive, idempotent. */
+    grantViewers(input: ArtifactProcessRunViewerChange): Promise<ArtifactProcessRunViewers>;
+    /** Take a share back; owner-gated, idempotent. Returns the grants that remain. */
+    revokeViewers(input: ArtifactProcessRunViewerChange): Promise<ArtifactProcessRunViewers>;
+    /** Users in the user's own tenant and groups they may see, to name in `assign` or a share. */
+    searchPrincipals(query: ArtifactProcessPrincipalSearch): Promise<ArtifactProcessPrincipal[]>;
+}
+/** `client.processes`: Lattice through the broker's typed `lattice*` operations. Atlas owns validation and redaction. */
+export declare function createArtifactProcessesClient({ mode, json }: {
+    mode: ArtifactServerMode;
+    json: (operation: ArtifactServerRequest) => Promise<unknown>;
+}): ArtifactServerProcesses;

package/dist/server/processes.js

@@ -0,0 +1,56 @@
+import { artifactServerRequestSchema, } from './broker-contract.js';
+import { ArtifactServerError } from './errors.js';
+/** `client.processes`: Lattice through the broker's typed `lattice*` operations. Atlas owns validation and redaction. */
+export function createArtifactProcessesClient({ mode, json }) {
+    return {
+        start: async ({ process, ...run }) => {
+            // Atlas returns the started run's identifiers; the shape is the Lattice start response.
+            return await json(artifactServerRequestSchema.parse({ operation: 'lattice', mode, process, ...run }));
+        },
+        listRuns: async (query) => {
+            // The Lattice list response: `{ runs }`, already filtered to what the user may view.
+            const body = await json(artifactServerRequestSchema.parse({ operation: 'lattice_runs', mode, ...query }));
+            if (!Array.isArray(body?.runs))
+                throw new ArtifactServerError(502, 'malformed_response', 'Atlas returned a malformed run list');
+            return body.runs;
+        },
+        getRun: async (runId) => {
+            // The Lattice run-detail response; Atlas owns redaction and node-state derivation.
+            return await json(artifactServerRequestSchema.parse({ operation: 'lattice_run', mode, runId }));
+        },
+        describe: async (query) => {
+            // Atlas projects the applied bundle; engine internals never leave it.
+            return await json(artifactServerRequestSchema.parse({ operation: 'lattice_process', mode, ...query }));
+        },
+        listTasks: async (query = {}) => {
+            // The Lattice inbox response shape: `{ items }`, already the user's own.
+            const body = await json(artifactServerRequestSchema.parse({ operation: 'lattice_tasks', mode, ...query }));
+            if (!Array.isArray(body?.items))
+                throw new ArtifactServerError(502, 'malformed_response', 'Atlas returned a malformed task list');
+            return body.items;
+        },
+        advance: async (input) => {
+            // The Lattice advance response; Atlas owns the step resolution, the ACL and the walk.
+            return await json(artifactServerRequestSchema.parse({ operation: 'lattice_advance', mode, ...input }));
+        },
+        assign: async (input) => {
+            return await json(artifactServerRequestSchema.parse({ operation: 'lattice_assign', mode, ...input }));
+        },
+        listViewers: async (runId) => {
+            return await json(artifactServerRequestSchema.parse({ operation: 'lattice_viewers', mode, runId }));
+        },
+        grantViewers: async (input) => {
+            return await json(artifactServerRequestSchema.parse({ operation: 'lattice_viewer_grant', mode, ...input }));
+        },
+        revokeViewers: async (input) => {
+            return await json(artifactServerRequestSchema.parse({ operation: 'lattice_viewer_revoke', mode, ...input }));
+        },
+        searchPrincipals: async (query) => {
+            // The Lattice picker response shape: `{ principals }`, already scoped to the user's tenant.
+            const body = await json(artifactServerRequestSchema.parse({ operation: 'lattice_principals', mode, ...query }));
+            if (!Array.isArray(body?.principals))
+                throw new ArtifactServerError(502, 'malformed_response', 'Atlas returned a malformed principal list');
+            return body.principals;
+        },
+    };
+}