@sequenceholdings/artifact-studio 0.2.2 → 0.2.4

package/VERSION-PIN.md

@@ -4,6 +4,12 @@ A (re)built Artifact Studio app gets whatever `@sequenceholdings/atlas-ui` the
 **building CLI** carries — not a semver the artifact's own `package.json`
 declares.
 
+Artifact Studio 0.2.4 (Studio CLI 0.1.30) pins Atlas UI 3.1.1 exactly.
+Ordinary builds now use its canonical, mode-aware `tokens.css`. Rebuilding an
+existing artifact adopts this toolchain; previously uploaded immutable bundles
+keep their original CSS. Migrate retired numbered black/white utilities to
+semantic roles and verify a preview before activating a rebuilt artifact.
+
 ## What this means
 
 `shared/services/artifact-studio/src/build.ts` force-aliases platform peers via
@@ -43,12 +49,16 @@ source (and older rows with null peer fields are rebuilt once to populate them).
 `seq-studio artifact plan` reports the same decision, so its `action:` line
 never claims `no-op` for a deploy that would actually rebuild.
 
-## V2 CSS sheets (sandbox previews)
-
-`seq-studio artifact build` idempotently injects `tokens.v2.css` + `theme.v2.css`
-when the artifact CSS entry lacks them (iframes do not inherit Atlas CSSOM; the
-host only stamps `data-tokens` / brand vars). Keep listing `tokens.css` for the
-ungated standalone/`vite dev` fallback. **Do not** import `tokens.v2.tenants.css`.
+## CSS entry points (sandbox previews)
 
-**DES-227 cutover:** remove the build inject; make `tokens.css` the v2 default;
-optionally sweep hand-written `@import …/tokens.v2.css` / `theme.v2.css` lines.
+`tokens.css` is the canonical stylesheet and includes semantic roles plus the
+Tailwind utility bridge. The legacy `tokens.v2.css` and `theme.v2.css` paths are
+temporary forwarding aliases; the compiler normalizes their source imports to one
+canonical layer and reports a migration warning. An explicit
+`seq-studio artifact dev --link <atlas-ui-package-dir>` preview additionally
+reports retired numbered black/white opacity utilities and uncertain dynamic
+class construction. Legacy stylesheet aliases normalize to canonical tokens;
+they do not restore retired utility scales. The runtime forwards brand variables
+independently of `data-tokens`.
+Import `tokens.css` for standalone/`vite dev` compatibility. **Do not** import
+`tokens.v2.tenants.css`.

package/dist/active-deploy-policy.d.ts

