@sequenceholdings/artifact-studio 0.6.7 → 0.7.1

package/README.md

@@ -5,6 +5,28 @@ requests use the current user's normal permissions.
 
 ## Governed ORM operations
 
+### Default SQL (planned SDK 0.7.0)
+
+With the matching Atlas runtime, no operation manifest or registration is needed
+for read-only runtime SQL:
+
+```ts
+const orm = createArtifactOrmExecutor({ namespace: 'lending' })
+const result = await orm.sql({
+  sql: `SELECT l.id, c.name FROM lending.loans l
+    JOIN party.customers c ON c.id = l."customerId"`,
+})
+```
+
+Keep the namespace bridge path declaration below. Caller permissions, row
+policies, foreign export gates and optional ontology consumer contracts still
+apply. Results contain `columns`, array-valued `rows`, and `truncated`; exact
+numeric/bigint values are strings. Queries are capped at 1,000 rows / 8 MiB.
+This prerelease source requires package publication and the matching server
+rollout. The generated-manifest path below remains backward-compatible.
+
+### Registered operations
+
 Use the published caller-aware adapter inside an Artifact Studio Preview or a
 deployed artifact. Generate and apply the namespace first, then import its
 `operations.manifest.json` into your application:
@@ -73,7 +95,10 @@ queries still need every table they read, and mutations still need write reach.
 The Next.js host routes ORM requests through this data contract; no additional
 API path declaration is needed. The POST transport does not grant mutation authority.
 
-The allowlist admits registered persisted operations only. Autogenerated
+The allowlist admits registered persisted operations and the server-owned
+`<namespace>/ops/BuiltinSqlRead` identity when explicitly listed. Default SQL
+still needs all of its table read reach and caller policies; listing it does
+not grant arbitrary database access. Autogenerated
 `DatasetPreview_*` hashes are excluded even if a registered operation has the
 same name. Operation admission retains the existing active and previous
 operation-set fallback; the allowlist pins names, not one content hash. Give a

package/dist/cli.js

