@sequenceholdings/artifact-studio 0.6.1 → 0.6.3

package/dist/manifest-next.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { artifactNextAuditCapabilitySchema } from './manifest-next-reach.js';
 /** Approved major/minor profile. Builds additionally record exact patch versions. */
 export declare const ARTIFACT_NEXT_RUNTIME: Readonly<{
     sdk: "sequence";
@@ -20,14 +21,8 @@ export declare const ARTIFACT_NEXT_RESOURCE_DEFAULTS: {
     max_instances: number;
     timeout_seconds: number;
 };
-/**
- * Where the server's audit events (`client.audit.record`) go: an Atlas audit service id. Every
- * application may record under `artifact_studio`; Atlas admits a first-party service, such as
- * `application_portal`, only for the projects it registers for it. Server-only: browsers can't audit.
- */
-export declare const artifactNextAuditCapabilitySchema: z.ZodObject<{
-    service: z.ZodString;
-}, z.core.$strict>;
+export { artifactNextAuditCapabilitySchema };
+export * from './manifest-next-ingress.js';
 export declare const artifactNextServerCapabilitiesSchema: z.ZodPrefault<z.ZodObject<{
     audit: z.ZodOptional<z.ZodObject<{
         service: z.ZodString;
@@ -132,6 +127,71 @@ export declare const artifactNextServerSchema: z.ZodPrefault<z.ZodObject<{
     lattice: z.ZodOptional<z.ZodObject<{
         accept: z.ZodDefault<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
+    ingress: z.ZodOptional<z.ZodObject<{
+        external: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            provider: z.ZodString;
+            service_account: z.ZodString;
+            headers: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            capabilities: z.ZodPrefault<z.ZodObject<{
+                storage: z.ZodOptional<z.ZodRecord<z.ZodUUID, z.ZodEnum<{
+                    viewer: "viewer";
+                    editor: "editor";
+                    admin: "admin";
+                }>>>;
+                data: z.ZodPrefault<z.ZodObject<{
+                    read: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                    write: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                }, z.core.$strict>>;
+                api: z.ZodPrefault<z.ZodObject<{
+                    read: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                    write: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                }, z.core.$strict>>;
+                functions: z.ZodPrefault<z.ZodObject<{
+                    invoke: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                }, z.core.$strict>>;
+                audit: z.ZodOptional<z.ZodObject<{
+                    service: z.ZodString;
+                }, z.core.$strict>>;
+                processes: z.ZodOptional<z.ZodNever>;
+            }, z.core.$strict>>;
+            evidence: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+                bind: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodEnum<{
+                    email: "email";
+                    subject: "subject";
+                    authTime: "authTime";
+                    amr: "amr";
+                    "client.ip": "client.ip";
+                    "client.userAgent": "client.userAgent";
+                    issuer: "issuer";
+                }>>>;
+                fresh_auth_seconds: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strict>>>;
+            routes: z.ZodArray<z.ZodObject<{
+                path: z.ZodString;
+                methods: z.ZodArray<z.ZodEnum<{
+                    GET: "GET";
+                    POST: "POST";
+                    PUT: "PUT";
+                    PATCH: "PATCH";
+                    DELETE: "DELETE";
+                }>>;
+                fresh_auth_seconds: z.ZodOptional<z.ZodNumber>;
+                max_body_bytes: z.ZodDefault<z.ZodNumber>;
+                responses: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+                    "application/json": "application/json";
+                    "application/problem+json": "application/problem+json";
+                    "application/pdf": "application/pdf";
+                    "application/zip": "application/zip";
+                    "image/png": "image/png";
+                    "image/jpeg": "image/jpeg";
+                    "image/webp": "image/webp";
+                    "text/csv": "text/csv";
+                    "application/octet-stream": "application/octet-stream";
+                }>>>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
 }, z.core.$strict>>;
 export declare const artifactStudioNextManifestSchema: z.ZodObject<{
     ontology: z.ZodOptional<z.ZodObject<{
@@ -251,6 +311,71 @@ export declare const artifactStudioNextManifestSchema: z.ZodObject<{
         lattice: z.ZodOptional<z.ZodObject<{
             accept: z.ZodDefault<z.ZodArray<z.ZodString>>;
         }, z.core.$strict>>;
+        ingress: z.ZodOptional<z.ZodObject<{
+            external: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                provider: z.ZodString;
+                service_account: z.ZodString;
+                headers: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                capabilities: z.ZodPrefault<z.ZodObject<{
+                    storage: z.ZodOptional<z.ZodRecord<z.ZodUUID, z.ZodEnum<{
+                        viewer: "viewer";
+                        editor: "editor";
+                        admin: "admin";
+                    }>>>;
+                    data: z.ZodPrefault<z.ZodObject<{
+                        read: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                        write: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                    }, z.core.$strict>>;
+                    api: z.ZodPrefault<z.ZodObject<{
+                        read: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                        write: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                    }, z.core.$strict>>;
+                    functions: z.ZodPrefault<z.ZodObject<{
+                        invoke: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                    }, z.core.$strict>>;
+                    audit: z.ZodOptional<z.ZodObject<{
+                        service: z.ZodString;
+                    }, z.core.$strict>>;
+                    processes: z.ZodOptional<z.ZodNever>;
+                }, z.core.$strict>>;
+                evidence: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+                    bind: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodEnum<{
+                        email: "email";
+                        subject: "subject";
+                        authTime: "authTime";
+                        amr: "amr";
+                        "client.ip": "client.ip";
+                        "client.userAgent": "client.userAgent";
+                        issuer: "issuer";
+                    }>>>;
+                    fresh_auth_seconds: z.ZodOptional<z.ZodNumber>;
+                }, z.core.$strict>>>;
+                routes: z.ZodArray<z.ZodObject<{
+                    path: z.ZodString;
+                    methods: z.ZodArray<z.ZodEnum<{
+                        GET: "GET";
+                        POST: "POST";
+                        PUT: "PUT";
+                        PATCH: "PATCH";
+                        DELETE: "DELETE";
+                    }>>;
+                    fresh_auth_seconds: z.ZodOptional<z.ZodNumber>;
+                    max_body_bytes: z.ZodDefault<z.ZodNumber>;
+                    responses: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+                        "application/json": "application/json";
+                        "application/problem+json": "application/problem+json";
+                        "application/pdf": "application/pdf";
+                        "application/zip": "application/zip";
+                        "image/png": "image/png";
+                        "image/jpeg": "image/jpeg";
+                        "image/webp": "image/webp";
+                        "text/csv": "text/csv";
+                        "application/octet-stream": "application/octet-stream";
+                    }>>>;
+                }, z.core.$strict>>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
     }, z.core.$strict>>;
     targets: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         url: z.ZodString;

package/dist/manifest-next.js

@@ -1,8 +1,9 @@
-import { storageScopesSchema } from '@sequenceholdings/storage';
 import { ontologyContractSchema } from '@sequenceholdings/orm/canonical';
 import { z } from 'zod';
 import { capabilityPinsSchema, customRolesBlockSchema, validateCapabilityPins } from './manifest-custom-roles.js';
 import { isManagedServerInvokePath } from './server/managed-server-path.js';
+import { artifactNextIngressSchema, validateIngressAgainstServer } from './manifest-next-ingress.js';
+import { artifactNextAuditCapabilitySchema, reachShape, serviceAccountRef } from './manifest-next-reach.js';
 import { apiCapabilityPathAllowed, artifactPresentationSchema, artifactStudioStaticManifestSchema, sidebarBadgeSchema, } from './manifest-static.js';
 /** Approved major/minor profile. Builds additionally record exact patch versions. */
 export const ARTIFACT_NEXT_RUNTIME = Object.freeze({ sdk: 'sequence', node: 24, react: 19, next: '16.3' });
@@ -11,51 +12,8 @@ export const ARTIFACT_NEXT_APPROVED_PACKAGES = Object.freeze({ next: '16.3.4', r
 export const ARTIFACT_NEXT_RESOURCE_DEFAULTS = {
     cpu: 1, memory_mb: 1024, concurrency: 20, min_instances: 0, max_instances: 3, timeout_seconds: 60,
 };
-const boundedRef = z.string().min(1).max(255).regex(/^[a-zA-Z0-9][a-zA-Z0-9_./:-]*$/).refine((value) => value.split('/').every((part) => part !== '' && part !== '.' && part !== '..'), 'Resource references cannot contain empty segments or traversal');
-const serviceAccountRef = z.string().regex(/^([a-z][a-z0-9-]{1,98}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$/);
-const apiPath = z.string().min(1).max(512).refine((value) => {
-    if (!value.startsWith('/api/') || value === '/api/' || value === '/api/*')
-        return false;
-    if (/[\\%?#\s\x00-\x1f]/.test(value))
-        return false;
-    return value.split('/').slice(1).every((part, index, parts) => part !== '.' && part !== '..' && (part !== '' || index === parts.length - 1));
-}, 'API capability paths must be scoped below /api/ without encoded paths, traversal, queries, or fragments');
-// ORM references are what a delegated data token covers (orm-data-plane checkDataTokenScope):
-// a query needs namespace/table for every table it reads, and a mutation needs its
-// namespace/ops/Operation (or table coverage). Any other shape can never match, so it is
-// a typo to report here rather than a 403 at request time. The patterns mirror the ORM's
-// NAMESPACE_PATTERN, IDENTIFIER_PATTERN and GraphQL operation names; they are kept local so
-// browser code that parses manifests does not load the ORM package. platformUsers is the
-// ORM's built-in platform-user entity (PLATFORM_USER_TABLE), a logical key outside the
-// identifier pattern that queries traversing user relations read.
-const ormTableRef = /^[a-z][a-z0-9_]{0,40}\/(?:[a-z][a-z0-9_]{0,62}|platformUsers)$/;
-const ormOperationRef = /^[a-z][a-z0-9_]{0,40}\/ops\/[_A-Za-z][_0-9A-Za-z]*$/;
-const dataReadRef = boundedRef.refine((ref) => ormTableRef.test(ref), 'ORM read references use namespace/table');
-const dataWriteRef = boundedRef.refine((ref) => ormTableRef.test(ref) || ormOperationRef.test(ref), 'ORM write references use namespace/ops/Operation or namespace/table');
-const latticeProcessRef = z.string().min(2).max(128).regex(/^[A-Za-z0-9._-]+$/, 'Process references are Lattice process ids');
-const reachShape = {
-    storage: storageScopesSchema.optional(),
-    data: z.strictObject({ read: z.array(dataReadRef).max(256).default([]), write: z.array(dataWriteRef).max(256).default([]) }).prefault({}),
-    api: z.strictObject({ read: z.array(apiPath).max(256).default([]), write: z.array(apiPath).max(256).default([]) }).prefault({}),
-    functions: z.strictObject({ invoke: z.array(boundedRef).max(256).default([]) }).prefault({}),
-    // `start`: processes the server may start runs of. `read`: processes whose runs, template and
-    // the user's own steps it may read. `act`: processes whose human steps it may advance and
-    // reassign, and whose runs' viewers it may manage. All name exact process ids; the user's own
-    // Invoker / Viewer / Advancer / Owner grants decide what happens.
-    processes: z.strictObject({
-        start: z.array(latticeProcessRef).max(256).default([]),
-        read: z.array(latticeProcessRef).max(256).default([]),
-        act: z.array(latticeProcessRef).max(256).default([]),
-    }).prefault({}),
-};
-/**
- * Where the server's audit events (`client.audit.record`) go: an Atlas audit service id. Every
- * application may record under `artifact_studio`; Atlas admits a first-party service, such as
- * `application_portal`, only for the projects it registers for it. Server-only: browsers can't audit.
- */
-export const artifactNextAuditCapabilitySchema = z.strictObject({
-    service: z.string().regex(/^[a-z][a-z0-9_]{0,63}$/, 'Audit services are Atlas audit service ids, such as artifact_studio'),
-});
+export { artifactNextAuditCapabilitySchema };
+export * from './manifest-next-ingress.js';
 export const artifactNextServerCapabilitiesSchema = z.strictObject({
     ...reachShape,
     audit: artifactNextAuditCapabilitySchema.optional(),
@@ -118,6 +76,8 @@ export const artifactNextServerSchema = z.strictObject({
     lattice: z.strictObject({
         accept: z.array(managedServerInvokePath).max(32).default([]),
     }).optional(),
+    /** Front doors for callers that are not Atlas users. Omitted means none: external callers are refused. */
+    ingress: artifactNextIngressSchema.optional(),
 }).superRefine((server, ctx) => {
     if (new Set(server.secrets.map((secret) => secret.name)).size !== server.secrets.length) {
         ctx.addIssue({ code: 'custom', path: ['secrets'], message: 'Each secret environment name must be unique' });
@@ -128,6 +88,7 @@ export const artifactNextServerSchema = z.strictObject({
     if (server.lattice && new Set(server.lattice.accept).size !== server.lattice.accept.length) {
         ctx.addIssue({ code: 'custom', path: ['lattice', 'accept'], message: 'Lattice accept paths must be unique' });
     }
+    validateIngressAgainstServer({ server, ctx });
 }).prefault({});
 const appRoot = z.string().min(1).max(512).refine((value) => {
     if (value === '.')

package/dist/manifest-static.d.ts

@@ -23,6 +23,12 @@ export declare const artifactOfflineCapabilitySchema: z.ZodObject<{
     policy_version: z.ZodNumber;
 }, z.core.$strip>;
 export type ArtifactOfflineCapability = z.infer<typeof artifactOfflineCapabilitySchema>;
+/**
+ * Whether {@link apiCapabilityPathAllowed} treats an entry as a prefix: a trailing `/`, or a
+ * trailing `/*` with no other whole-segment `*`. Such an entry admits every path below it,
+ * including routes added later. An entry with a mid-path `*` matches whole segments by count.
+ */
+export declare function isPrefixApiCapabilityEntry(entry: string): boolean;
 export declare function apiCapabilityPathAllowed(pathname: string, allowed: readonly string[]): boolean;
 export declare const artifactStudioStaticManifestSchema: z.ZodObject<{
     ontology: z.ZodOptional<z.ZodObject<{

package/dist/manifest-static.js

@@ -46,6 +46,16 @@ function hasMidPathWildcard(entry) {
     const parts = entry.split('/');
     return parts.slice(1, -1).some((part) => part === '*');
 }
+/**
+ * Whether {@link apiCapabilityPathAllowed} treats an entry as a prefix: a trailing `/`, or a
+ * trailing `/*` with no other whole-segment `*`. Such an entry admits every path below it,
+ * including routes added later. An entry with a mid-path `*` matches whole segments by count.
+ */
+export function isPrefixApiCapabilityEntry(entry) {
+    if (entry.includes('*') && (!entry.endsWith('/*') || hasMidPathWildcard(entry)))
+        return false;
+    return entry.endsWith('/*') || entry.endsWith('/');
+}
 export function apiCapabilityPathAllowed(pathname, allowed) {
     return allowed.some((entry) => matchesApiCapabilityEntry(pathname, entry));
 }

package/dist/manifest.d.ts

@@ -204,6 +204,71 @@ export declare const artifactStudioManifestSchema: z.ZodUnion<readonly [z.ZodObj
         lattice: z.ZodOptional<z.ZodObject<{
             accept: z.ZodDefault<z.ZodArray<z.ZodString>>;
         }, z.core.$strict>>;
+        ingress: z.ZodOptional<z.ZodObject<{
+            external: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                provider: z.ZodString;
+                service_account: z.ZodString;
+                headers: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                capabilities: z.ZodPrefault<z.ZodObject<{
+                    storage: z.ZodOptional<z.ZodRecord<z.ZodUUID, z.ZodEnum<{
+                        viewer: "viewer";
+                        editor: "editor";
+                        admin: "admin";
+                    }>>>;
+                    data: z.ZodPrefault<z.ZodObject<{
+                        read: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                        write: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                    }, z.core.$strict>>;
+                    api: z.ZodPrefault<z.ZodObject<{
+                        read: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                        write: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                    }, z.core.$strict>>;
+                    functions: z.ZodPrefault<z.ZodObject<{
+                        invoke: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                    }, z.core.$strict>>;
+                    audit: z.ZodOptional<z.ZodObject<{
+                        service: z.ZodString;
+                    }, z.core.$strict>>;
+                    processes: z.ZodOptional<z.ZodNever>;
+                }, z.core.$strict>>;
+                evidence: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+                    bind: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodEnum<{
+                        email: "email";
+                        subject: "subject";
+                        authTime: "authTime";
+                        amr: "amr";
+                        "client.ip": "client.ip";
+                        "client.userAgent": "client.userAgent";
+                        issuer: "issuer";
+                    }>>>;
+                    fresh_auth_seconds: z.ZodOptional<z.ZodNumber>;
+                }, z.core.$strict>>>;
+                routes: z.ZodArray<z.ZodObject<{
+                    path: z.ZodString;
+                    methods: z.ZodArray<z.ZodEnum<{
+                        GET: "GET";
+                        POST: "POST";
+                        PUT: "PUT";
+                        PATCH: "PATCH";
+                        DELETE: "DELETE";
+                    }>>;
+                    fresh_auth_seconds: z.ZodOptional<z.ZodNumber>;
+                    max_body_bytes: z.ZodDefault<z.ZodNumber>;
+                    responses: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+                        "application/json": "application/json";
+                        "application/problem+json": "application/problem+json";
+                        "application/pdf": "application/pdf";
+                        "application/zip": "application/zip";
+                        "image/png": "image/png";
+                        "image/jpeg": "image/jpeg";
+                        "image/webp": "image/webp";
+                        "text/csv": "text/csv";
+                        "application/octet-stream": "application/octet-stream";
+                    }>>>;
+                }, z.core.$strict>>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
     }, z.core.$strict>>;
     targets: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         url: z.ZodString;
@@ -226,3 +291,5 @@ export type ArtifactStudioManifest = ArtifactStudioStaticManifest | ArtifactStud
 export type ArtifactStudioManifestInput = z.input<typeof artifactStudioManifestSchema>;
 export declare function parseArtifactStudioManifest(value: unknown): ArtifactStudioManifest;
 export declare function isNextArtifactManifest(manifest: ArtifactStudioManifest): manifest is ArtifactStudioNextManifest;
+/** Parses an `artifact.bundle.yml` that must be an Artifact Next manifest (schema_version 2). */
+export declare function parseArtifactNextManifest(value: unknown): ArtifactStudioNextManifest;

package/dist/manifest.js

@@ -14,3 +14,10 @@ export function parseArtifactStudioManifest(value) {
 export function isNextArtifactManifest(manifest) {
     return manifest.artifact.type === 'nextjs';
 }
+/** Parses an `artifact.bundle.yml` that must be an Artifact Next manifest (schema_version 2). */
+export function parseArtifactNextManifest(value) {
+    const manifest = parseArtifactStudioManifest(value);
+    if (!isNextArtifactManifest(manifest))
+        throw new Error('Expected an Artifact Next manifest (artifact.type nextjs)');
+    return manifest;
+}

package/dist/server/api-client.d.ts

@@ -8,6 +8,7 @@ export interface ArtifactServerFetchOptions {
 /** Sends one broker operation; the client's transport (retries, the external-principal gate). */
 export type ArtifactBrokerRequest = (operation: ArtifactServerRequest, options?: {
     signal?: AbortSignal;
+    stream?: boolean;
 }) => Promise<Response>;
 /** `client.api`: Atlas routes reached through the broker as `api` operations. */
 export declare function createApiClient({ mode, request, json }: {

package/dist/server/api-client.js

@@ -22,7 +22,8 @@ export function createApiClient({ mode, request, json }) {
                 })) };
         },
         async stream(path, options = {}) {
-            const response = await fetchResponse(path, options);
+            // A stream outlives the broker's answer deadline: only its headers must arrive in time.
+            const response = await request(operation(path, options), { signal: options.signal, stream: true });
             if (!response.ok || !response.body) {
                 throw await stepUpErrorFromResponse(response) ??
                     new ArtifactServerError(response.status, 'stream_unavailable', 'Atlas did not return a readable response');

package/dist/server/broker-contract.d.ts

@@ -3,10 +3,10 @@ export { ORM_JSON_SCALARS_HEADER, ORM_LOSSLESS_JSON_SCALARS, type ArtifactOrmJso
 export declare const artifactServerMethodSchema: z.ZodEnum<{
     GET: "GET";
     POST: "POST";
-    DELETE: "DELETE";
-    HEAD: "HEAD";
     PUT: "PUT";
     PATCH: "PATCH";
+    DELETE: "DELETE";
+    HEAD: "HEAD";
 }>;
 export declare const artifactServerModeSchema: z.ZodDefault<z.ZodEnum<{
     service: "service";
@@ -18,6 +18,8 @@ export declare function isArtifactApiPath(path: string): boolean;
 export declare const ARTIFACT_PROCESS_RUN_STATUSES: readonly ["pending", "running", "completed", "failed", "cancelled", "timed_out"];
 /** Lattice lists at most this many runs per call. */
 export declare const ARTIFACT_PROCESS_RUNS_LIMIT = 500;
+/** A run-events read returns at most this many events per call, as the run's stream drains them. */
+export declare const ARTIFACT_PROCESS_RUN_EVENTS_LIMIT = 1000;
 /** Which of the user's human steps to list: parked and waiting on them, or already done. */
 export declare const ARTIFACT_PROCESS_TASK_VIEWS: readonly ["active", "completed"];
 /** Lattice lists at most this many human steps per call, as its own inbox does. */
@@ -45,10 +47,10 @@ export declare const artifactServerRequestSchema: z.ZodDiscriminatedUnion<[z.Zod
     method: z.ZodEnum<{
         GET: "GET";
         POST: "POST";
-        DELETE: "DELETE";
-        HEAD: "HEAD";
         PUT: "PUT";
         PATCH: "PATCH";
+        DELETE: "DELETE";
+        HEAD: "HEAD";
     }>;
     path: z.ZodString;
     body: z.ZodOptional<z.ZodUnknown>;
@@ -71,10 +73,10 @@ export declare const artifactServerRequestSchema: z.ZodDiscriminatedUnion<[z.Zod
     method: z.ZodEnum<{
         GET: "GET";
         POST: "POST";
-        DELETE: "DELETE";
-        HEAD: "HEAD";
         PUT: "PUT";
         PATCH: "PATCH";
+        DELETE: "DELETE";
+        HEAD: "HEAD";
     }>;
     path: z.ZodString;
     body: z.ZodOptional<z.ZodUnknown>;
@@ -94,6 +96,7 @@ export declare const artifactServerRequestSchema: z.ZodDiscriminatedUnion<[z.Zod
     }>>;
     process: z.ZodString;
     runId: z.ZodOptional<z.ZodString>;
+    startNodeId: z.ZodOptional<z.ZodString>;
     title: z.ZodOptional<z.ZodString>;
     entity: z.ZodOptional<z.ZodObject<{
         type: z.ZodString;
@@ -132,6 +135,15 @@ export declare const artifactServerRequestSchema: z.ZodDiscriminatedUnion<[z.Zod
         user: "user";
     }>>;
     runId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"lattice_run_events">;
+    mode: z.ZodDefault<z.ZodEnum<{
+        service: "service";
+        user: "user";
+    }>>;
+    runId: z.ZodString;
+    since: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>, z.ZodObject<{
     operation: z.ZodLiteral<"lattice_process">;
     mode: z.ZodDefault<z.ZodEnum<{
@@ -172,6 +184,21 @@ export declare const artifactServerRequestSchema: z.ZodDiscriminatedUnion<[z.Zod
     }>>;
     runId: z.ZodString;
     stepId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"lattice_cancel">;
+    mode: z.ZodDefault<z.ZodEnum<{
+        service: "service";
+        user: "user";
+    }>>;
+    runId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"lattice_reset_step">;
+    mode: z.ZodDefault<z.ZodEnum<{
+        service: "service";
+        user: "user";
+    }>>;
+    runId: z.ZodString;
+    stepId: z.ZodString;
 }, z.core.$strict>, z.ZodObject<{
     operation: z.ZodLiteral<"lattice_viewers">;
     mode: z.ZodDefault<z.ZodEnum<{

package/dist/server/broker-contract.js

@@ -31,6 +31,8 @@ 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-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. */
 export const ARTIFACT_PROCESS_TASK_VIEWS = ['active', 'completed'];
 /** Lattice lists at most this many human steps per call, as its own inbox does. */
@@ -106,10 +108,12 @@ export const artifactServerRequestSchema = z.discriminatedUnion('operation', [
         }, '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.
+    // run, passes its input, may seed who works each human node and may enter the graph at a node
+    // other than the process's start (the route's `start_node_id`). The version and engine stay with
+    // the process and its owning routes.
     z.object({
         operation: z.literal('lattice'), mode, process: latticeId, runId: latticeId.optional(),
+        startNodeId: z.string().min(1).max(255).regex(/^[A-Za-z0-9._-]+$/).optional(),
         title: z.string().max(500).optional(),
         entity: z.object({ type: entityRef, id: entityRef }).strict().optional(),
         metadata: z.record(z.string(), z.unknown()).optional(),
@@ -127,6 +131,14 @@ export const artifactServerRequestSchema = z.discriminatedUnion('operation', [
     // 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(),
+    // A page of a run's events after a cursor, oldest first, as `GET /api/lattice/runs/[runId]/stream`
+    // sends them: `since` is the cursor `lattice_run` returned, or the one the previous page returned.
+    // Polling with it sees every event exactly once. The user's Viewer relation on the run decides.
+    z.object({
+        operation: z.literal('lattice_run_events'), mode, runId: latticeId,
+        since: z.string().min(1).max(512).optional(),
+        limit: z.number().int().min(1).max(ARTIFACT_PROCESS_RUN_EVENTS_LIMIT).optional(),
+    }).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(),
@@ -150,6 +162,12 @@ 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),
+    // 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(),
+    // Resets a generating agent step without cancelling its run, as `POST .../steps/[stepId]/reset`
+    // does: the step settles and the run re-parks at the node's reset edge. Invoker-gated.
+    z.object({ operation: z.literal('lattice_reset_step'), mode, runId: latticeId, stepId: latticeId }).strict(),
     // 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;

package/dist/server/client.js

@@ -170,6 +170,8 @@ 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})`);
 }
+/** How long Atlas has to answer a broker call; for a stream, to send its first byte of headers. */
+const BROKER_RESPONSE_TIMEOUT_MS = 60_000;
 /**
  * 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.
@@ -186,7 +188,7 @@ function isReadOperation(operation) {
     }
 }
 function createBrokerTransport({ context, principal, token, getRuntime, fetcher, log }) {
-    const send = async (input, signal) => {
+    const send = async (input, signal, stream = false) => {
         // 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');
@@ -199,19 +201,32 @@ function createBrokerTransport({ context, principal, token, getRuntime, fetcher,
         if (Buffer.byteLength(body, 'utf8') > maxBodyBytes)
             throw new ArtifactServerError(413, 'request_too_large', 'Server SDK requests are limited to 1 MiB; use Storage uploads for files');
         const runtime = await getRuntime();
-        return fetcher(`${runtime.atlasUrl}${ARTIFACT_SERVER_REQUEST_PATH}`, {
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-                [ARTIFACT_RUNTIME_TOKEN_HEADER]: runtime.sessionToken,
-                [ARTIFACT_REQUEST_CONTEXT_HEADER]: token,
-            },
-            body,
-            cache: 'no-store',
-            redirect: 'error',
-            credentials: 'omit',
-            signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(60_000)]) : AbortSignal.timeout(60_000),
-        });
+        // The timeout covers the whole call, body included, except for a stream: its timer is cleared
+        // once Atlas answers, so a long body isn't cut off mid-read.
+        const expiry = new AbortController();
+        const timer = setTimeout(() => expiry.abort(new DOMException('Atlas did not answer in time', 'TimeoutError')), BROKER_RESPONSE_TIMEOUT_MS);
+        if (!stream)
+            timer.unref?.();
+        const timeout = expiry.signal;
+        try {
+            return await fetcher(`${runtime.atlasUrl}${ARTIFACT_SERVER_REQUEST_PATH}`, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    [ARTIFACT_RUNTIME_TOKEN_HEADER]: runtime.sessionToken,
+                    [ARTIFACT_REQUEST_CONTEXT_HEADER]: token,
+                },
+                body,
+                cache: 'no-store',
+                redirect: 'error',
+                credentials: 'omit',
+                signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
+            });
+        }
+        finally {
+            if (stream)
+                clearTimeout(timer);
+        }
     };
     /**
      * Sends a read again when its connection to Atlas failed before Atlas answered: such failures
@@ -219,10 +234,10 @@ function createBrokerTransport({ context, principal, token, getRuntime, fetcher,
      * 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) } = {}) => {
+    return async (input, { signal, replaySafe = isReadOperation(input), stream = false } = {}) => {
         for (let attempt = 1;; attempt++) {
             try {
-                return await send(input, signal);
+                return await send(input, signal, stream);
             }
             catch (error) {
                 const code = replaySafe && attempt < reconnect.attempts ? transientConnectionCode(error) : null;

package/dist/server/external-context.js

@@ -9,7 +9,7 @@ import { verifyAnyArtifactContext } from './internal/verify-any.js';
 export function verifyArtifactExternalContext({ token, publicKeys, projectId, environment, method, path, accept, now }) {
     if (!method || !path)
         throw new ArtifactContextError();
-    // TODO(C1): canonicalizeIngressPath(path) at the path comparison in internal/verify-any.ts, which the broker shares.
+    // verifyAnyArtifactContext canonicalises `path` (canonicalizeIngressPath) before comparing it.
     const context = verifyAnyArtifactContext({ token, publicKeys, projectId, environment, method, path, now });
     if (context.v !== 2)
         throw new ArtifactContextError('external_context_required');