@flisk-sh/flisk 0.0.0-stage → 1.3.189

package/engine/Tiltfile

@@ -0,0 +1,86 @@
+# =============================================================================
+# 🎯 FLISK-ENGINE - Core Execution Engine
+# =============================================================================
+# This is the Tiltfile entry point for the tdk-engine repo.
+# It exports core orchestration, resource builders, and topology management.
+#
+# Usage:
+#   v1alpha1.extension_repo(name='tdk-engine', url='https://github.com/tdk-landscape/tdk-engine')
+#   load('ext://tdk-engine', 'Utils', 'Manifest', 'Config', ...)
+# =============================================================================
+
+# Core
+load('./topologies/tilt/common/utils.star', _Utils='Utils')
+load('./topologies/tilt/discovery/loading.star', _Manifest='Manifest')
+load('./topologies/tilt/config/global.star', _Config='Config')
+load('./topologies/platform/docker/build/frontend_build_plan.star', _frontend_build_plan='frontend_build_plan')
+
+# Registry
+load('./topologies/tilt/discovery/registry.star',
+    _GLOBAL_CONFIG_EXPORT='GLOBAL_CONFIG_EXPORT',
+    _APP_RESOURCES='APP_RESOURCES',
+    _INFRA_RESOURCES_EXPORT='INFRA_RESOURCES_EXPORT',
+    _DDD_LIBS_EXPORT='DDD_LIBS_EXPORT',
+    _DEFAULTS_EXPORT='DEFAULTS_EXPORT',
+    _RESOURCE_ALIASES='RESOURCE_ALIASES',
+    _RESOURCE_PATH_MAP='RESOURCE_PATH_MAP',
+    _get_platform_libs_export='get_platform_libs_export',
+    _get_product_libs_export='get_product_libs_export',
+)
+
+# Providers
+load('./topologies/tilt/generators/vite_config.star', _Vite='Vite')
+load('./topologies/tilt/generators/tsconfig.star', _TSConfig='TSConfig')
+load('./topologies/platform/docker/index.star', _Docker='Docker')
+load('./topologies/tilt/generators/npmrc.star', _PackageConfig='PackageConfig')
+
+# Lifecycle
+load('./topologies/tilt/resources/deps.star', _Libs='Libs')
+load('./topologies/tilt/resources/conditions.star', _Database='Database')
+load('./topologies/tilt/resources/declaration.star', _Orchestrator='Orchestrator')
+load('./topologies/tilt/resources/ordering.star', _Infra='Infra')
+load('./topologies/tilt/resources/triggers.star', _Watchers='Watchers')
+load('./topologies/tilt/resources/orchestrator/apply_compose_resource_registration.star', _resource_defers_start='resource_defers_start')
+
+# =============================================================================
+# RE-EXPORTS
+# =============================================================================
+
+# Core
+Utils = _Utils
+Manifest = _Manifest
+Config = _Config
+FrontendBuildPlan = _frontend_build_plan
+
+# Registry Data
+GLOBAL_CONFIG_EXPORT = _GLOBAL_CONFIG_EXPORT
+APP_RESOURCES = _APP_RESOURCES
+INFRA_RESOURCES_EXPORT = _INFRA_RESOURCES_EXPORT
+DDD_LIBS_EXPORT = _DDD_LIBS_EXPORT
+DEFAULTS_EXPORT = _DEFAULTS_EXPORT
+RESOURCE_ALIASES = _RESOURCE_ALIASES
+RESOURCE_PATH_MAP = _RESOURCE_PATH_MAP
+
+def get_platform_libs_export():
+    return _get_platform_libs_export()
+
+def get_product_libs_export():
+    return _get_product_libs_export()
+
+# Providers
+Vite = _Vite
+TSConfig = _TSConfig
+Docker = _Docker
+PackageConfig = _PackageConfig
+
+# Lifecycle
+Libs = _Libs
+Database = _Database
+Orchestrator = _Orchestrator
+Infra = _Infra
+Watchers = _Watchers
+
+# True when a manifest's deferStart is actually active (licensed); decides whether a `<name>-image` prebuild resource exists.
+resource_defers_start = _resource_defers_start
+
+print("✅ Flisk Engine loaded: orchestration, resources, and lifecycle")