@@ -1,8 +1,8 @@
 /**
- * Official (active-channel) Artifact Studio deploys must come from a **clean
- * `main` checkout with a resolved commit** — whether the source is a platform
- * git-service repo (`--repo`) or a monorepo / local checkout. Preview deploys
- * may use feature branches, dirty trees, or other refs.
+ * Official (active-channel) Artifact Studio deploys must come from `main` with
+ * a resolved commit and a clean artifact source directory — whether the source
+ * is a platform git-service repo (`--repo`) or a monorepo / local checkout.
+ * Preview deploys may use feature branches, dirty trees, or other refs.
  *
  * This checks reported provenance (branch name + explicit clean flag + commit).
  * It does **not** independently verify that `gitCommit` equals the remote

package/dist/active-deploy-policy.js

@@ -1,8 +1,8 @@
 /**
- * Official (active-channel) Artifact Studio deploys must come from a **clean
- * `main` checkout with a resolved commit** — whether the source is a platform
- * git-service repo (`--repo`) or a monorepo / local checkout. Preview deploys
- * may use feature branches, dirty trees, or other refs.
+ * Official (active-channel) Artifact Studio deploys must come from `main` with
+ * a resolved commit and a clean artifact source directory — whether the source
+ * is a platform git-service repo (`--repo`) or a monorepo / local checkout.
+ * Preview deploys may use feature branches, dirty trees, or other refs.
  *
  * This checks reported provenance (branch name + explicit clean flag + commit).
  * It does **not** independently verify that `gitCommit` equals the remote
@@ -41,9 +41,12 @@ export function isActiveDeployDefaultBranch(branch) {
  * Preview callers must not invoke this.
  */
 export function assertActiveDeployProvenance(provenance) {
-    // Require an explicit clean recording — omitting gitDirty must not pass.
+    // Require an explicit clean source-directory recording — omitting gitDirty
+    // must not pass. The local source resolver scopes this value to the
+    // artifact directory, so unrelated changes elsewhere in a containing
+    // checkout do not block an official deploy.
     if (provenance.gitDirty !== false) {
-        throw new ActiveDeployPolicyError('Active (official) artifact deploys require a clean git tree ' +
+        throw new ActiveDeployPolicyError('Active (official) artifact deploys require a clean artifact source tree ' +
             '(`gitDirty: false`). Commit or stash your changes, or use ' +
             '`seq-studio artifact dev` / a preview deploy for dirty feature-branch work.');
     }

package/dist/atlas-ui-css-plugin.d.ts

@@ -1,15 +1,36 @@
 import type { Plugin } from 'vite';
+export interface AtlasUiResolvedTokenSelection {
+    specifier: '@sequenceholdings/atlas-ui/tokens.css';
+    injectedBy: string | null;
+}
 /**
- * Idempotent v2 token sheets for Artifact Studio builds. Sandbox iframes do not
- * inherit Atlas CSSOM; the host stamps `data-tokens` (floors to v2) but roles
- * only resolve if the bundle includes these sheets. Skip when the entry already
- * imports them. Remove this inject at DES-227 cutover when `tokens.css` *is* v2.
+ * Every supported source shape becomes one canonical import before Tailwind
+ * expands it. The aliases remain package-compatible, but are no longer allowed
+ * to create duplicate token layers in an Artifact Studio bundle (DES-437).
  */
-export declare function cssAlreadyImportsSheet(code: string, sheetFileName: string): boolean;
-/** Absolute or package `@import` lines to prepend when the CSS entry lacks v2 sheets. */
-export declare function planAtlasUiV2CssImports(code: string, _atlasUiDir: string): string[];
-export declare function atlasUiCssResolverPlugin({ atlasUiDir, atlasUiDist, formRendererDist, }: {
+export declare function normalizeAtlasUiTokenImports(code: string): {
+    code: string;
+    deprecatedImports: string[];
+};
+/**
+ * Evidence mirrors the CSS transform: aliases are normalized away, so the only
+ * selected sheet is the canonical token entry point.
+ */
+export declare function collectAtlasUiResolvedTokenSelections({ cssModules, }: {
+    cssModules: readonly {
+        id: string;
+        code: string;
+    }[];
+    atlasUiDir: string;
+    atlasUiDist: string;
+    formRendererDist: string | null;
+}): AtlasUiResolvedTokenSelection[];
+export declare function atlasUiCssResolverPlugin({ atlasUiDir: _atlasUiDir, atlasUiDist, formRendererDist, onTransform, }: {
     atlasUiDir: string;
     atlasUiDist: string;
     formRendererDist: string | null;
+    onTransform?: (cssModule: {
+        id: string;
+        code: string;
+    }) => void;
 }): Plugin;

package/dist/atlas-ui-css-plugin.js

@@ -17,36 +17,67 @@ function resolveTwAnimateCssPath() {
     }
     return resolved;
 }
+const CANONICAL_TOKEN_IMPORT = '@import "@sequenceholdings/atlas-ui/tokens.css";';
+const ATLAS_UI_TOKEN_IMPORT = /@import\s+(?:url\(\s*)?(?:["'][^"']*?@sequenceholdings\/atlas-ui\/|[^"'()\s;]*@sequenceholdings\/atlas-ui\/)(tokens\.css|tokens\.v2\.css|theme\.v2\.css)(?:["'])?\s*\)?[^;\n]*;/gi;
+function atlasUiTokenImportSheets(code) {
+    return [...code.matchAll(ATLAS_UI_TOKEN_IMPORT)]
+        .map((match) => match[1]?.toLowerCase())
+        .filter((sheet) => sheet !== undefined);
+}
 /**
- * Idempotent v2 token sheets for Artifact Studio builds. Sandbox iframes do not
- * inherit Atlas CSSOM; the host stamps `data-tokens` (floors to v2) but roles
- * only resolve if the bundle includes these sheets. Skip when the entry already
- * imports them. Remove this inject at DES-227 cutover when `tokens.css` *is* v2.
+ * Every supported source shape becomes one canonical import before Tailwind
+ * expands it. The aliases remain package-compatible, but are no longer allowed
+ * to create duplicate token layers in an Artifact Studio bundle (DES-437).
  */
-export function cssAlreadyImportsSheet(code, sheetFileName) {
-    return code.includes(sheetFileName);
+export function normalizeAtlasUiTokenImports(code) {
+    const deprecatedImports = new Set();
+    const withoutTokenImports = code.replace(ATLAS_UI_TOKEN_IMPORT, (importLine, sheet) => {
+        const normalizedSheet = String(sheet).toLowerCase();
+        if (normalizedSheet !== 'tokens.css')
+            deprecatedImports.add(normalizedSheet);
+        return '';
+    });
+    return {
+        code: insertAfterImports(withoutTokenImports, [CANONICAL_TOKEN_IMPORT]),
+        deprecatedImports: [...deprecatedImports],
+    };
 }
-/** Absolute or package `@import` lines to prepend when the CSS entry lacks v2 sheets. */
-export function planAtlasUiV2CssImports(code, _atlasUiDir) {
-    const imports = [];
-    // Package subpaths — resolved via Vite alias (PEER_RESOLVE_ALIAS). Prefer
-    // package form over absolute paths so Tailwind/Vite follow the same path as
-    // hand-written author imports.
-    if (!cssAlreadyImportsSheet(code, 'tokens.v2.css')) {
-        imports.push('@import "@sequenceholdings/atlas-ui/tokens.v2.css";');
+/**
+ * Evidence mirrors the CSS transform: aliases are normalized away, so the only
+ * selected sheet is the canonical token entry point.
+ */
+export function collectAtlasUiResolvedTokenSelections({ cssModules, }) {
+    for (const { code } of cssModules) {
+        if (!code.includes('@import "tailwindcss"'))
+            continue;
+        return [{
+                specifier: '@sequenceholdings/atlas-ui/tokens.css',
+                injectedBy: atlasUiTokenImportSheets(code).includes('tokens.css') ? null : 'atlas-ui-css-resolver',
+            }];
     }
-    if (!cssAlreadyImportsSheet(code, 'theme.v2.css')) {
-        imports.push('@import "@sequenceholdings/atlas-ui/theme.v2.css";');
+    return [];
+}
+/** Put Tailwind source directives after the import block but before style rules. */
+function insertAfterImports(code, lines) {
+    const importPattern = /@import\s+[^;]+;/gi;
+    let lastImport = null;
+    for (let match = importPattern.exec(code); match; match = importPattern.exec(code)) {
+        lastImport = match;
     }
-    return imports;
+    const block = `\n${lines.join('\n')}`;
+    if (lastImport?.index === undefined)
+        return `${lines.join('\n')}\n${code}`;
+    const end = lastImport.index + lastImport[0].length;
+    return `${code.slice(0, end)}${block}${code.slice(end)}`;
 }
-export function atlasUiCssResolverPlugin({ atlasUiDir, atlasUiDist, formRendererDist, }) {
+export function atlasUiCssResolverPlugin({ atlasUiDir: _atlasUiDir, atlasUiDist, formRendererDist, onTransform, }) {
     return {
         name: 'atlas-ui-css-resolver',
         enforce: 'pre',
         transform(code, id) {
             if (!id.endsWith('.css'))
                 return undefined;
+            onTransform?.({ id, code });
             let result = code;
             if (result.includes('@import "tailwindcss"')) {
                 result = result.replace('@import "tailwindcss"', `@import ${JSON.stringify(tailwindCssPath)}`);
@@ -57,8 +88,9 @@ export function atlasUiCssResolverPlugin({ atlasUiDir, atlasUiDist, formRenderer
                 if (formRendererDist) {
                     sources.push(`@source ${JSON.stringify(formRendererDist)};`);
                 }
-                const v2Imports = planAtlasUiV2CssImports(result, atlasUiDir);
-                result = `${sources.join('\n')}\n${v2Imports.join('\n')}${v2Imports.length > 0 ? '\n' : ''}${result}`;
+                const tokenImports = normalizeAtlasUiTokenImports(result);
+                result = tokenImports.code;
+                result = insertAfterImports(result, sources);
             }
             if (result.includes('@import "tw-animate-css"')) {
                 result = result.replace('@import "tw-animate-css"', `@import ${JSON.stringify(twAnimateCssPath)}`);

package/dist/atlas-ui-package-contract.d.ts

@@ -0,0 +1,7 @@
+export declare class AtlasUiPackageContractError extends Error {
+    constructor(message: string);
+}
+export declare function validateAtlasUiTokenStylesheetContract({ packageDir, resolvedTokensCssPath, }: {
+    packageDir: string;
+    resolvedTokensCssPath: string;
+}): string;

package/dist/atlas-ui-package-contract.js

@@ -0,0 +1,60 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+const ATLAS_UI_PACKAGE = '@sequenceholdings/atlas-ui';
+const TOKENS_CSS_EXPORT = './tokens.css';
+export class AtlasUiPackageContractError extends Error {
+    constructor(message) {
+        super(`Atlas UI package contract error: ${message}`);
+        this.name = 'AtlasUiPackageContractError';
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function readExportTarget(value) {
+    if (typeof value === 'string')
+        return value;
+    if (isRecord(value)) {
+        for (const key of ['style', 'default', 'import']) {
+            const target = value[key];
+            if (typeof target === 'string')
+                return target;
+        }
+    }
+    return null;
+}
+export function validateAtlasUiTokenStylesheetContract({ packageDir, resolvedTokensCssPath, }) {
+    const packageJsonPath = resolve(packageDir, 'package.json');
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+    }
+    catch (error) {
+        throw new AtlasUiPackageContractError(`unable to read ${packageJsonPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!isRecord(parsed)) {
+        throw new AtlasUiPackageContractError(`${packageJsonPath} is not a JSON object`);
+    }
+    if (parsed.name !== ATLAS_UI_PACKAGE) {
+        throw new AtlasUiPackageContractError(`${packageJsonPath} must be ${ATLAS_UI_PACKAGE}, got ${String(parsed.name)}`);
+    }
+    const exportsMap = parsed.exports;
+    if (!isRecord(exportsMap)) {
+        throw new AtlasUiPackageContractError(`${ATLAS_UI_PACKAGE} package.json must declare an exports map`);
+    }
+    const exportTarget = readExportTarget(exportsMap[TOKENS_CSS_EXPORT]);
+    if (!exportTarget) {
+        throw new AtlasUiPackageContractError(`${ATLAS_UI_PACKAGE} must export ${TOKENS_CSS_EXPORT} to a CSS file included in the package`);
+    }
+    const declaredPath = resolve(packageDir, exportTarget);
+    if (!existsSync(declaredPath)) {
+        throw new AtlasUiPackageContractError(`${ATLAS_UI_PACKAGE}${TOKENS_CSS_EXPORT} points to ${exportTarget}, but ${declaredPath} does not exist`);
+    }
+    if (!existsSync(resolvedTokensCssPath)) {
+        throw new AtlasUiPackageContractError(`${ATLAS_UI_PACKAGE}${TOKENS_CSS_EXPORT} resolved to ${resolvedTokensCssPath}, but that file does not exist`);
+    }
+    if (resolve(resolvedTokensCssPath) !== declaredPath) {
+        throw new AtlasUiPackageContractError(`${ATLAS_UI_PACKAGE}${TOKENS_CSS_EXPORT} export target (${declaredPath}) and build resolver (${resolvedTokensCssPath}) disagree`);
+    }
+    return declaredPath;
+}

package/dist/build-provenance.d.ts

@@ -0,0 +1,55 @@
+import type { ResolvedStylesheet } from './resolved-stylesheets.js';
+import type { ArtifactStudioPeerVersions } from './peer-versions.js';
+import type { AtlasUiResolvedTokenSelection } from './atlas-ui-css-plugin.js';
+export declare const ARTIFACT_BUILD_PROVENANCE_VERSION = 1;
+export interface ArtifactSourceRevision {
+    commit: string | null;
+    branch: string | null;
+    dirty: boolean | null;
+}
+export interface ArtifactTokenResolution {
+    specifier: string;
+    resolvedPath: string;
+    contentHash: string;
+    cssLayers: string[];
+    injectedBy: string | null;
+}
+/** Observed local build evidence; values are not independently verified by Atlas. */
+export interface ObservedBuildEvidence {
+    schemaVersion: typeof ARTIFACT_BUILD_PROVENANCE_VERSION;
+    channel: 'active' | 'preview';
+    /** `cliVersion` is retained for historical records and identifies Artifact Studio. */
+    toolchain: {
+        cliVersion: string;
+        selection: 'published' | 'linked';
+    };
+    atlasUi: {
+        version: string;
+        contentHash: string;
+    };
+    tokenResolution: {
+        modelVersion: 1;
+        entries: ArtifactTokenResolution[];
+    };
+    /** CSS modules that actually contribute to this artifact's visible cascade. */
+    stylesheets: ResolvedStylesheet[];
+    sourceRevision: ArtifactSourceRevision;
+}
+/**
+ * Evidence from the exact Atlas UI alias targets selected by this build. The
+ * format deliberately records paths and resolved layers, rather than naming a
+ * migration generation; future canonical token entry points need no schema
+ * change.
+ */
+export declare function createObservedBuildEvidence({ atlasUiDir, atlasUiDist, atlasUiTokens, channel, linked, peerVersions, sourceRevision, stylesheets, tokenSelections }: {
+    atlasUiDir: string;
+    atlasUiDist: string;
+    /** Exact tokens.css alias target; releases and linked candidates use different layouts. */
+    atlasUiTokens: string;
+    channel: ObservedBuildEvidence['channel'];
+    linked: boolean;
+    peerVersions: ArtifactStudioPeerVersions;
+    sourceRevision: ArtifactSourceRevision;
+    stylesheets?: ResolvedStylesheet[];
+    tokenSelections: readonly AtlasUiResolvedTokenSelection[];
+}): ObservedBuildEvidence;

package/dist/build-provenance.js

@@ -0,0 +1,45 @@
+import { readFileSync } from 'node:fs';
+import { relative } from 'node:path';
+import { sha256Hex } from './hash.js';
+export const ARTIFACT_BUILD_PROVENANCE_VERSION = 1;
+function cssLayers(content) {
+    return [...content.matchAll(/@layer\s+([\w-]+)/g)].map((match) => match[1]).filter((x) => x !== undefined);
+}
+function contentIdentity(entries) {
+    return sha256Hex(entries.slice().sort((a, b) => a.path.localeCompare(b.path)).map((entry) => `${entry.path}\0${entry.contentHash}`).join('\0'));
+}
+/**
+ * Evidence from the exact Atlas UI alias targets selected by this build. The
+ * format deliberately records paths and resolved layers, rather than naming a
+ * migration generation; future canonical token entry points need no schema
+ * change.
+ */
+export function createObservedBuildEvidence({ atlasUiDir, atlasUiDist, atlasUiTokens, channel, linked, peerVersions, sourceRevision, stylesheets = [], tokenSelections }) {
+    const knownTargets = new Map([
+        ['@sequenceholdings/atlas-ui/tokens.css', { filePath: atlasUiTokens }],
+        ['@sequenceholdings/atlas-ui/tokens.v2.css', { filePath: `${atlasUiDir}/tokens.v2.css` }],
+        ['@sequenceholdings/atlas-ui/theme.v2.css', { filePath: `${atlasUiDir}/theme.v2.css` }],
+    ]);
+    const entries = tokenSelections.map((target) => {
+        const resolved = knownTargets.get(target.specifier);
+        if (!resolved)
+            throw new Error(`Unknown Atlas UI token target: ${target.specifier}`);
+        const filePath = resolved.filePath;
+        const content = readFileSync(filePath, 'utf8');
+        return { specifier: target.specifier, resolvedPath: relative(atlasUiDir, filePath), contentHash: sha256Hex(content), cssLayers: cssLayers(content), injectedBy: target.injectedBy };
+    });
+    const identityEntries = [
+        ...entries.map((entry) => ({ path: entry.resolvedPath, contentHash: entry.contentHash })),
+        { path: 'dist/index.mjs', contentHash: sha256Hex(readFileSync(`${atlasUiDist}/index.mjs`)) },
+        { path: 'dist/charts.mjs', contentHash: sha256Hex(readFileSync(`${atlasUiDist}/charts.mjs`)) },
+    ];
+    return {
+        schemaVersion: ARTIFACT_BUILD_PROVENANCE_VERSION,
+        channel,
+        toolchain: { cliVersion: peerVersions.cliVersion, selection: linked ? 'linked' : 'published' },
+        atlasUi: { version: peerVersions.atlasUiVersion, contentHash: contentIdentity(identityEntries) },
+        tokenResolution: { modelVersion: 1, entries },
+        stylesheets,
+        sourceRevision,
+    };
+}

package/dist/build-subprocess.d.ts

@@ -6,6 +6,8 @@ export interface IsolatedBuildOptions {
     signal?: AbortSignal;
     /** Parent environment override for deterministic security tests. */
     sourceEnv?: NodeJS.ProcessEnv;
+    /** Explicitly report canonical-token compatibility for an Atlas UI --link preview. */
+    candidateTokenCompatibility?: boolean;
 }
 /**
  * Run a single artifact build in a short-lived child process and return its
@@ -14,4 +16,4 @@ export interface IsolatedBuildOptions {
  * long-running watch loops; one-shot commands can call
  * `buildArtifactStudioProject` directly.
  */
-export declare function buildArtifactStudioProjectIsolated(dir: string, { workerPath, signal, sourceEnv }?: IsolatedBuildOptions): Promise<ArtifactStudioBuildResult>;
+export declare function buildArtifactStudioProjectIsolated(dir: string, { workerPath, signal, sourceEnv, candidateTokenCompatibility }?: IsolatedBuildOptions): Promise<ArtifactStudioBuildResult>;

package/dist/build-subprocess.js

@@ -17,7 +17,7 @@ const DEFAULT_WORKER_PATH = existsSync(BUILT_WORKER_PATH)
  * long-running watch loops; one-shot commands can call
  * `buildArtifactStudioProject` directly.
  */
-export async function buildArtifactStudioProjectIsolated(dir, { workerPath = DEFAULT_WORKER_PATH, signal, sourceEnv } = {}) {
+export async function buildArtifactStudioProjectIsolated(dir, { workerPath = DEFAULT_WORKER_PATH, signal, sourceEnv, candidateTokenCompatibility = false } = {}) {
     const scratch = await mkdtemp(join(tmpdir(), 'artifact-build-'));
     const outFile = join(scratch, 'result.json');
     const homeDir = join(scratch, 'home');
@@ -29,6 +29,7 @@ export async function buildArtifactStudioProjectIsolated(dir, { workerPath = DEF
             outFile,
             homeDir,
             signal,
+            candidateTokenCompatibility,
             ...(sourceEnv ? { sourceEnv } : {}),
         });
         return JSON.parse(await readFile(outFile, 'utf8'));
@@ -37,7 +38,7 @@ export async function buildArtifactStudioProjectIsolated(dir, { workerPath = DEF
         await rm(scratch, { recursive: true, force: true });
     }
 }
-function runWorker({ workerPath, dir, outFile, homeDir, signal, sourceEnv, }) {
+function runWorker({ workerPath, dir, outFile, homeDir, signal, sourceEnv, candidateTokenCompatibility, }) {
     return new Promise((resolve, reject) => {
         if (signal?.aborted) {
             reject(new Error('build aborted'));
@@ -46,6 +47,8 @@ function runWorker({ workerPath, dir, outFile, homeDir, signal, sourceEnv, }) {
         const workerArgs = workerPath.endsWith('.ts')
             ? ['--import', 'tsx', workerPath, dir, outFile]
             : [workerPath, dir, outFile];
+        if (candidateTokenCompatibility)
+            workerArgs.push('--candidate-token-compatibility');
         const child = spawn(process.execPath, workerArgs, {
             stdio: ['ignore', 'inherit', 'pipe'],
             env: createScrubbedChildEnv({

package/dist/build-worker.js

@@ -13,13 +13,15 @@
 import { writeFile } from 'node:fs/promises';
 import { buildArtifactStudioProject } from './build.js';
 async function main() {
-    const [dir, outFile] = process.argv.slice(2);
+    const [dir, outFile, candidateFlag] = process.argv.slice(2);
     if (!dir || !outFile) {
         process.stderr.write('usage: build-worker <projectDir> <outFile>\n');
         process.exitCode = 2;
         return;
     }
-    const result = await buildArtifactStudioProject(dir);
+    const result = await buildArtifactStudioProject(dir, {
+        candidateTokenCompatibility: candidateFlag === '--candidate-token-compatibility',
+    });
     await writeFile(outFile, JSON.stringify(result), 'utf8');
 }
 main().catch((error) => {

package/dist/build.d.ts

@@ -1,20 +1,14 @@
+import { type ObservedBuildEvidence } from './build-provenance.js';
 import { type ArtifactStudioSourceFile } from './project.js';
 import type { ArtifactStudioManifest } from './manifest.js';
 import { type ArtifactStudioPeerVersions } from './peer-versions.js';
 /**
- * Import aliases for the Vite build. Artifacts are built against their own
- * source tree, which usually has no installed node_modules, so every bare
- * import the scaffold relies on is aliased to this package's pinned copy.
- * This also pins a single instance of each library — one React, one
- * react-query QueryClient context — so a duplicate copy can't silently break
- * hooks or the provider/consumer link. Exported so it can be regression-tested
- * (a missing/unresolvable peer must fail loudly).
- *
- * **CLI atlas-ui stamp (DES-254):** the atlas-ui a bundle gets is whatever
- * *this* CLI package resolves — not a semver the artifact declares.
- * See `VERSION-PIN.md`.
+ * Released Atlas UI 2.0.1 exports its canonical sheet from dist, while the
+ * candidate layout puts the generated entry at package root so it can be read
+ * before a workspace build. Accept both: ordinary CLI builds retain their
+ * released pin, and explicit linked previews prefer the synced root entry.
  */
-/** Platform + common artifact runtime peers — always aliased over node_modules. */
+export declare function resolveAtlasUiTokensPath(packageDir: string): string;
 export declare const PEER_RESOLVE_ALIAS: Record<string, string>;
 export interface ArtifactStudioRuntimeChunk {
     /** Vite/Rollup output path, always under `chunks/`. */
@@ -39,8 +33,16 @@ export interface ArtifactStudioBuildResult {
     bundleHash: string;
     /** CLI + force-aliased atlas-ui versions that built this bundle (DES-254). */
     peerVersions: ArtifactStudioPeerVersions;
+    /** Exact CLI-resolved UI/token evidence; deployment adds source revision + channel. */
+    observedBuildEvidence: Omit<ObservedBuildEvidence, 'channel' | 'sourceRevision'>;
+    /** Source diagnostics that do not prevent a build. */
+    diagnostics?: string[];
 }
-export declare function buildArtifactStudioProject(rootDir: string): Promise<ArtifactStudioBuildResult>;
+export declare function buildArtifactStudioProject(rootDir: string, { candidateTokenCompatibility, atlasUiPackageDir, }?: {
+    candidateTokenCompatibility?: boolean;
+    /** Explicit linked Atlas UI package, used by candidate toolchain hosts. */
+    atlasUiPackageDir?: string;
+}): Promise<ArtifactStudioBuildResult>;
 export declare function writeBuildArtifact(result: ArtifactStudioBuildResult, outPath: string): Promise<void>;
 export declare function hashBundleAndChunks({ bundle, chunks, }: {
     bundle: string;