@sequenceholdings/artifact-studio 0.6.4 → 0.6.6

package/dist/server/broker-contract.js

@@ -31,6 +31,12 @@ const latticeVersion = z.string().min(1).max(128).regex(/^[A-Za-z0-9._-]+$/);
 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;
+/** A run page can filter to at most this many entities of one type. */
+export const ARTIFACT_PROCESS_RUN_ENTITIES_LIMIT = 500;
+/** A run share adds collaborators to at most this many explicitly assigned human nodes. */
+export const ARTIFACT_PROCESS_SHARE_NODES_LIMIT = 100;
+/** An owner may list at most this many sharing authorities per page. */
+export const ARTIFACT_PROCESS_SHARING_AUTHORITIES_LIMIT = 50;
 /** A run-events read returns at most this many events per call, as the run's stream drains them. */
 export const ARTIFACT_PROCESS_RUN_EVENTS_LIMIT = 1000;
 /** Which of the user's human steps to list: parked and waiting on them, or already done. */
@@ -65,8 +71,14 @@ const assignmentNodeKey = z.string().min(1).max(255).regex(/^[A-Za-z0-9._-]+(?::
 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);
+const runPageEntity = z.object({
+    type: entityRef, id: entityRef.optional(),
+    ids: z.array(entityRef).min(1).max(ARTIFACT_PROCESS_RUN_ENTITIES_LIMIT).optional(),
+}).strict().refine(value => value.id === undefined || value.ids === undefined, 'Name one entity id or a set of ids, not both');
 // Unleash feature names are URL-safe.
 const flagName = z.string().min(1).max(255).regex(/^[A-Za-z0-9._~-]+$/);
+/** The data plane's own idempotency-key rule (`orm-data-plane/src/runtime.ts`), so a key the SDK sends is one it accepts. */
+export const artifactOrmIdempotencyKeySchema = z.string().regex(/^[A-Za-z0-9._:-]{1,128}$/);
 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 = [
@@ -97,10 +109,13 @@ const auditEvent = {
 export const artifactServerRequestSchema = z.discriminatedUnion('operation', [
     z.object({ operation: z.literal('api'), mode, method, path, body: 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.
+    // the data plane's own header and passes the acknowledgment back. idempotencyKey names one
+    // logical mutation so a retry returns its receipt; Atlas forwards it in the data plane body
+    // (re-scoped per caller for external principals) and the data plane refuses it on a query.
     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(),
+        idempotencyKey: artifactOrmIdempotencyKeySchema.optional(),
     }).strict(),
     z.object({ operation: z.literal('storage'), mode, method, path: path.refine(value => {
             const pathname = value.split('?')[0];
@@ -128,6 +143,17 @@ export const artifactServerRequestSchema = z.discriminatedUnion('operation', [
         limit: z.number().int().min(1).max(ARTIFACT_PROCESS_RUNS_LIMIT).optional(),
         archived: z.boolean().optional(),
     }).strict(),
+    // Keyset pagination selects a bounded window from the principal's authorized runs.
+    // Continuation is returned only when another visible run exists; denied rows do not expose a cursor.
+    z.object({
+        operation: z.literal('lattice_runs_page'), mode, process: latticeId,
+        statuses: z.array(z.enum(ARTIFACT_PROCESS_RUN_STATUSES)).min(1).max(ARTIFACT_PROCESS_RUN_STATUSES.length)
+            .refine(value => new Set(value).size === value.length, 'Statuses must be unique').optional(),
+        entity: runPageEntity.optional(),
+        limit: z.number().int().min(1).max(ARTIFACT_PROCESS_RUNS_LIMIT).optional(),
+        cursor: z.string().min(1).max(2048).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(),
@@ -162,6 +188,22 @@ export const artifactServerRequestSchema = z.discriminatedUnion('operation', [
     // 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),
+    // Adds collaborators to selected, explicitly assigned human nodes and grants run viewing.
+    // Existing assignees remain. Onward sharing is explicit and scoped to the admitted application.
+    z.object({
+        operation: z.literal('lattice_share_run'), mode, runId: latticeId,
+        nodeIds: z.array(z.string().min(1).max(255).refine(value => !value.includes('::'), 'Node ids cannot contain the reserved :: separator'))
+            .min(1).max(ARTIFACT_PROCESS_SHARE_NODES_LIMIT),
+        ...principalSet,
+        delegateSharing: z.object({ audience: z.literal('current_app') }).strict().optional(),
+    }).strict().refine(namesPrincipals, PRINCIPAL_SET_MESSAGE)
+        .refine(value => !value.delegateSharing || ((value.users?.length ?? 0) > 0 && (value.groups?.length ?? 0) === 0), 'Delegated sharing names individual users only'),
+    z.object({
+        operation: z.literal('lattice_sharing_authorities'), mode, runId: latticeId,
+        limit: z.number().int().min(1).max(ARTIFACT_PROCESS_SHARING_AUTHORITIES_LIMIT).optional(),
+        cursor: z.uuid().optional(),
+    }).strict(),
+    z.object({ operation: z.literal('lattice_sharing_authority_revoke'), mode, runId: latticeId, authorityId: z.uuid() }).strict(),
     // Cancels a run of a process declared under `processes.act`, with its forked lineage, as
     // `POST /api/lattice/runs/[runId]/cancel` does. The user's Invoker relation on the run decides.
     z.object({ operation: z.literal('lattice_cancel'), mode, runId: latticeId }).strict(),

package/dist/server/client.js

@@ -2,7 +2,7 @@ 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 { artifactOrmIdempotencyKeySchema, 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';
@@ -24,6 +24,7 @@ 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 };
 export async function createArtifactServerClient({ headers, runtime, fetch: fetcher = globalThis.fetch, method, path, logSink, accept }) {
+    // An explicit runtime is re-parsed, so it never carries the development-lease marker.
     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.');
@@ -32,7 +33,11 @@ export async function createArtifactServerClient({ headers, runtime, fetch: fetc
     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 });
+        context = verifyArtifactExternalContext({
+            token, publicKeys: config.publicKeys, projectId: config.projectId, environment: config.environment, method, path, accept,
+            // A development context only under a development lease (never a hosted or explicit runtime).
+            developmentSessionId: config.development === true ? config.devSessionId : undefined,
+        });
     }
     else {
         context = verifyArtifactRequestContext({ token, publicKeys: config.publicKeys, projectId: config.projectId, environment: config.environment, method, path });
@@ -42,7 +47,7 @@ export async function createArtifactServerClient({ headers, runtime, fetch: fetc
         throw new ArtifactServerError(401, 'invalid_runtime_session', 'Artifact request does not belong to this runtime');
     const getRuntime = async () => {
         const current = runtime ? config : await readArtifactRuntimeConfig();
-        if (!current || current.projectId !== config.projectId || current.environment !== config.environment || current.atlasUrl !== config.atlasUrl || current.devSessionId !== config.devSessionId || current.deploymentId !== config.deploymentId)
+        if (!current || current.projectId !== config.projectId || current.environment !== config.environment || current.atlasUrl !== config.atlasUrl || current.devSessionId !== config.devSessionId || current.deploymentId !== config.deploymentId || current.development !== config.development)
             throw new ArtifactServerError(401, 'runtime_changed', 'Artifact runtime disconnected or changed; reload the preview');
         return current;
     };
@@ -97,14 +102,9 @@ function buildClient(args) {
         },
         audit: { record: (event) => recordAuditEvent({ request, mode, event }) },
         orm: ({ namespace, manifest, jsonScalars }) => ({
-            async execute(op, variables = {}) {
-                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, ...(jsonScalars ? { jsonScalars } : {}) }), 
-                // Only an operation the manifest lists as a query is known to change nothing.
-                { replaySafe: listed?.kind === 'query' });
+            async execute(op, variables = {}, options = {}) {
+                const { operation, replaySafe } = ormOperationRequest({ mode, namespace, manifest, op, variables, jsonScalars, idempotencyKey: options.idempotencyKey });
+                const response = await request(operation, { replaySafe });
                 const body = await response.json().catch(() => null);
                 const stepUp = stepUpError(response.status, body);
                 if (stepUp)
@@ -130,6 +130,30 @@ function buildClient(args) {
         },
     };
 }
+/**
+ * The broker `orm` request for one persisted operation, and whether a lost connection may resend
+ * it: an operation the manifest lists as a query changes nothing, and a mutation sent with an
+ * idempotency key is answered from its stored receipt when it arrives twice (the same body carries
+ * the same key and fingerprint).
+ */
+function ormOperationRequest({ mode, namespace, manifest, op, variables, jsonScalars, idempotencyKey }) {
+    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 query = listed?.kind === 'query';
+    // A key names one mutation's receipt; the data plane refuses one on a query, so refuse it before the call.
+    if (idempotencyKey !== undefined && query)
+        throw new ArtifactServerError(400, 'idempotency_key_on_query', 'An idempotency key applies only to a mutation');
+    if (idempotencyKey !== undefined && !artifactOrmIdempotencyKeySchema.safeParse(idempotencyKey).success) {
+        throw new ArtifactServerError(400, 'invalid_idempotency_key', 'Idempotency keys are 1-128 letters, digits, dots, underscores, colons or hyphens');
+    }
+    const operation = artifactServerRequestSchema.parse({
+        operation: 'orm', mode, namespace, op: hash, variables,
+        ...(jsonScalars ? { jsonScalars } : {}), ...(idempotencyKey === undefined ? {} : { idempotencyKey }),
+    });
+    return { operation, replaySafe: query || idempotencyKey !== undefined };
+}
 /**
  * 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
@@ -231,8 +255,9 @@ function createBrokerTransport({ context, principal, token, getRuntime, fetcher,
     /**
      * 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.
+     * again, because a reset can come after Atlas acted on it, unless its caller marks it replay-safe
+     * (an ORM mutation carrying an idempotency key). A response, whatever its status, is Atlas's
+     * answer and is returned as is.
      */
     return async (input, { signal, replaySafe = isReadOperation(input), stream = false } = {}) => {
         for (let attempt = 1;; attempt++) {

package/dist/server/external-context.d.ts

@@ -9,7 +9,7 @@ export interface ArtifactExternalAccept {
  * bound to the one route it was signed for. Refuses a v1 context (`external_context_required`)
  * and a context from an ingress the handler did not name (`external_ingress_not_accepted`).
  */
-export declare function verifyArtifactExternalContext({ token, publicKeys, projectId, environment, method, path, accept, now }: {
+export declare function verifyArtifactExternalContext({ token, publicKeys, projectId, environment, method, path, accept, developmentSessionId, now }: {
     token: string | null;
     publicKeys: ArtifactGatewayPublicKeys;
     projectId: string;
@@ -17,5 +17,12 @@ export declare function verifyArtifactExternalContext({ token, publicKeys, proje
     method: string;
     path: string;
     accept: ArtifactExternalAccept;
+    /**
+     * Set only when this runtime runs under a development lease (`runtimeConfig.development`): its
+     * session id. A `development`-mode context is accepted only then, and only for that session; a
+     * hosted runtime leaves it unset and refuses every development context
+     * (`external_mode_not_accepted`).
+     */
+    developmentSessionId?: string;
     now?: number;
 }): RequestContextV2External;

package/dist/server/external-context.js

@@ -6,11 +6,16 @@ import { verifyAnyArtifactContext } from './internal/verify-any.js';
  * bound to the one route it was signed for. Refuses a v1 context (`external_context_required`)
  * and a context from an ingress the handler did not name (`external_ingress_not_accepted`).
  */
-export function verifyArtifactExternalContext({ token, publicKeys, projectId, environment, method, path, accept, now }) {
+export function verifyArtifactExternalContext({ token, publicKeys, projectId, environment, method, path, accept, developmentSessionId, now }) {
     if (!method || !path)
         throw new ArtifactContextError();
     // verifyAnyArtifactContext canonicalises `path` (canonicalizeIngressPath) before comparing it.
-    const context = verifyAnyArtifactContext({ token, publicKeys, projectId, environment, method, path, now });
+    // A direct property, not a conditional spread: a spread member escapes excess-property
+    // checks, so a renamed verifier option would silently refuse every development context.
+    const context = verifyAnyArtifactContext({
+        token, publicKeys, projectId, environment, method, path, now,
+        development: developmentSessionId ? { sessionId: developmentSessionId } : undefined,
+    });
     if (context.v !== 2)
         throw new ArtifactContextError('external_context_required');
     if (!accept.external.includes(context.principal.ingress))

package/dist/server/internal/v1-context.js

@@ -15,7 +15,7 @@ export function parseV1Context({ payload, projectId, environment, method, path,
     const context = parsed.data;
     if (context.projectId !== projectId || context.environment !== environment ||
         context.exp <= now || context.iat > now + 5 ||
-        (method !== undefined && context.method !== method.toUpperCase()) || (path !== undefined && context.path !== path))
+        (method !== undefined && context.method !== method.toUpperCase()) || (path !== undefined && !sameRequestTarget({ signed: context.path, actual: path })))
         throw new ArtifactContextError();
     Object.freeze(context.bridge);
     Object.freeze(context.lattice);
@@ -24,3 +24,19 @@ export function parseV1Context({ payload, projectId, environment, method, path,
         Object.freeze(context.taskRoutes);
     return Object.freeze(context);
 }
+/**
+ * The gateway signs the raw request target; a hosted Next.js handler only sees its query
+ * re-serialized (`:` → `%3A`, a space → `+`). The pathname must match exactly; the query
+ * matches when it carries the same parameters, in the same order, however it is encoded.
+ */
+function sameRequestTarget({ signed, actual }) {
+    if (signed === actual)
+        return true;
+    const [signedPath, signedQuery = ''] = splitTarget(signed);
+    const [actualPath, actualQuery = ''] = splitTarget(actual);
+    return signedPath === actualPath && new URLSearchParams(signedQuery).toString() === new URLSearchParams(actualQuery).toString();
+}
+function splitTarget(target) {
+    const separator = target.indexOf('?');
+    return separator === -1 ? [target] : [target.slice(0, separator), target.slice(separator + 1)];
+}

package/dist/server/internal/verify-any.d.ts

@@ -11,14 +11,23 @@ export type AnyArtifactRequestContext = ArtifactRequestContext | RequestContextV
  * context must be signed by an `external-` kid. This pairing is the only thing standing between
  * an `external-` kid and the v1 rules: the v1 branch goes straight to the shared v1 parser, not
  * through the public verifier's own external gate. A v2 context in `development` mode is refused
- * until development leases can admit it. The signature is checked once per call.
+ * unless the caller names the one development session it serves (`development`), and then only
+ * for that session; the kid pairing above already confines it to an `external-` kid. The
+ * signature is checked once per call.
  */
-export declare function verifyAnyArtifactContext({ token, publicKeys, projectId, environment, method, path, now }: {
+export declare function verifyAnyArtifactContext({ token, publicKeys, projectId, environment, method, path, development, now }: {
     token: string | null;
     publicKeys: ArtifactGatewayPublicKeys;
     projectId: string;
     environment: string;
     method?: string;
     path?: string;
+    /**
+     * The development session this caller serves. Pass it only from a development lease (the SDK)
+     * or, in Atlas, only under APP_ENV=development; never from a value the request carries.
+     */
+    development?: {
+        sessionId: string;
+    };
     now?: number;
 }): AnyArtifactRequestContext;

package/dist/server/internal/verify-any.js

@@ -13,9 +13,11 @@ import { canonicalizeIngressPath, signedIngressPath } from '../ingress-routes.js
  * context must be signed by an `external-` kid. This pairing is the only thing standing between
  * an `external-` kid and the v1 rules: the v1 branch goes straight to the shared v1 parser, not
  * through the public verifier's own external gate. A v2 context in `development` mode is refused
- * until development leases can admit it. The signature is checked once per call.
+ * unless the caller names the one development session it serves (`development`), and then only
+ * for that session; the kid pairing above already confines it to an `external-` kid. The
+ * signature is checked once per call.
  */
-export function verifyAnyArtifactContext({ token, publicKeys, projectId, environment, method, path, now = Math.floor(Date.now() / 1000) }) {
+export function verifyAnyArtifactContext({ token, publicKeys, projectId, environment, method, path, development, now = Math.floor(Date.now() / 1000) }) {
     let kid;
     let payload;
     try {
@@ -34,7 +36,7 @@ export function verifyAnyArtifactContext({ token, publicKeys, projectId, environ
     if (!parsed.success)
         throw new ArtifactContextError();
     const context = parsed.data;
-    if (context.mode !== 'published')
+    if (!modeAccepted({ context, development }))
         throw new ArtifactContextError('external_mode_not_accepted');
     // The gateway signs only a canonical path (plus its raw query); the caller's path is
     // canonicalised the same way before comparing, so an encoded or dot-segment variant never binds.
@@ -46,6 +48,12 @@ export function verifyAnyArtifactContext({ token, publicKeys, projectId, environ
         throw new ArtifactContextError();
     return freezeExternalContext(context);
 }
+/** `published` always; `development` only for the one development session the caller names. */
+function modeAccepted({ context, development }) {
+    if (context.mode === 'published')
+        return true;
+    return development !== undefined && context.devSessionId === development.sessionId;
+}
 function signedPathOf(raw) {
     const canonical = canonicalizeIngressPath(raw);
     return canonical && signedIngressPath(canonical);

package/dist/server/process-run-sharing.d.ts

@@ -0,0 +1,86 @@
+import { type ArtifactServerMode, type ArtifactServerRequest } from './broker-contract.js';
+/** Users (Auth0 `sub`) and chat groups (group id) to name in an assignment or a share. */
+export interface ArtifactProcessPrincipals {
+    users?: string[];
+    groups?: string[];
+}
+export interface ArtifactProcessRunViewerChange extends ArtifactProcessPrincipals {
+    runId: string;
+}
+/** Add collaborators to selected human nodes without replacing their existing run assignments. */
+export interface ArtifactProcessShareRun extends ArtifactProcessPrincipals {
+    runId: string;
+    /** Explicitly assigned human nodes of this run, at most ARTIFACT_PROCESS_SHARE_NODES_LIMIT. */
+    nodeIds: string[];
+    /** Explicitly permit these users to share full-run viewing and the same or fewer nodes within this app's live audience. */
+    delegateSharing?: {
+        audience: 'current_app';
+    };
+}
+export interface ArtifactProcessShareRunResult {
+    run_id: string;
+    nodes_updated: string[];
+    users: string[];
+    groups: string[];
+    /** True when the sharing grants have been applied; pending authorization rejects with 503. */
+    authorization_applied: boolean;
+    /** The root authority created or used by an explicitly delegated share. */
+    sharingAuthorityId?: string;
+}
+export interface ArtifactProcessRunSharingAuthoritiesQuery {
+    runId: string;
+    /** Default 20, at most ARTIFACT_PROCESS_SHARING_AUTHORITIES_LIMIT (50). */
+    limit?: number;
+    /** Authority id from the previous page's nextCursor. */
+    cursor?: string;
+}
+export interface ArtifactProcessRunSharingDelegate {
+    user_sub: string;
+    node_ids: string[];
+    granted_by: string;
+    granted_at: string;
+}
+export interface ArtifactProcessRunSharingAuthority {
+    id: string;
+    run_id: string;
+    bundle_hash: string;
+    node_ids: string[];
+    audience: {
+        kind: 'artifact_project';
+        project_id: string;
+    };
+    created_by: string;
+    created_at: string;
+    revoked_at: string | null;
+    /** At most 100 individual delegates under this root authority. */
+    delegates: ArtifactProcessRunSharingDelegate[];
+}
+export interface ArtifactProcessRunSharingAuthoritiesPage {
+    authorities: ArtifactProcessRunSharingAuthority[];
+    nextCursor: string | null;
+}
+export interface ArtifactProcessRevokeRunSharingAuthority {
+    runId: string;
+    authorityId: string;
+}
+export interface ArtifactProcessRevokeRunSharingAuthorityResult {
+    authority_id: string;
+    revoked: true;
+}
+export interface ArtifactRunSharingOperations {
+    /** Add collaborators and full-run viewing; owners may explicitly authorize scoped onward sharing. */
+    shareRun(input: ArtifactProcessShareRun): Promise<ArtifactProcessShareRunResult>;
+    /** Owner-only, user-mode page of this run's sharing authorities and their delegates. */
+    listRunSharingAuthorities(query: ArtifactProcessRunSharingAuthoritiesQuery): Promise<ArtifactProcessRunSharingAuthoritiesPage>;
+    /** Owner-only, idempotent revocation of onward sharing; existing viewing and step access remain. */
+    revokeRunSharingAuthority(input: ArtifactProcessRevokeRunSharingAuthority): Promise<ArtifactProcessRevokeRunSharingAuthorityResult>;
+}
+export declare function shareArtifactProcessRun({ mode, json, input }: {
+    mode: ArtifactServerMode;
+    json: (operation: ArtifactServerRequest) => Promise<unknown>;
+    input: ArtifactProcessShareRun;
+}): Promise<ArtifactProcessShareRunResult>;
+export declare function createArtifactProcessSharingClient({ mode, json }: {
+    mode: ArtifactServerMode;
+    json: (operation: ArtifactServerRequest) => Promise<unknown>;
+}): ArtifactRunSharingOperations;

package/dist/server/process-run-sharing.js

@@ -0,0 +1,29 @@
+import { artifactServerRequestSchema } from './broker-contract.js';
+import { ArtifactServerError } from './errors.js';
+export async function shareArtifactProcessRun({ mode, json, input }) {
+    // Atlas owns assignment validation; its wire result names the optional authority in snake case.
+    const body = await json(artifactServerRequestSchema.parse({ operation: 'lattice_share_run', mode, ...input }));
+    const { sharing_authority_id, ...shared } = body;
+    if (sharing_authority_id !== undefined && typeof sharing_authority_id !== 'string') {
+        throw new ArtifactServerError(502, 'malformed_response', 'Atlas returned a malformed sharing authority id');
+    }
+    return { ...shared, ...(sharing_authority_id === undefined ? {} : { sharingAuthorityId: sharing_authority_id }) };
+}
+export function createArtifactProcessSharingClient({ mode, json }) {
+    return {
+        shareRun: (input) => shareArtifactProcessRun({ mode, json, input }),
+        listRunSharingAuthorities: async (query) => {
+            // Atlas returns the owner-authorized records; the SDK maps only the continuation envelope.
+            const body = await json(artifactServerRequestSchema.parse({ operation: 'lattice_sharing_authorities', mode, ...query }));
+            if (!Array.isArray(body?.authorities) || !(typeof body.next_cursor === 'string' || body.next_cursor === null)) {
+                throw new ArtifactServerError(502, 'malformed_response', 'Atlas returned a malformed sharing authority page');
+            }
+            // Record projection and authority checks belong to Atlas, as with the other process lists.
+            return { authorities: body.authorities, nextCursor: body.next_cursor };
+        },
+        revokeRunSharingAuthority: async (input) => {
+            // The owner-authorized service returns its idempotent revocation receipt.
+            return await json(artifactServerRequestSchema.parse({ operation: 'lattice_sharing_authority_revoke', mode, ...input }));
+        },
+    };
+}

package/dist/server/process-runs-page.d.ts

@@ -0,0 +1,39 @@
+import { type ArtifactProcessRunStatus, type ArtifactServerMode, type ArtifactServerRequest } from './broker-contract.js';
+import type { ArtifactProcessRunRecord } from './processes.js';
+/**
+ * Page visible runs of one declared process; filters stay the same while following its cursor.
+ * Atlas establishes the caller's complete authorization scope before selecting run rows.
+ * Unavailable authorization, an unsupported authorization model, or an incomplete grant scope
+ * returns 503 without partial runs or a cursor.
+ */
+export interface ArtifactProcessRunsPageQuery {
+    process: string;
+    statuses?: ArtifactProcessRunStatus[];
+    /** One entity type, optionally narrowed to one id or a set of up to 500 ids. */
+    entity?: {
+        type: string;
+        id?: string;
+        ids?: string[];
+    };
+    /** Maximum returned visible runs per page, default 100 and at most ARTIFACT_PROCESS_RUNS_LIMIT (500). */
+    limit?: number;
+    /** Encrypted continuation bound to this principal and these filters; expires after one hour. */
+    cursor?: string;
+    /** Soft-archived runs only, instead of the default active ones. */
+    archived?: boolean;
+}
+/** A compact activity-list row; read the run separately for its state, output and steps. */
+export type ArtifactProcessRunSummary = Pick<ArtifactProcessRunRecord, 'id' | 'processId' | 'status' | 'entityType' | 'entityId' | 'startedAt' | 'completedAt' | 'error'>;
+export interface ArtifactProcessRunsPage {
+    runs: ArtifactProcessRunSummary[];
+    /**
+     * Continues after the last returned visible run only when another visible run exists.
+     * Null ends the list; a successful empty page always has null.
+     */
+    nextCursor: string | null;
+}
+export declare function readArtifactProcessRunsPage({ mode, json, query }: {
+    mode: ArtifactServerMode;
+    json: (operation: ArtifactServerRequest) => Promise<unknown>;
+    query: ArtifactProcessRunsPageQuery;
+}): Promise<ArtifactProcessRunsPage>;

package/dist/server/process-runs-page.js

@@ -0,0 +1,10 @@
+import { artifactServerRequestSchema } from './broker-contract.js';
+import { ArtifactServerError } from './errors.js';
+export async function readArtifactProcessRunsPage({ mode, json, query }) {
+    const body = await json(artifactServerRequestSchema.parse({ operation: 'lattice_runs_page', mode, ...query }));
+    if (!Array.isArray(body?.runs) || !(typeof body.nextCursor === 'string' || body.nextCursor === null)) {
+        throw new ArtifactServerError(502, 'malformed_response', 'Atlas returned a malformed run page');
+    }
+    // Atlas owns row projection and visibility filtering; the SDK preserves its continuation.
+    return body;
+}

package/dist/server/processes.d.ts

@@ -1,4 +1,9 @@
 import { type ArtifactProcessPrincipalType, type ArtifactProcessRunStatus, type ArtifactProcessTaskView, type ArtifactServerMode, type ArtifactServerRequest } from './broker-contract.js';
+import { type ArtifactProcessRunsPage, type ArtifactProcessRunsPageQuery } from './process-runs-page.js';
+import { type ArtifactProcessPrincipals, type ArtifactProcessRunViewerChange, type ArtifactRunSharingOperations } from './process-run-sharing.js';
+export type { ArtifactProcessRunSummary, ArtifactProcessRunsPage, ArtifactProcessRunsPageQuery } from './process-runs-page.js';
+export type { ArtifactProcessPrincipals, ArtifactProcessRunViewerChange, ArtifactProcessShareRun, ArtifactProcessShareRunResult } from './process-run-sharing.js';
+export type { ArtifactProcessRunSharingAuthoritiesQuery, ArtifactProcessRunSharingAuthoritiesPage, ArtifactProcessRunSharingAuthority, ArtifactProcessRunSharingDelegate, ArtifactProcessRevokeRunSharingAuthority, ArtifactProcessRevokeRunSharingAuthorityResult } from './process-run-sharing.js';
 /** A run of a process declared under `server.capabilities.processes.start`. */
 export interface ArtifactProcessStart {
     process: string;
@@ -264,11 +269,6 @@ export interface ArtifactProcessRunEvents {
     /** Pass as `since` on the next poll. Null only when the run has no events yet and no `since` was given. */
     cursor: string | null;
 }
-/** 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;
@@ -288,9 +288,6 @@ export interface ArtifactProcessRunViewers {
     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;
@@ -309,11 +306,13 @@ export interface ArtifactProcessPrincipal {
     /** Groups: active members. */
     memberCount?: number;
 }
-export interface ArtifactServerProcesses {
+export interface ArtifactServerProcesses extends ArtifactRunSharingOperations {
     /** 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[]>;
+    /** Page compact run summaries the user may view; nextCursor names a continuation only when more visible runs exist. */
+    listRunsPage(query: ArtifactProcessRunsPageQuery): Promise<ArtifactProcessRunsPage>;
     /** 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. */

package/dist/server/processes.js

@@ -1,5 +1,7 @@
 import { artifactServerRequestSchema, } from './broker-contract.js';
 import { ArtifactServerError } from './errors.js';
+import { readArtifactProcessRunsPage } from './process-runs-page.js';
+import { createArtifactProcessSharingClient } from './process-run-sharing.js';
 /** `client.processes`: Lattice through the broker's typed `lattice*` operations. Atlas owns validation and redaction. */
 export function createArtifactProcessesClient({ mode, json }) {
     return {
@@ -14,6 +16,7 @@ export function createArtifactProcessesClient({ mode, json }) {
                 throw new ArtifactServerError(502, 'malformed_response', 'Atlas returned a malformed run list');
             return body.runs;
         },
+        listRunsPage: (query) => readArtifactProcessRunsPage({ mode, json, query }),
         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 }));
@@ -36,6 +39,7 @@ export function createArtifactProcessesClient({ mode, json }) {
         assign: async (input) => {
             return await json(artifactServerRequestSchema.parse({ operation: 'lattice_assign', mode, ...input }));
         },
+        ...createArtifactProcessSharingClient({ mode, json }),
         cancel: async (runId) => {
             return await json(artifactServerRequestSchema.parse({ operation: 'lattice_cancel', mode, runId }));
         },

package/dist/server/request-context.js

@@ -72,8 +72,15 @@ export const ARTIFACT_SERVICE_ACCOUNT_SUB_PREFIX = 'service-account|';
 export const ARTIFACT_EXTERNAL_CONTEXT_MAX_AGE_SECONDS = 60;
 /** An IPv4 or IPv6 address, as the gateway observed it. The control contract reuses it. */
 export const artifactIpAddressSchema = z.union([z.ipv4(), z.ipv6()]);
+const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f]/;
 /** Signed by the gateway after it strips control characters and truncates; refused here otherwise. */
-const observedUserAgent = z.string().max(512).refine(value => !/[\u0000-\u001f\u007f]/.test(value), 'Expected a user agent without control characters');
+const observedUserAgent = z.string().max(512).refine(value => !CONTROL_CHARACTERS.test(value), 'Expected a user agent without control characters');
+/**
+ * The principal's subject and email become the ORM's row-policy claims (`ext_subject`, `ext_email`),
+ * which refuse control characters; refusing them here keeps such a context a 401 at verification
+ * rather than a failure in the middle of a request.
+ */
+const externalSubject = id.refine(value => !CONTROL_CHARACTERS.test(value), 'Expected a subject without control characters');
 /** The external caller as the gateway verified it at pass exchange. Strict: see the v2 key policy below. */
 export const artifactExternalPrincipalSchema = z.object({
     kind: z.literal('external'),
@@ -81,10 +88,10 @@ export const artifactExternalPrincipalSchema = z.object({
     ingress: id,
     provider: id,
     issuer: z.string().min(1).max(2048),
-    subject: id,
+    subject: externalSubject,
     clientId: id,
     /** Normalized (trimmed, lowercase) by Atlas at exchange. */
-    email: z.string().min(3).max(320).refine(value => value === value.trim().toLowerCase() && value.includes('@'), 'Expected a normalized email'),
+    email: z.string().min(3).max(320).refine(value => value === value.trim().toLowerCase() && value.includes('@') && !CONTROL_CHARACTERS.test(value), 'Expected a normalized email'),
     emailVerified: z.literal(true),
     authTime: z.number().int().nonnegative().nullable(),
     amr: z.array(z.string().min(1).max(64)).max(16).nullable(),

package/dist/server/runtime-config.d.ts

@@ -8,7 +8,16 @@ export declare const artifactRuntimeConfigSchema: z.ZodObject<{
     devSessionId: z.ZodOptional<z.ZodString>;
     deploymentId: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
-export type ArtifactRuntimeConfig = z.infer<typeof artifactRuntimeConfigSchema>;
+export type ArtifactRuntimeConfig = z.infer<typeof artifactRuntimeConfigSchema> & {
+    /**
+     * True only on a configuration read from a development lease: the owner-only file `artifact dev`
+     * writes and names in SEQUENCE_ARTIFACT_RUNTIME_FILE (`next-project.ts`), for one development
+     * session. Never parsed from JSON, so neither the lease file, the hosted configuration nor an
+     * explicit `runtime` option can claim it, and it does not survive a re-parse. Only under it does
+     * the SDK accept an external context in `development` mode.
+     */
+    readonly development?: true;
+};
 export type ArtifactRequestHeaders = Pick<Headers, 'get'>;
 /** Credentials are platform-provided and rotated by the CLI, never inferred from ambient cloud auth. */
 export declare function readArtifactRuntimeConfig({ file }?: {