@empire-builder-kit/nx 1.0.0-beta.9 → 1.0.0-rc.2

package/src/generators/upgrade/upgrade.js

@@ -1,24 +1,438 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeveloperAgentUpgradePreviewBindingError = void 0;
+exports.developerAgentUpgradeExecutionOptions = developerAgentUpgradeExecutionOptions;
 exports.preserveCompositionRegions = preserveCompositionRegions;
+exports.inspectWorkspaceSstVersion = inspectWorkspaceSstVersion;
 exports.createUpgradeReport = createUpgradeReport;
 exports.upgradeGenerator = upgradeGenerator;
+const deterministic_order_js_1 = require("../../deterministic-order.js");
 const devkit_1 = require("@nx/devkit");
+const node_buffer_1 = require("node:buffer");
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
+const node_util_1 = require("node:util");
 const prettier_1 = require("prettier");
+const yaml_1 = require("yaml");
 const index_js_1 = require("../../blueprints/index.js");
-const index_js_2 = require("../../foundation/index.js");
-const index_js_3 = require("../../ownership/index.js");
+const index_js_2 = require("../../api-contract/index.js");
+const index_js_3 = require("../../foundation/index.js");
+const index_js_4 = require("../../ownership/index.js");
 const function_js_1 = require("../function/function.js");
+const feature_registry_js_1 = require("../feature-registry.js");
 const generator_js_1 = require("../preset/generator.js");
+const tool_versions_js_1 = require("../preset/tool-versions.js");
 const workspace_files_js_1 = require("../preset/workspace-files.js");
-const slice_js_1 = require("../slice/slice.js");
+const built_in_plan_js_1 = require("../slice/built-in-plan.js");
 const workload_js_1 = require("../workload/workload.js");
