@sequenceholdings/artifact-studio 0.2.5 → 0.3.0

package/dist/cli.js

@@ -8,21 +8,22 @@ import { writeBuildArtifact } from './build.js';
 import { buildArtifactStudioProjectIsolated } from './build-subprocess.js';
 import { resolveArtifactStudioPeerVersions, } from './peer-versions.js';
 import { prepareArtifactBuildRoot } from './prepare-build.js';
-import { parseArtifactStudioManifest } from './manifest.js';
-import { hasArtifactStudioManifest, readArtifactStudioSource } from './project.js';
+import { isNextArtifactManifest, parseArtifactStudioManifest } from './manifest.js';
+import { hasArtifactStudioManifest, readArtifactStudioManifest, readArtifactStudioSource } from './project.js';
 import { localGitMetadata, parseSourceSpec, resolveArtifactSource, } from './source-resolver.js';
 import { acquireDevLock } from './dev-lock.js';
 import { runWatchLoop } from './watch-loop.js';
 import { hashLinkedSources, hasLinkedAtlasUiToolchain, parseLinks, rebuildLinkedDep, resolveLinkedDeps, syncLinkedDist, } from './dev-link.js';
 import { lintArtifactSandbox, reportSandboxWarnings } from './sandbox-lint.js';
 import { assertActiveDeployProvenance } from './active-deploy-policy.js';
+import { normalizeArtifactPath } from './paths.js';
 import yaml from 'js-yaml';
 const COMMANDS = [
     'init', 'whoami', 'link', 'env', 'status', 'list', 'show',
     'validate', 'build', 'plan', 'deploy', 'dev', 'promote', 'pull', 'rollback',
 ];
 const USAGE = `usage:
-  seq-studio artifact init <dir>
+  seq-studio artifact init <dir> [--template react-vite|nextjs]
   seq-studio artifact whoami --env <env>
   seq-studio artifact link --env <env> [--project <id>]
   seq-studio artifact env list|use <env>
@@ -33,7 +34,7 @@ const USAGE = `usage:
   seq-studio artifact build [dir | --repo <ns>/<name> | --git-url <url>] [--ref <ref>] [--out dist/artifact-bundle.json]
   seq-studio artifact plan [dir | --repo <ns>/<name> | --git-url <url>] [--ref <ref>] --env <env>
   seq-studio artifact deploy [dir | --repo <ns>/<name> | --git-url <url>] [--ref <ref>] --env <env> [--skip-unchanged] [--no-create] [--project <id>]
-  seq-studio artifact dev [dir] --env <env> [--once] [--key default] [--link <pkgDir>[,<pkgDir>]]
+  seq-studio artifact dev [dir] --env <env> [--once] [--key default] [--link <pkgDir>[,<pkgDir>]] [--port <port>]
   seq-studio artifact promote <deployment-id> --env <env>
   seq-studio artifact pull <project-id> --env <env> --out <dir>
   seq-studio artifact rollback <deployment-id> --env <env>
