@sequenceholdings/artifact-studio 0.6.3 → 0.6.6

package/README.md

@@ -64,6 +64,142 @@ deployer provide generic application capabilities; each deployed artifact owns
 its product behavior. Primitive code must not branch on an artifact ID or import
 an application's services. See [Platform primitive boundaries](../../../docs/platform/platform-primitives.md).
 
+## Lattice run lists and collaboration (internal prerelease)
+
+The server entry point remains an **internal** surface. These methods describe
+workspace source awaiting a matching SDK release and platform deployment;
+they are not a newly supported public SDK or direct HTTP contract. See
+[VERSION-PIN.md](./VERSION-PIN.md) for compatibility requirements.
+
+On the request-scoped client returned by `createArtifactServerClient`, declare
+the exact process IDs the application reads or acts on:
+
+```yaml
+server:
+  capabilities:
+    processes:
+      read: [review-process]
+      act: [review-process]
+```
+
+`client.processes.listRunsPage` returns compact summaries for activity lists:
+
+```ts
+const page = await client.processes.listRunsPage({
+  process: 'review-process',
+  statuses: ['pending', 'running'],
+  entity: { type: 'application', ids: ['example-application-1'] },
+  limit: 100,
+})
+// page: { runs: ArtifactProcessRunSummary[], nextCursor: string | null }
+```
+
+Each summary contains `id`, `processId`, `status`, `entityType`, `entityId`,
+`startedAt`, `completedAt` and `error`; it does not fetch run state, output or
+step payloads. Use `getRun` for detail. `statuses` is an optional, nonempty set
+of run statuses. `entity` accepts a type alone, one `id`, or 1–500 `ids`; `id`
+and `ids` are mutually exclusive. `archived: true` selects only archived runs;
+the default excludes them. The existing `listRuns` contract is unchanged.
+
+The caller's run Viewer permission filters the results. `limit` bounds visible
+rows (default 100, maximum 500). Pass `nextCursor` back as `cursor` with the
+same process, status, entity and archive filters; the limit may change. The
+encrypted cursor is bound to the caller and expires after one hour. It is
+returned only when another visible row exists and resumes after the last
+returned visible row. A successful empty page has `nextCursor: null`.
+
+The platform establishes the caller's complete authorization scope before
+selecting run rows. Unavailable authorization, an unsupported authorization
+model, or an incomplete grant scope rejects the call with 503 and no partial
+page. A 503 must not be treated as an empty list. Invalid, expired, or
+filter-mismatched cursors reject with 400. These reads work from read-only and
+stale request contexts.
+
+`client.processes.shareRun` adds collaborators to selected human nodes while
+preserving their existing assignments, and grants those recipients run viewing:
+
+```ts
+const shared = await client.processes.shareRun({
+  runId: 'example-run-1',
+  nodeIds: ['review', 'reopen'],
+  users: ['auth0|example-reviewer'],
+})
+// shared: { run_id, nodes_updated, users, groups, authorization_applied }
+```
+
+This requires `processes.act`, a signed-in human caller, and Owner on the run
+unless the caller explicitly uses an onward-sharing authority below. It is
+refused in service mode, from external callers, and from read-only or stale
+request contexts. Recipients gain full-run viewing, so a node's delegation
+permission alone does not authorize this operation. Authored assignment
+allowlists still constrain owners, and disabled users or deleted groups cannot
+receive access.
+
+Name 1–100 human nodes and 1–100 users and groups combined. Node IDs are
+1–255 characters and cannot contain the reserved `::` separator. Each target
+node must already have an explicit assignment on this run; missing assignments are
+rejected rather than replacing authored or dynamic defaults. Sharing preserves
+existing assignees, is additive on retries, and never adds the caller implicitly.
+Terminal runs are refused with 410. Use `assign` to replace one parked step's
+assignees, or `grantViewers` to grant viewing without participation.
+
+If sharing was saved but authorization delivery is pending, the call rejects
+with 503 and `SHARE_PENDING`. Retry the same share before changing the
+application's own task ownership; an error here does not mean the saved sharing
+intent was rolled back.
+
+### Explicit onward sharing
+
+A run owner can also consent to recipients sharing full-run viewing and the
+same or fewer human nodes onward, within this application's live runtime
+audience:
+
+```ts
+const shared = await client.processes.shareRun({
+  runId: 'example-run-1',
+  nodeIds: ['review', 'reopen'],
+  users: ['auth0|example-reviewer'],
+  delegateSharing: { audience: 'current_app' },
+})
+// Check shared.authorization_applied and shared.sharingAuthorityId before changing task ownership.
+```
+
+This option accepts individual users only; groups cannot receive delegated
+sharing authority. The platform resolves `current_app` from the admitted
+request, and checks the current application audience on every share. The
+authority is pinned to the run, its process bundle and the allowed nodes.
+Each onward recipient remains bounded by that authority and cannot expand the
+audience or node set. Delegates must pass `delegateSharing` explicitly on each
+onward share; omitting it retains the ordinary Owner-only behavior. Owning or
+viewing one human step does not itself grant this authority.
+
+Run owners can inspect and revoke root authorities through the same
+`processes.act` declaration, in user mode:
+
+```ts
+const page = await client.processes.listRunSharingAuthorities({
+  runId: 'example-run-1',
+  limit: 20,
+})
+// Follow page.nextCursor with the same runId until null.
+const authority = page.authorities[0]
+if (authority) {
+  await client.processes.revokeRunSharingAuthority({
+    runId: 'example-run-1',
+    authorityId: authority.id,
+  })
+}
+```
+
+Authority pages default to 20 records, at most 50. Each record includes its
+run, bundle, node scope, application audience, creator, creation/revocation
+timestamps and up to 100 delegates, including who granted each delegation and
+when. Record fields use the platform's snake case; the page exposes
+`nextCursor`. Listing works from stale/read-only contexts; revocation requires
+a current writable request. Revocation is idempotent and returns
+`{ authority_id, revoked: true }`. Revoking a root stops onward sharing through
+every delegate under it; existing run viewing and step participation remain.
+
 ## Lost connections in a Next.js server
 
 The server client (`@sequenceholdings/artifact-studio/server`) sends a read up
