@sequenceholdings/artifact-studio 0.9.1 → 0.10.0

package/dist/cli.js

@@ -1,3 +1,4 @@
+import { runContentReadersCommand } from './cli-content-readers.js';
 import { copyFile, cp, mkdir, writeFile } from 'node:fs/promises';
 import { constants, existsSync } from 'node:fs';
 import { dirname, join, relative, resolve } from 'node:path';
@@ -22,7 +23,7 @@ import yaml from 'js-yaml';
 import { warnOnRoleDefinitions } from './role-definitions-notice.js';
 const COMMANDS = [
     'init', 'whoami', 'link', 'env', 'status', 'list', 'show',
-    'validate', 'build', 'plan', 'deploy', 'dev', 'promote', 'pull', 'rollback',
+    'content-readers', 'validate', 'build', 'plan', 'deploy', 'dev', 'promote', 'pull', 'rollback',
 ];
 const USAGE = `usage:
   seq-studio artifact init <dir> [--template react-vite|nextjs]
@@ -40,6 +41,7 @@ const USAGE = `usage:
   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>
+  seq-studio artifact content-readers show|apply --project <id> --env <env> [--file bindings.json]
 
   Add --help or -h to any artifact command to print this usage without running it.
   init includes AGENTS.md pointing to your environment's live docs, with a