@@ -58,12 +58,10 @@ const USAGE = `usage:
   trees; feature branches and dirty source trees remain preview-only for
   deployed environments (\`artifact dev\` / preview channel).
 
-  Interactive --repo builds clone over smart-HTTP and require a repo:read git
-  PAT in ATLAS_GIT_PAT — create one with \`seq-studio auth pat create --scopes
-  repo:read\` or in Atlas → Settings → Tokens. Headless M2M builds use JSON
-  materialize and accept only platform-managed --repo sources. (--env +
-  seq-studio login are still needed to resolve the repo and upload the
-  deployment.)
+  Interactive --repo builds clone over smart-HTTP using your seq-studio login
+  and repository read access. No PAT is needed. Headless M2M builds use JSON
+  materialize and accept only platform-managed --repo sources. Use --env to
+  select the same environment for source and deployment.
 
   Next.js: init --template nextjs, then pnpm install with Node.js 24. dev starts
   a local Next server and an owner-only Atlas preview tunnel (no cloud credentials).

package/dist/gateway/abort.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Settles with `work`, or rejects with the signal's reason as soon as it aborts. For work
+ * that cannot itself be cancelled (google-auth-library token refreshes): the caller stops
+ * waiting at its deadline, and the abandoned work still settles, with its rejection handled.
+ */
+export declare function untilAborted<T>(work: Promise<T>, signal: AbortSignal): Promise<T>;

package/dist/gateway/abort.js

@@ -0,0 +1,16 @@
+/**
+ * Settles with `work`, or rejects with the signal's reason as soon as it aborts. For work
+ * that cannot itself be cancelled (google-auth-library token refreshes): the caller stops
+ * waiting at its deadline, and the abandoned work still settles, with its rejection handled.
+ */
+export function untilAborted(work, signal) {
+    if (signal.aborted) {
+        work.catch(() => undefined);
+        return Promise.reject(signal.reason);
+    }
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(signal.reason);
+        signal.addEventListener('abort', onAbort, { once: true });
+        work.then((value) => { signal.removeEventListener('abort', onAbort); resolve(value); }, (error) => { signal.removeEventListener('abort', onAbort); reject(error); });
+    });
+}

package/dist/gateway/authorization-cache.d.ts

@@ -10,6 +10,10 @@ type Lookup<T> = {
     load: () => Promise<T>;
     notAfter: (value: T) => number;
 };
+export type SeedReservation = {
+    readonly sequence: number;
+    readonly askedAt: number;
+};
 /**
  * Per-process, positive-only decision cache with single-flight loading: the burst of chunk
  * requests behind one page load costs one control-plane call per gateway replica per window.
@@ -31,11 +35,31 @@ export declare class PositiveDecisionCache<T> {
     });
     /** `notAfter` bounds the entry by the decision's own validity, such as a session's expiry. */
     get(lookup: Lookup<T>): Promise<T>;
+    /** The decision source is observed without another lookup or a wrapper around its promise. */
+    getObserved(lookup: Lookup<T>): {
+        promise: Promise<T>;
+        source: 'hit' | 'shared' | 'load';
+    };
     /**
      * Always asks the source, for decisions that must be current (a mutation). An allow refreshes the
      * cached entry; a refusal evicts it and fences older lookups, so the next read asks again too.
      */
     refresh(lookup: Lookup<T>): Promise<T>;
+    /**
+     * Places a question asked through another call, such as a ticket exchange, in this cache's order.
+     * Reserve before asking, then {@link seed} the answer.
+     */
+    reserve(): SeedReservation;
+    /**
+     * Stores an allow returned for a {@link reserve}d question. It ages from when that question was
+     * asked, and an answer asked later for the same key, a refusal included, is never replaced by it.
+     */
+    seed({ key, value, asked, notAfter }: {
+        key: string;
+        value: T;
+        asked: SeedReservation;
+        notAfter: (value: T) => number;
+    }): void;
     clear(): void;
     private ask;
     private record;

package/dist/gateway/authorization-cache.js

@@ -31,13 +31,17 @@ export class PositiveDecisionCache {
     }
     /** `notAfter` bounds the entry by the decision's own validity, such as a session's expiry. */
     get(lookup) {
+        return this.getObserved(lookup).promise;
+    }
+    /** The decision source is observed without another lookup or a wrapper around its promise. */
+    getObserved(lookup) {
         const cached = this.entries.get(lookup.key);
         if (cached && !cached.refused && cached.expiresAt > this.now())
-            return Promise.resolve(cached.value);
+            return { promise: Promise.resolve(cached.value), source: 'hit' };
         const inFlight = this.pending.get(lookup.key);
         if (inFlight)
-            return inFlight.promise;
-        return this.ask({ lookup, share: true });
+            return { promise: inFlight.promise, source: 'shared' };
+        return { promise: this.ask({ lookup, share: true }), source: 'load' };
     }
     /**
      * Always asks the source, for decisions that must be current (a mutation). An allow refreshes the
@@ -46,6 +50,20 @@ export class PositiveDecisionCache {
     refresh(lookup) {
         return this.ask({ lookup, share: false });
     }
+    /**
+     * Places a question asked through another call, such as a ticket exchange, in this cache's order.
+     * Reserve before asking, then {@link seed} the answer.
+     */
+    reserve() {
+        return { sequence: ++this.sequence, askedAt: this.now() };
+    }
+    /**
+     * Stores an allow returned for a {@link reserve}d question. It ages from when that question was
+     * asked, and an answer asked later for the same key, a refusal included, is never replaced by it.
+     */
+    seed({ key, value, asked, notAfter }) {
+        this.record({ key, entry: { sequence: asked.sequence, refused: false, value, expiresAt: Math.min(asked.askedAt + this.ttlMs, notAfter(value)) } });
+    }
     clear() {
         this.entries.clear();
         this.pending.clear();

package/dist/gateway/bootstrap-page.d.ts

@@ -0,0 +1,16 @@
+import type { ServerResponse } from 'node:http';
+/**
+ * Where the frame lands once the ticket is exchanged: the host's deep link when it is a path on
+ * this origin, else the application root. Landing on the route directly spares the application a
+ * root render (and any root redirect) followed by a client navigation once the bridge connects.
+ * Returns the validated absolute URL, never a path the browser would parse again: a path that
+ * normalizes to `//host` would otherwise read as protocol-relative and leave the application.
+ * The page embeds this function's source, so it must stay self-contained.
+ */
+export declare function bootstrapLandingUrl(route: string | null, origin: string): string;
+/** The bootstrap ticket travels in a fragment and a POST body, never a request URL or log. The page
+ * exchanges it only inside the Atlas frame; browsers without Fetch Metadata are covered by the script check. */
+export declare function bootstrapPage({ response, parentOrigin }: {
+    response: ServerResponse;
+    parentOrigin: string;
+}): void;

