From b3d2ceb4c8ae320d9250a483f9335b606c27a98c Mon Sep 17 00:00:00 2001
From: Kanad Gupta <git@kanad.dev>
Date: Fri, 14 Aug 2026 15:45:51 -0700
Subject: [PATCH 1/9] docs(adr): record sparse config subtraction decision
 (CLI-2155)

Adds ADR 0017 pinning the design for the config defaults mapping
function ahead of implementation: a pure, parameterized subtract core
in @supabase/config, defaults derived from schema annotations, strict
deep equality, and the remote-block baseline rule. Also seeds a root
CONTEXT.md glossary with the project's config vocabulary.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 CONTEXT.md                                 | 29 ++++++++++
 docs/adr/0017-sparse-config-subtraction.md | 63 ++++++++++++++++++++++
 docs/adr/README.md                         |  1 +
 3 files changed, 93 insertions(+)
 create mode 100644 CONTEXT.md
 create mode 100644 docs/adr/0017-sparse-config-subtraction.md

diff --git a/CONTEXT.md b/CONTEXT.md
new file mode 100644
index 0000000000..87b556d14e
--- /dev/null
+++ b/CONTEXT.md
@@ -0,0 +1,29 @@
+# Supabase CLI
+
+The Supabase CLI and its supporting packages, including `@supabase/config` — the schema and tooling for the `config.toml` project configuration file that config-driven development (diff/pull/push) is built on.
+
+## Language
+
+### Project configuration
+
+**Default config**:
+The `ProjectConfig` in which every value carries its schema-declared default — what a project means before anyone configures anything.
+_Avoid_: defaults reference, base config
+
+**Sparse config**:
+A partial config overlay containing only values that differ from some baseline. Not a valid complete config on its own.
+_Avoid_: minimal config, pruned config, massaged config
+
+**Subtract**:
+The directional operation `config − baseline` that produces a sparse config: remove every value deep-equal (order-sensitive) to the baseline's, then drop sections left empty.
+_Avoid_: prune, strip, massage
+
+**Remote block**:
+A `[remotes.<label>]` section — a sparse overlay on the base config scoped to one branch's project. Its baseline is the merged base config, never the default config.
+_Avoid_: environment block, branch config
+
+**Base config**:
+The root-scope fields of a `config.toml`, before any remote block is overlaid.
+
+**Drift**:
+A difference between a project's effective remote configuration and the local config file.
diff --git a/docs/adr/0017-sparse-config-subtraction.md b/docs/adr/0017-sparse-config-subtraction.md
new file mode 100644
index 0000000000..b876ac4c71
--- /dev/null
+++ b/docs/adr/0017-sparse-config-subtraction.md
@@ -0,0 +1,63 @@
+# 0017. Sparse Config Subtraction
+
+**Status**: proposed
+**Date**: 2026-08-14
+
+## Problem Statement
+
+`config diff` (CLI-2156) and `config pull` (CLI-2064) compare a project's remote configuration against the local `config.toml`. The remote endpoint (`GET /v2/projects/{ref}/config`) returns the *effective* config — every setting reported, defaulted or not — and a locally decoded `ProjectConfig` likewise has every default filled in. Comparing these full objects directly would drown the user in hundreds of identical default values. CLI-2155 asks for a stored reference of config defaults and a mapping function that omits values matching them, so diffs stay readable and pulled files stay sparse.
+
+The trap is where that mapping recurses. A `[remotes.<label>]` block is itself a sparse overlay whose meaning is "override the merged base config here". A value in a remote block that happens to equal a *global default* is not redundant: if the base config overrides the same property, removing the remote's value silently changes what that branch resolves to.
+
+## Decision
+
+`@supabase/config` exports a pure, parameterized subtraction core:
+
+- `getDefaultProjectConfig()` — the default config, derived by decoding `{}` through `ProjectConfigSchema` (memoized). The schema's `default` annotations and decoding defaults are the single source of truth; no hand-maintained defaults table exists.
+- `subtractProjectConfig(config, baseline)` — returns the sparse config `config − baseline`: every value strictly deep-equal (order-sensitive) to the baseline's is removed, then sections left empty are dropped recursively.
+- `omitDefaultValues(config)` — `subtractProjectConfig` with the default config as baseline.
+
+Subtraction never recurses into `remotes` when the baseline is the default config: the default config has no remote blocks, so under subtract semantics user remote blocks survive untouched. **The correct baseline for a remote block is the merged base config, never the default config.** Callers that want to sparsify a remote block (CLI-2156/2064) must call `subtractProjectConfig(remoteBlock, mergedBaseConfig)` explicitly.
+
+All functions are pure and synchronous, operating on decoded `ProjectConfig` values, with no Effect in the public signature.
+
+## Rationale
+
+- **One core instead of a cascade.** The merge-and-prune cascade sketched in CLI-2155's planning comment reduces algebraically to `subtract(merge(local, remote), defaults)`. Exporting the subtraction gives `config diff` and `config pull` the shared comparison core without binding this package to the Management API's response shape (translating that shape to `ProjectConfig` is CLI-2156's concern).
+- **Defaults derived, not duplicated.** Every field's default already lives in the schema (`default` annotations plus `withDecodingDefaultKey`). Decoding `{}` materializes them; a parallel hand-written defaults object would drift.
+- **Strict deep equality, array order matters.** Order is semantically load-bearing for values like `api.extra_search_path` (Postgres `search_path` resolution order). Treating reordered arrays as equal would prune values that behave differently from the default. The false-positive cost (a semantically-default-but-reordered array survives as harmless noise) is far cheaper than wrongly deleting meaningful config.
+- **Dropping empty sections is lossless.** Every section carries a section-level decoding default, so an absent section and an empty section decode identically; empty carcass headers are pure diff noise.
+- **Pure functions.** The subtraction has no failure channel, no resources, and no concurrency — the repo's Effect-native policy explicitly exempts such leaf primitives. Purity also keeps the module portable if the package later grows browser-compatible entry points.
+
+## Consequences
+
+### Positive
+
+- Diffs and pulled configs contain only values that differ from their baseline.
+- One walk implementation serves defaults-stripping and remote-block sparsification.
+- Schema remains the single source of truth for defaults; changing a default in the schema changes the subtraction behavior with no second edit.
+- A unit test pins the invariant that all schema defaults are mutually valid (decoding `{}` succeeds), so a conflicting default fails CI loudly.
+
+### Negative
+
+- Fields declared `optionalKey` without a `default` annotation can never be pruned; if a platform default exists for such a field, it must be added to the schema before subtraction can see it.
+- A user's explicitly-written default value (`max_rows = 1000` typed by hand) is indistinguishable from an omitted one and will be pruned; intent is not preserved.
+- Callers must know the remote-block baseline rule; misusing the default config as a remote block's baseline reintroduces the override-erasure bug this ADR exists to prevent.
+
+## Alternatives Considered
+
+1. **Merge-and-prune cascade as a single function** (`(apiResponse, configToml) → massaged config`): binds `@supabase/config` to the Management API response shape and entangles this package with remote-to-local translation, which belongs to the diff core (CLI-2156).
+2. **Recursing into `remotes` against global defaults**: looks obviously correct, is subtly wrong — pruning a remote's `api.max_rows = 1000` (global default) under a base that sets `500` changes the branch's effective value from 1000 to 500.
+3. **Hand-written defaults reference object**: duplicates ~100 defaults already declared in the schema and drifts silently.
+4. **Order-insensitive array comparison**: prunes reordered arrays whose order is semantically meaningful (`extra_search_path`).
+
+## Related Decisions
+
+- [ADR 0009](0009-configuration-schema-and-validation.md): Configuration Schema & Validation — the umbrella charter this decision answers a slice of (default config generation, `@supabase/config` package architecture)
+- [ADR 0006](0006-environment-management.md): Environment Management — remote blocks and branch mapping semantics
+
+## See Also
+
+- [CLI-2155](https://linear.app/supabase/issue/CLI-2155/store-the-config-default-values-and-provide-mapping-function) — this ticket
+- [CLI-2156](https://linear.app/supabase/issue/CLI-2156/add-supabase-config-diff-to-the-cli) — `config diff`, consumer of the subtract core
+- [CLI-2064](https://linear.app/supabase/issue/CLI-2064/add-supabase-config-pull-to-the-cli) — `config pull`
diff --git a/docs/adr/README.md b/docs/adr/README.md
index 887b3e57b5..2f540dba2f 100644
--- a/docs/adr/README.md
+++ b/docs/adr/README.md
@@ -57,6 +57,7 @@ When an ADR becomes outdated, mark it as `deprecated` or reference the supersedi
 | 0013 | [Live E2E Tests Bypass the Replay Server](0013-live-e2e-bypasses-replay-server.md)         | proposed |
 | 0015 | [Managed Stack Contract Fixtures](0015-managed-stack-contract-fixtures.md)                 | proposed |
 | 0016 | [Legacy Port Completion and Go CLI Authority Scope](0016-legacy-port-completion-and-go-cli-authority-scope.md) | proposed |
+| 0017 | [Sparse Config Subtraction](0017-sparse-config-subtraction.md)                             | proposed |
 
 ## Template
 

From 9ce13b0491c72ad7c248ec87b87a35b7c63798fb Mon Sep 17 00:00:00 2001
From: Kanad Gupta <git@kanad.dev>
Date: Mon, 17 Aug 2026 14:18:45 -0700
Subject: [PATCH 2/9] feat(config): store config defaults and provide sparse
 mapping functions (CLI-2155)

Adds getDefaultProjectConfig() (memoized decode of {} through the
schema, keeping annotations as the single source of truth for
defaults), subtractProjectConfig(config, baseline), and
omitDefaultValues(config), per ADR 0017. The generic subtraction walk
is extracted from io.ts's private stripDefaults so the save-time
minimal encoding and the new sparse API share one implementation.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 packages/config/src/index.ts            |   6 +
 packages/config/src/io.ts               |  69 +----------
 packages/config/src/sparse.ts           | 151 ++++++++++++++++++++++++
 packages/config/src/sparse.unit.test.ts | 121 +++++++++++++++++++
 4 files changed, 282 insertions(+), 65 deletions(-)
 create mode 100644 packages/config/src/sparse.ts
 create mode 100644 packages/config/src/sparse.unit.test.ts

diff --git a/packages/config/src/index.ts b/packages/config/src/index.ts
index e2b9475830..d7f2cd3b61 100644
--- a/packages/config/src/index.ts
+++ b/packages/config/src/index.ts
@@ -46,5 +46,11 @@ export { type ProjectPaths, findProjectPaths, findProjectRoot } from "./paths.ts
 export { projectConfigStoreLayer } from "./project-config.layer.ts";
 export { ProjectConfigStore } from "./project-config.service.ts";
 export { PROJECT_CONFIG_SCHEMA_URL } from "./schema-metadata.ts";
+export {
+  type SparseProjectConfig,
+  getDefaultProjectConfig,
+  omitDefaultValues,
+  subtractProjectConfig,
+} from "./sparse.ts";
 export { KONG_LOCAL_CA_CERT } from "./tls.ts";
 export { ENV_CAPTURE_REGEX } from "./lib/env.ts";
diff --git a/packages/config/src/io.ts b/packages/config/src/io.ts
index ae427d5f67..1eb79134f4 100644
--- a/packages/config/src/io.ts
+++ b/packages/config/src/io.ts
@@ -8,6 +8,7 @@ import {
 } from "./errors.ts";
 import { interpolateEnvReferencesAgainstSchema } from "./lib/env.ts";
 import { findProjectPaths } from "./paths.ts";
+import { getDefaultProjectConfig, subtractValue } from "./sparse.ts";
 import { loadProjectEnvironment, type ProjectEnvironment } from "./project.ts";
 
 const projectConfigSchemaKey = "$schema";
@@ -128,7 +129,7 @@ const decodeRemotesWithoutChecks = Schema.decodeUnknownSync(RemotesSchema, {
   disableChecks: true,
 });
 const encodeProjectConfig = Schema.encodeSync(ProjectConfigSchema);
-const defaultEncodedProjectConfig = encodeProjectConfig(decodeProjectConfig({}));
+const defaultEncodedProjectConfig = encodeProjectConfig(getDefaultProjectConfig());
 const defaultEncodedFunctionConfig = {
   enabled: true,
   verify_jwt: true,
@@ -306,68 +307,6 @@ const applyRemoteOverride = Effect.fnUntraced(function* (
   return { document: merged, appliedRemote: name };
 });
 
-function isEqualValue(left: unknown, right: unknown): boolean {
-  if (Array.isArray(left) && Array.isArray(right)) {
-    if (left.length !== right.length) {
-      return false;
-    }
-
-    for (let index = 0; index < left.length; index += 1) {
-      if (!isEqualValue(left[index], right[index])) {
-        return false;
-      }
-    }
-
-    return true;
-  }
-
-  if (isObject(left) && isObject(right)) {
-    const leftKeys = Object.keys(left);
-    const rightKeys = Object.keys(right);
-
-    if (leftKeys.length !== rightKeys.length) {
-      return false;
-    }
-
-    for (const key of leftKeys) {
-      if (!(key in right) || !isEqualValue(left[key], right[key])) {
-        return false;
-      }
-    }
-
-    return true;
-  }
-
-  return Object.is(left, right);
-}
-
-function stripDefaults(value: unknown, defaults: unknown): unknown {
-  if (defaults === undefined) {
-    return value;
-  }
-
-  if (Array.isArray(value)) {
-    return isEqualValue(value, defaults) ? undefined : value;
-  }
-
-  if (isObject(value)) {
-    const defaultObject = isObject(defaults) ? defaults : {};
-    const result: Record<string, unknown> = {};
-
-    for (const [key, child] of Object.entries(value)) {
-      const stripped = stripDefaults(child, defaultObject[key]);
-
-      if (stripped !== undefined) {
-        result[key] = stripped;
-      }
-    }
-
-    return Object.keys(result).length === 0 ? undefined : result;
-  }
-
-  return isEqualValue(value, defaults) ? undefined : value;
-}
-
 function stripFunctionRecordDefaults(value: unknown): unknown {
   if (!isObject(value)) {
     return value;
@@ -380,7 +319,7 @@ function stripFunctionRecordDefaults(value: unknown): unknown {
 
   const functions: Record<string, unknown> = {};
   for (const [name, functionConfig] of Object.entries(functionsValue)) {
-    functions[name] = stripDefaults(functionConfig, defaultEncodedFunctionConfig) ?? {};
+    functions[name] = subtractValue(functionConfig, defaultEncodedFunctionConfig) ?? {};
   }
 
   return { ...value, functions };
@@ -388,7 +327,7 @@ function stripFunctionRecordDefaults(value: unknown): unknown {
 
 function encodeMinimalProjectConfig(config: ProjectConfig): Record<string, unknown> {
   const encoded = stripFunctionRecordDefaults(encodeProjectConfig(config));
-  const stripped = stripDefaults(encoded, defaultEncodedProjectConfig);
+  const stripped = subtractValue(encoded, defaultEncodedProjectConfig);
   return isObject(stripped) ? stripped : {};
 }
 
diff --git a/packages/config/src/sparse.ts b/packages/config/src/sparse.ts
new file mode 100644
index 0000000000..1a8f79c42f
--- /dev/null
+++ b/packages/config/src/sparse.ts
@@ -0,0 +1,151 @@
+import { Schema } from "effect";
+import { ProjectConfigSchema, type ProjectConfig } from "./base.ts";
+
+/**
+ * Sparse config subtraction — see `docs/adr/0017-sparse-config-subtraction.md`.
+ *
+ * A sparse config is a partial overlay containing only the values that differ
+ * from some baseline; it is not a valid complete config on its own. Arrays are
+ * compared wholesale (order-sensitive) and never subtracted element-wise, so a
+ * sparse value is always either an entire array or an object subtree of kept
+ * leaves — hence arrays survive `DeepPartial` unchanged below.
+ */
+type DeepPartial<T> =
+  T extends ReadonlyArray<unknown>
+    ? T
+    : T extends object
+      ? { readonly [K in keyof T]?: DeepPartial<T[K]> }
+      : T;
+
+export type SparseProjectConfig = DeepPartial<ProjectConfig>;
+
+const decodeProjectConfig = Schema.decodeUnknownSync(ProjectConfigSchema);
+
+let defaultProjectConfig: ProjectConfig | undefined;
+
+/**
+ * The default config: a {@link ProjectConfig} in which every value carries its
+ * schema-declared default. Derived by decoding `{}` through
+ * {@link ProjectConfigSchema} — the schema's `default` annotations and decoding
+ * defaults are the single source of truth, so there is no hand-maintained
+ * defaults table to drift. Fields declared `optionalKey` without a default
+ * (e.g. `project_id`, `api.external_url`) are absent.
+ *
+ * Memoized (and the memo shared with callers) rather than computed at module
+ * load, so importing the package doesn't pay for a full schema decode; the
+ * decoded config is deeply readonly by type, so sharing is safe.
+ */
+export function getDefaultProjectConfig(): ProjectConfig {
+  defaultProjectConfig ??= decodeProjectConfig({});
+  return defaultProjectConfig;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isEqualValue(left: unknown, right: unknown): boolean {
+  if (Array.isArray(left) && Array.isArray(right)) {
+    if (left.length !== right.length) {
+      return false;
+    }
+
+    for (let index = 0; index < left.length; index += 1) {
+      if (!isEqualValue(left[index], right[index])) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  if (isObject(left) && isObject(right)) {
+    const leftKeys = Object.keys(left);
+    const rightKeys = Object.keys(right);
+
+    if (leftKeys.length !== rightKeys.length) {
+      return false;
+    }
+
+    for (const key of leftKeys) {
+      if (!(key in right) || !isEqualValue(left[key], right[key])) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  return Object.is(left, right);
+}
+
+/**
+ * The untyped subtraction walk: returns `value − baseline`, or `undefined`
+ * when nothing survives. Values strictly deep-equal (order-sensitive) to the
+ * baseline's are removed; objects recurse per key and are dropped once empty;
+ * arrays are removed wholesale on equality, never subtracted element-wise. A
+ * key with no counterpart in the baseline is kept verbatim — which is exactly
+ * how `remotes` and other record entries pass through untouched when the
+ * baseline is the default config.
+ *
+ * Shared with `io.ts`, which subtracts *encoded* documents before writing
+ * minimal config files; the typed entry points below operate on decoded
+ * {@link ProjectConfig} values, the only shape where "equals the default" is
+ * well-defined.
+ */
+export function subtractValue(value: unknown, baseline: unknown): unknown {
+  if (baseline === undefined) {
+    return value;
+  }
+
+  if (Array.isArray(value)) {
+    return isEqualValue(value, baseline) ? undefined : value;
+  }
+
+  if (isObject(value)) {
+    const baselineObject = isObject(baseline) ? baseline : {};
+    const result: Record<string, unknown> = {};
+
+    for (const [key, child] of Object.entries(value)) {
+      const subtracted = subtractValue(child, baselineObject[key]);
+
+      if (subtracted !== undefined) {
+        result[key] = subtracted;
+      }
+    }
+
+    return Object.keys(result).length === 0 ? undefined : result;
+  }
+
+  return isEqualValue(value, baseline) ? undefined : value;
+}
+
+/**
+ * Returns the sparse config `config − baseline`. Directional: a value equal to
+ * the baseline's is removed even when it differs from the schema default, and
+ * a value differing from the baseline's is kept even when it equals the schema
+ * default. A `[remotes.*]` block's correct baseline is the merged base config,
+ * never the default config — see ADR 0017 for why subtracting a remote block
+ * against global defaults would silently change what the branch resolves to.
+ */
+export function subtractProjectConfig(
+  config: ProjectConfig,
+  baseline: ProjectConfig,
+): SparseProjectConfig;
+// The implementation signature stays untyped because TypeScript cannot verify
+// that a structural walk over `unknown` reconstructs a `DeepPartial` of its
+// input; the overload above is the contract, pinned by the unit tests.
+export function subtractProjectConfig(config: ProjectConfig, baseline: ProjectConfig): unknown {
+  const result = subtractValue(config, baseline);
+  return isObject(result) ? result : {};
+}
+
+/**
+ * Returns the sparse config `config − default config`: only the values that
+ * differ from their schema defaults, per {@link subtractProjectConfig}'s
+ * semantics. `remotes` blocks pass through untouched (the default config has
+ * none), and undefaulted `optionalKey` fields always survive when present.
+ */
+export function omitDefaultValues(config: ProjectConfig): SparseProjectConfig {
+  return subtractProjectConfig(config, getDefaultProjectConfig());
+}
diff --git a/packages/config/src/sparse.unit.test.ts b/packages/config/src/sparse.unit.test.ts
new file mode 100644
index 0000000000..b5d33a22d2
--- /dev/null
+++ b/packages/config/src/sparse.unit.test.ts
@@ -0,0 +1,121 @@
+import { describe, expect, test } from "vitest";
+import { Schema } from "effect";
+import { ProjectConfigSchema } from "./base.ts";
+import { getDefaultProjectConfig, omitDefaultValues, subtractProjectConfig } from "./sparse.ts";
+
+const decodeProjectConfig = Schema.decodeUnknownSync(ProjectConfigSchema);
+
+describe("getDefaultProjectConfig", () => {
+  test("all schema defaults are mutually valid", () => {
+    // Decoding `{}` runs every business-rule check embedded in the schema, so
+    // a future default that conflicts with another fails here, loudly, rather
+    // than at import time in some consumer.
+    expect(() => getDefaultProjectConfig()).not.toThrow();
+  });
+
+  test("materializes known schema defaults across sections", () => {
+    const defaults = getDefaultProjectConfig();
+    expect(defaults.api.port).toBe(54321);
+    expect(defaults.api.schemas).toEqual(["public", "graphql_public"]);
+    expect(defaults.db.port).toBe(54322);
+    expect(defaults.db.major_version).toBe(17);
+    expect(defaults.auth.enabled).toBe(true);
+    expect(defaults.auth.site_url).toBe("http://127.0.0.1:3000");
+    expect(defaults.functions).toEqual({});
+    expect(defaults.remotes).toEqual({});
+  });
+
+  test("omits optional fields that carry no default", () => {
+    const defaults = getDefaultProjectConfig();
+    expect("project_id" in defaults).toBe(false);
+    expect("external_url" in defaults.api).toBe(false);
+  });
+});
+
+describe("omitDefaultValues", () => {
+  test("a fully-default config subtracts to an empty overlay", () => {
+    expect(omitDefaultValues(getDefaultProjectConfig())).toEqual({});
+    expect(omitDefaultValues(decodeProjectConfig({}))).toEqual({});
+  });
+
+  test("keeps an overridden leaf and drops its default-valued siblings", () => {
+    const config = decodeProjectConfig({ api: { max_rows: 500 } });
+    expect(omitDefaultValues(config)).toEqual({ api: { max_rows: 500 } });
+  });
+
+  test("array comparison is order-sensitive", () => {
+    const reordered = decodeProjectConfig({ api: { schemas: ["graphql_public", "public"] } });
+    expect(omitDefaultValues(reordered)).toEqual({
+      api: { schemas: ["graphql_public", "public"] },
+    });
+
+    const exact = decodeProjectConfig({ api: { schemas: ["public", "graphql_public"] } });
+    expect(omitDefaultValues(exact)).toEqual({});
+  });
+
+  test("sections emptied by subtraction disappear, cascading upward", () => {
+    // `api.tls.enabled` defaults to `false`: the leaf is pruned, leaving
+    // `tls: {}`, which is dropped, leaving `api: {}`, which is dropped.
+    const config = decodeProjectConfig({ api: { tls: { enabled: false } } });
+    expect(omitDefaultValues(config)).toEqual({});
+  });
+
+  test("optional fields with no default always survive when present", () => {
+    const config = decodeProjectConfig({
+      project_id: "my-project",
+      api: { external_url: "https://api.example.com" },
+    });
+    expect(omitDefaultValues(config)).toEqual({
+      project_id: "my-project",
+      api: { external_url: "https://api.example.com" },
+    });
+  });
+
+  test("record entries absent from the defaults pass through whole", () => {
+    const config = decodeProjectConfig({ functions: { hello: { verify_jwt: false } } });
+    const sparse = omitDefaultValues(config);
+    expect(sparse.functions).toEqual(config.functions);
+  });
+
+  test("remotes pass through untouched, even when set to global defaults", () => {
+    // `api.max_rows = 1000` IS the global default, but inside a remote block
+    // it overrides whatever the base config resolves to — subtracting it
+    // against global defaults would silently change the branch's effective
+    // value. See ADR 0017: a remote block's baseline is the merged base
+    // config, never the default config.
+    const config = decodeProjectConfig({
+      api: { max_rows: 500 },
+      remotes: { staging: { project_id: "abcdefghijklmnopqrst", api: { max_rows: 1000 } } },
+    });
+    const sparse = omitDefaultValues(config);
+    expect(sparse.remotes).toEqual(config.remotes);
+    expect(sparse.api).toEqual({ max_rows: 500 });
+  });
+
+  test("does not mutate its input", () => {
+    const config = decodeProjectConfig({
+      api: { max_rows: 500 },
+      remotes: { staging: { project_id: "abcdefghijklmnopqrst" } },
+    });
+    const before = structuredClone(config);
+    omitDefaultValues(config);
+    expect(config).toEqual(before);
+  });
+});
+
+describe("subtractProjectConfig", () => {
+  test("subtracting a config from itself yields an empty overlay", () => {
+    const config = decodeProjectConfig({ api: { max_rows: 500 } });
+    expect(subtractProjectConfig(config, config)).toEqual({});
+  });
+
+  test("subtraction is directional against the baseline, not the defaults", () => {
+    // The CLI-2156 remote-block scenario: subtract a merged effective config
+    // against the merged BASE config. `api.max_rows: 1000` equals the global
+    // default but differs from the baseline's 500 — kept. `db.port: 54399`
+    // differs from the global default but equals the baseline's — removed.
+    const baseline = decodeProjectConfig({ api: { max_rows: 500 }, db: { port: 54399 } });
+    const config = decodeProjectConfig({ api: { max_rows: 1000 }, db: { port: 54399 } });
+    expect(subtractProjectConfig(config, baseline)).toEqual({ api: { max_rows: 1000 } });
+  });
+});

From 608b9c3e4207141179875015dbd2c62e36401c46 Mon Sep 17 00:00:00 2001
From: Kanad Gupta <git@kanad.dev>
Date: Tue, 18 Aug 2026 16:17:17 -0700
Subject: [PATCH 3/9] docs(config): clarify remote-block product context and
 sparse validity (CLI-2155)

Introduces [remotes.*] blocks as config overrides for a specific
persistent Supabase branch (project_id binds the block; the label is a
user-chosen alias) in ADR 0017, CONTEXT.md, and the sparse.ts doc
comments. Replaces the flat "not a valid complete config" framing with
a split by baseline: subtracting the default config yields a valid
config document that re-decodes to the same effective config under the
current schema's defaults, while any other baseline yields an overlay
meaningful only relative to that baseline.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 CONTEXT.md                                 |  4 ++--
 docs/adr/0017-sparse-config-subtraction.md |  4 +++-
 packages/config/src/sparse.ts              | 28 +++++++++++++++-------
 3 files changed, 24 insertions(+), 12 deletions(-)

diff --git a/CONTEXT.md b/CONTEXT.md
index 87b556d14e..9c5ddbfb0a 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -11,7 +11,7 @@ The `ProjectConfig` in which every value carries its schema-declared default —
 _Avoid_: defaults reference, base config
 
 **Sparse config**:
-A partial config overlay containing only values that differ from some baseline. Not a valid complete config on its own.
+A partial config overlay containing only values that differ from some baseline. When the baseline is the default config it is itself a valid config that re-decodes to the same effective config under the current schema's defaults; against any other baseline it is meaningful only relative to that baseline.
 _Avoid_: minimal config, pruned config, massaged config
 
 **Subtract**:
@@ -19,7 +19,7 @@ The directional operation `config − baseline` that produces a sparse config: r
 _Avoid_: prune, strip, massage
 
 **Remote block**:
-A `[remotes.<label>]` section — a sparse overlay on the base config scoped to one branch's project. Its baseline is the merged base config, never the default config.
+A `[remotes.<label>]` section declaring config overrides for a specific persistent Supabase branch — the branch's project ref in `project_id` binds the block (the label is a user-chosen alias), and unspecified options inherit from the base config. Its baseline is the merged base config, never the default config.
 _Avoid_: environment block, branch config
 
 **Base config**:
diff --git a/docs/adr/0017-sparse-config-subtraction.md b/docs/adr/0017-sparse-config-subtraction.md
index b876ac4c71..cb775af6c9 100644
--- a/docs/adr/0017-sparse-config-subtraction.md
+++ b/docs/adr/0017-sparse-config-subtraction.md
@@ -7,7 +7,7 @@
 
 `config diff` (CLI-2156) and `config pull` (CLI-2064) compare a project's remote configuration against the local `config.toml`. The remote endpoint (`GET /v2/projects/{ref}/config`) returns the *effective* config — every setting reported, defaulted or not — and a locally decoded `ProjectConfig` likewise has every default filled in. Comparing these full objects directly would drown the user in hundreds of identical default values. CLI-2155 asks for a stored reference of config defaults and a mapping function that omits values matching them, so diffs stay readable and pulled files stay sparse.
 
-The trap is where that mapping recurses. A `[remotes.<label>]` block is itself a sparse overlay whose meaning is "override the merged base config here". A value in a remote block that happens to equal a *global default* is not redundant: if the base config overrides the same property, removing the remote's value silently changes what that branch resolves to.
+The trap is where that mapping recurses. A `[remotes.<label>]` block declares config overrides for a specific [persistent Supabase branch](https://supabase.com/docs/guides/local-development/cli/config#branching-config): the branch's project ref in `project_id` binds the block to the branch (the label is a user-chosen alias and is never matched on), any root config option can be overridden inside it, and unspecified options inherit from the base config. The block is therefore itself a sparse overlay over the merged base config. A value in a remote block that happens to equal a *global default* is not redundant: if the base config overrides the same property, removing the remote's value silently changes what that branch resolves to.
 
 ## Decision
 
@@ -17,6 +17,8 @@ The trap is where that mapping recurses. A `[remotes.<label>]` block is itself a
 - `subtractProjectConfig(config, baseline)` — returns the sparse config `config − baseline`: every value strictly deep-equal (order-sensitive) to the baseline's is removed, then sections left empty are dropped recursively.
 - `omitDefaultValues(config)` — `subtractProjectConfig` with the default config as baseline.
 
+What the output *is* depends on the baseline. In the primary case — subtracting the default config (`omitDefaultValues`) — the result is itself a valid config document: re-decoding refills exactly what was removed, so it denotes the same effective config *under the current schema's defaults*. That parenthetical is load-bearing: a sparse file's meaning leans on the defaults reference, so a default that changes in a future schema version changes the file's effective meaning — the dependency the PRFAQ's versioned-defaults open question exists to manage. Subtracting any other baseline — a remote block against the merged base config — yields an overlay that is meaningful only relative to that baseline and is not a standalone config. At the type level, `SparseProjectConfig` is a deep-partial of `ProjectConfig` either way and must be re-decoded before use where a complete config is required.
+
 Subtraction never recurses into `remotes` when the baseline is the default config: the default config has no remote blocks, so under subtract semantics user remote blocks survive untouched. **The correct baseline for a remote block is the merged base config, never the default config.** Callers that want to sparsify a remote block (CLI-2156/2064) must call `subtractProjectConfig(remoteBlock, mergedBaseConfig)` explicitly.
 
 All functions are pure and synchronous, operating on decoded `ProjectConfig` values, with no Effect in the public signature.
diff --git a/packages/config/src/sparse.ts b/packages/config/src/sparse.ts
index 1a8f79c42f..af081fcef1 100644
--- a/packages/config/src/sparse.ts
+++ b/packages/config/src/sparse.ts
@@ -5,10 +5,15 @@ import { ProjectConfigSchema, type ProjectConfig } from "./base.ts";
  * Sparse config subtraction — see `docs/adr/0017-sparse-config-subtraction.md`.
  *
  * A sparse config is a partial overlay containing only the values that differ
- * from some baseline; it is not a valid complete config on its own. Arrays are
- * compared wholesale (order-sensitive) and never subtracted element-wise, so a
- * sparse value is always either an entire array or an object subtree of kept
- * leaves — hence arrays survive `DeepPartial` unchanged below.
+ * from some baseline. In the primary case — subtracting the default config
+ * ({@link omitDefaultValues}) — the result is itself a valid config document:
+ * re-decoding refills exactly what was removed, so it denotes the same
+ * effective config under the current schema's defaults. Subtracting any other
+ * baseline (e.g. a remote block against the merged base config) yields an
+ * overlay meaningful only relative to that baseline. Arrays are compared
+ * wholesale (order-sensitive) and never subtracted element-wise, so a sparse
+ * value is always either an entire array or an object subtree of kept leaves —
+ * hence arrays survive `DeepPartial` unchanged below.
  */
 type DeepPartial<T> =
   T extends ReadonlyArray<unknown>
@@ -124,9 +129,11 @@ export function subtractValue(value: unknown, baseline: unknown): unknown {
  * Returns the sparse config `config − baseline`. Directional: a value equal to
  * the baseline's is removed even when it differs from the schema default, and
  * a value differing from the baseline's is kept even when it equals the schema
- * default. A `[remotes.*]` block's correct baseline is the merged base config,
- * never the default config — see ADR 0017 for why subtracting a remote block
- * against global defaults would silently change what the branch resolves to.
+ * default. A `[remotes.*]` block — config overrides for a specific persistent
+ * Supabase branch, bound to it by `project_id` — has the merged base config as
+ * its correct baseline, never the default config; see ADR 0017 for why
+ * subtracting a remote block against global defaults would silently change
+ * what the branch resolves to.
  */
 export function subtractProjectConfig(
   config: ProjectConfig,
@@ -143,8 +150,11 @@ export function subtractProjectConfig(config: ProjectConfig, baseline: ProjectCo
 /**
  * Returns the sparse config `config − default config`: only the values that
  * differ from their schema defaults, per {@link subtractProjectConfig}'s
- * semantics. `remotes` blocks pass through untouched (the default config has
- * none), and undefaulted `optionalKey` fields always survive when present.
+ * semantics. The result is itself a valid config document — re-decoding
+ * refills the removed defaults, yielding the same effective config. `remotes`
+ * blocks (per-persistent-branch overrides) pass through untouched (the
+ * default config has none), and undefaulted `optionalKey` fields always
+ * survive when present.
  */
 export function omitDefaultValues(config: ProjectConfig): SparseProjectConfig {
   return subtractProjectConfig(config, getDefaultProjectConfig());

From 0c418935428c4a033390741240cfd36f32ed4a6e Mon Sep 17 00:00:00 2001
From: Kanad Gupta <git@kanad.dev>
Date: Tue, 18 Aug 2026 16:23:16 -0700
Subject: [PATCH 4/9] chore: rename ADR

---
 ...se-config-subtraction.md => 0018-sparse-config-subtraction.md} | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename docs/adr/{0017-sparse-config-subtraction.md => 0018-sparse-config-subtraction.md} (100%)

diff --git a/docs/adr/0017-sparse-config-subtraction.md b/docs/adr/0018-sparse-config-subtraction.md
similarity index 100%
rename from docs/adr/0017-sparse-config-subtraction.md
rename to docs/adr/0018-sparse-config-subtraction.md

From 8e549997c3d77a0610678e1bb119b433c9d2f3e2 Mon Sep 17 00:00:00 2001
From: Kanad Gupta <git@kanad.dev>
Date: Tue, 18 Aug 2026 16:23:38 -0700
Subject: [PATCH 5/9] chore: update date

---
 docs/adr/0018-sparse-config-subtraction.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/adr/0018-sparse-config-subtraction.md b/docs/adr/0018-sparse-config-subtraction.md
index cb775af6c9..4e08d713ad 100644
--- a/docs/adr/0018-sparse-config-subtraction.md
+++ b/docs/adr/0018-sparse-config-subtraction.md
@@ -1,7 +1,7 @@
 # 0017. Sparse Config Subtraction
 
 **Status**: proposed
-**Date**: 2026-08-14
+**Date**: 2026-08-18
 
 ## Problem Statement
 

From 635c7dd81adecab46901e60b5ba6cd581cd3121e Mon Sep 17 00:00:00 2001
From: Kanad Gupta <git@kanad.dev>
Date: Tue, 18 Aug 2026 16:30:43 -0700
Subject: [PATCH 6/9] docs(config): remove CONTEXT.md and fold vocabulary into
 ADR 0018 (CLI-2155)

CONTEXT.md is not a convention this codebase follows. Its only content
not already defined in the ADR (base config, drift) is woven into ADR
0018's problem statement; the stale post-renumbering references (the
ADR's own 0017 heading, sparse.ts and sparse.unit.test.ts pointing at
ADR 0017) now say 0018.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 CONTEXT.md                                 | 29 ----------------------
 docs/adr/0018-sparse-config-subtraction.md |  6 ++---
 packages/config/src/sparse.ts              |  4 +--
 packages/config/src/sparse.unit.test.ts    |  2 +-
 4 files changed, 6 insertions(+), 35 deletions(-)
 delete mode 100644 CONTEXT.md

diff --git a/CONTEXT.md b/CONTEXT.md
deleted file mode 100644
index 9c5ddbfb0a..0000000000
--- a/CONTEXT.md
+++ /dev/null
@@ -1,29 +0,0 @@
-# Supabase CLI
-
-The Supabase CLI and its supporting packages, including `@supabase/config` — the schema and tooling for the `config.toml` project configuration file that config-driven development (diff/pull/push) is built on.
-
-## Language
-
-### Project configuration
-
-**Default config**:
-The `ProjectConfig` in which every value carries its schema-declared default — what a project means before anyone configures anything.
-_Avoid_: defaults reference, base config
-
-**Sparse config**:
-A partial config overlay containing only values that differ from some baseline. When the baseline is the default config it is itself a valid config that re-decodes to the same effective config under the current schema's defaults; against any other baseline it is meaningful only relative to that baseline.
-_Avoid_: minimal config, pruned config, massaged config
-
-**Subtract**:
-The directional operation `config − baseline` that produces a sparse config: remove every value deep-equal (order-sensitive) to the baseline's, then drop sections left empty.
-_Avoid_: prune, strip, massage
-
-**Remote block**:
-A `[remotes.<label>]` section declaring config overrides for a specific persistent Supabase branch — the branch's project ref in `project_id` binds the block (the label is a user-chosen alias), and unspecified options inherit from the base config. Its baseline is the merged base config, never the default config.
-_Avoid_: environment block, branch config
-
-**Base config**:
-The root-scope fields of a `config.toml`, before any remote block is overlaid.
-
-**Drift**:
-A difference between a project's effective remote configuration and the local config file.
diff --git a/docs/adr/0018-sparse-config-subtraction.md b/docs/adr/0018-sparse-config-subtraction.md
index 4e08d713ad..c52ccbcb44 100644
--- a/docs/adr/0018-sparse-config-subtraction.md
+++ b/docs/adr/0018-sparse-config-subtraction.md
@@ -1,13 +1,13 @@
-# 0017. Sparse Config Subtraction
+# 0018. Sparse Config Subtraction
 
 **Status**: proposed
 **Date**: 2026-08-18
 
 ## Problem Statement
 
-`config diff` (CLI-2156) and `config pull` (CLI-2064) compare a project's remote configuration against the local `config.toml`. The remote endpoint (`GET /v2/projects/{ref}/config`) returns the *effective* config — every setting reported, defaulted or not — and a locally decoded `ProjectConfig` likewise has every default filled in. Comparing these full objects directly would drown the user in hundreds of identical default values. CLI-2155 asks for a stored reference of config defaults and a mapping function that omits values matching them, so diffs stay readable and pulled files stay sparse.
+`config diff` (CLI-2156) and `config pull` (CLI-2064) compare a project's remote configuration against the local `config.toml` to surface *drift*: any difference between the project's effective remote configuration and the local file. The remote endpoint (`GET /v2/projects/{ref}/config`) returns the *effective* config — every setting reported, defaulted or not — and a locally decoded `ProjectConfig` likewise has every default filled in. Comparing these full objects directly would drown the user in hundreds of identical default values. CLI-2155 asks for a stored reference of config defaults and a mapping function that omits values matching them, so diffs stay readable and pulled files stay sparse.
 
-The trap is where that mapping recurses. A `[remotes.<label>]` block declares config overrides for a specific [persistent Supabase branch](https://supabase.com/docs/guides/local-development/cli/config#branching-config): the branch's project ref in `project_id` binds the block to the branch (the label is a user-chosen alias and is never matched on), any root config option can be overridden inside it, and unspecified options inherit from the base config. The block is therefore itself a sparse overlay over the merged base config. A value in a remote block that happens to equal a *global default* is not redundant: if the base config overrides the same property, removing the remote's value silently changes what that branch resolves to.
+The trap is where that mapping recurses. A `[remotes.<label>]` block declares config overrides for a specific [persistent Supabase branch](https://supabase.com/docs/guides/local-development/cli/config#branching-config): the branch's project ref in `project_id` binds the block to the branch (the label is a user-chosen alias and is never matched on), any root config option can be overridden inside it, and unspecified options inherit from the *base config* — the root-scope fields of the file, before any remote block is overlaid. The block is therefore itself a sparse overlay over the merged base config. A value in a remote block that happens to equal a *global default* is not redundant: if the base config overrides the same property, removing the remote's value silently changes what that branch resolves to.
 
 ## Decision
 
diff --git a/packages/config/src/sparse.ts b/packages/config/src/sparse.ts
index af081fcef1..8c4b346925 100644
--- a/packages/config/src/sparse.ts
+++ b/packages/config/src/sparse.ts
@@ -2,7 +2,7 @@ import { Schema } from "effect";
 import { ProjectConfigSchema, type ProjectConfig } from "./base.ts";
 
 /**
- * Sparse config subtraction — see `docs/adr/0017-sparse-config-subtraction.md`.
+ * Sparse config subtraction — see `docs/adr/0018-sparse-config-subtraction.md`.
  *
  * A sparse config is a partial overlay containing only the values that differ
  * from some baseline. In the primary case — subtracting the default config
@@ -131,7 +131,7 @@ export function subtractValue(value: unknown, baseline: unknown): unknown {
  * a value differing from the baseline's is kept even when it equals the schema
  * default. A `[remotes.*]` block — config overrides for a specific persistent
  * Supabase branch, bound to it by `project_id` — has the merged base config as
- * its correct baseline, never the default config; see ADR 0017 for why
+ * its correct baseline, never the default config; see ADR 0018 for why
  * subtracting a remote block against global defaults would silently change
  * what the branch resolves to.
  */
diff --git a/packages/config/src/sparse.unit.test.ts b/packages/config/src/sparse.unit.test.ts
index b5d33a22d2..e6caf89621 100644
--- a/packages/config/src/sparse.unit.test.ts
+++ b/packages/config/src/sparse.unit.test.ts
@@ -81,7 +81,7 @@ describe("omitDefaultValues", () => {
     // `api.max_rows = 1000` IS the global default, but inside a remote block
     // it overrides whatever the base config resolves to — subtracting it
     // against global defaults would silently change the branch's effective
-    // value. See ADR 0017: a remote block's baseline is the merged base
+    // value. See ADR 0018: a remote block's baseline is the merged base
     // config, never the default config.
     const config = decodeProjectConfig({
       api: { max_rows: 500 },

From a71749520cb6a32d942fba836f12d773fac717b6 Mon Sep 17 00:00:00 2001
From: Kanad Gupta <git@kanad.dev>
Date: Tue, 18 Aug 2026 17:15:09 -0700
Subject: [PATCH 7/9] fix(config): accept remote-block shape in subtraction and
 freeze the defaults memo (CLI-2155)

Review follow-ups on #6205: subtractProjectConfig/omitDefaultValues now
take BaseProjectConfig (ProjectConfig without the nested remotes), so
the ADR 0018 remote-block call type-checks without a cast; the memoized
default config is deeply frozen so a caller mutation cannot poison the
shared subtraction baseline. Both pinned by unit tests.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 docs/adr/0018-sparse-config-subtraction.md |  2 +-
 packages/config/src/index.ts               |  1 +
 packages/config/src/sparse.ts              | 37 ++++++++++++++++++----
 packages/config/src/sparse.unit.test.ts    | 28 ++++++++++++++++
 4 files changed, 60 insertions(+), 8 deletions(-)

diff --git a/docs/adr/0018-sparse-config-subtraction.md b/docs/adr/0018-sparse-config-subtraction.md
index c52ccbcb44..35c49f2c90 100644
--- a/docs/adr/0018-sparse-config-subtraction.md
+++ b/docs/adr/0018-sparse-config-subtraction.md
@@ -21,7 +21,7 @@ What the output *is* depends on the baseline. In the primary case — subtractin
 
 Subtraction never recurses into `remotes` when the baseline is the default config: the default config has no remote blocks, so under subtract semantics user remote blocks survive untouched. **The correct baseline for a remote block is the merged base config, never the default config.** Callers that want to sparsify a remote block (CLI-2156/2064) must call `subtractProjectConfig(remoteBlock, mergedBaseConfig)` explicitly.
 
-All functions are pure and synchronous, operating on decoded `ProjectConfig` values, with no Effect in the public signature.
+All functions are pure and synchronous, operating on decoded config values, with no Effect in the public signature. Subtraction accepts the shared base-config shape (`BaseProjectConfig`, a `ProjectConfig` without the nested `remotes`), which both full configs and decoded remote blocks satisfy — so the remote-block call above type-checks without a cast.
 
 ## Rationale
 
diff --git a/packages/config/src/index.ts b/packages/config/src/index.ts
index e230c823f5..2375d4e04d 100644
--- a/packages/config/src/index.ts
+++ b/packages/config/src/index.ts
@@ -50,6 +50,7 @@ export { projectConfigStoreLayer } from "./project-config.layer.ts";
 export { ProjectConfigStore } from "./project-config.service.ts";
 export { PROJECT_CONFIG_SCHEMA_URL } from "./schema-metadata.ts";
 export {
+  type BaseProjectConfig,
   type SparseProjectConfig,
   getDefaultProjectConfig,
   omitDefaultValues,
diff --git a/packages/config/src/sparse.ts b/packages/config/src/sparse.ts
index 8c4b346925..9be0803511 100644
--- a/packages/config/src/sparse.ts
+++ b/packages/config/src/sparse.ts
@@ -24,6 +24,14 @@ type DeepPartial<T> =
 
 export type SparseProjectConfig = DeepPartial<ProjectConfig>;
 
+/**
+ * The root-scope fields shared by a full {@link ProjectConfig} and a decoded
+ * `[remotes.*]` block (which has the same sections but no nested `remotes`).
+ * Subtraction accepts this shape so a remote block can be subtracted against
+ * the merged base config directly, as ADR 0018 prescribes, without a cast.
+ */
+export type BaseProjectConfig = Omit<ProjectConfig, "remotes">;
+
 const decodeProjectConfig = Schema.decodeUnknownSync(ProjectConfigSchema);
 
 let defaultProjectConfig: ProjectConfig | undefined;
@@ -37,14 +45,26 @@ let defaultProjectConfig: ProjectConfig | undefined;
  * (e.g. `project_id`, `api.external_url`) are absent.
  *
  * Memoized (and the memo shared with callers) rather than computed at module
- * load, so importing the package doesn't pay for a full schema decode; the
- * decoded config is deeply readonly by type, so sharing is safe.
+ * load, so importing the package doesn't pay for a full schema decode. The
+ * memo is deeply frozen before it is shared: it doubles as the module-wide
+ * subtraction baseline, so a caller mutation would silently corrupt every
+ * later {@link omitDefaultValues} result.
  */
 export function getDefaultProjectConfig(): ProjectConfig {
-  defaultProjectConfig ??= decodeProjectConfig({});
+  defaultProjectConfig ??= deepFreeze(decodeProjectConfig({}));
   return defaultProjectConfig;
 }
 
+function deepFreeze<T>(value: T): T {
+  if (typeof value === "object" && value !== null) {
+    for (const child of Object.values(value)) {
+      deepFreeze(child);
+    }
+    Object.freeze(value);
+  }
+  return value;
+}
+
 function isObject(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -136,13 +156,16 @@ export function subtractValue(value: unknown, baseline: unknown): unknown {
  * what the branch resolves to.
  */
 export function subtractProjectConfig(
-  config: ProjectConfig,
-  baseline: ProjectConfig,
+  config: BaseProjectConfig,
+  baseline: BaseProjectConfig,
 ): SparseProjectConfig;
 // The implementation signature stays untyped because TypeScript cannot verify
 // that a structural walk over `unknown` reconstructs a `DeepPartial` of its
 // input; the overload above is the contract, pinned by the unit tests.
-export function subtractProjectConfig(config: ProjectConfig, baseline: ProjectConfig): unknown {
+export function subtractProjectConfig(
+  config: BaseProjectConfig,
+  baseline: BaseProjectConfig,
+): unknown {
   const result = subtractValue(config, baseline);
   return isObject(result) ? result : {};
 }
@@ -156,6 +179,6 @@ export function subtractProjectConfig(config: ProjectConfig, baseline: ProjectCo
  * default config has none), and undefaulted `optionalKey` fields always
  * survive when present.
  */
-export function omitDefaultValues(config: ProjectConfig): SparseProjectConfig {
+export function omitDefaultValues(config: BaseProjectConfig): SparseProjectConfig {
   return subtractProjectConfig(config, getDefaultProjectConfig());
 }
diff --git a/packages/config/src/sparse.unit.test.ts b/packages/config/src/sparse.unit.test.ts
index e6caf89621..211fee0ed2 100644
--- a/packages/config/src/sparse.unit.test.ts
+++ b/packages/config/src/sparse.unit.test.ts
@@ -30,6 +30,17 @@ describe("getDefaultProjectConfig", () => {
     expect("project_id" in defaults).toBe(false);
     expect("external_url" in defaults.api).toBe(false);
   });
+
+  test("is deeply frozen so mutation cannot poison the shared baseline", () => {
+    const defaults = getDefaultProjectConfig();
+    expect(Object.isFrozen(defaults)).toBe(true);
+    expect(Object.isFrozen(defaults.api)).toBe(true);
+    expect(Object.isFrozen(defaults.api.schemas)).toBe(true);
+    expect(() => {
+      // @ts-expect-error -- readonly by type; pinning the runtime guard too
+      defaults.api.port = 9999;
+    }).toThrow(TypeError);
+  });
 });
 
 describe("omitDefaultValues", () => {
@@ -109,6 +120,23 @@ describe("subtractProjectConfig", () => {
     expect(subtractProjectConfig(config, config)).toEqual({});
   });
 
+  test("accepts a decoded remote block against the merged base config", () => {
+    // The ADR 0018 call shape for CLI-2156: a remote block has the root
+    // sections but no nested `remotes`, and must be accepted without a cast.
+    const config = decodeProjectConfig({
+      api: { max_rows: 500 },
+      remotes: { staging: { project_id: "abcdefghijklmnopqrst", api: { max_rows: 1000 } } },
+    });
+    const base = decodeProjectConfig({ api: { max_rows: 500 } });
+    const staging = config.remotes["staging"];
+    expect(staging).toBeDefined();
+    if (staging === undefined) return;
+    expect(subtractProjectConfig(staging, base)).toEqual({
+      project_id: "abcdefghijklmnopqrst",
+      api: { max_rows: 1000 },
+    });
+  });
+
   test("subtraction is directional against the baseline, not the defaults", () => {
     // The CLI-2156 remote-block scenario: subtract a merged effective config
     // against the merged BASE config. `api.max_rows: 1000` equals the global

From 24fab701f36cf5b98d53e962671a28d85640b1fd Mon Sep 17 00:00:00 2001
From: Kanad Gupta <git@kanad.dev>
Date: Wed, 19 Aug 2026 15:22:08 -0700
Subject: [PATCH 8/9] fix(config): harden record walks against __proto__ keys
 and lazify the encoded defaults (CLI-2155)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Review follow-ups on #6205:

- A record entry named `__proto__` (a valid function name or remote label —
  both smol-toml and JSON.parse produce it as an own key, and the schema
  decode preserves it) was silently dropped by `result[key] = value` hitting
  the legacy prototype setter, and `baseline[key]` read `Object.prototype`
  off the prototype chain. All three record walks (`subtractValue`,
  `mergeRemoteSubtree`, `stripFunctionRecordDefaults`) now use `Object.hasOwn`
  lookups and define own data properties via a shared `setOwnProperty`; a unit
  test pins the `__proto__` round-trip.
- `io.ts`'s encoded-defaults constant is now memoized like
  `getDefaultProjectConfig`, so importing `@supabase/config` no longer pays a
  schema decode+encode at module load — making sparse.ts's lazy-memo comment
  actually true.
- Documented that `omitDefaultValues` output is sparse at the root scope only
  (record-keyed entries carry materialized per-entry decoding defaults), in
  the docstring and ADR 0018's Negatives, and that baseline-only keys are
  ignored by design (absence means inherit).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 docs/adr/0018-sparse-config-subtraction.md |  1 +
 packages/config/src/io.ts                  | 31 +++++++++++++----
 packages/config/src/sparse.ts              | 40 +++++++++++++++++++---
 packages/config/src/sparse.unit.test.ts    | 16 +++++++++
 4 files changed, 77 insertions(+), 11 deletions(-)

diff --git a/docs/adr/0018-sparse-config-subtraction.md b/docs/adr/0018-sparse-config-subtraction.md
index 35c49f2c90..514317deb8 100644
--- a/docs/adr/0018-sparse-config-subtraction.md
+++ b/docs/adr/0018-sparse-config-subtraction.md
@@ -45,6 +45,7 @@ All functions are pure and synchronous, operating on decoded config values, with
 - Fields declared `optionalKey` without a `default` annotation can never be pruned; if a platform default exists for such a field, it must be added to the schema before subtraction can see it.
 - A user's explicitly-written default value (`max_rows = 1000` typed by hand) is indistinguishable from an omitted one and will be pruned; intent is not preserved.
 - Callers must know the remote-block baseline rule; misusing the default config as a remote block's baseline reintroduces the override-erasure bug this ADR exists to prevent.
+- `omitDefaultValues` output is sparse at the root scope only: record-keyed entries (`functions.*`, `remotes.*`) pass through whole with their per-entry decoding defaults materialized, since the default config's empty records offer no per-entry baseline. This cancels out in a diff (both sides carry the same materialized defaults), but a consumer rendering the sparse config directly must strip entry-level defaults itself, as the encoded write path does with `stripFunctionRecordDefaults`.
 
 ## Alternatives Considered
 
diff --git a/packages/config/src/io.ts b/packages/config/src/io.ts
index 3467e3de6b..b65435cf84 100644
--- a/packages/config/src/io.ts
+++ b/packages/config/src/io.ts
@@ -8,7 +8,7 @@ import {
 } from "./errors.ts";
 import { interpolateEnvReferencesAgainstSchema } from "./lib/env.ts";
 import { findProjectPaths } from "./paths.ts";
-import { getDefaultProjectConfig, subtractValue } from "./sparse.ts";
+import { getDefaultProjectConfig, setOwnProperty, subtractValue } from "./sparse.ts";
 import { loadProjectEnvironment, type ProjectEnvironment } from "./project.ts";
 
 const projectConfigSchemaKey = "$schema";
@@ -148,7 +148,17 @@ const decodeRemotesWithoutChecks = Schema.decodeUnknownSync(RemotesSchema, {
   disableChecks: true,
 });
 const encodeProjectConfig = Schema.encodeSync(ProjectConfigSchema);
-const defaultEncodedProjectConfig = encodeProjectConfig(getDefaultProjectConfig());
+
+let defaultEncodedProjectConfig: ReturnType<typeof encodeProjectConfig> | undefined;
+
+/**
+ * Memoized like `getDefaultProjectConfig` — only the save path needs the
+ * encoded defaults, so importing the package pays for no schema decode.
+ */
+function getDefaultEncodedProjectConfig(): ReturnType<typeof encodeProjectConfig> {
+  defaultEncodedProjectConfig ??= encodeProjectConfig(getDefaultProjectConfig());
+  return defaultEncodedProjectConfig;
+}
 const defaultEncodedFunctionConfig = {
   enabled: true,
   verify_jwt: true,
@@ -188,9 +198,12 @@ function mergeRemoteSubtree(
 ): Record<string, unknown> {
   const result: Record<string, unknown> = { ...base };
   for (const [key, value] of Object.entries(remote)) {
-    const existing = result[key];
-    result[key] =
-      isObject(existing) && isObject(value) ? mergeRemoteSubtree(existing, value) : value;
+    const existing = Object.hasOwn(result, key) ? result[key] : undefined;
+    setOwnProperty(
+      result,
+      key,
+      isObject(existing) && isObject(value) ? mergeRemoteSubtree(existing, value) : value,
+    );
   }
   return result;
 }
@@ -359,7 +372,11 @@ function stripFunctionRecordDefaults(value: unknown): unknown {
 
   const functions: Record<string, unknown> = {};
   for (const [name, functionConfig] of Object.entries(functionsValue)) {
-    functions[name] = subtractValue(functionConfig, defaultEncodedFunctionConfig) ?? {};
+    setOwnProperty(
+      functions,
+      name,
+      subtractValue(functionConfig, defaultEncodedFunctionConfig) ?? {},
+    );
   }
 
   return { ...value, functions };
@@ -367,7 +384,7 @@ function stripFunctionRecordDefaults(value: unknown): unknown {
 
 function encodeMinimalProjectConfig(config: ProjectConfig): Record<string, unknown> {
   const encoded = stripFunctionRecordDefaults(encodeProjectConfig(config));
-  const stripped = subtractValue(encoded, defaultEncodedProjectConfig);
+  const stripped = subtractValue(encoded, getDefaultEncodedProjectConfig());
   return isObject(stripped) ? stripped : {};
 }
 
diff --git a/packages/config/src/sparse.ts b/packages/config/src/sparse.ts
index 9be0803511..5206089f27 100644
--- a/packages/config/src/sparse.ts
+++ b/packages/config/src/sparse.ts
@@ -69,6 +69,22 @@ function isObject(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+/**
+ * Defines `key` as an own data property. Record keys come from user config
+ * files, and both smol-toml and `JSON.parse` produce an own `__proto__` key
+ * (a valid function name or remote label) that a plain `target[key] = value`
+ * assignment would feed to the legacy prototype setter, silently dropping the
+ * entry — or, for object values, swapping the target's prototype.
+ */
+export function setOwnProperty(target: Record<string, unknown>, key: string, value: unknown): void {
+  Object.defineProperty(target, key, {
+    value,
+    writable: true,
+    enumerable: true,
+    configurable: true,
+  });
+}
+
 function isEqualValue(left: unknown, right: unknown): boolean {
   if (Array.isArray(left) && Array.isArray(right)) {
     if (left.length !== right.length) {
@@ -93,7 +109,7 @@ function isEqualValue(left: unknown, right: unknown): boolean {
     }
 
     for (const key of leftKeys) {
-      if (!(key in right) || !isEqualValue(left[key], right[key])) {
+      if (!Object.hasOwn(right, key) || !isEqualValue(left[key], right[key])) {
         return false;
       }
     }
@@ -111,7 +127,10 @@ function isEqualValue(left: unknown, right: unknown): boolean {
  * arrays are removed wholesale on equality, never subtracted element-wise. A
  * key with no counterpart in the baseline is kept verbatim — which is exactly
  * how `remotes` and other record entries pass through untouched when the
- * baseline is the default config.
+ * baseline is the default config. Symmetrically, a baseline-only key is
+ * ignored by design: subtraction reports what `value` declares, and in
+ * overlay semantics absence means *inherit*, so a missing key is not a
+ * removal.
  *
  * Shared with `io.ts`, which subtracts *encoded* documents before writing
  * minimal config files; the typed entry points below operate on decoded
@@ -132,10 +151,13 @@ export function subtractValue(value: unknown, baseline: unknown): unknown {
     const result: Record<string, unknown> = {};
 
     for (const [key, child] of Object.entries(value)) {
-      const subtracted = subtractValue(child, baselineObject[key]);
+      const subtracted = subtractValue(
+        child,
+        Object.hasOwn(baselineObject, key) ? baselineObject[key] : undefined,
+      );
 
       if (subtracted !== undefined) {
-        result[key] = subtracted;
+        setOwnProperty(result, key, subtracted);
       }
     }
 
@@ -178,6 +200,16 @@ export function subtractProjectConfig(
  * blocks (per-persistent-branch overrides) pass through untouched (the
  * default config has none), and undefaulted `optionalKey` fields always
  * survive when present.
+ *
+ * The result is sparse at the root scope only: record-keyed entries
+ * (`functions.*`, `remotes.*`) survive whole, with every per-entry decoding
+ * default materialized — decoding fills them in, and the default config's
+ * empty records offer no per-entry baseline to subtract. This cancels out in
+ * a diff (both sides carry the same materialized defaults), but a consumer
+ * rendering the result directly must strip entry-level defaults itself. For a
+ * remote block that is necessarily the consumer's job — its correct baseline
+ * is the merged base config (ADR 0018); for function entries, `io.ts`'s
+ * `stripFunctionRecordDefaults` is the encoded-path precedent.
  */
 export function omitDefaultValues(config: BaseProjectConfig): SparseProjectConfig {
   return subtractProjectConfig(config, getDefaultProjectConfig());
diff --git a/packages/config/src/sparse.unit.test.ts b/packages/config/src/sparse.unit.test.ts
index 211fee0ed2..f055515bab 100644
--- a/packages/config/src/sparse.unit.test.ts
+++ b/packages/config/src/sparse.unit.test.ts
@@ -103,6 +103,22 @@ describe("omitDefaultValues", () => {
     expect(sparse.api).toEqual({ max_rows: 500 });
   });
 
+  test("preserves a record entry named __proto__ as an own data property", () => {
+    // Both smol-toml (`[functions.__proto__]`) and JSON.parse produce an own
+    // `__proto__` key, and the schema decode preserves it — so the subtraction
+    // walk must define it as an own data property rather than let a plain
+    // `result[key] = value` assignment hit the legacy prototype setter and
+    // silently drop the function from the sparse output.
+    const raw: unknown = JSON.parse('{"functions": {"__proto__": {"verify_jwt": false}}}');
+    const sparse = omitDefaultValues(decodeProjectConfig(raw));
+    const functions = sparse.functions ?? {};
+    expect(Object.hasOwn(functions, "__proto__")).toBe(true);
+    const entry = Object.getOwnPropertyDescriptor(functions, "__proto__")?.value;
+    expect(entry).toMatchObject({ verify_jwt: false });
+    // The walk must not have poisoned the container's prototype either.
+    expect(Object.getPrototypeOf(functions)).toBe(Object.prototype);
+  });
+
   test("does not mutate its input", () => {
     const config = decodeProjectConfig({
       api: { max_rows: 500 },

From d85bee0e44d889c2a1588aedd87c30eac57ba37e Mon Sep 17 00:00:00 2001
From: Kanad Gupta <git@kanad.dev>
Date: Wed, 19 Aug 2026 15:45:57 -0700
Subject: [PATCH 9/9] docs(config): require merged effective configs as
 subtraction operands (CLI-2155)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Review follow-up on #6205: subtractProjectConfig's advertised remote-block
call shape passed a standalone-decoded `[remotes.*]` block, but decoding a
sparse fragment materializes global defaults in every omitted section —
where the block meant to inherit from the base config. With base
`db.port = 54399` and a remote that omits `db`, the decoded block carries
the global default `54322`, the overlay retains it, and writing it back
flips the branch from inheriting the base's value to pinning the default.

The subtraction core is unchanged; the contract is corrected: both operands
must be *effective* configs, and a branch's is the raw remote subtree merged
over the raw base document before decoding (the same pre-decode order
`mergeRemoteSubtree` documents, precisely so remote schema defaults never
leak in). ADR 0018, the docstrings, and the unit test now pin that call
shape, with the base-only-override counterexample as the regression test.
`BaseProjectConfig` stays, re-justified: it keeps `remotes` out of the
contract so API-translated effective configs fit without a fabricated field.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 docs/adr/0018-sparse-config-subtraction.md |  6 ++---
 packages/config/src/sparse.ts              | 31 +++++++++++++++-------
 packages/config/src/sparse.unit.test.ts    | 29 ++++++++++++--------
 3 files changed, 43 insertions(+), 23 deletions(-)

diff --git a/docs/adr/0018-sparse-config-subtraction.md b/docs/adr/0018-sparse-config-subtraction.md
index 514317deb8..0bd3e91062 100644
--- a/docs/adr/0018-sparse-config-subtraction.md
+++ b/docs/adr/0018-sparse-config-subtraction.md
@@ -19,9 +19,9 @@ The trap is where that mapping recurses. A `[remotes.<label>]` block declares co
 
 What the output *is* depends on the baseline. In the primary case — subtracting the default config (`omitDefaultValues`) — the result is itself a valid config document: re-decoding refills exactly what was removed, so it denotes the same effective config *under the current schema's defaults*. That parenthetical is load-bearing: a sparse file's meaning leans on the defaults reference, so a default that changes in a future schema version changes the file's effective meaning — the dependency the PRFAQ's versioned-defaults open question exists to manage. Subtracting any other baseline — a remote block against the merged base config — yields an overlay that is meaningful only relative to that baseline and is not a standalone config. At the type level, `SparseProjectConfig` is a deep-partial of `ProjectConfig` either way and must be re-decoded before use where a complete config is required.
 
-Subtraction never recurses into `remotes` when the baseline is the default config: the default config has no remote blocks, so under subtract semantics user remote blocks survive untouched. **The correct baseline for a remote block is the merged base config, never the default config.** Callers that want to sparsify a remote block (CLI-2156/2064) must call `subtractProjectConfig(remoteBlock, mergedBaseConfig)` explicitly.
+Subtraction never recurses into `remotes` when the baseline is the default config: the default config has no remote blocks, so under subtract semantics user remote blocks survive untouched. Both operands must be *effective* configs — values in which every absence has already been resolved. A standalone-decoded `[remotes.*]` block is not one: decoding a sparse fragment materializes global defaults in every section it omitted, where the block meant to inherit from the base config. Subtracting such a block retains those materialized defaults wherever the base overrides the same field (base `db.port = 54399`, remote omits `db` → the decoded block carries the global default `54322`, which survives subtraction), and writing the overlay back flips the branch from inheriting the base's value to explicitly pinning the global default. **To sparsify a branch's config (CLI-2156/2064), subtract its merged effective config — the raw remote subtree merged over the raw base document *before* decoding, as `io.ts`'s `mergeRemoteSubtree` does precisely so remote schema defaults never leak in — against the base effective config, never the default config.**
 
-All functions are pure and synchronous, operating on decoded config values, with no Effect in the public signature. Subtraction accepts the shared base-config shape (`BaseProjectConfig`, a `ProjectConfig` without the nested `remotes`), which both full configs and decoded remote blocks satisfy — so the remote-block call above type-checks without a cast.
+All functions are pure and synchronous, operating on decoded config values, with no Effect in the public signature. Subtraction accepts the root-scope shape (`BaseProjectConfig`, a `ProjectConfig` without the nested `remotes`), keeping `remotes` out of its contract — an effective config translated from the Management API has no `remotes` of its own and still fits without a cast or a fabricated field.
 
 ## Rationale
 
@@ -44,7 +44,7 @@ All functions are pure and synchronous, operating on decoded config values, with
 
 - Fields declared `optionalKey` without a `default` annotation can never be pruned; if a platform default exists for such a field, it must be added to the schema before subtraction can see it.
 - A user's explicitly-written default value (`max_rows = 1000` typed by hand) is indistinguishable from an omitted one and will be pruned; intent is not preserved.
-- Callers must know the remote-block baseline rule; misusing the default config as a remote block's baseline reintroduces the override-erasure bug this ADR exists to prevent.
+- Callers must know the remote-block rules, and neither is enforceable at the type level: the config operand must be the branch's *merged effective* config (a standalone-decoded `[remotes.*]` block materializes global defaults where it meant to inherit), and the baseline must be the merged base config, never the default config. Violating either reintroduces the silent branch-behavior change this ADR exists to prevent.
 - `omitDefaultValues` output is sparse at the root scope only: record-keyed entries (`functions.*`, `remotes.*`) pass through whole with their per-entry decoding defaults materialized, since the default config's empty records offer no per-entry baseline. This cancels out in a diff (both sides carry the same materialized defaults), but a consumer rendering the sparse config directly must strip entry-level defaults itself, as the encoded write path does with `stripFunctionRecordDefaults`.
 
 ## Alternatives Considered
diff --git a/packages/config/src/sparse.ts b/packages/config/src/sparse.ts
index 5206089f27..7d35268c62 100644
--- a/packages/config/src/sparse.ts
+++ b/packages/config/src/sparse.ts
@@ -25,10 +25,12 @@ type DeepPartial<T> =
 export type SparseProjectConfig = DeepPartial<ProjectConfig>;
 
 /**
- * The root-scope fields shared by a full {@link ProjectConfig} and a decoded
- * `[remotes.*]` block (which has the same sections but no nested `remotes`).
- * Subtraction accepts this shape so a remote block can be subtracted against
- * the merged base config directly, as ADR 0018 prescribes, without a cast.
+ * The root-scope fields of a {@link ProjectConfig}, without the nested
+ * `remotes` record. Subtraction accepts this shape to keep `remotes` out of
+ * its contract: the operands are root-scope *effective* configs — e.g. the
+ * merged base config, or a branch's effective config translated from the
+ * Management API, which has no `remotes` of its own — so neither operand has
+ * to fabricate a `remotes` field to type-check.
  */
 export type BaseProjectConfig = Omit<ProjectConfig, "remotes">;
 
@@ -171,11 +173,22 @@ export function subtractValue(value: unknown, baseline: unknown): unknown {
  * Returns the sparse config `config − baseline`. Directional: a value equal to
  * the baseline's is removed even when it differs from the schema default, and
  * a value differing from the baseline's is kept even when it equals the schema
- * default. A `[remotes.*]` block — config overrides for a specific persistent
- * Supabase branch, bound to it by `project_id` — has the merged base config as
- * its correct baseline, never the default config; see ADR 0018 for why
- * subtracting a remote block against global defaults would silently change
- * what the branch resolves to.
+ * default.
+ *
+ * Both operands must be *effective* configs — values in which every absence
+ * has already been resolved (a decode of a complete document, or of a
+ * raw-merged one). A standalone-decoded `[remotes.*]` block is NOT one:
+ * decoding a sparse fragment materializes global defaults in every section it
+ * omitted, where the block meant to inherit from the base config, so the
+ * overlay would pin the branch to global defaults wherever the base overrides
+ * a field the block omits. To sparsify a branch's config (a `[remotes.*]`
+ * block declares overrides for a specific persistent Supabase branch, bound
+ * to it by `project_id`), subtract its merged effective config — the raw
+ * remote subtree merged over the raw base document *before* decoding, exactly
+ * as `io.ts`'s `mergeRemoteSubtree` does so remote schema defaults never leak
+ * in — against the base effective config, never the default config; see ADR
+ * 0018 for why the default-config baseline silently changes what the branch
+ * resolves to.
  */
 export function subtractProjectConfig(
   config: BaseProjectConfig,
diff --git a/packages/config/src/sparse.unit.test.ts b/packages/config/src/sparse.unit.test.ts
index f055515bab..5553a8ab75 100644
--- a/packages/config/src/sparse.unit.test.ts
+++ b/packages/config/src/sparse.unit.test.ts
@@ -136,21 +136,28 @@ describe("subtractProjectConfig", () => {
     expect(subtractProjectConfig(config, config)).toEqual({});
   });
 
-  test("accepts a decoded remote block against the merged base config", () => {
-    // The ADR 0018 call shape for CLI-2156: a remote block has the root
-    // sections but no nested `remotes`, and must be accepted without a cast.
-    const config = decodeProjectConfig({
-      api: { max_rows: 500 },
-      remotes: { staging: { project_id: "abcdefghijklmnopqrst", api: { max_rows: 1000 } } },
+  test("sparsifies a branch via its merged effective config, not the decoded block", () => {
+    // The ADR 0018 call shape for CLI-2156/2064: both operands are *effective*
+    // configs, and the branch's is the raw remote subtree merged over the raw
+    // base document BEFORE decoding. Decoding the sparse `[remotes.*]` block
+    // on its own would materialize the global default `db.port = 54322` in
+    // place of the omitted-and-therefore-inherited base override `54399`, and
+    // the overlay would wrongly pin the branch to the global default.
+    const rawBase = { api: { max_rows: 500 }, db: { port: 54399 } };
+    const rawRemote = { project_id: "abcdefghijklmnopqrst", api: { max_rows: 1000 } };
+    const base = decodeProjectConfig(rawBase);
+    const effectiveBranch = decodeProjectConfig({
+      ...rawBase,
+      ...rawRemote,
+      api: { ...rawBase.api, ...rawRemote.api },
     });
-    const base = decodeProjectConfig({ api: { max_rows: 500 } });
-    const staging = config.remotes["staging"];
-    expect(staging).toBeDefined();
-    if (staging === undefined) return;
-    expect(subtractProjectConfig(staging, base)).toEqual({
+    const overlay = subtractProjectConfig(effectiveBranch, base);
+    expect(overlay).toEqual({
       project_id: "abcdefghijklmnopqrst",
       api: { max_rows: 1000 },
     });
+    // The base-only `db.port` override the remote inherits must not surface.
+    expect(overlay).not.toHaveProperty("db");
   });
 
   test("subtraction is directional against the baseline, not the defaults", () => {