feat(pgpm): object-level apply routing (route a table and a function to different schemas)

[pyramation]

Summary

Extends pgpm.apply.json proxy modules with object-level routing: a single source schema's objects can now fan out to different target schemas — e.g. a table to shop_a and a function to analytics_a — instead of the whole schema going to one place. Targets are expressed as individual properties (no dotted identity strings), and cross-object references inside function bodies are rewritten to follow each object to its new home.

This consumes the upstream object-routing primitive shipped in @pgsql/transform@18.4.1 (constructive-io/pgsql-parser#319) — the SchemaRouter model resolving a target per (schema, name, namespace). This PR bumps the dep and wires it through the pgpm apply path. Backwards compatible: the existing whole-schema schemas map is unchanged.

Spec syntax (pgpm.apply.json)

{
  "source": "catalog-module",
  "schemas": { "catalog": "shop_a", "reporting": "analytics_a" },
  "route": [
    { "fromSchema": "catalog", "kind": "function", "name": "product_count", "toSchema": "analytics_a" }
  ]
}

• schemas — whole-schema default (now optional; at least one of schemas/route required).
• route[] — per-object overrides. kind ∈ table | view | function | procedure | type selects the routing namespace, so a table and a function of the same name route independently. Each route wins over the schema default for its object.

How it works

makeSchemaTranspiler now builds a single SchemaRouter (from schemaMap + routes) that drives both dimensions in lockstep:

• Change identity (renameChange): the object is read straight from the pgpm path schemas/<schema>/<kind>/<name> and its schema segment rewritten to the routed target — schemas/catalog/procedures/product_count → schemas/analytics_a/procedures/product_count while schemas/catalog/tables/products/table → schemas/shop_a/tables/products/table.

• SQL bodies (transformScript): transformSql(sql, router, …) moves each definition to its target and rewrites cross-object refs, so CREATE FUNCTION catalog.product_count() … SELECT count(*) FROM catalog.products becomes:

  CREATE FUNCTION analytics_a.product_count() ... SELECT count(*) FROM shop_a.products

  (definition follows the function route; the products reference follows the table's schema-level target).

Destinations that may or may not exist

Apply deploys into consumer-chosen namespaces that can pre-exist (a shared/reporting schema, another tenant). Every distinct target schema is passed to the transform's assumeSchemasExist, so CREATE SCHEMA is emitted idempotently (CREATE SCHEMA IF NOT EXISTS) — the same source applies cleanly whether or not the destination already exists.

Files

• pgpm/transform/src/bundle-driver.ts — SchemaObjectRoute, buildSchemaRouter, router-driven renameChange/transformScript; schemaMap now optional.
• pgpm/core/src/apply/{types,apply-spec}.ts — route field + validation (kinds, non-empty, at-least-one-of).
• pgpm/core/src/apply/materialize.ts — build router from schemas + route; idempotent target-schema creation.
• pgpm/transform/package.json + lockfile — bump @pgsql/transform to ^18.4.1.
• __fixtures__/apply/routing/* + pgpm/core/__tests__/apply/apply-routing.test.ts — a catalog-module source (schemas catalog + reporting) applied as two instances that route the table to the schema-level target and the function to the reporting-derived target.

Tests

• Spec parsing (object routes, route-only, invalid-shape rejections).
• materializeApplyModule: deploy-order rename, cross-schema body rewrite, idempotent schema DDL.
• E2E: deploys two instances; table lands in shop_a/shop_b, function in analytics_a/analytics_b; a pre-existing destination schema deploys without error; per-instance counts are independent; verify + independent revert.

@pgpmjs/transform (26) + @pgpmjs/core apply suite (23) pass; typecheck clean for both. Repo-wide pnpm lint is a pre-existing failure (ESLint 9 expects eslint.config.js; repo has .eslintrc.json) and is not run in CI.

Follow-up (not in this PR)

Object reuse/dedup across instances (a shared, tenant-independent helper deployed once) is deliberately out of scope: a table-dependent function cannot be shared across tenants, and safe shared-object revert needs reference counting. The durable model is shared-module decomposition (a dedicated pgpm module both instances require) rather than CREATE OR REPLACE emission. Tracked in constructive-io/constructive-planning#1298.

Link to Devin session: https://app.devin.ai/sessions/025fb88043964fdbb335ac5e39df2478
Requested by: @pyramation

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring