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

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,9 +1,13 @@
 export * from './discovery.js';
+export * from './capability-plan.js';
 export * from './local-database-contract.js';
 export * from './logging.js';
 export * from './logging-preflight.js';
+export * from './partial-state.js';
 export * from './provision-database-bindings.js';
 export * from './provision-logical-database.js';
 export * from './requirements.js';
 export * from './router-origin-proof.js';
+export * from './router-waf.js';
+export declare function cleanupGithubPrivateSmoke(...args: Parameters<typeof import('./private-smoke-access.js').cleanupGithubPrivateSmoke>): Promise<void>;
 export * from './stages.js';

package/src/foundation/index.js

@@ -1,13 +1,24 @@
 "use strict";
 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);
+tslib_1.__exportStar(require("./partial-state.js"), exports);
 tslib_1.__exportStar(require("./provision-database-bindings.js"), exports);
 tslib_1.__exportStar(require("./provision-logical-database.js"), exports);
 tslib_1.__exportStar(require("./requirements.js"), exports);
 tslib_1.__exportStar(require("./router-origin-proof.js"), exports);
+tslib_1.__exportStar(require("./router-waf.js"), exports);
+// SST bundles this infrastructure entry point. Keep the workflow-only AWS
+// control plane lazy: its external SDK resolves from the installed package
+// when the generated GitHub finalizer calls it, not from an SST config bundle.
+async function cleanupGithubPrivateSmoke(...args) {
+    const { cleanupGithubPrivateSmoke: cleanup } = await Promise.resolve().then(() => require('./private-smoke-access.js'));
+    return cleanup(...args);
+}
 tslib_1.__exportStar(require("./stages.js"), exports);
 //# sourceMappingURL=index.js.map

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>;

package/src/foundation/local-database-contract.js

@@ -6,6 +6,15 @@ exports.postgresIdentifierByteLength = postgresIdentifierByteLength;
 exports.assertPostgresIdentifierLength = assertPostgresIdentifierLength;
 exports.resolveLogicalDatabaseIdentifiers = resolveLogicalDatabaseIdentifiers;
 exports.resolveLocalDatabaseContract = resolveLocalDatabaseContract;