@@ -57,6 +58,12 @@ const USAGE = `usage:
   seq-studio login are still needed to resolve the repo and upload the
   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).
+  build --env creates an immutable hosted preview; deploy builds and publishes
+  a reviewed Git Service revision through Atlas. For local build checks, use pnpm build.
+  --once applies to static artifacts; --port applies to Next development.
+
   Authenticate with: seq-studio login`;
 export async function runCli(argv = process.argv.slice(2)) {
     if (argv.some((arg) => arg === '--token' || arg.startsWith('--token='))) {
@@ -118,17 +125,30 @@ async function initCommand(args) {
     const dir = resolve(args.positional[0] ?? '.');
     const name = dir.split('/').filter(Boolean).at(-1) ?? 'my-artifact';
     const slug = slugify(name);
+    const template = args.flags.template ?? 'react-vite';
+    if (template !== 'react-vite' && template !== 'nextjs') {
+        throw new Error('--template must be react-vite or nextjs.');
+    }
     const moduleDir = dirname(fileURLToPath(import.meta.url));
-    const templateRoot = existsSync(resolve(moduleDir, 'templates', 'react-vite'))
-        ? resolve(moduleDir, 'templates', 'react-vite')
-        : resolve(moduleDir, '..', 'templates', 'react-vite');
+    const templateRoot = existsSync(resolve(moduleDir, 'templates', template))
+        ? resolve(moduleDir, 'templates', template)
+        : resolve(moduleDir, '..', 'templates', template);
     await mkdir(dir, { recursive: true });
     await cp(templateRoot, dir, { recursive: true, force: false, errorOnExist: false });
     await replaceInFile(join(dir, 'artifact.bundle.yml'), /\{\{slug\}\}/g, slug);
     await replaceInFile(join(dir, 'artifact.bundle.yml'), /\{\{title\}\}/g, titleize(slug));
     await replaceInFile(join(dir, 'package.json'), /\{\{slug\}\}/g, slug);
+    if (template === 'nextjs') {
+        const peers = resolveArtifactStudioPeerVersions();
+        await replaceInFile(join(dir, 'package.json'), /\{\{artifactStudioVersion\}\}/g, peers.cliVersion);
+        for (const file of ['app/layout.tsx', 'app/page.tsx']) {
+            await replaceInFile(join(dir, file), /\{\{title\}\}/g, titleize(slug));
+        }
+    }
     console.log(`[seq-studio] initialized ${dir}`);
-    console.log('Next: seq-studio login && seq-studio artifact dev --env <env>  (see: seq-studio envs list)');
+    console.log(template === 'nextjs'
+        ? 'Next: cd into the app, run pnpm install, then seq-studio login && seq-studio artifact dev --env <env>. Commit pnpm-lock.yaml before deploying. No cloud credentials are required.'
+        : 'Next: seq-studio login && seq-studio artifact dev --env <env>  (see: seq-studio envs list)');
     return 0;
 }
 async function whoamiCommand(args) {
@@ -184,10 +204,12 @@ async function linkCommand(args) {
                 title: source.manifest.artifact.title,
                 slug: source.manifest.artifact.project_id,
                 description: source.manifest.artifact.description ?? null,
+                ...(isNextArtifactManifest(source.manifest) ? { projectType: 'nextjs' } : {}),
             },
         });
         project = created.project;
     }
