@sequenceholdings/artifact-studio 0.9.1 → 0.9.2

package/dist/artifact-env-bindings.d.ts

@@ -1,4 +1,4 @@
-/** Fail an artifact deploy whose source still points at another environment. */
+/** Validate explicit artifact manifest bindings against the selected environment. */
 export declare function assertArtifactEnvironmentBindings({ directory, environment, token, }: {
     directory: string;
     environment: {

package/dist/artifact-env-bindings.js

@@ -1,10 +1,11 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
 import { getJsonOr404 } from './api.js';
 import { knownEnvUrls } from './config.js';
 import { assertNoCrossEnvironmentBindings, canonicalDeploymentOrigin } from './env-bindings.js';
-import { readArtifactStudioSource } from './project.js';
-/** Fail an artifact deploy whose source still points at another environment. */
+/** Validate explicit artifact manifest bindings against the selected environment. */
 export async function assertArtifactEnvironmentBindings({ directory, environment, token, }) {
-    const source = await readArtifactStudioSource(directory);
+    const manifest = await readFile(join(directory, 'artifact.bundle.yml'), 'utf8');
     const deployOrigin = canonicalDeploymentOrigin(environment.url);
     if (!deployOrigin)
         throw new Error(`Invalid deployment URL '${environment.url}'.`);
@@ -17,7 +18,7 @@ export async function assertArtifactEnvironmentBindings({ directory, environment
         deployOrigin,
         origins,
         workspaces: [],
-        files: source.files,
+        files: [{ path: 'artifact.bundle.yml', content: manifest }],
         workspaceExists: async (workspaceId) => {
             const workspace = await getJsonOr404({
                 baseUrl: environment.url,

package/dist/build-input-guards.d.ts

@@ -0,0 +1,8 @@
+import { type Plugin } from 'vite';
+import { type SourceBoundary } from './source-boundary.js';
+export declare function guardStylesheetInputsPlugin(boundary: SourceBoundary): Plugin;
+/**
+ * Reject `new URL('<path>', import.meta.url)` assets outside the boundary. A
+ * template literal is a glob over its static directory, which must stay inside.
+ */
+export declare function guardImportMetaUrlPlugin(boundary: SourceBoundary): Plugin;

package/dist/build-input-guards.js

@@ -0,0 +1,178 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { createIdResolver } from 'vite';
+import { isBareImport } from './source-boundary.js';
+/**
+ * Vite and Tailwind resolve some build inputs with internal resolvers that
+ * never reach a plugin's `resolveId`: stylesheet `@import`, CSS `url()` and
+ * `image-set()`, and `new URL('<literal>', import.meta.url)`. Tailwind also
+ * runs JavaScript named by `@plugin` and `@config`. The build runs on the
+ * caller's machine (a laptop, CI, or an agent sandbox holding the caller's
+ * token), so these guards check every such reference against the source
+ * boundary before Vite or Tailwind acts on it.
+ */
+/** The stylesheet requests Vite and Tailwind process (Vite's own CSS language test). */
+const STYLESHEET_REQUEST_RE = /\.(?:css|less|sass|scss|styl|stylus|pcss|postcss|sss)(?:$|\?)|[?&]lang\.css\b/;
+/** Tailwind at-rules that load and run JavaScript at build time. */
+const BUILD_CODE_AT_RULE_RE = /@(?:plugin|config)(?![\w-])/i;
+/** A CSS string: either quote, with the other quote and escapes allowed inside. */
+const CSS_STRING = String.raw `"((?:[^"\\]|\\.)*)"|'((?:[^'\\]|\\.)*)'`;
+/** `@import` / `@reference` targets: a string, or a string or bare token in `url()`. */
+const STYLESHEET_IMPORT_RE = new RegExp(String.raw `@(?:import|reference)\s*(?:url\(\s*)?(?:${CSS_STRING}|([^'"\s;)]+))`, 'gi');
+/** Tailwind `@source` paths (`@source inline(...)` names classes, not files). */
+const SOURCE_DIRECTIVE_RE = new RegExp(String.raw `@source\s+(?:not\s+)?(?:${CSS_STRING})`, 'gi');
+/** Mirrors Vite's `cssUrlRE`, so every `url()` Vite rewrites is checked. */
+const CSS_URL_RE = /(?<=^|[^\w\-\u0080-￿])url\((\s*('[^']+'|"[^"]+")\s*|(?:\\.|[^'")\\])+)\)/g;
+const IMAGE_SET_RE = /image-set\(([^)]*(?:\([^)]*\)[^)]*)*)\)/gi;
+const QUOTED_RE = new RegExp(CSS_STRING, 'g');
+/** Mirrors Vite's `assetImportMetaUrlRE`. */
+const IMPORT_META_URL_RE = /\bnew\s+URL\s*\(\s*('[^']+'|"[^"]+"|`[^`]+`)\s*,\s*import\.meta\.url\s*(?:,\s*)?\)/g;
+const NON_FILE_URL_RE = /^(?:[a-z][a-z\d+.-]*:|\/\/|#)/i;
+function pathOf(id) {
+    if (id.startsWith('\0'))
+        return null;
+    const filePath = id.split('?')[0];
+    return isAbsolute(filePath) ? filePath : null;
+}
+/**
+ * Where Vite would read a referenced asset from: relative to the referencing
+ * file, root-relative then absolute for a leading `/`. Null for a URL that is
+ * not a local file or that does not exist (Vite leaves those unresolved).
+ */
+function referencedFile({ reference, importer, root }) {
+    let target = reference.trim().replace(/^['"]|['"]$/g, '').split(/[?#]/)[0];
+    try {
+        target = decodeURI(target);
+    }
+    catch {
+        // Vite keeps an undecodable URL as written.
+    }
+    if (!target || NON_FILE_URL_RE.test(target))
+        return null;
+    const candidates = target.startsWith('/') ? [join(root, target), target] : [resolve(dirname(importer), target)];
+    return candidates.find((candidate) => existsSync(candidate)) ?? null;
+}
+/**
+ * Reject Tailwind JavaScript loading and out-of-boundary references in every
+ * stylesheet the build processes, following `@import` into nested stylesheets
+ * because Tailwind and Vite read those without another plugin pass. Must run
+ * before Tailwind: list it ahead of `@tailwindcss/vite`.
+ */
+/** The first capture group a match filled: the string body or the bare token. */
+function captured(match) {
+    return match.slice(1).find((group) => group !== undefined);
+}
+export function guardStylesheetInputsPlugin(boundary) {
+    // Files already scanned or being scanned. Recording a file before awaiting
+    // its imports makes an import cycle end instead of awaiting an ancestor.
+    const started = new Set();
+    // Resolve package stylesheets as Vite's CSS @import does (the `style`
+    // condition): a CSS-only package such as tw-animate-css has no JS entry.
+    let resolveStylesheet;
+    async function checkStylesheet({ file, code, resolveStylesheetImport }) {
+        if (!boundary.isTrusted(file) && BUILD_CODE_AT_RULE_RE.test(code)) {
+            throw new Error(`Artifact stylesheet "${file}" uses Tailwind @plugin or @config, which runs JavaScript on the build machine. ` +
+                'Configure Tailwind in CSS (@theme, @utility, @custom-variant) instead.');
+        }
+        const assertPath = (reference, kind) => {
+            const filePath = referencedFile({ reference, importer: file, root: boundary.root });
+            if (filePath)
+                boundary.assertBuildInput({ filePath, importer: file, bareSpecifier: false, reference: kind });
+            return filePath;
+        };
+        const nested = [];
+        for (const match of code.matchAll(STYLESHEET_IMPORT_RE)) {
+            const specifier = captured(match);
+            if (!specifier || NON_FILE_URL_RE.test(specifier))
+                continue;
+            // Check both the literal path and what the CSS resolver finds (which adds
+            // `.css` to an extensionless path and follows a package's `style` entry):
+            // Tailwind and Vite load whichever exists.
+            const literal = assertPath(specifier, 'stylesheet import');
+            const resolved = await resolveStylesheetImport(specifier, file);
+            if (resolved) {
+                boundary.assertBuildInput({ filePath: resolved, importer: file, bareSpecifier: isBareImport(specifier), reference: 'stylesheet import' });
+            }
+            // Tailwind and Vite parse any imported file as CSS, whatever its extension.
+            for (const filePath of new Set([literal, resolved]))
+                if (filePath)
+                    nested.push(filePath);
+        }
+        for (const match of code.matchAll(SOURCE_DIRECTIVE_RE)) {
+            const path = captured(match);
+            if (path)
+                boundary.assertBuildInput({ filePath: resolve(dirname(file), path), importer: file, bareSpecifier: false, reference: '@source path' });
+        }
+        for (const [, reference] of code.matchAll(CSS_URL_RE)) {
+            if (reference)
+                assertPath(reference, 'stylesheet url()');
+        }
+        for (const [, body] of code.matchAll(IMAGE_SET_RE)) {
+            for (const quoted of (body ?? '').matchAll(QUOTED_RE)) {
+                const reference = captured(quoted);
+                if (reference)
+                    assertPath(reference, 'stylesheet image-set()');
+            }
+        }
+        await Promise.all(nested.map((nestedFile) => checkFile(nestedFile, resolveStylesheetImport)));
+    }
+    async function checkFile(file, resolveStylesheetImport) {
+        // A file another traversal already started is checked there, and a failure
+        // there fails the build.
+        if (started.has(file))
+            return;
+        started.add(file);
+        await checkStylesheet({ file, code: await readFile(file, 'utf8'), resolveStylesheetImport });
+    }
+    return {
+        name: 'guard-artifact-stylesheet-inputs',
+        enforce: 'pre',
+        configResolved(config) {
+            resolveStylesheet = createIdResolver(config, {
+                extensions: ['.css'], mainFields: ['style'], conditions: ['style', 'production'], tryIndex: false, preferRelative: true,
+            });
+        },
+        async transform(code, id) {
+            const file = pathOf(id);
+            if (!file || !STYLESHEET_REQUEST_RE.test(id) || /[?&]raw\b/.test(id))
+                return null;
+            const environment = this.environment;
+            const resolveStylesheetImport = async (specifier, importer) => {
+                // An import the CSS resolver cannot find is checked by its literal path;
+                // anything else unresolvable fails in Vite or Tailwind as well.
+                const resolved = await resolveStylesheet?.(environment, specifier, importer).catch(() => undefined);
+                return resolved ? pathOf(resolved) : null;
+            };
+            await checkStylesheet({ file, code, resolveStylesheetImport });
+            return null;
+        },
+    };
+}
+/**
+ * Reject `new URL('<path>', import.meta.url)` assets outside the boundary. A
+ * template literal is a glob over its static directory, which must stay inside.
+ */
+export function guardImportMetaUrlPlugin(boundary) {
+    return {
+        name: 'guard-artifact-import-meta-url',
+        enforce: 'pre',
+        transform(code, id) {
+            const file = pathOf(id);
+            if (!file || STYLESHEET_REQUEST_RE.test(id) || !code.includes('import.meta.url'))
+                return null;
+            for (const [, literal] of code.matchAll(IMPORT_META_URL_RE)) {
+                const body = literal.slice(1, -1);
+                const isTemplate = literal.startsWith('`') && body.includes('${');
+                const reference = isTemplate ? body.slice(0, body.lastIndexOf('/', body.indexOf('${')) + 1) || '.' : body;
+                if (NON_FILE_URL_RE.test(reference))
+                    continue;
+                const target = reference.startsWith('/')
+                    ? [join(boundary.root, reference), reference].find((candidate) => existsSync(candidate)) ?? join(boundary.root, reference)
+                    : resolve(dirname(file), reference);
+                boundary.assertBuildInput({ filePath: target, importer: file, bareSpecifier: false, reference: 'new URL() asset' });
+            }
+            return null;
+        },
+    };
+}

package/dist/build.js

@@ -15,7 +15,8 @@ import { isNextArtifactManifest } from './manifest.js';
 import { normalizeArtifactPath } from './paths.js';
 import { resolveArtifactStudioPeerVersions, } from './peer-versions.js';
 import { ARTIFACT_RUNTIME_CHUNK_DIR, assertSafeRuntimeChunkFileName } from './runtime-chunks.js';
-import { rejectOutsideSourcePlugin } from './source-boundary.js';
+import { guardImportMetaUrlPlugin, guardStylesheetInputsPlugin } from './build-input-guards.js';
+import { createSourceBoundary, rejectOutsideSourcePlugin } from './source-boundary.js';
 import { collectCandidateTokenCompatibilityDiagnostics, collectDeprecatedTokenImportDiagnostics, } from './token-contract.js';
 /** Keep in sync with `atlas/src/server/services/artifact-studio/limits.ts`. */
 const MAX_DEPLOY_SOURCEMAP_BYTES = 10 * 1024 * 1024;
@@ -126,16 +127,24 @@ export async function buildArtifactStudioProject(rootDir, { candidateTokenCompat
     // Give Vite and the source boundary the same physical root.
     const root = await realpath(source.root);
     const transformedCssModules = new Map();
+    const boundary = createSourceBoundary({
+        root,
+        trustedExternalRoots: [...Object.values(peerResolveAlias).map((target) => dirname(target)), dirname(artifactSdkEntry)],
+    });
     const result = await viteBuild({
         root,
         configFile: false,
         logLevel: 'silent',
+        // An inline PostCSS config stops Vite from loading postcss.config.* (or
+        // .postcssrc) from the source tree, which would run repository code on the
+        // build machine. Tailwind runs as the Vite plugin below and needs none.
+        css: { postcss: { plugins: [] } },
         plugins: [
-            rejectOutsideSourcePlugin({
-                root,
-                trustedExternalRoots: [...Object.values(peerResolveAlias).map((target) => dirname(target)), dirname(artifactSdkEntry)],
-            }),
+            rejectOutsideSourcePlugin(boundary),
             rejectIgnoredSourcePlugin(root, source.ignorePatterns),
+            // Before Tailwind, which reads @import / @plugin / @config itself.
+            guardStylesheetInputsPlugin(boundary),
+            guardImportMetaUrlPlugin(boundary),
             artifactSdkVirtualModule(),
             atlasUiCssResolverPlugin({
                 atlasUiDir: selectedAtlasUiDir,

package/dist/cli.d.ts

@@ -39,5 +39,6 @@ export interface ProvidedToken {
     authMode: SourceAuthMode;
     token: string;
 }
+export declare function setPackageInstallUnavailable(guidance: string | null): void;
 export declare function setTokenProvider(provider: ((options: TokenProviderOptions) => Promise<ProvidedToken | null>) | null): void;
 export {};

package/dist/cli.js

@@ -64,6 +64,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.
 
@@ -397,6 +398,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 +422,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 +447,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 +1081,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-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;