@empire-builder-kit/nx 1.0.0-rc.4 → 1.0.0-rc.40

package/src/workload-roles/authority.js

@@ -36,6 +36,13 @@ exports.DIRECT_WORKLOAD_ROLE_IAM_MUTATION_ACTIONS = [
     'iam:UpdateRole',
     'iam:UpdateRoleDescription',
 ];
+const EXACT_WORKLOAD_ROLE_OBSERVATION_ACTIONS = [
+    'iam:GetInstanceProfile',
+    'iam:GetRole',
+    'iam:GetRolePolicy',
+    'iam:ListAttachedRolePolicies',
+    'iam:ListRolePolicies',
+];
 function compareStrings(left, right) {
     return left < right ? -1 : left > right ? 1 : 0;
 }
@@ -63,11 +70,48 @@ function createPassRoleStatements(registry) {
         sid: `PassRegisteredWorkloadRoles${index + 1}`,
     }));
 }
+function createRoleObservationStatements(registry) {
+    const roles = registry.manifest.roles.map((declaration) => registry.resolve(declaration.id));
+    const statements = [
+        {
+            actions: [
+                'iam:GetRole',
+                'iam:GetRolePolicy',
+                'iam:ListAttachedRolePolicies',
+                'iam:ListRolePolicies',
+            ],
+            effect: 'Allow',
+            resources: roles.map(({ roleArn }) => roleArn).sort(compareStrings),
+            sid: 'ObserveRegisteredWorkloadRoles',
+        },
+    ];
+    const instanceProfileArns = roles
+        .filter(({ surface }) => surface === 'foundation-nat-instance')
+        .map(({ roleArn, roleName }) => {
+        const suffix = `:role/${roleName}`;
+        if (!roleArn.endsWith(suffix)) {
+            throw new Error(`Registered NAT role ${roleName} has an invalid exact role ARN.`);
+        }
+        return `${roleArn.slice(0, -suffix.length)}:instance-profile/${roleName}-profile`;
+    })
+        .sort(compareStrings);
+    if (instanceProfileArns.length > 0) {
+        statements.push({
+            actions: ['iam:GetInstanceProfile'],
+            effect: 'Allow',
+            resources: instanceProfileArns,
+            sid: 'ObserveRegisteredNatInstanceProfiles',
+        });
+    }
+    return statements;
+}
 /**
  * Stable ordinary deployment-role authority. It can read exact protected
  * registration objects, invoke and observe only the fixed qualified
  * provisioner, and pass exact registered roles to their declared AWS services.
- * It deliberately exposes no direct IAM role inspection or mutation surface.
+ * It exposes only exact read authority needed by Pulumi to import the already
+ * provisioned roles and NAT instance profiles. It exposes no direct IAM
+ * mutation surface.
  */
 function createDeploymentRoleAuthorityPlan(registry, registrationReadScope) {
     return {
@@ -78,6 +122,7 @@ function createDeploymentRoleAuthorityPlan(registry, registrationReadScope) {
                 resources: ['*'],
                 sid: 'DenyDirectWorkloadIamMutation',
             },
+            ...createRoleObservationStatements(registry),
             {
                 actions: ['lambda:InvokeFunction'],
                 effect: 'Allow',
@@ -141,6 +186,7 @@ function validateDeploymentRoleAuthorityPlan(registry, value, registrationReadSc
             if (typeof action !== 'string' ||
                 (action.startsWith('iam:') &&
                     action !== 'iam:PassRole' &&
+                    !EXACT_WORKLOAD_ROLE_OBSERVATION_ACTIONS.includes(action) &&
                     (!('effect' in statement) || statement.effect !== 'Deny'))) {
                 issues.push(`ordinary deployment authority contains forbidden IAM action ${String(action)}`);
             }
@@ -149,7 +195,7 @@ function validateDeploymentRoleAuthorityPlan(registry, value, registrationReadSc
     const expected = createDeploymentRoleAuthorityPlan(registry, registrationReadScope);
     if (canonicalPlan(value) !==
         canonicalPlan(expected)) {
-        issues.push('authority plan does not exactly match the fixed provisioner and registered PassRole plan');
+        issues.push('authority plan does not exactly match fixed provisioner, exact observation, and registered PassRole authority');
     }
     return { issues, valid: issues.length === 0 };
 }

package/src/workload-roles/aws-s3-state.js

@@ -28,6 +28,7 @@ function requireS3Sdk(value) {
     return {
         DeleteObjectCommand: requireConstructor(value.DeleteObjectCommand, 'DeleteObjectCommand'),
         GetObjectCommand: requireConstructor(value.GetObjectCommand, 'GetObjectCommand'),
+        ListObjectsV2Command: requireConstructor(value.ListObjectsV2Command, 'ListObjectsV2Command'),
         PutObjectCommand: requireConstructor(value.PutObjectCommand, 'PutObjectCommand'),
         S3Client: requireConstructor(value.S3Client, 'S3Client'),
     };
@@ -61,6 +62,32 @@ async function createAwsSdkV3S3JsonControlPlane(options = {}) {
             }));
         },
         async getJson(input) {
+            const listed = await client.send(new sdk.ListObjectsV2Command({
+                Bucket: input.bucketName,
+                MaxKeys: 1,
+                Prefix: input.key,
+            }));
+            if (!isRecord(listed)) {
+                throw new Error('AWS S3 exact-key listing response is malformed.');
+            }
+            if (listed.Contents === undefined) {
+                if (listed.KeyCount === 0 && listed.IsTruncated === false) {
+                    return undefined;
+                }
+                throw new Error('AWS S3 exact-key listing response is malformed.');
+            }
+            if (!Array.isArray(listed.Contents) ||
+                listed.Contents.length !== 1 ||
+                listed.KeyCount !== 1 ||
+                listed.IsTruncated !== false) {
+                throw new Error('AWS S3 exact-key listing response is malformed.');
+            }
+            const first = listed.Contents[0];
+            if (!isRecord(first) || typeof first.Key !== 'string') {
+                throw new Error('AWS S3 exact-key listing entry is malformed.');
+            }
+            if (first.Key !== input.key)
+                return undefined;
             let response;
             try {
                 response = await client.send(new sdk.GetObjectCommand({

package/src/workload-roles/boundary.d.ts

@@ -10,7 +10,7 @@ export interface WorkloadRoleBoundaryContract {
     partition: 'aws' | 'aws-cn' | 'aws-us-gov';
     path: string;
     policy: CanonicalIamPolicyDocument;
-    policyName: typeof WORKLOAD_ROLE_BOUNDARY_POLICY_NAME;
+    policyName: string;
     stage: string;
 }
 export type WorkloadRoleBoundaryFailureClassification = 'boundary-identity-invalid' | 'boundary-policy-incomplete' | 'boundary-substitution';
@@ -19,6 +19,7 @@ export declare class WorkloadRoleBoundaryContractError extends Error {
     constructor(classification: WorkloadRoleBoundaryFailureClassification, message: string);
 }
 export declare function workloadRoleBoundaryPath(stage: string): string;
+export declare function workloadRoleBoundaryPolicyName(stage: string): string;
 export declare function workloadRoleBoundaryArn(options: {
     accountId: string;
     partition: string;

package/src/workload-roles/boundary.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WorkloadRoleBoundaryContractError = exports.WORKLOAD_ROLE_BOUNDARY_DENIED_ACTIONS = exports.WORKLOAD_ROLE_BOUNDARY_POLICY_NAME = exports.WORKLOAD_ROLE_BOUNDARY_POLICY_PATH = void 0;
 exports.workloadRoleBoundaryPath = workloadRoleBoundaryPath;
+exports.workloadRoleBoundaryPolicyName = workloadRoleBoundaryPolicyName;
 exports.workloadRoleBoundaryArn = workloadRoleBoundaryArn;
 exports.createWorkloadRoleBoundaryContract = createWorkloadRoleBoundaryContract;
 const node_crypto_1 = require("node:crypto");
@@ -61,9 +62,15 @@ function workloadRoleBoundaryPath(stage) {
     }
     return `${exports.WORKLOAD_ROLE_BOUNDARY_POLICY_PATH}/${stage}/`;
 }
+function workloadRoleBoundaryPolicyName(stage) {
+    if (!stagePattern.test(stage)) {
+        throw new WorkloadRoleBoundaryContractError('boundary-identity-invalid', `Workload-role boundary stage ${stage} is not normalized.`);
+    }
+    return `${exports.WORKLOAD_ROLE_BOUNDARY_POLICY_NAME}-${stage}`;
+}
 function workloadRoleBoundaryArn(options) {
     const identity = requireIdentity(options);
-    return `arn:${identity.partition}:iam::${identity.accountId}:policy${workloadRoleBoundaryPath(identity.stage)}${exports.WORKLOAD_ROLE_BOUNDARY_POLICY_NAME}`;
+    return `arn:${identity.partition}:iam::${identity.accountId}:policy${workloadRoleBoundaryPath(identity.stage)}${workloadRoleBoundaryPolicyName(identity.stage)}`;
 }
 function boundaryAllowStatements(manifest, bundle) {
     const statements = [];
@@ -123,7 +130,7 @@ function createWorkloadRoleBoundaryContract(options) {
         partition: identity.partition,
         path: workloadRoleBoundaryPath(identity.stage),
         policy,
-        policyName: exports.WORKLOAD_ROLE_BOUNDARY_POLICY_NAME,
+        policyName: workloadRoleBoundaryPolicyName(identity.stage),
         stage: identity.stage,
     };
 }

package/src/workload-roles/handler.js

@@ -66,7 +66,7 @@ function operationCounts(operationKinds) {
         update: operationKinds.filter((kind) => kind === 'update').length,
     };
 }
-function failureClassification(error) {
+function failureClassification(error, internalClassification) {
     if (typeof error === 'object' &&
         error !== null &&
         'classification' in error &&
@@ -74,7 +74,15 @@ function failureClassification(error) {
         failureClassifications.has(error.classification)) {
         return error.classification;
     }
-    return 'fixed-provisioner-internal-error';
+    return internalClassification;
+}
+function failureResult(error, internalClassification) {
+    return {
+        classification: failureClassification(error, internalClassification),
+        ok: false,
+        protocolVersion: provisioner_js_1.FIXED_WORKLOAD_ROLE_PROVISIONER_PROTOCOL_VERSION,
+        resultSchemaVersion: exports.FIXED_WORKLOAD_ROLE_PROVISIONER_RESULT_SCHEMA_VERSION,
+    };
 }
 /**
  * Creates the fixed Lambda handler. Its registered-manifest source and IAM
@@ -84,47 +92,67 @@ function failureClassification(error) {
  */
 function createFixedWorkloadRoleProvisionerHandler(options) {
     return async (request) => {
+        let loaded;
         try {
-            const loaded = await (0, registration_js_1.loadFixedWorkloadRoleProvisionerRequest)({
+            loaded = await (0, registration_js_1.loadFixedWorkloadRoleProvisionerRequest)({
                 request,
                 source: options.source,
             });
-            const result = await (0, provisioner_js_1.executeFixedWorkloadRoleProvisioner)({
+        }
+        catch (error) {
+            return failureResult(error, 'fixed-provisioner-source-load-error');
+        }
+        let history;
+        try {
+            history = await options.state.loadHistory();
+        }
+        catch (error) {
+            return failureResult(error, 'fixed-provisioner-history-load-error');
+        }
+        let result;
+        let provisionedRegistration;
+        try {
+            result = await (0, provisioner_js_1.executeFixedWorkloadRoleProvisioner)({
                 adapter: options.adapter,
                 boundary: loaded.boundary,
-                history: await options.state.loadHistory(),
+                history,
                 intentsByRole: loaded.document.intentsByRole,
                 manifest: loaded.document.manifest,
                 provisionerFunctionArn: loaded.document.provisionerFunctionArn,
                 registration: loaded.registration,
                 request: loaded.request,
             });
-            const provisionedRegistration = result.registration
+            provisionedRegistration = result.registration
                 ? sanitizedRegistration(result.registration)
                 : undefined;
+        }
+        catch (error) {
+            return failureResult(error, 'fixed-provisioner-convergence-error');
+        }
+        try {
             await options.state.saveHistory(result.history);
+        }
+        catch (error) {
+            return failureResult(error, 'fixed-provisioner-history-save-error');
+        }
+        try {
             await options.state.saveProvisionedRegistration(provisionedRegistration);
-            return {
-                candidateIdentity: loaded.document.manifest.candidate.identity,
-                historyDigest: result.historyDigest,
-                manifestDigest: result.manifestDigest,
-                ok: true,
-                operation: loaded.request.operation,
-                operationCounts: operationCounts(result.operationKinds),
-                protocolVersion: result.protocolVersion,
-                ...(provisionedRegistration ? { provisionedRegistration } : {}),
-                resultSchemaVersion: exports.FIXED_WORKLOAD_ROLE_PROVISIONER_RESULT_SCHEMA_VERSION,
-                stage: loaded.document.manifest.candidate.stage,
-            };
         }
         catch (error) {
-            return {
-                classification: failureClassification(error),
-                ok: false,
-                protocolVersion: provisioner_js_1.FIXED_WORKLOAD_ROLE_PROVISIONER_PROTOCOL_VERSION,
-                resultSchemaVersion: exports.FIXED_WORKLOAD_ROLE_PROVISIONER_RESULT_SCHEMA_VERSION,
-            };
+            return failureResult(error, 'fixed-provisioner-registration-save-error');
         }
+        return {
+            candidateIdentity: loaded.document.manifest.candidate.identity,
+            historyDigest: result.historyDigest,
+            manifestDigest: result.manifestDigest,
+            ok: true,
+            operation: loaded.request.operation,
+            operationCounts: operationCounts(result.operationKinds),
+            protocolVersion: result.protocolVersion,
+            ...(provisionedRegistration ? { provisionedRegistration } : {}),
+            resultSchemaVersion: exports.FIXED_WORKLOAD_ROLE_PROVISIONER_RESULT_SCHEMA_VERSION,
+            stage: loaded.document.manifest.candidate.stage,
+        };
     };
 }
 //# sourceMappingURL=handler.js.map

package/src/workload-roles/index.d.ts

@@ -1,17 +1,10 @@
-export * from './aws-adapter.js';
-export * from './aws-internal-handler.js';
-export * from './aws-s3-state.js';
-export * from './aws-sdk-control-plane.js';
-export * from './account-baseline.js';
-export * from './authority.js';
-export * from './boundary.js';
-export * from './convergence.js';
-export * from './effective-policy.js';
-export * from './handler.js';
-export * from './history.js';
-export * from './injection.js';
-export * from './manifest.js';
-export * from './provisioner.js';
-export * from './registration.js';
-export * from './standard-slice.js';
-export * from './stage-boundary.js';
+/**
+ * Runtime-intent helpers used by SST-owned workload role creation.
+ *
+ * Candidate-bound manifests, provisioners, registrations, convergence, and
+ * AWS control-plane adapters are intentionally not public in the thin
+ * lifecycle. Native SST creates the roles; generated infrastructure consumes
+ * only this topology and permission-intent surface.
+ */
+export type { WorkloadRolePermissionIntent } from './effective-policy.js';
+export { STANDARD_SLICE_WORKLOAD_EXTENSION_KINDS, StandardSliceWorkloadRoleError, createStandardSliceWorkloadRoleTopology, type StandardSliceServiceAdapterMetadata, type StandardSliceWorkloadExtension, type StandardSliceWorkloadExtensionKind, type StandardSliceWorkloadRoleFailureClassification, type StandardSliceWorkloadRoleTopology, type StandardSliceWorkloadRoleTopologyEntry, } from './standard-slice.js';

package/src/workload-roles/index.js

@@ -1,21 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-const tslib_1 = require("tslib");
-tslib_1.__exportStar(require("./aws-adapter.js"), exports);
-tslib_1.__exportStar(require("./aws-internal-handler.js"), exports);
-tslib_1.__exportStar(require("./aws-s3-state.js"), exports);
-tslib_1.__exportStar(require("./aws-sdk-control-plane.js"), exports);
-tslib_1.__exportStar(require("./account-baseline.js"), exports);
-tslib_1.__exportStar(require("./authority.js"), exports);
-tslib_1.__exportStar(require("./boundary.js"), exports);
-tslib_1.__exportStar(require("./convergence.js"), exports);
-tslib_1.__exportStar(require("./effective-policy.js"), exports);
-tslib_1.__exportStar(require("./handler.js"), exports);
-tslib_1.__exportStar(require("./history.js"), exports);
-tslib_1.__exportStar(require("./injection.js"), exports);
-tslib_1.__exportStar(require("./manifest.js"), exports);
-tslib_1.__exportStar(require("./provisioner.js"), exports);
-tslib_1.__exportStar(require("./registration.js"), exports);
-tslib_1.__exportStar(require("./standard-slice.js"), exports);
-tslib_1.__exportStar(require("./stage-boundary.js"), exports);
+exports.createStandardSliceWorkloadRoleTopology = exports.StandardSliceWorkloadRoleError = exports.STANDARD_SLICE_WORKLOAD_EXTENSION_KINDS = void 0;
+var standard_slice_js_1 = require("./standard-slice.js");
+Object.defineProperty(exports, "STANDARD_SLICE_WORKLOAD_EXTENSION_KINDS", { enumerable: true, get: function () { return standard_slice_js_1.STANDARD_SLICE_WORKLOAD_EXTENSION_KINDS; } });
+Object.defineProperty(exports, "StandardSliceWorkloadRoleError", { enumerable: true, get: function () { return standard_slice_js_1.StandardSliceWorkloadRoleError; } });
+Object.defineProperty(exports, "createStandardSliceWorkloadRoleTopology", { enumerable: true, get: function () { return standard_slice_js_1.createStandardSliceWorkloadRoleTopology; } });
 //# sourceMappingURL=index.js.map

package/src/workload-roles/injection.js

@@ -325,7 +325,7 @@ const ECS_CONTAINER_NAME_PATTERN = /^[A-Za-z0-9_-]{1,255}$/;
 const JSONATA_DELIMITER_PATTERN = /{%|%}/;
 const ECS_RUN_TASK_SYNC_RESOURCE = 'arn:aws:states:::ecs:runTask.sync';
 const ECS_RUN_TASK_CALLBACK_RESOURCE = 'arn:aws:states:::ecs:runTask.waitForTaskToken';
-const DATABASE_LIFECYCLE_CORRELATION_EXPRESSION = '{% $states.input.databaseLifecycleCorrelationId %}';
+const DATABASE_LIFECYCLE_CORRELATION_EXPRESSION = '{% $states.context.Execution.Input.databaseLifecycleCorrelationId %}';
 const TASK_TOKEN_EXPRESSION = '{% $states.context.Task.Token %}';
 /**
  * Validates only the two bounded raw graphs emitted by the v1 generator. This is

package/src/workload-roles/provisioner.js

@@ -98,16 +98,12 @@ async function applyOperation(adapter, operation, mutation) {
     if (!mutation) {
         throw new FixedWorkloadRoleProvisionerError('provisioner-result-substitution', 'A create or update operation is missing its fixed registered mutation.');
     }
-    const profile = natProfile(declaration);
     if (operation.kind === 'create') {
         await adapter.create(mutation);
     }
     else {
         await adapter.update(mutation, operation.before);
     }
-    if (profile) {
-        await adapter.ensureNatInstanceProfile(profile);
-    }
 }
 async function executeFixedWorkloadRoleProvisioner(options) {
     const manifest = (0, manifest_js_1.canonicalizeWorkloadRoleManifest)(options.manifest);
@@ -180,6 +176,18 @@ async function executeFixedWorkloadRoleProvisioner(options) {
     for (const operation of retirementPlan?.operations ?? []) {
         await applyOperation(options.adapter, operation);
     }
+    if (options.request.operation === 'converge') {
+        // The role convergence plan can be empty on a retry after a prior attempt
+        // created the role but failed while attaching its NAT instance profile.
+        // Reconcile every derived profile independently of role mutations so a
+        // successful no-op retry cannot publish an incomplete runtime identity.
+        for (const declaration of manifest.roles) {
+            const profile = natProfile(declaration);
+            if (profile) {
+                await options.adapter.ensureNatInstanceProfile(profile);
+            }
+        }
+    }
     const operationKinds = [
         ...plan.operations,
         ...(retirementPlan?.operations ?? []),

package/src/workload-roles/registration.d.ts

@@ -35,6 +35,7 @@ export interface WorkloadRoleStorageRegistration {
     schemaVersion: typeof WORKLOAD_ROLE_STORAGE_REGISTRATION_SCHEMA_VERSION;
     stage: string;
 }
+export declare function areWorkloadRoleIntentsEquivalent(left: Readonly<Record<string, readonly WorkloadRolePermissionIntent[]>>, right: Readonly<Record<string, readonly WorkloadRolePermissionIntent[]>>): boolean;
 export interface FixedRegisteredManifestSource {
     /**
      * Loads one baseline-selected value. The invocation request cannot supply a

package/src/workload-roles/registration.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WorkloadRoleRegistrationError = exports.WORKLOAD_ROLE_STORAGE_REGISTRATION_SCHEMA_VERSION = exports.PROVISIONED_WORKLOAD_ROLE_REGISTRATION_SCHEMA_VERSION = exports.REGISTERED_WORKLOAD_ROLE_MANIFEST_SCHEMA_VERSION = void 0;
+exports.areWorkloadRoleIntentsEquivalent = areWorkloadRoleIntentsEquivalent;
 exports.requireRegisteredWorkloadRoleManifestDocument = requireRegisteredWorkloadRoleManifestDocument;
 exports.createRegisteredWorkloadRoleManifestDocument = createRegisteredWorkloadRoleManifestDocument;
 exports.requireProvisionedWorkloadRoleRegistrationDocument = requireProvisionedWorkloadRoleRegistrationDocument;
@@ -13,6 +14,7 @@ exports.createWorkloadRoleStorageRegistration = createWorkloadRoleStorageRegistr
 exports.loadFixedWorkloadRoleProvisionerRequest = loadFixedWorkloadRoleProvisionerRequest;
 exports.validateWorkloadRolePreflight = validateWorkloadRolePreflight;
 const node_crypto_1 = require("node:crypto");
+const canonical_json_1 = require("@empire-builder-kit/runtime/canonical-json");
 const authority_js_1 = require("./authority.js");
 const boundary_js_1 = require("./boundary.js");
 const convergence_js_1 = require("./convergence.js");
@@ -31,6 +33,9 @@ class WorkloadRoleRegistrationError extends Error {
     }
 }
 exports.WorkloadRoleRegistrationError = WorkloadRoleRegistrationError;
+function areWorkloadRoleIntentsEquivalent(left, right) {
+    return (0, canonical_json_1.canonicalJson)(left) === (0, canonical_json_1.canonicalJson)(right);
+}
 const accountPattern = /^\d{12}$/;
 const digestPattern = /^[a-f0-9]{64}$/;
 const identifierPattern = /^(?:[a-z0-9][a-z0-9._-]{0,127}|@[a-z0-9][a-z0-9._-]{0,62}\/[a-z0-9][a-z0-9._-]{0,63})$/;

package/src/workload-roles/stage-boundary.js

@@ -200,7 +200,7 @@ function createStageWorkloadRoleBoundaryContract(options) {
         path: (0, boundary_js_1.workloadRoleBoundaryPath)(options.expectedStage),
         policy,
         policyCharacters: serializedPolicy.length,
-        policyName: boundary_js_1.WORKLOAD_ROLE_BOUNDARY_POLICY_NAME,
+        policyName: (0, boundary_js_1.workloadRoleBoundaryPolicyName)(options.expectedStage),
         projects: expectedProjects,
         stage: options.expectedStage,
     };

package/src/workload-roles/standard-slice.js

@@ -55,6 +55,7 @@ function baseTopology(slice, databaseIdentifiers) {
         role('api-database-health', 'api-route'),
         role('api-database-records', 'api-route'),
         role('api-publish-created', 'api-route'),
+        role('async-inbox-cleanup', 'lambda-function'),
         role('async-outbox-relay', 'lambda-function'),
         role('async-provider-worker', 'queue-consumer'),
         role('async-schedule-target', 'lambda-function'),
@@ -120,9 +121,8 @@ function extensionTopology(slice, extension, ownsProtectedLoadAdapter) {
 function createStandardSliceWorkloadRoleTopology(options) {
     const slice = requireIdentifier(options.slice, 'Slice');
     const databaseIdentifiers = options.databaseIdentifiers ?? ['primary'];
-    if (databaseIdentifiers.length === 0) {
-        throw new StandardSliceWorkloadRoleError('standard-role-input-invalid', 'A Standard Slice must declare at least one database identifier.');
-    }
+    // An explicit empty declaration is the SQL-free Standard topology. Omitting
+    // this field retains the existing relational caller contract.
     for (const identifier of databaseIdentifiers) {
         requireDatabaseIdentifier(identifier);
     }

package/src/workspace-deployment/affected-lifecycle.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Affected-only native lifecycle selection.
+ *
+ * A protected deployment may skip Product Slices whose inputs have not changed
+ * since the newest successful deployment receipt on the same branch. Declining
+ * is always safe: every rule below that cannot prove a project unchanged
+ * deploys it, and any governing change (policy, Nx configuration, Foundation
+ * contract, framework version) deploys everything.
+ */
+export type LifecycleMode = 'affected' | 'full';
+export type LifecycleProjectDecision = 'deploy' | 'skip-unchanged';
+export interface LifecycleBaseline {
+    readonly commit: string;
+    readonly runAttempt: string;
+    readonly runId: string;
+}
+export interface LifecycleBaselineReceipt {
+    readonly children: readonly {
+        readonly outcome: string;
+        readonly project: string;
+        readonly target: string;
+    }[];
+    readonly frameworkVersion: string;
+    readonly outcome: string;
+    readonly source: {
+        readonly commit: string;
+    };
+    readonly stage: string;
+}
+export interface LifecycleScope {
+    readonly baseline: LifecycleBaseline | null;
+    readonly mode: LifecycleMode;
+    readonly projects: Readonly<Record<string, LifecycleProjectDecision>>;
+    readonly reason: string;
+}
+export interface SelectLifecycleScopeInput {
+    /** Projects affected between the baseline commit and the source commit, or
+     * null when the affected set could not be computed. */
+    readonly affectedProjects: readonly string[] | null;
+    readonly baseline: (LifecycleBaseline & {
+        readonly receipt: LifecycleBaselineReceipt;
+    }) | null;
+    /** Governing files changed since the baseline (policy, Nx configuration,
+     * Foundation contract). Any entry forces the full lifecycle. */
+    readonly changedGoverningFiles: readonly string[];
+    readonly frameworkVersion: string;
+    readonly orderedProjects: readonly string[];
+    readonly requestedMode: LifecycleMode;
+    readonly stage: string;
+}
+/** Repository-relative files whose change always forces the full lifecycle. */
+export declare const LIFECYCLE_GOVERNING_FILES: readonly string[];
+export declare function selectLifecycleScope(input: SelectLifecycleScopeInput): LifecycleScope;

package/src/workspace-deployment/affected-lifecycle.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LIFECYCLE_GOVERNING_FILES = void 0;
+exports.selectLifecycleScope = selectLifecycleScope;
+/** Repository-relative files whose change always forces the full lifecycle. */
+exports.LIFECYCLE_GOVERNING_FILES = Object.freeze([
+    '.ebk/ownership.json',
+    'ebk.repository-policy.json',
+    'nx.json',
+    'packages/foundation/sst.config.ts',
+    'pnpm-lock.yaml',
+    'pnpm-workspace.yaml',
+]);
+const PROJECT = /^[a-z0-9][a-z0-9-]{0,62}$/u;
+function full(input, reason) {
+    return {
+        baseline: input.baseline
+            ? {
+                commit: input.baseline.commit,
+                runAttempt: input.baseline.runAttempt,
+                runId: input.baseline.runId,
+            }
+            : null,
+        mode: 'full',
+        projects: Object.fromEntries(input.orderedProjects.map((project) => [project, 'deploy'])),
+        reason,
+    };
+}
+function selectLifecycleScope(input) {
+    for (const project of input.orderedProjects) {
+        if (!PROJECT.test(project)) {
+            throw new Error(`Lifecycle project ${project} is not a normalized name.`);
+        }
+    }
+    if (input.requestedMode === 'full')
+        return full(input, 'requested-full');
+    const baseline = input.baseline;
+    if (!baseline)
+        return full(input, 'no-baseline');
+    if (baseline.receipt.outcome !== 'succeeded') {
+        return full(input, 'baseline-not-succeeded');
+    }
+    if (baseline.receipt.stage !== input.stage) {
+        return full(input, 'baseline-stage-differs');
+    }
+    if (baseline.receipt.source.commit !== baseline.commit) {
+        return full(input, 'baseline-commit-differs');
+    }
+    if (baseline.receipt.frameworkVersion !== input.frameworkVersion) {
+        return full(input, 'framework-version-changed');
+    }
+    if (input.changedGoverningFiles.length > 0) {
+        return full(input, 'governing-files-changed:' +
+            [...input.changedGoverningFiles].sort().join(','));
+    }
+    if (input.affectedProjects === null)
+        return full(input, 'affected-unavailable');
+    const affected = new Set(input.affectedProjects);
+    const succeeded = new Set(baseline.receipt.children
+        .filter(({ outcome, target }) => target === 'deploy' && outcome === 'succeeded')
+        .map(({ project }) => project));
+    const projects = Object.fromEntries(input.orderedProjects.map((project) => [
+        project,
+        affected.has(project) || !succeeded.has(project)
+            ? 'deploy'
+            : 'skip-unchanged',
+    ]));
+    const deployed = Object.values(projects).filter((decision) => decision === 'deploy').length;
+    return {
+        baseline: {
+            commit: baseline.commit,
+            runAttempt: baseline.runAttempt,
+            runId: baseline.runId,
+        },
+        mode: 'affected',
+        projects,
+        reason: deployed === input.orderedProjects.length
+            ? 'affected:all'
+            : deployed === 0
+                ? 'affected:none'
+                : 'affected',
+    };
+}
+//# sourceMappingURL=affected-lifecycle.js.map

package/src/workspace-deployment/identity.d.ts

@@ -0,0 +1,3 @@
+export declare const WORKSPACE_DEPLOYMENT_ID_PATTERN: RegExp;
+export declare function createWorkspaceDeploymentId(createUuid?: () => string): string;
+export declare function normalizeWorkspaceDeploymentId(value: unknown): string;

package/src/workspace-deployment/identity.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WORKSPACE_DEPLOYMENT_ID_PATTERN = void 0;
+exports.createWorkspaceDeploymentId = createWorkspaceDeploymentId;
+exports.normalizeWorkspaceDeploymentId = normalizeWorkspaceDeploymentId;
+const node_crypto_1 = require("node:crypto");
+exports.WORKSPACE_DEPLOYMENT_ID_PATTERN = /^ebkws-[a-f0-9]{32}$/u;
+function createWorkspaceDeploymentId(createUuid = node_crypto_1.randomUUID) {
+    const uuid = createUuid();
+    if (!/^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/u.test(uuid)) {
+        throw new Error('Workspace deployment identity generation requires one lowercase UUIDv4.');
+    }
+    return `ebkws-${uuid.replace(/-/g, '')}`;
+}
+function normalizeWorkspaceDeploymentId(value) {
+    if (typeof value !== 'string' ||
+        !exports.WORKSPACE_DEPLOYMENT_ID_PATTERN.test(value)) {
+        throw new Error('Workspace deployment ID must be ebkws- followed by exactly 128 bits of lowercase hexadecimal identity.');
+    }
+    return value;
+}
+//# sourceMappingURL=identity.js.map

package/src/workspace-deployment/index.d.ts

@@ -0,0 +1,4 @@
+export * from './affected-lifecycle.js';
+export * from './identity.js';
+export * from './migration.js';
+export * from './ownership.js';

package/src/workspace-deployment/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./affected-lifecycle.js"), exports);
+tslib_1.__exportStar(require("./identity.js"), exports);
+tslib_1.__exportStar(require("./migration.js"), exports);
+tslib_1.__exportStar(require("./ownership.js"), exports);
+//# sourceMappingURL=index.js.map