@ykdz/template 0.0.36 → 0.0.37

package/node_modules/@ykdz/template-builtin-presets/dist/src/foundation.js

@@ -2,17 +2,21 @@ import { createHash } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { composeCiDiagnosticArtifacts } from "#template-core/ci-diagnostic-artifact";
-import { collectGeneratedManifestCatalogReferences, selectTemplateDependencyCatalogEntries, } from "#template-core/dependency-catalog";
-import { planDevelopmentContainerToolLayersSync, } from "#template-core/development-container-tool-layer";
-import { editorCustomizationForCapabilities, loadEditorCustomizationDeclarations, } from "#template-core/editor-customization";
-import { normalizeEnvironmentNeeds, parseEnvironmentNeedsMetadata, renderDeploymentCheckCommand, renderFixCommand, renderRootCheckCommand, renderTurboRunCommand, } from "#template-core/module-graph";
-import { assertPackageContribution, assertPackageContributionCommandNames, } from "#template-core/package-contribution";
-import { assertProjectBlueprint, assertProjectBlueprintDraft, isValidNewNpmPackageName, validateNewPackagePath, validateProjectBlueprint as validateCoreProjectBlueprint, } from "#template-core/project-blueprint";
-import { projectCheckWorkflowTemplateSource, projectCheckWorkflowTemplateReplacements, projectDependabotTemplateReplacements, } from "#template-core/project-github";
-import { planExplicitProjectLinks } from "#template-core/project-linking-v2";
-import { validateProjectProjectionPlan } from "#template-core/project-projection";
-import { resolveTemplateSource, } from "#template-core/renderer";
+import { isDeepStrictEqual } from "node:util";
+import { composeCiDiagnosticArtifacts } from "@ykdz/template-core/ci-diagnostic-artifact";
+import { collectGeneratedManifestCatalogReferences, selectTemplateDependencyCatalogEntries, } from "@ykdz/template-core/dependency-catalog";
+import { planDevelopmentContainerToolLayersSync, } from "@ykdz/template-core/development-container-tool-layer";
+import { editorCustomizationForCapabilities, loadEditorCustomizationDeclarations, } from "@ykdz/template-core/editor-customization";
+import { normalizeEnvironmentNeeds, parseEnvironmentNeedsMetadata, playwrightBrowserAssetsEnvironmentNeed, renderDeploymentCheckCommand, renderFixCommand, renderRootCheckCommand, renderTurboRunCommand, shellCheckEnvironmentNeed, } from "@ykdz/template-core/module-graph";
+import { assertPackageContribution, assertPackageContributionCommandNames, } from "@ykdz/template-core/package-contribution";
+import { assertProjectBlueprint, assertProjectBlueprintDraft, isValidNewNpmPackageName, validateNewPackagePath, validateProjectBlueprint as validateCoreProjectBlueprint, } from "@ykdz/template-core/project-blueprint";
+import { projectCheckWorkflowTemplateSource, projectCheckWorkflowTemplateReplacements, projectDependabotTemplateReplacements, } from "@ykdz/template-core/project-github";
+import { canConsumeNodePackageNameImport, canLinkNodePackageRoles, canProvideSourceConditionPackageNameImport, planExplicitProjectLinks, } from "@ykdz/template-core/project-linking-v2";
+import { validateProjectProjectionPlan } from "@ykdz/template-core/project-projection";
+import { releaseToolchainSnapshot } from "@ykdz/template-core/release-toolchain-snapshot";
+import { resolveTemplateSource, } from "@ykdz/template-core/renderer";
+import { parse as parseToml } from "smol-toml";
+import ts from "typescript";
 import { isValidDefaultPackageScope, parseGenerationRecord, } from "./generation-record.js";
 import { rustBinDefinition } from "./rust-bin/definition.js";
 import { githubCliDevelopmentContainerToolLayer } from "./shared/development-container.js";
@@ -25,6 +29,20 @@ import { vikeAppDefinition } from "./vike-app/definition.js";
 import { vueAppDefinition } from "./vue-app/definition.js";
 import { vueHonoAppDefinition } from "./vue-hono-app/definition.js";
 const localTemplateMetadataStateKey = Symbol("localTemplateMetadataState");
