@tdk-landscape/tdk-cli-core 1.3.117 → 1.3.118

package/cli/dist/utils/shared-platform-postgres.js

@@ -0,0 +1,211 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { DEFAULT_ALWAYS_ENABLED_INFRA } from "./project-config-defaults.js";
+import { discoverResourcesFromRoot } from "./services.js";
+/**
+ * Shared platform Postgres start predicate.
+ *
+ * Both names mean the one shared platform Postgres Tilt resource `postgres`.
+ * The engine start path is selection-bounded (tdk up --only); verify/doctor
+ * evaluate the project resource set they already inspect (no tdk up filter).
+ * Both surfaces use this same predicate shape over their own resource set.
+ *
+ * Feature state is read from project.json **and** the generated Tiltfile /
+ * spec.master when present, because a stock `tdk up` focus pass expands
+ * CORE_INFRA → database-management even when project.json omits it.
+ *
+ * Spec: openspec/changes/dependson-starts-platform-postgres
+ */
+export const POSTGRES_DEPENDENCY_NAMES = ["postgres", "database-management"];
+const PHASE_KEYS = ["pre_alpha", "alpha", "beta", "out_of_scope"];
+export function isSharedPlatformPostgresDependency(name) {
+    return POSTGRES_DEPENDENCY_NAMES.includes(name);
+}
+function readProjectJson(projectRoot) {
+    try {
+        return JSON.parse(readFileSync(join(projectRoot, ".tdk", "project.json"), "utf-8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function readTextIfExists(path) {
+    try {
+        return existsSync(path) ? readFileSync(path, "utf-8") : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseStarlarkStringList(source, name) {
+    const re = new RegExp(`${name}\\s*=\\s*\\[([^\\]]*)\\]`);
+    const m = source.match(re);
+    if (!m)
+        return undefined;
+    return [...m[1].matchAll(/"([^"]+)"|'([^']+)'/g)].map((x) => x[1] ?? x[2] ?? "");
+}
+function tiltfileAlwaysEnabledInfra(projectRoot) {
+    const path = join(projectRoot, ".tdk", ".tdk-out", "Tiltfile");
+    const text = readTextIfExists(path);
+    if (!text)
+        return undefined;
+    return parseStarlarkStringList(text, "ALWAYS_ENABLED_INFRA");
+}
+function specMasterHasDatabaseManagement(projectRoot) {
+    const path = join(projectRoot, ".tdk", ".tdk-out", "spec.master");
+    const text = readTextIfExists(path);
+    if (text === undefined)
+        return undefined;
+    // PRE_ALPHA/DEFAULTS style: "database-management": True
+    return /"database-management"\s*:\s*True/.test(text);
+}
+function generatedDefaultFocusEnablesDatabaseManagement(projectRoot) {
+    const output = join(projectRoot, ".tdk", ".tdk-out");
+    const tiltfile = readTextIfExists(join(output, "Tiltfile"));
+    const spec = readTextIfExists(join(output, "spec.master"));
+    const config = readTextIfExists(join(output, "tdk-cli-ext", "discovery", "config.star"));
+    const profiles = readTextIfExists(join(output, "tdk-cli-ext", "engine", "topologies", "tilt", "config", "profiles.star"));
+    if (!tiltfile || !spec || !config || !profiles)
+        return false;
+    const preAlpha = spec.match(/PRE_ALPHA_RESOURCES\s*=\s*\{([^}]*)\}/)?.[1];
+    const coreInfra = parseStarlarkStringList(config, "CORE_INFRA");
+    return (/FOCUS_MODE\s*,\s*FOCUS_ENABLED_ALL\s*,\s*FOCUS_ENABLED_RESOURCES\s*=\s*Config\.apply_focus\(cfg\)/.test(tiltfile) &&
+        /if FOCUS_MODE and FOCUS_ENABLED_ALL\s*:/.test(tiltfile) &&
+        /"[^"]+"\s*:\s*True|'[^']+'\s*:\s*True/.test(preAlpha ?? "") &&
+        (coreInfra?.includes("postgres") ?? false) &&
+        /["']postgres["']\s*:\s*["']database-management["']/.test(config) &&
+        /for infra in CORE_INFRA_EXPORT\s*:/.test(profiles) &&
+        /needed\[INFRA_STACK_MAP_EXPORT\[infra\]\]\s*=\s*True/.test(profiles));
+}
+function projectJsonFeatureOn(projectRoot) {
+    const parsed = readProjectJson(projectRoot);
+    if (!parsed)
+        return false;
+    const phases = (parsed.phases ?? {});
+    for (const phase of PHASE_KEYS) {
+        const stacks = phases[phase]?.enabledStacks;
+        if (Array.isArray(stacks) && stacks.includes("database-management")) {
+            return true;
+        }
+    }
+    const alwaysEnabled = parsed.always_enabled_infra ?? DEFAULT_ALWAYS_ENABLED_INFRA;
+    return Array.isArray(alwaysEnabled) && alwaysEnabled.includes("database-management");
+}
+/**
+ * True when database-management is on for this project from project.json
+ * **or** the generated Tiltfile/spec.master when those files exist.
+ */
+export function databaseManagementEnabled(projectRoot) {
+    if (projectJsonFeatureOn(projectRoot))
+        return true;
+    const fromTilt = tiltfileAlwaysEnabledInfra(projectRoot);
+    if (Array.isArray(fromTilt) && fromTilt.includes("database-management"))
+        return true;
+    if (specMasterHasDatabaseManagement(projectRoot) === true)
+        return true;
+    return false;
+}
+/** Known names for unknown-dependsOn detection: discovered services/stacks + project stacks/infra. */
+function knownDependsonNames(projectRoot) {
+    const known = new Set();
+    for (const name of POSTGRES_DEPENDENCY_NAMES)
+        known.add(name);
+    for (const resource of discoverResourcesFromRoot(projectRoot)) {
+        known.add(resource.name);
+        if (resource.stack)
+            known.add(resource.stack);
+    }
+    const parsed = readProjectJson(projectRoot);
+    if (parsed) {
+        const phases = (parsed.phases ?? {});
+        for (const phase of PHASE_KEYS) {
+            const stacks = phases[phase]?.enabledStacks;
+            if (Array.isArray(stacks)) {
+                for (const stack of stacks)
+                    known.add(stack);
+            }
+        }
+        const alwaysEnabled = parsed.always_enabled_infra ?? DEFAULT_ALWAYS_ENABLED_INFRA;
+        if (Array.isArray(alwaysEnabled)) {
+            for (const entry of alwaysEnabled)
+                known.add(entry);
+        }
+    }
+    const fromTilt = tiltfileAlwaysEnabledInfra(projectRoot);
+    if (Array.isArray(fromTilt)) {
+        for (const entry of fromTilt)
+            known.add(entry);
+    }
+    return known;
+}
+/**
+ * Evaluate whether shared platform Postgres will start for this project.
+ *
+ * willStart = featureOn OR any inspected project resource depends on either name.
+ * Resource set is project scope (discoverResourcesFromRoot), NOT tdk up --only.
+ *
+ * Also reports focusWouldEnableDatabaseManagement so doctor/verify can warn that
+ * default focus expands CORE_INFRA → database-management even when project.json
+ * says the feature is off (the 7.1 gap).
+ */
+export function evaluateSharedPlatformPostgres(projectRoot) {
+    const featureOnFromProjectJson = projectJsonFeatureOn(projectRoot);
+    const fromTilt = tiltfileAlwaysEnabledInfra(projectRoot);
+    const featureOnFromTiltfile = Array.isArray(fromTilt) && fromTilt.includes("database-management");
+    const featureOnFromSpecMaster = specMasterHasDatabaseManagement(projectRoot) === true;
+    const featureOn = featureOnFromProjectJson || featureOnFromTiltfile || featureOnFromSpecMaster;
+    const focusWouldEnableDatabaseManagement = !featureOnFromProjectJson && generatedDefaultFocusEnablesDatabaseManagement(projectRoot);
+    const known = knownDependsonNames(projectRoot);
+    const dependsOnUsers = [];
+    const unknownDependsOnNames = [];
+    for (const resource of discoverResourcesFromRoot(projectRoot)) {
+        const deps = resource.config?.dependsOn ?? [];
+        let usesSharedPostgres = false;
+        for (const dep of deps) {
+            if (isSharedPlatformPostgresDependency(dep)) {
+                usesSharedPostgres = true;
+                continue;
+            }
+            if (!known.has(dep)) {
+                unknownDependsOnNames.push({ resource: resource.name, name: dep });
+            }
+        }
+        if (usesSharedPostgres) {
+            dependsOnUsers.push(resource.name);
+        }
+    }
+    const willStart = featureOn || dependsOnUsers.length > 0;
+    const reason = featureOn
+        ? "feature"
+        : dependsOnUsers.length > 0
+            ? "dependsOn"
+            : "none";
+    return {
+        featureOn,
+        featureOnFromProjectJson,
+        featureOnFromTiltfile,
+        featureOnFromSpecMaster,
+        focusWouldEnableDatabaseManagement,
+        dependsOnUsers,
+        willStart,
+        reason,
+        unknownDependsOnNames,
+    };
+}
+/** Human-readable will-start / will-not-start sentence shared by doctor + verify. */
+export function sharedPlatformPostgresMessage(evaluation) {
+    const projectScopeNote = " (project resource set; tdk up may select a subset and not start Postgres)";
+    if (!evaluation.willStart) {
+        const focusNote = evaluation.focusWouldEnableDatabaseManagement
+            ? " Note: default focus/CORE_INFRA expansion would enable database-management on a typical tdk up even when project.json lists it off."
+            : "";
+        return `Shared platform Postgres will not start for this project.json/generated Tiltfile state (no database-management feature, no selected dependsOn).${focusNote}`;
+    }
+    const why = evaluation.reason === "feature"
+        ? `the database-management feature is enabled${evaluation.featureOnFromTiltfile || evaluation.featureOnFromSpecMaster
+            ? " (generated Tiltfile/spec.master)"
+            : ""}`
+        : `resource(s) ${evaluation.dependsOnUsers.join(", ")} depend on postgres/database-management`;
+    return `Shared platform Postgres will start because ${why}${projectScopeNote}`;
+}
+//# sourceMappingURL=shared-platform-postgres.js.map

package/cli/package.json

@@ -1,7 +1,7 @@
 {
   "name": "tdk-cli-internal",
   "private": true,
-  "version": "1.3.117",
+  "version": "1.3.118",
   "description": "TDK CLI — start services on your laptop.",
   "keywords": [
     "tdk",

package/cli/templates/Tiltfile.hbs

@@ -225,6 +225,8 @@ TILT_CONTEXT = {
     'project_root': PROJECT_ROOT,
     'all_services': _app_resources_list,
     'golden_image_resource': GOLDEN_IMAGE_RESOURCE,
+    'focus_mode': FOCUS_MODE,
+    'focus_enabled_resources': FOCUS_ENABLED_RESOURCES,
 }
 
 print("🚀 Creating Tilt resources for {} services...".format(len(_app_resources_list)))
@@ -314,7 +316,9 @@ if FOCUS_MODE and FOCUS_ENABLED_RESOURCES:
     # local mail catcher standing in for a managed email provider. Every
     # service it declares is loaded via docker_compose() in infra-loader.star,
     # so it must be enabled here too, or it is silently disabled the same way.
-    _ALWAYS_ENABLED_INFRA_RESOURCES = ['init-networks', 'postgres', 'traefik', 'golden-layers-build']
+    _ALWAYS_ENABLED_INFRA_RESOURCES = ['init-networks', 'traefik', 'golden-layers-build']
+    if should_enable('database-management') or TILT_CONTEXT.get('_shared_platform_postgres_force_started', False):
+        _ALWAYS_ENABLED_INFRA_RESOURCES.append('postgres')
     _messaging_compose_path = PROJECT_ROOT + '/services/platform/messaging/docker-compose.yml'
     if str(local("test -f '" + _messaging_compose_path + "' && echo yes || echo no", quiet=True, echo_off=True)).strip() == 'yes':
         # infra-loader.star only creates these Tilt resources when this file

package/engine/topologies/tilt/common/utils.star

@@ -273,6 +273,8 @@ def _is_allowed_generated_path(file_path, project_root):
         return True
     if path.startswith('.tdk/.tdk-out/'):
         return True
+    if path == 'services/platform/database-management/docker-compose.yml':
+        return True
     if path.startswith('product_autogenerated_resource_manifests/') or path.startswith('product_autogenerated_services_list/'):
         return True
     if path == 'Tiltfile' or path == '.tiltignore':

package/engine/topologies/tilt/generators/validators.star

@@ -24,6 +24,7 @@ Validators Architecture:
 load("../common/utils.star", "Utils")
 load("../../platform/docker/constants.star", "PlatformDockerConstants")
 load("../manifest/constants.star", "GENERATED_CONFIG_FILENAMES")
+load("../resources/shared-platform-postgres.star", "is_shared_platform_postgres_dependency")
 
 load("../common/utils.star", "LIBRARY_ROOTS")
 
@@ -182,6 +183,10 @@ def validate_dependency_graph(resource_path, manifest, all_services):
     # Check manifest dependsOn
     internal_deps = manifest.get("dependsOn", [])
     for dep in internal_deps:
+        # Shared platform Postgres aliases are not app services; they resolve to
+        # the Tilt resource `postgres` and must not be reported as missing.
+        if is_shared_platform_postgres_dependency(dep):
+            continue
         dep_exists = False
         for svc in all_services:
             # Check service name/stack match (supports legacy 'stack' field)
@@ -196,7 +201,7 @@ def validate_dependency_graph(resource_path, manifest, all_services):
                     break
             if dep_exists:
                 break
-        
+
         if not dep_exists:
             missing_deps.append({
                 "name": dep,

package/engine/topologies/tilt/manifest/integration.star

@@ -13,6 +13,7 @@ load("./__init__.star", "Manifest")
 load("./loader.star", "ManifestLoader")
 load("./parser.star", "ManifestParser")
 load("./validator.star", "ManifestValidator")
+load("../resources/shared-platform-postgres.star", "SHARED_POSTGRES_DEPENDENCY_NAMES")
 
 # Phase 5: Migration complete - always use new system
 def load_and_validate_manifest(manifest_path, all_manifests=None):
@@ -290,21 +291,27 @@ def check_port_conflicts(manifests):
 def check_dependencies_valid(manifests):
     """
     Check if all dependencies reference valid services.
-    
+
+    Shared platform Postgres names (`postgres`, `database-management`) are not
+    app services; they resolve to the Tilt resource `postgres` and are not
+    reported as missing.
+
     Args:
         manifests: List of manifest dicts
-    
+
     Returns:
         List of dependency error structs
     """
     errors = []
     app_names = {m.get('appName'): m for m in manifests if m.get('appName')}
-    
+
     for manifest in manifests:
         app_name = manifest.get('appName', 'unknown')
         internal_deps = manifest.get('dependsOn', [])
-        
+
         for dep in internal_deps:
+            if dep in SHARED_POSTGRES_DEPENDENCY_NAMES:
+                continue
             if dep not in app_names:
                 errors.append(ManifestErrors.new(
                     message="Service '{}' depends on non-existent service '{}'".format(app_name, dep),

package/engine/topologies/tilt/manifest/validator.star

@@ -25,6 +25,7 @@ load("./constants.star",
 load("./schema.star", "ManifestSchema")
 load("./errors.star", "ManifestErrors")
 load("./parser.star", "extract_stack_from_path")
+load("../resources/shared-platform-postgres.star", "is_shared_platform_postgres_dependency")
 
 def validate(manifest, context=None, level='all'):
     """
@@ -463,6 +464,9 @@ def _validate_cross_resource(manifest, context):
         
         missing_deps = []
         for dep in internal_deps:
+            # Shared platform Postgres aliases are not app services.
+            if is_shared_platform_postgres_dependency(dep):
+                continue
             if dep not in app_names:
                 missing_deps.append(dep)
         

package/engine/topologies/tilt/resources/infra-loader.star

@@ -92,32 +92,83 @@ volumes:
 
 
 def _ensure_database_management_compose(root_prefix, write_fn):
-    """Ensure the database-management stack feature has its compose file."""
+    """Ensure the database-management stack feature has its compose file.
+
+    write_fn is expected to be Utils.write_file_if_changed, which prepends
+    TDK_PROJECT_ROOT to relative paths — the same base as root_prefix when
+    the Tiltfile sets TDK_PROJECT_ROOT = PROJECT_ROOT. A custom write_fn that
+    does not prepend may write a different file; if the path we return is
+    absolute and still missing after the relative write, write that exact
+    path once so the exists-check and the write cannot diverge.
+    """
     compose_rel = "services/platform/database-management/docker-compose.yml"
     compose_file = root_prefix + compose_rel if root_prefix else compose_rel
     if _file_exists(compose_file):
         return compose_file
     if write_fn:
         write_fn(compose_rel, _generate_database_management_compose())
+        if not _file_exists(compose_file) and compose_file.startswith('/'):
+            write_fn(compose_file, _generate_database_management_compose())
     return compose_file
 
+# No module-level mutable registration flag: Tilt freezes Starlark globals after
+# module load, so writing a key on a global dict raises "cannot insert into
+# frozen hash table". Feature-on (`_load_database_management`) and force-start
+# (`force_start_platform_postgres`) are mutually exclusive via should_enable —
+# the orchestrator only force-starts when database-management is off — so each
+# Tiltfile evaluation registers `postgres` at most once on its own path.
+
+
+def _register_platform_postgres(should_enable, root_prefix="", env_file=None, write_fn=None, required=False):
+    """Materialize the platform compose and register the shared `postgres` Tilt resource.
+
+    Does NOT load messaging, kafka, redis, nats, provision-db, or Prisma.
+
+    When `required` is true (dependsOn force-start path), a missing compose after
+    ensure is a hard failure — not a silent skip — so Tilt never waits on a
+    `postgres` resource that has no compose definition.
+    """
+    postgres_compose = _ensure_database_management_compose(root_prefix, write_fn)
+    if _file_exists(postgres_compose):
+        print("DEBUG INFRA: Loading postgres compose from {}".format(postgres_compose))
+        _docker_compose(postgres_compose, env_file)
+        dc_resource('postgres', labels=['infra.tools'], resource_deps=['init-networks'], auto_init=True)
+        return
+    message = "Shared platform Postgres compose was not materialized at {}".format(postgres_compose)
+    if required:
+        fail(message + " (write_fn present: {}). Refusing to register a postgres Tilt resource with no compose.".format(write_fn != None))
+    print("DEBUG INFRA: Skipping postgres (compose file not found): {}".format(message))
+
+
+def force_start_platform_postgres(should_enable, root_prefix="", env_file=None, write_fn=None):
+    """Force-start the shared platform Postgres for a run whose selected resources
+    depend on `postgres` / `database-management` while `database-management` is off.
+
+    Reuses the existing platform compose path and the existing `postgres` Tilt
+    resource — no second image, port, migrator, or Prisma resource.
+
+    The orchestrator MUST pass the same `write_fn` the feature path uses
+    (`ctx['write_file']`) so `services/platform/database-management/docker-compose.yml`
+    is materialized when missing. A failed materialize fails the run.
+    """
+    if env_file == None:
+        candidate_env_file = root_prefix + '.env' if root_prefix else '.env'
+        env_file = candidate_env_file if _file_exists(candidate_env_file) else None
+    print("🗃️  Force-starting shared platform Postgres (selected dependsOn postgres/database-management)")
+    _register_platform_postgres(should_enable, root_prefix, env_file, write_fn, required=True)
+
+
 def _load_database_management(should_enable, root_prefix="", env_file=None, write_fn=None):
     """Load database and messaging infrastructure."""
     if not should_enable('database-management'):
         print("DEBUG INFRA: database-management not enabled")
         return
-    
+
     print("🗃️  Loading database management services...")
-    
+
     # Load postgres from the database-management stack feature compose.
-    postgres_compose = _ensure_database_management_compose(root_prefix, write_fn)
-    if _file_exists(postgres_compose):
-        print("DEBUG INFRA: Loading postgres compose from {}".format(postgres_compose))
-        _docker_compose(postgres_compose, env_file)
-        dc_resource('postgres', labels=['infra.tools'], resource_deps=['init-networks'], auto_init=True)
-    else:
-        print("DEBUG INFRA: Skipping postgres (compose file not found)")
-    
+    _register_platform_postgres(should_enable, root_prefix, env_file, write_fn)
+
     # Load messaging if compose file exists
     messaging_compose = root_prefix + 'services/platform/messaging/docker-compose.yml'
     if _file_exists(messaging_compose):
@@ -131,7 +182,7 @@ def _load_database_management(should_enable, root_prefix="", env_file=None, writ
             dc_resource('nats', labels=['infra.messaging'], auto_init=True)
     else:
         print("DEBUG INFRA: Skipping messaging (compose file not found)")
-    
+
     # Only create kafka resources if debezium is enabled AND messaging exists
     cdc_enabled = should_enable('debezium')
     if cdc_enabled and _file_exists(messaging_compose):
@@ -422,7 +473,7 @@ Infra = struct(
     # Main loader
     load_all = load_all_infrastructure,
     init_networks = _init_networks,
-    
+
     # Individual loaders (for granular control)
     load_database = _load_database_management,
     load_verdaccio = _load_verdaccio,
@@ -432,4 +483,8 @@ Infra = struct(
     load_debezium = _load_debezium,
     load_elk = _load_elk,
     load_golden_image = _load_golden_image,
+
+    # Shared platform Postgres start signal (dependsOn postgres/database-management
+    # when the database-management feature is off). Idempotent; no messaging/kafka/Prisma.
+    force_start_postgres = force_start_platform_postgres,
 )

package/engine/topologies/tilt/resources/orchestrator/apply_compose_resource_registration.star

@@ -12,10 +12,68 @@ load('../../../platform/docker/constants.star', 'PlatformDockerConstants')
 load('../../../tilt/manifest/constants.star', 'BASE_PORT_FRONTEND', 'BASE_PORT_BACKEND')
 load('../../../platform/docker/networking/traefik_static_routes.star', 'generate_static_wake_route', 'normalize_abs_path')
 load('../../../platform/docker/networking/sablier_container_cycle.star', 'sablier_middleware_suffix')
+# Shared platform Postgres force-start path. infra-loader.star must not load
+# apply_compose (no circular load): it only loads platform/docker + registries.
+load('../infra-loader.star', 'Infra')
+load('../shared-platform-postgres.star',
+     _shared_postgres_names = 'SHARED_POSTGRES_DEPENDENCY_NAMES',
+     _is_shared_platform_postgres_dependency = 'is_shared_platform_postgres_dependency',
+     _manifest_needs_shared_platform_postgres = 'manifest_needs_shared_platform_postgres')
 
 load('./builders/typescript.star', 'TypescriptBuilders')
 
 
+# Public wrappers for shared platform Postgres helpers. Starlark `load` does not
+# re-export loaded names. Canonical list + predicates live in
+# shared-platform-postgres.star — do not hardcode a second copy of the names here.
+
+def is_shared_platform_postgres_dependency(name):
+    """True when a dependsOn name is one of the shared platform Postgres aliases."""
+    return _is_shared_platform_postgres_dependency(name)
+
+
+def manifest_needs_shared_platform_postgres(manifest):
+    """True when a manifest's dependsOn lists postgres or database-management."""
+    return _manifest_needs_shared_platform_postgres(manifest)
+
+
+def selected_for_shared_platform_postgres(name, ctx):
+    """Use the same focus selection later passed to set_enabled_resources."""
+    if not ctx.get('focus_mode', False):
+        return True
+    return name in (ctx.get('focus_enabled_resources') or [])
+
+
+def force_start_shared_platform_postgres_once(ctx, should_enable, resource_name=""):
+    """Force-start shared platform Postgres at most once per Tiltfile evaluation.
+
+    `register_compose_resources` runs per stack and can see unselected nested
+    services; two selected services that both `dependsOn` Postgres would otherwise call
+    `Infra.force_start_postgres` twice (docker_compose + dc_resource each time).
+    Module-level mutable flags are unusable — Tilt freezes Starlark globals — so
+    the guard lives on `ctx`, a dict the Tiltfile already owns for this run.
+
+    Returns True when this call performed the force-start, False when it skipped
+    (already started this run, or database-management is already on).
+    """
+    if ctx.get('_shared_platform_postgres_force_started', False):
+        print("DEBUG COMPOSE: shared platform Postgres already force-started this run; skip for '{}'".format(resource_name))
+        return False
+    if should_enable('database-management'):
+        return False
+    project_root_for_env = ctx.get('project_root', '')
+    root_prefix = (project_root_for_env + '/') if project_root_for_env else ''
+    env_candidate = (project_root_for_env + '/.env') if project_root_for_env else '.env'
+    env_file = _env_file_if_exists(env_candidate)
+    write_fn = ctx.get('write_file', None)
+    if write_fn == None:
+        fail("dependsOn postgres/database-management on selected resource '{}' requires ctx.write_file to materialize services/platform/database-management/docker-compose.yml".format(resource_name))
+    print("DEBUG COMPOSE: force-starting shared platform Postgres once (selected '{}' dependsOn)".format(resource_name))
+    Infra.force_start_postgres(should_enable, root_prefix=root_prefix, env_file=env_file, write_fn=write_fn)
+    ctx['_shared_platform_postgres_force_started'] = True
+    return True
+
+
 def _env_file_if_exists(env_file):
     """.env is gitignored (no .env.example shipped) across every TDK example repo, so a
     fresh clone must not hard-require it: docker_compose()'s env_file kwarg type-checks as
@@ -51,22 +109,30 @@ def _build_infra_dependencies(resource_name, should_enable, ctx, has_backend=Fal
 def _resolve_dependency_to_resource(dep_name, all_services_map):
     """
     Resolve a short dependency name (e.g., 'identity') to the full YAML resource name.
-    
+
     The discovery registry creates YAML resources with names like:
     - 'identity-management-backend-yaml' for identity backend
     - 'api-gateway-yaml' for api-gateway
-    
+
     But manifests reference them as short names like 'identity' or 'api-gateway'.
+
+    Shared platform Postgres aliases (`postgres`, `database-management`) resolve
+    to the literal Tilt resource `postgres` in BOTH feature states — they must
+    NOT fall through to `postgres-yaml` or any other name.
     """
+    # Shared platform Postgres: exact names only (typos stay on the normal path).
+    if is_shared_platform_postgres_dependency(dep_name):
+        return 'postgres'
+
     # Check if already a full YAML resource name
     if dep_name in all_services_map:
         return dep_name
-    
+
     # Try with -yaml suffix (for resources already resolved)
     yaml_name = dep_name + '-yaml'
     if yaml_name in all_services_map:
         return yaml_name
-    
+
     # Try to find matching service by stack/short name
     for resource_name, resource_info in all_services_map.items():
         # Check if this service's stack matches the dependency
@@ -81,16 +147,51 @@ def _resolve_dependency_to_resource(dep_name, all_services_map):
                         return res['name'] + '-yaml'
                 # Fallback to first resource
                 return resources[0]['name'] + '-yaml'
-    
+
     # Try pattern matching: identity -> identity-*-yaml
     for resource_name in all_services_map.keys():
         if resource_name.startswith(dep_name + '-') and resource_name.endswith('-yaml'):
             return resource_name
-    
+
     # Return original with -yaml suffix as last resort
     return dep_name + '-yaml'
 
 
+def resolve_dependency_to_resource(dep_name, all_services_map):
+    """Public wrapper over `_resolve_dependency_to_resource` (exported for tests)."""
+    return _resolve_dependency_to_resource(dep_name, all_services_map)
+
+
+def build_infra_dependencies(resource_name, should_enable, ctx=None, has_backend=False):
+    """Public wrapper over `_build_infra_dependencies` (exported for tests).
+
+    feature off → no postgres; feature on → has postgres (plus backend
+    provision-db edge when has_backend is true).
+    """
+    return _build_infra_dependencies(resource_name, should_enable, ctx if ctx != None else {}, has_backend)
+
+
+def build_resource_deps(res, res_name, manifest, resource_config, infra_deps, config_gen_resources=None, resource_manifests=None, runtime_flags=None, all_services_map=None):
+    """Public wrapper over `_build_resource_deps` (exported for tests).
+
+    Ensures the dependsOn→resource_deps edge is exercised by tests: feature off
+    + dependsOn postgres → postgres edge present; feature on + dependsOn →
+    exactly one postgres edge (infra_deps already carries it).
+    """
+    default_runtime_flags = {
+        'enforce_migrator_deps': False,
+        'auto_init_apps': True,
+        'disable_app_replicas': False,
+    }
+    return _build_resource_deps(
+        res, res_name, manifest, resource_config, infra_deps,
+        config_gen_resources if config_gen_resources != None else {},
+        resource_manifests if resource_manifests != None else {},
+        runtime_flags if runtime_flags != None else default_runtime_flags,
+        all_services_map,
+    )
+
+
 def _build_resource_deps(res, res_name, manifest, resource_config, infra_deps, config_gen_resources, resource_manifests, runtime_flags, all_services_map=None):
     # Drop self-deps: shared infra_deps always includes verdaccio when enabled, so
     # registering verdaccio itself would otherwise produce resource_deps=['verdaccio'].
@@ -572,6 +673,26 @@ def register_compose_resources(resource_config, ctx, runtime_flags, manifest_sta
             if res_name:
                 all_services_map[res_name] = svc
 
+    # Selection-bound shared platform Postgres start signal.
+    # Only enabled resources in THIS stack are evaluated. Registration sees
+    # unselected siblings before Tilt's enabled-resource filter runs.
+    # When database-management is off and any selected resource's
+    # manifest depends on postgres/database-management, force-start the shared
+    # platform Postgres via the existing infra loader (materializes
+    # services/platform/database-management/docker-compose.yml + registers the
+    # existing `postgres` Tilt resource). Does NOT open migrators/provision-db/Prisma.
+    # Idempotent across services: force_start_shared_platform_postgres_once
+    # guards on ctx so two selected dependents do not register postgres twice.
+    if not should_enable('database-management'):
+        for res in resource_config.get('resources', []):
+            if not selected_for_shared_platform_postgres(res.get('name', ''), ctx):
+                continue
+            res_manifest = resource_manifests.get(res['name'], {})
+            if manifest_needs_shared_platform_postgres(res_manifest):
+                print("DEBUG COMPOSE: selected '{}' dependsOn shared platform Postgres; force-starting postgres".format(res.get('name', '')))
+                force_start_shared_platform_postgres_once(ctx, should_enable, res.get('name', ''))
+                break
+
     resource_entries = []
     resource_configs = []
 
@@ -627,11 +748,17 @@ def register_compose_resources(resource_config, ctx, runtime_flags, manifest_sta
                 ))
 
         resource_entries.append(entry)
-        resource_configs.append(_build_resource_config(
+        built_config = _build_resource_config(
             res, manifest, resource_config, full_res_path, infra_deps,
             config_gen_resources, resource_manifests, runtime_flags, all_services_map,
             ctx.get('project_root', ''),
-        ))
+        )
+        # A focused run still registers disabled siblings before Tilt applies
+        # set_enabled_resources. Do not leave their edge pointing at a Postgres
+        # resource that this evaluation did not register.
+        if not should_enable('database-management') and not ctx.get('_shared_platform_postgres_force_started', False):
+            built_config['res_deps'] = [dep for dep in built_config['res_deps'] if dep != 'postgres']
+        resource_configs.append(built_config)
 
     print("DEBUG COMPOSE: Calling Docker.app_compose for '{}' with write_fn={}".format(resource_name, write_file))
     Docker.app_compose(resource_path, resource_entries, write_file)