+const git_inspection_js_1 = require("../../developer-agent/git-inspection.js");
+const context_js_1 = require("../../developer-agent/context.js");
+const model_js_1 = require("../../developer-agent/model.js");
+const preview_source_js_1 = require("../../developer-agent/preview-source.js");
+const preview_changes_js_1 = require("../../developer-agent/preview-changes.js");
+const validation_js_1 = require("../../developer-agent/validation.js");
+function requireTargetCompositionFeatures(files, ownership) {
+    if (ownership.compositions.length === 0)
+        return;
+    const source = files.get(feature_registry_js_1.SLICE_FEATURE_REGISTRY_PATH);
+    if (source === undefined) {
+        throw new Error(`Target Product Slice is missing ${feature_registry_js_1.SLICE_FEATURE_REGISTRY_PATH} required by retained composition ownership.`);
+    }
+    let value;
+    try {
+        value = JSON.parse(source);
+    }
+    catch {
+        throw new Error(`Target Product Slice feature registry at ${feature_registry_js_1.SLICE_FEATURE_REGISTRY_PATH} must be valid JSON.`);
+    }
+    const registry = (0, feature_registry_js_1.parseSliceFeatureRegistry)(value, `Target Product Slice feature registry at ${feature_registry_js_1.SLICE_FEATURE_REGISTRY_PATH}`);
+    const registered = new Set(registry.features.map(({ id }) => id));
+    for (const composition of ownership.compositions) {
+        if (!registered.has(composition.feature)) {
+            throw new Error(`Target Product Slice feature registry does not register retained composition feature "${composition.feature}" for ${composition.kind} ${composition.name}.`);
+        }
+    }
+}
+function developerAgentUpgradeExecutionOptions(options = {}) {
+    return {
+        ...options,
+        externalBlueprintDiagnostics: 'suppress',
+    };
+}
+const DEVELOPER_AGENT_PREVIEW_REFERENCE = /^\.ebk\/agent\/previews\/[a-z][a-z0-9-]{0,62}\.json$/;
+const SHA256_DIGEST = /^sha256:[a-f0-9]{64}$/;
+const PREVIEW_BINDING_FAILURE = 'Developer-Agent Upgrade preview binding does not match the current exact mutation candidate.';
+class DeveloperAgentUpgradePreviewBindingError extends Error {
+    classification = 'generated-drift';
+    constructor() {
+        super(PREVIEW_BINDING_FAILURE);
+        this.name = 'DeveloperAgentUpgradePreviewBindingError';
+    }
+}
+exports.DeveloperAgentUpgradePreviewBindingError = DeveloperAgentUpgradePreviewBindingError;
+function previewBindingFailure() {
+    throw new DeveloperAgentUpgradePreviewBindingError();
+}
+function developerAgentPreviewBlueprintReference(preview) {
+    if (preview.input.name === 'workspace' ||
+        preview.input.name === 'foundation') {
+        return undefined;
+    }
+    const states = preview.source.ownershipVersions.filter(({ kind, target }) => kind === 'slice' && target === preview.input.name);
+    const state = states[0];
+    if (states.length !== 1 ||
+        !state?.blueprintName ||
+        !state.installedBlueprintVersion) {
+        return previewBindingFailure();
+    }
+    return state.blueprintName === index_js_1.BUILTIN_BLUEPRINT_NAME
+        ? index_js_1.BUILTIN_BLUEPRINT_REFERENCE
+        : `${state.blueprintName}@${state.installedBlueprintVersion}`;
+}
+function readDeveloperAgentPreviewFile(workspaceRoot, reference) {
+    try {
+        if (!DEVELOPER_AGENT_PREVIEW_REFERENCE.test(reference)) {
+            return previewBindingFailure();
+        }
+        const root = (0, node_fs_1.realpathSync)(workspaceRoot);
+        const absolute = (0, node_path_1.resolve)(root, ...reference.split('/'));
+        const fromRoot = (0, node_path_1.relative)(root, absolute);
+        if (fromRoot === '' ||
+            fromRoot === '..' ||
+            fromRoot.startsWith(`..${node_path_1.sep}`) ||
+            (0, node_path_1.isAbsolute)(fromRoot)) {
+            return previewBindingFailure();
+        }
+        const entry = (0, node_fs_1.lstatSync)(absolute);
+        if (!entry.isFile() || entry.isSymbolicLink()) {
+            return previewBindingFailure();
+        }
+        const real = (0, node_fs_1.realpathSync)(absolute);
+        const realFromRoot = (0, node_path_1.relative)(root, real);
+        if (realFromRoot === '..' ||
+            realFromRoot.startsWith(`..${node_path_1.sep}`) ||
+            (0, node_path_1.isAbsolute)(realFromRoot)) {
+            return previewBindingFailure();
+        }
+        const descriptor = (0, node_fs_1.openSync)(real, node_fs_1.constants.O_RDONLY | (node_fs_1.constants.O_NOFOLLOW ?? 0));
+        try {
+            const before = (0, node_fs_1.fstatSync)(descriptor);
+            const currentUser = typeof process.getuid === 'function' ? process.getuid() : undefined;
+            if (!before.isFile() ||
+                before.size > model_js_1.DEVELOPER_AGENT_GENERATOR_PREVIEW_RECEIPT_MAX_BYTES ||
+                (process.platform !== 'win32' &&
+                    ((currentUser !== undefined && before.uid !== currentUser) ||
+                        (before.mode & 0o077) !== 0))) {
+                return previewBindingFailure();
+            }
+            const bytes = node_buffer_1.Buffer.alloc(before.size);
+            let offset = 0;
+            while (offset < bytes.length) {
+                const count = (0, node_fs_1.readSync)(descriptor, bytes, offset, bytes.length - offset, offset);
+                if (count === 0)
+                    break;
+                offset += count;
+            }
+            const after = (0, node_fs_1.fstatSync)(descriptor);
+            if (offset !== bytes.length ||
+                after.dev !== before.dev ||
+                after.ino !== before.ino ||
+                after.size !== before.size ||
+                after.mtimeMs !== before.mtimeMs ||
+                after.ctimeMs !== before.ctimeMs) {
+                return previewBindingFailure();
+            }
+            const parsed = JSON.parse(bytes.toString('utf8'));
+            const validation = (0, validation_js_1.validateDeveloperAgentGeneratorPreview)(parsed);
+            if (!validation.valid)
+                return previewBindingFailure();
+            return {
+                digest: `sha256:${(0, node_crypto_1.createHash)('sha256').update(bytes).digest('hex')}`,
+                preview: validation.value,
+            };
+        }
+        finally {
+            (0, node_fs_1.closeSync)(descriptor);
+        }
+    }
+    catch (error) {
+        if (error instanceof DeveloperAgentUpgradePreviewBindingError)
+            throw error;
+        return previewBindingFailure();
+    }
+}
+async function requireDeveloperAgentPreviewBinding(tree, options, executionOptions) {
+    const reference = options.developerAgentPreview;
+    const digest = options.developerAgentPreviewDigest;
+    if (reference === undefined && digest === undefined)
+        return undefined;
+    if (reference === undefined ||
+        digest === undefined ||
+        !SHA256_DIGEST.test(digest) ||
+        options.apply !== true ||
+        options.skipFormat !== true ||
+        options.skipInstall !== true) {
+        return previewBindingFailure();
+    }
+    const previewFile = readDeveloperAgentPreviewFile(tree.root, reference);
+    const { preview } = previewFile;
+    const expectedBlueprint = developerAgentPreviewBlueprintReference(preview);
+    const packageJsonSource = tree.read('package.json', 'utf8');
+    if (packageJsonSource === null)
+        return previewBindingFailure();
+    let packageJson;
+    try {
+        packageJson = JSON.parse(packageJsonSource);
+    }
+    catch {
+        return previewBindingFailure();
+    }
+    const git = await (0, git_inspection_js_1.inspectDeveloperAgentGit)({ cwd: (0, node_fs_1.realpathSync)(tree.root) });
+    if (previewFile.digest !== digest ||
+        preview.input.name !== options.name ||
+        options.blueprint !== expectedBlueprint ||
+        options.inputs !== undefined ||
+        preview.source.commit !== git.worktree.commit ||
+        git.worktree.dirtyPaths.length > 0 ||
+        !packageJson ||
+        typeof packageJson !== 'object' ||
+        Array.isArray(packageJson) ||
+        packageJson.name !== preview.source.workspace ||
+        preview.source.frameworkVersion !== (0, generator_js_1.frameworkPackageVersion)()) {
+        return previewBindingFailure();
+    }
+    await assertCurrentDeveloperAgentPreviewSource(tree.root, preview, executionOptions);
+    return previewFile;
+}
+async function inspectCurrentDeveloperAgentPreviewSource(workspaceRoot, preview) {
+    const target = preview.input.name;
+    const context = await (0, context_js_1.inspectDeveloperAgentContext)(workspaceRoot, {
+        ...(preview.source.candidateProvenance
+            ? {
+                candidateProvenancePath: preview.source.candidateProvenance.reference,
+            }
+            : {}),
+        ...(target === 'workspace'
+            ? {}
+            : target === 'foundation'
+                ? { selectedProjects: ['foundation'] }
+                : {
+                    selectedProjects: ['foundation', target].sort(),
+                    selectedSlice: target,
+                }),
+    });
+    if (context.git.dirty ||
+        context.warnings.some(({ classification }) => classification === 'stale-base')) {
+        return previewBindingFailure();
+    }
+    return (0, preview_source_js_1.developerAgentGeneratorPreviewSource)(context);
+}
+async function assertCurrentDeveloperAgentPreviewSource(workspaceRoot, preview, executionOptions) {
+    try {
+        const current = await (executionOptions.inspectDeveloperAgentPreviewSource ??
+            inspectCurrentDeveloperAgentPreviewSource)(workspaceRoot, preview);
+        if (!(0, node_util_1.isDeepStrictEqual)(current, preview.source)) {
+            return previewBindingFailure();
+        }
+    }
+    catch (error) {
+        if (error instanceof DeveloperAgentUpgradePreviewBindingError)
+            throw error;
+        return previewBindingFailure();
+    }
+}
+const SEEDED_RECONCILIATION = {
+    'async/recovery-adapters.ts': {
+        category: 'async-adapter',
+        implications: [
+            'failure-semantics',
+            'provider-behavior',
+            'provider-permissions',
+        ],
+    },
+    'async/runtime.ts': {
+        category: 'async-settings',
+        implications: [
+            'retry-and-dlq-settings',
+            'schedule-contracts',
+            'workflow-contracts',
+        ],
+    },
+    'async/webhook.ts': {
+        category: 'async-adapter',
+        implications: [
+            'provider-authentication',
+            'provider-behavior',
+            'webhook-replay-protection',
+        ],
+    },
+    'async/work-contract.json': {
+        category: 'async-settings',
+        implications: [
+            'recovery-authority',
+            'retry-and-dlq-settings',
+            'workflow-versioning',
+        ],
+    },
+    'configuration/declarations.json': {
+        category: 'configuration-contract',
+        implications: [
+            'configuration-types',
+            'outage-policy',
+            'provider-permissions',
+        ],
+    },
+    'configuration/declarations.ts': {
+        category: 'configuration-contract',
+        implications: [
+            'configuration-types',
+            'outage-policy',
+            'provider-permissions',
+        ],
+    },
+    'configuration/local-values.json': {
+        category: 'configuration-values',
+        implications: ['local-defaults', 'safe-fallbacks'],
+    },
+    'docs/reliability/slo.json': {
+        category: 'reliability-slo',
+        implications: [
+            'error-budget-policy',
+            'journey-ownership',
+            'service-level-objectives',
+        ],
+    },
+    'frontend/contract.json': {
+        category: 'frontend-contract',
+        implications: [
+            'accessibility-proof',
+            'browser-security-boundary',
+            'public-configuration',
+        ],
+    },
+    'frontend/security-headers.json': {
+        category: 'frontend-security',
+        implications: [
+            'content-security-policy',
+            'response-header-ownership',
+            'transport-profile',
+        ],
+    },
+    'operations/features.json': {
+        category: 'feature-controls',
+        implications: ['flag-lifecycle', 'owners', 'stop-conditions'],
+    },
+    'operations/reliability.json': {
+        category: 'reliability-operations',
+        implications: [
+            'alarm-registration',
+            'diagnostic-authority',
+            'incident-remediation',
+        ],
+    },
+    'operations/release.json': {
+        category: 'release-controls',
+        implications: [
+            'artifact-inventory',
+            'compatibility-sequence',
+            'rollout-controls',
+        ],
+    },
+    'performance/aggregate-count-provider.ts': {
+        category: 'performance-aggregate-provider',
+        implications: [
+            'aggregate-source-authority',
+            'business-capability-counts',
+            'provider-data-access',
+        ],
+    },
+    'performance/policy.json': {
+        category: 'performance-policy',
+        implications: [
+            'capacity-and-load-settings',
+            'cost-budgets',
+            'journey-authority',
+        ],
+    },
+};
+const SEEDED_RECONCILIATION_MARKER_REFERENCE = 'PLAN:5.6/seeded-upgrade-reconciliation';
+const SEEDED_RECONCILIATION_MARKER = '// EBK-TODO(PLAN:5.6/seeded-upgrade-reconciliation): Review retained seeded async, configuration, feature, frontend, performance, reliability, and release decisions against this framework upgrade before protected promotion.';
+const SEEDED_RECONCILIATION_MARKER_ANCHOR = 'async/recovery-adapters.ts';
+const DEVELOPER_AGENT_AGENTS_HEADING = '## Developer-Agent workflow';
+function developerAgentAgentsAppendix(renderedAgents) {
+    if (renderedAgents === undefined) {
+        throw new Error('Target workspace did not render AGENTS.md.');
+    }
+    const marker = `\n${DEVELOPER_AGENT_AGENTS_HEADING}\n`;
+    const start = renderedAgents.indexOf(marker);
+    if (start < 0 || renderedAgents.indexOf(marker, start + marker.length) >= 0) {
+        throw new Error('Target AGENTS.md must contain one Developer-Agent workflow section.');
+    }
+    return renderedAgents.slice(start + 1);
+}
+function planDeveloperAgentInstructionAppend(currentAgents, targetAgents) {
+    if (currentAgents === null ||
+        new RegExp(`(?:^|\\r?\\n)${DEVELOPER_AGENT_AGENTS_HEADING}(?:\\r?\\n|$)`).test(currentAgents)) {
+        return null;
+    }
+    const appendix = developerAgentAgentsAppendix(targetAgents);
+    const separator = currentAgents.length === 0
+        ? ''
+        : currentAgents.endsWith('\n\n')
+            ? ''
+            : currentAgents.endsWith('\n')
+                ? '\n'
+                : '\n\n';
+    return {
+        contents: `${currentAgents}${separator}${appendix}`,
+        path: 'AGENTS.md',
+    };
+}
+function seededReconciliationDefinition(path) {
+    return Object.prototype.hasOwnProperty.call(SEEDED_RECONCILIATION, path)
+        ? SEEDED_RECONCILIATION[path]
+        : null;
+}
+function appendSeededReconciliationMarker(tree, root, report) {
+    if (report.seededReconciliation.length === 0)
+        return;
+    const anchor = node_path_1.posix.join(root, SEEDED_RECONCILIATION_MARKER_ANCHOR);
+    const current = tree.read(anchor, 'utf8');
+    if (current === null) {
+        throw new Error(`Seeded reconciliation requires deterministic anchor ${anchor}.`);
+    }
+    if (current.includes(SEEDED_RECONCILIATION_MARKER_REFERENCE))
+        return;
+    tree.write(anchor, `${current.replace(/\s*$/, '')}\n\n${SEEDED_RECONCILIATION_MARKER}\n`);
+}
+function currentContractConsumers(tree, root) {
+    const source = tree.read(node_path_1.posix.join(root, 'contracts/dependencies.json'), 'utf8');
+    if (source === null)
+        return [];
+    const declaration = JSON.parse(source);
+    if (declaration.schemaVersion !== 1 || !Array.isArray(declaration.consumes)) {
+        throw new Error(`${root}/contracts/dependencies.json must be a v1 consumes declaration before upgrade.`);
+    }
+    return [
+        ...((0, index_js_2.normalizeApiContractProjectDeclarations)([
+            {
+                contracts: {
+                    consumes: declaration.consumes,
+                    publishes: [],
+                },
+                project: root.slice(root.lastIndexOf('/') + 1),
+            },
+        ])[0]?.contracts.consumes ?? []),
+    ];
+}
 const COMPOSITION_REGIONS = [
     'composition-imports',
     'workload-registrations',
     'function-registrations',
     'composition-outputs',
+    'workload-role-extensions',
+    'workload-role-intent-contributions',
 ];
 function preserveCompositionRegions(current, target) {
     let merged = target;
@@ -53,13 +467,27 @@ function upgradeConflictMessage(label, report) {
     ];
     return `${label} upgrade has user-modified managed files or unsafe JSON ownership changes:\n${report.conflicting.map((path) => `- ${path}`).join('\n')}${ownershipDetails.length > 0 ? `\n${ownershipDetails.join('\n')}` : ''}\nResolve or restore them before applying the upgrade.`;
 }