@@ -64,6 +66,7 @@ const USAGE = `usage:
   select the target environment. Next.js build/plan/deploy accept --source-env
   to read a Git Service repository from a separately authenticated environment.
   Log in to both environments; source read and target deploy permissions apply.
+  Source identity must be adopted and belong to the destination tenant.
   The target must support verified cross-environment builds. Source credentials
   are used only to fetch source, never passed to the build or stored with it.
 
@@ -110,6 +113,10 @@ export async function runCli(argv = process.argv.slice(2)) {
         case 'promote': return promoteCommand(parsed);
         case 'pull': return pullCommand(parsed);
         case 'rollback': return rollbackCommand(parsed);
+        case 'content-readers': {
+            const env = await envFromArgs(parsed);
+            return runContentReadersCommand({ action: parsed.positional.join(' '), projectId: parsed.flags.project, file: parsed.flags.file, baseUrl: env.url, token: await getRequiredToken(parsed) });
+        }
     }
 }
 function validateKnownOptions(args) {
@@ -124,6 +131,7 @@ function validateKnownOptions(args) {
         dev: { values: ['env', 'key', 'link', 'port'], booleans: ['once'] },
         promote: { values: ['env'], booleans: [] }, pull: { values: ['env', 'out'], booleans: [] },
         rollback: { values: ['env'], booleans: [] },
+        'content-readers': { values: ['env', 'project', 'file'], booleans: [] },
     };
     const { values, booleans } = options[args.command];
     const allowed = new Set([...values, ...booleans]);
@@ -397,6 +405,19 @@ async function showCommand(args) {
     }
     return 0;
 }
+function observedEvidenceLine(evidence) {
+    if ('atlasUi' in evidence) {
+        return `${evidence.channel} / ${evidence.integrityReceipt?.status ?? 'no receipt'} / ${evidence.toolchain.selection} toolchain ` +
+            `(atlas-ui ${evidence.atlasUi.contentHash.slice(0, 12)})`;
+    }
+    const toolchain = evidence.toolchain;
+    const parts = [
+        `Next.js ${toolchain?.next ?? '?'} on Node ${toolchain?.node ?? '?'}`,
+        evidence.builderImage ? `builder ${evidence.builderImage.replace(/^sha256:/, '').slice(0, 12)}` : undefined,
+        evidence.lockfileSha256 ? `lockfile ${evidence.lockfileSha256.slice(0, 12)}` : undefined,
+    ];
+    return parts.filter(Boolean).join(' / ');
+}
 function logActiveDeploymentDetails(deployment) {
     console.log(`    version:    ${deployment.version}`);
     console.log(`    sourceHash: ${deployment.sourceHash}`);
@@ -408,10 +429,8 @@ function logActiveDeploymentDetails(deployment) {
     if (deployment.cliVersion || deployment.atlasUiVersion) {
         console.log(`    peers:      artifact-studio@${deployment.cliVersion ?? '?'} atlas-ui@${deployment.atlasUiVersion ?? '?'}`);
     }
-    if (deployment.observedBuildEvidence) {
-        console.log(`    observed:   ${deployment.observedBuildEvidence.channel} / ${deployment.observedBuildEvidence.integrityReceipt?.status ?? 'no receipt'} / ${deployment.observedBuildEvidence.toolchain.selection} toolchain ` +
-            `(atlas-ui ${deployment.observedBuildEvidence.atlasUi.contentHash.slice(0, 12)})`);
-    }
+    if (deployment.observedBuildEvidence)
+        console.log(`    observed:   ${observedEvidenceLine(deployment.observedBuildEvidence)}`);
     if (deployment.deployMessage)
         console.log(`    message:    ${deployment.deployMessage}`);
     if (deployment.createdAt)
@@ -435,7 +454,10 @@ async function validateCommand(args) {
     return 0;
 }
 async function buildPreparedArtifactSource(source) {
-    await prepareArtifactBuildRoot(source.dir, { remote: source.remote });
+    await prepareArtifactBuildRoot(source.dir, {
+        remote: source.remote,
+        ...(packageInstallUnavailable ? { installUnavailable: packageInstallUnavailable } : {}),
+    });
     return buildArtifactStudioProjectIsolated(source.dir);
 }
 function reportBuildDiagnostics(result) {
@@ -1066,6 +1088,16 @@ function assertSourceEnvironmentSupportsManifest(args) {
         throw new Error('--source-env is supported for Next.js repository builds only.');
 }
 let tokenProvider = null;
+/**
+ * Embedder guidance for a host that cannot reach a package registry, such as an
+ * agent sandbox. When set, a remote build whose package.json declares
+ * production dependencies fails with it instead of attempting an install.
+ * Next.js applications build in Atlas and are unaffected.
+ */
+let packageInstallUnavailable = null;
+export function setPackageInstallUnavailable(guidance) {
+    packageInstallUnavailable = guidance;
+}
 export function setTokenProvider(provider) {
     tokenProvider = provider;
 }

package/dist/{env-binding-scan.d.ts → env-binding-manifest.d.ts}

@@ -1,10 +1,7 @@
 import type { BindingSourceFile, NamedOrigin } from './env-bindings.js';
 export declare function originsDeclaredInFiles(files: readonly BindingSourceFile[]): NamedOrigin[];
 export declare function declaredTargets(content: string): Record<string, string>;
-export declare function contentContainsOrigin(content: string, origin: string, skippedLines: ReadonlySet<number>): boolean;
-/** Manifest text with the root `targets` map removed, so its URLs are declarations. */
-export declare function contentOutsideTargets(content: string): string;
 export declare function collectWorkspaceSlotIds(files: readonly BindingSourceFile[]): string[];
+/** These are schema-defined capability maps, not arbitrary keys containing "workspace". */
 export declare function workspaceSlotIds(file: BindingSourceFile): string[];
-export declare function scannable(file: BindingSourceFile): boolean;
 export declare function basename(path: string): string;

package/dist/env-binding-manifest.js

@@ -0,0 +1,56 @@
+import yaml from 'js-yaml';
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Only schema-defined artifact manifest fields declare bindings; source text is never inspected. */
+function manifestDocument(file) {
+    if (file.encoding === 'base64' || basename(file.path) !== 'artifact.bundle.yml')
+        return undefined;
+    return object(yaml.load(file.content));
+}
+function object(value) {
+    return isRecord(value) ? value : undefined;
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+export function originsDeclaredInFiles(files) {
+    const origins = [];
+    for (const file of files) {
+        if (!manifestDocument(file))
+            continue;
+        for (const [name, url] of Object.entries(declaredTargets(file.content))) {
+            try {
+                origins.push({ name, origin: new URL(url).origin.toLowerCase() });
+            }
+            catch {
+                // An invalid selected target is reported by the binding validator.
+            }
+        }
+    }
+    return origins;
+}
+export function declaredTargets(content) {
+    const targets = object(object(yaml.load(content))?.targets);
+    const urls = {};
+    for (const [name, value] of Object.entries(targets ?? {})) {
+        const url = object(value)?.url;
+        if (typeof url === 'string')
+            urls[name] = url;
+    }
+    return urls;
+}
+export function collectWorkspaceSlotIds(files) {
+    return [...new Set(files.flatMap(workspaceSlotIds))];
+}
+/** These are schema-defined capability maps, not arbitrary keys containing "workspace". */
+export function workspaceSlotIds(file) {
+    const manifest = manifestDocument(file);
+    if (!manifest)
+        return [];
+    const browser = object(object(manifest.capabilities)?.storage);
+    const server = object(object(object(manifest.server)?.capabilities)?.storage);
+    return [...new Set([...Object.keys(browser ?? {}), ...Object.keys(server ?? {})]
+            .filter((id) => UUID.test(id)).map((id) => id.toLowerCase()))];
+}
+export function basename(path) {
+    return path.split('/').at(-1) ?? path;
+}

package/dist/env-bindings.js

@@ -1,4 +1,4 @@
-import { basename, collectWorkspaceSlotIds, contentContainsOrigin, declaredTargets, contentOutsideTargets, originsDeclaredInFiles, scannable, workspaceSlotIds, } from './env-binding-scan.js';
+import { basename, collectWorkspaceSlotIds, declaredTargets, originsDeclaredInFiles, workspaceSlotIds, } from './env-binding-manifest.js';
 export class CrossEnvironmentBindingError extends Error {
     deployEnvironment;
     bindings;
@@ -19,7 +19,7 @@ export function canonicalDeploymentOrigin(url) {
 }
 export function formatCrossEnvironmentBindings({ deployEnvironment, bindings, }) {
     const lines = bindings.map((binding) => `  ${binding.path}: ${binding.message}`);
-    return `Refusing to deploy to ${deployEnvironment} because the source binds another environment.\n${lines.join('\n')}`;
+    return `Refusing to deploy to ${deployEnvironment} because declared manifest bindings do not match the selected environment.\n${lines.join('\n')}`;
 }
 export function findCrossEnvironmentBindings(input) {
     const deployOrigin = canonicalDeploymentOrigin(input.deployOrigin);
@@ -35,7 +35,6 @@ export function findCrossEnvironmentBindings(input) {
     const present = workspaceIdsPresent(input);
     return dedupe([
         ...selectedTargetFindings({ ...input, deployOrigin, origins }),
-        ...foreignOriginFindings({ ...input, deployOrigin, origins }),
         ...unresolvedWorkspaceFindings(input),
         ...foreignWorkspaceFindings({ ...input, present }),
     ]);
@@ -93,35 +92,6 @@ function selectedTargetFindings({ deployEnvironment, deployOrigin, origins, file
     }
     return findings;
 }
-function foreignOriginFindings({ deployOrigin, origins, files, }) {
-    const foreign = new Map();
-    for (const origin of origins) {
-        if (origin.origin === deployOrigin)
-            continue;
-        const names = foreign.get(origin.origin) ?? [];
-        if (!names.includes(origin.name))
-            names.push(origin.name);
-        foreign.set(origin.origin, names);
-    }
-    const findings = [];
-    for (const file of files) {
-        if (!scannable(file))
-            continue;
-        const content = basename(file.path) === 'artifact.bundle.yml' ? contentOutsideTargets(file.content) : file.content;
-        for (const [origin, names] of foreign) {
-            if (!contentContainsOrigin(content, origin, new Set()))
-                continue;
-            findings.push({
-                path: file.path,
-                kind: 'api_origin',
-                value: origin,
-                environment: names[0],
-                message: `API origin ${origin} belongs to ${names.join(', ')}`,
-            });
-        }
-    }
-    return findings;
-}
 function unresolvedWorkspaceFindings(input) {
     const seen = new Set();
     const findings = [];
@@ -142,8 +112,6 @@ function foreignWorkspaceFindings({ deployEnvironment, files, present, }) {
     const findings = [];
     const reported = new Set();
     for (const file of files) {
-        if (!scannable(file))
-            continue;
         for (const workspaceId of workspaceSlotIds(file)) {
             if (present.has(workspaceId) || reported.has(`${file.path}:${workspaceId}`))
                 continue;

package/dist/git-service-client.d.ts

@@ -1,3 +1,14 @@
+/** Read-only server provenance preflight, never a permission grant or an activation token. */
+export declare function checkRepositoryDeploymentIdentity({ baseUrl, token, repoId, commit }: {
+    baseUrl: string;
+    token: string;
+    repoId: string;
+    commit: string;
+}): Promise<{
+    tenantId: string;
+    repositoryId: string;
+    generation: number;
+}>;
 /** Resolve `namespace/name` to a repo id + default branch (FGA-filtered list, paginated). */
 export declare function resolveRepo({ baseUrl, token, namespace, name, }: {
     baseUrl: string;

package/dist/git-service-client.js

@@ -1,6 +1,16 @@
 import { lstat, mkdir, realpath, unlink, writeFile } from 'node:fs/promises';
 import { dirname, resolve, sep } from 'node:path';
 import { getJson, getJsonOr404 } from './api.js';
+import { RepositoryIdentitySchema } from './repository-identity.js';
+/** Read-only server provenance preflight, never a permission grant or an activation token. */
+export async function checkRepositoryDeploymentIdentity({ baseUrl, token, repoId, commit }) {
+    const result = await getJson({ baseUrl, token,
+        path: `/api/git-service/repos/${encodeURIComponent(repoId)}/deployment-admission?commit=${encodeURIComponent(commit)}` });
+    const identity = RepositoryIdentitySchema.parse(result.identity);
+    if (identity.repositoryId !== repoId || result.commit !== commit)
+        throw new Error('Deployment preflight returned a different repository or commit');
+    return identity;
+}
 const REPO_PAGE_SIZE = 200;
 /**
  * Encode a `/`-delimited git path for a `[...path]` / `[...ref]` catch-all

package/dist/manifest-next.d.ts

@@ -86,6 +86,9 @@ export declare const artifactNextBuildConfigSchema: z.ZodPrefault<z.ZodObject<{
         url: z.ZodString;
         sha256: z.ZodString;
     }, z.core.$strict>>>;
+    source_includes: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+    }, z.core.$strict>>>;
 }, z.core.$strict>>;
 export declare const artifactNextServerSchema: z.ZodPrefault<z.ZodObject<{
     capabilities: z.ZodPrefault<z.ZodObject<{
@@ -280,6 +283,9 @@ export declare const artifactStudioNextManifestSchema: z.ZodObject<{
             url: z.ZodString;
             sha256: z.ZodString;
         }, z.core.$strict>>>;
+        source_includes: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+        }, z.core.$strict>>>;
     }, z.core.$strict>>;
     server: z.ZodPrefault<z.ZodObject<{
         capabilities: z.ZodPrefault<z.ZodObject<{

package/dist/manifest-next.js

@@ -1,5 +1,6 @@
 import { ontologyContractSchema } from '@sequenceholdings/orm/canonical';
 import { z } from 'zod';
+import { artifactNextSourceIncludesSchema } from './next-source-includes.js';
 import { capabilityPinsSchema, customRolesBlockSchema, validateCapabilityPins } from './manifest-custom-roles.js';
 import { artifactNextBrowserDataSchema, validateBrowserDataAdmission } from './manifest-next-browser-data.js';
 import { isManagedServerInvokePath } from './server/managed-server-path.js';
@@ -77,6 +78,8 @@ export const artifactNextPublicFontSchema = z.strictObject({
 export const artifactNextBuildConfigSchema = z.strictObject({
     public_env: z.record(publicEnvironmentName, z.string().max(8192)).refine((values) => Object.keys(values).length <= 64, 'At most 64 public build variables are allowed').default({}),
     public_fonts: z.array(artifactNextPublicFontSchema).max(8).refine((fonts) => new Set(fonts.map((font) => font.path)).size === fonts.length, 'Public font destination paths must be unique').default([]),
+    /** Repository directories compiled alongside this bundle; see next-source-includes.ts. */
+    source_includes: artifactNextSourceIncludesSchema,
 }).prefault({});
 const hostname = z.string().max(253).regex(/^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z](?:[a-z0-9-]{0,61}[a-z0-9])?$/, 'Egress entries must be exact lowercase DNS hostnames without schemes, ports, paths, IPs, or wildcards').refine((host) => !host.endsWith('.localhost') && !host.endsWith('.local') && !host.endsWith('.internal'), 'Egress cannot target local or platform-internal hostnames');
 const managedServerInvokePath = z.string().refine(isManagedServerInvokePath, 'Lattice accept paths are exact origin-relative paths with no query or traversal');

package/dist/manifest.d.ts

@@ -3,6 +3,7 @@ import { type ArtifactStudioStaticManifest } from './manifest-static.js';
 import { type ArtifactStudioNextManifest } from './manifest-next.js';
 export * from './manifest-static.js';
 export * from './manifest-next.js';
+export * from './next-source-includes.js';
 /** Versioned parsing keeps schema-v1 stripping/default behavior unchanged. */
 export declare const artifactStudioManifestSchema: z.ZodUnion<readonly [z.ZodObject<{
     ontology: z.ZodOptional<z.ZodObject<{
@@ -161,6 +162,9 @@ export declare const artifactStudioManifestSchema: z.ZodUnion<readonly [z.ZodObj
             url: z.ZodString;
             sha256: z.ZodString;
         }, z.core.$strict>>>;
+        source_includes: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+        }, z.core.$strict>>>;
     }, z.core.$strict>>;
     server: z.ZodPrefault<z.ZodObject<{
         capabilities: z.ZodPrefault<z.ZodObject<{

package/dist/manifest.js

@@ -3,6 +3,7 @@ import { artifactStudioStaticManifestSchema } from './manifest-static.js';
 import { artifactStudioNextManifestSchema } from './manifest-next.js';
 export * from './manifest-static.js';
 export * from './manifest-next.js';
+export * from './next-source-includes.js';
 /** Versioned parsing keeps schema-v1 stripping/default behavior unchanged. */
 export const artifactStudioManifestSchema = z.union([
     artifactStudioStaticManifestSchema,

package/dist/next/bridge.d.ts

@@ -37,7 +37,21 @@ export interface NextArtifactBridge {
     reportRuntimeLog(input: NextArtifactRuntimeLog): void;
     forwardHostShortcut(input: Pick<KeyboardEvent, 'key' | 'code' | 'metaKey' | 'ctrlKey' | 'shiftKey' | 'altKey'>): boolean;
     host: SequenceHost;
-    lattice: SequenceLattice;
+    /** Read only the current viewer's app navigation decisions. This is not an authorization grant. */
+    auth: {
+        getAppAccess(): Promise<Record<string, boolean>>;
+    };
+    lattice: SequenceLattice & {
+        /** Ask the host to verify its own task completed after an app-owned mutation.
+         * Returns false while the native step is pending; retry this read, never the mutation. */
+        notifyAdvance(): Promise<{
+            notified: boolean;
+        }>;
+        /** Verify current host task admission without notifying or completing it. */
+        prepareAdvance(): Promise<{
+            supported: true;
+        }>;
+    };
 }
 /**
  * An SSR-safe external store and DOM transport. Call connect from a client effect,

package/dist/next/bridge.js

@@ -1,3 +1,4 @@
+import { z } from 'zod';
 import { createNextArtifactBridgeEnvelope, EMPTY_NEXT_ARTIFACT_LATTICE_CONTEXT, isNextArtifactRelativePath, nextArtifactInitialContextSchema, nextArtifactThemeSchema, parseNextArtifactBridgeEnvelope, validateNextArtifactBootstrap, } from './protocol.js';
 import { createNextArtifactRequests } from './requests.js';
 import { createNextArtifactStreams } from './streams.js';
@@ -203,7 +204,23 @@ export function createNextArtifactBridge(options) {
             send({ type: 'artifact-studio-host-shortcut', key: input.key, code: input.code, metaKey: input.metaKey, ctrlKey: input.ctrlKey, shiftKey: input.shiftKey, altKey: input.altKey });
             return true;
         },
-        lattice: { context: () => ({ ...(snapshot.lattice ?? EMPTY_NEXT_ARTIFACT_LATTICE_CONTEXT) }) },
+        auth: {
+            async getAppAccess() {
+                const result = await bridge.request({ method: 'auth.getAppAccess' });
+                return z.record(z.string(), z.boolean()).parse(result);
+            },
+        },
+        lattice: {
+            context: () => ({ ...(snapshot.lattice ?? EMPTY_NEXT_ARTIFACT_LATTICE_CONTEXT) }),
+            async prepareAdvance() {
+                const result = await bridge.request({ method: 'lattice.prepareAdvance' });
+                return z.object({ supported: z.literal(true) }).strict().parse(result);
+            },
+            async notifyAdvance() {
+                const result = await bridge.request({ method: 'lattice.notifyAdvance' });
+                return z.object({ notified: z.boolean() }).strict().parse(result);
+            },
+        },
         host: {
             navigate(path) {
                 requireReady();

package/dist/next-source-includes.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Source includes: repository directories a Next artifact compiles alongside
+ * its own bundle, such as a generated ORM client several apps share.
+ *
+ * The bundle directory stays the build boundary. An include is read from the
+ * same immutable commit as the bundle, with the same blob, exclusion and size
+ * checks, and placed at a fixed mount inside the app root, so it becomes
+ * ordinary bundle source: hashed into the source hash, compiled from within
+ * the app (no external directories), and invisible to anything not declared.
+ * Apps import it through a tsconfig path alias to the mount; local
+ * development writes the same mount. Never accepted from a local upload,
+ * whose bytes outside the bundle no dirty bit covers.
+ */
+import { z } from 'zod';
+/** Where includes are placed, relative to app_root. Reserved when any include is declared. */
+export declare const SOURCE_INCLUDE_MOUNT = ".artifact-includes";
+export declare const MAX_SOURCE_INCLUDES = 4;
+export declare const artifactNextSourceIncludeSchema: z.ZodObject<{
+    path: z.ZodString;
+}, z.core.$strict>;
+export type ArtifactNextSourceInclude = z.infer<typeof artifactNextSourceIncludeSchema>;
+export declare const artifactNextSourceIncludesSchema: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    path: z.ZodString;
+}, z.core.$strict>>>;
+export declare function sourceIncludeMountRoot({ appRoot }: {
+    appRoot: string;
+}): string;
+export interface PlannedSourceInclude {
+    /** Path in the repository tree at the build commit. */
+    readonly repositoryPath: string;
+    /** Path in the bundle's source snapshot, under the reserved mount. */
+    readonly sourcePath: string;
+}
+/**
+ * Which repository files each include contributes and where they mount.
+ * `paths` are repository-relative file paths at the build commit; `sourceRoot`
+ * is the bundle directory. Throws for an include that overlaps the bundle or
+ * contributes nothing.
+ */
+export declare function planSourceIncludes({ includes, sourceRoot, appRoot, paths }: {
+    includes: readonly ArtifactNextSourceInclude[];
+    sourceRoot: string;
+    appRoot: string;
+    paths: readonly string[];
+}): PlannedSourceInclude[];
+/** A bundle that declares includes may not commit its own files under the mount they own. */
+export declare function assertNoReservedSourcePaths({ appRoot, paths }: {
+    appRoot: string;
+    paths: readonly string[];
+}): void;

package/dist/next-source-includes.js

@@ -0,0 +1,68 @@
+/**
+ * Source includes: repository directories a Next artifact compiles alongside
+ * its own bundle, such as a generated ORM client several apps share.
+ *
+ * The bundle directory stays the build boundary. An include is read from the
+ * same immutable commit as the bundle, with the same blob, exclusion and size
+ * checks, and placed at a fixed mount inside the app root, so it becomes
+ * ordinary bundle source: hashed into the source hash, compiled from within
+ * the app (no external directories), and invisible to anything not declared.
+ * Apps import it through a tsconfig path alias to the mount; local
+ * development writes the same mount. Never accepted from a local upload,
+ * whose bytes outside the bundle no dirty bit covers.
+ */
+import { z } from 'zod';
+import { isExcludedArtifactSourcePath } from './source-exclusions.js';
+/** Where includes are placed, relative to app_root. Reserved when any include is declared. */
+export const SOURCE_INCLUDE_MOUNT = '.artifact-includes';
+export const MAX_SOURCE_INCLUDES = 4;
+const includePath = z.string().min(1).max(512).refine((value) => !value.startsWith('/') && !/[\\:\s\x00-\x1f]/.test(value) &&
+    value.split('/').every((part) => part !== '' && part !== '.' && part !== '..' && !part.startsWith('.') && part !== 'node_modules') &&
+    !isExcludedArtifactSourcePath({ path: value }), 'Source include paths must be repository-relative directories without traversal, hidden directories, or excluded segments');
+export const artifactNextSourceIncludeSchema = z.strictObject({ path: includePath });
+const isWithin = ({ path, root }) => path === root || path.startsWith(`${root}/`);
+export const artifactNextSourceIncludesSchema = z.array(artifactNextSourceIncludeSchema).max(MAX_SOURCE_INCLUDES).superRefine((includes, ctx) => {
+    includes.forEach((include, index) => {
+        const overlap = includes.findIndex((other, otherIndex) => otherIndex !== index && isWithin({ path: include.path, root: other.path }));
+        if (overlap !== -1)
+            ctx.addIssue({ code: 'custom', path: [index, 'path'], message: `${include.path} overlaps ${includes[overlap]?.path}; declare each directory once` });
+    });
+}).default([]);
+export function sourceIncludeMountRoot({ appRoot }) {
+    return appRoot === '.' ? SOURCE_INCLUDE_MOUNT : `${appRoot}/${SOURCE_INCLUDE_MOUNT}`;
+}
+/**
+ * Which repository files each include contributes and where they mount.
+ * `paths` are repository-relative file paths at the build commit; `sourceRoot`
+ * is the bundle directory. Throws for an include that overlaps the bundle or
+ * contributes nothing.
+ */
+export function planSourceIncludes({ includes, sourceRoot, appRoot, paths }) {
+    if (includes.length === 0)
+        return [];
+    if (sourceRoot === '.')
+        throw new Error('Source includes are unavailable to a bundle at the repository root; its whole tree is already the bundle');
+    const mount = sourceIncludeMountRoot({ appRoot });
+    const planned = [];
+    for (const { path: root } of includes) {
+        if (isWithin({ path: root, root: sourceRoot }))
+            throw new Error(`Source include ${root} is already inside the bundle ${sourceRoot}`);
+        if (isWithin({ path: sourceRoot, root }))
+            throw new Error(`Source include ${root} contains the bundle ${sourceRoot}`);
+        const files = paths
+            .filter((path) => path.startsWith(`${root}/`) && !isExcludedArtifactSourcePath({ path: path.slice(root.length + 1) }))
+            .sort();
+        if (files.length === 0)
+            throw new Error(`Source include ${root} contains no source files at this commit`);
+        for (const repositoryPath of files)
+            planned.push({ repositoryPath, sourcePath: `${mount}/${repositoryPath}` });
+    }
+    return planned;
+}
+/** A bundle that declares includes may not commit its own files under the mount they own. */
+export function assertNoReservedSourcePaths({ appRoot, paths }) {
+    const mount = sourceIncludeMountRoot({ appRoot });
+    const reserved = paths.find((path) => isWithin({ path, root: mount }));
+    if (reserved)
+        throw new Error(`${reserved} is under ${mount}, which is reserved for source includes; remove it from the commit (keep the local copy ignored)`);
+}

package/dist/prepare-build.d.ts

@@ -14,14 +14,22 @@ export declare function extractChainguardAuthLines(userNpmrc: string): string[];
 /** Merge trusted Chainguard auth from ~/.npmrc with pinned install settings. */
 export declare function buildControlledArtifactNpmrc(userNpmrcPath?: string): string;
 export interface PrepareBuildOptions {
-    /** Remote sources (--repo / --git-url) install when package.json exists. */
+    /** Remote sources (--repo / --git-url) install the production dependencies package.json declares. */
     remote?: boolean;
+    /**
+     * Set by an embedder whose host cannot reach a package registry, such as an
+     * agent sandbox. A remote source that needs an install fails with this
+     * guidance instead of attempting one.
+     */
+    installUnavailable?: string;
     /** Parent environment override for deterministic security tests. */
     sourceEnv?: NodeJS.ProcessEnv;
 }
 /**
  * Whether the build should run `pnpm install` before Vite bundles the tree.
- * Only remote materializations (--repo / --git-url) are bare and need install.
+ * Only remote materializations (--repo / --git-url) are bare, and only
+ * production dependencies need installing: the build aliases every scaffold
+ * import (react, atlas-ui, react-query, the SDK) to this package's pinned copies.
  */
 export declare function shouldInstallArtifactDependencies(dir: string, opts?: PrepareBuildOptions): boolean;
 /**

package/dist/prepare-build.js

@@ -46,14 +46,35 @@ export function buildControlledArtifactNpmrc(userNpmrcPath = join(homedir(), '.n
     }
     return `${authBlock}${ARTIFACT_BUILD_NPMRC}`;
 }
+/** The package.json fields `pnpm install --prod` installs. devDependencies never reach a build. */
+const INSTALLED_DEPENDENCY_FIELDS = ['dependencies', 'optionalDependencies'];
+function declaresInstalledDependencies(packageJsonPath) {
+    let manifest;
+    try {
+        manifest = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`package.json is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (typeof manifest !== 'object' || manifest === null || Array.isArray(manifest)) {
+        throw new Error('package.json must be a JSON object.');
+    }
+    return INSTALLED_DEPENDENCY_FIELDS.some((field) => {
+        const value = Reflect.get(manifest, field);
+        return typeof value === 'object' && value !== null && Object.keys(value).length > 0;
+    });
+}
 /**
  * Whether the build should run `pnpm install` before Vite bundles the tree.
- * Only remote materializations (--repo / --git-url) are bare and need install.
+ * Only remote materializations (--repo / --git-url) are bare, and only
+ * production dependencies need installing: the build aliases every scaffold
+ * import (react, atlas-ui, react-query, the SDK) to this package's pinned copies.
  */
 export function shouldInstallArtifactDependencies(dir, opts = {}) {
     if (!opts.remote)
         return false;
-    return existsSync(join(dir, 'package.json'));
+    const packageJsonPath = join(dir, 'package.json');
+    return existsSync(packageJsonPath) && declaresInstalledDependencies(packageJsonPath);
 }
 /**
  * Install artifact runtime deps into the build root. Platform peers (react,
@@ -61,8 +82,17 @@ export function shouldInstallArtifactDependencies(dir, opts = {}) {
  * time — this step resolves app-specific imports like recharts or reactflow.
  */
 export async function prepareArtifactBuildRoot(dir, opts = {}) {
-    if (!shouldInstallArtifactDependencies(dir, opts))
+    if (!opts.remote)
+        return;
+    if (!shouldInstallArtifactDependencies(dir, opts)) {
+        // Nothing to install, but a node_modules committed into the checkout must
+        // still never resolve imports for the build (see the install path below).
+        await rm(join(dir, 'node_modules'), { recursive: true, force: true });
         return;
+    }
+    if (opts.installUnavailable) {
+        throw new Error(`This artifact declares production dependencies (package.json dependencies or optionalDependencies), which install from the package registry. ${opts.installUnavailable}`);
+    }
     if (!existsSync(join(dir, 'pnpm-lock.yaml'))) {
         throw new Error('Remote artifact deploy requires pnpm-lock.yaml — run `pnpm install` locally and commit the lockfile.');
     }

package/dist/repository-identity.d.ts

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+/** Internal wire contract shared by Atlas and seq-studio. Not deployment authorization. */
+export declare const REPOSITORY_IDENTITY_PATH = ".seq/identity.json";
+export declare const RepositoryIdentitySchema: z.ZodObject<{
+    tenantId: z.ZodString;
+    repositoryId: z.ZodString;
+    generation: z.ZodNumber;
+}, z.core.$strict>;
+export type RepositoryIdentity = z.infer<typeof RepositoryIdentitySchema>;
+export declare const RepositoryReceiptSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    identity: z.ZodObject<{
+        tenantId: z.ZodString;
+        repositoryId: z.ZodString;
+        generation: z.ZodNumber;
+    }, z.core.$strict>;
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+}, z.core.$strict>;
+export type RepositoryReceipt = z.infer<typeof RepositoryReceiptSchema>;
+export declare function parseRepositoryReceipt({ text }: {
+    text: string;
+}): RepositoryReceipt;
+export declare function renderRepositoryReceipt({ identity, metadata }: {
+    identity: RepositoryIdentity;
+    metadata?: RepositoryReceipt['metadata'];
+}): string;
+export declare function assertRepositoryIdentity({ receipt, expected }: {
+    receipt: RepositoryReceipt;
+    /** Must come from the authenticated platform record, never from the receipt itself. */
+    expected: RepositoryIdentity;
+}): void;