package/engine/assets/docker/golden-layers.Dockerfile

@@ -0,0 +1,204 @@
+###############################################################################
+# 🛑 CRITICAL: SYSTEM-GENERATED FILE - DO NOT MODIFY DIRECTLY
+#
+# ANY MANUAL CHANGES MADE TO THIS FILE WILL BE WIPED ON THE NEXT 'tilt up'.
+# TO MODIFY THIS CONFIGURATION:
+# 1. Edit the source generator in: .tilt/topologies/
+# 2. Or update service.json
+#
+# Generation Source: GoldenImage.generate_layered_dockerfile()
+# Service: tdk-project-l1-l4
+# Type: GOLDEN LAYERED IMAGES | L1-L4 Pre-built Layers
+###############################################################################
+
+# =============================================================================
+# 🏗️ GOLDEN LAYERED IMAGES - Multi-Stage Base Images
+# =============================================================================
+# This Dockerfile builds 8 golden images:
+#   - tdk-project-l1:latest - OS base + Bun runtime
+#   - tdk-project-l2:latest - Dependencies installed
+#   - tdk-project-l3-backend:latest - Backend and migrator build tools (Prisma, no Infisical CLI)
+#   - tdk-project-l3-frontend:latest - Frontend build tools (no Prisma)
+#   - tdk-project-l4-backend:latest - Backend production runtime (Bun)
+#   - tdk-project-l4-backend-node:latest - Backend production runtime (Node.js)
+#   - tdk-project-l4-frontend:latest - Frontend production runtime (Nginx)
+#   - tdk-project-l4-migrator:latest - Migrator production runtime
+#
+# Migrators build on l3-backend: a separate l3-migrator stage installed the same Prisma
+# and produced identical layers under a second image name.
+#
+# Services use these as base images to skip heavy dependency installation.
+#
+# ⚠️ SKIP_INFISICAL_SETUP Support:
+#   All generated Dockerfiles support --build-arg SKIP_INFISICAL_SETUP=1
+#   to bypass Infisical CLI installation (avoids Cloudsmith CDN hangs).
+#   When SKIP_INFISICAL_SETUP=1, secrets are read from env vars only.
+#   See: .tilt/topologies/platform/docker/layers/l3_builder_layers.star
+# =============================================================================
+
+# =============================================================================
+# L1: OS BASE + RUNTIME ENVIRONMENT
+# =============================================================================
+FROM oven/bun:1.3.11-alpine@sha256:7ed9f74c326d1c260abe247ac423ccbf5ac92af62bb442d515d1f92f21e8ea9b AS l1_golden
+
+LABEL layer="l1"       description="OS base with runtime environment"       maintainer="tdk-project"
+
+# System dependencies for all services
+RUN apk add --no-cache     ca-certificates     tzdata     curl     file     bash     openssl
+
+# Create app user/group for security
+RUN addgroup -S app && adduser -S app -G app
+
+# Runtime environment
+ENV NODE_ENV=development     BUN_INSTALL_CACHE_DIR=/cache/bun
+
+WORKDIR /app
+
+
+# =============================================================================
+# L2: DEPENDENCY RESOLVER
+# =============================================================================
+FROM l1_golden AS l2_golden
+
+LABEL layer="l2"       description="Base with common dependencies installed"       maintainer="tdk-project"
+
+# Install minimal debugging tools (removed: vim, python3, make, g++ = -67MB)
+RUN apk add --no-cache     curl     netcat-openbsd     jq     bind-tools
+
+# Pre-create cache directories
+RUN mkdir -p /cache/bun /cache/prisma
+
+# Bun is already installed in base image
+RUN echo "Bun version: $(bun --version)"
+
+
+# =============================================================================
+# L3-BACKEND: BACKEND BUILD TOOLS (PRISMA)
+# =============================================================================
+FROM l2_golden AS l3_backend_golden
+
+LABEL layer="l3-backend"       description="Backend build tools with Prisma"       maintainer="tdk-project"
+
+# Install Prisma CLI globally (pinned for deterministic builds)
+RUN bun add -g prisma@7.5.0 @prisma/client@7.5.0
+
+# Verify Prisma installation
+RUN echo "Prisma version: $(bunx prisma --version | head -1)"
+
+# ⚠️ CRITICAL: Infisical CLI is NOT installed in golden L3 images
+# Reason: curl to dl.cloudsmith.io hangs during Docker builds when CDN is slow
+# Solution: Use SKIP_INFISICAL_SETUP=1 build arg or runtime env var injection
+# Services read secrets from environment variables at runtime (no CLI needed)
+# See: .tilt/topologies/platform/docker/layers/l3_builder_layers.star
+
+
+# =============================================================================
+# L3-FRONTEND: FRONTEND BUILD TOOLS (NO PRISMA)
+# =============================================================================
+FROM l2_golden AS l3_frontend_golden
+
+LABEL layer="l3-frontend"       description="Frontend build tools without Prisma"       maintainer="tdk-project"
+
+# Frontend doesn't need Prisma, just verify Bun
+RUN echo "Bun version: $(bun --version)"
+
+
+# =============================================================================
+# L4-BACKEND-BUN: BACKEND PRODUCTION RUNTIME (BUN)
+# =============================================================================
+FROM l1_golden AS l4_backend_bun
+
+LABEL layer="l4-backend-bun"       description="Backend production runtime (Bun)"       maintainer="tdk-project"
+
+ENV NODE_ENV=production
+
+# Install hugo for services that require static site generation (specified via manifest features)
+RUN apk add --no-cache hugo
+
+# ⚠️ Infisical CLI is NOT installed in golden L4 images
+# Services use TypeScript SDK (fetch API) or read from env vars - no CLI needed
+# The entrypoint.sh gracefully handles missing CLI (falls back to env vars)
+# Build with --build-arg SKIP_INFISICAL_SETUP=1 to skip CLI installation
+
+USER bun
+
+# Backend-specific healthcheck (checks Bun runtime)
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3   CMD bun --version || exit 1
+
+WORKDIR /app
+
+
+# =============================================================================
+# L4-BACKEND-NODE: BACKEND PRODUCTION RUNTIME (NODE.JS - LIGHTWEIGHT!)
+# =============================================================================
+FROM node:22-alpine@sha256:0a7108bf6c7bf5de370ffb1a3ed6be93d405b43ff159f681a8d18c0e2bc2e402 AS l4_backend_node
+
+LABEL layer="l4-backend-node"       description="Backend production runtime (Node.js - lightweight)"       maintainer="tdk-project"
+
+ENV NODE_ENV=production
+
+# Minimal runtime dependencies
+RUN apk add --no-cache ca-certificates tzdata curl
+
+# Create app user for security
+RUN addgroup -S app && adduser -S app -G app
+
+# ⚠️ Infisical CLI is NOT installed in golden L4 images
+# Services read secrets from environment variables at runtime
+
+USER app
+
+# Backend-specific healthcheck (checks Node.js runtime)
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3   CMD node --version || exit 1
+
+WORKDIR /app
+
+
+# Alias for backwards compatibility - defaults to Bun (most efficient)
+FROM l4_backend_bun AS l4_backend_golden
+
+
+# =============================================================================
+# L4-FRONTEND: FRONTEND PRODUCTION RUNTIME
+# =============================================================================
+FROM nginx:1.27-alpine@sha256:65645c7bb6a0661892a8b03b89d0743208a18dd2f3f17a54ef4b76fb8e2f2a10 AS l4_frontend_golden
+
+LABEL layer="l4-frontend"       description="Frontend production runtime with Nginx"       maintainer="tdk-project"
+
+ENV NODE_ENV=production
+
+# Install curl for healthchecks
+RUN apk add --no-cache curl
+
+# Frontend-specific healthcheck (checks Nginx)
+HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3   CMD curl -f http://localhost/ || exit 1
+
+WORKDIR /usr/share/nginx/html
+
+
+# =============================================================================
+# L4-MIGRATOR: MIGRATOR PRODUCTION RUNTIME
+# =============================================================================
+FROM l1_golden AS l4_migrator_golden
+
+LABEL layer="l4-migrator"       description="Migrator runtime with Prisma"       maintainer="tdk-project"
+
+ENV NODE_ENV=production
+
+# Copy global Prisma installation from L3 (l3-backend carries the same pinned Prisma)
+COPY --from=l3_backend_golden /root/.bun/install/global /root/.bun/install/global
+
+# ⚠️ Infisical CLI is NOT included in golden L4 images
+# The migrator reads secrets directly from environment variables at runtime
+# (no entrypoint wrapper needed for database migrations)
+# Use --build-arg SKIP_INFISICAL_SETUP=1 to skip CLI installation in derived images
+
+# Ensure Bun cache path is writable for non-root runtime healthcheck commands.
+RUN mkdir -p /cache/bun && chown -R bun:bun /cache/bun
+
+USER bun
+
+# Migrator-specific healthcheck (checks Prisma CLI)
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3   CMD bunx prisma --version || exit 1
+
+WORKDIR /app