+function seededMigrationUpgradeMessage(label, report) {
+    return `${label} upgrade cannot rewrite an existing seeded database migration:\n${report.incompatibleSeededMigrations.map((path) => `- ${path}`).join('\n')}\nRegenerate this prerelease workspace instead. Stable-v1 upgrades must add a new migration rather than rewrite migration history.`;
+}
 async function formatRenderedFiles(files, prefix = '') {
+    const canonicalApiArtifacts = new Set([
+        'api/generated/baseline.json',
+        'api/generated/contract.json',
+        'api/generated/openapi.json',
+    ]);
     return Object.fromEntries(await Promise.all(Object.entries(files).map(async ([path, contents]) => {
+        const workspacePath = node_path_1.posix.join(prefix, path);
+        if (canonicalApiArtifacts.has(path) ||
+            (0, workspace_files_js_1.isRawWorkspaceAuthorityPath)(workspacePath) ||
+            path.startsWith('database/migrations/')) {
+            return [path, contents];
+        }
         try {
             return [
                 path,
                 await (0, prettier_1.format)(contents, {
-                    filepath: node_path_1.posix.join(prefix, path),
+                    filepath: workspacePath,
                     singleQuote: true,
                 }),
             ];
@@ -80,6 +508,85 @@ function readJson(tree, path, label) {
         throw new Error(`${label} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
+function objectMember(value, member) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return undefined;
+    }
+    const candidate = value[member];
+    return typeof candidate === 'object' &&
+        candidate !== null &&
+        !Array.isArray(candidate)
+        ? candidate
+        : undefined;
+}
+function stringMember(value, member) {
+    const candidate = value?.[member];
+    return typeof candidate === 'string' ? candidate : null;
+}
+function inspectWorkspaceSstVersion(tree, packageJson) {
+    const remediation = `pnpm add --workspace-root --save-dev --save-exact sst@${tool_versions_js_1.WORKSPACE_SST_VERSION}`;
+    const dependencyVersion = packageJson.dependencies?.sst;
+    const developmentVersion = packageJson.devDependencies?.sst;
+    const declaredVersion = developmentVersion ?? dependencyVersion ?? null;
+    const issues = [];
+    if (dependencyVersion !== undefined) {
+        issues.push('package.json must declare SST in devDependencies only');
+    }
+    if (developmentVersion !== tool_versions_js_1.WORKSPACE_SST_VERSION) {
+        issues.push(`package.json devDependencies.sst is ${developmentVersion ?? 'missing'}`);
+    }
+    let lockSpecifier = null;
+    let lockVersion = null;
+    let lockIntegrity = null;
+    const lockContents = tree.read('pnpm-lock.yaml', 'utf8');
+    if (lockContents === null) {
+        issues.push('pnpm-lock.yaml is missing');
+    }
+    else {
+        try {
+            const lock = (0, yaml_1.parse)(lockContents);
+            const rootImporter = objectMember(objectMember(lock, 'importers'), '.');
+            const rootDependencies = objectMember(rootImporter, 'dependencies');
+            const rootDevelopmentDependencies = objectMember(rootImporter, 'devDependencies');
+            const dependencyEntry = objectMember(rootDependencies, 'sst');
+            const developmentEntry = objectMember(rootDevelopmentDependencies, 'sst');
+            const lockEntry = developmentEntry ?? dependencyEntry;
+            lockSpecifier = stringMember(lockEntry, 'specifier');
+            lockVersion = stringMember(lockEntry, 'version');
+            const packageEntry = objectMember(objectMember(lock, 'packages'), `sst@${tool_versions_js_1.WORKSPACE_SST_VERSION}`);
+            lockIntegrity = stringMember(objectMember(packageEntry, 'resolution'), 'integrity');
+            if (dependencyEntry !== undefined) {
+                issues.push('pnpm-lock.yaml must resolve SST from devDependencies only');
+            }
+            if (lockSpecifier !== tool_versions_js_1.WORKSPACE_SST_VERSION) {
+                issues.push(`pnpm-lock.yaml SST specifier is ${lockSpecifier ?? 'missing'}`);
+            }
+            if (lockVersion !== tool_versions_js_1.WORKSPACE_SST_VERSION) {
+                issues.push(`pnpm-lock.yaml SST resolution is ${lockVersion ?? 'missing'}`);
+            }
+            if (lockIntegrity !== tool_versions_js_1.WORKSPACE_SST_NPM_INTEGRITY) {
+                issues.push(`pnpm-lock.yaml SST integrity is ${lockIntegrity ?? 'missing'}`);
+            }
+        }
+        catch (error) {
+            issues.push(`pnpm-lock.yaml is not valid YAML: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return {
+        classification: issues.length === 0 ? 'sst-version-current' : 'sst-version-drift',
+        declaredVersion,
+        expectedIntegrity: tool_versions_js_1.WORKSPACE_SST_NPM_INTEGRITY,
+        expectedVersion: tool_versions_js_1.WORKSPACE_SST_VERSION,
+        issues,
+        lockIntegrity,
+        lockSpecifier,
+        lockVersion,
+        remediation,
+    };
+}
+function workspaceSstVersionDriftMessage(state) {
+    return `[ebk-upgrade] ${state.classification}: workspace upgrades require the exact audited SST ${state.expectedVersion} manifest and lock resolution before framework ownership can be restamped.\n${state.issues.map((issue) => `- ${issue}`).join('\n')}\nRemediation: ${state.remediation}`;
+}
 function ownershipValidationMessage(label, issues) {
     const details = issues
         .map((issue) => `- ${issue.path}: ${issue.message}`)
@@ -91,7 +598,7 @@ function ownershipValidationMessage(label, issues) {
 }
 function requireUpgradePrerequisites(tree, target) {
     const installedVersion = (0, generator_js_1.frameworkPackageVersion)();
-    const workspaceResult = (0, index_js_3.validateWorkspaceOwnershipRecord)(readJson(tree, '.ebk/ownership.json', 'Workspace ownership metadata'));
+    const workspaceResult = (0, index_js_4.validateWorkspaceOwnershipRecord)(readJson(tree, '.ebk/ownership.json', 'Workspace ownership metadata'));
     if (!workspaceResult.valid) {
         throw new Error(ownershipValidationMessage('Workspace ownership metadata', workspaceResult.issues));
     }
@@ -100,7 +607,7 @@ function requireUpgradePrerequisites(tree, target) {
     }
     if (target === 'foundation')
         return;
-    const foundationResult = (0, index_js_3.validateFoundationOwnershipRecord)(readJson(tree, 'packages/foundation/.ebk/ownership.json', 'Standard Foundation ownership metadata'));
+    const foundationResult = (0, index_js_4.validateFoundationOwnershipRecord)(readJson(tree, 'packages/foundation/.ebk/ownership.json', 'Standard Foundation ownership metadata'));
     if (!foundationResult.valid) {
         throw new Error(ownershipValidationMessage('Standard Foundation ownership metadata', foundationResult.issues));
     }
@@ -156,7 +663,7 @@ Compatible target line: ${current.name}@${transition.compatibilityLine}
 Reason: ${reason}
 ${declarations.length > 0 ? `Available target declarations:\n${declarations.join('\n')}\n` : ''}No Blueprint files were rendered or changed. Keep using an exact compatible-line target, or create a reviewed replacement Product Slice with publisher guidance.`;
 }
-function gateBreakingBlueprintTransition(current, blueprint, apply) {
+function gateBreakingBlueprintTransition(current, blueprint, apply, output) {
     const transition = (0, index_js_1.classifyBlueprintTransition)(current, blueprint.manifest);
     if (transition.kind === 'compatible')
         return false;
@@ -183,7 +690,7 @@ function gateBreakingBlueprintTransition(current, blueprint, apply) {
         manualSuccession: `${blueprint.manifest.name}@${blueprint.manifest.version}:${migration.manualSuccession}`,
         verification: migration.verification,
     };
-    devkit_1.logger.info(`[ebk-upgrade] declared breaking Blueprint transition — manual succession only\n${JSON.stringify(report, null, 2)}\nNo Blueprint files were rendered or changed. The declared executor, if any, was not executed.`);
+    output.info(`[ebk-upgrade] declared breaking Blueprint transition — manual succession only\n${JSON.stringify(report, null, 2)}\nNo Blueprint files were rendered or changed. The declared executor, if any, was not executed.`);
     if (apply) {
         throw new Error(`Breaking Blueprint migration ${migration.id} is report-only in v1 and was not applied. Follow ${report.manualSuccession}; do not restamp the target Blueprint as active until manual succession is complete.`);
     }
@@ -197,20 +704,24 @@ function createUpgradeReport(currentFiles, currentOwnership, targetFiles, target
 }) {
     const report = {
         addedSeeded: [],
+        appendedSeeded: [],
         changed: [],
         claimedJsonMembers: [...jsonOwnershipChanges.claimedJsonMembers],
         conflicting: [],
         conflictingJsonMembers: [...jsonOwnershipChanges.conflictingJsonMembers],
         expandedJsonOwnership: [...jsonOwnershipChanges.expandedJsonOwnership],
+        incompatibleSeededMigrations: [],
         missing: [],
         obsolete: [],
         preservedSeeded: [],
         releasedJsonMembers: [...jsonOwnershipChanges.releasedJsonMembers],
+        seededReconciliation: [],
         unchanged: [],
     };
     const targetPaths = new Set(targetOwnership.paths.map(({ path }) => path));
     const currentPathOwnership = new Map(currentOwnership.paths.map((entry) => [entry.path, entry]));
-    for (const { mode, path } of targetOwnership.paths) {
+    for (const targetEntry of targetOwnership.paths) {
+        const { mode, path, sha256: targetSha256 } = targetEntry;
         const current = currentFiles.get(path) ?? null;
         const target = targetFiles.get(path);
         const currentEntry = currentPathOwnership.get(path);
@@ -219,12 +730,36 @@ function createUpgradeReport(currentFiles, currentOwnership, targetFiles, target
         }
         if (mode === 'seeded') {
             (current === null ? report.addedSeeded : report.preservedSeeded).push(path);
+            if (current !== null &&
+                currentEntry !== undefined &&
+                currentEntry.sha256 !== targetSha256 &&
+                path.startsWith('database/migrations/')) {
+                report.incompatibleSeededMigrations.push(path);
+            }
+            else if (current !== null &&
+                currentEntry?.sha256 !== targetSha256 &&
+                seededReconciliationDefinition(path) !== null) {
+                const reconciliation = seededReconciliationDefinition(path);
+                if (reconciliation === null) {
+                    throw new Error(`Missing seeded reconciliation definition for ${path}.`);
+                }
+                report.seededReconciliation.push({
+                    adopterContentSha256: (0, index_js_4.hashOwnedContent)(current, currentEntry ?? targetEntry),
+                    category: reconciliation.category,
+                    currentFrameworkSha256: currentEntry?.sha256 ?? null,
+                    implications: [...reconciliation.implications],
+                    markerReference: SEEDED_RECONCILIATION_MARKER_REFERENCE,
+                    path,
+                    requiredAction: 'review-and-reconcile-preserving-adopter-content',
+                    targetFrameworkSha256: targetSha256,
+                });
+            }
         }
         else if (current === null) {
             report.missing.push(path);
         }
         else if (currentEntry !== undefined &&
-            (0, index_js_3.hashOwnedContent)(current, currentEntry) !== currentEntry.sha256) {
+            (0, index_js_4.hashOwnedContent)(current, currentEntry) !== currentEntry.sha256) {
             report.conflicting.push(path);
         }
         else if (current === target) {
@@ -247,7 +782,7 @@ function createUpgradeReport(currentFiles, currentOwnership, targetFiles, target
         const current = currentFiles.get(path) ?? null;
         if (current === null)
             continue;
-        if ((0, index_js_3.hashOwnedContent)(current, entry) === sha256) {
+        if ((0, index_js_4.hashOwnedContent)(current, entry) === sha256) {
             report.obsolete.push(path);
         }
         else if (!report.conflicting.includes(path)) {
@@ -264,8 +799,11 @@ function createUpgradeReport(currentFiles, currentOwnership, targetFiles, target
         if (!report.conflicting.includes(path))
             report.conflicting.push(path);
     }
-    for (const paths of Object.values(report))
-        paths.sort();
+    for (const paths of Object.values(report)) {
+        paths.sort((left, right) => typeof left === 'string' && typeof right === 'string'
+            ? (0, deterministic_order_js_1.compareUtf16)(left, right)
+            : (0, deterministic_order_js_1.compareUtf16)(left.path, right.path));
+    }
     return report;
 }
 function mergeStructuredTargetFiles(currentFiles, currentOwnership, targetFiles, targetOwnership) {
@@ -295,7 +833,7 @@ function mergeStructuredTargetFiles(currentFiles, currentOwnership, targetFiles,
         if (!targetEntry.managedJsonPointers)
             continue;
         if (currentEntry?.managedJsonPointers) {
-            const transition = (0, index_js_3.analyzeManagedJsonPointerTransition)(current, target, currentEntry.managedJsonPointers, targetEntry.managedJsonPointers);
+            const transition = (0, index_js_4.analyzeManagedJsonPointerTransition)(current, target, currentEntry.managedJsonPointers, targetEntry.managedJsonPointers);
             changes.claimedJsonMembers.push(...transition.claimed.map((pointer) => `${targetEntry.path}#${pointer}`));
             changes.conflictingJsonMembers.push(...transition.conflictingClaims.map((pointer) => `${targetEntry.path}#${pointer}`));
             changes.releasedJsonMembers.push(...transition.released.map((pointer) => `${targetEntry.path}#${pointer}`));
@@ -304,26 +842,12 @@ function mergeStructuredTargetFiles(currentFiles, currentOwnership, targetFiles,
                 continue;
             }
         }
-        files.set(targetEntry.path, (0, index_js_3.mergeManagedJsonContents)(current, target, targetEntry.managedJsonPointers));
+        files.set(targetEntry.path, (0, index_js_4.mergeManagedJsonContents)(current, target, targetEntry.managedJsonPointers));
     }
     return { files, ...changes };
 }
-function renderCompositionUpgradePlan(ownership) {
+function renderCompositionUpgradePlan(ownership, workspace, runtimeVersion, serviceAdapterOwner) {
     const compositionPaths = ownership.paths.filter(({ origin }) => origin === 'composition');
-    const functionNames = new Set();
-    const workloads = new Map();
-    for (const { path } of compositionPaths) {
-        const functionMatch = /^infra\/functions\/([^/]+)\.ts$/.exec(path);
-        if (functionMatch?.[1])
-            functionNames.add(functionMatch[1]);
-        const workloadMatch = /^(services|jobs)\/([^/]+)\//.exec(path);
-        if (workloadMatch?.[1] && workloadMatch[2]) {
-            workloads.set(`${workloadMatch[1]}/${workloadMatch[2]}`, {
-                kind: workloadMatch[1] === 'services' ? 'service' : 'job',
-                name: workloadMatch[2],
-            });
-        }
-    }
     const files = {};
     const paths = new Map();
     const addPlan = (planFiles, planPaths) => {
@@ -340,17 +864,20 @@ function renderCompositionUpgradePlan(ownership) {
                 mode: entry.mode ?? 'managed',
                 origin: 'composition',
                 path: entry.path,
-                sha256: (0, index_js_3.hashOwnedContent)(contents, entry),
+                sha256: (0, index_js_4.hashOwnedContent)(contents, entry),
             });
         }
     };
-    for (const name of functionNames) {
-        const plan = (0, function_js_1.createFunctionFilePlan)(ownership.slice, name);
-        addPlan(plan.files, plan.paths);
-    }
-    for (const { kind, name } of workloads.values()) {
-        const plan = (0, workload_js_1.createWorkloadFilePlan)(ownership.slice, name, kind);
-        addPlan(plan.files, plan.paths);
+    for (const composition of ownership.compositions) {
+        if (composition.kind === 'function') {
+            const plan = (0, function_js_1.createFunctionFilePlan)(workspace, ownership.slice, composition.name, composition.feature);
+            addPlan(plan.files, plan.paths);
+        }
+        else {
+            const plan = (0, workload_js_1.createWorkloadFilePlan)(workspace, ownership.slice, composition.name, composition.kind, runtimeVersion, composition.feature, composition.kind === 'service' &&
+                composition.name === serviceAdapterOwner);
+            addPlan(plan.files, plan.paths);
+        }
     }
     for (const entry of compositionPaths) {
         if (paths.has(entry.path))
@@ -359,12 +886,124 @@ function renderCompositionUpgradePlan(ownership) {
     }
     return { files, paths: [...paths.values()] };
 }
-async function upgradeFoundation(tree, options, packageJson) {
+function retainedServiceAdapterOwner(tree, root, ownership) {
+    const pathOwners = ownership.compositions
+        .filter(({ kind, name }) => kind === 'service' &&
+        ownership.paths.some(({ mode, origin, path }) => path === `services/${name}/src/performance.ts` &&
+            mode === 'managed' &&
+            origin === 'composition'))
+        .map(({ name }) => name);
+    if (ownership.blueprint.name !== index_js_1.BUILTIN_BLUEPRINT_NAME &&
+        pathOwners.length === 0) {
+        return null;
+    }
+    const operationsPath = node_path_1.posix.join(root, 'operations/performance.json');
+    if (!tree.exists(operationsPath)) {
+        if (pathOwners.length === 0)
+            return null;
+        throw new Error('Product Slice Service adapter owner cannot be reconciled for upgrade.');
+    }
+    const operations = readJson(tree, operationsPath, 'Product Slice performance operations registry');
+    const record = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+    const load = record(operations) ? operations['load'] : undefined;
+    const allowlistedAdapters = record(load)
+        ? load['allowlistedScenarioAdapters']
+        : undefined;
+    const owner = record(load) ? load['serviceAdapterOwner'] : undefined;
+    const status = record(load) ? load['serviceAdapterStatus'] : undefined;
+    if (!record(load) ||
+        !Array.isArray(allowlistedAdapters) ||
+        allowlistedAdapters.some((adapter) => typeof adapter !== 'string')) {
+        throw new Error('Product Slice Service adapter owner cannot be reconciled for upgrade.');
+    }
+    const scenarioDocument = readJson(tree, node_path_1.posix.join(root, 'performance/load-scenarios.json'), 'Product Slice protected-load scenario catalog');
+    const scenarios = record(scenarioDocument)
+        ? scenarioDocument['scenarios']
+        : undefined;
+    const serviceScenarios = Array.isArray(scenarios)
+        ? scenarios.filter((scenario) => record(scenario) && scenario['id'] === 'service-extension')
+        : [];
+    const serviceScenario = serviceScenarios[0];
+    const secretAccess = readJson(tree, node_path_1.posix.join(root, 'secrets/workload-access.json'), 'Product Slice secret workload access registry');
+    const bindings = record(secretAccess) ? secretAccess['bindings'] : undefined;
+    const logicalName = `${ownership.slice
+        .split('-')
+        .map((part) => `${part.charAt(0).toUpperCase()}${part.slice(1)}`)
+        .join('')}PerformanceLoadHmacKeys`;
+    const protectedLoadBindings = Array.isArray(bindings)
+        ? bindings.filter((binding) => record(binding) &&
+            binding['logicalName'] === logicalName &&
+            typeof binding['workload'] === 'string' &&
+            binding['workload'].endsWith('-service-performance-task'))
+        : [];
+    if (status === 'requires-adopter-service-runtime-endpoint' &&
+        owner === null &&
+        pathOwners.length === 0 &&
+        !allowlistedAdapters.includes('ebk-service-v1') &&
+        serviceScenarios.length === 1 &&
+        record(serviceScenario) &&
+        serviceScenario['adapterId'] === 'ebk-service-v1' &&
+        serviceScenario['adapterStatus'] === 'requires-adopter-service-endpoint' &&
+        serviceScenario['saturationSignalRef'] ===
+            'adopter:service-saturation-percent' &&
+        serviceScenario['workload'] === 'service' &&
+        Array.isArray(bindings) &&
+        protectedLoadBindings.length === 0) {
+        return null;
+    }
+    if (status === 'managed-generated-service-runtime-endpoint' &&
+        typeof owner === 'string' &&
+        pathOwners.length === 1 &&
+        pathOwners[0] === owner &&
+        allowlistedAdapters.includes('ebk-service-v1') &&
+        serviceScenarios.length === 1 &&
+        record(serviceScenario) &&
+        serviceScenario['adapterId'] === 'ebk-service-v1' &&
+        serviceScenario['adapterStatus'] === 'managed' &&
+        serviceScenario['saturationSignalRef'] ===
+            `runtime:service-${owner}-per-task-concurrency-utilization-percent` &&
+        serviceScenario['workload'] === 'service' &&
+        Array.isArray(bindings) &&
+        protectedLoadBindings.length === 1 &&
+        record(protectedLoadBindings[0]) &&
+        protectedLoadBindings[0]['workload'] ===
+            `${ownership.slice}.${owner}-service-performance-task`) {
+        return owner;
+    }
+    throw new Error('Product Slice Service adapter owner cannot be reconciled for upgrade.');
+}
+function carryRetainedServiceAdapterAuthority(targetFiles, owner) {
+    const path = 'operations/performance.json';
+    const targetSource = targetFiles[path];
+    if (targetSource === undefined) {
+        throw new Error('Target Product Slice does not render the managed Service adapter authority.');
+    }
+    let target;
+    try {
+        target = JSON.parse(targetSource);
+    }
+    catch {
+        throw new Error('Target Product Slice performance operations registry is invalid JSON.');
+    }
+    if (!target.load ||
+        !Array.isArray(target.load.allowlistedScenarioAdapters) ||
+        target.load.allowlistedScenarioAdapters.some((adapter) => typeof adapter !== 'string')) {
+        throw new Error('Product Slice Service adapter owner cannot be carried into the target Blueprint.');
+    }
+    target.load.allowlistedScenarioAdapters = [
+        ...new Set([...target.load.allowlistedScenarioAdapters, 'ebk-service-v1']),
+    ].sort();
+    target.load.serviceAdapterOwner = owner;
+    target.load.serviceAdapterStatus =
+        'managed-generated-service-runtime-endpoint';
+    return { ...targetFiles, [path]: json(target) };
+}
+async function upgradeFoundation(tree, options, packageJson, output) {
     if (options.blueprint !== undefined || options.inputs !== undefined) {
         throw new Error('Standard Foundation upgrades do not accept Blueprint or input options.');
     }
     const root = 'packages/foundation';
-    const ownershipResult = (0, index_js_3.validateFoundationOwnershipRecord)(readJson(tree, node_path_1.posix.join(root, '.ebk/ownership.json'), 'Standard Foundation ownership metadata'));
+    const ownershipResult = (0, index_js_4.validateFoundationOwnershipRecord)(readJson(tree, node_path_1.posix.join(root, '.ebk/ownership.json'), 'Standard Foundation ownership metadata'));
     if (!ownershipResult.valid) {
         throw new Error(ownershipValidationMessage('Standard Foundation ownership metadata', ownershipResult.issues));
     }
@@ -380,7 +1019,7 @@ async function upgradeFoundation(tree, options, packageJson) {
         ...renderedTarget,
         files: await formatRenderedFiles(renderedTarget.files, root),
     };
-    const targetValidation = (0, index_js_3.validateFoundationOwnershipRecord)(target.ownership);
+    const targetValidation = (0, index_js_4.validateFoundationOwnershipRecord)(target.ownership);
     if (!targetValidation.valid) {
         throw new Error(`Target Standard Foundation ownership metadata is invalid:\n${targetValidation.issues
             .map((issue) => `- ${issue.path}: ${issue.message}`)
@@ -396,9 +1035,12 @@ async function upgradeFoundation(tree, options, packageJson) {
     ]));
     const mergedTarget = mergeStructuredTargetFiles(currentFiles, currentOwnership, new Map(Object.entries(target.files)), target.ownership);
     const report = createUpgradeReport(currentFiles, currentOwnership, mergedTarget.files, target.ownership, mergedTarget);
-    devkit_1.logger.info(`[ebk-upgrade] foundation ${currentOwnership.frameworkVersion} -> ${target.ownership.frameworkVersion}\n${JSON.stringify(report, null, 2)}`);
+    output.info(`[ebk-upgrade] foundation ${currentOwnership.frameworkVersion} -> ${target.ownership.frameworkVersion}\n${JSON.stringify(report, null, 2)}`);
     if (!options.apply)
         return;
+    if (report.incompatibleSeededMigrations.length > 0) {
+        throw new Error(seededMigrationUpgradeMessage('Standard Foundation', report));
+    }
     if (report.conflicting.length > 0) {
         throw new Error(upgradeConflictMessage('Standard Foundation', report));
     }
@@ -419,19 +1061,20 @@ async function upgradeFoundation(tree, options, packageJson) {
     }
     if (!options.skipFormat)
         await (0, devkit_1.formatFiles)(tree);
-    (0, index_js_3.restampFoundationOwnership)(tree);
+    (0, index_js_4.restampFoundationOwnership)(tree);
 }
-async function upgradeWorkspace(tree, options, packageJson) {
+async function upgradeWorkspace(tree, options, packageJson, output) {
     if (options.blueprint !== undefined || options.inputs !== undefined) {
         throw new Error('Workspace upgrades do not accept Blueprint or input options.');
     }
-    const ownershipResult = (0, index_js_3.validateWorkspaceOwnershipRecord)(readJson(tree, '.ebk/ownership.json', 'Workspace ownership metadata'));
+    const ownershipResult = (0, index_js_4.validateWorkspaceOwnershipRecord)(readJson(tree, '.ebk/ownership.json', 'Workspace ownership metadata'));
     if (!ownershipResult.valid) {
         throw new Error(ownershipValidationMessage('Workspace ownership metadata', ownershipResult.issues));
     }
     if (!packageJson.name) {
         throw new Error('Workspace package.json must declare a name.');
     }
+    const sstVersionState = inspectWorkspaceSstVersion(tree, packageJson);
     const currentOwnership = ownershipResult.value;
     const renderedTarget = (0, workspace_files_js_1.renderWorkspaceRootFilePlan)({
         frameworkVersion: (0, generator_js_1.frameworkPackageVersion)(),
@@ -441,7 +1084,7 @@ async function upgradeWorkspace(tree, options, packageJson) {
         ...renderedTarget,
         files: await formatRenderedFiles(renderedTarget.files),
     };
-    const targetValidation = (0, index_js_3.validateWorkspaceOwnershipRecord)(target.ownership);
+    const targetValidation = (0, index_js_4.validateWorkspaceOwnershipRecord)(target.ownership);
     if (!targetValidation.valid) {
         throw new Error('Target workspace ownership metadata is invalid.');
     }
@@ -451,26 +1094,27 @@ async function upgradeWorkspace(tree, options, packageJson) {
     ]);
     const currentFiles = new Map([...allPaths].map((path) => [path, tree.read(path, 'utf8')]));
     const mergedTarget = mergeStructuredTargetFiles(currentFiles, currentOwnership, new Map(Object.entries(target.files)), target.ownership);
+    const developerAgentInstructionAppend = planDeveloperAgentInstructionAppend(currentFiles.get('AGENTS.md') ?? null, target.files['AGENTS.md']);
+    if (developerAgentInstructionAppend !== null) {
+        mergedTarget.files.set(developerAgentInstructionAppend.path, developerAgentInstructionAppend.contents);
+    }
     const report = createUpgradeReport(currentFiles, currentOwnership, mergedTarget.files, target.ownership, mergedTarget);
-    devkit_1.logger.info(`[ebk-upgrade] workspace ${currentOwnership.frameworkVersion} -> ${target.ownership.frameworkVersion}\n${JSON.stringify(report, null, 2)}`);
-    const repositoryPolicyContents = tree.read('ebk.repository-policy.json', 'utf8');
-    if (repositoryPolicyContents !== null) {
-        try {
-            const repositoryPolicy = JSON.parse(repositoryPolicyContents);
-            if (typeof repositoryPolicy === 'object' &&
-                repositoryPolicy !== null &&
-                !Array.isArray(repositoryPolicy) &&
-                !Object.prototype.hasOwnProperty.call(repositoryPolicy, 'productionApproval')) {
-                devkit_1.logger.warn('[ebk-upgrade] Preserved pre-beta.7 Repository Operating Policy requires an explicit production approval amendment before workspace health or GitHub bootstrap. Report it with pnpm nx g @empire-builder-kit/nx:repository-policy --productionApprovalMode=promotion-pr, then rerun with --apply after review. Use environment-reviewer instead only when that stronger committed contract is intended and supported.');
-            }
-        }
-        catch {
-            // The upgrade preserves adopter-owned policy source. Its normal validator
-            // reports malformed JSON; this notice is only for the known missing member.
-        }
+    if (developerAgentInstructionAppend !== null) {
+        report.preservedSeeded = report.preservedSeeded.filter((path) => path !== developerAgentInstructionAppend.path);
+        report.appendedSeeded.push(developerAgentInstructionAppend.path);
+    }
+    output.info(`[ebk-upgrade] workspace ${currentOwnership.frameworkVersion} -> ${target.ownership.frameworkVersion}\n${JSON.stringify({ ...report, tooling: { sst: sstVersionState } }, null, 2)}`);
+    if (sstVersionState.classification === 'sst-version-drift') {
+        const message = workspaceSstVersionDriftMessage(sstVersionState);
+        if (options.apply)
+            throw new Error(message);
+        output.warn(message);
     }
     if (!options.apply)
         return;
+    if (report.incompatibleSeededMigrations.length > 0) {
+        throw new Error(seededMigrationUpgradeMessage('Workspace', report));
+    }
     if (report.conflicting.length > 0) {
         throw new Error(upgradeConflictMessage('Workspace', report));
     }
@@ -480,32 +1124,43 @@ async function upgradeWorkspace(tree, options, packageJson) {
         ...report.changed,
         ...report.missing,
         ...report.addedSeeded,
+        ...report.appendedSeeded,
         '.ebk/ownership.json',
     ]);
     for (const path of writePaths) {
+        if (path === developerAgentInstructionAppend?.path)
+            continue;
         const contents = mergedTarget.files.get(path);
         if (contents === undefined) {
             throw new Error(`Target workspace did not render ${path}.`);
         }
         tree.write(path, contents);
     }
-    if (!options.skipFormat)
+    if (!options.skipFormat) {
         await (0, devkit_1.formatFiles)(tree);
-    (0, index_js_3.restampWorkspaceOwnership)(tree);
+        for (const [path, contents] of Object.entries(target.files)) {
+            if ((0, workspace_files_js_1.isRawWorkspaceAuthorityPath)(path))
+                tree.write(path, contents);
+        }
+    }
+    if (developerAgentInstructionAppend !== null) {
+        tree.write(developerAgentInstructionAppend.path, developerAgentInstructionAppend.contents);
+    }
+    (0, index_js_4.restampWorkspaceOwnership)(tree);
 }
-async function upgradeGenerator(tree, options) {
+async function executeUpgradeGenerator(tree, options, output = devkit_1.logger, executionOptions = {}) {
     const name = requireName(options.name);
     const packageJson = readJson(tree, 'package.json', 'Workspace package.json');
     if (name === 'workspace') {
-        return upgradeWorkspace(tree, options, packageJson);
+        return upgradeWorkspace(tree, options, packageJson, output);
     }
     if (name === 'foundation') {
         requireUpgradePrerequisites(tree, 'foundation');
-        return upgradeFoundation(tree, options, packageJson);
+        return upgradeFoundation(tree, options, packageJson, output);
     }
     requireUpgradePrerequisites(tree, 'product-slice');
     const root = node_path_1.posix.join('packages', name);
-    const ownershipResult = (0, index_js_3.validateGeneratedOwnershipRecord)(readJson(tree, node_path_1.posix.join(root, '.ebk/ownership.json'), 'Product Slice ownership metadata'));
+    const ownershipResult = (0, index_js_4.validateGeneratedOwnershipRecord)(readJson(tree, node_path_1.posix.join(root, '.ebk/ownership.json'), 'Product Slice ownership metadata'));
     if (!ownershipResult.valid) {
         throw new Error(ownershipValidationMessage('Product Slice ownership metadata', ownershipResult.issues));
     }
@@ -513,38 +1168,46 @@ async function upgradeGenerator(tree, options) {
     if (currentOwnership.slice !== name) {
         throw new Error(`Ownership metadata belongs to ${currentOwnership.slice}, not ${name}.`);
     }
+    for (const composition of currentOwnership.compositions) {
+        (0, feature_registry_js_1.requireRegisteredSliceFeature)(tree, root, composition.feature);
+    }
+    const serviceAdapterOwner = retainedServiceAdapterOwner(tree, root, currentOwnership);
     const recordedReference = currentOwnership.blueprint.name === index_js_1.BUILTIN_BLUEPRINT_NAME
         ? index_js_1.BUILTIN_BLUEPRINT_REFERENCE
         : `${currentOwnership.blueprint.name}@${currentOwnership.blueprint.version}`;
     const blueprint = (0, index_js_1.resolveBlueprint)({
+        localAuthoringPackages: packageJson.ebk?.blueprints?.localAuthoringPackages ?? [],
         localPackages: packageJson.ebk?.blueprints?.localPackages,
         reference: options.blueprint ?? recordedReference,
-        trust: { packages: packageJson.ebk?.blueprints?.trustedPackages ?? [] },
         workspaceRoot: tree.root,
     });
+    if (serviceAdapterOwner !== null && blueprint.source !== 'built-in') {
+        throw new Error('External Blueprint upgrades cannot retain the managed generated Service adapter authority; remove or explicitly migrate the elected adapter before changing Blueprint authority.');
+    }
     const inputResult = (0, index_js_1.validateBlueprintInputs)(blueprint.inputSchema, parseInputs(options.inputs, currentOwnership.inputs));
     if (!inputResult.valid) {
         throw new Error(`Blueprint inputs are invalid:\n${inputResult.issues
             .map((issue) => `- ${issue.path}: ${issue.message}`)
             .join('\n')}`);
     }
-    const compatibility = (0, index_js_2.validateFoundationCompatibility)(blueprint.manifest.foundation, readJson(tree, 'packages/foundation/contracts/foundation.json', 'Standard Foundation descriptor'));
+    const compatibility = (0, index_js_3.validateFoundationCompatibility)(blueprint.manifest.foundation, readJson(tree, 'packages/foundation/contracts/foundation.json', 'Standard Foundation descriptor'));
     if (!compatibility.valid) {
         throw new Error(`Standard Foundation is incompatible with the target Blueprint:\n${compatibility.issues
             .map((issue) => `- ${issue.path}: ${issue.message}`)
             .join('\n')}`);
     }
-    if (gateBreakingBlueprintTransition(currentOwnership.blueprint, blueprint, options.apply === true)) {
+    if (gateBreakingBlueprintTransition(currentOwnership.blueprint, blueprint, options.apply === true, output)) {
         return;
     }
     let targetFiles;
     let targetOwnership;
+    let externalBlueprintDestinationPaths;
     const scope = workspaceScope(packageJson);
     if (blueprint.source === 'built-in') {
         const runtimeVersion = packageJson.dependencies?.['@empire-builder-kit/runtime'];
         if (!runtimeVersion)
             throw new Error('Workspace must depend on @empire-builder-kit/runtime.');
-        const plan = (0, slice_js_1.createBuiltInSlicePlan)(name, scope, runtimeVersion, blueprint.manifest, inputResult.value);
+        const plan = (0, built_in_plan_js_1.createBuiltInSlicePlan)(name, scope, runtimeVersion, blueprint.manifest, inputResult.value);
         targetFiles = Object.fromEntries(Object.entries(plan.files).map(([path, contents]) => {
             const current = tree.read(node_path_1.posix.join(root, path), 'utf8');
             return [
@@ -554,39 +1217,75 @@ async function upgradeGenerator(tree, options) {
                     : preserveCompositionRegions(current, contents),
             ];
         }));
-        targetOwnership = plan.ownership;
+        targetOwnership = {
+            ...plan.ownership,
+            contracts: {
+                ...plan.ownership.contracts,
+                consumes: currentContractConsumers(tree, root),
+            },
+        };
     }
     else {
+        const nxVersion = packageJson.devDependencies?.['@empire-builder-kit/nx'];
+        const runtimeVersion = packageJson.dependencies?.['@empire-builder-kit/runtime'];
+        if (!nxVersion || !runtimeVersion) {
+            throw new Error('External Blueprint upgrades require exact Nx and Runtime framework dependencies.');
+        }
         if (!blueprint.generatorPath) {
             throw new Error('Resolved external Blueprint has no generator entry point.');
         }
+        if (!blueprint.packageRoot) {
+            throw new Error('Resolved external Blueprint has no package root.');
+        }
+        if (blueprint.source === 'installed' &&
+            (!blueprint.registryIntegrity || !blueprint.lockfileDigest)) {
+            throw new Error('Resolved installed Blueprint has no lockfile and registry-integrity authority.');
+        }
+        const executionSource = blueprint.source === 'installed'
+            ? {
+                lockfileDigest: blueprint.lockfileDigest,
+                registryIntegrity: blueprint.registryIntegrity,
+                source: 'installed',
+            }
+            : { source: 'local' };
         const generated = await (0, index_js_1.executeBlueprintGenerator)(blueprint.generatorPath, {
             foundation: compatibility.value,
             inputs: inputResult.value,
             manifest: blueprint.manifest,
             name,
             root,
-            workspace: { name: packageJson.name ?? '', scope },
+            workspace: {
+                framework: { nx: nxVersion, runtime: runtimeVersion },
+                name: packageJson.name ?? '',
+                scope,
+            },
+        }, {
+            diagnostics: executionOptions.externalBlueprintDiagnostics ?? 'inherit',
+            packageRoot: blueprint.packageRoot,
+            ...executionSource,
+            workspaceRoot: tree.root,
         });
+        externalBlueprintDestinationPaths = generated.files.map(({ path }) => path);
         const paths = generated.files.map(({ contents, managedJsonPointers, mode, path }) => ({
             ...(managedJsonPointers ? { managedJsonPointers } : {}),
             mode,
             origin: 'blueprint',
             path,
-            sha256: (0, index_js_3.hashOwnedContent)(contents, { managedJsonPointers }),
+            sha256: (0, index_js_4.hashOwnedContent)(contents, { managedJsonPointers }),
         }));
-        paths.sort((left, right) => left.path.localeCompare(right.path));
+        paths.sort((left, right) => (0, deterministic_order_js_1.compareUtf16)(left.path, right.path));
         targetOwnership = {
             blueprint: {
                 name: blueprint.manifest.name,
                 version: blueprint.manifest.version,
             },
+            compositions: [],
             contracts: generated.contracts,
             foundation: blueprint.manifest.foundation,
             inputs: inputResult.value,
             paths,
             projects: generated.projects,
-            schemaVersion: index_js_3.GENERATED_OWNERSHIP_SCHEMA_VERSION,
+            schemaVersion: index_js_4.GENERATED_OWNERSHIP_SCHEMA_VERSION,
             slice: name,
             verification: blueprint.manifest.verification,
         };
@@ -595,9 +1294,18 @@ async function upgradeGenerator(tree, options) {
             ['.ebk/ownership.json', json(targetOwnership)],
         ]);
     }
+    if (blueprint.source === 'built-in' && serviceAdapterOwner !== null) {
+        targetFiles = carryRetainedServiceAdapterAuthority(targetFiles, serviceAdapterOwner);
+    }
     const targetPathSet = new Set(targetOwnership.paths.map(({ path }) => path));
-    const compositionPlan = renderCompositionUpgradePlan(currentOwnership);
+    const compositionPlan = renderCompositionUpgradePlan(currentOwnership, packageJson.name ?? '', packageJson.dependencies?.['@empire-builder-kit/runtime'] ?? '', serviceAdapterOwner);
     const compositionPaths = compositionPlan.paths.filter(({ path }) => !targetPathSet.has(path));
+    if (externalBlueprintDestinationPaths) {
+        (0, index_js_1.assertBlueprintDestinationPaths)(tree.root, root, [
+            ...externalBlueprintDestinationPaths,
+            ...compositionPaths.map(({ path }) => path),
+        ]);
+    }
     for (const entry of compositionPaths) {
         const contents = compositionPlan.files[entry.path] ??
             tree.read(node_path_1.posix.join(root, entry.path), 'utf8');
@@ -609,6 +1317,7 @@ async function upgradeGenerator(tree, options) {
     targetFiles = await formatRenderedFiles(targetFiles, root);
     targetOwnership = {
         ...targetOwnership,
+        compositions: currentOwnership.compositions,
         ...(targetOwnership.migrationHistory === undefined &&
             currentOwnership.migrationHistory !== undefined
             ? { migrationHistory: currentOwnership.migrationHistory }
@@ -618,7 +1327,7 @@ async function upgradeGenerator(tree, options) {
             if (contents === undefined) {
                 throw new Error(`Target Blueprint did not render ${entry.path}.`);
             }
-            return { ...entry, sha256: (0, index_js_3.hashOwnedContent)(contents, entry) };
+            return { ...entry, sha256: (0, index_js_4.hashOwnedContent)(contents, entry) };
         }),
         projects: [
             ...new Set([...targetOwnership.projects, ...currentOwnership.projects]),
@@ -628,7 +1337,7 @@ async function upgradeGenerator(tree, options) {
         ...targetFiles,
         '.ebk/ownership.json': json(targetOwnership),
     };
-    const targetValidation = (0, index_js_3.validateGeneratedOwnershipRecord)(targetOwnership);
+    const targetValidation = (0, index_js_4.validateGeneratedOwnershipRecord)(targetOwnership);
     if (!targetValidation.valid) {
         throw new Error(`Target ownership metadata is invalid:\n${targetValidation.issues
             .map((issue) => `- ${issue.path}: ${issue.message}`)
@@ -643,10 +1352,14 @@ async function upgradeGenerator(tree, options) {
         tree.read(node_path_1.posix.join(root, path), 'utf8'),
     ]));
     const mergedTarget = mergeStructuredTargetFiles(currentFiles, currentOwnership, new Map(Object.entries(targetFiles)), targetOwnership);
+    requireTargetCompositionFeatures(mergedTarget.files, targetOwnership);
     const report = createUpgradeReport(currentFiles, currentOwnership, mergedTarget.files, targetOwnership, mergedTarget);
-    devkit_1.logger.info(`[ebk-upgrade] ${name} ${currentOwnership.blueprint.name}@${currentOwnership.blueprint.version} -> ${blueprint.manifest.name}@${blueprint.manifest.version}\n${JSON.stringify(report, null, 2)}`);
+    output.info(`[ebk-upgrade] ${name} ${currentOwnership.blueprint.name}@${currentOwnership.blueprint.version} -> ${blueprint.manifest.name}@${blueprint.manifest.version}\n${JSON.stringify(report, null, 2)}`);
     if (!options.apply)
         return;
+    if (report.incompatibleSeededMigrations.length > 0) {
+        throw new Error(seededMigrationUpgradeMessage('Product Slice', report));
+    }
     if (report.conflicting.length > 0) {
         throw new Error(upgradeConflictMessage('Product Slice', report));
     }
@@ -664,6 +1377,7 @@ async function upgradeGenerator(tree, options) {
             throw new Error(`Target Blueprint did not render ${path}.`);
         tree.write(node_path_1.posix.join(root, path), contents);
     }
+    appendSeededReconciliationMarker(tree, root, report);
     if (blueprint.source === 'installed') {
         packageJson.devDependencies = {
             ...packageJson.devDependencies,
@@ -673,10 +1387,34 @@ async function upgradeGenerator(tree, options) {
     }
     if (!options.skipFormat)
         await (0, devkit_1.formatFiles)(tree);
-    (0, index_js_3.restampProductSliceOwnership)(tree, name);
+    (0, index_js_4.restampProductSliceOwnership)(tree, name, { preserveSeeded: true });
     return options.skipInstall
         ? undefined
         : () => (0, devkit_1.installPackagesTask)(tree, true);
 }
+async function upgradeGenerator(tree, options, output = devkit_1.logger, executionOptions = {}) {
+    const previewFile = await requireDeveloperAgentPreviewBinding(tree, options, executionOptions);
+    if (!previewFile) {
+        return executeUpgradeGenerator(tree, options, output, executionOptions);
+    }
+    const upgradeOptions = { ...options };
+    delete upgradeOptions.developerAgentPreview;
+    delete upgradeOptions.developerAgentPreviewDigest;
+    const deferred = new preview_changes_js_1.DeferredDeveloperAgentTree(tree);
+    const beforeModes = (0, preview_changes_js_1.developerAgentPreviewOwnershipModes)(tree, options.name);
+    const install = await executeUpgradeGenerator(deferred, upgradeOptions, output, developerAgentUpgradeExecutionOptions(executionOptions));
+    if (install !== undefined)
+        return previewBindingFailure();
+    const modes = new Map([
+        ...beforeModes,
+        ...(0, preview_changes_js_1.developerAgentPreviewOwnershipModes)(deferred, options.name),
+    ]);
+    const changes = (0, preview_changes_js_1.createDeveloperAgentPreviewChanges)(deferred.listChanges(), modes);
+    if (!(0, node_util_1.isDeepStrictEqual)(changes, previewFile.preview.changes)) {
+        return previewBindingFailure();
+    }
+    await assertCurrentDeveloperAgentPreviewSource(tree.root, previewFile.preview, executionOptions);
+    deferred.apply();
+}
 exports.default = upgradeGenerator;
 //# sourceMappingURL=upgrade.js.map