package/dist/gateway/bootstrap-page.js

@@ -0,0 +1,42 @@
+import { randomBytes } from 'node:crypto';
+/**
+ * Where the frame lands once the ticket is exchanged: the host's deep link when it is a path on
+ * this origin, else the application root. Landing on the route directly spares the application a
+ * root render (and any root redirect) followed by a client navigation once the bridge connects.
+ * Returns the validated absolute URL, never a path the browser would parse again: a path that
+ * normalizes to `//host` would otherwise read as protocol-relative and leave the application.
+ * The page embeds this function's source, so it must stay self-contained.
+ */
+export function bootstrapLandingUrl(route, origin) {
+    const root = origin + '/';
+    if (typeof route !== 'string' || route.length > 2048 || !route.startsWith('/') || route.startsWith('//') || route.includes('\\'))
+        return root;
+    try {
+        const url = new URL(route, origin);
+        if (url.origin !== origin || url.pathname.startsWith('//') || url.pathname.startsWith('/_sequence'))
+            return root;
+        return url.href;
+    }
+    catch {
+        return root;
+    }
+}
+/**
+ * Transparent while it connects, so the frame keeps the host's own background through the exchange
+ * and the redirect (a white page reading "Connecting" flashed between Atlas and the app). Only a
+ * failure is shown, on its own light card so it reads over either host theme.
+ */
+const BOOTSTRAP_STYLE = 'html,body{margin:0;height:100%;background:transparent}'
+    + 'body{display:flex;align-items:center;justify-content:center;font:14px/1.4 system-ui,sans-serif}'
+    + '#status:empty{display:none}#status{margin:16px;padding:12px 16px;border-radius:8px;background:#fff;color:#27272a;box-shadow:0 1px 3px rgba(0,0,0,.2)}';
+/** The bootstrap ticket travels in a fragment and a POST body, never a request URL or log. The page
+ * exchanges it only inside the Atlas frame; browsers without Fetch Metadata are covered by the script check. */
+export function bootstrapPage({ response, parentOrigin }) {
+    const nonce = randomBytes(24).toString('base64');
+    response.writeHead(200, {
+        'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store', 'referrer-policy': 'no-referrer',
+        'x-content-type-options': 'nosniff',
+        'content-security-policy': `default-src 'none'; script-src 'nonce-${nonce}'; style-src 'nonce-${nonce}'; connect-src 'self'; frame-ancestors ${parentOrigin}; base-uri 'none'; form-action 'none'`,
+    });
+    response.end(`<!doctype html><meta charset="utf-8"><title>Opening application</title><style nonce="${nonce}">${BOOTSTRAP_STYLE}</style><p id="status" role="status"></p><script nonce="${nonce}">(() => {const landing=${bootstrapLandingUrl.toString()};const fragment=new URLSearchParams(location.hash.slice(1));const ticket=fragment.get('ticket');history.replaceState(null,'',location.pathname);if(!ticket||window.top===window){document.getElementById('status').textContent='Open this application from Atlas.';return;}fetch('/_sequence/session',{method:'POST',credentials:'same-origin',headers:{'content-type':'application/json'},body:JSON.stringify({ticket})}).then(r=>{if(!r.ok)throw new Error();location.replace(landing(fragment.get('route'),location.origin));}).catch(()=>{document.getElementById('status').textContent='This preview expired. Open it again from Atlas.';});})();</script>`);
+}

package/dist/gateway/control-config.d.ts

@@ -0,0 +1,21 @@
+import type { GatewayControlIdentity } from './control.js';
+export interface GatewayControlConfig {
+    /** Where the gateway calls Atlas: its public origin, or its private Cloud Run address. */
+    url: string;
+    /** The Atlas origin allowed to frame applications. */
+    parentOrigin: string;
+    /** Absent only for a local gateway: the shared control token authenticates its calls. */
+    identity?: GatewayControlIdentity;
+}
+/**
+ * A deployed gateway presents its service account's identity token, the only gateway
+ * credential a deployed Atlas accepts. A local gateway has no metadata server to mint one,
+ * so it presents the shared control token, which only a local Atlas accepts. Cloud Run sets
+ * K_SERVICE, so a mislabelled deployment never falls back to the shared token. The token's
+ * audience is the parent origin's control path: the public origin Atlas also derives it
+ * from, whichever address the call is routed to.
+ */
+export declare function resolveGatewayControlConfig({ env, identityToken }: {
+    env: NodeJS.ProcessEnv;
+    identityToken: GatewayControlIdentity['token'];
+}): GatewayControlConfig;

