refactor(stack): restore service factory locality

packages/stack/README.md

@@ -214,6 +214,10 @@ start, restart, activation, and reload operations; a call-specific option overri
 deadline fails with `STACK_READINESS_TIMEOUT` and disposes the local runtime, so the handle cannot
 be used to relaunch processes afterward.
 
+When no readiness policy is configured, request-triggered lazy activation expands the three-minute
+default to cover the target service's complete transitive startup budget. An explicitly configured
+finite or infinite stack policy remains authoritative.
+
 ### Status
 
 ```typescript

packages/stack/docs/architecture.md

@@ -56,6 +56,10 @@ reload, and explicit readiness waits. A finite deadline fails with `StackReadine
 the same scoped cleanup used by disposal. Promise and remote Adapters pass `ReadyOptions` through
 to that Implementation instead of layering a second timeout rule around it.
 
+Request-triggered lazy activation expands the package-default deadline when a service's transitive
+startup budget is longer than three minutes. Explicit finite and infinite stack policies are never
+expanded.
+
 The current zero-config stack enables PostgreSQL, PostgREST, Auth, and Edge Runtime. Realtime,
 Storage, imgproxy, Mailpit, Postgres Meta, Studio, Analytics, Vector, and Supavisor are enabled only
 when their corresponding configuration object is present. In `native` mode, Edge Runtime is also
@@ -93,7 +97,9 @@ runtime.
 
 `StackBuilder.build(config, prepared)` is the explicit owner of cross-service topology. Individual
 factories under `src/services/` own executable arguments, environment, mounts, health checks, and
-per-process cleanup. The builder owns which definitions exist and how they depend on one another.
+per-process cleanup. Docker factories also own their host-network and port-mapping arguments. The
+builder owns which definitions exist and how they depend on one another, including the choice
+between `postgres-init (completed)` and `postgres (healthy)` for every database consumer.
 
 | Public service | Automatic runtime support               | Principal dependency or role                                                                                       |
 | -------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
@@ -213,8 +219,10 @@ binding. Supervised Docker services have a wider window because the supervisor s
 
 Every Docker definition has ordinary in-process cleanup and supervisor-owned orphan cleanup.
 `StackBuilder` also returns exact Docker container names for the definitions it constructed. The
-coordinator persists these targets for managed daemons and uses them as a force-removal safety net
-after graceful stop. Auto-created PostgreSQL, Storage, and runtime paths are also removed.
+local Implementation captures these targets before persistence or orchestrator setup, persists
+them for managed daemons, and uses them as a force-removal safety net after graceful stop. Launch,
+exact cleanup, and candidate cleanup all derive container identity through the same naming
+function. Auto-created PostgreSQL, Storage, and runtime paths are also removed.
 
 Cleanup is intentionally defensive:
 
@@ -223,7 +231,8 @@ Cleanup is intentionally defensive:
    external resources;
 3. stack disposal force-removes exact known Docker containers;
 4. managed `stop` can use persisted cleanup metadata after daemon death;
-5. startup failure has candidate cleanup derived from the requested configuration.
+5. a failure before the exact build plan exists has candidate cleanup derived from enabled catalog
+   services; a partial startup failure disposes the exact build-produced plan.
 
 These paths overlap by design and must remain idempotent.
 

packages/stack/src/CleanupTargets.ts

@@ -1,4 +1,5 @@
 import { Schema } from "effect";