+    assertProjectRuntime({ project, artifactType: source.manifest.artifact.type, declaredSlug: source.manifest.artifact.project_id });
     await writeLocalConfig({
         projectId: project.id,
         projectSlug: project.slug,
@@ -254,8 +276,7 @@ async function listCommand(args) {
             : project.activeDeploymentId
                 ? 'deployed'
                 : 'not deployed';
-        const visibility = project.visibility ? `  ${project.visibility}` : '';
-        console.log(`  ${project.slug}  id=${project.id}  [${active}]${visibility}  ${project.title}`);
+        console.log(`  ${project.slug}  id=${project.id}  [${active}]  ${project.title}`);
     }
     return 0;
 }
@@ -300,8 +321,6 @@ async function showCommand(args) {
     console.log(`  title:       ${project.title}`);
     if (project.description)
         console.log(`  description: ${project.description}`);
-    if (project.visibility)
-        console.log(`  visibility:  ${project.visibility}`);
     if (project.appEligible !== undefined)
         console.log(`  appEligible: ${project.appEligible ? 'yes' : 'no'}`);
     if (project.createdBy)
@@ -346,6 +365,12 @@ async function validateCommand(args) {
     console.log(`[seq-studio] valid ${source.manifest.bundle.name}`);
     console.log(`[seq-studio] files: ${source.files.length}`);
     console.log(`[seq-studio] source: ${source.sourceHash}`);
+    if (isNextArtifactManifest(source.manifest)) {
+        const { validateNextProject } = await import('./next-project.js');
+        await validateNextProject({ root: dir, manifest: source.manifest, installed: false });
+        console.log('[seq-studio] Next.js source is valid; Atlas performs the release build and hosted policy checks.');
+        return 0;
+    }
     reportSandboxWarnings(lintArtifactSandbox(source.files));
     return 0;
 }
@@ -375,6 +400,9 @@ async function buildCommand(args) {
             : {};
     const source = await resolveArtifactSource(spec, remote);
     try {
+        if (isNextArtifactManifest(await readArtifactStudioManifest(source.dir))) {
+            return await buildNextCommand({ args, source, active: false });
+        }
         const result = await buildPreparedArtifactSource(source);
         reportBuildDiagnostics(result);
         // A remote source's dir is a temp dir we tear down below, so default the
@@ -405,6 +433,11 @@ async function planCommand(args) {
         token,
     });
     try {
+        const manifest = await readArtifactStudioManifest(source.dir);
+        if (isNextArtifactManifest(manifest)) {
+            const { planNextProject } = await import('./next-build.js');
+            return await planNextProject({ root: source.dir, manifest, environment: env.name });
+        }
         const result = await buildPreparedArtifactSource(source);
         reportBuildDiagnostics(result);
         console.log(`[seq-studio] plan ${result.manifest.artifact.project_id} -> ${env.name}`);
@@ -461,6 +494,9 @@ async function deployCommand(args) {
         // the current branch and dirty working tree.
         if (env.name !== 'local')
             assertActiveDeployProvenance(source.provenance);
+        if (isNextArtifactManifest(await readArtifactStudioManifest(source.dir))) {
+            return await buildNextCommand({ args, source, active: true });
+        }
         // --skip-unchanged: hash the raw source (no build needed) and no-op when
         // the remote active deployment already matches *and* was built with the
         // same CLI/atlas-ui pin. Lets CI redeploy every artifact on every release
@@ -499,7 +535,6 @@ async function deployCommand(args) {
             linkConfigDir: spec.kind === 'local' ? source.dir : null,
             allowCreate: args.flags['no-create'] !== true,
             explicitProjectId,
-            envName: env.name,
         });
         const deployment = await uploadDeployment({ env: env.url, token, projectId: project.id, result, channel: 'active', provenance: source.provenance });
         console.log(`[seq-studio] deployed ${project.title} ${deployment.version}`);
@@ -510,12 +545,56 @@ async function deployCommand(args) {
         await source.cleanup();
     }
 }
+async function buildNextCommand({ args, source, active }) {
+    const env = await envFromArgs(args);
+    const token = await getRequiredToken(args);
+    const manifest = await readArtifactStudioManifest(source.dir);
+    if (!isNextArtifactManifest(manifest))
+        throw new Error('Expected a Next.js application manifest.');
+    const { nextSourceRepository, resolveNextRepositoryId, submitNextBuild } = await import('./next-build.js');
+    const spec = parseSourceSpec(args);
+    const repository = nextSourceRepository({ spec, root: source.dir });
+    if (active)
+        assertActiveDeployProvenance(source.provenance);
+    const repositoryId = active || spec.kind === 'git-service'
+        ? await resolveNextRepositoryId({ spec, repository, baseUrl: env.url, token })
+        : undefined;
+    const project = await ensureRemoteProject({
+        env: env.url, token, result: { manifest }, linkConfigDir: spec.kind === 'local' ? source.dir : null,
+        allowCreate: args.flags['no-create'] !== true,
+        explicitProjectId: typeof args.flags.project === 'string' ? args.flags.project : null,
+    });
+    if (args.flags['skip-unchanged']) {
+        console.log('[seq-studio] Next.js submits source to Atlas for build verification; local static-bundle skip checks do not apply.');
+    }
+    return submitNextBuild({
+        root: source.dir, manifest, projectId: project.id, baseUrl: env.url,
+        getToken: () => getRequiredToken(args), provenance: source.provenance, repository, repositoryId,
+        channel: active ? 'active' : 'preview', out: typeof args.flags.out === 'string' ? resolve(args.flags.out) : undefined,
+    });
+}
 async function devCommand(args) {
     if (args.flags.repo || args.flags['git-url']) {
         throw new Error('dev watches a local folder; --repo / --git-url are only for build, plan, and deploy.');
     }
     const dir = resolve(args.positional[0] ?? '.');
     const env = await envFromArgs(args);
+    const initialManifest = await readArtifactStudioManifest(dir);
+    if (isNextArtifactManifest(initialManifest)) {
+        if (args.flags.once)
+            throw new Error('Next.js dev is a live local session. Use artifact build --env <env> for an immutable hosted preview.');
+        const auth = await getRequiredAuth(args);
+        if (auth.authMode !== 'user')
+            throw new Error('Local Next.js development requires a user login. Run seq-studio login.');
+        const project = await ensureRemoteProject({ env: env.url, token: auth.token, result: { manifest: initialManifest }, linkConfigDir: dir });
+        const { runNextDevelopment } = await import('./next-dev.js');
+        return runNextDevelopment({
+            root: dir, manifest: initialManifest, projectId: project.id, baseUrl: env.url,
+            environment: env.name, previewKey: typeof args.flags.key === 'string' ? args.flags.key : 'default',
+            port: typeof args.flags.port === 'string' ? args.flags.port : undefined,
+            links: parseLinks(args.flags.link), getToken: () => getRequiredToken(args),
+        });
+    }
     // Validate auth up front for a fast failure, but resolve a fresh token on
     // every push (below) so a long-running watcher survives access-token expiry
     // instead of dying with "Authentication failed" once the initial token's TTL
@@ -589,9 +668,7 @@ async function devCommand(args) {
         // Resolve per push so the token refreshes across a long watch session.
         const token = await getRequiredToken(args);
         if (!projectId) {
-            // envName so a first-time `artifact dev` creation honors the manifest
-            // visibility too (and notes drift, once, when the project pre-exists).
-            const project = await ensureRemoteProject({ env: env.url, token, result, linkConfigDir: dir, envName: env.name });
+            const project = await ensureRemoteProject({ env: env.url, token, result, linkConfigDir: dir });
             projectId = project.id;
         }
         const deployment = await uploadDeployment({
@@ -731,9 +808,9 @@ async function pullCommand(args) {
         path: `/api/artifact-studio/projects/${projectId}/deployments/${projectData.project.activeDeploymentId}/files`,
     });
     for (const file of filesData.files) {
-        const target = join(out, file.path);
+        const target = join(out, normalizeArtifactPath(file.path));
         await mkdir(dirname(target), { recursive: true });
-        await writeFile(target, file.content, 'utf8');
+        await writeFile(target, file.encoding === 'base64' ? Buffer.from(file.content, 'base64') : file.content);
     }
     console.log(`[seq-studio] pulled ${projectId} to ${out}`);
     return 0;
@@ -771,21 +848,7 @@ export function activeDeploymentMatchesSkipPin({ active, sourceHash, peerVersion
     return (active.cliVersion === peerVersions.cliVersion &&
         active.atlasUiVersion === peerVersions.atlasUiVersion);
 }
-/**
- * Deploys never change a live project's visibility — the Studio sharing UI /
- * PATCH own that. The manifest's targets.<env>.visibility is honored at
- * project CREATION only; on drift, say so instead of silently ignoring the
- * field (which is how it read as decorative for a year).
- */
-function warnOnVisibilityDrift({ project, declared, envName }) {
-    if (!declared || !envName || !project.visibility || declared === project.visibility)
-        return;
-    console.warn(`[seq-studio] note: artifact.bundle.yml targets.${envName}.visibility is "${declared}" but the project is ` +
-        `"${project.visibility}" on this environment — deploys never change visibility. Update it in Studio sharing ` +
-        `(or PATCH /api/artifact-studio/projects/${project.id}) if the manifest is what you intend.`);
-}
-async function ensureRemoteProject({ env, token, result, linkConfigDir, allowCreate = true, explicitProjectId = null, envName = null }) {
-    const declaredVisibility = envName ? result.manifest.targets?.[envName]?.visibility : undefined;
+async function ensureRemoteProject({ env, token, result, linkConfigDir, allowCreate = true, explicitProjectId = null }) {
     if (explicitProjectId) {
         const data = await getJsonOr404({ baseUrl: env, token, path: `/api/artifact-studio/projects/${explicitProjectId}` });
         if (!data)
@@ -794,23 +857,23 @@ async function ensureRemoteProject({ env, token, result, linkConfigDir, allowCre
             throw new Error(`--project ${explicitProjectId} resolves to slug "${data.project.slug}" but this source's ` +
                 `artifact.bundle.yml declares project_id "${result.manifest.artifact.project_id}" — refusing to deploy over a different project`);
         }
-        warnOnVisibilityDrift({ project: data.project, declared: declaredVisibility, envName });
+        assertProjectRuntime({ project: data.project, artifactType: result.manifest.artifact.type, declaredSlug: result.manifest.artifact.project_id });
         return data.project;
     }
     const config = linkConfigDir ? await readLocalConfig(linkConfigDir) : {};
     if (config.projectId) {
         const data = await getJsonOr404({ baseUrl: env, token, path: `/api/artifact-studio/projects/${config.projectId}` });
         if (data) {
-            warnOnVisibilityDrift({ project: data.project, declared: declaredVisibility, envName });
+            assertProjectRuntime({ project: data.project, artifactType: result.manifest.artifact.type, declaredSlug: result.manifest.artifact.project_id });
             return data.project;
         }
         console.warn(`[seq-studio] cached projectId ${config.projectId} not found on ${env} — relinking by slug`);
     }
     const existing = await fetchRemoteProject({ env, token, slug: result.manifest.artifact.project_id });
     if (existing) {
+        assertProjectRuntime({ project: existing, artifactType: result.manifest.artifact.type, declaredSlug: result.manifest.artifact.project_id });
         if (linkConfigDir)
             await writeLocalConfig({ ...config, projectId: existing.id, projectSlug: existing.slug }, linkConfigDir);
-        warnOnVisibilityDrift({ project: existing, declared: declaredVisibility, envName });
         return existing;
     }
     if (!allowCreate) {
@@ -826,13 +889,21 @@ async function ensureRemoteProject({ env, token, result, linkConfigDir, allowCre
             title: result.manifest.artifact.title,
             slug: result.manifest.artifact.project_id,
             description: result.manifest.artifact.description ?? null,
-            ...(declaredVisibility ? { visibility: declaredVisibility } : {}),
+            ...(result.manifest.artifact.type === 'nextjs' ? { projectType: 'nextjs' } : {}),
         },
     });
     if (linkConfigDir)
         await writeLocalConfig({ ...config, projectId: created.project.id, projectSlug: created.project.slug }, linkConfigDir);
     return created.project;
 }
+function assertProjectRuntime({ project, artifactType, declaredSlug }) {
+    if (artifactType === 'nextjs' && project.slug !== declaredSlug) {
+        throw new Error(`Linked project ${project.slug} does not match artifact.bundle.yml project_id ${declaredSlug}. Relink to the intended project.`);
+    }
+    if (artifactType === 'nextjs' && project.projectType && project.projectType !== 'nextjs') {
+        throw new Error(`Project ${project.slug} uses the static runtime. Create a separate Next.js project in Atlas and update artifact.bundle.yml project_id before linking.`);
+    }
+}
 async function uploadDeployment({ env, token, projectId, result, channel, previewKey, linked = false, provenance, message, }) {
     // Active deploys omit `version`: the server derives it from its own
     // sourceHash and de-dupes against the (projectId, version) unique

package/dist/dev-link.d.ts

@@ -53,7 +53,7 @@ export declare function resolveLinkedDeps({ links, cwd, resolver, readPackageNam
  */
 export declare function hashLinkedSources(deps: readonly LinkedDep[]): Promise<string>;
 /** Run a linked package's `build` script in a child process. */
-export declare function rebuildLinkedDep(dep: LinkedDep, signal?: AbortSignal): Promise<void>;
+export declare function rebuildLinkedDep(dep: LinkedDep, signal?: AbortSignal, env?: NodeJS.ProcessEnv): Promise<void>;
 /**
  * Copy a linked package's freshly built `dist` and root CSS entries into the
  * location the artifact build resolves them from. A no-op when the artifact

package/dist/dev-link.js

@@ -135,7 +135,7 @@ async function collectFiles(root) {
     return out;
 }
 /** Run a linked package's `build` script in a child process. */
-export function rebuildLinkedDep(dep, signal) {
+export function rebuildLinkedDep(dep, signal, env) {
     return new Promise((resolveBuild, reject) => {
         if (signal?.aborted) {
             reject(new Error('build aborted'));
@@ -143,6 +143,7 @@ export function rebuildLinkedDep(dep, signal) {
         }
         const child = spawn('pnpm', ['run', 'build'], {
             cwd: dep.dir,
+            ...(env ? { env } : {}),
             stdio: ['ignore', 'inherit', 'inherit'],
         });
         const onAbort = () => {

package/dist/gateway/admission.d.ts

@@ -0,0 +1,55 @@
+import type { EventEmitter } from 'node:events';
+export interface AdmissionRedis {
+    readonly options: {
+        enableOfflineQueue?: boolean;
+        autoResendUnfulfilledCommands?: boolean;
+        maxRetriesPerRequest?: number | null;
+    };
+    eval(script: string, numberOfKeys: number, ...parameters: (string | number)[]): Promise<unknown>;
+}
+export interface AdmissionTarget {
+    environment: string;
+    projectId: string;
+    deploymentId: string;
+    resources?: {
+        concurrency?: number;
+        max_instances?: number;
+        timeout_seconds?: number;
+    };
+}
+type ResponseLifecycle = Pick<EventEmitter, 'once' | 'off'> & {
+    writableFinished?: boolean;
+    destroyed?: boolean;
+};
+export interface AdmissionLease {
+    requestId: string;
+    /** Redis-server deadline, for tracing; local cancellation uses elapsed time. */
+    deadline: number;
+    timeoutMs: number;
+    release(): Promise<void>;
+    /** Register immediately after admission, before starting upstream work.
+     * onTimeout must synchronously abort the upstream before the permit is freed. */
+    bind(response: ResponseLifecycle, onTimeout: () => void): () => void;
+}
+export declare class ArtifactAdmissionError extends Error {
+    readonly status: 429 | 503;
+    readonly code: 'capacity_exceeded' | 'admission_unavailable';
+    constructor(status: 429 | 503, code: 'capacity_exceeded' | 'admission_unavailable');
+}
+/** 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 {
+    private readonly options;
+    private readonly namespace;
+    private readonly ceiling;
+    constructor(options: {
+        redis: AdmissionRedis;
+        namespace: string;
+        platformCeiling?: number;
+        onError?: (event: {
+            kind: 'admission_release_failed' | 'admission_timeout_callback_failed';
+        }) => void;
+    });
+    acquire(target: AdmissionTarget): Promise<AdmissionLease>;
+}
+export {};

package/dist/gateway/admission.js

@@ -0,0 +1,132 @@
+import { randomUUID } from 'node:crypto';
+import { performance } from 'node:perf_hooks';
+import { z } from 'zod';
+import { artifactNextResourceLimitsSchema } from '../manifest-next.js';
+import { redisNamespaceSchema } from '../tunnel/redis-ownership.js';
+export class ArtifactAdmissionError extends Error {
+    status;
+    code;
+    constructor(status, code) {
+        super(status === 429 ? 'Application request capacity exceeded' : 'Application request admission unavailable');
+        this.status = status;
+        this.code = code;
+        this.name = 'ArtifactAdmissionError';
+    }
+}
+// The tunnel's APP_ENV namespace format, so both Redis key spaces accept the same deployment identities.
+const namespace = redisNamespaceSchema;
+const identifier = z.string().min(1).max(128).regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/);
+const resourceFields = artifactNextResourceLimitsSchema.unwrap().shape;
+const resources = z.object({
+    concurrency: resourceFields.concurrency,
+    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
+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
+  redis.call('ZREMRANGEBYSCORE', key, '-inf', now)
+  if redis.call('ZCARD', key) >= maximum then return {0, now} end
+end
+for _, key in ipairs(KEYS) do
+  redis.call('ZADD', key, deadline, ARGV[1])
+  local latest = redis.call('ZREVRANGE', key, 0, 0, 'WITHSCORES')
+  redis.call('PEXPIRE', key, tonumber(latest[2]) - now + 1000)
+end
+return {1, deadline}`;
+const RELEASE = `-- artifact-request-admission-release-v1
+for _, key in ipairs(KEYS) do
+  redis.call('ZREM', key, ARGV[1])
+  if redis.call('ZCARD', key) == 0 then redis.call('DEL', key) end
+end
+return 1`;
+/** 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 class ArtifactRequestAdmission {
+    options;
+    namespace;
+    ceiling;
+    constructor(options) {
+        this.options = options;
+        this.namespace = namespace.parse(options.namespace);
+        this.ceiling = z.number().int().min(1).max(256).parse(options.platformCeiling ?? 256);
+        const policy = options.redis.options;
+        if (policy.enableOfflineQueue !== false || policy.autoResendUnfulfilledCommands !== false || policy.maxRetriesPerRequest !== 0) {
+            throw new Error('Admission Redis must disable offline queues, command replay and retries');
+        }
+    }
+    async acquire(target) {
+        if (namespace.parse(target.environment) !== this.namespace)
+            throw new Error('Admission environment mismatch');
+        const projectId = identifier.parse(target.projectId), deploymentId = identifier.parse(target.deploymentId);
+        const limits = resources.parse(target.resources ?? {});
+        const maximum = Math.min(limits.concurrency * limits.max_instances, this.ceiling);
+        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 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));
+        }
+        catch {
+            throw new ArtifactAdmissionError(503, 'admission_unavailable');
+        }
+        if (result[0] === 0)
+            throw new ArtifactAdmissionError(429, 'capacity_exceeded');
+        // Never start work under an admission whose local request budget already
+        // elapsed while Redis was unavailable or stalled. Redis TTL reclaims it.
+        if (performance.now() - began >= timeoutMs)
+            throw new ArtifactAdmissionError(503, 'admission_unavailable');
+        let releasePromise;
+        let cleanup;
+        let bound = false;
+        const release = () => {
+            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'); });
+            return releasePromise;
+        };
+        const releaseQuietly = () => {
+            void release().catch(() => this.options.onError?.({ kind: 'admission_release_failed' }));
+        };
+        return {
+            requestId, deadline: result[1], timeoutMs, release,
+            bind: (response, onTimeout) => {
+                if (bound || releasePromise)
+                    throw new Error('Admission lease already bound or released');
+                bound = true;
+                const timer = setTimeout(() => {
+                    try {
+                        onTimeout();
+                    }
+                    catch {
+                        this.options.onError?.({ kind: 'admission_timeout_callback_failed' });
+                    }
+                    finally {
+                        releaseQuietly();
+                    }
+                }, Math.max(0, timeoutMs - (performance.now() - began)));
+                timer.unref();
+                cleanup = () => {
+                    clearTimeout(timer);
+                    response.off('finish', releaseQuietly);
+                    response.off('close', releaseQuietly);
+                };
+                response.once('finish', releaseQuietly);
+                response.once('close', releaseQuietly);
+                if (response.writableFinished || response.destroyed)
+                    releaseQuietly();
+                // Detaching also releases; callers cannot strand an admitted permit.
+                return releaseQuietly;
+            },
+        };
+    }
+}

package/dist/gateway/control.d.ts

@@ -0,0 +1,91 @@
+import { z } from 'zod';
+import type { TunnelLease } from '../tunnel/index.js';
+import type { GatewaySession } from './session.js';
+import type { GatewayUsageEvent } from './usage.js';
+export declare const gatewayTargetSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"development">;
+    sessionId: z.ZodString;
+    epoch: z.ZodNumber;
+    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>, z.ZodObject<{
+    kind: z.ZodLiteral<"hosted">;
+    deploymentId: z.ZodString;
+    frameworkBuildId: z.ZodString;
+    upstreamUrl: z.ZodString;
+    upstreamAudience: z.ZodOptional<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>;
+export declare class GatewayControlError extends Error {
+    readonly status: number;
+    constructor(status: number);
+}
+export declare class ArtifactGatewayControl {
+    private readonly options;
+    private readonly origin;
+    constructor(options: {
+        url: string;
+        token: string;
+        fetch?: typeof fetch;
+    });
+    private call;
+    usage(event: GatewayUsageEvent): Promise<void>;
+    bootstrap(ticket: string): Promise<{
+        session: GatewaySession;
+        target: GatewayTarget;
+    }>;
+    authorize(session: GatewaySession): Promise<GatewayTarget>;
+    tunnel({ token, sessionId, epoch }: {
+        token: string;
+        sessionId: string;
+        epoch: number;
+    }): Promise<TunnelLease>;
+}