@@ -72,12 +208,53 @@ connection was refused or reset, the host or network was unreachable, or a DNS
 lookup failed transiently. It pauses up to 100 ms, then up to 200 ms, and logs a
 `broker.reconnect` warning for each resend. Reads are `client.orm` operations
 the manifest lists with `kind: 'query'`, `client.api` GET and HEAD requests,
-Storage GET and HEAD requests, and flag evaluations. ORM mutations, other API
-methods, Storage writes, function invokes and process starts are sent once,
-because a reset can come after Atlas acted on them, and reject with fetch's
-`TypeError: fetch failed` as before. (Audit delivery keeps its own single
-resend under the same event id.) A response with any status is Atlas's answer
-and is never resent.
+Storage GET and HEAD requests, flag evaluations, and ORM mutations sent with an
+idempotency key (below). Other ORM mutations, other API methods, Storage
+writes, function invokes and process starts are sent once, because a reset can
+come after Atlas acted on them, and reject with fetch's `TypeError: fetch
+failed` as before. (Audit delivery keeps its own single resend under the same
+event id.) A response with any status is Atlas's answer and is never resent.
+To retry an ORM mutation yourself, pass `{ idempotencyKey }` as the third
+argument of `orm(...).execute`; the data plane returns the first attempt's
+receipt for the same key and body (a key on a query is refused).
+
+```ts
+// Mutations only: a key on a manifest-listed query throws 400 `idempotency_key_on_query`.
+await db.execute('SaveApplication', variables, { idempotencyKey: `save:${applicationId}:${draftId}` })
+```
+
+Keys are 1-128 letters, digits, dots, underscores, colons or hyphens; anything
+else throws 400 `invalid_idempotency_key` before a call is made. An Atlas build
+that predates the key rejects it with a 400, so pass one only to an Atlas that
+includes it (see [VERSION-PIN.md](./VERSION-PIN.md)).
+
+## Previewing a retained Storage file in the browser
+
+An Embed app can use the host's shared PDF/image dialog without adding its own
+PDF worker or changing sandbox CSP. Declare the workspace under browser
+`capabilities.storage` with at least `viewer` reach, then call:
+
+```ts
+if (seq.storage.preview) {
+  await seq.storage.preview({ workspaceId, fileId, versionId, filename, mime: 'application/pdf' })
+}
+```
+
+`versionId` is required: previews never silently switch to the latest file.
+The manifest limits reach; it does not grant access. Atlas requests the download
+lease as the signed-in user and Storage checks their permissions and the
+file/version association. No URL or bytes are accepted from the app or returned
+by this method. `filename` and `mime` are display hints; supported MIME types are
+`application/pdf`, `image/jpeg`, `image/png`, `image/gif`, and `image/webp`.
+The promise resolves `{ opened: true }` when the dialog opens; loading/access
+errors appear there. Close and reopen to retry or refresh an expired lease.
+
+Next.js browser integrations can make the same host request through
+`bridge.request({ method: 'storage.preview', args: [input] })`; this is a browser
+UI operation, never a server SDK operation or service-account read. It requires
+an Atlas build with Storage preview support. Older Embed hosts omit
+`seq.storage.preview`; feature-detect it and retain an external-open fallback
+until the host rollout completes. Host/session replacement closes the preview.
 
 ## Calling agents from a Next.js server
 

package/VERSION-PIN.md

@@ -33,16 +33,53 @@ refuse a v2 context, or any token signed with an `external-` kid, with reason
 through `verifyArtifactExternalContext` or `createArtifactServerClient({ accept })`,
 and an external principal reaches platform services only through `asService()`.
 `@sequenceholdings/artifact-studio/server/testing` signs test contexts.
+The server client's `orm(...).execute(op, variables, { idempotencyKey })` sends
+an idempotency key (the data plane's `^[A-Za-z0-9._:-]{1,128}$`) with a
+mutation, so a retry returns the first attempt's receipt; a key on a query is
+refused. Atlas scopes an external caller's key to that caller before the data
+plane sees it, so callers sharing the ingress service identity never share a
+receipt. Because a resend carries the same key and body, the server client also
+resends a keyed mutation once its connection to Atlas fails before an answer,
+as it does a read. Atlas builds without this change reject `idempotencyKey`
+(400); pass a key only once the target Atlas includes it, and publish 0.6.0
+from a commit that contains it.
 0.6.0 also carries `error.atlas` (`{ code, detail }`) on a refused broker call
 (#13398); a step-up 401 still surfaces as `insufficient_user_authentication`.
 
 0.6.0 also accepts the `server.ingress` manifest block. Earlier CLIs and Atlas
 versions parse the server block strictly and reject the key, so an app that
-declares an ingress needs 0.6.0 on both sides; that failure is closed. An
+declares an ingress needs 0.6.0 on both sides; that failure is closed.
+An ingress names every ORM operation the application may run through the
+broker for an external caller: reads in `capabilities.data.operations` and
+writes in `capabilities.data.write`, each as `namespace/ops/<Operation>` (no
+globs, in a namespace the ingress's own data reaches). Atlas refuses an
+external caller's call to any other persisted operation, query or mutation,
+with 403 `operation_not_allowed`, before the data plane's table check;
+`data.operations` defaults to none, so an ingress that lists no reads runs no
+queries. The list does not bound a Managed Function the ingress invokes: that
+function runs with its own data credential. User and v1 service-mode calls
+keep table-set admission. An
 external context binds the canonical route path (`server/ingress-routes`): a
 handler's `path` is canonicalised the same way before it is compared, and a
 signed path that is not canonical is refused.
 
+An external context in `development` mode (local `artifact dev` only) is
+accepted only when the runtime configuration came from a development lease:
+the owner-only file `artifact dev` names in `SEQUENCE_ARTIFACT_RUNTIME_FILE`,
+exposed as `runtimeConfig.development === true`, and only for that lease's
+session. The marker is never parsed from JSON, so a hosted runtime
+(`SEQUENCE_ARTIFACT_RUNTIME_CONFIG`), the lease file's content and an explicit
+`runtime` option all refuse development contexts. A gateway proxies a
+development target only when its own `APP_ENV` is `development`.
+
+Over the development tunnel the app sees the ingress host as `host` and
+`x-forwarded-host`, as it sees the ingress origin on a hosted release: the
+broker sets it, and the tunnel client keeps it only on a frame whose context is
+signed by an `external-` kid. A tunnel client from an SDK before this change
+pins every request, ingress ones included, to the session origin
+(`<session>.apps.localhost`), so app code that builds absolute URLs from the
+host behaves differently locally until the CLI is upgraded.
+
 Context version policy: a context verifier rejects any unknown top-level or
 `principal` key unless it sits under `ext` or is named in `crit` (and `crit`
 names only extensions the verifier understands; today none, so it is empty).
@@ -57,6 +94,24 @@ before publication; an ordinary released CLI intentionally cannot.
 The React/Vite starter therefore uses released primitives and responsive CSS
 until that pin advances. Its build test exercises the ordinary CLI toolchain.
 
+## Unreleased server process additions
+
+Workspace source adds `processes.listRunsPage` (visible, paginated run summaries)
+and `processes.shareRun` (additive collaboration on explicitly assigned human
+nodes, with owner-consented onward sharing scoped to the current application).
+The owner-only `listRunSharingAuthorities` and `revokeRunSharingAuthority`
+methods inspect and stop that onward authority. These methods need an SDK
+published from this change and a target platform deployment containing their
+matching handlers. An SDK version string
+alone does not establish that the deployed platform supports them; earlier
+platform builds reject the new operations. See the SDK README for their input,
+pagination, authorization and retry contracts.
+
+These additions use the existing `./server` and `./server/broker-contract`
+entry points, which remain classified **internal**. They add no package export
+subpath or supported direct HTTP surface. Publication and a reviewed public
+contract decision are separate from local build verification.
+
 ## What this means
 
 `shared/services/artifact-studio/src/build.ts` force-aliases platform peers via

package/dist/gateway/admission.d.ts

@@ -37,6 +37,22 @@ export declare class ArtifactAdmissionError extends Error {
     readonly retryAfterSeconds?: number | undefined;
     constructor(status: 429 | 503, code: 'capacity_exceeded' | 'admission_unavailable', retryAfterSeconds?: number | undefined);
 }
+/** Per-request concurrency an external ingress adds on top of the app's (design "Steady state" step 7). */
+export declare const INGRESS_CONCURRENCY: Readonly<{
+    perSubject: 4;
+    perClient: 8;
+    appShare: 0.5;
+}>;
+/** An external ingress request: its share of the app, and per subject and client caps. */
+export interface AdmissionIngress {
+    id: string;
+    /** `sha256(subject)`, lowercase hex. */
+    subjectHash: string;
+    /** `ingressClientBucket(clientIp)`. */
+    clientBucket: string;
+}
+/** The ingress's share of the app: half its capacity, and never zero. */
+export declare function ingressConcurrencyShare(appMaximum: number): number;
 /** Fail-closed admission with no command retries. An uncertain acquisition is
  * never used; its unique permit expires even if Redis accepted it before loss. */
 export declare class ArtifactRequestAdmission {
@@ -51,6 +67,12 @@ export declare class ArtifactRequestAdmission {
             kind: 'admission_release_failed' | 'admission_timeout_callback_failed';
         }) => void;
     });
-    acquire(target: AdmissionTarget): Promise<AdmissionLease>;
+    /**
+     * `ingress` adds the external ingress keys: the ingress's share of the app, 4 per subject and 8
+     * per client bucket, in the same atomic acquisition as the app and deployment keys.
+     */
+    acquire(target: AdmissionTarget, { ingress }?: {
+        ingress?: AdmissionIngress;
+    }): Promise<AdmissionLease>;
 }
 export {};

package/dist/gateway/admission.js

@@ -1,7 +1,7 @@
-import { randomUUID } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { performance } from 'node:perf_hooks';
 import { z } from 'zod';
-import { artifactNextResourceLimitsSchema } from '../manifest-next.js';
+import { artifactNextIngressIdSchema, artifactNextResourceLimitsSchema } from '../manifest-next.js';
 import { redisNamespaceSchema } from '../tunnel/redis-ownership.js';
 export class ArtifactAdmissionError extends Error {
     status;
@@ -24,16 +24,16 @@ const resources = z.object({
     max_instances: resourceFields.max_instances,
     timeout_seconds: resourceFields.timeout_seconds,
 });
-// Both keys have the same Redis Cluster hash tag. A lease can never exist in
-// only one set, and previews/retained releases consume the same application cap.
-const ACQUIRE = `-- artifact-request-admission-acquire-v1
+// Every key has the same Redis Cluster hash tag. A lease can never exist in only some of the sets,
+// and previews/retained releases consume the same application cap. ARGV[2..n+1] are the per-key
+// maxima (an ingress shares the app's capacity with stricter keys of its own); ARGV[n+2] the timeout.
+const ACQUIRE = `-- artifact-request-admission-acquire-v2
 local time = redis.call('TIME')
 local now = tonumber(time[1]) * 1000 + math.floor(tonumber(time[2]) / 1000)
-local maximum = tonumber(ARGV[2])
-local deadline = now + tonumber(ARGV[3])
-for _, key in ipairs(KEYS) do
+local deadline = now + tonumber(ARGV[#KEYS + 2])
+for index, key in ipairs(KEYS) do
   redis.call('ZREMRANGEBYSCORE', key, '-inf', now)
-  if redis.call('ZCARD', key) >= maximum then return {0, now} end
+  if redis.call('ZCARD', key) >= tonumber(ARGV[index + 1]) then return {0, now} end
 end
 for _, key in ipairs(KEYS) do
   redis.call('ZADD', key, deadline, ARGV[1])
@@ -41,6 +41,13 @@ for _, key in ipairs(KEYS) do
   redis.call('PEXPIRE', key, tonumber(latest[2]) - now + 1000)
 end
 return {1, deadline}`;