+import type { ServiceName } from "./ServiceName.ts";
 
 export interface CleanupTargets {
   readonly dockerContainerNames: ReadonlyArray<string>;
@@ -7,3 +8,6 @@ export interface CleanupTargets {
 export const CleanupTargetsSchema = Schema.Struct({
   dockerContainerNames: Schema.Array(Schema.String),
 });
+
+export const dockerContainerName = (service: ServiceName, apiPort: number): string =>
+  `supabase-${service}-${apiPort}`;

packages/stack/src/DaemonServer.ts

@@ -19,6 +19,7 @@ export class DaemonServer extends Context.Service<
   DaemonServer,
   {
     readonly address: HttpServer.Address;
+    readonly beginShutdown: Effect.Effect<void>;
     readonly awaitShutdown: Effect.Effect<void>;
   }
 >()("stack/DaemonServer") {
@@ -366,6 +367,7 @@ export class DaemonServer extends Context.Service<
 
         return {
           address: server.address,
+          beginShutdown,
           awaitShutdown: Deferred.await(shutdownDeferred),
         };
       }),

packages/stack/src/LocalStack.ts

@@ -23,6 +23,7 @@ import { configureFunctionsRuntime, type FunctionsConfig } from "./functions.ts"
 import { detectPlatform, dockerHostAddress } from "./Platform.ts";
 import type { PortLease } from "./PortAllocator.ts";
 import {
+  activationReadinessPolicy,
   activationTargetsForService,
   eagerServices,
   lifecycleTargetsForService,
@@ -58,11 +59,19 @@ type LifecyclePhase =
 
 type StackService = typeof Stack.Service;
 
+/** Private signal used by the Promise adapter to close its enclosing managed runtime. */
+export class LocalStackLifecycle extends Context.Service<
+  LocalStackLifecycle,
+  {
+    readonly awaitDisposed: Effect.Effect<void>;
+    readonly isDisposed: Effect.Effect<boolean>;
+  }
+>()("stack/LocalStackLifecycle") {}
+
 interface RuntimeState {
   readonly orchestrator: Orchestrator["Service"];
   readonly graph: ResolvedGraph;
   readonly serviceProjection: StackServiceProjectionCatalog;
-  readonly cleanupTargets: CleanupTargets;
 }
 
 const initialPublicStates = (config: ResolvedStackConfig): ReadonlyArray<StackServiceState> =>
@@ -147,7 +156,7 @@ export const localStackLayer = (
   config: ResolvedStackConfig,
   portLease: PortLease,
 ): Layer.Layer<
-  Stack | StackServiceActivator,
+  Stack | StackServiceActivator | LocalStackLifecycle,
   StackBuildError,
   | StackBuilder
   | StackPreparation
@@ -170,6 +179,7 @@ export const localStackLayer = (
       const enabledServices = enabledServicesForConfig(config);
       const stateRef = yield* SubscriptionRef.make(initialPublicStates(config));
       const phaseRef = yield* Ref.make<LifecyclePhase>("idle");
+      const disposedSignal = yield* Deferred.make<void>();
       const lifecycleLock = Semaphore.makeUnsafe(1);
       const projectionLock = Semaphore.makeUnsafe(1);
 
@@ -223,6 +233,7 @@ export const localStackLayer = (
       let prepareDeferred: Deferred.Deferred<PreparedStackArtifacts, StackBuildError> | undefined;
       let runtimeState: RuntimeState | undefined;
       let runtimeDeferred: Deferred.Deferred<RuntimeState, StackBuildError> | undefined;
+      let exactCleanupTargets: CleanupTargets | undefined;
 
       const ensurePrepared = Effect.suspend(() => {
         if (preparedArtifacts !== undefined) {
@@ -337,6 +348,7 @@ export const localStackLayer = (
             config,
             prepared,
           );
+          exactCleanupTargets = cleanupTargets;
 
           yield* metadataPersistence.persistCleanupTargets(cleanupTargets).pipe(
             Effect.mapError(
@@ -366,7 +378,6 @@ export const localStackLayer = (
             orchestrator,
             graph,
             serviceProjection,
-            cleanupTargets,
           } satisfies RuntimeState;
         }).pipe(
           Effect.tap((value) =>
@@ -596,14 +607,17 @@ export const localStackLayer = (
             yield* cleanupLocalStackResources({
               stop: () =>
                 runtimeState === undefined ? Effect.void : runtimeState.orchestrator.stop(),
-              cleanupTargets: runtimeState?.cleanupTargets ?? { dockerContainerNames: [] },
+              cleanupTargets: exactCleanupTargets ?? { dockerContainerNames: [] },
               config,
             }).pipe(
               Effect.ensuring(portLease.releaseAll),
               Effect.ensuring(Ref.set(phaseRef, "disposed")),
             );
           }).pipe(withLifecycleLock);
-        }).pipe(Effect.uninterruptible);
+        }).pipe(
+          Effect.ensuring(Deferred.succeed(disposedSignal, undefined).pipe(Effect.asVoid)),
+          Effect.uninterruptible,
+        );
 
       const withReadinessPolicy = <A, E, R>(
         effect: Effect.Effect<A, E, R>,
@@ -639,7 +653,6 @@ export const localStackLayer = (
             disposeOnce().pipe(Effect.andThen(Effect.fail(error))),
           ),
         );
-
       yield* Effect.addFinalizer(disposeOnce);
 
       const activateService = (name: ServiceName) =>
@@ -654,7 +667,13 @@ export const localStackLayer = (
             return;
           }
           if (existing !== undefined) {
-            yield* waitForTargets(existing).pipe((effect) => withReadinessPolicy(effect, name));
+            yield* waitForTargets(existing).pipe((effect) =>
+              withReadinessPolicy(
+                effect,
+                name,
+                activationReadinessPolicy(service, config.readiness, config.readinessSource),
+              ),
+            );
             return;
           }
           const started = yield* Effect.gen(function* () {
@@ -663,17 +682,25 @@ export const localStackLayer = (
             if (concurrentlyStarted !== undefined) return concurrentlyStarted;
             return yield* beginStartTargets(service, new Set());
           }).pipe(withLifecycleLock);
-          yield* waitForTargets(started).pipe((effect) => withReadinessPolicy(effect, name));
+          yield* waitForTargets(started).pipe((effect) =>
+            withReadinessPolicy(
+              effect,
+              name,
+              activationReadinessPolicy(service, config.readiness, config.readinessSource),
+            ),
+          );
         }).pipe(cleanupOnReadinessFailure);
 
       const stack = {
         getInfo: () => Effect.succeed(info),
-        start: () =>
-          Effect.gen(function* () {
+        start: () => {
+          let serviceStartupBegan = false;
+          return Effect.gen(function* () {
             yield* requireMutable("start");
             yield* Ref.set(phaseRef, "starting");
             const runtime = yield* ensureRuntime;
             yield* configureFunctions(config);
+            serviceStartupBegan = true;
 
             if (config.startupMode === "lazy") {
               const readiness: Array<Effect.Effect<void, ServiceReadyError | StackBuildError>> = [];
@@ -718,8 +745,9 @@ export const localStackLayer = (
           }).pipe(
             Effect.onError(() => Ref.set(phaseRef, "stopped")),
             withLifecycleLock,
-            cleanupOnReadinessFailure,
-          ),
+            Effect.onError(() => (serviceStartupBegan ? disposeOnce() : Effect.void)),
+          );
+        },
         stop: () =>
           Effect.gen(function* () {
             if (disposed) {
@@ -889,6 +917,10 @@ export const localStackLayer = (
 
       return Context.make(Stack, stack).pipe(
         Context.add(StackServiceActivator, { activate: activateService }),
+        Context.add(LocalStackLifecycle, {
+          awaitDisposed: Deferred.await(disposedSignal),
+          isDisposed: Effect.sync(() => disposed),
+        }),
       );
     }),
   );

packages/stack/src/ServiceActivation.ts

@@ -5,6 +5,7 @@ import { StackBuildError, StackNotRunningError, StackReadinessError } from "./er
 import { stackServiceStartupBudgetSeconds } from "./services/health-budgets.ts";
 import { SERVICE_NAMES, serviceMetadata } from "./ServiceCatalog.ts";
 import type { ServiceName } from "./ServiceName.ts";
+import type { ReadinessPolicy } from "./StackConfig.ts";
 
 export const eagerServices = (enabled: ReadonlyArray<ServiceName>): ReadonlyArray<ServiceName> =>
   enabled.filter((service) => serviceMetadata(service).activation.startup === "eager");
@@ -46,6 +47,19 @@ export const activationTimeoutSecondsForService = (service: ServiceName): number
   );
 };
 
+/**
+ * The package default expands for services whose transitive startup budget is
+ * longer than three minutes. An explicit stack policy remains authoritative.
+ */
+export const activationReadinessPolicy = (
+  service: ServiceName,
+  stackPolicy: ReadinessPolicy,
+  source: "default" | "configured",
+): ReadinessPolicy =>
+  source === "default"
+    ? { mode: "finite", timeoutMs: activationTimeoutSecondsForService(service) * 1000 }
+    : stackPolicy;
+
 /** Services exclusively owned by a public service for stop/restart operations. */
 export const lifecycleTargetsForService = (
   enabledServices: ReadonlyArray<ServiceName>,

packages/stack/src/ServiceActivation.unit.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest";
 import {
+  activationReadinessPolicy,
   activationTimeoutSecondsForService,
   activationTargetsForService,
   eagerServices,
@@ -50,6 +51,18 @@ describe("service activation", () => {
     expect(activationTimeoutSecondsForService("studio")).toBe(825);
   });
 
+  it("expands only the package-default activation deadline", () => {
+    expect(
+      activationReadinessPolicy("analytics", { mode: "finite", timeoutMs: 180_000 }, "default"),
+    ).toEqual({ mode: "finite", timeoutMs: 554_000 });
+    expect(
+      activationReadinessPolicy("analytics", { mode: "finite", timeoutMs: 10_000 }, "configured"),
+    ).toEqual({ mode: "finite", timeoutMs: 10_000 });
+    expect(activationReadinessPolicy("analytics", { mode: "infinite" }, "configured")).toEqual({
+      mode: "infinite",
+    });
+  });
+
   it("does not assign shared public dependencies to their consumers", () => {
     expect(lifecycleTargetsForService(SERVICE_NAMES, "storage")).toEqual(["storage", "imgproxy"]);
     expect(lifecycleTargetsForService(SERVICE_NAMES, "analytics")).toEqual(["analytics", "vector"]);