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

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

package/src/foundation/local-private-smoke-access.d.ts

@@ -0,0 +1,20 @@
+import { type FleetProcessIdentity, type ProcessIdentityProbe } from '../local-dev/fleet-lock.js';
+import { type PrivateStateSecurity } from '../local-dev/private-state.js';
+import { openPrivateSmokeControlPlane } from './private-smoke-control-plane.js';
+import type { GithubPrivateSmokeInput } from './private-smoke-access.js';
+export interface LocalPrivateSmokeInput extends GithubPrivateSmokeInput {
+    /** Already verified invocation-private transport, never ambient credentials. */
+    credentialEnvironment: NodeJS.ProcessEnv;
+}
+interface Dependencies {
+    fetch?: typeof fetch;
+    open?: typeof openPrivateSmokeControlPlane;
+    capture?: () => FleetProcessIdentity;
+    probe?: (owner: FleetProcessIdentity) => ProcessIdentityProbe;
+    security?: PrivateStateSecurity;
+    wait?: (milliseconds: number) => Promise<void>;
+}
+/** Used after the local lifecycle verifies source, policy and federated role.
+ * A private process receipt proves recovery ownership, not deployment authority. */
+export declare function runLocalPrivateSmoke(input: LocalPrivateSmokeInput, dependencies?: Dependencies): Promise<void>;
+export {};