+/** Per-request concurrency an external ingress adds on top of the app's (design "Steady state" step 7). */
+export const INGRESS_CONCURRENCY = Object.freeze({ perSubject: 4, perClient: 8, appShare: 0.5 });
+/** The ingress's share of the app: half its capacity, and never zero. */
+export function ingressConcurrencyShare(appMaximum) {
+    return Math.max(1, Math.floor(INGRESS_CONCURRENCY.appShare * appMaximum));
+}
+const subjectHashSchema = z.string().regex(/^[0-9a-f]{64}$/);
 const RELEASE = `-- artifact-request-admission-release-v1
 for _, key in ipairs(KEYS) do
   redis.call('ZREM', key, ARGV[1])
@@ -62,7 +69,11 @@ export class ArtifactRequestAdmission {
             throw new Error('Admission Redis must disable offline queues, command replay and retries');
         }
     }
-    async acquire(target) {
+    /**
+     * `ingress` adds the external ingress keys: the ingress's share of the app, 4 per subject and 8
+     * per client bucket, in the same atomic acquisition as the app and deployment keys.
+     */
+    async acquire(target, { ingress } = {}) {
         if (namespace.parse(target.environment) !== this.namespace)
             throw new Error('Admission environment mismatch');
         const projectId = identifier.parse(target.projectId), deploymentId = identifier.parse(target.deploymentId);
@@ -71,11 +82,17 @@ export class ArtifactRequestAdmission {
         const timeoutMs = limits.timeout_seconds * 1000;
         const requestId = randomUUID();
         const prefix = `artifact-admission:${this.namespace}:{${this.namespace}:${projectId}}`;
-        const keys = [`${prefix}:app`, `${prefix}:deployment:${deploymentId}`];
+        const keyed = [[`${prefix}:app`, maximum], [`${prefix}:deployment:${deploymentId}`, maximum]];
+        if (ingress) {
+            const id = artifactNextIngressIdSchema.parse(ingress.id), subject = subjectHashSchema.parse(ingress.subjectHash).slice(0, 16);
+            const client = createHash('sha256').update(z.string().min(1).max(64).parse(ingress.clientBucket)).digest('hex').slice(0, 16);
+            keyed.push([`${prefix}:ingress:${id}`, ingressConcurrencyShare(maximum)], [`${prefix}:ingress:${id}:subject:${subject}`, INGRESS_CONCURRENCY.perSubject], [`${prefix}:ingress:${id}:client:${client}`, INGRESS_CONCURRENCY.perClient]);
+        }
+        const keys = keyed.map(([key]) => key);
         const began = performance.now();
         let result;
         try {
-            result = z.tuple([z.number().int().min(0).max(1), z.number().int().positive()]).parse(await this.options.redis.eval(ACQUIRE, 2, ...keys, requestId, maximum, timeoutMs));
+            result = z.tuple([z.number().int().min(0).max(1), z.number().int().positive()]).parse(await this.options.redis.eval(ACQUIRE, keys.length, ...keys, requestId, ...keyed.map(([, max]) => max), timeoutMs));
         }
         catch {
             throw new ArtifactAdmissionError(503, 'admission_unavailable');
@@ -93,7 +110,7 @@ export class ArtifactRequestAdmission {
             cleanup?.();
             // Repeated finish/close/error notifications must never free another
             // request's permit, nor cause a failed command to be retried.
-            releasePromise ??= this.options.redis.eval(RELEASE, 2, ...keys, requestId).then(() => undefined, () => { throw new ArtifactAdmissionError(503, 'admission_unavailable'); });
+            releasePromise ??= this.options.redis.eval(RELEASE, keys.length, ...keys, requestId).then(() => undefined, () => { throw new ArtifactAdmissionError(503, 'admission_unavailable'); });
             return releasePromise;
         };
         const releaseQuietly = () => {

package/dist/gateway/control.d.ts

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import type { TunnelLease } from '../tunnel/index.js';
 import type { GatewaySession } from './session.js';
 import type { GatewayUsageEvent } from './usage.js';
+import { type IngressAuditBatch, type IngressExchangeRequest, type IngressExchangeResponse, type IngressGrantRequest, type IngressGrantResponse, type IngressRevokeRequest, type IngressSnapshot } from '../server/ingress-control-contract.js';
 export declare const gatewayTargetSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"development">;
     sessionId: z.ZodString;
@@ -36,6 +37,10 @@ export declare const gatewayTargetSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     frameworkBuildId: z.ZodString;
     upstreamUrl: z.ZodString;
     upstreamAudience: z.ZodOptional<z.ZodString>;
+    runtimeTransport: z.ZodOptional<z.ZodEnum<{
+        "cloud-run": "cloud-run";
+        "local-docker": "local-docker";
+    }>>;
     active: z.ZodBoolean;
     published: z.ZodOptional<z.ZodBoolean>;
     projectId: z.ZodString;
@@ -70,6 +75,10 @@ declare const latticeInvokeGrantSchema: z.ZodObject<{
     frameworkBuildId: z.ZodString;
     upstreamUrl: z.ZodString;
     upstreamAudience: z.ZodOptional<z.ZodString>;
+    runtimeTransport: z.ZodOptional<z.ZodEnum<{
+        "cloud-run": "cloud-run";
+        "local-docker": "local-docker";
+    }>>;
     publicOrigin: z.ZodString;
     environment: z.ZodString;
     principalSub: z.ZodString;
@@ -86,6 +95,26 @@ export declare class GatewayControlError extends Error {
     readonly status: number;
     constructor(status: number);
 }
+/** Codes an ingress control route may answer with (design §(i)), and the status each one carries. */
+declare const INGRESS_CONTROL_CODES: {
+    readonly invalid_token: 401;
+    readonly exchange_denied: 403;
+    readonly not_found: 404;
+    readonly rate_limited: 429;
+    readonly temporarily_unavailable: 503;
+};
+export type IngressControlCode = keyof typeof INGRESS_CONTROL_CODES;
+/**
+ * A refusal an ingress control route decided: its contract code and Atlas's `Retry-After`, so the
+ * gateway answers the caller with Atlas's decision instead of inventing one. `code` is null when the
+ * response named no contract code matching its status (a misconfigured control token, a bare 500):
+ * the gateway then answers 503, never a code that would send the client into a sign-in loop.
+ */
+export declare class IngressControlError extends GatewayControlError {
+    readonly code: IngressControlCode | null;
+    readonly retryAfterSeconds?: number | undefined;
+    constructor(status: number, code: IngressControlCode | null, retryAfterSeconds?: number | undefined);
+}
 export declare class ArtifactGatewayControl {
     private readonly options;
     private readonly origin;
@@ -95,6 +124,17 @@ export declare class ArtifactGatewayControl {
         fetch?: typeof fetch;
     });
     private call;
+    private send;
+    /** Every enabled ingress host (GET, at most 1 MiB); the gateway pulls it on a timer, never per request. */
+    ingressSnapshot(): Promise<IngressSnapshot>;
+    /** Verifies an identity provider's token for an ingress; refusals carry Atlas's contract code. */
+    ingressExchange(body: IngressExchangeRequest): Promise<IngressExchangeResponse>;
+    /** Re-checks one ingress request against the active deployment and returns where to proxy it. */
+    ingressGrant(body: IngressGrantRequest): Promise<IngressGrantResponse>;
+    /** Logout: revokes every identity provider token the subject was issued up to Atlas's now. */
+    ingressRevoke(body: IngressRevokeRequest): Promise<void>;
+    /** One batch of refusals the gateway decided locally (Atlas audits the ones it decided itself). */
+    ingressAudit(body: IngressAuditBatch): Promise<void>;
     /** One idempotent batch; Atlas reports events it refused (for example, a retired target). */
     usage(events: GatewayUsageEvent[]): Promise<{
         rejected: number;

package/dist/gateway/control.js

@@ -3,6 +3,7 @@ import { z } from 'zod';
 import { normalizePublicOrigin } from '../tunnel/protocol.js';
 import { artifactRequestContextSchema } from '../server/request-context.js';
 import { artifactNextFrameworkBuildIdSchema } from '../runtime-contracts.js';
+import { INGRESS_SNAPSHOT_MAX_BYTES, ingressExchangeResponseSchema, ingressGrantResponseSchema, ingressSnapshotSchema, } from '../server/ingress-control-contract.js';
 const id = z.string().min(1).max(255);
 const base = {
     projectId: id, ownerId: id, environment: id, publicOrigin: z.string().transform(normalizePublicOrigin),
@@ -17,7 +18,7 @@ const base = {
 };
 export const gatewayTargetSchema = z.discriminatedUnion('kind', [
     z.object({ ...base, kind: z.literal('development'), sessionId: id, epoch: z.number().int().positive() }),
-    z.object({ ...base, kind: z.literal('hosted'), deploymentId: id, frameworkBuildId: artifactNextFrameworkBuildIdSchema, upstreamUrl: z.string().url(), upstreamAudience: z.string().url().optional(), active: z.boolean(), published: z.boolean().optional() }),
+    z.object({ ...base, kind: z.literal('hosted'), deploymentId: id, frameworkBuildId: artifactNextFrameworkBuildIdSchema, upstreamUrl: z.string().url(), upstreamAudience: z.string().url().optional(), runtimeTransport: z.enum(['cloud-run', 'local-docker']).optional(), active: z.boolean(), published: z.boolean().optional() }),
 ]);
 const bootstrapSchema = z.object({ parentOrigin: z.string().transform(normalizePublicOrigin), channelId: id, nonce: z.string().min(16).max(255) });
 const usageResultSchema = z.object({ rejected: z.number().int().nonnegative() });
@@ -27,6 +28,7 @@ const latticeInvokeGrantSchema = z.object({
     frameworkBuildId: artifactNextFrameworkBuildIdSchema,
     upstreamUrl: z.string().url(),
     upstreamAudience: z.string().url().optional(),
+    runtimeTransport: z.enum(['cloud-run', 'local-docker']).optional(),
     publicOrigin: z.string().min(1).max(2048),
     environment: id,
     principalSub: id,
@@ -46,6 +48,49 @@ export class GatewayControlError extends Error {
         this.name = 'GatewayControlError';
     }
 }
+/** Codes an ingress control route may answer with (design §(i)), and the status each one carries. */
+const INGRESS_CONTROL_CODES = { invalid_token: 401, exchange_denied: 403, not_found: 404, rate_limited: 429, temporarily_unavailable: 503 };
+const INGRESS_ERROR_BODY_MAX_BYTES = 4096;
+function isIngressControlCode(value) {
+    return Object.hasOwn(INGRESS_CONTROL_CODES, value);
+}
+/**
+ * A refusal an ingress control route decided: its contract code and Atlas's `Retry-After`, so the
+ * gateway answers the caller with Atlas's decision instead of inventing one. `code` is null when the
+ * response named no contract code matching its status (a misconfigured control token, a bare 500):
+ * the gateway then answers 503, never a code that would send the client into a sign-in loop.
+ */
+export class IngressControlError extends GatewayControlError {
+    code;
+    retryAfterSeconds;
+    constructor(status, code, retryAfterSeconds) {
+        super(status);
+        this.code = code;
+        this.retryAfterSeconds = retryAfterSeconds;
+        this.name = 'IngressControlError';
+    }
+}
+/** The contract code of a refused control response, read from at most 4 KiB of its JSON body. */
+async function ingressRefusal(response) {
+    const retryAfter = Number(response.headers.get('retry-after'));
+    const retryAfterSeconds = Number.isSafeInteger(retryAfter) && retryAfter > 0 && retryAfter <= 3600 ? retryAfter : undefined;
+    let code = null;
+    try {
+        const length = Number(response.headers.get('content-length'));
+        const text = length > INGRESS_ERROR_BODY_MAX_BYTES ? '' : (await response.text()).slice(0, INGRESS_ERROR_BODY_MAX_BYTES);
+        const parsed = z.object({ error: z.string() }).safeParse(JSON.parse(text));
+        const named = parsed.success && isIngressControlCode(parsed.data.error) ? parsed.data.error : null;
+        // A code is believed only with the status the contract gives it.
+        code = named !== null && INGRESS_CONTROL_CODES[named] === response.status ? named : null;
+    }
+    catch {
+        code = null;
+    }
+    finally {
+        await response.body?.cancel().catch(() => undefined);
+    }
+    return new IngressControlError(response.status, code, retryAfterSeconds);
+}
 export class ArtifactGatewayControl {
     options;
     origin;
@@ -55,15 +100,19 @@ export class ArtifactGatewayControl {
         if (options.token.length < 32)
             throw new Error('Artifact control plane token requires at least 32 characters');
     }
-    async call(path, body, timeoutMs = 10_000) {
+    call(path, body, timeoutMs = 10_000) {
+        return this.send({ path, body, timeoutMs, maxBytes: 128 * 1024 });
+    }
+    async send({ path, body, timeoutMs, maxBytes, ingress = false }) {
         const response = await (this.options.fetch ?? fetch)(`${this.origin}/api/artifact-studio/next/control/${path}`, {
-            method: 'POST', headers: { authorization: `Bearer ${this.options.token}`, 'content-type': 'application/json' },
-            body: JSON.stringify(body), signal: AbortSignal.timeout(timeoutMs), redirect: 'error',
+            method: body === undefined ? 'GET' : 'POST',
+            headers: { authorization: `Bearer ${this.options.token}`, ...(body === undefined ? {} : { 'content-type': 'application/json' }) },
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }), signal: AbortSignal.timeout(timeoutMs), redirect: 'error',
         });
         if (!response.ok)
-            throw new GatewayControlError(response.status);
+            throw ingress ? await ingressRefusal(response) : new GatewayControlError(response.status);
         const contentLength = Number(response.headers.get('content-length'));
-        if (contentLength > 128 * 1024) {
+        if (contentLength > maxBytes) {
             await response.body?.cancel();
             throw new GatewayControlError(502);
         }
@@ -78,7 +127,7 @@ export class ArtifactGatewayControl {
                 if (done)
                     break;
                 length += value.length;
-                if (length > 128 * 1024)
+                if (length > maxBytes)
                     throw new GatewayControlError(502);
                 chunks.push(value);
             }
@@ -88,6 +137,26 @@ export class ArtifactGatewayControl {
             await reader.cancel().catch(() => undefined);
         }
     }
+    /** Every enabled ingress host (GET, at most 1 MiB); the gateway pulls it on a timer, never per request. */
+    async ingressSnapshot() {
+        return ingressSnapshotSchema.parse(await this.send({ path: 'ingress-snapshot', timeoutMs: 10_000, maxBytes: INGRESS_SNAPSHOT_MAX_BYTES }));
+    }
+    /** Verifies an identity provider's token for an ingress; refusals carry Atlas's contract code. */
+    async ingressExchange(body) {
+        return ingressExchangeResponseSchema.parse(await this.send({ path: 'ingress-exchange', body, timeoutMs: 10_000, maxBytes: 16 * 1024, ingress: true }));
+    }
+    /** Re-checks one ingress request against the active deployment and returns where to proxy it. */
+    async ingressGrant(body) {
+        return ingressGrantResponseSchema.parse(await this.send({ path: 'ingress-grant', body, timeoutMs: 10_000, maxBytes: 16 * 1024, ingress: true }));
+    }
+    /** Logout: revokes every identity provider token the subject was issued up to Atlas's now. */
+    async ingressRevoke(body) {
+        await this.send({ path: 'ingress-revoke', body, timeoutMs: 10_000, maxBytes: 16 * 1024, ingress: true });
+    }
+    /** One batch of refusals the gateway decided locally (Atlas audits the ones it decided itself). */
+    async ingressAudit(body) {
+        await this.send({ path: 'ingress-audit', body, timeoutMs: 5_000, maxBytes: 16 * 1024, ingress: true });
+    }
     /** One idempotent batch; Atlas reports events it refused (for example, a retired target). */
     async usage(events) {
         const value = await this.call('usage', { events }, 5_000);