package/dist/gateway/control-config.js

@@ -0,0 +1,18 @@
+import { artifactNextControlAudience } from '../runtime-contracts.js';
+/**
+ * A deployed gateway presents its service account's identity token, the only gateway
+ * credential a deployed Atlas accepts. A local gateway has no metadata server to mint one,
+ * so it presents the shared control token, which only a local Atlas accepts. Cloud Run sets
+ * K_SERVICE, so a mislabelled deployment never falls back to the shared token. The token's
+ * audience is the parent origin's control path: the public origin Atlas also derives it
+ * from, whichever address the call is routed to.
+ */
+export function resolveGatewayControlConfig({ env, identityToken }) {
+    const url = env.ARTIFACT_NEXT_CONTROL_PLANE_URL?.trim();
+    if (!url)
+        throw new Error('Missing required gateway configuration: ARTIFACT_NEXT_CONTROL_PLANE_URL');
+    const parentOrigin = env.ARTIFACT_NEXT_PARENT_ORIGIN?.trim() || new URL(url).origin;
+    if (env.APP_ENV === 'development' && !env.K_SERVICE)
+        return { url, parentOrigin };
+    return { url, parentOrigin, identity: { audience: artifactNextControlAudience(parentOrigin), token: identityToken } };
+}

package/dist/gateway/control.d.ts

@@ -67,6 +67,36 @@ export declare const gatewayTargetSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             }, z.core.$strip>;
         }, z.core.$strip>;
     }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"static">;
