@ykdz/template 0.0.42 → 0.1.0-experimental.1

package/node_modules/@ykdz/template-generator/dist/index.js

@@ -0,0 +1,1147 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { assertContentIdentity, contentIdentityKey, contentIdentityLabel, createContentIndex, } from "@ykdz/template-core/content-identity";
+import { assertPackageContribution, } from "@ykdz/template-core/package-contribution";
+import { assertProjectBlueprint, } from "@ykdz/template-core/project-blueprint";
+import { reconcileAndApplyProjectProjections, materializeProjectProjection, } from "@ykdz/template-core/project-projection";
+import { renderNewProject } from "@ykdz/template-core/renderer";
+import { parseGenerationRecordStructure } from "@ykdz/template-core/workspace-strategy";
+export { generationRecordSchema } from "@ykdz/template-core/workspace-strategy";
+function packageIdentity(definition) {
+    return {
+        name: definition.name,
+        path: definition.path,
+        role: definition.role,
+    };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isPresetDefinition(value) {
+    return isRecord(value) && value.kind === "preset" && isRecord(value.nodes);
+}
+function isLoadedPreset(value) {
+    return (isRecord(value) &&
+        value.kind === "preset" &&
+        isRecord(value.definition) &&
+        isPresetDefinition(value.definition));
+}
+function mergeCreationInput(defaults, supplied) {
+    if (defaults === undefined)
+        return supplied;
+    if (supplied === undefined)
+        return defaults;
+    return { ...defaults, ...supplied };
+}
+function fail(phase, error, diagnostic) {
+    return {
+        status: "operation-failure",
+        phase,
+        error: {
+            message: error instanceof Error ? error.message : String(error),
+            ...(diagnostic === undefined ? {} : { diagnostic }),
+        },
+    };
+}
+class AdditionPlanningFailure extends Error {
+    constructor(error) {
+        super(error instanceof Error ? error.message : String(error), {
+            cause: error,
+        });
+    }
+}
+function readJson(value, label) {
+    if (!isRecord(value))
+        throw new Error(label + " must be an object");
+    return value;
+}
+function presetSelectionKey(identity) {
+    return contentIdentityKey(identity);
+}
+function parsePresetSelections(value) {
+    if (!Array.isArray(value))
+        throw new Error("生成记录的预设选择无效");
+    const seen = new Set();
+    return value.map((item) => {
+        const selection = readJson(item, "生成记录预设选择");
+        assertContentIdentity(selection);
+        const key = presetSelectionKey(selection);
+        if (seen.has(key))
+            throw new Error("生成记录的预设选择重复");
+        seen.add(key);
+        return { ...selection };
+    });
+}
+export function parseGenerationRecord(value) {
+    const record = parseGenerationRecordStructure(value);
+    const nodeInstances = record.nodeInstances;
+    const packageIds = new Set();
+    for (const packageRecord of record.packages) {
+        assertContentIdentity(packageRecord.contentIdentity);
+        if (packageIds.has(packageRecord.packageDefinitionId)) {
+            throw new Error("生成记录包含重复包实例：" + packageRecord.packageDefinitionId);
+        }
+        packageIds.add(packageRecord.packageDefinitionId);
+    }
+    for (const packageRecord of record.packages) {
+        for (const [identity, packageDefinitionId] of Object.entries(packageRecord.bindings)) {
+            if (identity.length === 0 || !packageIds.has(packageDefinitionId)) {
+                throw new Error(`生成记录中的内容 ${contentIdentityLabel(packageRecord.contentIdentity)} 包含无效实例绑定：${identity}`);
+            }
+        }
+    }
+    for (const [nodeIdentity, packageDefinitionId] of Object.entries(nodeInstances)) {
+        if (nodeIdentity.length === 0 ||
+            typeof packageDefinitionId !== "string" ||
+            !packageIds.has(packageDefinitionId)) {
+            throw new Error("生成记录的节点实例映射无效");
+        }
+    }
+    const presetSelections = parsePresetSelections(record.presetSelections);
+    return {
+        schemaVersion: 4,
+        strategyIdentity: record.strategyIdentity,
+        strategyState: record.strategyState,
+        packages: record.packages,
+        nodeInstances: nodeInstances,
+        presetSelections,
+    };
+}
+function packageId(options) {
+    const facts = {
+        domain: "ykdz.template.generator.package-instance.v1",
+        contentIdentity: options.contentIdentity,
+        createdBy: options.createdBy,
+        definition: options.definition,
+    };
+    let nonce = 0;
+    for (;;) {
+        const value = nonce === 0
+            ? facts
+            : { facts, occupied: [...options.occupied].toSorted(), nonce };
+        const candidate = "package-" +
+            createHash("sha256").update(JSON.stringify(value)).digest("hex");
+        if (!options.occupied.has(candidate)) {
+            return candidate;
+        }
+        nonce += 1;
+    }
+}
+export function createGenerator(options) {
+    const contentIndex = createContentIndex(options.content);
+    const contentMembers = contentIndex.members.filter((member) => member.kind === "reference");
+    const presetMembers = contentIndex.members.filter(isLoadedPreset);
+    const contentByIdentity = new Map(contentMembers.map((content) => [
+        contentIdentityKey(content.identity),
+        content,
+    ]));
+    const preparations = new WeakMap();
+    const preparedDefinitions = new WeakSet();
+    const prepareContent = (content) => {
+        const definition = content.definition;
+        if (preparedDefinitions.has(definition))
+            return preparations.get(definition);
+        const preparation = definition.prepare?.();
+        preparations.set(definition, preparation);
+        preparedDefinitions.add(definition);
+        return preparation;
+    };
+    const presetsByIdentity = new Map();
+    for (const presetMember of presetMembers) {
+        const preset = presetMember.definition;
+        const identityKey = contentIdentityKey(presetMember.identity);
+        if (presetsByIdentity.has(identityKey)) {
+            throw new Error(`预设规范身份重复：${contentIdentityLabel(presetMember.identity)}`);
+        }
+        presetsByIdentity.set(identityKey, presetMember);
+        for (const node of Object.values(preset.nodes)) {
+            try {
+                contentIndex.fromDefinition(node.reference, "reference", {
+                    namespace: presetMember.identity.namespace,
+                });
+            }
+            catch (error) {
+                throw new Error(`预设${contentIdentityLabel(presetMember.identity)}引用未装载的来源定义：${error instanceof Error ? error.message : String(error)}`, { cause: error });
+            }
+        }
+    }
+    function requireContent(selector) {
+        return contentIndex.resolve(selector, "reference");
+    }
+    function resolvePreset(selector) {
+        const member = isPresetDefinition(selector)
+            ? contentIndex.fromDefinition(selector, "preset")
+            : contentIndex.resolve(selector, "preset");
+        return member;
+    }
+    function expandPreset(options_) {
+        const preset = options_.preset.definition;
+        if (!preset.operations.includes(options_.operation)) {
+            throw new Error(`预设不支持${options_.operation}操作`);
+        }
+        const nodes = Object.entries(preset.nodes);
+        if ((options_.creationInput !== undefined ||
+            options_.configuration !== undefined) &&
+            nodes.length !== 1) {
+            throw new Error("多节点预设不能接收单一包创建输入");
+        }
+        return nodes.map(([nodeIdentity, node]) => {
+            const creationInput = mergeCreationInput(node.creationInput?.[options_.operation], options_.creationInput);
+            const reference = contentIndex.fromDefinition(node.reference, "reference", { namespace: options_.preset.identity.namespace });
+            return {
+                nodeIdentity,
+                contentIdentity: reference.identity,
+                ...(node.layout === undefined ? {} : { layout: node.layout }),
+                ...(creationInput === undefined ? {} : { creationInput }),
+                configuration: options_.configuration === undefined
+                    ? node.configuration?.[options_.operation]
+                    : options_.configuration,
+            };
+        });
+    }
+    function findByPackageId(records, id) {
+        const record = records.find((candidate) => candidate.packageDefinitionId === id);
+        if (record === undefined) {
+            throw new Error("生成记录引用了不存在的包实例：" + id);
+        }
+        return record;
+    }
+    function normalizeConfiguration(content, input) {
+        if (content.definition.normalizeConfiguration !== undefined)
+            return content.definition.normalizeConfiguration(input) ?? null;
+        if (input !== undefined && input !== null)
+            throw new Error(`内容 ${contentIdentityLabel(content.identity)} 不支持实例配置`);
+        return null;
+    }
+    function resolvePackageStates(records, blueprint) {
+        const definitionsById = new Map(blueprint.packages.map((definition) => [
+            definition.packageDefinitionId,
+            definition,
+        ]));
+        if (definitionsById.size !== records.length) {
+            throw new Error("生成记录与蓝图的包实例数量不一致");
+        }
+        for (const definition of blueprint.packages) {
+            if (!records.some((record) => record.packageDefinitionId === definition.packageDefinitionId)) {
+                throw new Error(`蓝图包实例缺少生成记录事实：${definition.packageDefinitionId}`);
+            }
+        }
+        return records.map((record) => {
+            const definition = definitionsById.get(record.packageDefinitionId);
+            if (definition === undefined) {
+                throw new Error(`蓝图缺少内容 ${contentIdentityLabel(record.contentIdentity)} 对应的包实例：${record.packageDefinitionId}`);
+            }
+            const configuration = normalizeConfiguration(requireContent(record.contentIdentity), record.configuration);
+            if (!isDeepStrictEqual(configuration, record.configuration))
+                throw new Error(`生成记录包含未规范化的实例配置：${definition.path}`);
+            return { ...record, definition };
+        });
+    }
+    function requiredDependencyIdentities(records) {
+        const dependenciesByPackageId = new Map();
+        for (const record of records) {
+            const content = requireContent(record.contentIdentity);
+            dependenciesByPackageId.set(record.definition.packageDefinitionId, options.strategy.dependencies({
+                content,
+                contentByIdentity,
+                configuration: record.configuration,
+                ...(record.creationInput === null
+                    ? {}
+                    : { creationInput: record.creationInput }),
+            }));
+        }
+        return dependenciesByPackageId;
+    }
+    function validateRequiredBindings(records, dependenciesByPackageId = requiredDependencyIdentities(records), providers = records) {
+        for (const record of records) {
+            const dependencies = dependenciesByPackageId.get(record.definition.packageDefinitionId);
+            if (dependencies === undefined) {
+                throw new Error("生成记录缺少已准备的内容依赖：" +
+                    contentIdentityLabel(record.contentIdentity));
+            }
+            for (const dependency of dependencies) {
+                const dependencyKey = contentIdentityKey(dependency);
+                const packageDefinitionId = record.bindings[dependencyKey];
+                if (packageDefinitionId === undefined) {
+                    throw new Error(`生成记录中的内容 ${contentIdentityLabel(record.contentIdentity)} 缺少必要实例绑定：${contentIdentityLabel(dependency)}`);
+                }
+                const provider = findByPackageId(providers, packageDefinitionId);
+                if (contentIdentityKey(provider.contentIdentity) !== dependencyKey) {
+                    throw new Error(`生成记录中的内容 ${contentIdentityLabel(record.contentIdentity)} 将依赖绑定到错误实例：${contentIdentityLabel(dependency)}`);
+                }
+            }
+        }
+    }
+    function validateNodeInstances(records, nodeInstances) {
+        const mappedIds = new Set(Object.values(nodeInstances));
+        for (const record of records) {
+            if (record.createdBy === "initialization" &&
+                !mappedIds.has(record.packageDefinitionId)) {
+                throw new Error(`生成记录中的内容 ${contentIdentityLabel(record.contentIdentity)} 缺少必要节点实例映射：${record.packageDefinitionId}`);
+            }
+        }
+    }
+    function validatePresetSelections(selections) {
+        for (const selection of selections) {
+            if (!presetsByIdentity.has(presetSelectionKey(selection))) {
+                throw new Error(`生成记录所选预设不可用：${contentIdentityLabel(selection)}`);
+            }
+        }
+    }
+    function resolveNodeInstances(records, nodeInstances) {
+        return new Map(Object.entries(nodeInstances).map(([nodeIdentity, packageDefinitionId]) => [
+            nodeIdentity,
+            findByPackageId(records, packageDefinitionId).definition,
+        ]));
+    }
+    function nodesFromRecords(records) {
+        return records.map((record) => {
+            return {
+                content: requireContent(record.contentIdentity),
+                definition: record.definition,
+                createdBy: record.createdBy,
+                configuration: record.configuration,
+                preparation: preparations.get(requireContent(record.contentIdentity).definition),
+                preparationComplete: preparedDefinitions.has(requireContent(record.contentIdentity).definition),
+                ...(record.creationInput === null
+                    ? {}
+                    : { creationInput: record.creationInput }),
+                providers: new Map(),
+                record,
+            };
+        });
+    }
+    function createContribution(node, context, allRecords, nodeInstances) {
+        if (node.contribution !== undefined)
+            return node.contribution;
+        const providerDefinitions = new Map();
+        const bindings = node.record?.bindings;
+        if (bindings !== undefined) {
+            for (const [identity, id] of Object.entries(bindings)) {
+                const record = findByPackageId(allRecords, id);
+                providerDefinitions.set(identity, record.definition);
+            }
+        }
+        else {
+            for (const [identity, provider] of node.providers) {
+                if (provider.record === undefined) {
+                    throw new Error("内容闭包的包实例尚未登记：" + identity);
+                }
+                providerDefinitions.set(identity, provider.definition);
+            }
+        }
+        const nativeBindings = options.strategy.bindings({
+            content: node.content,
+            contentByIdentity,
+            providers: providerDefinitions,
+        });
+        const contributionOptions = {
+            context,
+            configuration: node.configuration,
+            definition: node.definition,
+            bindings: nativeBindings,
+            createdBy: node.createdBy,
+            nodeInstances,
+            ...(node.preparationComplete ? { preparation: node.preparation } : {}),
+            ...(node.creationInput === undefined
+                ? {}
+                : { creationInput: node.creationInput }),
+        };
+        const contribution = node.content.definition.contribute(contributionOptions);
+        const contributionDefinition = contribution.definition;
+        if (contributionDefinition.name !== node.definition.name ||
+            contributionDefinition.path !== node.definition.path ||
+            contributionDefinition.role !== node.definition.role ||
+            ("packageDefinitionId" in contributionDefinition &&
+                contributionDefinition.packageDefinitionId !==
+                    node.record?.packageDefinitionId)) {
+            throw new Error(`内容 ${contentIdentityLabel(node.content.identity)} 返回的包定义与已分配实例不一致：${node.definition.path}`);
+        }
+        assertPackageContribution({
+            definition: node.definition,
+            operations: contribution.operations,
+        }, {
+            definitionName: contentIdentityLabel(node.content.identity),
+            planner: "内容贡献",
+        });
+        node.contribution = contribution;
+        return node.contribution;
+    }
+    function storedRecord(state, records, nodeInstances, presetSelections) {
+        return {
+            schemaVersion: 4,
+            strategyIdentity: options.strategy.identity,
+            strategyState: state,
+            packages: records.map(({ definition: _definition, ...record }) => record),
+            nodeInstances,
+            presetSelections,
+        };
+    }
+    function selectedPreset(preset) {
+        return preset.identity;
+    }
+    function mergePresetSelections(existing, added) {
+        const selections = new Map();
+        for (const selection of [...existing, ...added]) {
+            selections.set(presetSelectionKey(selection), selection);
+        }
+        return [...selections.values()];
+    }
+    async function validatePresetUpdate(targetRoot, context, contributions, nodeInstances, presetSelections) {
+        for (const selection of presetSelections) {
+            const presetMember = presetsByIdentity.get(presetSelectionKey(selection));
+            if (presetMember === undefined) {
+                throw new Error(`生成记录所选预设不可用：${contentIdentityLabel(selection)}`);
+            }
+            await presetMember.definition.validateUpdate?.({
+                targetRoot,
+                context,
+                contributions,
+                nodeInstances,
+            });
+        }
+    }
+    function computePresetProjectContributions(context, contributions, nodeInstances, presetSelections) {
+        return presetSelections.flatMap((selection) => {
+            const presetMember = presetsByIdentity.get(presetSelectionKey(selection));
+            if (presetMember === undefined) {
+                throw new Error(`生成记录所选预设不可用：${contentIdentityLabel(selection)}`);
+            }
+            if (presetMember.definition.project === undefined)
+                return [];
+            return presetMember.definition.project({
+                context,
+                contributions,
+                nodeInstances,
+            });
+        });
+    }
+    function project(context, state, blueprint, records, contributions, nodeInstances, presetSelections) {
+        const resolvedNodeInstances = resolveNodeInstances(records, nodeInstances);
+        const presetProjectContributions = computePresetProjectContributions(context, contributions, resolvedNodeInstances, presetSelections);
+        const projection = options.strategy.project({
+            context,
+            state,
+            blueprint,
+            packages: records,
+            contributions,
+            nodeInstances: resolvedNodeInstances,
+            presetProjectContributions,
+        });
+        const projectedBlueprint = assertProjectBlueprint(projection.blueprint ?? blueprint);
+        const allocatedDefinitions = new Map(records.map((record) => [record.packageDefinitionId, record.definition]));
+        if (projectedBlueprint.packages.length !== allocatedDefinitions.size) {
+            throw new Error("策略蓝图必须引用完整且唯一的已分配包实例");
+        }
+        for (const projectedDefinition of projectedBlueprint.packages) {
+            const allocated = allocatedDefinitions.get(projectedDefinition.packageDefinitionId);
+            if (allocated === undefined ||
+                allocated.name !== projectedDefinition.name ||
+                allocated.path !== projectedDefinition.path ||
+                allocated.role !== projectedDefinition.role) {
+                throw new Error("策略蓝图中的包定义必须与生成器分配的包实例一致：" +
+                    projectedDefinition.path);
+            }
+            allocatedDefinitions.delete(projectedDefinition.packageDefinitionId);
+        }
+        if (allocatedDefinitions.size > 0) {
+            throw new Error("策略蓝图遗漏了已分配的包实例");
+        }
+        const generationRecord = storedRecord(state, records, nodeInstances, presetSelections);
+        return {
+            ...projection,
+            blueprint: projectedBlueprint,
+            operations: [
+                ...projection.operations,
+                {
+                    kind: "writeJson",
+                    to: ".template/generation.json",
+                    value: generationRecord,
+                },
+            ],
+            generationRecord,
+        };
+    }
+    function expandDependencies(options_) {
+        const newNodes = new Map();
+        const visiting = new Set();
+        const expanded = new Set();
+        const visit = (node) => {
+            const identity = contentIdentityKey(node.content.identity);
+            const key = identity + "\u0000" + node.definition.path;
+            if (visiting.has(key)) {
+                throw new Error("显式内容依赖形成循环：" +
+                    contentIdentityLabel(node.content.identity));
+            }
+            if (expanded.has(key))
+                return;
+            visiting.add(key);
+            if (node.record === undefined)
+                newNodes.set(key, node);
+            node.preparation = prepareContent(node.content);
+            node.preparationComplete = true;
+            const dependencies = options.strategy.dependencies({
+                content: node.content,
+                contentByIdentity,
+                configuration: node.configuration,
+                ...(node.creationInput === undefined
+                    ? {}
+                    : { creationInput: node.creationInput }),
+            });
+            for (const dependencyIdentity of dependencies) {
+                const dependencyKey = contentIdentityKey(dependencyIdentity);
+                const dependency = requireContent(dependencyIdentity);
+                const candidates = [...options_.existing, ...newNodes.values()].filter((candidate) => contentIdentityKey(candidate.content.identity) === dependencyKey);
+                const boundId = node.record?.bindings[dependencyKey];
+                const bound = boundId === undefined
+                    ? undefined
+                    : candidates.find((candidate) => candidate.record?.packageDefinitionId === boundId);
+                if (bound === undefined && candidates.length > 1) {
+                    throw new Error("依赖内容有多个持久实例，无法唯一绑定：" +
+                        contentIdentityLabel(dependencyIdentity));
+                }
+                let provider = bound ?? candidates[0];
+                if (provider === undefined) {
+                    if (dependency.definition.instance !== "shared") {
+                        throw new Error("缺少明确的独立依赖实例：" +
+                            contentIdentityLabel(dependencyIdentity));
+                    }
+                    const definition = options.strategy.createDefinition({
+                        context: options_.context,
+                        content: dependency,
+                    });
+                    const occupied = [...options_.existing, ...newNodes.values()].find((candidate) => candidate.definition.name === definition.name ||
+                        candidate.definition.path === definition.path);
+                    if (occupied !== undefined) {
+                        throw new Error("共享依赖默认身份已被占用：" + definition.path);
+                    }
+                    provider = {
+                        content: dependency,
+                        definition,
+                        createdBy: "shared-dependency",
+                        configuration: normalizeConfiguration(dependency, undefined),
+                        providers: new Map(),
+                    };
+                    newNodes.set(dependencyKey + "\u0000" + definition.path, provider);
+                }
+                node.providers.set(dependencyKey, provider);
+                visit(provider);
+            }
+            visiting.delete(key);
+            expanded.add(key);
+        };
+        const explicitByContent = new Set();
+        const explicitByPath = new Set();
+        const explicitByNode = new Set();
+        for (const root of options_.roots) {
+            const identity = contentIdentityKey(root.content.identity);
+            const key = identity + "\u0000" + root.definition.path;
+            if (explicitByNode.has(root.nodeIdentity ?? "")) {
+                throw new Error("显式初始化节点身份重复：" + root.nodeIdentity);
+            }
+            explicitByNode.add(root.nodeIdentity ?? "");
+            if (root.content.definition.instance === "independent" &&
+                explicitByContent.has(identity)) {
+                throw new Error("同一独立内容不能重复作为显式根：" +
+                    contentIdentityLabel(root.content.identity));
+            }
+            explicitByContent.add(identity);
+            if (explicitByPath.has(root.definition.path)) {
+                throw new Error("显式初始化根路径重复：" + root.definition.path);
+            }
+            explicitByPath.add(root.definition.path);
+            if (root.record === undefined)
+                newNodes.set(key, root);
+        }
+        for (const root of options_.roots)
+            visit(root);
+        const nodes = [...newNodes.values()];
+        for (const node of nodes) {
+            const persisted = {
+                ...node.definition,
+                packageDefinitionId: packageId({
+                    contentIdentity: node.content.identity,
+                    createdBy: node.createdBy,
+                    definition: node.definition,
+                    occupied: options_.occupiedIds,
+                }),
+            };
+            options_.occupiedIds.add(persisted.packageDefinitionId);
+            node.definition = persisted;
+            node.record = {
+                contentIdentity: node.content.identity,
+                createdBy: node.createdBy,
+                packageDefinitionId: persisted.packageDefinitionId,
+                creationInput: node.creationInput ?? null,
+                configuration: node.configuration,
+                bindings: {},
+            };
+        }
+        for (const node of new Set([...nodes, ...options_.roots])) {
+            const bindings = Object.fromEntries([...node.providers].map(([identity, provider]) => {
+                if (provider.record === undefined) {
+                    throw new Error("内容闭包绑定缺少包实例：" + identity);
+                }
+                return [identity, provider.record.packageDefinitionId];
+            }));
+            node.record = { ...node.record, bindings };
+        }
+        return nodes;
+    }
+    function persistedContributions(nodes, context, records, nodeInstances) {
+        return nodes.map((node) => createContribution(node, context, records, nodeInstances));
+    }
+    async function init(initOptions) {
+        try {
+            const selectedPresets = [];
+            for (const root of initOptions.selection.roots) {
+                if (!("preset" in root))
+                    continue;
+                selectedPresets.push(selectedPreset(resolvePreset(root.preset)));
+            }
+            const presetSelections = mergePresetSelections([], selectedPresets);
+            const selectionRoots = initOptions.selection.roots.flatMap((root) => "preset" in root
+                ? expandPreset({
+                    preset: resolvePreset(root.preset),
+                    operation: "init",
+                    configuration: root.configuration,
+                    ...(root.creationInput === undefined
+                        ? {}
+                        : { creationInput: root.creationInput }),
+                })
+                : [
+                    {
+                        ...root,
+                        contentIdentity: requireContent(root.contentIdentity).identity,
+                    },
+                ]);
+            if (selectionRoots.length === 0) {
+                throw new Error("初始化至少需要一个显式内容根");
+            }
+            const rootsByIdentity = new Set();
+            for (const root of selectionRoots) {
+                if (root.nodeIdentity.length === 0) {
+                    throw new Error("显式初始化节点身份不能为空");
+                }
+                if (rootsByIdentity.has(root.nodeIdentity)) {
+                    throw new Error("显式初始化节点身份重复：" + root.nodeIdentity);
+                }
+                rootsByIdentity.add(root.nodeIdentity);
+                requireContent(root.contentIdentity);
+            }
+            const prepared = options.strategy.initialize({
+                targetRoot: initOptions.targetRoot,
+                input: initOptions.strategyInput,
+                selection: selectionRoots,
+                contentByIdentity,
+            });
+            const roots = selectionRoots.map((root) => {
+                const content = requireContent(root.contentIdentity);
+                const definition = options.strategy.createDefinition({
+                    context: prepared.context,
+                    content,
+                    ...(root.layout === undefined ? {} : { layout: root.layout }),
+                    ...(root.creationInput === undefined
+                        ? {}
+                        : { creationInput: root.creationInput }),
+                });
+                return {
+                    content,
+                    definition,
+                    nodeIdentity: root.nodeIdentity,
+                    createdBy: "initialization",
+                    configuration: normalizeConfiguration(content, root.configuration),
+                    ...(root.creationInput === undefined
+                        ? {}
+                        : { creationInput: root.creationInput }),
+                    providers: new Map(),
+                };
+            });
+            const nodes = expandDependencies({
+                roots,
+                existing: [],
+                context: prepared.context,
+                occupiedIds: new Set(),
+            });
+            const records = nodes.flatMap((node) => node.record === undefined ? [] : [node.record]);
+            const nodeInstances = Object.fromEntries(roots.map((root) => {
+                if (root.record === undefined) {
+                    throw new Error("显式初始化节点没有持久实例：" + root.nodeIdentity);
+                }
+                return [root.nodeIdentity, root.record.packageDefinitionId];
+            }));
+            const blueprint = assertProjectBlueprint({
+                schemaVersion: 3,
+                packages: nodes.map((node) => node.definition),
+            });
+            const packageStates = resolvePackageStates(records, blueprint);
+            validateRequiredBindings(packageStates);
+            validateNodeInstances(packageStates, nodeInstances);
+            const contributions = persistedContributions(nodes, prepared.context, packageStates, resolveNodeInstances(packageStates, nodeInstances));
+            const projectPlan = project(prepared.context, prepared.state, blueprint, packageStates, contributions, nodeInstances, presetSelections);
+            await materializeProjectProjection({
+                operations: projectPlan.operations,
+                reconciliation: projectPlan.reconciliation,
+            });
+            if (!initOptions.dryRun) {
+                try {
+                    await renderNewProject({
+                        targetRoot: path.resolve(initOptions.targetRoot),
+                        operations: [...projectPlan.operations],
+                    });
+                }
+                catch (error) {
+                    return fail("render", error);
+                }
+            }
+            return {
+                status: "success",
+                dryRun: initOptions.dryRun ?? false,
+                blueprint: projectPlan.blueprint,
+                generationRecord: projectPlan.generationRecord,
+                projection: projectPlan,
+                actions: [],
+            };
+        }
+        catch (error) {
+            return fail("planning", error);
+        }
+    }
+    async function restoreRepository(repositoryRoot) {
+        const blueprintValue = JSON.parse(await readFile(path.join(repositoryRoot, ".template/blueprint.json"), "utf8"));
+        const blueprint = assertProjectBlueprint(blueprintValue);
+        const record = parseGenerationRecord(JSON.parse(await readFile(path.join(repositoryRoot, ".template/generation.json"), "utf8")));
+        if (record.strategyIdentity !== options.strategy.identity) {
+            throw new Error("目标仓库使用了不兼容的工作区策略");
+        }
+        const state = options.strategy.parseState(record.strategyState);
+        const packageStates = resolvePackageStates(record.packages, blueprint);
+        validateNodeInstances(packageStates, record.nodeInstances);
+        validatePresetSelections(record.presetSelections);
+        return { blueprint, record, state, packageStates };
+    }
+    async function add(addOptions) {
+        try {
+            const repositoryRoot = path.resolve(addOptions.repositoryRoot);
+            let blueprint;
+            let record;
+            let packageStates;
+            let state;
+            try {
+                ({ blueprint, record, state, packageStates } =
+                    await restoreRepository(repositoryRoot));
+            }
+            catch (error) {
+                return fail("metadata", error, options.strategy.diagnoseFailure?.(error));
+            }
+            let requiredDependencies;
+            try {
+                for (const packageRecord of packageStates) {
+                    prepareContent(requireContent(packageRecord.contentIdentity));
+                }
+                requiredDependencies = requiredDependencyIdentities(packageStates);
+            }
+            catch (error) {
+                return fail("planning", error);
+            }
+            try {
+                validateRequiredBindings(packageStates, requiredDependencies);
+            }
+            catch (error) {
+                return fail("metadata", error, options.strategy.diagnoseFailure?.(error));
+            }
+            const additionRoots = "preset" in addOptions
+                ? expandPreset({
+                    preset: resolvePreset(addOptions.preset),
+                    operation: "add",
+                    configuration: addOptions.configuration,
+                    ...(addOptions.creationInput === undefined
+                        ? {}
+                        : { creationInput: addOptions.creationInput }),
+                })
+                : [
+                    {
+                        nodeIdentity: "addition",
+                        configuration: addOptions.configuration,
+                        contentIdentity: addOptions.contentIdentity,
+                        ...(addOptions.creationInput === undefined
+                            ? {}
+                            : { creationInput: addOptions.creationInput }),
+                    },
+                ];
+            if (additionRoots.length !== 1) {
+                throw new Error("加包预设必须恰好包含一个节点");
+            }
+            const selectionRoot = additionRoots[0];
+            if (selectionRoot === undefined) {
+                throw new Error("加包预设必须恰好包含一个节点");
+            }
+            const selected = requireContent(selectionRoot.contentIdentity);
+            const creationInput = selectionRoot.creationInput;
+            const configuration = normalizeConfiguration(selected, selectionRoot.configuration);
+            const addedPresetMember = "preset" in addOptions ? resolvePreset(addOptions.preset) : undefined;
+            const addedPreset = addedPresetMember === undefined
+                ? undefined
+                : selectedPreset(addedPresetMember);
+            const addedProjectPreset = addedPresetMember?.definition.project === undefined
+                ? undefined
+                : addedPreset;
+            const existingNodes = nodesFromRecords(packageStates);
+            const currentNodeInstances = resolveNodeInstances(packageStates, record.nodeInstances);
+            try {
+                prepareContent(selected);
+            }
+            catch (error) {
+                return fail("planning", error);
+            }
+            let context;
+            try {
+                context = await options.strategy.prepareUpdate({
+                    targetRoot: repositoryRoot,
+                    state,
+                    content: selected,
+                    contentByIdentity,
+                    configuration,
+                    packages: packageStates,
+                    nodeInstances: currentNodeInstances,
+                    ...(creationInput === undefined ? {} : { creationInput }),
+                });
+            }
+            catch (error) {
+                return fail("metadata", error, options.strategy.diagnoseFailure?.(error));
+            }
+            const existingContributions = existingNodes.map((node) => createContribution(node, context, packageStates, currentNodeInstances));
+            const definition = options.strategy.createDefinition({
+                context,
+                content: selected,
+                ...(selectionRoot.layout === undefined
+                    ? {}
+                    : { layout: selectionRoot.layout }),
+                ...(creationInput === undefined ? {} : { creationInput }),
+            });
+            const requested = {
+                content: selected,
+                definition,
+                createdBy: "addition",
+                configuration,
+                ...(addedProjectPreset !== undefined
+                    ? { nodeIdentity: selectionRoot.nodeIdentity }
+                    : {}),
+                ...(creationInput === undefined ? {} : { creationInput }),
+                providers: new Map(),
+            };
+            let preparedAddition;
+            const prepareAdditionNodes = () => {
+                if (preparedAddition !== undefined)
+                    return preparedAddition;
+                try {
+                    const nodes = expandDependencies({
+                        roots: [requested],
+                        existing: existingNodes,
+                        context,
+                        occupiedIds: new Set(record.packages.map((item) => item.packageDefinitionId)),
+                    });
+                    const records = nodes.flatMap((node) => node.record === undefined ? [] : [node.record]);
+                    const allRecords = [...record.packages, ...records];
+                    const afterBlueprint = {
+                        ...blueprint,
+                        packages: [
+                            ...blueprint.packages,
+                            ...nodes.map((node) => node.definition),
+                        ],
+                    };
+                    const packages = resolvePackageStates(allRecords, afterBlueprint);
+                    const addedPackageIds = new Set(records.map((item) => item.packageDefinitionId));
+                    const addedPackages = packages.filter((item) => addedPackageIds.has(item.packageDefinitionId));
+                    validateRequiredBindings(addedPackages, requiredDependencyIdentities(addedPackages), packages);
+                    const nodeInstanceIds = {
+                        ...record.nodeInstances,
+                    };
+                    if (addedProjectPreset !== undefined &&
+                        !Object.hasOwn(nodeInstanceIds, selectionRoot.nodeIdentity)) {
+                        const addedRoot = nodes.find((node) => node.nodeIdentity === selectionRoot.nodeIdentity);
+                        if (addedRoot?.record === undefined) {
+                            throw new Error("加包预设节点没有持久实例：" + selectionRoot.nodeIdentity);
+                        }
+                        nodeInstanceIds[selectionRoot.nodeIdentity] =
+                            addedRoot.record.packageDefinitionId;
+                    }
+                    const nodeInstances = resolveNodeInstances(packages, nodeInstanceIds);
+                    preparedAddition = {
+                        nodes,
+                        records,
+                        packages,
+                        blueprint: afterBlueprint,
+                        nodeInstances,
+                        contributions: persistedContributions(nodes, context, packages, nodeInstances),
+                    };
+                    return preparedAddition;
+                }
+                catch (error) {
+                    throw new AdditionPlanningFailure(error);
+                }
+            };
+            try {
+                await validatePresetUpdate(repositoryRoot, context, existingContributions, currentNodeInstances, record.presetSelections);
+                const currentPresetProjectContributions = computePresetProjectContributions(context, existingContributions, currentNodeInstances, record.presetSelections);
+                const validation = await options.strategy.validateAddition?.({
+                    targetRoot: repositoryRoot,
+                    blueprint,
+                    content: selected,
+                    definition,
+                    ...(creationInput === undefined ? {} : { creationInput }),
+                    packages: packageStates,
+                    contributions: existingContributions,
+                    getAdditionContributions: () => prepareAdditionNodes().contributions,
+                    nodeInstances: currentNodeInstances,
+                    presetProjectContributions: currentPresetProjectContributions,
+                });
+                if (validation?.status === "input-invalid")
+                    return validation;
+                if (validation?.status === "conflict") {
+                    return {
+                        status: "conflict",
+                        dryRun: addOptions.dryRun ?? false,
+                        reason: "工作区策略报告了包加法冲突。",
+                        conflicts: [],
+                        ownerConflict: validation.conflict,
+                        actions: [],
+                    };
+                }
+            }
+            catch (error) {
+                if (error instanceof AdditionPlanningFailure) {
+                    return fail("planning", error);
+                }
+                return fail("metadata", error, options.strategy.diagnoseFailure?.(error));
+            }
+            const conflicting = blueprint.packages.find((candidate) => candidate.name === definition.name ||
+                candidate.path === definition.path);
+            if (conflicting !== undefined) {
+                const prior = packageStates.find((item) => item.packageDefinitionId === conflicting.packageDefinitionId);
+                if (prior !== undefined &&
+                    contentIdentityKey(prior.contentIdentity) ===
+                        contentIdentityKey(selected.identity) &&
+                    prior.definition.name === definition.name &&
+                    prior.definition.path === definition.path &&
+                    isDeepStrictEqual(prior.configuration, configuration) &&
+                    isDeepStrictEqual(prior.creationInput ?? undefined, selectionRoot.creationInput)) {
+                    return {
+                        status: "success",
+                        dryRun: addOptions.dryRun ?? false,
+                        blueprint,
+                        generationRecord: record,
+                        projection: null,
+                        actions: [],
+                    };
+                }
+                const samePackageIdentity = prior !== undefined &&
+                    contentIdentityKey(prior.contentIdentity) ===
+                        contentIdentityKey(selected.identity) &&
+                    prior.definition.name === definition.name &&
+                    prior.definition.path === definition.path;
+                return {
+                    status: "conflict",
+                    dryRun: addOptions.dryRun ?? false,
+                    reason: samePackageIdentity
+                        ? "已存在的包实例不能接受不同的加包输入。"
+                        : "目标包名称或路径已被其他实例占用。",
+                    conflicts: [],
+                    identityConflict: {
+                        existing: packageIdentity(conflicting),
+                        requested: packageIdentity(definition),
+                    },
+                    actions: [],
+                };
+            }
+            const prepared = prepareAdditionNodes();
+            const additions = prepared.nodes;
+            const allRecords = prepared.packages;
+            const afterBlueprint = assertProjectBlueprint(prepared.blueprint);
+            const afterNodeInstanceIds = {
+                ...record.nodeInstances,
+            };
+            if (addedProjectPreset !== undefined) {
+                if (Object.hasOwn(record.nodeInstances, selectionRoot.nodeIdentity)) {
+                    throw new Error("加包预设节点身份已存在：" + selectionRoot.nodeIdentity);
+                }
+                const addedRoot = additions.find((node) => node.nodeIdentity === selectionRoot.nodeIdentity);
+                if (addedRoot?.record === undefined) {
+                    throw new Error("加包预设节点没有持久实例：" + selectionRoot.nodeIdentity);
+                }
+                afterNodeInstanceIds[selectionRoot.nodeIdentity] =
+                    addedRoot.record.packageDefinitionId;
+            }
+            const afterPresetSelections = mergePresetSelections(record.presetSelections, addedPreset === undefined ? [] : [addedPreset]);
+            const beforeContributions = persistedContributions(existingNodes, context, packageStates, currentNodeInstances);
+            const afterNodes = [...existingNodes, ...additions];
+            const afterContributions = persistedContributions(afterNodes, context, allRecords, resolveNodeInstances(allRecords, afterNodeInstanceIds));
+            const before = project(context, state, blueprint, packageStates, beforeContributions, record.nodeInstances, record.presetSelections);
+            const after = project(context, state, afterBlueprint, allRecords, afterContributions, afterNodeInstanceIds, afterPresetSelections);
+            const projectedBlueprint = after.blueprint;
+            const preconditions = additions.map((node) => ({
+                path: node.definition.path,
+                kind: "must-not-exist",
+                reason: "新包路径已存在：" + node.definition.path,
+            }));
+            const reconciliation = await reconcileAndApplyProjectProjections({
+                targetRoot: repositoryRoot,
+                before: {
+                    operations: before.operations,
+                    reconciliation: before.reconciliation,
+                },
+                after: {
+                    operations: after.operations,
+                    reconciliation: after.reconciliation,
+                },
+                preconditions,
+                ...(addOptions.dryRun === undefined
+                    ? {}
+                    : { dryRun: addOptions.dryRun }),
+            });
+            if (!reconciliation.ok) {
+                return {
+                    status: "conflict",
+                    dryRun: addOptions.dryRun ?? false,
+                    reason: "目标工作区的现行内容与新增投影发生冲突。",
+                    conflicts: reconciliation.conflicts,
+                    actions: [],
+                };
+            }
+            return {
+                status: "success",
+                dryRun: addOptions.dryRun ?? false,
+                blueprint: projectedBlueprint,
+                generationRecord: after.generationRecord,
+                projection: after,
+                actions: reconciliation.actions,
+            };
+        }
+        catch (error) {
+            return fail(error instanceof AdditionPlanningFailure
+                ? "planning"
+                : "reconciliation", error);
+        }
+    }
+    async function configure(configureOptions) {
+        const repositoryRoot = path.resolve(configureOptions.repositoryRoot);
+        let restored;
+        try {
+            restored = await restoreRepository(repositoryRoot);
+        }
+        catch (error) {
+            return fail("metadata", error, options.strategy.diagnoseFailure?.(error));
+        }
+        const { blueprint, record, state, packageStates } = restored;
+        const target = packageStates.find((item) => item.packageDefinitionId === configureOptions.packageDefinitionId);
+        if (target === undefined)
+            return {
+                status: "input-invalid",
+                issues: [{ code: "UNKNOWN_GENERATED_INSTANCE" }],
+            };
+        try {
+            for (const item of packageStates)
+                prepareContent(requireContent(item.contentIdentity));
+            validateRequiredBindings(packageStates);
+        }
+        catch (error) {
+            return fail("metadata", error, options.strategy.diagnoseFailure?.(error));
+        }
+        let phase = "planning";
+        try {
+            const selected = requireContent(target.contentIdentity);
+            const configuration = normalizeConfiguration(selected, configureOptions.configuration);
+            if (isDeepStrictEqual(target.configuration, configuration)) {
+                return {
+                    status: "success",
+                    dryRun: configureOptions.dryRun ?? false,
+                    blueprint,
+                    generationRecord: record,
+                    projection: null,
+                    actions: [],
+                };
+            }
+            const currentNodeInstances = resolveNodeInstances(packageStates, record.nodeInstances);
+            const context = await options.strategy.prepareUpdate({
+                targetRoot: repositoryRoot,
+                state,
+                content: selected,
+                contentByIdentity,
+                configuration,
+                packages: packageStates,
+                nodeInstances: currentNodeInstances,
+                ...(target.creationInput === null
+                    ? {}
+                    : { creationInput: target.creationInput }),
+            });
+            const beforeNodes = nodesFromRecords(packageStates);
+            const beforeContributions = persistedContributions(beforeNodes, context, packageStates, currentNodeInstances);
+            await validatePresetUpdate(repositoryRoot, context, beforeContributions, currentNodeInstances, record.presetSelections);
+            const before = project(context, state, blueprint, packageStates, beforeContributions, record.nodeInstances, record.presetSelections);
+            const afterNodes = nodesFromRecords(packageStates.map((item) => item.packageDefinitionId === target.packageDefinitionId
+                ? { ...item, configuration }
+                : item));
+            const changed = afterNodes.find((node) => node.record?.packageDefinitionId === target.packageDefinitionId);
+            const additions = expandDependencies({
+                roots: [changed],
+                existing: afterNodes,
+                context,
+                occupiedIds: new Set(record.packages.map((item) => item.packageDefinitionId)),
+            });
+            const allNodes = [...afterNodes, ...additions];
+            const afterBlueprint = assertProjectBlueprint({
+                ...blueprint,
+                packages: [
+                    ...blueprint.packages,
+                    ...additions.map((node) => node.definition),
+                ],
+            });
+            const afterPackages = resolvePackageStates(allNodes.map((node) => node.record), afterBlueprint);
+            validateRequiredBindings(afterPackages);
+            const afterNodeInstances = resolveNodeInstances(afterPackages, record.nodeInstances);
+            const after = project(context, state, afterBlueprint, afterPackages, persistedContributions(allNodes, context, afterPackages, afterNodeInstances), record.nodeInstances, record.presetSelections);
+            phase = "reconciliation";
+            const reconciliation = await reconcileAndApplyProjectProjections({
+                targetRoot: repositoryRoot,
+                before: {
+                    operations: before.operations,
+                    reconciliation: before.reconciliation,
+                },
+                after: {
+                    operations: after.operations,
+                    reconciliation: after.reconciliation,
+                },
+                preconditions: additions.map((node) => ({
+                    path: node.definition.path,
+                    kind: "must-not-exist",
+                    reason: "新共享依赖路径已存在：" + node.definition.path,
+                })),
+                ...(configureOptions.dryRun === undefined
+                    ? {}
+                    : { dryRun: configureOptions.dryRun }),
+            });
+            if (!reconciliation.ok)
+                return {
+                    status: "conflict",
+                    dryRun: configureOptions.dryRun ?? false,
+                    reason: "目标工作区的现行内容与配置投影发生冲突。",
+                    conflicts: reconciliation.conflicts,
+                    actions: [],
+                };
+            return {
+                status: "success",
+                dryRun: configureOptions.dryRun ?? false,
+                blueprint: after.blueprint,
+                generationRecord: after.generationRecord,
+                projection: after,
+                actions: reconciliation.actions,
+            };
+        }
+        catch (error) {
+            return fail(phase, error, options.strategy.diagnoseFailure?.(error));
+        }
+    }
+    return { init, add, configure };
+}