+exports.prepareLocalDatabaseContract = prepareLocalDatabaseContract;
+exports.runLocalDatabaseLifecycle = runLocalDatabaseLifecycle;
+const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const ports_js_1 = require("../local-dev/ports.js");
+const private_state_js_1 = require("../local-dev/private-state.js");
+const task_identity_js_1 = require("../local-dev/task-identity.js");
 exports.POSTGRES_IDENTIFIER_MAX_BYTES = 63;
 function normalizePostgresIdentifier(input) {
     const sanitized = input.replace(/[^A-Za-z0-9_]/g, '_');
@@ -22,7 +31,7 @@ function postgresIdentifierByteLength(identifier) {
 function assertPostgresIdentifierLength(identifier, label) {
     const bytes = postgresIdentifierByteLength(identifier);
     if (bytes > exports.POSTGRES_IDENTIFIER_MAX_BYTES) {
-        throw new Error(`${label} "${identifier}" is ${bytes} UTF-8 bytes; PostgreSQL identifiers must be ${exports.POSTGRES_IDENTIFIER_MAX_BYTES} bytes or fewer. Choose a shorter stage, Slice, or database identifier. Identifiers are never truncated.`);
+        throw new Error(`${label} "${identifier}" is ${bytes} UTF-8 bytes; PostgreSQL identifiers must be ${exports.POSTGRES_IDENTIFIER_MAX_BYTES} bytes or fewer. Shorten a user-selected Slice or database identifier before deployment; framework task stages are not user-selectable. Identifiers are never truncated.`);
     }
 }
 function resolveLogicalDatabaseIdentifiers(options) {
@@ -54,25 +63,265 @@ function resolveLogicalDatabaseIdentifiers(options) {
         readwriteRole,
     };
 }
-function deterministicLocalDatabasePort(key) {
-    let hash = 5381;
-    for (let index = 0; index < key.length; index += 1) {
-        hash = (hash * 33) ^ key.charCodeAt(index);
+function databaseIdentity(options) {
+    if (!/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(options.slice)) {
+        throw new Error('Local Slice must be a DNS-safe identifier.');
     }
-    return 54320 + (Math.abs(hash) % 100);
-}
-function resolveLocalDatabaseContract(options) {
-    const database = normalizePostgresIdentifier(`${options.slice}_${options.database}`);
+    if (!/^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$/.test(options.database)) {
+        throw new Error('Local database must be a logical database identifier.');
+    }
+    const workspaceRoot = (0, node_fs_1.realpathSync)(options.workspaceRoot ??
+        (0, node_child_process_1.execFileSync)('git', [
+            '--no-optional-locks',
+            '-c',
+            'core.fsmonitor=false',
+            'rev-parse',
+            '--show-toplevel',
+        ], {
+            cwd: process.cwd(),
+            encoding: 'utf8',
+            timeout: 5_000,
+            env: Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_'))),
+            stdio: ['ignore', 'pipe', 'pipe'],
+        }).trim());
+    const { taskId } = (0, task_identity_js_1.resolveTaskIdentity)(workspaceRoot);
+    const stage = (0, task_identity_js_1.taskStage)(taskId);
+    if (options.stage !== undefined && options.stage !== stage) {
+        throw new Error(`Local database stage does not match this worktree's task (${stage}).`);
+    }
+    const readableDatabase = normalizePostgresIdentifier(`t_${taskId}_${options.slice.length}_${options.slice}_${options.database}`);
+    // Preserve every previously valid allocation. Overlength names were never
+    // accepted, so use a bounded task + tuple digest only for that new domain.
+    const database = postgresIdentifierByteLength(`${readableDatabase}_readwrite`) <=
+        exports.POSTGRES_IDENTIFIER_MAX_BYTES
+        ? readableDatabase
+        : `t_${taskId}_${(0, node_crypto_1.createHash)('sha256')
+            .update(JSON.stringify([options.slice, options.database]))
+            .digest('hex')
+            .slice(0, 24)}`;
     const username = `${database}_readwrite`;
     assertPostgresIdentifierLength(database, 'Local database identifier');
     assertPostgresIdentifierLength(username, 'Local read-write role identifier');
+    const directory = (0, node_path_1.join)((0, node_path_1.dirname)((0, task_identity_js_1.taskIdentityPath)(workspaceRoot)), 'databases', taskId);
     return {
+        taskId,
+        stage,
+        directory,
+        path: (0, node_path_1.join)(directory, `${options.slice.length}-${options.slice}-${options.database}.json`),
+        project: `ebk-${taskId}-${options.slice.length}-${options.slice}-${options.database}`,
         database,
-        host: '127.0.0.1',
-        password: options.password ?? `${options.slice}-local-dev`,
-        port: options.port ??
-            deterministicLocalDatabasePort(`${options.slice}_${options.database}`),
         username,
     };
 }
+function readDatabaseContract(options, identity) {
+    if (!allocationExists(identity.path)) {
+        throw new Error(`Local database allocation is missing. Run the ${options.slice} local-database up target before connecting.`);
+    }
+    const record = JSON.parse((0, private_state_js_1.readPrivateFile)(identity.path).toString('utf8'));
+    if (record.schemaVersion !== 1 ||
+        record.taskId !== identity.taskId ||
+        record.slice !== options.slice ||
+        record.logicalDatabase !== options.database ||
+        record.database !== identity.database ||
+        record.username !== identity.username ||
+        record.host !== '127.0.0.1' ||
+        typeof record.password !== 'string' ||
+        !record.password ||
+        !Number.isSafeInteger(record.port) ||
+        record.port < 1024 ||
+        record.port > 65535 ||
+        (options.port !== undefined && options.port !== record.port) ||
+        (options.password !== undefined && options.password !== record.password)) {
+        throw new Error('Local database allocation ownership or connection coordinates do not match; refusing to connect.');
+    }
+    return {
+        database: record.database,
+        host: '127.0.0.1',
+        password: record.password,
+        port: record.port,
+        username: record.username,
+    };
+}
+function allocationExists(path) {
+    try {
+        (0, node_fs_1.lstatSync)(path);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+/** Read the same private allocation used by Docker, Drizzle, and SST links. */
+function resolveLocalDatabaseContract(options) {
+    return readDatabaseContract(options, databaseIdentity(options));
+}
+/** Prepare coordinates only; Docker's bind remains authoritative against races. */
+async function prepareLocalDatabaseContract(options, isAvailable = ports_js_1.canBindLoopbackPort) {
+    const identity = databaseIdentity(options);
+    if (allocationExists(identity.path))
+        return readDatabaseContract(options, identity);
+    const reserved = new Set();
+    if ((0, node_fs_1.existsSync)(identity.directory)) {
+        for (const name of (0, node_fs_1.readdirSync)(identity.directory)) {
+            if (name.endsWith('.json')) {
+                const sibling = JSON.parse((0, private_state_js_1.readPrivateFile)((0, node_path_1.join)(identity.directory, name)).toString('utf8'));
+                if (Number.isSafeInteger(sibling.port))
+                    reserved.add(sibling.port);
+            }
+        }
+    }
+    let port = options.port;
+    if (port !== undefined) {
+        if (!Number.isSafeInteger(port) ||
+            port < 1024 ||
+            port > 65535 ||
+            reserved.has(port) ||
+            !(await isAvailable(port))) {
+            throw new Error('Requested local database port is invalid, reserved, or occupied.');
+        }
+    }
+    else {
+        port = await (0, ports_js_1.allocateFleetPort)(identity.project, { isAvailable, reserved });
+    }
+    (0, private_state_js_1.publishPrivateFileExclusive)(identity.path, `${JSON.stringify({
+        schemaVersion: 1,
+        taskId: identity.taskId,
+        slice: options.slice,
+        logicalDatabase: options.database,
+        database: identity.database,
+        host: '127.0.0.1',
+        password: options.password ?? `${identity.taskId}-local-dev`,
+        port,
+        username: identity.username,
+    })}\n`);
+    return readDatabaseContract(options, identity);
+}
+/** Exact-owned local Docker lifecycle. Volumes and allocation survive down. */
+async function runLocalDatabaseLifecycle(options, dependencies = {}) {
+    const environment = dependencies.environment ?? process.env;
+    const overrides = Object.keys(environment).filter((key) => key.startsWith('COMPOSE_') && environment[key] !== undefined);
+    if (overrides.length)
+        throw new Error(`Ambient Compose overrides are not allowed: ${overrides.join(', ')}.`);
+    const identity = databaseIdentity(options);
+    let local = allocationExists(identity.path)
+        ? readDatabaseContract(options, identity)
+        : undefined;
+    const env = {
+        ...environment,
+        ...(local
+            ? {
+                EBK_LOCAL_DATABASE: local.database,
+                EBK_LOCAL_DATABASE_PASSWORD: local.password,
+                EBK_LOCAL_DATABASE_PORT: String(local.port),
+                EBK_LOCAL_DATABASE_USERNAME: local.username,
+            }
+            : {}),
+        EBK_LOCAL_DATABASE_PROJECT: identity.project,
+        EBK_LOCAL_DATABASE_TASK: identity.taskId,
+        EBK_LOCAL_DATABASE_SLICE: options.slice,
+        EBK_LOCAL_DATABASE_LOGICAL: options.database,
+    };
+    const docker = dependencies.docker ??
+        ((args, childEnvironment) => (0, node_child_process_1.spawnSync)('docker', args, {
+            env: childEnvironment,
+            encoding: 'utf8',
+            timeout: 120_000,
+            windowsHide: true,
+        }));
+    const run = (args) => {
+        const result = docker(args, env);
+        if (result.error)
+            throw result.error;
+        return result;
+    };
+    const inspect = (kind, name) => {
+        const result = run([kind, 'inspect', name]);
+        if (result.status !== 0) {
+            if (/No such (?:object|container|volume|network)/i.test(result.stderr) ||
+                (kind === 'network' &&
+                    result.stderr.includes(`network ${name} not found`)))
+                return undefined;
+            throw new Error(`Unable to inspect exact local database ${kind}; check Docker availability before retrying.`);
+        }
+        const records = JSON.parse(result.stdout);
+        if (!Array.isArray(records) || records.length !== 1)
+            throw new Error('Ambiguous local database Docker ownership.');
+        const record = records[0];
+        const labels = kind === 'container' ? record.Config?.Labels : record.Labels;
+        if (labels?.['dev.ebk.task'] !== identity.taskId ||
+            labels?.['dev.ebk.slice'] !== options.slice ||
+            labels?.['dev.ebk.database'] !== options.database ||
+            labels?.['com.docker.compose.project'] !== identity.project) {
+            throw new Error(`Local database ${kind} ownership mismatch; refusing creation or cleanup.`);
+        }
+        if (kind === 'container' && local) {
+            const bindings = record.HostConfig?.PortBindings?.['5432/tcp'];
+            if (!Array.isArray(bindings) ||
+                bindings.length !== 1 ||
+                bindings[0].HostIp !== '127.0.0.1' ||
+                bindings[0].HostPort !== String(local.port)) {
+                throw new Error('Local database container port ownership mismatch; refusing to connect.');
+            }
+        }
+        return record;
+    };
+    const container = inspect('container', `${identity.project}-database`);
+    const volume = inspect('volume', `${identity.project}-data`);
+    const network = inspect('network', `${identity.project}-network`);
+    if (!local) {
+        if (container || volume || network) {
+            throw new Error('Local database allocation is missing while exact Docker resources remain. Restore the original private allocation before up or down; no coordinates were created and no resources were removed.');
+        }
+        // Missing coordinates are not absence evidence; exact Docker inspection is.
+        if (options.action === 'down')
+            return;
+        local = await prepareLocalDatabaseContract(options, dependencies.isAvailable);
+        Object.assign(env, {
+            EBK_LOCAL_DATABASE: local.database,
+            EBK_LOCAL_DATABASE_PASSWORD: local.password,
+            EBK_LOCAL_DATABASE_PORT: String(local.port),
+            EBK_LOCAL_DATABASE_USERNAME: local.username,
+        });
+    }
+    if (options.action === 'down') {
+        // Never issue project-wide cleanup; use the verified immutable container ID.
+        if (container) {
+            if (typeof container.Id !== 'string' ||
+                !/^[a-f0-9]{64}$/.test(container.Id))
+                throw new Error('Invalid owned container ID.');
+            if (run(['container', 'rm', '--force', container.Id]).status !== 0)
+                throw new Error('Owned local database container cleanup failed; retry down.');
+        }
+        if (network) {
+            if (typeof network.Id !== 'string' || !/^[a-f0-9]{64}$/.test(network.Id))
+                throw new Error('Invalid owned network ID.');
+            if (run(['network', 'rm', network.Id]).status !== 0)
+                throw new Error('Owned local database network cleanup failed; inspect its remaining endpoints.');
+        }
+        return;
+    }
+    if (!container &&
+        !(await (dependencies.isAvailable ?? ports_js_1.canBindLoopbackPort)(local.port))) {
+        throw new Error(`Task database port ${local.port} is occupied by another service. Free that exact port and retry; no connection was made.`);
+    }
+    const result = run([
+        'compose',
+        '--env-file',
+        process.platform === 'win32' ? 'NUL' : '/dev/null',
+        '--project-name',
+        identity.project,
+        '-f',
+        options.composeFile,
+        'up',
+        '-d',
+        '--wait',
+    ]);
+    if (result.status !== 0) {
+        throw new Error(`Task database startup failed (possible port bind race). Run this task's local-database down, resolve the Docker/port conflict, then retry up.`);
+    }
+    if (!inspect('container', `${identity.project}-database`))
+        throw new Error('Docker reported success without the exact owned local database container.');
+}
 //# sourceMappingURL=local-database-contract.js.map