+export class PackageAdditionBusinessConflict extends Error {
+    kind;
+    existing;
+    requested;
+    missingLink;
+    constructor(kind, existing, requested, missingLink) {
+        super("Package Addition business conflict");
+        this.kind = kind;
+        this.existing = existing;
+        this.requested = requested;
+        if (missingLink !== undefined)
+            this.missingLink = missingLink;
+    }
+}
 const environmentNeedsPath = ".template/environment-needs.json";
 const packageManifestKeyOrder = [
     "name",
@@ -157,12 +175,123 @@ function readGenerationRecord(options) {
     const generationPath = path.join(options.repositoryRoot, ".template/generation.json");
     return parseGenerationRecord(readJsonFile(generationPath, "Generation Record facts"));
 }
+/**
+ * Package Addition 的目标根 package.json 允许两种 Node 声明：旧仓库的纯大版本
+ * （"24"）与精确版本（"24.16.0"），两者都能派生大版本；范围表达式与两段版本拒绝。
+ */
+const nodeMajorOrExactVersionPattern = /^(\d+)(?:\.(\d+)\.(\d+))?$/u;
+/** 与 npm packageManager 字段一致的精确 pnpm pin（可带预发布或构建元数据）。 */
+const exactPnpmPinPattern = /^pnpm@\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/u;
+/**
+ * 目标根现行版本声明缺失或形状错误时的显式带形状内部失败：点名文件与字段、实际值与修正动作，
+ * 由 Package Addition 准备边界传递给命令层；其他 metadata 错误保持通用。
+ */
+class PackageAdditionTargetDeclarationFailure extends Error {
+    field;
+    suggestion;
+    constructor(file, field, requirement, actualDeclaration, suggestion) {
+        super(`加包需要目标仓库根 ${file} 的 ${field} ${requirement}，实际收到 ${actualDeclaration}。${suggestion}`);
+        this.field = field;
+        this.suggestion = suggestion;
+    }
+}
+/**
+ * Package Addition 的版本上下文来自目标仓库根 package.json 的当前声明，因此升级过
+ * Node 或 pnpm 的仓库会继续按自身版本加包；Generation Record 的 toolchain 只保留为
+ * 初始化历史。
+ */
+function readPackageAdditionVersionFacts(repositoryRoot) {
+    const manifest = readRepositoryJsonRecord({
+        repositoryRoot,
+        relativePath: "package.json",
+        label: "root Manifest",
+    });
+    const nodeDeclaration = isRecord(manifest.engines)
+        ? manifest.engines.node
+        : undefined;
+    const nodeDeclarationMatch = typeof nodeDeclaration === "string"
+        ? nodeMajorOrExactVersionPattern.exec(nodeDeclaration)
+        : undefined;
+    const nodeLtsMajor = nodeDeclarationMatch?.[1];
+    if (nodeLtsMajor === undefined || typeof nodeDeclaration !== "string") {
+        throw new PackageAdditionTargetDeclarationFailure("package.json", "engines.node", '声明单个 Node 大版本（"24"）或精确 Node 版本（"24.16.0"）', JSON.stringify(nodeDeclaration ?? null), "请先修改根 package.json 的 engines.node 声明再加包。");
+    }
+    const packageManagerDeclaration = manifest.packageManager;
+    if (typeof packageManagerDeclaration !== "string" ||
+        !exactPnpmPinPattern.test(packageManagerDeclaration)) {
+        throw new PackageAdditionTargetDeclarationFailure("package.json", "packageManager", '声明精确 pnpm 版本（"pnpm@11.21.0"）', JSON.stringify(packageManagerDeclaration ?? null), "请先修改根 package.json 的 packageManager 声明再加包。");
+    }
+    // 根只声明大版本时没有诚实的精确 patch 可传，保持缺省而不伪造。
+    return {
+        toolchain: {
+            nodeLtsMajor,
+            packageManagerPin: packageManagerDeclaration,
+            ...(nodeDeclarationMatch?.[2] === undefined
+                ? {}
+                : { nodeVersion: nodeDeclaration }),
+        },
+        rootNodeDeclaration: nodeDeclaration,
+    };
+}
+/** 生成仓库根 Rust 声明的唯一文件名；所有权判定与投影保留都只经这个接缝引用它。 */
+const rootRustDeclarationFileName = "rust-toolchain.toml";
+/**
+ * 已选用 Rust 的目标仓库由根 rust-toolchain.toml 的 channel 拥有后续 Rust 版本选择，因此加包
+ * 按该现行声明重放根投影与开发容器初值。声明缺失、非法 TOML 或 channel 形状错误时在此失败，
+ * 不回退 CLI 发版快照、Generation Record 历史或 ambient 环境。
+ */
+function readPackageAdditionTargetRustChannel(repositoryRoot) {
+    const relativePath = rootRustDeclarationFileName;
+    const filePath = path.join(repositoryRoot, relativePath);
+    if (!existsSync(filePath)) {
+        throw new PackageAdditionTargetDeclarationFailure(relativePath, "[toolchain].channel", "存在", "文件不存在", `请先创建根 ${relativePath}，在 [toolchain] 表内声明 channel 再加包。`);
+    }
+    let declaration;
+    try {
+        declaration = parseToml(readFileSync(filePath, "utf8"));
+    }
+    catch (error) {
+        throw new PackageAdditionTargetDeclarationFailure(relativePath, "[toolchain].channel", "是有效 TOML 声明", `无法解析：${error instanceof Error ? error.message : String(error)}`, `请先修正根 ${relativePath} 的 TOML 语法，使 [toolchain] 表内声明 channel 再加包。`);
+    }
+    const toolchain = isRecord(declaration) ? declaration.toolchain : undefined;
+    const channel = isRecord(toolchain) ? toolchain.channel : undefined;
+    if (typeof channel !== "string" || channel.trim().length === 0) {
+        throw new PackageAdditionTargetDeclarationFailure(relativePath, "[toolchain].channel", "为非空字符串", JSON.stringify(channel ?? null), `请先在根 ${relativePath} 的 [toolchain] 表内写入 channel 再加包。`);
+    }
+    return channel;
+}
+/**
+ * Root Rust 来源的最小接缝：从 rust-toolchain.toml 正文结构化读出 `[toolchain].channel`。
+ * 复用加包路径同一 smol-toml 真源，供模板仓投影值门核对 M5；不引入第二套版本或文件名表。
+ * 正文非法 TOML 或缺少非空 channel 时返回不可解释，由调用方按缺失/漂移分类，不静默跳过。
+ */
+export function readRustToolchainChannelFromToml(contents) {
+    let declaration;
+    try {
+        declaration = parseToml(contents);
+    }
+    catch (error) {
+        return {
+            reason: `不是有效 TOML 声明：${error instanceof Error ? error.message : String(error)}`,
+            status: "unreadable",
+        };
+    }
+    const toolchain = isRecord(declaration) ? declaration.toolchain : undefined;
+    const channel = isRecord(toolchain) ? toolchain.channel : undefined;
+    if (typeof channel !== "string" || channel.trim().length === 0) {
+        return {
+            reason: `[toolchain].channel 必须是非空字符串，实际为 ${JSON.stringify(channel ?? null)}`,
+            status: "unreadable",
+        };
+    }
+    return { channel, status: "explained" };
+}
 function readJsonFile(filePath, label) {
     try {
         return JSON.parse(readFileSync(filePath, "utf8"));
     }
     catch (error) {
-        throw new Error(`Package Addition requires valid ${label}: ${error instanceof Error ? error.message : String(error)}`);
+        throw new Error(`Package Addition requires valid ${label}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
     }
 }
 function barePackageDefinition(definition) {
@@ -309,7 +438,8 @@ export function loadLocalTemplateMetadata(repositoryRoot) {
         blueprint,
         generationRecord,
     });
-    const context = {
+    const rootVersions = readPackageAdditionVersionFacts(resolvedRoot);
+    const nodeFactsContext = {
         targetDir: resolvedRoot,
         repositoryName: generationRecord.repositoryName,
         defaultPackageScope: generationRecord.defaultPackageScope,
@@ -318,16 +448,37 @@ export function loadLocalTemplateMetadata(repositoryRoot) {
                 name: preflight.foundationPackage.definition.name,
             },
         },
-        toolchain: generationRecord.toolchain,
+        toolchain: rootVersions.toolchain,
     };
-    const planningState = replayLocalTemplateMetadata({
-        context,
+    let context = nodeFactsContext;
+    let planningState = replayLocalTemplateMetadata({
+        context: nodeFactsContext,
         preflight,
     });
+    // 已有 Rust 能力事实的目标仓库由自己的根 rust-toolchain.toml 拥有后续版本选择：读出该现行
+    // channel 后重放，使根声明与开发容器初值来自同一个目标根事实；首次引入 Rust 的仓库还没有
+    // 该声明，保持缺省上下文交由建源路径处理。
+    if (normalizeRustToolchain([
+        planningState.foundationContribution,
+        ...planningState.packageContributions,
+    ]) !== undefined) {
+        context = {
+            ...nodeFactsContext,
+            toolchain: {
+                ...nodeFactsContext.toolchain,
+                rustVersion: readPackageAdditionTargetRustChannel(resolvedRoot),
+            },
+        };
+        planningState = replayLocalTemplateMetadata({ context, preflight });
+    }
     return {
         blueprint,
         context,
-        [localTemplateMetadataStateKey]: { generationRecord, ...planningState },
+        [localTemplateMetadataStateKey]: {
+            generationRecord,
+            rootNodeDeclaration: rootVersions.rootNodeDeclaration,
+            ...planningState,
+        },
     };
 }
 function requireReplayAdapter(options) {
@@ -405,7 +556,7 @@ function readPersistedEnvironmentNeeds(targetDir) {
         value = JSON.parse(readFileSync(filePath, "utf8"));
     }
     catch (error) {
-        throw new Error(`Package Addition requires valid Check Environment Need facts: ${error instanceof Error ? error.message : String(error)}`);
+        throw new Error(`Package Addition requires valid Check Environment Need facts: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
     }
     try {
         return parseEnvironmentNeedsMetadata(value);
@@ -419,8 +570,38 @@ function readExistingPackageAdditionState(options) {
     const state = options.localTemplateMetadata[localTemplateMetadataStateKey];
     const { foundationContribution, generationRecord, packageContributions: contributions, } = state;
     const persistedEnvironmentNeeds = readPersistedEnvironmentNeeds(context.targetDir);
+    const allContributions = [foundationContribution, ...contributions];
+    const deploymentCheck = normalizeDeploymentCheck(allContributions);
+    const vueHonoJointE2e = normalizeVueHonoJointE2e(allContributions);
+    const databasePreparation = normalizeDatabasePreparation(allContributions);
     const manifestTruthByPackagePath = new Map();
     const requiredManifestTruthPackagePaths = new Set(options.requiredManifestTruthPackagePaths ?? []);
+    const packageByName = new Map(allContributions.map((contribution) => [
+        contribution.definition.name,
+        contribution,
+    ]));
+    const capabilityPackageNames = [
+        ...(databasePreparation === undefined
+            ? []
+            : [
+                databasePreparation.databasePackageName,
+                databasePreparation.migrationPackageName,
+                ...Object.values(databasePreparation.consumers),
+            ]),
+        ...(deploymentCheck === undefined
+            ? []
+            : [
+                deploymentCheck.applicationPackageName,
+                deploymentCheck.databasePackageName,
+                deploymentCheck.migrationPackageName,
+            ]),
+    ];
+    for (const packageName of capabilityPackageNames) {
+        const contribution = packageByName.get(packageName);
+        if (contribution !== undefined) {
+            requiredManifestTruthPackagePaths.add(contribution.definition.path);
+        }
+    }
     for (const packagePath of requiredManifestTruthPackagePaths) {
         if (!blueprint.packages.some((definition) => definition.path === packagePath)) {
             throw new Error(`Package Addition requires manifest truth for unknown Package Path ${packagePath}`);
@@ -437,16 +618,26 @@ function readExistingPackageAdditionState(options) {
             manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
         }
         catch (error) {
-            throw new Error(`Package Addition requires manifest truth for ${expectedDefinition.path}: ${error instanceof Error ? error.message : String(error)}`);
+            throw new Error(`Package Addition requires manifest truth for ${expectedDefinition.path}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
         }
         if (!isRecord(manifest) || manifest.name !== expectedDefinition.name) {
             throw new Error(`Package Addition requires manifest truth for ${expectedDefinition.path}: expected name ${expectedDefinition.name}`);
         }
         manifestTruthByPackagePath.set(expectedDefinition.path, manifest);
     }
+    assertCapabilityRepositoryTruth({
+        repositoryRoot: context.targetDir,
+        blueprint,
+        contributions: allContributions,
+        packageByName,
+        manifestTruthByPackagePath,
+        databasePreparation,
+        deploymentCheck,
+        vueHonoJointE2e,
+    });
     const reconstructedEnvironmentNeeds = normalizeEnvironmentNeeds({
-        check: [foundationContribution, ...contributions].flatMap((contribution) => contribution.environmentNeeds),
-        deployment: [foundationContribution, ...contributions].flatMap((contribution) => contribution.deploymentEnvironmentNeeds ?? []),
+        check: foundationCheckEnvironmentNeeds(allContributions, deploymentCheck, vueHonoJointE2e),
+        deployment: deploymentCheck?.environmentNeeds ?? [],
     });
     if (JSON.stringify(reconstructedEnvironmentNeeds) !==
         JSON.stringify(persistedEnvironmentNeeds)) {
@@ -456,7 +647,6 @@ function readExistingPackageAdditionState(options) {
         foundationContribution,
         contributions,
         manifestTruthByPackagePath,
-        deploymentEnvironmentNeeds: persistedEnvironmentNeeds.deployment,
         generationRecord,
     };
 }
@@ -504,13 +694,14 @@ function contributedDevcontainerComposition(options) {
             buildArguments: [
                 {
                     name: "NODE_VERSION",
-                    value: options.context.toolchain.nodeLtsMajor,
-                },
-                {
-                    name: "PACKAGE_MANAGER_PIN",
-                    value: options.context.toolchain.packageManagerPin,
+                    // 根 Node 声明原文是 M1 槽位唯一来源；major 与快照字段不得另作真源。
+                    value: options.rootNodeDeclaration,
                 },
             ],
+            probes: [
+                { identity: "procps", command: "ps", args: ["--version"] },
+                { identity: "bubblewrap", command: "bwrap", args: ["--version"] },
+            ],
             mounts: [
                 {
                     identity: "pnpm-store",
@@ -531,8 +722,7 @@ function contributedDevcontainerComposition(options) {
                 to: ".devcontainer/devcontainer.json",
                 replacements: {
                     PROJECT_NAME: options.context.repositoryName,
-                    NODE_LTS_MAJOR: options.context.toolchain.nodeLtsMajor,
-                    PACKAGE_MANAGER_PIN: options.context.toolchain.packageManagerPin,
+                    NODE_VERSION: options.rootNodeDeclaration,
                 },
             },
             {
@@ -576,191 +766,1094 @@ function contributedDevcontainerComposition(options) {
         probes: layerPlan.probes,
     };
 }
-function contributedFoundationTemplateFileOperations(contributions) {
-    const byIdentity = new Map();
-    const outputOwners = new Map();
-    for (const file of contributions.flatMap((contribution) => contribution.foundation.templateFiles ?? [])) {
-        const previous = byIdentity.get(file.identity);
-        if (previous !== undefined) {
-            const previousFingerprint = JSON.stringify({
-                source: resolveTemplateSource(previous.source, previous.from),
-                from: previous.from,
-                to: previous.to,
-                replacements: previous.replacements ?? {},
-            });
-            const fingerprint = JSON.stringify({
-                source: resolveTemplateSource(file.source, file.from),
-                from: file.from,
-                to: file.to,
-                replacements: file.replacements ?? {},
-            });
-            if (fingerprint !== previousFingerprint) {
-                throw new Error(`Foundation Template File identity ${file.identity} has conflicting descriptors`);
-            }
-            continue;
+function normalizeDatabasePreparation(contributions) {
+    const declarations = contributions.flatMap((contribution) => {
+        const capability = contribution.foundation.databasePreparation;
+        if (capability === undefined)
+            return [];
+        if (capability.kind !== "sqlite-database-preparation") {
+            throw new Error("Database Preparation has an unsupported capability kind");
         }
-        const outputOwner = outputOwners.get(file.to);
-        if (outputOwner !== undefined) {
-            throw new Error(`Foundation Template File output ${file.to} is declared by both ${outputOwner} and ${file.identity}`);
+        const consumers = Object.fromEntries(capability.consumers.map((consumer) => [
+            consumer.kind,
+            consumer.packageName,
+        ]));
+        if (capability.consumers.length !== 3 ||
+            new Set(capability.consumers.map((consumer) => consumer.kind)).size !==
+                3 ||
+            consumers["application-dev"] === undefined ||
+            consumers["database-test"] === undefined ||
+            consumers["application-e2e"] === undefined) {
+            throw new Error("Database Preparation must declare application-dev, database-test, and application-e2e consumers exactly once");
         }
-        byIdentity.set(file.identity, file);
-        outputOwners.set(file.to, file.identity);
-    }
-    return [...byIdentity.values()]
-        .toSorted((left, right) => left.identity.localeCompare(right.identity))
-        .map((file) => ({
-        kind: "writeTextTemplate",
-        source: file.source,
-        from: file.from,
-        to: file.to,
-        replacements: { ...file.replacements },
-    }));
-}
-function assertCompatibleRustToolchainFacts(contributions) {
-    const facts = contributions.flatMap((contribution) => {
-        const rust = contribution.foundation.toolchains.rust;
-        return rust === undefined
-            ? []
-            : [
-                JSON.stringify({
-                    toolchain: rust.toolchain,
-                    components: [...new Set(rust.components)].toSorted(),
+        const normalizedConsumers = {
+            "application-dev": consumers["application-dev"],
+            "database-test": consumers["database-test"],
+            "application-e2e": consumers["application-e2e"],
+        };
+        return [
+            {
+                databasePackageName: contribution.definition.name,
+                migrationPackageName: capability.migrationPackageName,
+                consumers: normalizedConsumers,
+                fingerprint: JSON.stringify({
+                    databasePackageName: contribution.definition.name,
+                    migrationPackageName: capability.migrationPackageName,
+                    consumers: normalizedConsumers,
+                    profiles: ["dev", "test", "e2e"],
                 }),
-            ];
+            },
+        ];
     });
-    if (new Set(facts).size > 1) {
-        throw new Error("Foundation requires compatible Rust toolchain facts");
+    const first = declarations.at(0);
+    if (first === undefined)
+        return undefined;
+    if (declarations.some((item) => item.fingerprint !== first.fingerprint)) {
+        throw new Error("Database Preparation has conflicting capability declarations");
     }
+    return first;
 }
-function composeDependencyMaintenancePolicy(contributions) {
-    const ecosystems = [
-        ...new Set(contributions.flatMap((contribution) => contribution.foundation.dependencyMaintenance.ecosystems)),
+function databasePreparationCommands(preparation) {
+    const run = (profile, packageName, task) => `DATABASE_PROFILE=${profile} pnpm --filter ${packageName} run ${task}`;
+    return {
+        "database:prepare:dev": [
+            run("dev", preparation.migrationPackageName, "db:push"),
+            run("dev", preparation.databasePackageName, "db:seed:example"),
+        ].join(" && "),
+        "database:prepare:test": [
+            run("test", preparation.databasePackageName, "db:reset"),
+            run("test", preparation.migrationPackageName, "db:push"),
+            run("test", preparation.databasePackageName, "db:seed:example"),
+        ].join(" && "),
+        "database:prepare:e2e": [
+            run("e2e", preparation.databasePackageName, "db:reset"),
+            run("e2e", preparation.migrationPackageName, "db:push"),
+            run("e2e", preparation.databasePackageName, "db:seed:example"),
+        ].join(" && "),
+        dev: `pnpm run database:prepare:dev && turbo watch dev --filter=${preparation.consumers["application-dev"]}`,
+    };
+}
+function databasePreparationTurboTasks(preparation) {
+    return {
+        "//#database:prepare:dev": { cache: false },
+        "//#database:prepare:test": { cache: false },
+        "//#database:prepare:e2e": { cache: false },
+        [`${preparation.databasePackageName}#test`]: {
+            dependsOn: ["//#database:prepare:test"],
+        },
+        [`${preparation.migrationPackageName}#typecheck`]: {
+            dependsOn: [`${preparation.databasePackageName}#build`],
+        },
+        [`${preparation.consumers["application-dev"]}#typecheck`]: {
+            dependsOn: [`${preparation.databasePackageName}#build`],
+        },
+        [`${preparation.consumers["application-dev"]}#dev`]: {
+            dependsOn: [`${preparation.databasePackageName}#build`],
+            cache: false,
+            persistent: true,
+        },
+        [`${preparation.consumers["application-e2e"]}#test:e2e`]: {
+            dependsOn: [
+                "//#database:prepare:e2e",
+                `${preparation.databasePackageName}#build`,
+                "build",
+            ],
+            cache: false,
+        },
+    };
+}
+function deploymentTurboTasks(deploymentCheck) {
+    return {
+        "//#deployment": {
+            dependsOn: [
+                `${deploymentCheck.applicationPackageName}#build`,
+                `${deploymentCheck.databasePackageName}#build`,
+                `${deploymentCheck.migrationPackageName}#build`,
+            ],
+            cache: false,
+        },
+    };
+}
+function vueHonoJointE2eTurboTasks(e2e) {
+    return {
+        "//#test:e2e": {
+            dependsOn: [`${e2e.apiPackageName}#build`, `${e2e.webPackageName}#build`],
+            cache: false,
+        },
+    };
+}
+function assertDatabasePreparationManifestTruth(options) {
+    const { preparation, packageByName, manifestTruthByPackagePath } = options;
+    if (preparation === undefined || manifestTruthByPackagePath === undefined) {
+        return;
+    }
+    const expectedTasks = [
+        [preparation.databasePackageName, "build"],
+        [preparation.databasePackageName, "db:reset"],
+        [preparation.databasePackageName, "db:seed:example"],
+        [preparation.databasePackageName, "test"],
+        [preparation.migrationPackageName, "db:push"],
+        [preparation.migrationPackageName, "typecheck"],
+        [preparation.consumers["application-dev"], "dev"],
+        [preparation.consumers["application-dev"], "typecheck"],
+        [preparation.consumers["application-e2e"], "build"],
+        [preparation.consumers["application-e2e"], "test:e2e"],
     ];
-    const directories = {};
-    const extraDirectories = {};
-    for (const ecosystem of ecosystems) {
-        const candidates = [
-            ...new Set(contributions.flatMap((contribution) => {
-                const policy = contribution.foundation.dependencyMaintenance;
-                const primary = policy.directories?.[ecosystem];
-                return [
-                    ...(primary === undefined ? [] : [primary]),
-                    ...(policy.extraDirectories?.[ecosystem] ?? []),
-                ];
-            })),
+    for (const [packageName, taskName] of expectedTasks) {
+        const contribution = requireContributionByName(packageByName, packageName, "Database Preparation");
+        const manifest = requireManifestTruth(manifestTruthByPackagePath, contribution, "Database Preparation");
+        const actualScripts = manifest.scripts;
+        const expectedScripts = contribution.manifest.scripts;
+        const actual = isRecord(actualScripts)
+            ? actualScripts[taskName]
+            : undefined;
+        const expected = isRecord(expectedScripts)
+            ? expectedScripts[taskName]
+            : undefined;
+        if (actual !== expected) {
+            throw new Error(`Database Preparation requires exact ${packageName} script ${taskName}`);
+        }
+    }
+}
+function normalizeDeploymentCheck(contributions) {
+    const declarations = contributions.flatMap((contribution) => {
+        const check = contribution.foundation.deploymentCheck;
+        if (check === undefined)
+            return [];
+        if (check.kind !== "application-container-with-database-migrations") {
+            throw new Error("Deployment Check has an unsupported capability kind");
+        }
+        return [{ ...check, declaringPackagePath: contribution.definition.path }];
+    });
+    if (declarations.length > 1) {
+        throw new Error("Deployment Check has multiple capability declarations");
+    }
+    return declarations.at(0);
+}
+function normalizeVueHonoJointE2e(contributions) {
+    const declarations = contributions.flatMap((contribution) => {
+        const e2e = contribution.foundation.vueHonoJointE2e;
+        if (e2e === undefined)
+            return [];
+        if (e2e.kind !== "vue-hono-joint-e2e") {
+            throw new Error("Vue-Hono joint E2E has an unsupported capability kind");
+        }
+        return [
+            {
+                ...e2e,
+                webPackageName: contribution.definition.name,
+                declaringPackagePath: contribution.definition.path,
+            },
         ];
-        const [primary, ...extra] = candidates;
-        if (primary !== undefined)
-            directories[ecosystem] = primary;
-        if (extra.length > 0)
-            extraDirectories[ecosystem] = extra;
+    });
+    if (declarations.length > 1) {
+        throw new Error("Vue-Hono joint E2E has multiple capability declarations");
     }
-    return {
-        ecosystems,
-        ...(Object.keys(directories).length === 0 ? {} : { directories }),
-        ...(Object.keys(extraDirectories).length === 0 ? {} : { extraDirectories }),
-        interval: "weekly",
-    };
+    return declarations.at(0);
 }
-function localTypescriptConfigurationSpecifier(options) {
-    const relativePackagePath = path.posix.relative(options.consumerPackagePath, options.configurationPackagePath);
-    if (relativePackagePath.length === 0) {
-        throw new Error("TypeScript Configuration Package must have a distinct Package Path");
+function requireContributionByName(packageByName, packageName, capability) {
+    const contribution = packageByName.get(packageName);
+    if (contribution === undefined) {
+        throw new Error(`${capability} references unknown Package ${packageName}`);
     }
-    return `link:${relativePackagePath}`;
+    return contribution;
 }
-function publicCliCandidate(contributions) {
-    const candidates = contributions.filter((contribution) => contribution.foundation.npmPublication?.kind === "public-cli-candidate");
-    if (candidates.length > 1) {
-        throw new Error(`Generated Repository Plan supports at most one public CLI candidate; found ${candidates.map((candidate) => `${candidate.definition.name} at ${candidate.definition.path}`).join(", ")}`);
+function requireManifestTruth(manifestTruthByPackagePath, contribution, capability) {
+    const manifest = manifestTruthByPackagePath.get(contribution.definition.path);
+    if (manifest === undefined) {
+        throw new Error(`${capability} requires manifest truth for ${contribution.definition.path}`);
     }
-    const candidate = candidates[0];
-    if (candidate !== undefined && candidate.definition.role !== "cli-tool") {
-        throw new Error(`Public CLI candidate ${candidate.definition.name} must use the cli-tool Package role`);
+    return manifest;
+}
+function assertExpectedRecordMembers(options) {
+    if (!isRecord(options.expected)) {
+        throw new Error(`${options.label} replay did not provide object truth`);
+    }
+    if (!isRecord(options.actual)) {
+        throw new Error(`${options.label} must be an object`);
+    }
+    for (const [key, expectedValue] of Object.entries(options.expected)) {
+        if (!isDeepStrictEqual(options.actual[key], expectedValue)) {
+            throw new Error(`${options.label} must preserve replayed member ${key}`);
+        }
     }
-    return candidate;
 }
-function renderPublicationRootCheckCommand(candidatePackagePath) {
-    return [
-        renderTurboRunCommand(["boundaries", "format:check", "lint", "typecheck", "test"], [], { continueAfterFailure: true, taskPrefix: true }),
-        renderTurboRunCommand(["build", "test:e2e"], [`--filter=!./${candidatePackagePath}`], { continueAfterFailure: true, taskPrefix: true }),
-        "pnpm run publication:artifact",
-    ].join(" && ");
+function assertArtifactConditionOrder(options) {
+    if (!isRecord(options.expected) || !isRecord(options.actual))
+        return;
+    const conditionNames = ["source", "types", "default"];
+    const expectedConditions = Object.keys(options.expected).filter((name) => conditionNames.includes(name));
+    if (!expectedConditions.includes("source") ||
+        !expectedConditions.some((name) => name === "types" || name === "default")) {
+        return;
+    }
+    const actualConditions = Object.keys(options.actual).filter((name) => expectedConditions.includes(name));
+    if (!isDeepStrictEqual(actualConditions, expectedConditions)) {
+        throw new Error(`${options.label} must preserve replayed condition order`);
+    }
 }
-function foundationPlan(options) {
-    assertProjectBlueprint(options.blueprint);
-    const configContribution = options.foundationContribution;
-    const configDefinition = configContribution.definition;
-    if (!options.blueprint.packages.some((definition) => packageDefinitionsEqual(definition, configDefinition))) {
-        throw new Error("Project Blueprint must contain the Foundation TypeScript configuration Package Definition");
+function assertDatabaseArtifactConditionTruth(options) {
+    if (!isRecord(options.actual) || !isRecord(options.expected))
+        return;
+    for (const [memberName, expectedMember] of Object.entries(options.expected)) {
+        assertArtifactConditionOrder({
+            actual: options.actual[memberName],
+            expected: expectedMember,
+            label: `${options.label} ${memberName}`,
+        });
     }
-    const initialProjectLinkPlan = planExplicitProjectLinks({
+}
+function assertDatabaseArtifactManifestTruth(options) {
+    if (options.preparation === undefined)
+        return;
+    const database = requireContributionByName(options.packageByName, options.preparation.databasePackageName, "Database Preparation");
+    const actual = requireManifestTruth(options.manifestTruthByPackagePath, database, "Database Preparation");
+    const expected = database.manifest;
+    if (actual.type !== expected.type || expected.type !== "module") {
+        throw new Error(`Database Preparation requires ${database.definition.name} manifest type module`);
+    }
+    if (!Array.isArray(expected.files)) {
+        throw new Error(`Database Preparation replay for ${database.definition.name} did not provide files truth`);
+    }
+    const actualFiles = actual.files;
+    if (!Array.isArray(actualFiles) ||
+        expected.files.some((expectedFile) => !actualFiles.some((actualFile) => isDeepStrictEqual(actualFile, expectedFile)))) {
+        throw new Error(`Database Preparation requires ${database.definition.name} public build files`);
+    }
+    assertExpectedRecordMembers({
+        actual: actual.exports,
+        expected: expected.exports,
+        label: `Database Preparation ${database.definition.name} exports`,
+    });
+    assertDatabaseArtifactConditionTruth({
+        actual: actual.exports,
+        expected: expected.exports,
+        label: `Database Preparation ${database.definition.name} exports`,
+    });
+    assertExpectedRecordMembers({
+        actual: actual.imports,
+        expected: expected.imports,
+        label: `Database Preparation ${database.definition.name} imports`,
+    });
+    assertDatabaseArtifactConditionTruth({
+        actual: actual.imports,
+        expected: expected.imports,
+        label: `Database Preparation ${database.definition.name} imports`,
+    });
+}
+function assertDatabaseProjectLinkManifestTruth(options) {
+    if (options.preparation === undefined)
+        return;
+    const database = requireContributionByName(options.packageByName, options.preparation.databasePackageName, "Database Preparation");
+    const expectedLinks = planExplicitProjectLinks({
         blueprint: options.blueprint,
         contributions: options.contributions,
-        ...(options.manifestTruthByPackagePath === undefined
+    });
+    for (const intent of options.blueprint.packageLinkIntents ?? []) {
+        if (intent.providerPackagePath !== database.definition.path)
+            continue;
+        const consumer = options.contributions.find((candidate) => candidate.definition.path === intent.consumerPackagePath);
+        if (consumer === undefined) {
+            throw new Error(`Database Preparation Project Link references unknown consumer ${intent.consumerPackagePath}`);
+        }
+        const actual = requireManifestTruth(options.manifestTruthByPackagePath, consumer, "Database Preparation Project Link");
+        if (!isRecord(actual.dependencies) ||
+            actual.dependencies[database.definition.name] !== "workspace:*") {
+            throw new Error(`Database Preparation requires ${consumer.definition.name} to depend on ${database.definition.name} through workspace:*`);
+        }
+        const expectedMetadata = expectedLinks.manifestPatchesByPackagePath.get(consumer.definition.path)?.dependenciesMeta?.[database.definition.name];
+        if (actual.dependenciesMeta !== undefined &&
+            !isRecord(actual.dependenciesMeta)) {
+            throw new Error(`Database Preparation requires valid dependency metadata in ${consumer.definition.name}`);
+        }
+        const actualMetadata = isRecord(actual.dependenciesMeta)
+            ? actual.dependenciesMeta[database.definition.name]
+            : undefined;
+        if (!isDeepStrictEqual(actualMetadata, expectedMetadata)) {
+            throw new Error(`Database Preparation requires replayed Project Link metadata for ${consumer.definition.name} -> ${database.definition.name}`);
+        }
+    }
+}
+function assertDeploymentBuildManifestTruth(options) {
+    if (options.deploymentCheck === undefined)
+        return;
+    for (const packageName of [
+        options.deploymentCheck.applicationPackageName,
+        options.deploymentCheck.databasePackageName,
+        options.deploymentCheck.migrationPackageName,
+    ]) {
+        const contribution = requireContributionByName(options.packageByName, packageName, "Deployment Check");
+        const actual = requireManifestTruth(options.manifestTruthByPackagePath, contribution, "Deployment Check");
+        const actualBuild = isRecord(actual.scripts)
+            ? actual.scripts.build
+            : undefined;
+        const expectedBuild = isRecord(contribution.manifest.scripts)
+            ? contribution.manifest.scripts.build
+            : undefined;
+        if (typeof expectedBuild !== "string" || actualBuild !== expectedBuild) {
+            throw new Error(`Deployment Check requires exact ${packageName} manifest script build`);
+        }
+    }
+}
+function assertVueHonoJointE2eManifestTruth(options) {
+    if (options.e2e === undefined)
+        return;
+    if (options.e2e.apiPackageName === options.e2e.webPackageName) {
+        throw new Error("Vue-Hono joint E2E requires distinct API and web Packages");
+    }
+    const expectedTasks = [
+        [options.e2e.apiPackageName, "build"],
+        [options.e2e.apiPackageName, "start"],
+        [options.e2e.webPackageName, "build"],
+        [options.e2e.webPackageName, "preview"],
+    ];
+    for (const [packageName, taskName] of expectedTasks) {
+        const contribution = requireContributionByName(options.packageByName, packageName, "Vue-Hono joint E2E");
+        const actual = requireManifestTruth(options.manifestTruthByPackagePath, contribution, "Vue-Hono joint E2E");
+        const expected = isRecord(contribution.manifest.scripts)
+            ? contribution.manifest.scripts[taskName]
+            : undefined;
+        const actualScript = isRecord(actual.scripts)
+            ? actual.scripts[taskName]
+            : undefined;
+        if (typeof expected !== "string" || actualScript !== expected) {
+            throw new Error(`Vue-Hono joint E2E requires exact ${packageName} manifest script ${taskName}`);
+        }
+    }
+}
+function readRepositoryJsonRecord(options) {
+    const value = readJsonFile(path.join(options.repositoryRoot, options.relativePath), `${options.label} in ${options.relativePath}`);
+    if (!isRecord(value)) {
+        throw new Error(`Package Addition requires ${options.label} in ${options.relativePath} to be an object`);
+    }
+    return value;
+}
+function assertRootCapabilityManifestTruth(options) {
+    if (options.databasePreparation === undefined &&
+        options.deploymentCheck === undefined &&
+        options.vueHonoJointE2e === undefined) {
+        return;
+    }
+    const manifest = readRepositoryJsonRecord({
+        repositoryRoot: options.repositoryRoot,
+        relativePath: "package.json",
+        label: "root Manifest Truth",
+    });
+    if (!isRecord(manifest.scripts)) {
+        throw new Error("Package Addition requires root manifest scripts truth");
+    }
+    const expectedScripts = {
+        ...(options.databasePreparation === undefined
+            ? {}
+            : databasePreparationCommands(options.databasePreparation)),
+        ...(options.deploymentCheck === undefined
             ? {}
             : {
-                manifestTruthByPackagePath: options.manifestTruthByPackagePath,
+                deployment: "node --conditions=source scripts/check-standalone-deployment.ts",
+                "check:deployment": renderDeploymentCheckCommand(),
             }),
-    });
-    const injectedProviderNames = new Set([...initialProjectLinkPlan.manifestPatchesByPackagePath.values()].flatMap((patch) => Object.entries(patch.dependenciesMeta)
-        .filter(([, metadata]) => metadata.injected)
-        .map(([name]) => name)));
-    const configPackageName = options.context.foundationPackages.typescriptConfiguration.name;
-    if (configDefinition.name !== configPackageName) {
-        throw new Error(`Generation Context TypeScript Configuration Package ${configPackageName} conflicts with Blueprint Package Definition ${configDefinition.name}`);
+        ...(options.vueHonoJointE2e === undefined
+            ? {}
+            : { "test:e2e": "playwright test" }),
+    };
+    for (const [scriptName, expectedCommand] of Object.entries(expectedScripts)) {
+        if (manifest.scripts[scriptName] !== expectedCommand) {
+            throw new Error(`Package Addition requires exact root manifest script ${scriptName}`);
+        }
     }
-    const publicationCandidate = publicCliCandidate(options.contributions);
-    const packageContributions = options.contributions.map((contribution) => {
-        if (contribution.foundation.typescriptConfigurationPackage === undefined) {
-            return contribution;
+}
+function assertTurboTaskTruth(options) {
+    if (!isRecord(options.config.tasks)) {
+        throw new Error(`${options.label} requires Turbo tasks truth`);
+    }
+    for (const [taskName, expectedTask] of Object.entries(options.expectedTasks)) {
+        const actualTask = options.config.tasks[taskName];
+        if (!isRecord(actualTask)) {
+            throw new Error(`${options.label} requires Turbo task ${taskName}`);
         }
-        const dependencyField = injectedProviderNames.has(contribution.definition.name)
-            ? "dependencies"
-            : "devDependencies";
-        const dependencySpecifier = dependencyField === "devDependencies" &&
-            (contribution.manifest.private !== true ||
-                publicationCandidate?.definition.path === contribution.definition.path)
-            ? localTypescriptConfigurationSpecifier({
-                consumerPackagePath: contribution.definition.path,
-                configurationPackagePath: configDefinition.path,
-            })
-            : "workspace:*";
-        const existingDependencies = contribution.manifest[dependencyField];
-        return {
-            ...contribution,
-            manifest: {
-                ...contribution.manifest,
-                [dependencyField]: {
-                    ...(isRecord(existingDependencies) ? existingDependencies : {}),
-                    [configPackageName]: dependencySpecifier,
-                },
-            },
-        };
-    });
-    const requiresPackingHook = packageContributions.some((contribution) => {
-        const developmentDependencies = contribution.manifest.devDependencies;
-        return (isRecord(developmentDependencies) &&
-            typeof developmentDependencies[configPackageName] === "string" &&
-            developmentDependencies[configPackageName].startsWith("link:"));
-    });
-    const contributions = [configContribution, ...packageContributions];
-    assertPackageContributionCommandNames(contributions.map((contribution) => {
-        const manifest = options.manifestTruthByPackagePath?.get(contribution.definition.path);
-        return manifest === undefined
-            ? contribution
-            : { ...contribution, manifest };
-    }));
-    const candidateRecord = options.generationRecord ?? {
-        schemaVersion: 2,
-        repositoryName: options.context.repositoryName,
-        defaultPackageScope: options.context.defaultPackageScope,
-        preset: options.definition.metadata.name,
-        templateVersion: "0.0.0",
-        toolchain: options.context.toolchain,
-        packages: [
-            ...options.contributions.map((contribution) => {
-                const planningContribution = options.mode === "initialization"
+        for (const [field, expectedValue] of Object.entries(expectedTask)) {
+            const actualValue = actualTask[field];
+            if (Array.isArray(expectedValue)) {
+                if (!Array.isArray(actualValue) ||
+                    expectedValue.some((expectedMember) => !actualValue.includes(expectedMember))) {
+                    throw new Error(`${options.label} requires Turbo task ${taskName} ${field}`);
+                }
+            }
+            else if (!isDeepStrictEqual(actualValue, expectedValue)) {
+                throw new Error(`${options.label} requires Turbo task ${taskName} ${field}`);
+            }
+        }
+    }
+}
+function assertCapabilityPackageTurboInheritanceTruth(options) {
+    if (!Array.isArray(options.config.extends) ||
+        options.config.extends.length !== 1 ||
+        options.config.extends[0] !== "//") {
+        throw new Error(`${options.label} requires exact Turbo extends truth`);
+    }
+}
+function effectiveCapabilityTaskDependencies(options) {
+    if (options.localTask === undefined) {
+        if (!isRecord(options.inheritedTask)) {
+            throw new Error(`${options.label} requires Turbo task ${options.taskName}`);
+        }
+        return options.inheritedTask.dependsOn;
+    }
+    if (!isRecord(options.localTask)) {
+        throw new Error(`${options.label} requires Turbo task ${options.taskName}`);
+    }
+    const extendsValue = options.localTask.extends;
+    if (extendsValue !== undefined && typeof extendsValue !== "boolean") {
+        throw new Error(`${options.label} requires Turbo task ${options.taskName} extends truth`);
+    }
+    if (extendsValue === false || options.localTask.dependsOn !== undefined) {
+        return options.localTask.dependsOn;
+    }
+    if (!isRecord(options.inheritedTask)) {
+        throw new Error(`${options.label} requires Turbo task ${options.taskName}`);
+    }
+    return options.inheritedTask.dependsOn;
+}
+function assertCapabilityConsumerTurboTruth(options) {
+    const turboByPackagePath = new Map();
+    for (const [qualifiedTaskName, expectedTask] of Object.entries(options.expectedTasks)) {
+        if (expectedTask.dependsOn === undefined)
+            continue;
+        const separator = qualifiedTaskName.lastIndexOf("#");
+        if (separator <= 0)
+            continue;
+        const packageName = qualifiedTaskName.slice(0, separator);
+        const taskName = qualifiedTaskName.slice(separator + 1);
+        const contribution = requireContributionByName(options.packageByName, packageName, "Database Preparation");
+        const packageTurbo = turboByPackagePath.get(contribution.definition.path) ??
+            readRepositoryJsonRecord({
+                repositoryRoot: options.repositoryRoot,
+                relativePath: `${contribution.definition.path}/turbo.json`,
+                label: `${contribution.definition.name} Turbo Truth`,
+            });
+        turboByPackagePath.set(contribution.definition.path, packageTurbo);
+        if (!isRecord(packageTurbo.tasks)) {
+            throw new Error(`Package Addition ${contribution.definition.name} Turbo Truth requires Turbo tasks truth`);
+        }
+        assertCapabilityPackageTurboInheritanceTruth({
+            config: packageTurbo,
+            label: `Package Addition ${contribution.definition.name} Turbo Truth`,
+        });
+        const localTask = packageTurbo.tasks[taskName];
+        const localDependencies = effectiveCapabilityTaskDependencies({
+            localTask,
+            inheritedTask: expectedTask,
+            label: `Package Addition ${contribution.definition.name} Turbo Truth`,
+            taskName,
+        });
+        if (!Array.isArray(localDependencies) ||
+            expectedTask.dependsOn.some((expectedDependency) => !localDependencies.includes(expectedDependency))) {
+            throw new Error(`Package Addition ${contribution.definition.name} Turbo Truth requires Turbo task ${taskName} dependsOn`);
+        }
+    }
+    for (const packageName of options.buildConsumerPackageNames) {
+        const contribution = requireContributionByName(options.packageByName, packageName, "Database Preparation");
+        const packageTurbo = turboByPackagePath.get(contribution.definition.path) ??
+            readRepositoryJsonRecord({
+                repositoryRoot: options.repositoryRoot,
+                relativePath: `${contribution.definition.path}/turbo.json`,
+                label: `${contribution.definition.name} Turbo Truth`,
+            });
+        turboByPackagePath.set(contribution.definition.path, packageTurbo);
+        if (!isRecord(packageTurbo.tasks)) {
+            throw new Error(`Package Addition ${contribution.definition.name} Turbo Truth requires Turbo tasks truth`);
+        }
+        assertCapabilityPackageTurboInheritanceTruth({
+            config: packageTurbo,
+            label: `Package Addition ${contribution.definition.name} Turbo Truth`,
+        });
+        const localBuild = packageTurbo.tasks.build;
+        const qualifiedBuild = isRecord(options.rootTurbo.tasks)
+            ? options.rootTurbo.tasks[`${packageName}#build`]
+            : undefined;
+        const genericBuild = isRecord(options.rootTurbo.tasks)
+            ? options.rootTurbo.tasks.build
+            : undefined;
+        const dependencies = effectiveCapabilityTaskDependencies({
+            localTask: localBuild,
+            inheritedTask: qualifiedBuild === undefined ? genericBuild : qualifiedBuild,
+            label: `Package Addition ${contribution.definition.name} Turbo Truth`,
+            taskName: "build",
+        });
+        if (!Array.isArray(dependencies) ||
+            !dependencies.some((dependency) => dependency === "^build" ||
+                dependency === `${options.databasePackageName}#build`)) {
+            throw new Error(`Package Addition ${contribution.definition.name} Turbo Truth requires Turbo task build dependsOn`);
+        }
+    }
+}
+function assertCapabilityTurboTruth(options) {
+    if (options.databasePreparation === undefined &&
+        options.deploymentCheck === undefined &&
+        options.vueHonoJointE2e === undefined) {
+        return;
+    }
+    const rootTurbo = readRepositoryJsonRecord({
+        repositoryRoot: options.repositoryRoot,
+        relativePath: "turbo.json",
+        label: "root Turbo Truth",
+    });
+    assertTurboTaskTruth({
+        config: rootTurbo,
+        expectedTasks: {
+            ...(options.databasePreparation === undefined
+                ? {}
+                : databasePreparationTurboTasks(options.databasePreparation)),
+            ...(options.deploymentCheck === undefined
+                ? {}
+                : deploymentTurboTasks(options.deploymentCheck)),
+            ...(options.vueHonoJointE2e === undefined
+                ? {}
+                : vueHonoJointE2eTurboTasks(options.vueHonoJointE2e)),
+        },
+        label: "Package Addition root Turbo Truth",
+    });
+    if (options.databasePreparation === undefined)
+        return;
+    const database = requireContributionByName(options.packageByName, options.databasePreparation.databasePackageName, "Database Preparation");
+    const databaseTurbo = readRepositoryJsonRecord({
+        repositoryRoot: options.repositoryRoot,
+        relativePath: `${database.definition.path}/turbo.json`,
+        label: `${database.definition.name} Turbo Truth`,
+    });
+    assertTurboTaskTruth({
+        config: databaseTurbo,
+        expectedTasks: { build: { outputs: ["dist/**"] } },
+        label: `Package Addition ${database.definition.name} Turbo Truth`,
+    });
+    assertCapabilityConsumerTurboTruth({
+        repositoryRoot: options.repositoryRoot,
+        rootTurbo,
+        expectedTasks: databasePreparationTurboTasks(options.databasePreparation),
+        buildConsumerPackageNames: [
+            options.databasePreparation.migrationPackageName,
+            ...new Set(Object.values(options.databasePreparation.consumers)),
+        ],
+        databasePackageName: options.databasePreparation.databasePackageName,
+        packageByName: options.packageByName,
+    });
+}
+function unwrapTypeScriptExpression(expression) {
+    return ts.isParenthesizedExpression(expression) ||
+        ts.isAsExpression(expression) ||
+        ts.isSatisfiesExpression(expression) ||
+        ts.isTypeAssertionExpression(expression)
+        ? unwrapTypeScriptExpression(expression.expression)
+        : expression;
+}
+function typeScriptPropertyName(name) {
+    return ts.isIdentifier(name) || ts.isStringLiteralLike(name)
+        ? name.text
+        : undefined;
+}
+function finalObjectLiteralPropertyValue(expression, propertyName) {
+    let hasUnverifiableOverride = false;
+    for (const property of [...expression.properties].reverse()) {
+        if (ts.isSpreadAssignment(property)) {
+            hasUnverifiableOverride = true;
+            continue;
+        }
+        const name = typeScriptPropertyName(property.name);
+        if (name === propertyName) {
+            if (!ts.isPropertyAssignment(property) || hasUnverifiableOverride) {
+                return undefined;
+            }
+            return property.initializer;
+        }
+        if (name === undefined) {
+            hasUnverifiableOverride = true;
+        }
+    }
+    return undefined;
+}
+function assertDatabaseViteRuntimeTruth(options) {
+    if (options.deploymentCheck === undefined)
+        return;
+    const application = requireContributionByName(options.packageByName, options.deploymentCheck.applicationPackageName, "Deployment Check");
+    const configPath = `${application.definition.path}/vite.config.ts`;
+    let sourceText;
+    try {
+        sourceText = readFileSync(path.join(options.repositoryRoot, configPath), "utf8");
+    }
+    catch (error) {
+        throw new Error(`Package Addition requires Vite runtime truth in ${configPath}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+    const sourceFile = ts.createSourceFile(configPath, sourceText, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    if ((sourceFile.parseDiagnostics ?? []).length > 0) {
+        throw new Error(`Package Addition requires valid Vite runtime truth in ${configPath}`);
+    }
+    const exportAssignment = sourceFile.statements.find((statement) => ts.isExportAssignment(statement) && !statement.isExportEquals);
+    const exported = exportAssignment === undefined
+        ? undefined
+        : unwrapTypeScriptExpression(exportAssignment.expression);
+    const configCall = exported !== undefined &&
+        ts.isCallExpression(exported) &&
+        ts.isIdentifier(exported.expression) &&
+        exported.expression.text === "defineConfig"
+        ? exported
+        : undefined;
+    const configArgument = configCall?.arguments[0];
+    const config = configArgument === undefined
+        ? undefined
+        : unwrapTypeScriptExpression(configArgument);
+    const ssrValue = config !== undefined && ts.isObjectLiteralExpression(config)
+        ? finalObjectLiteralPropertyValue(config, "ssr")
+        : undefined;
+    const ssr = ssrValue === undefined ? undefined : unwrapTypeScriptExpression(ssrValue);
+    const externalValue = ssr !== undefined && ts.isObjectLiteralExpression(ssr)
+        ? finalObjectLiteralPropertyValue(ssr, "external")
+        : undefined;
+    const external = externalValue === undefined
+        ? undefined
+        : unwrapTypeScriptExpression(externalValue);
+    const expectedPackageName = options.deploymentCheck.databasePackageName;
+    const externalPackageNames = external !== undefined && ts.isArrayLiteralExpression(external)
+        ? external.elements.flatMap((element) => ts.isStringLiteralLike(element) ? [element.text] : [])
+        : external !== undefined && ts.isStringLiteralLike(external)
+            ? [external.text]
+            : [];
+    if (!externalPackageNames.includes(expectedPackageName)) {
+        throw new Error(`Package Addition requires ${configPath} to externalize ${expectedPackageName} through Vite SSR`);
+    }
+}
+function assertVueHonoJointE2ePlaywrightTruth(options) {
+    if (options.e2e === undefined)
+        return;
+    const configPath = "playwright.config.ts";
+    let sourceText;
+    try {
+        sourceText = readFileSync(path.join(options.repositoryRoot, configPath), "utf8");
+    }
+    catch (error) {
+        throw new Error(`Package Addition requires Vue-Hono joint E2E root Playwright truth in ${configPath}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+    const sourceFile = ts.createSourceFile(configPath, sourceText, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    if ((sourceFile.parseDiagnostics ?? []).length > 0) {
+        throw new Error(`Package Addition requires valid Vue-Hono joint E2E root Playwright truth in ${configPath}`);
+    }
+    const exportAssignment = sourceFile.statements.find((statement) => ts.isExportAssignment(statement) && !statement.isExportEquals);
+    const exported = exportAssignment === undefined
+        ? undefined
+        : unwrapTypeScriptExpression(exportAssignment.expression);
+    const configCall = exported !== undefined &&
+        ts.isCallExpression(exported) &&
+        ts.isIdentifier(exported.expression) &&
+        exported.expression.text === "defineConfig"
+        ? exported
+        : undefined;
+    const configArgument = configCall?.arguments[0];
+    const config = configArgument === undefined
+        ? undefined
+        : unwrapTypeScriptExpression(configArgument);
+    const webServerValue = config !== undefined && ts.isObjectLiteralExpression(config)
+        ? finalObjectLiteralPropertyValue(config, "webServer")
+        : undefined;
+    const webServers = webServerValue === undefined
+        ? undefined
+        : unwrapTypeScriptExpression(webServerValue);
+    if (webServers === undefined ||
+        !ts.isArrayLiteralExpression(webServers) ||
+        webServers.elements.length !== 2) {
+        throw new Error(`Package Addition requires two static Vue-Hono joint E2E web servers in ${configPath}`);
+    }
+    const expectedServers = [
+        {
+            command: `pnpm --filter ${options.e2e.apiPackageName} --fail-if-no-match run start`,
+            portEnvironment: "PORT",
+            portVariable: "apiPort",
+            portInput: "PLAYWRIGHT_API_PORT",
+            stdout: "/Hono API listening on (?<VITE_API_BASE_URL>http:\\/\\/localhost:\\d+)/",
+        },
+        {
+            command: `pnpm --filter ${options.e2e.webPackageName} --fail-if-no-match run preview --host 127.0.0.1 --strictPort`,
+            portEnvironment: "PLAYWRIGHT_WEB_PORT",
+            portVariable: "webPort",
+            portInput: "PLAYWRIGHT_WEB_PORT",
+            stdout: "/Local:\\s+(?<PLAYWRIGHT_WEB_URL>http:\\/\\/127\\.0\\.0\\.1:\\d+)/",
+        },
+    ];
+    for (const [index, expected] of expectedServers.entries()) {
+        const server = unwrapTypeScriptExpression(webServers.elements[index]);
+        if (!ts.isObjectLiteralExpression(server)) {
+            throw new Error(`Package Addition requires static Vue-Hono joint E2E web server ${index + 1} in ${configPath}`);
+        }
+        const command = finalObjectLiteralPropertyValue(server, "command");
+        if (command === undefined ||
+            !ts.isStringLiteralLike(command) ||
+            command.text !== expected.command) {
+            throw new Error(`Package Addition requires exact Vue-Hono joint E2E web server ${index + 1} command in ${configPath}`);
+        }
+        const environmentValue = finalObjectLiteralPropertyValue(server, "env");
+        const environment = environmentValue === undefined
+            ? undefined
+            : unwrapTypeScriptExpression(environmentValue);
+        const environmentProperty = environment !== undefined && ts.isObjectLiteralExpression(environment)
+            ? environment.properties[0]
+            : undefined;
+        const portValue = environmentProperty !== undefined &&
+            ts.isPropertyAssignment(environmentProperty) &&
+            !ts.isComputedPropertyName(environmentProperty.name) &&
+            (ts.isIdentifier(environmentProperty.name) ||
+                ts.isStringLiteral(environmentProperty.name)) &&
+            environmentProperty.name.text === expected.portEnvironment
+            ? unwrapTypeScriptExpression(environmentProperty.initializer)
+            : undefined;
+        if (environment === undefined ||
+            !ts.isObjectLiteralExpression(environment) ||
+            environment.properties.length !== 1 ||
+            portValue === undefined ||
+            !ts.isIdentifier(portValue) ||
+            portValue.text !== expected.portVariable) {
+            throw new Error(`Package Addition requires Vue-Hono joint E2E web server ${index + 1} ${expected.portEnvironment} environment in ${configPath}`);
+        }
+        const waitValue = finalObjectLiteralPropertyValue(server, "wait");
+        const wait = waitValue === undefined
+            ? undefined
+            : unwrapTypeScriptExpression(waitValue);
+        const stdout = wait !== undefined && ts.isObjectLiteralExpression(wait)
+            ? finalObjectLiteralPropertyValue(wait, "stdout")
+            : undefined;
+        if (stdout === undefined ||
+            !ts.isRegularExpressionLiteral(stdout) ||
+            stdout.text !== expected.stdout) {
+            throw new Error(`Package Addition requires static Vue-Hono joint E2E web server ${index + 1} stdout capture in ${configPath}`);
+        }
+        const reuseExistingServer = finalObjectLiteralPropertyValue(server, "reuseExistingServer");
+        if (reuseExistingServer?.kind !== ts.SyntaxKind.FalseKeyword) {
+            throw new Error(`Package Addition requires Vue-Hono joint E2E web server ${index + 1} native cleanup in ${configPath}`);
+        }
+    }
+    const expectedPortInputs = expectedServers.map(({ portVariable, portInput }) => ({ portVariable, portInput }));
+    for (const expected of expectedPortInputs) {
+        const declarations = sourceFile.statements
+            .filter(ts.isVariableStatement)
+            .flatMap((statement) => statement.declarationList.declarations.map((declaration) => ({
+            declaration,
+            declarationList: statement.declarationList,
+        })))
+            .filter(({ declaration }) => ts.isIdentifier(declaration.name) &&
+            declaration.name.text === expected.portVariable);
+        const declaration = declarations[0];
+        if (declarations.length !== 1 ||
+            declaration === undefined ||
+            (declaration.declarationList.flags & ts.NodeFlags.Const) === 0) {
+            throw new Error(`Package Addition requires one top-level const Vue-Hono joint E2E ${expected.portVariable} in ${configPath}`);
+        }
+        const initializer = declaration.declaration.initializer;
+        const left = initializer !== undefined &&
+            ts.isBinaryExpression(initializer) &&
+            initializer.operatorToken.kind === ts.SyntaxKind.QuestionQuestionToken
+            ? initializer.left
+            : undefined;
+        const right = initializer !== undefined &&
+            ts.isBinaryExpression(initializer) &&
+            initializer.operatorToken.kind === ts.SyntaxKind.QuestionQuestionToken
+            ? initializer.right
+            : undefined;
+        const environmentInput = left !== undefined &&
+            ts.isPropertyAccessExpression(left) &&
+            ts.isPropertyAccessExpression(left.expression) &&
+            ts.isIdentifier(left.expression.expression) &&
+            left.expression.expression.text === "process" &&
+            left.expression.name.text === "env"
+            ? left.name.text
+            : undefined;
+        if (environmentInput !== expected.portInput ||
+            right === undefined ||
+            !ts.isStringLiteralLike(right) ||
+            right.text !== "0") {
+            throw new Error(`Package Addition requires Vue-Hono joint E2E ${expected.portVariable} to read ${expected.portInput} or static port 0 in ${configPath}`);
+        }
+    }
+}
+function assertCapabilityRepositoryTruth(options) {
+    assertDatabasePreparationManifestTruth({
+        preparation: options.databasePreparation,
+        packageByName: options.packageByName,
+        manifestTruthByPackagePath: options.manifestTruthByPackagePath,
+    });
+    assertDatabaseArtifactManifestTruth({
+        preparation: options.databasePreparation,
+        packageByName: options.packageByName,
+        manifestTruthByPackagePath: options.manifestTruthByPackagePath,
+    });
+    assertDatabaseProjectLinkManifestTruth({
+        blueprint: options.blueprint,
+        contributions: options.contributions,
+        preparation: options.databasePreparation,
+        packageByName: options.packageByName,
+        manifestTruthByPackagePath: options.manifestTruthByPackagePath,
+    });
+    assertDeploymentBuildManifestTruth({
+        deploymentCheck: options.deploymentCheck,
+        packageByName: options.packageByName,
+        manifestTruthByPackagePath: options.manifestTruthByPackagePath,
+    });
+    assertVueHonoJointE2eManifestTruth({
+        e2e: options.vueHonoJointE2e,
+        packageByName: options.packageByName,
+        manifestTruthByPackagePath: options.manifestTruthByPackagePath,
+    });
+    assertVueHonoJointE2ePlaywrightTruth({
+        repositoryRoot: options.repositoryRoot,
+        e2e: options.vueHonoJointE2e,
+    });
+    assertRootCapabilityManifestTruth(options);
+    assertCapabilityTurboTruth(options);
+    assertDatabaseViteRuntimeTruth(options);
+}
+function foundationCheckEnvironmentNeeds(contributions, deploymentCheck, vueHonoJointE2e) {
+    return [
+        ...contributions.flatMap((contribution) => contribution.environmentNeeds),
+        ...(vueHonoJointE2e === undefined
+            ? []
+            : [
+                playwrightBrowserAssetsEnvironmentNeed({
+                    browser: "chromium",
+                    owner: { kind: "workspace-orchestration", path: "." },
+                }),
+            ]),
+        ...(deploymentCheck === undefined
+            ? []
+            : [
+                shellCheckEnvironmentNeed({
+                    kind: "workspace-orchestration",
+                    path: ".",
+                }),
+            ]),
+    ];
+}
+function deploymentCheckDevelopmentContainerToolLayers(deploymentCheck) {
+    if (deploymentCheck === undefined)
+        return [];
+    return [
+        {
+            identity: "shellcheck",
+            dockerfile: deploymentCheck.sources.shellCheckDockerfile,
+            requires: ["node-pnpm"],
+            probes: [
+                {
+                    identity: "shellcheck",
+                    command: "shellcheck",
+                    args: ["--version"],
+                },
+            ],
+        },
+        {
+            identity: "docker-client",
+            dockerfile: deploymentCheck.sources.dockerClientToolLayer,
+            requires: ["node-pnpm"],
+            mounts: [
+                {
+                    identity: "docker-socket",
+                    type: "bind",
+                    source: "/var/run/docker.sock",
+                    target: "/var/run/docker.sock",
+                },
+            ],
+            probes: [
+                {
+                    identity: "docker-cli",
+                    command: "docker",
+                    args: ["--version"],
+                    failureMessage: "Docker CLI is unavailable; rebuild the Development Container to install the Docker Client Tool Layer.",
+                },
+                {
+                    identity: "docker-daemon",
+                    command: "docker",
+                    args: ["version"],
+                    failureMessage: "Docker daemon is inaccessible through /var/run/docker.sock; verify the host daemon is running and the standard socket is accessible.",
+                },
+            ],
+        },
+    ];
+}
+function normalizeRustToolchain(contributions) {
+    const declarations = contributions.flatMap((contribution) => {
+        const rust = contribution.foundation.toolchains.rust;
+        return rust === undefined
+            ? []
+            : [
+                {
+                    ...rust,
+                    components: [...new Set(rust.components)].toSorted(),
+                },
+            ];
+    });
+    const fingerprints = declarations.map((rust) => JSON.stringify({
+        toolchain: rust.toolchain,
+        components: rust.components,
+        configurationSource: resolveTemplateSource(rust.configurationSource.source, rust.configurationSource.from),
+    }));
+    if (new Set(fingerprints).size > 1) {
+        throw new Error("Foundation requires compatible Rust toolchain facts");
+    }
+    return declarations.at(0);
+}
+function composeDependencyMaintenancePolicy(contributions, deploymentCheck) {
+    const ecosystems = [
+        ...new Set([
+            ...contributions.flatMap((contribution) => contribution.foundation.dependencyMaintenance.ecosystems),
+            ...(deploymentCheck === undefined ? [] : ["docker"]),
+        ]),
+    ];
+    const directories = {};
+    const extraDirectories = {};
+    for (const ecosystem of ecosystems) {
+        const candidates = [
+            ...new Set([
+                ...contributions.flatMap((contribution) => {
+                    const policy = contribution.foundation.dependencyMaintenance;
+                    const primary = policy.directories?.[ecosystem];
+                    return [
+                        ...(primary === undefined ? [] : [primary]),
+                        ...(policy.extraDirectories?.[ecosystem] ?? []),
+                    ];
+                }),
+                ...(ecosystem === "docker" && deploymentCheck !== undefined
+                    ? ["/"]
+                    : []),
+            ]),
+        ];
+        const [primary, ...extra] = candidates;
+        if (primary !== undefined)
+            directories[ecosystem] = primary;
+        if (extra.length > 0)
+            extraDirectories[ecosystem] = extra;
+    }
+    return {
+        ecosystems,
+        ...(Object.keys(directories).length === 0 ? {} : { directories }),
+        ...(Object.keys(extraDirectories).length === 0 ? {} : { extraDirectories }),
+        interval: "weekly",
+    };
+}
+function localTypescriptConfigurationSpecifier(options) {
+    const relativePackagePath = path.posix.relative(options.consumerPackagePath, options.configurationPackagePath);
+    if (relativePackagePath.length === 0) {
+        throw new Error("TypeScript Configuration Package must have a distinct Package Path");
+    }
+    return `link:${relativePackagePath}`;
+}
+function publicCliCandidate(contributions) {
+    const candidates = contributions.filter((contribution) => contribution.foundation.npmPublication?.kind === "public-cli-candidate");
+    if (candidates.length > 1) {
+        throw new Error(`Generated Repository Plan supports at most one public CLI candidate; found ${candidates.map((candidate) => `${candidate.definition.name} at ${candidate.definition.path}`).join(", ")}`);
+    }
+    const candidate = candidates[0];
+    if (candidate !== undefined && candidate.definition.role !== "cli-tool") {
+        throw new Error(`Public CLI candidate ${candidate.definition.name} must use the cli-tool Package role`);
+    }
+    return candidate;
+}
+function renderPublicationRootCheckCommand(candidatePackagePath) {
+    return [
+        "pnpm run boundaries",
+        renderTurboRunCommand(["format:check", "lint", "typecheck", "test"], [], {
+            continueAfterFailure: true,
+            taskPrefix: true,
+        }),
+        renderTurboRunCommand(["build", "test:e2e"], [`--filter=!./${candidatePackagePath}`], { continueAfterFailure: true, taskPrefix: true }),
+        "pnpm run publication:artifact",
+    ].join(" && ");
+}
+/**
+ * 票 26 清单单源：把 plan 声明的镜像槽位集合投影成生成检查器携带的清单文本。
+ * 转义 `$` 是必要的：清单文本注入模板字面量，未转义的 `$` 会被当成 TypeScript 插值。
+ */
+function renderToolchainMirrorSlotManifest(reconciliation) {
+    const slots = reconciliation.flatMap((policy) => policy.driver === "canonical"
+        ? []
+        : (policy.mirrorSlots ?? []).map((slot) => ({
+            id: slot.id,
+            path: policy.path,
+            location: slot.location,
+        })));
+    return JSON.stringify(slots, null, 2).replaceAll("$", String.raw `\$`);
+}
+function foundationPlan(options) {
+    assertProjectBlueprint(options.blueprint);
+    const configContribution = options.foundationContribution;
+    const configDefinition = configContribution.definition;
+    if (!options.blueprint.packages.some((definition) => packageDefinitionsEqual(definition, configDefinition))) {
+        throw new Error("Project Blueprint must contain the Foundation TypeScript configuration Package Definition");
+    }
+    const initialProjectLinkPlan = planExplicitProjectLinks({
+        blueprint: options.blueprint,
+        contributions: options.contributions,
+        ...(options.manifestTruthByPackagePath === undefined
+            ? {}
+            : {
+                manifestTruthByPackagePath: options.manifestTruthByPackagePath,
+            }),
+    });
+    const injectedProviderNames = new Set([...initialProjectLinkPlan.manifestPatchesByPackagePath.values()].flatMap((patch) => Object.entries(patch.dependenciesMeta ?? {})
+        .filter(([, metadata]) => metadata.injected)
+        .map(([name]) => name)));
+    const configPackageName = options.context.foundationPackages.typescriptConfiguration.name;
+    if (configDefinition.name !== configPackageName) {
+        throw new Error(`Generation Context TypeScript Configuration Package ${configPackageName} conflicts with Blueprint Package Definition ${configDefinition.name}`);
+    }
+    const publicationCandidate = publicCliCandidate(options.contributions);
+    const packageContributions = options.contributions.map((contribution) => {
+        if (contribution.foundation.typescriptConfigurationPackage === undefined) {
+            return contribution;
+        }
+        const dependencyField = injectedProviderNames.has(contribution.definition.name)
+            ? "dependencies"
+            : "devDependencies";
+        const dependencySpecifier = dependencyField === "devDependencies" &&
+            (contribution.manifest.private !== true ||
+                publicationCandidate?.definition.path === contribution.definition.path)
+            ? localTypescriptConfigurationSpecifier({
+                consumerPackagePath: contribution.definition.path,
+                configurationPackagePath: configDefinition.path,
+            })
+            : "workspace:*";
+        const existingDependencies = contribution.manifest[dependencyField];
+        return {
+            ...contribution,
+            manifest: {
+                ...contribution.manifest,
+                [dependencyField]: {
+                    ...(isRecord(existingDependencies) ? existingDependencies : {}),
+                    [configPackageName]: dependencySpecifier,
+                },
+            },
+        };
+    });
+    const requiresPackingHook = packageContributions.some((contribution) => {
+        const developmentDependencies = contribution.manifest.devDependencies;
+        return (isRecord(developmentDependencies) &&
+            typeof developmentDependencies[configPackageName] === "string" &&
+            developmentDependencies[configPackageName].startsWith("link:"));
+    });
+    const contributions = [configContribution, ...packageContributions];
+    assertPackageContributionCommandNames(contributions.map((contribution) => {
+        const manifest = options.manifestTruthByPackagePath?.get(contribution.definition.path);
+        return manifest === undefined
+            ? contribution
+            : { ...contribution, manifest };
+    }));
+    const candidateRecord = options.generationRecord ?? {
+        schemaVersion: 2,
+        repositoryName: options.context.repositoryName,
+        defaultPackageScope: options.context.defaultPackageScope,
+        preset: options.definition.metadata.name,
+        templateVersion: "0.0.0",
+        // 显式只投影 v2 的两个历史字段，上下文里的精确 Node 事实不得进入持久记录。
+        toolchain: {
+            nodeLtsMajor: options.context.toolchain.nodeLtsMajor,
+            packageManagerPin: options.context.toolchain.packageManagerPin,
+        },
+        packages: [
+            ...options.contributions.map((contribution) => {
+                const planningContribution = options.mode === "initialization"
                     ? "planInitialization"
                     : "planPackageAddition";
                 return {
@@ -785,21 +1878,82 @@ function foundationPlan(options) {
         ],
     };
     const generationRecord = parseGenerationRecord(candidateRecord);
+    const deploymentCheck = normalizeDeploymentCheck(contributions);
+    const vueHonoJointE2e = normalizeVueHonoJointE2e(contributions);
+    const databasePreparation = normalizeDatabasePreparation(contributions);
+    const rustToolchain = normalizeRustToolchain(contributions);
+    const packageByName = new Map(contributions.map((contribution) => [
+        contribution.definition.name,
+        contribution,
+    ]));
+    const deploymentPackages = deploymentCheck === undefined
+        ? undefined
+        : {
+            application: requireContributionByName(packageByName, deploymentCheck.applicationPackageName, "Deployment Check"),
+            database: requireContributionByName(packageByName, deploymentCheck.databasePackageName, "Deployment Check"),
+            migration: requireContributionByName(packageByName, deploymentCheck.migrationPackageName, "Deployment Check"),
+        };
+    if (databasePreparation !== undefined) {
+        const migration = packageByName.get(databasePreparation.migrationPackageName);
+        if (migration === undefined) {
+            throw new Error("Database Preparation references an unknown migration Package");
+        }
+        for (const packageName of Object.values(databasePreparation.consumers)) {
+            if (!packageByName.has(packageName)) {
+                throw new Error("Database Preparation references an unknown consumer Package");
+            }
+        }
+        if (databasePreparation.consumers["database-test"] !==
+            databasePreparation.databasePackageName) {
+            throw new Error("Database Preparation database-test consumer must be its owner");
+        }
+    }
+    assertDatabasePreparationManifestTruth({
+        preparation: databasePreparation,
+        packageByName,
+        manifestTruthByPackagePath: options.manifestTruthByPackagePath,
+    });
+    if (deploymentCheck !== undefined) {
+        const deploymentPackageNames = [
+            deploymentCheck.applicationPackageName,
+            deploymentCheck.databasePackageName,
+            deploymentCheck.migrationPackageName,
+        ];
+        if (new Set(deploymentPackageNames).size !== 3) {
+            throw new Error("Deployment Check requires three distinct Packages");
+        }
+        if (deploymentPackages?.application.definition.path !==
+            deploymentCheck.declaringPackagePath) {
+            throw new Error("Deployment Check must be declared by its application Package");
+        }
+        if (databasePreparation !== undefined &&
+            (databasePreparation.databasePackageName !==
+                deploymentCheck.databasePackageName ||
+                databasePreparation.migrationPackageName !==
+                    deploymentCheck.migrationPackageName)) {
+            throw new Error("Deployment Check must use the Database Preparation Packages");
+        }
+        for (const packageName of deploymentPackageNames) {
+            const contribution = requireContributionByName(packageByName, packageName, "Deployment Check");
+            const manifest = options.manifestTruthByPackagePath?.get(contribution.definition.path) ??
+                contribution.manifest;
+            const expectedBuild = isRecord(contribution.manifest.scripts)
+                ? contribution.manifest.scripts.build
+                : undefined;
+            const actualBuild = isRecord(manifest.scripts)
+                ? manifest.scripts.build
+                : undefined;
+            if (typeof expectedBuild !== "string" || actualBuild !== expectedBuild) {
+                throw new Error(`Deployment Check requires exact ${packageName} manifest script build`);
+            }
+        }
+    }
     const persistedEnvironmentNeeds = normalizeEnvironmentNeeds({
-        check: contributions.flatMap((item) => item.environmentNeeds),
-        deployment: [
-            ...(options.existingDeploymentEnvironmentNeeds ?? []),
-            ...contributions.flatMap((item) => item.deploymentEnvironmentNeeds ?? []),
-        ],
+        check: foundationCheckEnvironmentNeeds(contributions, deploymentCheck, vueHonoJointE2e),
+        deployment: deploymentCheck?.environmentNeeds ?? [],
     });
     const environmentNeeds = persistedEnvironmentNeeds.check;
     const deploymentEnvironmentNeeds = persistedEnvironmentNeeds.deployment;
-    const hasDeploymentTask = contributions.some((contribution) => {
-        const scripts = contribution.manifest.scripts;
-        return (typeof scripts === "object" &&
-            scripts !== null &&
-            typeof scripts.deployment === "string");
-    });
     const contributionPackagePaths = contributions.map((contribution) => contribution.definition.path);
     if (new Set(contributionPackagePaths).size !== contributionPackagePaths.length)
         throw new Error("Package Contributions must have unique Package Paths");
@@ -814,13 +1968,26 @@ function foundationPlan(options) {
     const ciDiagnosticArtifactDeclarations = contributions.flatMap((contribution) => contribution.ciDiagnosticArtifacts ?? []);
     const ciDiagnosticArtifacts = composeCiDiagnosticArtifacts({
         packagePaths: blueprintPackagePaths,
-        declarations: ciDiagnosticArtifactDeclarations,
+        declarations: [
+            ...ciDiagnosticArtifactDeclarations,
+            ...(vueHonoJointE2e === undefined
+                ? []
+                : [
+                    {
+                        kind: "playwright",
+                        owner: { kind: "workspace-orchestration", path: "." },
+                    },
+                ]),
+        ],
     });
-    assertCompatibleRustToolchainFacts(contributions);
     const contributedToolLayers = contributions.flatMap((contribution) => contribution.foundation.developmentContainerToolLayers ?? []);
     const developmentContainer = contributedDevcontainerComposition({
         context: options.context,
-        layers: contributedToolLayers,
+        rootNodeDeclaration: options.rootNodeDeclaration,
+        layers: [
+            ...contributedToolLayers,
+            ...deploymentCheckDevelopmentContainerToolLayers(deploymentCheck),
+        ],
     });
     const workspacePackageGlobs = [
         "apps/*",
@@ -835,7 +2002,9 @@ function foundationPlan(options) {
         ]),
     ];
     const editorCustomization = editorCustomizationForCapabilities(contributions.flatMap((contribution) => contribution.foundation.editorCapabilities), loadEditorCustomizationDeclarations(resolveTemplateSource(templateSources.editorCustomization, "capabilities.json")));
-    const dependencyMaintenancePolicy = composeDependencyMaintenancePolicy(contributions);
+    const dependencyMaintenancePolicy = composeDependencyMaintenancePolicy(contributions, deploymentCheck);
+    const rootOwnedE2e = vueHonoJointE2e !== undefined;
+    const rootAutomationPaths = rootOwnedE2e ? "scripts test" : "scripts";
     const rootManifest = {
         name: options.context.repositoryName,
         private: true,
@@ -851,25 +2020,39 @@ function foundationPlan(options) {
             check: publicationCandidate === undefined
                 ? renderRootCheckCommand()
                 : renderPublicationRootCheckCommand(publicationCandidate.definition.path),
-            boundaries: "node --conditions=source scripts/check-boundaries.ts",
+            // Cargo 会在首次代理调用时按根 rust-toolchain.toml 安装版本与组件；先经唯一根任务完成解析，再并行运行各 Rust 包的 Cargo 检查。
+            ...(rustToolchain === undefined
+                ? {}
+                : { "toolchain:prepare": "cargo --version" }),
+            boundaries: "turbo boundaries --no-color && node --conditions=source scripts/check-toolchain-versions.ts",
+            ...(databasePreparation === undefined
+                ? {}
+                : databasePreparationCommands(databasePreparation)),
             ...(publicationCandidate === undefined
                 ? {}
                 : {
                     "publication:readiness": "node --conditions=source scripts/npm-publication/check-readiness.ts",
                     "publication:artifact": "node --conditions=source scripts/npm-publication/check-artifact.ts",
                 }),
-            ...(hasDeploymentTask
-                ? { "check:deployment": renderDeploymentCheckCommand() }
-                : {}),
+            ...(deploymentCheck === undefined
+                ? {}
+                : {
+                    deployment: "node --conditions=source scripts/check-standalone-deployment.ts",
+                    "check:deployment": renderDeploymentCheckCommand(),
+                }),
+            ...(rootOwnedE2e ? { "test:e2e": "playwright test" } : {}),
             fix: renderFixCommand(),
-            "format:check": "node --conditions=source scripts/run-root-owned-task.ts format:check",
-            "format:write": "node --conditions=source scripts/run-root-owned-task.ts format:write",
-            lint: "node --conditions=source scripts/run-root-owned-task.ts lint",
-            "lint:fix": "node --conditions=source scripts/run-root-owned-task.ts lint:fix",
+            "format:check": `oxfmt --list-different --no-error-on-unmatched-pattern package.json pnpm-workspace.yaml pnpm-lock.yaml turbo.json tsconfig.json tsconfig.config.json *.config.ts .pnpmfile.mjs .gitignore .dockerignore Dockerfile TODO.md rust-toolchain.toml .vscode .github .devcontainer ${rootAutomationPaths}`,
+            "format:write": `oxfmt --write --no-error-on-unmatched-pattern package.json pnpm-workspace.yaml pnpm-lock.yaml turbo.json tsconfig.json tsconfig.config.json *.config.ts .pnpmfile.mjs .gitignore .dockerignore Dockerfile TODO.md rust-toolchain.toml .vscode .github .devcontainer ${rootAutomationPaths}`,
+            lint: deploymentCheck === undefined
+                ? `oxlint --quiet --format=unix --no-error-on-unmatched-pattern *.config.ts .pnpmfile.mjs ${rootAutomationPaths}`
+                : `shellcheck scripts/container-entrypoint.sh && oxlint --quiet --format=unix --no-error-on-unmatched-pattern *.config.ts .pnpmfile.mjs ${rootAutomationPaths}`,
+            "lint:fix": `oxlint --format=unix --no-error-on-unmatched-pattern *.config.ts .pnpmfile.mjs ${rootAutomationPaths} --fix`,
             typecheck: "tsc -p tsconfig.json --noEmit --pretty false",
         },
         devDependencies: {
             "@types/node": "catalog:",
+            ...(rootOwnedE2e ? { "@playwright/test": "catalog:" } : {}),
             ...(publicationCandidate === undefined
                 ? {}
                 : {
@@ -879,6 +2062,7 @@ function foundationPlan(options) {
             oxfmt: "catalog:",
             oxlint: "catalog:",
             "oxlint-tsgolint": "catalog:",
+            "smol-toml": "catalog:",
             ...(publicationCandidate === undefined
                 ? {}
                 : {
@@ -890,7 +2074,7 @@ function foundationPlan(options) {
             turbo: "catalog:",
             "typescript-7": "catalog:",
         },
-        engines: { node: options.context.toolchain.nodeLtsMajor },
+        engines: { node: options.rootNodeDeclaration },
         packageManager: options.context.toolchain.packageManagerPin,
     };
     const dependencyCatalog = selectTemplateDependencyCatalogEntries(collectGeneratedManifestCatalogReferences([
@@ -930,8 +2114,7 @@ function foundationPlan(options) {
     };
     const workflowTemplateSource = projectCheckWorkflowTemplateSource({
         packagePaths: blueprintPackagePaths,
-        deploymentEnvironmentNeeds,
-        hasDeploymentTask,
+        deploymentCheck,
         diagnosticArtifacts: ciDiagnosticArtifacts,
     });
     const workflowOperation = ciDiagnosticArtifacts.length === 0
@@ -973,6 +2156,70 @@ function foundationPlan(options) {
     ];
     const projectLinkPlan = initialProjectLinkPlan;
     const turboBoundaryTags = turboBoundaryTagsForContributions(contributions);
+    const reconciliation = [
+        { path: "tsconfig.json", driver: "structured" },
+        { path: "turbo.json", driver: "structured" },
+        {
+            path: ".devcontainer/devcontainer.json",
+            driver: "structured",
+            identitySets: [developmentContainer.mountIdentitySet],
+            // M1：根 engines.node 原文拥有的静态镜像槽位；Core 只见位置，不见文件语义。
+            // 设计写作 /build.args/NODE_VERSION；RFC 6901 下点号不是分隔符，取同位置的标准形。
+            mirrorSlots: [
+                {
+                    id: "node-version-build-arg",
+                    location: {
+                        kind: "json-pointer",
+                        pointer: "/build/args/NODE_VERSION",
+                    },
+                },
+                // M5：仅当本 plan 选用 Rust 时接入同一机制，值由根 rust-toolchain.toml channel 拥有。
+                // 声明只给位置、不含版本值，故已含 Rust 的目标在加包时 Before/After 清单逐字节相同，
+                // reconciliationPoliciesCompatible 不因 M5 扩展把合法加包变成策略不兼容。
+                ...(rustToolchain === undefined
+                    ? []
+                    : [
+                        {
+                            id: "rust-toolchain-build-arg",
+                            location: {
+                                kind: "json-pointer",
+                                pointer: "/build/args/RUST_TOOLCHAIN",
+                            },
+                        },
+                    ]),
+            ],
+        },
+        ...(deploymentCheck === undefined || deploymentPackages === undefined
+            ? []
+            : [
+                {
+                    path: "Dockerfile",
+                    driver: "text",
+                    // M2：同一 rootNodeDeclaration 投影的锚定 ARG 默认值。
+                    mirrorSlots: [
+                        {
+                            id: "node-version-deployment-arg",
+                            location: { kind: "text-anchor", name: "NODE_VERSION" },
+                        },
+                    ],
+                },
+            ]),
+        {
+            path: ".vscode/extensions.json",
+            driver: "structured",
+            identitySets: [
+                {
+                    location: "/recommendations",
+                    identity: { kind: "self" },
+                },
+            ],
+        },
+        { path: ".template/blueprint.json", driver: "canonical" },
+        { path: environmentNeedsPath, driver: "canonical" },
+        { path: ".template/generation.json", driver: "canonical" },
+    ];
+    // 票 26 清单单源：生成检查器携带的槽位清单是上面声明的投影，不是第二份真源。
+    const toolchainMirrorSlotManifest = renderToolchainMirrorSlotManifest(reconciliation);
     const initializationFoundationOperations = [
         {
             kind: "writeJson",
@@ -998,12 +2245,57 @@ function foundationPlan(options) {
             from: "gitignore",
             to: ".gitignore",
         },
+        {
+            kind: "copyFile",
+            source: templateSources.foundation,
+            from: "AGENTS.md.template",
+            to: "AGENTS.md",
+        },
         {
             kind: "copyFile",
             source: templateSources.foundation,
             from: "turbo.json",
             to: "turbo.json",
         },
+        ...(vueHonoJointE2e === undefined
+            ? []
+            : [
+                {
+                    kind: "mergeJson",
+                    to: "turbo.json",
+                    value: { tasks: vueHonoJointE2eTurboTasks(vueHonoJointE2e) },
+                    multilineArrays: ["tasks.//#test:e2e.dependsOn"],
+                },
+            ]),
+        ...(deploymentCheck === undefined
+            ? []
+            : [
+                {
+                    kind: "mergeJson",
+                    to: "turbo.json",
+                    value: {
+                        tasks: deploymentTurboTasks(deploymentCheck),
+                    },
+                    multilineArrays: ["tasks.//#deployment.dependsOn"],
+                },
+            ]),
+        ...(databasePreparation === undefined
+            ? []
+            : [
+                {
+                    kind: "mergeJson",
+                    to: "turbo.json",
+                    value: {
+                        tasks: databasePreparationTurboTasks(databasePreparation),
+                    },
+                    multilineArrays: [
+                        `tasks.${databasePreparation.migrationPackageName}#typecheck.dependsOn`,
+                        `tasks.${databasePreparation.consumers["application-dev"]}#typecheck.dependsOn`,
+                        `tasks.${databasePreparation.consumers["application-dev"]}#dev.dependsOn`,
+                        `tasks.${databasePreparation.consumers["application-e2e"]}#test:e2e.dependsOn`,
+                    ],
+                },
+            ]),
         ...(publicationCandidate === undefined
             ? []
             : [
@@ -1019,18 +2311,16 @@ function foundationPlan(options) {
             source: templateSources.foundation,
             from: `turbo-boundary-tags/${tag}.json`,
             to: "turbo.json",
+            multilineArrays: deploymentCheck === undefined ? [] : ["tasks.//#deployment.dependsOn"],
         })),
         {
-            kind: "copyFile",
-            source: templateSources.foundation,
-            from: "scripts/check-boundaries.ts",
-            to: "scripts/check-boundaries.ts",
-        },
-        {
-            kind: "copyFile",
+            kind: "writeTextTemplate",
             source: templateSources.foundation,
-            from: "scripts/run-root-owned-task.ts",
-            to: "scripts/run-root-owned-task.ts",
+            from: "scripts/check-toolchain-versions.ts",
+            to: "scripts/check-toolchain-versions.ts",
+            replacements: {
+                TOOLCHAIN_MIRROR_SLOT_MANIFEST: toolchainMirrorSlotManifest,
+            },
         },
         {
             kind: "copyFile",
@@ -1038,6 +2328,38 @@ function foundationPlan(options) {
             from: "tsconfig.json",
             to: "tsconfig.json",
         },
+        ...(vueHonoJointE2e === undefined
+            ? []
+            : [
+                {
+                    kind: "mergeJsonTemplate",
+                    source: templateSources.vueHonoApp,
+                    from: "root/tsconfig.json",
+                    to: "tsconfig.json",
+                },
+                {
+                    kind: "writeTextTemplate",
+                    source: templateSources.vueHonoApp,
+                    from: "root/playwright.config.ts",
+                    to: "playwright.config.ts",
+                    replacements: {
+                        API_PACKAGE_NAME: vueHonoJointE2e.apiPackageName,
+                        WEB_PACKAGE_NAME: vueHonoJointE2e.webPackageName,
+                    },
+                },
+                {
+                    kind: "copyFile",
+                    source: templateSources.vueHonoApp,
+                    from: "root/test/e2e/fixtures.ts",
+                    to: "test/e2e/fixtures.ts",
+                },
+                {
+                    kind: "copyFile",
+                    source: templateSources.vueHonoApp,
+                    from: "root/test/e2e/app.spec.ts",
+                    to: "test/e2e/app.spec.ts",
+                },
+            ]),
         ...(publicationCandidate === undefined
             ? []
             : [
@@ -1046,7 +2368,6 @@ function foundationPlan(options) {
                     source: templateSources.tsCli,
                     from: "publication/root-tsconfig.json",
                     to: "tsconfig.json",
-                    multilineArrays: ["include"],
                 },
             ]),
         ...(requiresPackingHook && publicationCandidate === undefined
@@ -1220,7 +2541,67 @@ function foundationPlan(options) {
             value: editorCustomization.settings,
         },
         ...developmentContainer.operations,
-        ...contributedFoundationTemplateFileOperations(contributions),
+        ...(rustToolchain === undefined
+            ? []
+            : [
+                {
+                    kind: "writeTextTemplate",
+                    source: rustToolchain.configurationSource.source,
+                    from: rustToolchain.configurationSource.from,
+                    to: "rust-toolchain.toml",
+                    replacements: { RUST_TOOLCHAIN: rustToolchain.toolchain },
+                },
+            ]),
+        ...(deploymentCheck === undefined || deploymentPackages === undefined
+            ? []
+            : [
+                {
+                    kind: "writeTextTemplate",
+                    source: deploymentCheck.sources.dockerfile.source,
+                    from: deploymentCheck.sources.dockerfile.from,
+                    to: "Dockerfile",
+                    replacements: {
+                        NODE_VERSION: options.rootNodeDeclaration,
+                        APPLICATION_PACKAGE_NAME: deploymentPackages.application.definition.name,
+                        APPLICATION_PACKAGE_PATH: deploymentPackages.application.definition.path,
+                        DATABASE_PACKAGE_NAME: deploymentPackages.database.definition.name,
+                        DATABASE_PACKAGE_PATH: deploymentPackages.database.definition.path,
+                        MIGRATION_PACKAGE_NAME: deploymentPackages.migration.definition.name,
+                        MIGRATION_PACKAGE_PATH: deploymentPackages.migration.definition.path,
+                        TYPESCRIPT_CONFIG_PACKAGE_PATH: configDefinition.path,
+                    },
+                },
+                {
+                    kind: "writeTextTemplate",
+                    source: deploymentCheck.sources.dockerIgnore.source,
+                    from: deploymentCheck.sources.dockerIgnore.from,
+                    to: ".dockerignore",
+                    replacements: {
+                        APPLICATION_PACKAGE_PATH: deploymentPackages.application.definition.path,
+                        DATABASE_PACKAGE_PATH: deploymentPackages.database.definition.path,
+                    },
+                },
+                {
+                    kind: "writeTextTemplate",
+                    source: deploymentCheck.sources.checker.source,
+                    from: deploymentCheck.sources.checker.from,
+                    to: "scripts/check-standalone-deployment.ts",
+                    replacements: {
+                        APPLICATION_PACKAGE_NAME: deploymentPackages.application.definition.name,
+                    },
+                },
+                {
+                    kind: "copyFile",
+                    source: deploymentCheck.sources.controlScript.source,
+                    from: deploymentCheck.sources.controlScript.from,
+                    to: "scripts/container-entrypoint.sh",
+                },
+                {
+                    kind: "setExecutable",
+                    path: "scripts/container-entrypoint.sh",
+                    executable: true,
+                },
+            ]),
         ...workflowOperations,
         {
             kind: "writeJson",
@@ -1293,60 +2674,173 @@ function foundationPlan(options) {
         ...plannedFoundationOperations.map((operation) => withProvenance(operation, foundationProvenance)),
         ...linkOperations.map((operation) => withProvenance(operation, foundationProvenance)),
     ];
-    const reconciliation = [
-        { path: "tsconfig.json", driver: "structured" },
-        { path: "turbo.json", driver: "structured" },
-        {
-            path: ".devcontainer/devcontainer.json",
-            driver: "structured",
-            identitySets: [developmentContainer.mountIdentitySet],
+    return {
+        definitionName: options.definition.metadata.name,
+        plannerSourceFile: options.definition.plannerSourceFile,
+        planningContribution: options.mode === "addition"
+            ? "planPackageAddition"
+            : "planInitialization",
+        blueprint: options.blueprint,
+        generationRecord,
+        packageContributions,
+        operations,
+        reconciliation,
+        developmentContainer: {
+            toolLayers: developmentContainer.toolLayers,
+            buildArguments: developmentContainer.buildArguments,
+            mounts: developmentContainer.mounts,
+            probes: developmentContainer.probes,
         },
-        {
-            path: ".vscode/extensions.json",
-            driver: "structured",
-            identitySets: [
-                {
-                    location: "/recommendations",
-                    identity: { kind: "self" },
-                },
-            ],
+        environmentNeeds,
+        deploymentCheck: deploymentCheck === undefined
+            ? undefined
+            : {
+                kind: deploymentCheck.kind,
+                applicationPackageName: deploymentCheck.applicationPackageName,
+                databasePackageName: deploymentCheck.databasePackageName,
+                migrationPackageName: deploymentCheck.migrationPackageName,
+                environmentNeeds: deploymentCheck.environmentNeeds,
+            },
+        vueHonoJointE2e: vueHonoJointE2e === undefined
+            ? undefined
+            : {
+                kind: vueHonoJointE2e.kind,
+                apiPackageName: vueHonoJointE2e.apiPackageName,
+            },
+        deploymentEnvironmentNeeds,
+        ciDiagnosticArtifacts,
+        manifests: [...contributions.map((item) => item.manifest), rootManifest],
+        dependencyCatalog,
+        dependencyMaintenancePolicy,
+        nextStepInstructions: [
+            { display: "pnpm install" },
+            { display: "pnpm run fix" },
+            { display: "pnpm run check" },
+        ],
+    };
+}
+function hasConfigurablePrimaryPackage(definition) {
+    return definition.initialPrimaryPackage !== undefined;
+}
+function deduplicateInitializationInputIssues(issues) {
+    return issues.filter((issue, index) => issues.findIndex((candidate) => candidate.code === issue.code) === index);
+}
+function collectInitializationInput(options) {
+    const issues = [];
+    const definition = options.definition ??
+        (options.preset === undefined
+            ? undefined
+            : builtInPresetRegistry
+                .all()
+                .find((candidate) => candidate.metadata.name === options.preset));
+    if (definition === undefined) {
+        return {
+            status: "input-invalid",
+            issues: [{ code: "PRESET_UNKNOWN" }],
+        };
+    }
+    const scopeOverride = options.overrides?.scope;
+    const normalizedScope = scopeOverride?.startsWith("@") === true
+        ? scopeOverride.slice(1)
+        : scopeOverride;
+    const nameOverride = options.overrides?.name;
+    const pathOverride = options.overrides?.path;
+    const repositoryName = path.basename(path.resolve(options.targetDir));
+    const configurablePrimaryPackage = definition.initialPrimaryPackage !== undefined;
+    if (!configurablePrimaryPackage &&
+        (nameOverride !== undefined || pathOverride !== undefined)) {
+        issues.push({ code: "FIXED_TOPOLOGY_OVERRIDE" });
+    }
+    let validNameOverride = nameOverride !== undefined &&
+        isValidNewNpmPackageName(`@x/${nameOverride}`);
+    if (nameOverride !== undefined && !validNameOverride) {
+        issues.push({ code: "INVALID_PACKAGE_NAME" });
+    }
+    if (pathOverride !== undefined) {
+        const pathValidation = validateNewPackagePath(pathOverride);
+        if (!pathValidation.hasValidShape) {
+            issues.push({ code: "INVALID_PACKAGE_PATH" });
+        }
+        if (pathValidation.reservedWorkspaceCollection !== undefined) {
+            issues.push({ code: "RESERVED_PACKAGE_PATH" });
+        }
+    }
+    let validScopeOverride = normalizedScope !== undefined &&
+        scopeOverride === scopeOverride?.trim() &&
+        isValidDefaultPackageScope(normalizedScope) &&
+        isValidNewNpmPackageName(`@${normalizedScope}/typescript-config`);
+    if (normalizedScope !== undefined && !validScopeOverride) {
+        issues.push({ code: "INVALID_PACKAGE_SCOPE" });
+    }
+    let validRepositoryScope = isValidDefaultPackageScope(repositoryName) &&
+        isValidNewNpmPackageName(`@${repositoryName}/typescript-config`);
+    if (normalizedScope === undefined && !validRepositoryScope) {
+        issues.push({ code: "INVALID_REPOSITORY_SCOPE" });
+    }
+    const resolvedScope = validScopeOverride
+        ? (normalizedScope ?? "repository")
+        : validRepositoryScope
+            ? repositoryName
+            : "repository";
+    const resolvedLeaf = configurablePrimaryPackage &&
+        nameOverride !== undefined &&
+        validNameOverride
+        ? nameOverride
+        : configurablePrimaryPackage
+            ? definition.initialPrimaryPackage?.defaultLeafName
+            : undefined;
+    if (resolvedLeaf !== undefined &&
+        !isValidNewNpmPackageName(`@${resolvedScope}/${resolvedLeaf}`)) {
+        if (nameOverride !== undefined) {
+            validNameOverride = false;
+            issues.push({ code: "INVALID_PACKAGE_NAME" });
+        }
+        else if (scopeOverride !== undefined) {
+            validScopeOverride = false;
+            issues.push({ code: "INVALID_PACKAGE_SCOPE" });
+        }
+        else {
+            validRepositoryScope = false;
+            issues.push({ code: "INVALID_REPOSITORY_SCOPE" });
+        }
+    }
+    const initialPrimaryPackage = definition.initialPrimaryPackage;
+    const foundationDefinition = typescriptConfigPackageDefinition({
+        foundationPackages: {
+            typescriptConfiguration: {
+                name: `@${resolvedScope}/typescript-config`,
+            },
         },
-        { path: ".template/blueprint.json", driver: "canonical" },
-        { path: environmentNeedsPath, driver: "canonical" },
-        { path: ".template/generation.json", driver: "canonical" },
-    ];
+    });
+    if ((nameOverride !== undefined &&
+        `@${resolvedScope}/${nameOverride}` === foundationDefinition.name) ||
+        pathOverride === foundationDefinition.path) {
+        issues.push({ code: "CONFLICTING_PACKAGE_IDENTITY" });
+    }
+    if (issues.length > 0) {
+        return {
+            status: "input-invalid",
+            issues: deduplicateInitializationInputIssues(issues),
+        };
+    }
     return {
-        definitionName: options.definition.metadata.name,
-        plannerSourceFile: options.definition.plannerSourceFile,
-        planningContribution: options.mode === "addition"
-            ? "planPackageAddition"
-            : "planInitialization",
-        blueprint: options.blueprint,
-        generationRecord,
-        packageContributions,
-        operations,
-        reconciliation,
-        developmentContainer: {
-            toolLayers: developmentContainer.toolLayers,
-            buildArguments: developmentContainer.buildArguments,
-            mounts: developmentContainer.mounts,
-            probes: developmentContainer.probes,
-        },
-        environmentNeeds,
-        deploymentEnvironmentNeeds,
-        ciDiagnosticArtifacts,
-        manifests: [...contributions.map((item) => item.manifest), rootManifest],
-        dependencyCatalog,
-        dependencyMaintenancePolicy,
-        nextStepInstructions: [
-            { display: "pnpm install" },
-            { display: "pnpm run fix" },
-            { display: "pnpm run check" },
-        ],
+        status: "valid",
+        definition,
+        normalizedScope,
+        nameOverride,
+        pathOverride,
+        repositoryName,
+        configurablePrimaryPackage,
+        validScopeOverride,
+        validRepositoryScope,
+        resolvedScope,
+        initialPrimaryPackage,
+        foundationDefinition,
     };
 }
-function hasConfigurablePrimaryPackage(definition) {
-    return definition.initialPrimaryPackage !== undefined;
+export function validateGeneratedRepositoryInitializationInput(options) {
+    const input = collectInitializationInput(options);
+    return input.status === "input-invalid" ? input : { status: "valid" };
 }
 function errorDiagnostics(error) {
     return (error instanceof Error ? error.message : String(error))
@@ -1476,6 +2970,7 @@ function planPreparedRepositoryInitialization(options) {
         foundationContribution: typescriptConfigReplayAdapter.identify(typescriptConfigContribution(options.context, configDefinition)),
         contributions,
         mode: "initialization",
+        rootNodeDeclaration: options.rootNodeDeclaration,
     });
 }
 function assertPreflightedInitializationPlan(plan) {
@@ -1488,6 +2983,28 @@ function assertPreflightedInitializationPlan(plan) {
     }
     return plan;
 }
+/** 精确 Node 事实必须是有三段补丁号的版本，不接受纯大版本或两段形式。 */
+const exactNodeVersionPattern = /^\d+\.\d+\.\d+$/u;
+/**
+ * 私有根的 Node 声明：上下文带已知精确值时沿用该精确值，并校验其大版本与 nodeLtsMajor 一致；
+ * 缺省时沿用原有大版本声明。这条缺省路径不作为新生成公开包范围的推导来源。
+ */
+function resolvePrivateRootNodeDeclaration(toolchain) {
+    const { nodeLtsMajor, nodeVersion } = toolchain;
+    if (nodeVersion === undefined)
+        return nodeLtsMajor;
+    if (!exactNodeVersionPattern.test(nodeVersion)) {
+        throw new Error(`Generation Context 的 toolchain.nodeVersion 必须是精确三段 Node 版本（"24.16.0"），实际收到 ${JSON.stringify(nodeVersion)}。`);
+    }
+    if (nodeVersion.slice(0, nodeVersion.indexOf(".")) !== nodeLtsMajor) {
+        throw new Error(`Generation Context 的 toolchain.nodeVersion ${nodeVersion} 与 nodeLtsMajor ${nodeLtsMajor} 大版本不一致。`);
+    }
+    return nodeVersion;
+}
+/**
+ * 直接规划接缝：调用方自带 Generation Context，私有根沿用其 Node 声明；上下文带精确事实时
+ * 私有根得到精确版本。生产初始化由 prepareGeneratedRepositoryInitialization 投影 CLI 发版快照。
+ */
 export function planGeneratedRepositoryInitialization(options) {
     const prepared = preparePresetInitialization(options);
     return assertPreflightedInitializationPlan(planPreparedRepositoryInitialization({
@@ -1495,79 +3012,46 @@ export function planGeneratedRepositoryInitialization(options) {
         context: options.context,
         presetBlueprint: prepared.presetBlueprint,
         contributions: prepared.contributions,
+        rootNodeDeclaration: resolvePrivateRootNodeDeclaration(options.context.toolchain),
     }));
 }
+/**
+ * 初始化只消费随 CLI 发版的不可变工具链快照：私有根得到精确 Node 与 pnpm pin，
+ * 选用 Rust 的仓库根 toolchain 声明得到快照的精确 Rust 版本，Generation Record 与容器等
+ * 消费者继续得到派生的大版本。不读在线版本源，也不接受调用方版本。
+ */
+const initializationSnapshotToolchain = {
+    nodeLtsMajor: releaseToolchainSnapshot.nodeVersion.slice(0, releaseToolchainSnapshot.nodeVersion.indexOf(".")),
+    packageManagerPin: releaseToolchainSnapshot.packageManagerPin,
+    nodeVersion: releaseToolchainSnapshot.nodeVersion,
+    rustVersion: releaseToolchainSnapshot.rustVersion,
+};
 export function prepareGeneratedRepositoryInitialization(options) {
-    const diagnostics = [];
-    const appendDiagnostics = (error) => {
-        diagnostics.push(...errorDiagnostics(error));
-    };
-    const scopeOverride = options.overrides?.scope;
-    const normalizedScope = scopeOverride?.startsWith("@") === true
-        ? scopeOverride.slice(1)
-        : scopeOverride;
-    const nameOverride = options.overrides?.name;
-    const pathOverride = options.overrides?.path;
-    const repositoryName = path.basename(path.resolve(options.targetDir));
-    const configurablePrimaryPackage = options.definition.initialPrimaryPackage !== undefined;
-    if (!configurablePrimaryPackage &&
-        (nameOverride !== undefined || pathOverride !== undefined)) {
-        diagnostics.push(`Built-in Preset ${options.definition.metadata.name} has fixed initial package topology and does not accept --name or --path`);
-    }
-    let validNameOverride = nameOverride !== undefined &&
-        isValidNewNpmPackageName(`@x/${nameOverride}`);
-    if (nameOverride !== undefined && !validNameOverride) {
-        diagnostics.push("--name must be an unscoped package leaf name");
-    }
-    let validPathOverride = pathOverride !== undefined;
-    if (pathOverride !== undefined) {
-        const pathValidation = validateNewPackagePath(pathOverride);
-        if (!pathValidation.hasValidShape) {
-            diagnostics.push("--path must be exactly two safe path segments");
-            validPathOverride = false;
-        }
-        if (pathValidation.reservedWorkspaceCollection !== undefined) {
-            diagnostics.push(`--path ${pathOverride} uses reserved workspace collection ${pathValidation.reservedWorkspaceCollection}`);
-            validPathOverride = false;
+    const input = collectInitializationInput(options);
+    if (input.status === "input-invalid")
+        return input;
+    const { definition, normalizedScope, nameOverride, pathOverride, repositoryName, configurablePrimaryPackage, validScopeOverride, validRepositoryScope, resolvedScope, initialPrimaryPackage, foundationDefinition, } = input;
+    let derivedPackagePath;
+    if (initialPrimaryPackage !== undefined) {
+        try {
+            derivedPackagePath = initialPrimaryPackage.defaultPackagePath({
+                packageLeafName: nameOverride ?? initialPrimaryPackage.defaultLeafName,
+            });
         }
-    }
-    let validScopeOverride = normalizedScope !== undefined &&
-        scopeOverride === scopeOverride?.trim() &&
-        isValidDefaultPackageScope(normalizedScope) &&
-        isValidNewNpmPackageName(`@${normalizedScope}/typescript-config`);
-    if (normalizedScope !== undefined && !validScopeOverride) {
-        diagnostics.push("--scope must be a valid npm scope without whitespace");
-    }
-    let validRepositoryScope = isValidDefaultPackageScope(repositoryName) &&
-        isValidNewNpmPackageName(`@${repositoryName}/typescript-config`);
-    if (normalizedScope === undefined && !validRepositoryScope) {
-        diagnostics.push(`Repository Identity ${repositoryName} is not a valid default package scope; pass --scope with a valid npm scope`);
-    }
-    const resolvedScope = validScopeOverride
-        ? (normalizedScope ?? "repository")
-        : validRepositoryScope
-            ? repositoryName
-            : "repository";
-    const resolvedLeaf = configurablePrimaryPackage &&
-        nameOverride !== undefined &&
-        validNameOverride
-        ? nameOverride
-        : configurablePrimaryPackage
-            ? options.definition.initialPrimaryPackage?.defaultLeafName
-            : undefined;
-    if (resolvedLeaf !== undefined &&
-        !isValidNewNpmPackageName(`@${resolvedScope}/${resolvedLeaf}`)) {
-        if (nameOverride !== undefined) {
-            validNameOverride = false;
-            diagnostics.push("--name must be an unscoped package leaf name");
+        catch {
+            return { status: "operation-failure", phase: "preset" };
         }
-        else if (scopeOverride !== undefined) {
-            validScopeOverride = false;
-            diagnostics.push("--scope must be a valid npm scope without whitespace");
+        const derivedPathValidation = validateNewPackagePath(derivedPackagePath);
+        if (!derivedPathValidation.hasValidShape ||
+            derivedPathValidation.reservedWorkspaceCollection !== undefined) {
+            return { status: "operation-failure", phase: "preset" };
         }
-        else {
-            validRepositoryScope = false;
-            diagnostics.push(`Repository Identity ${repositoryName} is not a valid default package scope; pass --scope with a valid npm scope`);
+        if ((nameOverride === undefined &&
+            `@${resolvedScope}/${initialPrimaryPackage.defaultLeafName}` ===
+                foundationDefinition.name) ||
+            (pathOverride === undefined &&
+                derivedPackagePath === foundationDefinition.path)) {
+            return { status: "operation-failure", phase: "preset" };
         }
     }
     const context = createGenerationContext({
@@ -1577,77 +3061,56 @@ export function prepareGeneratedRepositoryInitialization(options) {
             : validRepositoryScope
                 ? repositoryName
                 : "repository",
-        toolchain: options.toolchain,
+        toolchain: initializationSnapshotToolchain,
     });
-    const safeNameOverride = configurablePrimaryPackage && nameOverride !== undefined
-        ? validNameOverride
-            ? nameOverride
-            : "x"
-        : undefined;
-    let safeDerivedPathOverride;
-    const initialPrimaryPackage = options.definition.initialPrimaryPackage;
-    if (initialPrimaryPackage !== undefined && pathOverride === undefined) {
-        const safeLeafName = safeNameOverride ?? initialPrimaryPackage.defaultLeafName;
-        const derivedPackagePath = initialPrimaryPackage.defaultPackagePath({
-            packageLeafName: safeLeafName,
-        });
-        const derivedPathValidation = validateNewPackagePath(derivedPackagePath);
-        if (!derivedPathValidation.hasValidShape ||
-            derivedPathValidation.reservedWorkspaceCollection !== undefined) {
-            diagnostics.push(`Preset-derived Package Path ${derivedPackagePath} is unsafe; pass --path with exactly two safe path segments`);
-            safeDerivedPathOverride = "packages/invalid";
-        }
-    }
     const safeIdentityOverrides = {
-        ...(safeNameOverride === undefined ? {} : { name: safeNameOverride }),
+        ...(configurablePrimaryPackage && nameOverride !== undefined
+            ? { name: nameOverride }
+            : {}),
         ...(configurablePrimaryPackage && pathOverride !== undefined
-            ? { path: validPathOverride ? pathOverride : "packages/invalid" }
-            : safeDerivedPathOverride === undefined
+            ? { path: pathOverride }
+            : derivedPackagePath === undefined
                 ? {}
-                : { path: safeDerivedPathOverride }),
+                : { path: derivedPackagePath }),
     };
     let prepared;
     try {
         prepared = preparePresetInitialization({
-            definition: options.definition,
+            definition,
             context,
             ...(Object.keys(safeIdentityOverrides).length === 0
                 ? {}
                 : { overrides: safeIdentityOverrides }),
         });
     }
-    catch (error) {
-        appendDiagnostics(error);
+    catch {
+        return { status: "operation-failure", phase: "preset" };
     }
     let plan;
-    if (prepared !== undefined) {
-        try {
-            plan = planPreparedRepositoryInitialization({
-                definition: options.definition,
-                context,
-                presetBlueprint: prepared.presetBlueprint,
-                contributions: prepared.contributions,
-            });
-        }
-        catch (error) {
-            appendDiagnostics(error);
-        }
-    }
-    if (plan !== undefined) {
-        diagnostics.push(...validateProjectProjectionPlan({
+    try {
+        plan = planPreparedRepositoryInitialization({
+            definition,
+            context,
+            presetBlueprint: prepared.presetBlueprint,
+            contributions: prepared.contributions,
+            // 私有根与上下文共用同一精确 Node 事实的推导点，避免根声明与上下文出现两个来源。
+            rootNodeDeclaration: resolvePrivateRootNodeDeclaration(context.toolchain),
+        });
+        if (validateProjectProjectionPlan({
             operations: plan.operations,
             reconciliation: plan.reconciliation,
-        }));
+        }).length > 0) {
+            return { status: "operation-failure", phase: "preflight" };
+        }
     }
-    if (diagnostics.length > 0)
-        throw new Error(diagnostics.join("\n"));
-    if (prepared === undefined || plan === undefined) {
-        throw new Error("Initialization preparation did not produce a plan");
+    catch {
+        return { status: "operation-failure", phase: "planning" };
     }
     return {
+        status: "ready",
         context,
         resolved: {
-            preset: options.definition.metadata.name,
+            preset: definition.metadata.name,
             topology: prepared.resolvedPackageIdentity === undefined
                 ? "fixed"
                 : "configurable-primary-package",
@@ -1666,24 +3129,11 @@ export function prepareGeneratedRepositoryInitialization(options) {
             : { command: "./scripts/npm-publication-setup/setup.sh" },
     };
 }
-export function planGeneratedRepositoryPackageAddition(options) {
+function planGeneratedRepositoryPackageAdditionFromPreparedContribution(options) {
     const { blueprint: persistedBlueprint, context } = options.localTemplateMetadata;
+    const { rootNodeDeclaration } = options.localTemplateMetadata[localTemplateMetadataStateKey];
     assertProjectBlueprint(persistedBlueprint);
-    if (!options.definition.planPackageAddition)
-        throw new Error(`Built-in Preset ${options.definition.metadata.name} does not support Package Addition`);
-    const packagePath = options.packagePath ??
-        options.definition.defaultPackagePath?.({
-            context,
-            packageLeafName: options.packageLeafName,
-        });
-    if (packagePath === undefined) {
-        throw new Error(`Built-in Preset ${options.definition.metadata.name} must own a default Package Path or receive an explicit Package Path`);
-    }
-    const contribution = options.definition.planPackageAddition({
-        context,
-        packageLeafName: options.packageLeafName,
-        packagePath,
-    });
+    const contribution = options.contribution;
     const requestedPackageLinkIntents = [...new Set(options.linkFrom ?? [])].map((consumerPackagePath) => ({
         consumerPackagePath,
         providerPackagePath: contribution.definition.path,
@@ -1703,10 +3153,10 @@ export function planGeneratedRepositoryPackageAddition(options) {
                 foundationContribution: existing.foundationContribution,
                 contributions: existing.contributions,
                 renderContributions: [],
-                existingDeploymentEnvironmentNeeds: existing.deploymentEnvironmentNeeds,
                 manifestTruthByPackagePath: existing.manifestTruthByPackagePath,
                 generationRecord: existing.generationRecord,
                 mode: "addition",
+                rootNodeDeclaration,
             });
             const currentProjection = foundationPlan({
                 definition: options.definition,
@@ -1714,9 +3164,9 @@ export function planGeneratedRepositoryPackageAddition(options) {
                 blueprint: persistedBlueprint,
                 foundationContribution: existing.foundationContribution,
                 contributions: existing.contributions,
-                existingDeploymentEnvironmentNeeds: existing.deploymentEnvironmentNeeds,
                 generationRecord: existing.generationRecord,
                 mode: "initialization",
+                rootNodeDeclaration,
             });
             return {
                 ...plan,
@@ -1735,9 +3185,9 @@ export function planGeneratedRepositoryPackageAddition(options) {
             };
         }
         if (isExactPackageDefinition) {
-            throw new Error(`Package Addition conflicts because requested Package Link Intent ${missingPackageLinkIntent.consumerPackagePath} -> ${missingPackageLinkIntent.providerPackagePath} does not already exist`);
+            throw new PackageAdditionBusinessConflict("missing-link", conflictingPackage, contribution.definition, missingPackageLinkIntent);
         }
-        throw new Error(`Package Addition conflicts with existing Package Definition ${conflictingPackage.name} at ${conflictingPackage.path} (${conflictingPackage.role}); requested ${contribution.definition.name} at ${contribution.definition.path} (${contribution.definition.role})`);
+        throw new PackageAdditionBusinessConflict("identity", conflictingPackage, contribution.definition);
     }
     const contributionIdentity = requireReplayAdapter({
         owner: options.definition.metadata.name,
@@ -1798,9 +3248,9 @@ export function planGeneratedRepositoryPackageAddition(options) {
         blueprint: persistedBlueprint,
         foundationContribution: existing.foundationContribution,
         contributions: existing.contributions,
-        existingDeploymentEnvironmentNeeds: existing.deploymentEnvironmentNeeds,
         generationRecord: existing.generationRecord,
         mode: "initialization",
+        rootNodeDeclaration,
     });
     const afterProjection = foundationPlan({
         definition: options.definition,
@@ -1808,10 +3258,10 @@ export function planGeneratedRepositoryPackageAddition(options) {
         blueprint,
         foundationContribution: existing.foundationContribution,
         contributions: [...existing.contributions, contribution],
-        existingDeploymentEnvironmentNeeds: existing.deploymentEnvironmentNeeds,
         manifestTruthByPackagePath: existing.manifestTruthByPackagePath,
         generationRecord,
         mode: "initialization",
+        rootNodeDeclaration,
     });
     const plan = foundationPlan({
         definition: options.definition,
@@ -1820,20 +3270,35 @@ export function planGeneratedRepositoryPackageAddition(options) {
         foundationContribution: existing.foundationContribution,
         contributions: [...existing.contributions, contribution],
         renderContributions: [contribution],
-        existingDeploymentEnvironmentNeeds: existing.deploymentEnvironmentNeeds,
         manifestTruthByPackagePath: existing.manifestTruthByPackagePath,
         generationRecord,
         mode: "addition",
+        rootNodeDeclaration,
     });
+    let beforeOperations = beforeProjection.operations;
+    let afterOperations = afterProjection.operations;
+    if (options.existingRootRustDeclaration !== undefined) {
+        const preserveOperation = {
+            kind: "writeText",
+            to: rootRustDeclarationFileName,
+            text: options.existingRootRustDeclaration,
+        };
+        beforeOperations = [...beforeProjection.operations, preserveOperation];
+        afterOperations = afterProjection.operations.map((operation) => operation.kind === "writeTextTemplate" &&
+            "to" in operation &&
+            operation.to === rootRustDeclarationFileName
+            ? preserveOperation
+            : operation);
+    }
     return {
         ...plan,
         projectProjections: {
             before: {
-                operations: beforeProjection.operations,
+                operations: beforeOperations,
                 reconciliation: beforeProjection.reconciliation,
             },
             after: {
-                operations: afterProjection.operations,
+                operations: afterOperations,
                 reconciliation: afterProjection.reconciliation,
             },
             preconditions: [
@@ -1846,3 +3311,215 @@ export function planGeneratedRepositoryPackageAddition(options) {
         },
     };
 }
+export function planGeneratedRepositoryPackageAddition(options) {
+    const { context } = options.localTemplateMetadata;
+    if (options.definition.planPackageAddition === undefined) {
+        throw new Error(`Built-in Preset ${options.definition.metadata.name} does not support Package Addition`);
+    }
+    const packagePath = options.packagePath ??
+        options.definition.defaultPackagePath?.({
+            context,
+            packageLeafName: options.packageLeafName,
+        });
+    if (packagePath === undefined) {
+        throw new Error(`Built-in Preset ${options.definition.metadata.name} must own a default Package Path or receive an explicit Package Path`);
+    }
+    const contribution = options.definition.planPackageAddition({
+        context,
+        packageLeafName: options.packageLeafName,
+        packagePath,
+    });
+    return planGeneratedRepositoryPackageAdditionFromPreparedContribution({
+        ...options,
+        packagePath,
+        contribution,
+    });
+}
+function collectPackageAdditionInput(options) {
+    const issues = [];
+    const definition = builtInPresetRegistry
+        .all()
+        .find((candidate) => candidate.metadata.name === options.preset);
+    if (definition === undefined)
+        issues.push({ code: "PRESET_UNKNOWN" });
+    else if (definition.planPackageAddition === undefined)
+        issues.push({ code: "PRESET_NOT_ADDABLE" });
+    if (!isValidNewNpmPackageName(`@x/${options.packageLeafName}`)) {
+        issues.push({ code: "INVALID_PACKAGE_NAME" });
+    }
+    if (options.packagePath !== undefined) {
+        const validation = validateNewPackagePath(options.packagePath);
+        if (!validation.hasValidShape)
+            issues.push({ code: "INVALID_PACKAGE_PATH" });
+        if (validation.reservedWorkspaceCollection !== undefined) {
+            issues.push({ code: "RESERVED_PACKAGE_PATH" });
+        }
+    }
+    const linkFrom = [...new Set(options.linkFrom ?? [])];
+    for (const consumerPackagePath of linkFrom) {
+        const validation = validateNewPackagePath(consumerPackagePath);
+        if (!validation.hasValidShape) {
+            issues.push({ code: "INVALID_LINK_FROM" });
+        }
+        if (validation.reservedWorkspaceCollection !== undefined)
+            issues.push({ code: "RESERVED_LINK_FROM" });
+    }
+    if (issues.length > 0 || definition === undefined) {
+        return { status: "input-invalid", issues };
+    }
+    return { status: "valid", definition, linkFrom };
+}
+/**
+ * Command-owned preparation: user input is checked before local metadata or any
+ * Preset default/planner work; all remaining failures are deliberately bounded.
+ */
+export function prepareGeneratedRepositoryPackageAddition(options) {
+    const input = collectPackageAdditionInput(options);
+    if (input.status === "input-invalid")
+        return input;
+    let localTemplateMetadata;
+    try {
+        localTemplateMetadata = loadLocalTemplateMetadata(options.repositoryRoot);
+    }
+    catch (error) {
+        if (error instanceof PackageAdditionTargetDeclarationFailure) {
+            return {
+                status: "operation-failure",
+                phase: "metadata",
+                diagnostic: { message: error.message, suggestion: error.suggestion },
+            };
+        }
+        return { status: "operation-failure", phase: "metadata" };
+    }
+    if (input.linkFrom.some((consumerPackagePath) => !localTemplateMetadata.blueprint.packages.some((candidate) => candidate.path === consumerPackagePath))) {
+        return {
+            status: "input-invalid",
+            issues: [{ code: "UNKNOWN_LINK_FROM" }],
+        };
+    }
+    let packagePath = options.packagePath;
+    if (packagePath === undefined) {
+        try {
+            packagePath = input.definition.defaultPackagePath?.({
+                context: localTemplateMetadata.context,
+                packageLeafName: options.packageLeafName,
+            });
+        }
+        catch {
+            return { status: "operation-failure", phase: "default" };
+        }
+        const defaultPathValidation = packagePath === undefined
+            ? undefined
+            : validateNewPackagePath(packagePath);
+        if (defaultPathValidation === undefined ||
+            !defaultPathValidation.hasValidShape ||
+            defaultPathValidation.reservedWorkspaceCollection !== undefined) {
+            return { status: "operation-failure", phase: "default" };
+        }
+    }
+    if (packagePath === undefined) {
+        return { status: "operation-failure", phase: "default" };
+    }
+    let provider;
+    try {
+        provider = input.definition.planPackageAddition({
+            context: localTemplateMetadata.context,
+            packageLeafName: options.packageLeafName,
+            packagePath,
+        });
+    }
+    catch {
+        return { status: "operation-failure", phase: "planning" };
+    }
+    // 首次引入 Rust 的加包按目标事实二选一：已有合法根声明由该声明拥有版本并原正文保留；
+    // 没有根声明才以当前 CLI 已验证快照建源。已有 Rust 能力的仓库在 loadLocalTemplateMetadata
+    // 已由根 channel 重放（缺真源在那里失败），不进入这条路径；不可解释的声明在此可行动失败，
+    // 不用快照掩盖。非 Rust 加包不读无关根文件。
+    let additionMetadata = localTemplateMetadata;
+    let preservedRootRustDeclaration;
+    if (provider.foundation.toolchains.rust !== undefined &&
+        localTemplateMetadata.context.toolchain.rustVersion === undefined) {
+        const repositoryRoot = localTemplateMetadata.context.targetDir;
+        const rootDeclarationPath = path.join(repositoryRoot, rootRustDeclarationFileName);
+        const existingDeclaration = existsSync(rootDeclarationPath)
+            ? readFileSync(rootDeclarationPath, "utf8")
+            : undefined;
+        let rustVersion;
+        try {
+            if (existingDeclaration === undefined) {
+                rustVersion = releaseToolchainSnapshot.rustVersion;
+            }
+            else {
+                rustVersion = readPackageAdditionTargetRustChannel(repositoryRoot);
+                preservedRootRustDeclaration = existingDeclaration;
+            }
+        }
+        catch (error) {
+            if (error instanceof PackageAdditionTargetDeclarationFailure) {
+                return {
+                    status: "operation-failure",
+                    phase: "metadata",
+                    diagnostic: { message: error.message, suggestion: error.suggestion },
+                };
+            }
+            return { status: "operation-failure", phase: "metadata" };
+        }
+        additionMetadata = {
+            ...localTemplateMetadata,
+            context: {
+                ...localTemplateMetadata.context,
+                toolchain: {
+                    ...localTemplateMetadata.context.toolchain,
+                    rustVersion,
+                },
+            },
+        };
+        try {
+            provider = input.definition.planPackageAddition({
+                context: additionMetadata.context,
+                packageLeafName: options.packageLeafName,
+                packagePath,
+            });
+        }
+        catch {
+            return { status: "operation-failure", phase: "planning" };
+        }
+    }
+    const contributionsByPath = new Map(localTemplateMetadata[localTemplateMetadataStateKey].packageContributions.map((contribution) => [
+        contribution.definition.path,
+        contribution,
+    ]));
+    if (input.linkFrom.length > 0 &&
+        (!canProvideSourceConditionPackageNameImport(provider) ||
+            input.linkFrom.some((consumerPackagePath) => {
+                const consumer = contributionsByPath.get(consumerPackagePath);
+                return (consumer === undefined ||
+                    !canConsumeNodePackageNameImport(consumer) ||
+                    !canLinkNodePackageRoles(consumer.definition.role, provider.definition.role));
+            }))) {
+        return { status: "input-invalid", issues: [{ code: "UNSUPPORTED_LINK" }] };
+    }
+    try {
+        return {
+            status: "ready",
+            definition: input.definition,
+            plan: planGeneratedRepositoryPackageAdditionFromPreparedContribution({
+                definition: input.definition,
+                localTemplateMetadata: additionMetadata,
+                packageLeafName: options.packageLeafName,
+                packagePath,
+                contribution: provider,
+                ...(input.linkFrom.length === 0 ? {} : { linkFrom: input.linkFrom }),
+                ...(preservedRootRustDeclaration === undefined
+                    ? {}
+                    : { existingRootRustDeclaration: preservedRootRustDeclaration }),
+            }),
+        };
+    }
+    catch (error) {
+        if (error instanceof PackageAdditionBusinessConflict) {
+            return { status: "conflict", conflict: error };
+        }
+        return { status: "operation-failure", phase: "planning" };
+    }
+}