package/engine/assets/docker/wake-gateway/Dockerfile

@@ -0,0 +1,28 @@
+# Wake gateway (see openspec/changes/prioritized-cold-start): fronts every
+# `sablier.deferStart` resource's Traefik static route, triggers cold
+# containers via `tilt trigger` and/or Sablier, then holds the request until
+# healthy. Needs the Docker CLI plus its Compose plugin (client only, talks
+# to the mounted /var/run/docker.sock; compose starts an already-built image
+# directly, ahead of Tilt's build queue) and the real `tilt` CLI (D3: shells out to the
+# documented `tilt trigger` command rather than depending on Tilt's
+# undocumented internal HTTP API).
+
+FROM oven/bun:1.3.11-alpine@sha256:7ed9f74c326d1c260abe247ac423ccbf5ac92af62bb442d515d1f92f21e8ea9b AS base
+
+# Pin to the same Tilt version this workspace runs (v0.37.7) so `tilt trigger`
+# talks the same protocol as the real daemon it's connecting to. Installed
+# directly (not via tilt-dev's install.sh, which shells out to `sudo` -- not
+# present in this minimal image, and unnecessary since we're already root).
+ARG TILT_VERSION=0.37.7
+RUN apk add --no-cache docker-cli docker-cli-compose curl gcompat \
+    && arch="$(uname -m)" \
+    && case "$arch" in aarch64) tilt_arch=arm64 ;; x86_64) tilt_arch=x86_64 ;; *) echo "unsupported arch: $arch" >&2; exit 1 ;; esac \
+    && curl -fsSL "https://github.com/tilt-dev/tilt/releases/download/v${TILT_VERSION}/tilt.${TILT_VERSION}.linux.${tilt_arch}.tar.gz" \
+       | tar -xz -C /usr/local/bin tilt
+
+WORKDIR /app
+COPY decide.ts server.ts ./
+
+EXPOSE 9999
+HEALTHCHECK --interval=10s --timeout=3s --start-period=10s --retries=3 CMD curl --fail --silent http://127.0.0.1:${PORT:-9999}/health || exit 1
+CMD ["bun", "run", "server.ts"]