+    deploymentId: z.ZodString;
+    contentHash: z.ZodString;
+    active: z.ZodBoolean;
+    published: z.ZodOptional<z.ZodBoolean>;
+    projectId: z.ZodString;
+    ownerId: z.ZodString;
+    environment: z.ZodString;
+    publicOrigin: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    expiresAt: z.ZodNumber;
+    maxExpiresAt: z.ZodOptional<z.ZodNumber>;
+    capabilities: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    serviceAccountId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    lattice: z.ZodOptional<z.ZodObject<{
+        runId: z.ZodNullable<z.ZodString>;
+        nodeId: z.ZodNullable<z.ZodString>;
+        stepId: z.ZodNullable<z.ZodString>;
+        processId: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+    taskRoutes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    manifest: z.ZodOptional<z.ZodObject<{
+        server: z.ZodObject<{
+            resources: z.ZodObject<{
+                concurrency: z.ZodNumber;
+                max_instances: z.ZodNumber;
+                timeout_seconds: z.ZodNumber;
+            }, z.core.$strip>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
 }, z.core.$strip>], "kind">;
 export type GatewayTarget = z.infer<typeof gatewayTargetSchema>;
 declare const latticeInvokeGrantSchema: z.ZodObject<{
@@ -91,6 +121,15 @@ declare const latticeInvokeGrantSchema: z.ZodObject<{
     }, z.core.$strict>;
 }, z.core.$strict>;
 export type LatticeInvokeGrant = z.infer<typeof latticeInvokeGrantSchema>;
+/** Paths a static deployment serves: its page, entry bundle, source map and lazy chunks. */
+export declare const STATIC_PAGE = "index.html";
+/** The static bundle ceiling (30 MiB) plus headroom; a larger file is a platform fault, never served. */
+export declare const STATIC_FILE_MAX_BYTES: number;
+export interface StaticArtifactFile {
+    body: Buffer;
+    contentType: string;
+    etag?: string;
+}
 export declare class GatewayControlError extends Error {
     readonly status: number;
     constructor(status: number);
@@ -115,15 +154,27 @@ export declare class IngressControlError extends GatewayControlError {
     readonly retryAfterSeconds?: number | undefined;
     constructor(status: number, code: IngressControlCode | null, retryAfterSeconds?: number | undefined);
 }
+/** Calls Atlas with the gateway service account's identity token instead of the shared control token. */
+export interface GatewayControlIdentity {
+    audience: string;
+    token: (input: {
+        audience: string;
+        signal: AbortSignal;
+    }) => Promise<string>;
+}
 export declare class ArtifactGatewayControl {
     private readonly options;
     private readonly origin;
+    /** `token` stays required with an identity: Atlas still presents it when it calls the gateway (tokenMatches). */
     constructor(options: {
         url: string;
         token: string;
+        identity?: GatewayControlIdentity;
         fetch?: typeof fetch;
     });
     private call;
+    /** An identity token that cannot be minted is an unavailable control plane, never a call without credentials. */
+    private credential;
     private send;
     /** Every enabled ingress host (GET, at most 1 MiB); the gateway pulls it on a timer, never per request. */
     ingressSnapshot(): Promise<IngressSnapshot>;
@@ -144,6 +195,16 @@ export declare class ArtifactGatewayControl {
         target: GatewayTarget;
     }>;
     authorize(session: GatewaySession): Promise<GatewayTarget>;
+    /**
+     * One immutable file of a static deployment (the page, entry bundle, source map or a chunk), raw
+     * bytes up to the static bundle ceiling. The gateway authorized the browser's session first; this
+     * call carries only the gateway's own credential.
+     */
+    staticFile({ deploymentId, path, parentOrigin }: {
+        deploymentId: string;
+        path: string;
+        parentOrigin: string;
+    }): Promise<StaticArtifactFile>;
     /** SHA-256 both sides so a wrong bearer still takes constant time. */
     tokenMatches(presented: string): boolean;
     latticeInvoke(body: {

package/dist/gateway/control.js

@@ -2,7 +2,8 @@ import { createHash, timingSafeEqual } from 'node:crypto';
 import { z } from 'zod';
 import { normalizePublicOrigin } from '../tunnel/protocol.js';
 import { artifactRequestContextSchema } from '../server/request-context.js';
-import { artifactNextFrameworkBuildIdSchema } from '../runtime-contracts.js';
+import { ARTIFACT_NEXT_CONTROL_PATH, artifactNextFrameworkBuildIdSchema } from '../runtime-contracts.js';
+import { untilAborted } from './abort.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 = {
@@ -19,6 +20,8 @@ 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(), runtimeTransport: z.enum(['cloud-run', 'local-docker']).optional(), active: z.boolean(), published: z.boolean().optional() }),
+    // A static (React/Vite) deployment: the gateway serves its immutable files itself, fetched from Atlas.
+    z.object({ ...base, kind: z.literal('static'), deploymentId: id, contentHash: z.string().min(1).max(128), 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() });
@@ -40,6 +43,39 @@ const latticeInvokeGrantSchema = z.object({
         timeout_seconds: z.number().int().min(1).max(300),
     }).strict(),
 }).strict();
+/** Paths a static deployment serves: its page, entry bundle, source map and lazy chunks. */
+export const STATIC_PAGE = 'index.html';
+const STATIC_FILE_PATH = /^(?:index\.html|bundle\.js|sourcemap\.json|chunks\/[A-Za-z0-9._-]{1,200})$/;
+/** The static bundle ceiling (30 MiB) plus headroom; a larger file is a platform fault, never served. */
+export const STATIC_FILE_MAX_BYTES = 32 * 1024 * 1024;
+const STATIC_CONTENT_TYPES = new Set(['text/html', 'application/javascript', 'text/javascript', 'application/json', 'text/css']);
+/** Reads at most `maxBytes` of a response body, refusing (502) anything larger. */
+async function readBounded(response, maxBytes) {
+    if (Number(response.headers.get('content-length')) > maxBytes) {
+        await response.body?.cancel().catch(() => undefined);
+        throw new GatewayControlError(502);
+    }
+    const reader = response.body?.getReader();
+    if (!reader)
+        throw new GatewayControlError(502);
+    const chunks = [];
+    let length = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            length += value.length;
+            if (length > maxBytes)
+                throw new GatewayControlError(502);
+            chunks.push(value);
+        }
+        return Buffer.concat(chunks);
+    }
+    finally {
+        await reader.cancel().catch(() => undefined);
+    }
+}
 export class GatewayControlError extends Error {
     status;
     constructor(status) {
@@ -94,6 +130,7 @@ async function ingressRefusal(response) {
 export class ArtifactGatewayControl {
     options;
     origin;
+    /** `token` stays required with an identity: Atlas still presents it when it calls the gateway (tokenMatches). */
     constructor(options) {
         this.options = options;
         this.origin = normalizePublicOrigin(options.url);
@@ -103,11 +140,26 @@ export class ArtifactGatewayControl {
     call(path, body, timeoutMs = 10_000) {
         return this.send({ path, body, timeoutMs, maxBytes: 128 * 1024 });
     }
+    /** An identity token that cannot be minted is an unavailable control plane, never a call without credentials. */
+    async credential(signal) {
+        const identity = this.options.identity;
+        if (!identity)
+            return this.options.token;
+        // The token source may ignore `signal`; the call's own deadline still bounds the wait.
+        try {
+            return await untilAborted(identity.token({ audience: identity.audience, signal }), signal);
+        }
+        catch {
+            throw new GatewayControlError(503);
+        }
+    }
     async send({ path, body, timeoutMs, maxBytes, ingress = false }) {
-        const response = await (this.options.fetch ?? fetch)(`${this.origin}/api/artifact-studio/next/control/${path}`, {
+        const signal = AbortSignal.timeout(timeoutMs);
+        const credential = await this.credential(signal);
+        const response = await (this.options.fetch ?? fetch)(`${this.origin}${ARTIFACT_NEXT_CONTROL_PATH}/${path}`, {
             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',
+            headers: { authorization: `Bearer ${credential}`, ...(body === undefined ? {} : { 'content-type': 'application/json' }) },
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }), signal, redirect: 'error',
         });
         if (!response.ok)
             throw ingress ? await ingressRefusal(response) : new GatewayControlError(response.status);
@@ -169,11 +221,11 @@ export class ArtifactGatewayControl {
             version: 1, kind: target.kind, projectId: target.projectId, ownerId: target.ownerId,
             environment: target.environment, publicOrigin: target.publicOrigin,
             sessionId: target.kind === 'development' ? target.sessionId : null,
-            deploymentId: target.kind === 'hosted' ? target.deploymentId : null,
+            deploymentId: target.kind === 'development' ? null : target.deploymentId,
             frameworkBuildId: target.kind === 'hosted' ? target.frameworkBuildId : null,
             expiresAt: Math.min(target.expiresAt, target.maxExpiresAt ?? target.expiresAt, Date.now() + 8 * 60 * 60_000),
             maxExpiresAt: Math.min(target.maxExpiresAt ?? (target.kind === 'development' ? target.expiresAt : Date.now() + 8 * 60 * 60_000), Date.now() + 8 * 60 * 60_000),
-            published: target.kind === 'hosted' && (target.published ?? target.active), bridge,
+            published: target.kind !== 'development' && (target.published ?? target.active), bridge,
             ...(target.lattice ? { lattice: target.lattice } : {}),
             ...(target.taskRoutes ? { taskRoutes: target.taskRoutes } : {}),
         };
@@ -189,10 +241,37 @@ export class ArtifactGatewayControl {
         const target = gatewayTargetSchema.parse(value);
         if (target.kind !== session.kind || target.projectId !== session.projectId || target.ownerId !== session.ownerId ||
             target.environment !== session.environment || target.publicOrigin !== session.publicOrigin || target.expiresAt <= Date.now() ||
-            (target.kind === 'development' ? target.sessionId !== session.sessionId : target.deploymentId !== session.deploymentId || target.frameworkBuildId !== session.frameworkBuildId))
+            (target.kind === 'development' ? target.sessionId !== session.sessionId
+                : target.deploymentId !== session.deploymentId || (target.kind === 'hosted' && target.frameworkBuildId !== session.frameworkBuildId)))
             throw new GatewayControlError(403);
         return target;
     }
+    /**
+     * One immutable file of a static deployment (the page, entry bundle, source map or a chunk), raw
+     * bytes up to the static bundle ceiling. The gateway authorized the browser's session first; this
+     * call carries only the gateway's own credential.
+     */
+    async staticFile({ deploymentId, path, parentOrigin }) {
+        if (!STATIC_FILE_PATH.test(path) || !/^[A-Za-z0-9_-]{1,128}$/.test(deploymentId))
+            throw new GatewayControlError(404);
+        const signal = AbortSignal.timeout(15_000);
+        const credential = await this.credential(signal);
+        const query = path === STATIC_PAGE ? `?parentOrigin=${encodeURIComponent(parentOrigin)}` : '';
+        const response = await (this.options.fetch ?? fetch)(`${this.origin}${ARTIFACT_NEXT_CONTROL_PATH}/static/${deploymentId}/${path}${query}`, {
+            headers: { authorization: `Bearer ${credential}` }, signal, redirect: 'error',
+        });
+        if (!response.ok) {
+            await response.body?.cancel().catch(() => undefined);
+            throw new GatewayControlError(response.status);
+        }
+        const contentType = response.headers.get('content-type') ?? '';
+        if (!STATIC_CONTENT_TYPES.has(contentType.split(';', 1)[0].trim().toLowerCase())) {
+            await response.body?.cancel().catch(() => undefined);
+            throw new GatewayControlError(502);
+        }
+        const body = await readBounded(response, STATIC_FILE_MAX_BYTES);
+        return { body, contentType, etag: response.headers.get('etag') ?? undefined };
+    }
     /** SHA-256 both sides so a wrong bearer still takes constant time. */
     tokenMatches(presented) {
         if (presented.length === 0 || presented.length > 1024)

package/dist/gateway/hosted-proxy.d.ts

@@ -1,6 +1,7 @@
 import { type IncomingMessage, type ServerResponse } from 'node:http';
 import { type HostedArtifactIngressMode } from './ingress-response.js';
 import { type HostedRuntimeTarget } from './runtime-transport.js';
+import { type GatewayTimings } from './usage.js';
 export { cloudRunOrigin, resolveHostedTarget, type HostedRuntimeTarget } from './runtime-transport.js';
 export declare const HOSTED_ARTIFACT_PROXY_LIMITS: Readonly<{
     maxRequestBytes: number;
@@ -35,6 +36,8 @@ export interface HostedArtifactProxyOptions {
     };
     /** Present only for an external ingress request. */
     ingress?: HostedArtifactIngressMode;
+    /** Request-local observations; the caller snapshots them when recording usage. */
+    gatewayTimings?: GatewayTimings;
 }
 export declare function hostedIdentityToken(input: {
     audience: string;

package/dist/gateway/hosted-proxy.js

@@ -8,6 +8,7 @@ import { enforceBrowserCachePolicy, mergeFramePolicy, rewriteLocation } from './
 import { createReleaseFormTransform } from '../server/release-forms.js';
 import { declaredContentLength, INGRESS_PROXY_ERROR_CODES, INGRESS_PROXY_LIMITS, writeIngressResponseHead } from './ingress-response.js';
 import { resolveHostedTarget } from './runtime-transport.js';
+import { gatewayElapsedMs } from './usage.js';
 export { cloudRunOrigin, resolveHostedTarget } from './runtime-transport.js';
 export const HOSTED_ARTIFACT_PROXY_LIMITS = Object.freeze({ maxRequestBytes: 32 * 1024 * 1024, maxResponseBytes: 32 * 1024 * 1024, timeoutMs: 60_000, maxTimeoutMs: 300_000 });
 const googleAuth = new GoogleAuth();
@@ -129,7 +130,11 @@ class HostedExchange {
         stripCloudHeaders(headers);
         if (audience) {
             const provider = this.options.identityTokenProvider ?? defaultIdentityTokenProvider;
-            const token = await provider({ audience: audience.origin, signal: this.controller.signal });
+            const identityStarted = performance.now();
+            const token = await provider({ audience: audience.origin, signal: this.controller.signal }).finally(() => {
+                if (!this.stopped && this.options.gatewayTimings)
+                    this.options.gatewayTimings.identityTokenMs = gatewayElapsedMs(identityStarted);
+            });
             if (this.stopped)
                 return;
             if (!/^[A-Za-z0-9._~-]+$/.test(token) || token.length > 16384)
@@ -145,7 +150,12 @@ class HostedExchange {
         headers['x-sequence-artifact-context'] = requestContext;
         const destination = this.resolveDestination(upstream);
         const transport = destination.protocol === 'https:' ? httpsRequest : httpRequest;
-        this.outgoing = transport(destination, { method: request.method, path: request.url, headers, maxHeaderSize: 32 * 1024 }, (incoming) => this.receive({ incoming, upstream, publicOrigin }));
+        const upstreamStarted = performance.now();
+        this.outgoing = transport(destination, { method: request.method, path: request.url, headers, maxHeaderSize: 32 * 1024 }, (incoming) => {
+            if (!this.stopped && this.options.gatewayTimings)
+                this.options.gatewayTimings.upstreamHeadersMs = gatewayElapsedMs(upstreamStarted);
+            this.receive({ incoming, upstream, publicOrigin });
+        });
         this.outgoing.on('error', () => this.fail(this.unavailableStatus));
         this.outgoing.once('upgrade', (_incoming, socket) => { socket.destroy(); this.fail(502); });
         this.outgoing.on('drain', () => { if (!this.stopped)

package/dist/gateway/release-admission.d.ts

@@ -20,4 +20,9 @@ export declare function admitHostedMutation({ request, expectedDeploymentId, exp
 }): Promise<{
     body?: AsyncIterable<Uint8Array>;
 }>;
+/** The release a request names: the deployment header, or the Next build id (header or `dpl` query), never conflicting. */
+export declare function releaseHints(request: IncomingMessage): {
+    deploymentId?: string;
+    frameworkBuildId?: string;
+};
 export {};

package/dist/gateway/release-admission.js

@@ -257,3 +257,22 @@ export async function admitHostedMutation({ request, expectedDeploymentId, expec
     }
     return { body: continuation() };
 }
+/** The release a request names: the deployment header, or the Next build id (header or `dpl` query), never conflicting. */
+export function releaseHints(request) {
+    function uniqueHeader(name) {
+        const value = request.headers[name];
+        if (value === undefined)
+            return undefined;
+        const count = request.rawHeaders.filter((_, index) => index % 2 === 0 && request.rawHeaders[index].toLowerCase() === name).length;
+        if (typeof value !== 'string' || count !== 1 || !artifactNextFrameworkBuildIdSchema.safeParse(value).success)
+            throw new ReleaseAdmissionError('conflicting-release');
+        return value;
+    }
+    const deploymentId = uniqueHeader('x-sequence-artifact-release');
+    const frameworkHeader = uniqueHeader('x-deployment-id');
+    const query = new URL(request.url ?? '/', 'https://gateway.invalid').searchParams.getAll('dpl');
+    if (query.length > 1 || (query.length === 1 && !artifactNextFrameworkBuildIdSchema.safeParse(query[0]).success) ||
+        (frameworkHeader && query.length === 1 && frameworkHeader !== query[0]))
+        throw new ReleaseAdmissionError('conflicting-release');
+    return { deploymentId, frameworkBuildId: frameworkHeader ?? query[0] };
+}

package/dist/gateway/server.d.ts

@@ -5,13 +5,14 @@ import { type GatewaySessionSameSite } from './session.js';
 import { type ArtifactRequestAdmission } from './admission.js';
 import { type GatewayControlAdmission } from './control-admission.js';
 import { type ArtifactGatewayIngressOptions } from './ingress.js';
+import { StaticArtifactFiles } from './static-files.js';
 export interface ArtifactGatewayOptions {
     control: ArtifactGatewayControl;
     runtimeDomain: string;
     parentOrigin: string;
     gatewayOrigin: string;
     sessionKey: string;
-    /** Defaults to `Strict`. `None` only for a local development gateway (see GatewaySessionSameSite). */
+    /** Defaults to `Strict`; `None` when app origins are cross-site to Atlas (see gatewaySessionSameSite). */
     sessionCookieSameSite?: GatewaySessionSameSite;
     contextPrivateKey: string;
     contextKeyId: string;
@@ -28,6 +29,8 @@ export interface ArtifactGatewayOptions {
     controlAdmission?: Pick<GatewayControlAdmission, 'admit'>;
     /** External ingress front door (design §(e)). Absent: every `ingress-*` host answers 404. */
     ingress?: ArtifactGatewayIngressOptions;
+    /** Static deployments' files (default: fetched from Atlas, cached by deployment within the default byte budget). */
+    staticFiles?: Pick<StaticArtifactFiles, 'get'>;
     /** Reuse of a positive Atlas authorization (default GATEWAY_AUTHORIZATION_TTL_MS; 0 disables). */
     authorizationCacheTtlMs?: number;
     onError?: (event: {