@empire-builder-kit/nx 1.0.0-rc.37 → 1.0.0-rc.39

package/src/executors/sst-lifecycle/task-unlock.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCurrentTaskUnlock = runCurrentTaskUnlock;
+const devkit_1 = require("@nx/devkit");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const index_js_1 = require("../../aws-authority/index.js");
+const fleet_launcher_js_1 = require("../../local-dev/fleet-launcher.js");
+const local_context_js_1 = require("../../local-dev/local-context.js");
+const task_authority_js_1 = require("../../local-dev/task-authority.js");
+const task_identity_js_1 = require("../../local-dev/task-identity.js");
+const task_native_writer_js_1 = require("../../local-dev/task-native-writer.js");
+const task_stack_absence_js_1 = require("../dev-task-cleanup/task-stack-absence.js");
+const federated_credential_transport_js_1 = require("../local-deploy/federated-credential-transport.js");
+const local_deploy_js_1 = require("../local-deploy/local-deploy.js");
+const run_sst_command_js_1 = require("./run-sst-command.js");
+async function runCurrentTaskUnlock(options, context, dependencies = {}) {
+    let transport, success = false;
+    try {
+        const environment = dependencies.environment ?? process.env;
+        if (Object.keys(options).some((key) => ![
+            'args',
+            'cwd',
+            'expectedRoleArn',
+            'foundationStage',
+            'profile',
+            'region',
+            'stage',
+            'stageMode',
+            'target',
+        ].includes(key)))
+            throw new Error('Task unlock received an unsupported option.');
+        if (environment.GITHUB_ACTIONS === 'true')
+            throw new Error('Task unlock is local to the current owning worktree.');
+        const task = (0, task_identity_js_1.resolveTaskIdentity)(context.root), stage = (0, task_identity_js_1.taskStage)(task.taskId);
+        const project = context.projectName
+            ? context.projectsConfigurations?.projects[context.projectName]
+            : undefined;
+        if (options.stage !== stage ||
+            options.stageMode !== 'consumer' ||
+            !project?.tags?.includes('type:slice') ||
+            project.tags.includes('scope:foundation'))
+            throw new Error('Task unlock requires the exact current task and one Product Slice.');
+        if (options.profile !== undefined ||
+            options.region !== undefined ||
+            options.expectedRoleArn !== undefined ||
+            options.target !== undefined ||
+            (options.args !== undefined &&
+                (!Array.isArray(options.args) || options.args.length !== 0)) ||
+            (options.foundationStage !== undefined &&
+                options.foundationStage !== 'development'))
+            throw new Error('Task unlock does not accept AWS, target, argument, or Foundation overrides.');
+        const projectRoot = (0, node_fs_1.realpathSync)((0, node_path_1.join)(context.root, project.root));
+        if (options.cwd !== undefined &&
+            (0, node_fs_1.realpathSync)((0, node_path_1.isAbsolute)(options.cwd) ? options.cwd : (0, node_path_1.join)(context.root, options.cwd)) !== projectRoot)
+            throw new Error('Task unlock cwd must equal its generated Slice project root.');
+        (0, task_stack_absence_js_1.resolveStaticTaskApp)({
+            workspaceRoot: context.root,
+            projectRoot,
+            projectName: context.projectName,
+        });
+        const saved = (0, local_context_js_1.readSavedLocalDevContext)((0, fleet_launcher_js_1.resolveGitCommonDirectory)(context.root));
+        if (saved.kind !== 'ready')
+            throw new Error('Task unlock requires the saved development AWS context. Run ebk dev configure.');
+        const verified = await (0, task_authority_js_1.verifyTaskEnvironment)(context.root, saved.resolution.context, dependencies.authority);
+        (0, task_identity_js_1.assertCurrentTaskEnvironment)(context.root, verified);
+        const source = (0, local_deploy_js_1.localWorkingTreeDigest)(context.root);
+        (0, task_native_writer_js_1.assertTaskNativeWritersAbsent)(context, dependencies.writers);
+        const region = verified.region;
+        const expectedRoleArn = (0, index_js_1.createStageAuthorityIdentity)({
+            accountId: verified.accountId,
+            region,
+            stage: 'development',
+            partition: region.startsWith('cn-')
+                ? 'aws-cn'
+                : region.startsWith('us-gov-')
+                    ? 'aws-us-gov'
+                    : 'aws',
+        }).deploymentRoleArn;
+        transport = await (dependencies.createTransport ?? federated_credential_transport_js_1.createLocalFederatedCredentialTransport)({
+            account: verified.accountId,
+            expectedRoleArn,
+            profile: saved.resolution.context.profile,
+            region,
+        });
+        await transport.refresh();
+        if ((0, task_identity_js_1.assertCurrentTaskEnvironment)(context.root, verified).taskId !==
+            task.taskId ||
+            JSON.stringify((0, local_deploy_js_1.localWorkingTreeDigest)(context.root)) !==
+                JSON.stringify(source))
+            throw new Error('Task unlock source or ownership changed during authorization.');
+        (0, task_native_writer_js_1.assertTaskNativeWritersAbsent)(context, dependencies.writers);
+        success = (await (dependencies.run ?? run_sst_command_js_1.runSstCommand)('unlock', {
+            stage,
+            stageMode: 'consumer',
+            foundationStage: 'development',
+            profile: transport.profile,
+            region,
+            expectedRoleArn,
+        }, context, {
+            environment: {
+                ...transport.childEnvironment(environment),
+                AWS_EXPECTED_ACCOUNT_ID: verified.accountId,
+                AWS_REGION: region,
+                EBK_NX_TASK_UNLOCK: task.taskId,
+                EBK_SOURCE_COMMIT: source.commit,
+                EBK_LOCAL_SOURCE_TREE: source.digest,
+            },
+            taskNativeWriterEffects: dependencies.writers,
+        })).success;
+    }
+    catch (error) {
+        devkit_1.logger.error(`Task unlock failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    finally {
+        try {
+            transport?.cleanup();
+        }
+        catch {
+            success = false;
+            devkit_1.logger.error('Task unlock credential cleanup failed; acceptance is blocked.');
+        }
+    }
+    return { success };
+}
+//# sourceMappingURL=task-unlock.js.map

package/src/foundation/capability-plan.d.ts

@@ -0,0 +1,43 @@
+/** Resource capability version, independent of the requirement-document schema. */
+export declare const FOUNDATION_CAPABILITY_CONTRACT_VERSION: "2.0.0";
+/** Known generated-source migration only; never accepted as a live v2 contract. */
+export declare const LEGACY_STANDARD_FOUNDATION_CAPABILITIES: readonly ["network", "routing", "container-compute", "postgres", "identity", "events", "observability", "configuration", "deployment"];
+export declare const FOUNDATION_BASE_CAPABILITIES: readonly ["key-value", "routing", "identity", "events", "observability", "configuration", "deployment"];
+export declare const FOUNDATION_CAPABILITY_VOCABULARY: readonly ["key-value", "routing", "identity", "events", "observability", "configuration", "deployment", "network", "container-compute", "postgres"];
+export type FoundationCapability = (typeof FOUNDATION_CAPABILITY_VOCABULARY)[number];
+export interface FoundationCapabilityDescriptor {
+    contractVersion: typeof FOUNDATION_CAPABILITY_CONTRACT_VERSION;
+    capabilities: FoundationCapability[];
+}
+export interface FoundationCapabilityRequirement {
+    contract: string;
+    capabilities: FoundationCapability[];
+}
+export interface StandardSqlDeclaration {
+    reason: string;
+}
+export interface FoundationCapabilityPlan {
+    descriptor: FoundationCapabilityDescriptor;
+    added: FoundationCapability[];
+    retained: FoundationCapability[];
+    migratedFromContract: '1.0.0' | null;
+    resources: {
+        containerCompute: boolean;
+        network: boolean;
+        postgres: boolean;
+    };
+}
+/** Absence means DynamoDB-first; false/null is never a database retirement instruction. */
+export declare function readStandardSqlDeclaration(inputs: unknown): StandardSqlDeclaration | null;
+export declare function standardPersistenceRequirement(inputs: unknown, compositions?: readonly {
+    kind: string;
+}[]): FoundationCapabilityRequirement;
+/**
+ * Pure generation plan. Existing declarations are monotonic: removing a Slice
+ * cannot remove a database, network, or cluster. Retirement is a separate operation.
+ * This function never reads AWS and does not attest that resources are deployed.
+ */
+export declare function planFoundationCapabilities(options: {
+    current?: unknown;
+    requirements: readonly unknown[];
+}): FoundationCapabilityPlan;

package/src/foundation/capability-plan.js

@@ -0,0 +1,168 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FOUNDATION_CAPABILITY_VOCABULARY = exports.FOUNDATION_BASE_CAPABILITIES = exports.LEGACY_STANDARD_FOUNDATION_CAPABILITIES = exports.FOUNDATION_CAPABILITY_CONTRACT_VERSION = void 0;
+exports.readStandardSqlDeclaration = readStandardSqlDeclaration;
+exports.standardPersistenceRequirement = standardPersistenceRequirement;
+exports.planFoundationCapabilities = planFoundationCapabilities;
+const semver_1 = require("semver");
+const validation_js_1 = require("../validation.js");
+/** Resource capability version, independent of the requirement-document schema. */
+exports.FOUNDATION_CAPABILITY_CONTRACT_VERSION = '2.0.0';
+/** Known generated-source migration only; never accepted as a live v2 contract. */
+exports.LEGACY_STANDARD_FOUNDATION_CAPABILITIES = [
+    'network',
+    'routing',
+    'container-compute',
+    'postgres',
+    'identity',
+    'events',
+    'observability',
+    'configuration',
+    'deployment',
+];
+exports.FOUNDATION_BASE_CAPABILITIES = [
+    'key-value',
+    'routing',
+    'identity',
+    'events',
+    'observability',
+    'configuration',
+    'deployment',
+];
+exports.FOUNDATION_CAPABILITY_VOCABULARY = [
+    ...exports.FOUNDATION_BASE_CAPABILITIES,
+    'network',
+    'container-compute',
+    'postgres',
+];
+function requireCapabilities(value, label) {
+    if (!Array.isArray(value))
+        throw new Error(`${label} must be an array.`);
+    const seen = new Set();
+    for (const capability of value) {
+        if (typeof capability !== 'string' ||
+            !exports.FOUNDATION_CAPABILITY_VOCABULARY.some((known) => known === capability) ||
+            seen.has(capability)) {
+            throw new Error(`${label} contains an unknown or duplicate capability.`);
+        }
+        seen.add(capability);
+    }
+    return [...value];
+}
+function requireExactKeys(value, keys, label) {
+    if (Object.keys(value).some((key) => !keys.includes(key))) {
+        throw new Error(`${label} contains unsupported properties.`);
+    }
+}
+/** Absence means DynamoDB-first; false/null is never a database retirement instruction. */
+function readStandardSqlDeclaration(inputs) {
+    if (!(0, validation_js_1.isRecord)(inputs))
+        throw new Error('Standard Blueprint inputs must be an object.');
+    if (!Object.prototype.hasOwnProperty.call(inputs, 'sql'))
+        return null;
+    const sql = inputs.sql;
+    if (!(0, validation_js_1.isRecord)(sql))
+        throw new Error('Standard Blueprint inputs.sql must declare a relational reason.');
+    requireExactKeys(sql, ['reason'], 'Standard Blueprint inputs.sql');
+    if (typeof sql.reason !== 'string' ||
+        sql.reason.trim().length === 0 ||
+        sql.reason.length > 512 ||
+        [...sql.reason].some((character) => {
+            const code = character.charCodeAt(0);
+            return code < 0x20 || code === 0x7f;
+        })) {
+        throw new Error('Standard Blueprint inputs.sql.reason must be a non-empty single-line rationale of at most 512 characters.');
+    }
+    return { reason: sql.reason.trim() };
+}
+function standardPersistenceRequirement(inputs, compositions = []) {
+    const sql = readStandardSqlDeclaration(inputs);
+    const containers = sql !== null ||
+        compositions.some(({ kind }) => kind === 'service' || kind === 'job');
+    return {
+        contract: '^2.0.0',
+        capabilities: [
+            ...exports.FOUNDATION_BASE_CAPABILITIES,
+            ...(containers ? ['network', 'container-compute'] : []),
+            ...(sql ? ['postgres'] : []),
+        ],
+    };
+}
+function readCurrentDescriptor(value) {
+    if (!(0, validation_js_1.isRecord)(value))
+        throw new Error('Existing Foundation descriptor must be an object.');
+    requireExactKeys(value, ['contractVersion', 'capabilities'], 'Existing Foundation descriptor');
+    const capabilities = requireCapabilities(value.capabilities, 'Existing Foundation capabilities');
+    const available = new Set(capabilities);
+    if (value.contractVersion === '1.0.0') {
+        // This is an explicit generated-source upgrade, not a live discovery fallback.
+        // The old Standard Foundation always provisioned all nine capabilities.
+        if (capabilities.length !== exports.LEGACY_STANDARD_FOUNDATION_CAPABILITIES.length ||
+            exports.LEGACY_STANDARD_FOUNDATION_CAPABILITIES.some((capability) => !available.has(capability))) {
+            throw new Error('Existing v1 Standard Foundation must retain its complete capability declaration before upgrade.');
+        }
+        return { capabilities, migratedFromContract: '1.0.0' };
+    }
+    if (value.contractVersion !== exports.FOUNDATION_CAPABILITY_CONTRACT_VERSION ||
+        exports.FOUNDATION_BASE_CAPABILITIES.some((capability) => !available.has(capability)) ||
+        (available.has('postgres') &&
+            (!available.has('network') || !available.has('container-compute'))) ||
+        (available.has('container-compute') && !available.has('network'))) {
+        throw new Error('Existing Foundation descriptor must use contract 2.0.0 with complete capability dependencies.');
+    }
+    return { capabilities, migratedFromContract: null };
+}
+/**
+ * Pure generation plan. Existing declarations are monotonic: removing a Slice
+ * cannot remove a database, network, or cluster. Retirement is a separate operation.
+ * This function never reads AWS and does not attest that resources are deployed.
+ */
+function planFoundationCapabilities(options) {
+    const current = options.current === undefined
+        ? {
+            capabilities: [],
+            migratedFromContract: null,
+        }
+        : readCurrentDescriptor(options.current);
+    const selected = new Set([
+        ...exports.FOUNDATION_BASE_CAPABILITIES,
+        ...current.capabilities,
+    ]);
+    for (const requirement of options.requirements) {
+        if (!(0, validation_js_1.isRecord)(requirement))
+            throw new Error('Foundation requirement must be an object.');
+        requireExactKeys(requirement, ['contract', 'capabilities'], 'Foundation requirement');
+        if (typeof requirement.contract !== 'string' ||
+            !requirement.contract.trim() ||
+            (0, semver_1.validRange)(requirement.contract) === null ||
+            !(0, semver_1.satisfies)(exports.FOUNDATION_CAPABILITY_CONTRACT_VERSION, requirement.contract)) {
+            throw new Error('Foundation requirement must admit contract 2.0.0; regenerate older Blueprint requirements explicitly.');
+        }
+        for (const capability of requireCapabilities(requirement.capabilities, 'Foundation requirement capabilities')) {
+            selected.add(capability);
+        }
+    }
+    // The current SQL migration implementation uses private container compute.
+    // Keep its resource dependency explicit rather than allocating NAT for every Slice.
+    if (selected.has('postgres'))
+        selected.add('container-compute');
+    if (selected.has('container-compute'))
+        selected.add('network');
+    const capabilities = exports.FOUNDATION_CAPABILITY_VOCABULARY.filter((capability) => selected.has(capability));
+    const retained = new Set(current.capabilities);
+    return {
+        descriptor: {
+            contractVersion: exports.FOUNDATION_CAPABILITY_CONTRACT_VERSION,
+            capabilities,
+        },
+        added: capabilities.filter((capability) => !retained.has(capability)),
+        retained: capabilities.filter((capability) => retained.has(capability)),
+        migratedFromContract: current.migratedFromContract,
+        resources: {
+            containerCompute: selected.has('container-compute'),
+            network: selected.has('network'),
+            postgres: selected.has('postgres'),
+        },
+    };
+}
+//# sourceMappingURL=capability-plan.js.map

package/src/foundation/discovery.d.ts

@@ -1,6 +1,6 @@
 import { type FoundationRequirement, type StandardFoundationCapability } from './requirements.js';
 export declare const FOUNDATION_SSM_NAMESPACE: "/ebk";
-export declare const FOUNDATION_SSM_SCHEMA_VERSION: 6;
+export declare const FOUNDATION_SSM_SCHEMA_VERSION: 7;
 export declare const FOUNDATION_SSM_KEYS: {
     readonly accountCostPolicyDigest: "accountCostPolicyDigest";
     readonly accountMonthlyMaximumUsd: "accountMonthlyMaximumUsd";
@@ -28,22 +28,25 @@ export declare const FOUNDATION_SSM_KEYS: {
     readonly vpcId: "vpcId";
 };
 export type FoundationSsmKey = keyof typeof FOUNDATION_SSM_KEYS;
-export declare const FOUNDATION_REQUIRED_SSM_KEYS: FoundationSsmKey[];
+export declare const FOUNDATION_POSTGRES_SSM_KEYS: readonly ["databaseClusterArn", "databaseClusterEndpoint", "databaseClusterId", "databaseClusterResourceId", "databaseHost", "databaseMasterSecretArn", "databasePort"];
+/** Required for every Foundation; optional resource capabilities add their own keys. */
+export declare const FOUNDATION_REQUIRED_SSM_KEYS: ("contractVersion" | "capabilities" | "accountCostPolicyDigest" | "accountMonthlyMaximumUsd" | "alertTopicArn" | "clusterId" | "databaseClusterArn" | "databaseClusterEndpoint" | "databaseClusterId" | "databaseClusterResourceId" | "databaseHost" | "databaseMasterSecretArn" | "databasePort" | "eventBusArn" | "eventBusName" | "hasPublicDomain" | "identityUserPoolArn" | "identityUserPoolId" | "identityTokenEndpoint" | "rootDomain" | "routerDistributionId" | "routerUrl" | "schemaVersion" | "vpcId")[];
+export declare function foundationSsmKeysForCapabilities(capabilities: readonly StandardFoundationCapability[]): FoundationSsmKey[];
 export declare const STANDARD_FOUNDATION_REQUIREMENT: FoundationRequirement;
 export interface FoundationDiscovery {
     accountCostPolicyDigest: `sha256:${string}`;
     accountMonthlyMaximumUsd: number;
     alertTopicArn: string;
     capabilities: StandardFoundationCapability[];
-    clusterId: string;
+    clusterId?: string;
     contractVersion: string;
-    databaseClusterArn: string;
-    databaseClusterEndpoint: string;
-    databaseClusterId: string;
-    databaseClusterResourceId: string;
-    databaseHost: string;
-    databaseMasterSecretArn: string;
-    databasePort: number;
+    databaseClusterArn?: string;
+    databaseClusterEndpoint?: string;
+    databaseClusterId?: string;
+    databaseClusterResourceId?: string;
+    databaseHost?: string;
+    databaseMasterSecretArn?: string;
+    databasePort?: number;
     eventBusArn: string;
     eventBusName: string;
     hasPublicDomain: boolean;
@@ -54,7 +57,7 @@ export interface FoundationDiscovery {
     routerDistributionId: string;
     routerUrl: string;
     schemaVersion: typeof FOUNDATION_SSM_SCHEMA_VERSION;
-    vpcId: string;
+    vpcId?: string;
 }
 export interface ProductSliceRegistration {
     consumerStage: string;

package/src/foundation/discovery.js

@@ -1,16 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.STANDARD_FOUNDATION_REQUIREMENT = exports.FOUNDATION_REQUIRED_SSM_KEYS = exports.FOUNDATION_SSM_KEYS = exports.FOUNDATION_SSM_SCHEMA_VERSION = exports.FOUNDATION_SSM_NAMESPACE = void 0;
+exports.STANDARD_FOUNDATION_REQUIREMENT = exports.FOUNDATION_REQUIRED_SSM_KEYS = exports.FOUNDATION_POSTGRES_SSM_KEYS = exports.FOUNDATION_SSM_KEYS = exports.FOUNDATION_SSM_SCHEMA_VERSION = exports.FOUNDATION_SSM_NAMESPACE = void 0;
+exports.foundationSsmKeysForCapabilities = foundationSsmKeysForCapabilities;
 exports.foundationSsmStageRoot = foundationSsmStageRoot;
 exports.foundationSsmPath = foundationSsmPath;
 exports.productSliceRegistrationRoot = productSliceRegistrationRoot;
 exports.productSliceRegistrationPath = productSliceRegistrationPath;
 exports.productSliceMigrationPath = productSliceMigrationPath;
 exports.productSliceRetentionPath = productSliceRetentionPath;
-const requirements_js_1 = require("./requirements.js");
+const capability_plan_js_1 = require("./capability-plan.js");
 const stages_js_1 = require("./stages.js");
 exports.FOUNDATION_SSM_NAMESPACE = '/ebk';
-exports.FOUNDATION_SSM_SCHEMA_VERSION = 6;
+exports.FOUNDATION_SSM_SCHEMA_VERSION = 7;
 exports.FOUNDATION_SSM_KEYS = {
     accountCostPolicyDigest: 'accountCostPolicyDigest',
     accountMonthlyMaximumUsd: 'accountMonthlyMaximumUsd',
@@ -37,10 +38,35 @@ exports.FOUNDATION_SSM_KEYS = {
     schemaVersion: 'schemaVersion',
     vpcId: 'vpcId',
 };
-exports.FOUNDATION_REQUIRED_SSM_KEYS = Object.keys(exports.FOUNDATION_SSM_KEYS);
+exports.FOUNDATION_POSTGRES_SSM_KEYS = [
+    'databaseClusterArn',
+    'databaseClusterEndpoint',
+    'databaseClusterId',
+    'databaseClusterResourceId',
+    'databaseHost',
+    'databaseMasterSecretArn',
+    'databasePort',
+];
+const conditionalKeys = new Set([
+    ...exports.FOUNDATION_POSTGRES_SSM_KEYS,
+    'vpcId',
+    'clusterId',
+]);
+/** Required for every Foundation; optional resource capabilities add their own keys. */
+exports.FOUNDATION_REQUIRED_SSM_KEYS = Object.keys(exports.FOUNDATION_SSM_KEYS).filter((key) => !conditionalKeys.has(key));
+function foundationSsmKeysForCapabilities(capabilities) {
+    return [
+        ...exports.FOUNDATION_REQUIRED_SSM_KEYS,
+        ...(capabilities.includes('network') ? ['vpcId'] : []),
+        ...(capabilities.includes('container-compute')
+            ? ['clusterId']
+            : []),
+        ...(capabilities.includes('postgres') ? exports.FOUNDATION_POSTGRES_SSM_KEYS : []),
+    ];
+}
 exports.STANDARD_FOUNDATION_REQUIREMENT = {
-    capabilities: [...requirements_js_1.STANDARD_FOUNDATION_CAPABILITIES],
-    contract: '^1.0.0',
+    capabilities: [...capability_plan_js_1.FOUNDATION_BASE_CAPABILITIES],
+    contract: '^2.0.0',
 };
 function requirePathSegment(value, label) {
     const normalized = value.trim();

package/src/foundation/index.d.ts

@@ -1,4 +1,5 @@
 export * from './discovery.js';
+export * from './capability-plan.js';
 export * from './local-database-contract.js';
 export * from './logging.js';
 export * from './logging-preflight.js';

package/src/foundation/index.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.cleanupGithubPrivateSmoke = cleanupGithubPrivateSmoke;
 const tslib_1 = require("tslib");
 tslib_1.__exportStar(require("./discovery.js"), exports);
+tslib_1.__exportStar(require("./capability-plan.js"), exports);
 tslib_1.__exportStar(require("./local-database-contract.js"), exports);
 tslib_1.__exportStar(require("./logging.js"), exports);
 tslib_1.__exportStar(require("./logging-preflight.js"), exports);

package/src/foundation/local-database-contract.d.ts

@@ -3,6 +3,8 @@ export interface LocalDatabaseContractOptions {
     password?: string;
     port?: number;
     slice: string;
+    stage?: string;
+    workspaceRoot?: string;
 }
 export interface LocalDatabaseContract {
     database: string;
@@ -28,4 +30,22 @@ export declare function resolveLogicalDatabaseIdentifiers(options: {
     slice: string;
     stage: string;
 }): LogicalDatabaseIdentifiers;
+/** Read the same private allocation used by Docker, Drizzle, and SST links. */
 export declare function resolveLocalDatabaseContract(options: LocalDatabaseContractOptions): LocalDatabaseContract;
+/** Prepare coordinates only; Docker's bind remains authoritative against races. */
+export declare function prepareLocalDatabaseContract(options: LocalDatabaseContractOptions, isAvailable?: (port: number) => Promise<boolean>): Promise<LocalDatabaseContract>;
+export type LocalDatabaseDockerCommand = (args: string[], env: NodeJS.ProcessEnv) => {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+    error?: Error;
+};
+/** Exact-owned local Docker lifecycle. Volumes and allocation survive down. */
+export declare function runLocalDatabaseLifecycle(options: LocalDatabaseContractOptions & {
+    action: 'up' | 'down';
+    composeFile: string;
+}, dependencies?: {
+    docker?: LocalDatabaseDockerCommand;
+    environment?: NodeJS.ProcessEnv;
+    isAvailable?: (port: number) => Promise<boolean>;
+}): Promise<void>;