package/engine/assets/docker/wake-gateway/decide.test.ts

@@ -0,0 +1,177 @@
+// Copyright (c) 2026 Flisk Landscape contributors
+// SPDX-License-Identifier: MIT
+import { describe, expect, test } from "bun:test";
+import {
+  COMPOSE_START_TIMEOUT_MS,
+  EARLY_RESPONSE_MS,
+  MAX_EARLY_RESPONSE_MS,
+  RETRY_AFTER_SECONDS,
+  TILT_TRIGGER_TIMEOUT_MS,
+  decideWakeAction,
+  earlyResponseMs,
+  evaluateReadiness,
+  isGatewayLivenessProbe,
+  wakeTimeoutMs,
+} from "./decide";
+
+describe("decideWakeAction", () => {
+  test("never-created resource: tilt trigger only, no Sablier start", () => {
+    const action = decideWakeAction({
+      resourceContainerName: "data-governance-api",
+      resourceState: "absent",
+      dependencies: [],
+    });
+    expect(action.tiltTriggerNames).toEqual(["data-governance-api"]);
+    expect(action.useSablierStart).toBe(false);
+  });
+
+  test("previously-run, now-exited resource: both tilt trigger and Sablier start", () => {
+    const action = decideWakeAction({
+      resourceContainerName: "data-governance-api",
+      resourceState: "exited",
+      dependencies: [],
+    });
+    expect(action.tiltTriggerNames).toEqual(["data-governance-api"]);
+    expect(action.useSablierStart).toBe(true);
+  });
+
+  test("created-but-not-started resource: both paths apply", () => {
+    const action = decideWakeAction({
+      resourceContainerName: "data-governance-api",
+      resourceState: "created",
+      dependencies: [],
+    });
+    expect(action.useSablierStart).toBe(true);
+  });
+
+  test("already running: no trigger needed", () => {
+    const action = decideWakeAction({
+      resourceContainerName: "data-governance-api",
+      resourceState: "running",
+      dependencies: [],
+    });
+    expect(action.tiltTriggerNames).toEqual([]);
+    expect(action.useSablierStart).toBe(false);
+  });
+
+  test("cold dependency is triggered alongside the resource (task 1.5 finding)", () => {
+    const action = decideWakeAction({
+      resourceContainerName: "data-governance-api",
+      resourceState: "absent",
+      dependencies: [
+        { name: "postgres", state: "running" },
+        { name: "data-governance-api-db-migrator", state: "absent" },
+      ],
+    });
+    expect(action.tiltTriggerNames).toEqual([
+      "data-governance-api",
+      "data-governance-api-db-migrator",
+    ]);
+  });
+
+  test("never-created resource with compose details: started directly, not queued in Tilt", () => {
+    const action = decideWakeAction({
+      resourceContainerName: "data-governance-api",
+      resourceState: "absent",
+      dependencies: [{ name: "peer-api", state: "absent" }],
+      hasComposeInvocation: true,
+    });
+    expect(action.useComposeStart).toBe(true);
+    // Dependencies carry no compose details, so they still go through Tilt.
+    expect(action.tiltTriggerNames).toEqual(["peer-api"]);
+    expect(action.useSablierStart).toBe(false);
+  });
+
+  test("existing (exited) container keeps the Sablier path even with compose details", () => {
+    const action = decideWakeAction({
+      resourceContainerName: "data-governance-api",
+      resourceState: "exited",
+      dependencies: [],
+      hasComposeInvocation: true,
+    });
+    expect(action.useComposeStart).toBe(false);
+    expect(action.tiltTriggerNames).toEqual(["data-governance-api"]);
+    expect(action.useSablierStart).toBe(true);
+  });
+
+  test("running dependency is not re-triggered", () => {
+    const action = decideWakeAction({
+      resourceContainerName: "data-governance-api",
+      resourceState: "running",
+      dependencies: [{ name: "postgres", state: "running" }],
+    });
+    expect(action.tiltTriggerNames).toEqual([]);
+  });
+});
+
+describe("wakeTimeoutMs", () => {
+  test("a direct compose start only waits for boot + healthcheck", () => {
+    expect(wakeTimeoutMs(true)).toBe(COMPOSE_START_TIMEOUT_MS);
+  });
+
+  test("the tilt trigger path allows for an image build, under Bun's 255s idle cap", () => {
+    expect(wakeTimeoutMs(false)).toBe(TILT_TRIGGER_TIMEOUT_MS);
+    expect(TILT_TRIGGER_TIMEOUT_MS).toBeLessThan(255_000);
+  });
+
+  test("an explicit X-Wake-Timeout-Ms wins", () => {
+    expect(wakeTimeoutMs(false, 5_000)).toBe(5_000);
+  });
+});
+
+describe("earlyResponseMs", () => {
+  test("holds a waking request for EARLY_RESPONSE_MS by default", () => {
+    expect(earlyResponseMs()).toBe(EARLY_RESPONSE_MS);
+  });
+
+  test("the default answers well before Bun's 255s idle cap drops the connection", () => {
+    expect(EARLY_RESPONSE_MS).toBeLessThan(255_000);
+  });
+
+  test("an explicit X-Wake-Respond-Within-Ms wins, but is capped under Bun's idle limit", () => {
+    expect(earlyResponseMs(5_000)).toBe(5_000);
+    expect(earlyResponseMs(600_000)).toBe(MAX_EARLY_RESPONSE_MS);
+    expect(MAX_EARLY_RESPONSE_MS).toBeLessThan(255_000);
+  });
+
+  test("tells the caller to retry soon", () => {
+    expect(RETRY_AFTER_SECONDS).toBeGreaterThan(0);
+    expect(RETRY_AFTER_SECONDS * 1000).toBeLessThan(EARLY_RESPONSE_MS);
+  });
+});
+
+describe("evaluateReadiness", () => {
+  test("ready once every required name reports healthy", () => {
+    const outcome = evaluateReadiness(["a", "b"], { a: true, b: true });
+    expect(outcome.ready).toBe(true);
+    expect(outcome.pending).toEqual([]);
+  });
+
+  test("not ready while some names are still unhealthy", () => {
+    const outcome = evaluateReadiness(["a", "b"], { a: true, b: false });
+    expect(outcome.ready).toBe(false);
+    expect(outcome.pending).toEqual(["b"]);
+  });
+
+  test("missing entries count as not healthy", () => {
+    const outcome = evaluateReadiness(["a", "b"], { a: true });
+    expect(outcome.ready).toBe(false);
+    expect(outcome.pending).toEqual(["b"]);
+  });
+});
+
+describe("isGatewayLivenessProbe", () => {
+  test("a bare GET /health from the image HEALTHCHECK is answered by the gateway", () => {
+    expect(isGatewayLivenessProbe("GET", "/health", new Headers())).toBe(true);
+  });
+
+  test("a backend /health routed through the wake gateway is proxied, not answered", () => {
+    const routed = new Headers({ "X-Wake-Resource": "cold-api", "X-Wake-Container": "cold-api-1" });
+    expect(isGatewayLivenessProbe("GET", "/health", routed)).toBe(false);
+  });
+
+  test("other methods and paths are not liveness probes", () => {
+    expect(isGatewayLivenessProbe("POST", "/health", new Headers())).toBe(false);
+    expect(isGatewayLivenessProbe("GET", "/health/ready", new Headers())).toBe(false);
+  });
+});

package/engine/assets/docker/wake-gateway/decide.ts

@@ -0,0 +1,135 @@
+// Copyright (c) 2026 Flisk contributors
+// SPDX-License-Identifier: MIT
+/**
+ * Pure decision logic for the wake gateway (see openspec/changes/prioritized-cold-start).
+ *
+ * The gateway sits behind a Traefik static (file-provider) route for every
+ * `sablier: {enable: true, deferStart: true}` resource. This module decides
+ * what to *do* given a snapshot of container state; the actual Docker/Tilt
+ * I/O and the healthcheck-polling loop live in server.ts, which is a thin
+ * wrapper around this so the decision itself stays testable without a live
+ * Docker daemon or Tilt instance.
+ */
+
+export type ContainerState = "absent" | "created" | "running" | "exited";
+
+export interface DependencySnapshot {
+  name: string;
+  state: ContainerState;
+}
+
+export interface WakeRequestSnapshot {
+  resourceContainerName: string;
+  resourceState: ContainerState;
+  dependencies: DependencySnapshot[];
+  /**
+   * Whether the route carried enough compose detail (project, files, image)
+   * for the gateway to create the resource's container itself.
+   */
+  hasComposeInvocation?: boolean;
+}
+
+export interface WakeAction {
+  /** Resources to `tilt trigger` (task 1.5: Tilt never cascades this on its own). */
+  tiltTriggerNames: string[];
+  /**
+   * Whether to create/start the resource's container directly with
+   * `docker compose up --no-build` instead of `tilt trigger`. `tilt trigger`
+   * only queues the resource: with Tilt's build slots busy (e.g. 100+
+   * resources rebuilding after a re-vendor), a triggered resource waited
+   * behind them and the request timed out (observed live against
+   * tdk-erp-system, see tasks.md 7.2). server.ts falls back to `tilt trigger`
+   * when no image exists yet to start from.
+   */
+  useComposeStart: boolean;
+  /**
+   * Whether to also try Sablier's own Docker-level start for the resource.
+   * Only meaningful when the resource's container already exists (D2/D3):
+   * Sablier has nothing to manage for a container that was never created.
+   */
+  useSablierStart: boolean;
+}
+
+/**
+ * Decide which resources need `tilt trigger` and whether Sablier's Docker-level
+ * start also applies, given one point-in-time snapshot (D2/D3/D5).
+ */
+export function decideWakeAction(snapshot: WakeRequestSnapshot): WakeAction {
+  const tiltTriggerNames: string[] = [];
+  const useComposeStart = snapshot.resourceState === "absent" && snapshot.hasComposeInvocation === true;
+
+  if (snapshot.resourceState !== "running" && !useComposeStart) {
+    tiltTriggerNames.push(snapshot.resourceContainerName);
+  }
+  for (const dep of snapshot.dependencies) {
+    if (dep.state !== "running") {
+      tiltTriggerNames.push(dep.name);
+    }
+  }
+
+  const useSablierStart = snapshot.resourceState === "exited" || snapshot.resourceState === "created";
+
+  return { tiltTriggerNames, useComposeStart, useSablierStart };
+}
+
+/** Wait budget when the gateway starts an existing image itself (boot + healthcheck only). */
+export const COMPOSE_START_TIMEOUT_MS = 180_000;
+/**
+ * Wait budget when the resource has to go through `tilt trigger` (image build
+ * included). Kept under Bun.serve's 255s idleTimeout cap in server.ts.
+ */
+export const TILT_TRIGGER_TIMEOUT_MS = 240_000;
+
+/** The wait budget for a wake: an explicit X-Wake-Timeout-Ms wins, else by start path. */
+export function wakeTimeoutMs(startedViaCompose: boolean, overrideMs?: number): number {
+  if (overrideMs && overrideMs > 0) return overrideMs;
+  return startedViaCompose ? COMPOSE_START_TIMEOUT_MS : TILT_TRIGGER_TIMEOUT_MS;
+}
+
+/**
+ * How long a waking request is held before the gateway answers
+ * `503` + `Retry-After` while the start keeps going in the background.
+ * Found live (task 7.2): during a full `flisk up` bring-up the Docker daemon
+ * took ~5 min to start one container, and Bun.serve's 255s idle cap dropped
+ * the held connection with no response at all.
+ */
+export const EARLY_RESPONSE_MS = 60_000;
+/** Largest hold allowed: stays under Bun.serve's 255s idle cap. */
+export const MAX_EARLY_RESPONSE_MS = 240_000;
+/** The `Retry-After` value sent with the early 503. */
+export const RETRY_AFTER_SECONDS = 10;
+
+/** How long to hold a request: an explicit X-Wake-Respond-Within-Ms wins, capped under Bun's idle limit. */
+export function earlyResponseMs(overrideMs?: number): number {
+  if (overrideMs && overrideMs > 0) return Math.min(overrideMs, MAX_EARLY_RESPONSE_MS);
+  return EARLY_RESPONSE_MS;
+}
+
+export interface WaitOutcome {
+  ready: boolean;
+  /** Names still not running/healthy when the wait ended (empty when ready). */
+  pending: string[];
+}
+
+/**
+ * Decide whether a set of health polls (resource + dependencies) means the
+ * request can be let through yet, or should keep waiting / time out.
+ * `healthy` maps each name from a WakeAction's tiltTriggerNames (plus the
+ * resource itself) to its latest observed health state.
+ */
+export function evaluateReadiness(
+  requiredNames: string[],
+  healthy: Record<string, boolean>,
+): WaitOutcome {
+  const pending = requiredNames.filter((name) => !healthy[name]);
+  return { ready: pending.length === 0, pending };
+}
+
+/**
+ * True for the gateway's own liveness probe (the image HEALTHCHECK's `GET /health`). Traefik's static route
+ * forwards every backend request here with its X-Wake-* headers and the backend's prefix stripped, so a
+ * backend's `/health` arrives as `/health` too; those must be proxied, not answered by the gateway.
+ */
+export function isGatewayLivenessProbe(method: string, pathname: string, headers: Headers): boolean {
+  return method === "GET" && pathname === "/health" && !headers.has("X-Wake-Resource");
+}