@prisma-next/extension-postgis 0.0.1

package/README.md

@@ -0,0 +1,283 @@
+# @prisma-next/extension-postgis
+
+Geospatial data for Prisma Next on PostgreSQL, powered by [PostGIS](https://postgis.net).
+
+Model points, lines, and polygons as first-class columns, query them with a type-safe DSL (`distance`, `containment`, `intersection`, `bounding-box`), and let the framework handle the wire format, SRID metadata, and `CREATE EXTENSION postgis` for you.
+
+## What you get
+
+- **`Geometry` column type** — store Points, LineStrings, Polygons, and their Multi-\* variants as a single `geometry` column. Optional SRID parameter (e.g. `Geometry(4326)` for WGS84 lng/lat) flows through to `contract.d.ts` and DDL.
+- **GeoJSON-shaped runtime values** — read and write geometries as plain `{ type, coordinates }` objects. No PostGIS-specific client APIs to learn.
+- **Seven query operations** on geometry columns: `distance`, `distanceSphere`, `dwithin`, `contains`, `within`, `intersects`, `intersectsBbox`.
+- **Automatic `CREATE EXTENSION`** — the control descriptor declares `postgis` as a database dependency, so `prisma-next db init` ensures the server has it enabled before the first migration runs.
+- **Both authoring paths** — works with PSL schemas and the TypeScript contract builder.
+
+## Prerequisites
+
+The PostGIS extension must be installable on your PostgreSQL server. Most managed providers (RDS, Cloud SQL, Supabase, Neon, …) include it; for local development the easiest route is the `postgis/postgis` Docker image, or a multi-arch fork like `imresamu/postgis` on Apple Silicon hosts.
+
+## Installation
+
+```bash
+pnpm add @prisma-next/extension-postgis
+```
+
+## Quick start
+
+A complete five-step example — see [`examples/prisma-next-postgis-demo`](../../../examples/prisma-next-postgis-demo) for the full version with a seeded database, a Next.js UI, and e2e tests.
+
+**1. Register the extension in `prisma-next.config.ts`:**
+
+```typescript
+import { defineConfig } from '@prisma-next/cli/config-types';
+import postgresAdapter from '@prisma-next/adapter-postgres/control';
+import sql from '@prisma-next/family-sql/control';
+import postgres from '@prisma-next/target-postgres/control';
+import postgis from '@prisma-next/extension-postgis/control';
+
+export default defineConfig({
+  family: sql,
+  target: postgres,
+  adapter: postgresAdapter,
+  extensionPacks: [postgis],
+});
+```
+
+**2. Declare a geometry column in your schema (PSL):**
+
+```prisma
+// use prisma-next
+
+types {
+  WgsGeometry = postgis.Geometry(4326)
+}
+
+model Cafe {
+  id       String      @id @default(uuid())
+  name     String
+  location WgsGeometry
+  @@map("cafe")
+}
+```
+
+**3. Emit the contract and apply the migration:**
+
+```bash
+pnpm prisma-next contract emit   # generates contract.json + contract.d.ts
+pnpm prisma-next db init         # CREATE EXTENSION postgis + CREATE TABLE
+```
+
+**4. Wire the extension into the runtime:**
+
+```typescript
+// src/prisma/db.ts
+import postgres from '@prisma-next/postgres/runtime';
+import postgis from '@prisma-next/extension-postgis/runtime';
+import type { Contract } from './contract.d';
+import contractJson from './contract.json' with { type: 'json' };
+
+export const db = postgres<Contract>({
+  contractJson,
+  extensions: [postgis],
+  url: process.env['DATABASE_URL']!,
+});
+```
+
+**5. Query:**
+
+```typescript
+import { point } from '@prisma-next/extension-postgis/geojson';
+import { db } from './prisma/db';
+
+const ferryBuilding = point(-122.3937, 37.7955, 4326);
+
+// Five nearest cafes, with their distance in metres.
+const closest = await db.runtime().execute(
+  db.sql.cafe
+    .select('id', 'name')
+    .select('meters', (f, fns) => fns.distanceSphere(f.location, ferryBuilding))
+    .orderBy((f, fns) => fns.distanceSphere(f.location, ferryBuilding), { direction: 'asc' })
+    .limit(5)
+    .build(),
+);
+```
+
+## Authoring schemas
+
+### PSL
+
+`postgis.Geometry(srid)` declares an SRID-constrained `geometry` column. Aliasing it via a `types {}` block keeps the SRID in one place when you have several geometry fields.
+
+```prisma
+types {
+  WgsGeometry = postgis.Geometry(4326)
+}
+
+model Route {
+  id   String      @id @default(uuid())
+  name String
+  path WgsGeometry        // LineStrings, polygons, points — all valid runtime values
+  @@map("route")
+}
+```
+
+`Geometry` without an SRID (`postgis.Geometry()`) is also valid for schemas that mix SRIDs at the row level.
+
+### TypeScript contract builder
+
+```typescript
+import { textColumn, varcharColumn } from '@prisma-next/adapter-postgres/column-types';
+import sqlFamily from '@prisma-next/family-sql/pack';
+import { defineContract, field, model } from '@prisma-next/sql-contract-ts/contract-builder';
+import { geometry, geometryColumn } from '@prisma-next/extension-postgis/column-types';
+import postgis from '@prisma-next/extension-postgis/pack';
+import postgres from '@prisma-next/target-postgres/pack';
+
+export const contract = defineContract({
+  family: sqlFamily,
+  target: postgres,
+  extensionPacks: { postgis },
+  models: {
+    Cafe: model('Cafe', {
+      fields: {
+        id: field.column(varcharColumn).id(),
+        name: field.column(textColumn),
+        location: field.column(geometry({ srid: 4326 })), // SRID-constrained
+      },
+    }).sql({ table: 'cafe' }),
+  },
+});
+```
+
+`geometry({ srid })` is the dimensioned form (emits `geometry(Geometry, 4326)` in DDL). `geometryColumn` is the unconstrained form for schemas that need flexibility.
+
+## Geometry values
+
+Runtime geometries are GeoJSON-shaped objects: `{ type, coordinates, srid? }`. Build them with the constructors from `@prisma-next/extension-postgis/geojson` rather than constructing the literals by hand — the constructors keep the coordinate ordering straight (`[lng, lat]`) and attach SRID metadata in one place.
+
+```typescript
+import { bboxPolygon, point, polygon } from '@prisma-next/extension-postgis/geojson';
+
+// Point — note: longitude first, latitude second.
+const sightglass = point(-122.4106, 37.7765, 4326);
+
+// Polygon — outer ring, optionally followed by holes. First point must equal last.
+const soma = polygon(
+  [
+    [-122.418, 37.77],
+    [-122.4, 37.77],
+    [-122.4, 37.785],
+    [-122.418, 37.785],
+    [-122.418, 37.77],
+  ],
+  4326,
+);
+
+// Axis-aligned bbox polygon — handy for "what's in this map viewport?" queries.
+const downtownViewport = bboxPolygon([-122.425, 37.775, -122.4, 37.8], 4326);
+```
+
+For `LineString`, `MultiPoint`, `MultiLineString`, and `MultiPolygon`, build the object literally:
+
+```typescript
+const route: Geometry = {
+  type: 'LineString',
+  coordinates: [[-122.4194, 37.7749], [-122.4106, 37.7765]],
+  srid: 4326,
+};
+```
+
+## Querying
+
+All seven operations are available on any `geometry` column inside the SQL DSL's `.where()`, `.select()`, and `.orderBy()` callbacks via the `fns` argument:
+
+```typescript
+// Within radius — uses ST_DistanceSphere for sphere-accurate metres.
+db.sql.cafe
+  .select('id', 'name')
+  .where((f, fns) => fns.distanceSphere(f.location, ferryBuilding) <= 2_000)
+  .build();
+
+// Point-in-polygon — "which neighborhood contains this point?"
+db.sql.neighborhood
+  .select('id', 'name')
+  .where((f, fns) => fns.contains(f.boundary, sightglass))
+  .build();
+
+// Index-friendly bounding-box filter for map viewport queries.
+db.sql.cafe
+  .select('id', 'name')
+  .where((f, fns) => fns.intersectsBbox(f.location, downtownViewport))
+  .build();
+
+// Routes that cross an arbitrary geometry (e.g. a road-closure polygon).
+db.sql.route
+  .select('id', 'name')
+  .where((f, fns) => fns.intersects(f.path, closurePolygon))
+  .build();
+```
+
+User-supplied geometries (the second argument to each operation) are bound as parameters, not interpolated. The codec encodes them as EWKT on the wire — see [Wire format](#wire-format) below.
+
+## Operations reference
+
+| Method | SQL | Returns | Use when |
+| --- | --- | --- | --- |
+| `distance(other)` | `ST_Distance(self, other)` | `float8` | Cartesian distance in the geometry's native units (degrees for SRID 4326). |
+| `distanceSphere(other)` | `ST_DistanceSphere(self, other)` | `float8` | Sphere-accurate metres between two lng/lat geometries. |
+| `dwithin(other, distance)` | `ST_DWithin(self, other, distance)` | `boolean` | Index-friendly "are these within X of each other?" — `distance` is in the geometry's native units. |
+| `contains(other)` | `ST_Contains(self, other)` | `boolean` | Point-in-polygon and polygon-contains-polygon checks. |
+| `within(other)` | `ST_Within(self, other)` | `boolean` | The inverse of `contains` — `A within B` ⇔ `B contains A`. |
+| `intersects(other)` | `ST_Intersects(self, other)` | `boolean` | Any kind of overlap between two geometries. |
+| `intersectsBbox(other)` | `self && other` | `boolean` | Cheap 2-D bounding-box overlap — fast viewport filtering. |
+
+### Picking the right distance op
+
+For SRID 4326 (WGS84) lng/lat data, `distance` returns **degrees**, which is rarely what you want. Use `distanceSphere` for human-friendly metres, or cast to `geography` upstream if you need ellipsoidal accuracy. `dwithin` interprets its `distance` argument in whatever units the inputs use — pair it with a projected SRS (or use `geography`) if you want metres directly.
+
+## SRID and units
+
+- Declare an SRID at the column level (`postgis.Geometry(4326)` / `geometry({ srid: 4326 })`) to constrain the column and have the runtime preserve the SRID through writes.
+- `point(lng, lat, srid)`, `polygon(rings, srid)`, and `bboxPolygon(box, srid)` attach the SRID to the value; the codec emits it as `SRID=4326;…` on the wire.
+- `distance` and `dwithin` are not unit-aware — they return whatever the SRS uses. If you need metres on WGS84 data, prefer `distanceSphere`.
+
+## Wire format
+
+- **JS → SQL**: values are emitted as EWKT (`SRID=4326;POINT(-122.39 37.79)`) and cast to `::geometry`. SRID is preserved through the `SRID=…;` prefix.
+- **SQL → JS**: `node-postgres` returns `geometry` columns as hex-encoded EWKB. The codec parses Point, LineString, Polygon, MultiPoint, MultiLineString, and MultiPolygon. Z and M coordinates are **not** supported in this release; if a column carries them, decoding throws so the mismatch is visible rather than silent.
+
+## Capabilities
+
+The extension declares a single capability flag:
+
+- `postgis.geometry` — gating signal for the `geometry` codec and the seven operations above.
+
+Features that require it should declare a `requires: ['postgis.geometry']` constraint in their capability gate.
+
+## Types
+
+For consumers that need to reference the value or operation shapes directly:
+
+```typescript
+import type { CodecTypes, Geometry } from '@prisma-next/extension-postgis/codec-types';
+import type { OperationTypes, QueryOperationTypes } from '@prisma-next/extension-postgis/operation-types';
+
+// CodecTypes['pg/geometry@1']['output'] = Geometry (the GeoJSON union)
+// Geometry<4326> is the SRID-branded form rendered into contract.d.ts.
+```
+
+## Demo
+
+The end-to-end demo in [`examples/prisma-next-postgis-demo`](../../../examples/prisma-next-postgis-demo) walks through:
+
+- Schema with three geometry shapes (`Point`, `LineString`, `Polygon`).
+- Seeded data (five SF cafes, two delivery routes, three neighborhood polygons).
+- One query file per operation — distance, radius, point-in-polygon, intersection, and bbox.
+- A Next.js App Router UI that runs the queries as server components and renders the results on a Leaflet map.
+- Vitest e2e tests that exercise the full pipeline against a local PostGIS container.
+
+## References
+
+- [PostGIS documentation](https://postgis.net/docs/)
+- [Prisma Next Architecture Overview](../../../docs/Architecture%20Overview.md)
+- [Extension Packs Guide](../../../docs/reference/Extension-Packs-Naming-and-Layout.md)

package/dist/codec-types-DODPC0GY.d.mts

@@ -0,0 +1,59 @@
+import { t as Geometry$1 } from "./geojson-Cj4ldHQ0.mjs";
+import { AnyCodecDescriptor, CodecCallContext, CodecDescriptorImpl, CodecImpl, CodecInstanceContext } from "@prisma-next/framework-components/codec";
+import { JsonValue } from "@prisma-next/contract/types";
+import { ExtractCodecTypes } from "@prisma-next/sql-relational-core/ast";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+
+//#region src/core/constants.d.ts
+declare const POSTGIS_GEOMETRY_CODEC_ID: "pg/geometry@1";
+//#endregion
+//#region src/core/codecs.d.ts
+type GeometryParams = {
+  readonly srid: number;
+};
+declare class PostgisGeometryCodec extends CodecImpl<typeof POSTGIS_GEOMETRY_CODEC_ID, readonly ['equality'], string, Geometry$1> {
+  constructor(descriptor: AnyCodecDescriptor);
+  encode(value: Geometry$1, _ctx: CodecCallContext): Promise<string>;
+  decode(wire: string, _ctx: CodecCallContext): Promise<Geometry$1>;
+  encodeJson(value: Geometry$1): JsonValue;
+  decodeJson(json: JsonValue): Geometry$1;
+}
+declare class PostgisGeometryDescriptor extends CodecDescriptorImpl<GeometryParams> {
+  readonly codecId: "pg/geometry@1";
+  readonly traits: readonly ["equality"];
+  readonly targetTypes: readonly ["geometry"];
+  readonly meta: {
+    readonly db: {
+      readonly sql: {
+        readonly postgres: {
+          readonly nativeType: "geometry";
+        };
+      };
+    };
+  };
+  readonly paramsSchema: StandardSchemaV1<GeometryParams>;
+  renderOutputType(params: GeometryParams): string;
+  /**
+   * The runtime calls `factory(undefined)(ctx)` to materialize a
+   * representative codec for parameterised descriptors that ship a
+   * no-params column variant (here, `geometryColumn` vs `geometry({ srid })`).
+   * The runtime cast widens `params` to `unknown`, so guarding with an
+   * optional read keeps the typed call site (`factory({ srid })`)
+   * strict while still producing an SRID-agnostic codec for
+   * representative use. Encode/decode for an unparameterised column
+   * runs through this representative; the wire format already carries
+   * SRID inside the EWKT/EWKB payload, so it's dimension-independent.
+   */
+  factory(_params: GeometryParams): (ctx: CodecInstanceContext) => PostgisGeometryCodec;
+}
+declare const codecDescriptorMap: {
+  readonly geometry: PostgisGeometryDescriptor;
+};
+type CodecTypes$1 = ExtractCodecTypes<typeof codecDescriptorMap>;
+//#endregion
+//#region src/types/codec-types.d.ts
+type Geometry<_Srid extends number = number> = Geometry$1;
+type CodecTypes = CodecTypes$1;
+//#endregion
+export { Geometry as n, CodecTypes as t };
+//# sourceMappingURL=codec-types-DODPC0GY.d.mts.map

package/dist/codec-types-DODPC0GY.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec-types-DODPC0GY.d.mts","names":[],"sources":["../src/core/constants.ts","../src/core/codecs.ts","../src/types/codec-types.ts"],"mappings":";;;;;;;cAAa,yBAAA;;;KCmDR,cAAA;EAAA,SAA4B,IAAA;AAAA;AAAA,cA2CpB,oBAAA,SAA6B,SAAA,QACjC,yBAAA,iCAGP,UAAA;cAEY,UAAA,EAAY,kBAAA;EAIlB,MAAA,CAAO,KAAA,EAAO,UAAA,EAAU,IAAA,EAAM,gBAAA,GAAmB,OAAA;EAKjD,MAAA,CAAO,IAAA,UAAc,IAAA,EAAM,gBAAA,GAAmB,OAAA,CAAQ,UAAA;EAO5D,UAAA,CAAW,KAAA,EAAO,UAAA,GAAW,SAAA;EAK7B,UAAA,CAAW,IAAA,EAAM,SAAA,GAAY,UAAA;AAAA;AAAA,cAMlB,yBAAA,SAAkC,mBAAA,CAAoB,cAAA;EAAA,SAC/C,OAAA;EAAA,SACA,MAAA;EAAA,SACA,WAAA;EAAA,SACA,IAAA;IAAA;;;;;;;;WACA,YAAA,EAAc,gBAAA,CAAiB,cAAA;EACxC,gBAAA,CAAiB,MAAA,EAAQ,cAAA;EAZvB;;;;AAMb;;;;;;;EAsBW,OAAA,CAAQ,OAAA,EAAS,cAAA,IAAkB,GAAA,EAAK,oBAAA,KAAyB,oBAAA;AAAA;AAAA,cAqCtE,kBAAA;EAAA,mBAEI,yBAAA;AAAA;AAAA,KAEE,YAAA,GAAa,iBAAA,QAAyB,kBAAA;;;KCjLtC,QAAA,kCAA0C,UAAA;AAAA,KAE1C,UAAA,GAAa,YAAA"}

package/dist/codec-types.d.mts

@@ -0,0 +1,2 @@
+import { n as Geometry, t as CodecTypes } from "./codec-types-DODPC0GY.mjs";
+export { type CodecTypes, type Geometry };

package/dist/codec-types.mjs

@@ -0,0 +1 @@
+export {};

package/dist/column-types.d.mts

@@ -0,0 +1,26 @@
+import { ColumnTypeDescriptor } from "@prisma-next/framework-components/codec";
+
+//#region src/exports/column-types.d.ts
+declare const geometryColumn: {
+  readonly codecId: "pg/geometry@1";
+  readonly nativeType: "geometry";
+};
+/**
+ * Build an SRID-constrained geometry column descriptor.
+ *
+ * @example
+ *   .column('location', { type: geometry({ srid: 4326 }), nullable: false })
+ *   // Produces: nativeType: 'geometry', typeParams: { srid: 4326 }
+ *
+ * @throws {RangeError} If `srid` is not a non-negative integer.
+ */
+declare function geometry<S extends number>(options: {
+  readonly srid: S;
+}): ColumnTypeDescriptor & {
+  readonly typeParams: {
+    readonly srid: S;
+  };
+};
+//#endregion
+export { geometry, geometryColumn };
+//# sourceMappingURL=column-types.d.mts.map

package/dist/column-types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"column-types.d.mts","names":[],"sources":["../src/exports/column-types.ts"],"mappings":";;;cAWa,cAAA;EAAA,SAG4B,OAAA;EAAA,SAAA,UAAA;AAAA;;;;;;;;;;iBAWzB,QAAA,kBAAA,CAA2B,OAAA;EAAA,SAChC,IAAA,EAAM,CAAA;AAAA,IACb,oBAAA;EAAA,SAAkC,UAAA;IAAA,SAAuB,IAAA,EAAM,CAAA;EAAA;AAAA"}

package/dist/column-types.mjs

@@ -0,0 +1,28 @@
+import { t as POSTGIS_GEOMETRY_CODEC_ID } from "./constants-dLvIWSgv.mjs";
+//#region src/exports/column-types.ts
+const geometryColumn = {
+	codecId: POSTGIS_GEOMETRY_CODEC_ID,
+	nativeType: "geometry"
+};
+/**
+* Build an SRID-constrained geometry column descriptor.
+*
+* @example
+*   .column('location', { type: geometry({ srid: 4326 }), nullable: false })
+*   // Produces: nativeType: 'geometry', typeParams: { srid: 4326 }
+*
+* @throws {RangeError} If `srid` is not a non-negative integer.
+*/
+function geometry(options) {
+	const { srid } = options;
+	if (!Number.isInteger(srid) || srid < 0) throw new RangeError(`postgis: srid must be a non-negative integer, got ${srid}`);
+	return {
+		codecId: POSTGIS_GEOMETRY_CODEC_ID,
+		nativeType: "geometry",
+		typeParams: { srid }
+	};
+}
+//#endregion
+export { geometry, geometryColumn };
+
+//# sourceMappingURL=column-types.mjs.map

package/dist/column-types.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"column-types.mjs","names":[],"sources":["../src/exports/column-types.ts"],"sourcesContent":["/**\n * Column type descriptors for the PostGIS extension.\n *\n * Use `geometryColumn` for an untyped `geometry` column, or\n * `geometry({ srid })` to declare an SRID-constrained column whose DDL\n * comes out as `geometry(Geometry, <srid>)`.\n */\n\nimport type { ColumnTypeDescriptor } from '@prisma-next/framework-components/codec';\nimport { POSTGIS_GEOMETRY_CODEC_ID } from '../core/constants';\n\nexport const geometryColumn = {\n  codecId: POSTGIS_GEOMETRY_CODEC_ID,\n  nativeType: 'geometry',\n} as const satisfies ColumnTypeDescriptor;\n\n/**\n * Build an SRID-constrained geometry column descriptor.\n *\n * @example\n *   .column('location', { type: geometry({ srid: 4326 }), nullable: false })\n *   // Produces: nativeType: 'geometry', typeParams: { srid: 4326 }\n *\n * @throws {RangeError} If `srid` is not a non-negative integer.\n */\nexport function geometry<S extends number>(options: {\n  readonly srid: S;\n}): ColumnTypeDescriptor & { readonly typeParams: { readonly srid: S } } {\n  const { srid } = options;\n  if (!Number.isInteger(srid) || srid < 0) {\n    throw new RangeError(`postgis: srid must be a non-negative integer, got ${srid}`);\n  }\n  return {\n    codecId: POSTGIS_GEOMETRY_CODEC_ID,\n    nativeType: 'geometry',\n    typeParams: { srid },\n  } as const;\n}\n"],"mappings":";;AAWA,MAAa,iBAAiB;CAC5B,SAAS;CACT,YAAY;CACb;;;;;;;;;;AAWD,SAAgB,SAA2B,SAE8B;CACvE,MAAM,EAAE,SAAS;CACjB,IAAI,CAAC,OAAO,UAAU,KAAK,IAAI,OAAO,GACpC,MAAM,IAAI,WAAW,qDAAqD,OAAO;CAEnF,OAAO;EACL,SAAS;EACT,YAAY;EACZ,YAAY,EAAE,MAAM;EACrB"}

package/dist/constants-dLvIWSgv.mjs

@@ -0,0 +1,6 @@
+//#region src/core/constants.ts
+const POSTGIS_GEOMETRY_CODEC_ID = "pg/geometry@1";
+//#endregion
+export { POSTGIS_GEOMETRY_CODEC_ID as t };
+
+//# sourceMappingURL=constants-dLvIWSgv.mjs.map

package/dist/constants-dLvIWSgv.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants-dLvIWSgv.mjs","names":[],"sources":["../src/core/constants.ts"],"sourcesContent":["export const POSTGIS_GEOMETRY_CODEC_ID = 'pg/geometry@1' as const;\n\nexport const SRID_WGS84 = 4326 as const;\n"],"mappings":";AAAA,MAAa,4BAA4B"}

package/dist/control.d.mts

@@ -0,0 +1,7 @@
+import { SqlControlExtensionDescriptor } from "@prisma-next/family-sql/control";
+
+//#region src/exports/control.d.ts
+declare const postgisExtensionDescriptor: SqlControlExtensionDescriptor<'postgres'>;
+//#endregion
+export { postgisExtensionDescriptor as default, postgisExtensionDescriptor };
+//# sourceMappingURL=control.d.mts.map

package/dist/control.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"control.d.mts","names":[],"sources":["../src/exports/control.ts"],"mappings":";;;cA+EM,0BAAA,EAA4B,6BAAA"}

package/dist/control.mjs

@@ -0,0 +1,189 @@
+import { t as POSTGIS_GEOMETRY_CODEC_ID } from "./constants-dLvIWSgv.mjs";
+import { n as postgisQueryOperations, t as postgisPackMeta } from "./descriptor-meta-DUKzIH9c.mjs";
+import { contractSpaceFromJson } from "@prisma-next/migration-tools/spaces";
+//#region migrations/20260601T0000_install_postgis_extension/migration.json
+var migration_default = {
+	from: null,
+	to: "sha256:01622b3970e0ee2a582cc4c857bca7f6ed970f21b23f44e3f2781eea0be7d5eb",
+	labels: [],
+	providedInvariants: ["postgis:install-postgis-v1"],
+	createdAt: "2026-06-01T00:00:00.000Z",
+	fromContract: null,
+	toContract: {
+		"schemaVersion": "1",
+		"targetFamily": "sql",
+		"target": "postgres",
+		"profileHash": "sha256:1a8dbe044289f30a1de958fe800cc5a8378b285d2e126a8c44b58864bac2c18e",
+		"roots": {},
+		"models": {},
+		"storage": {
+			"storageHash": "sha256:01622b3970e0ee2a582cc4c857bca7f6ed970f21b23f44e3f2781eea0be7d5eb",
+			"tables": {},
+			"types": { "geometry": {
+				"codecId": "pg/geometry@1",
+				"nativeType": "geometry",
+				"typeParams": {}
+			} }
+		},
+		"capabilities": {
+			"postgres": {
+				"jsonAgg": true,
+				"lateral": true,
+				"limit": true,
+				"orderBy": true,
+				"returning": true
+			},
+			"sql": {
+				"defaultInInsert": true,
+				"enums": true,
+				"returning": true
+			}
+		},
+		"extensionPacks": {},
+		"meta": {},
+		"_generated": {
+			"warning": "⚠️  GENERATED FILE - DO NOT EDIT",
+			"message": "This file is automatically generated by \"prisma-next contract emit\".",
+			"regenerate": "To regenerate, run: prisma-next contract emit"
+		}
+	},
+	hints: {
+		"used": [],
+		"applied": [],
+		"plannerVersion": "2.0.0"
+	},
+	migrationHash: "sha256:87029e185c726572b12a1383e3687dd9e3b19261f70bf75bbb3b76f884608597"
+};
+//#endregion
+//#region migrations/20260601T0000_install_postgis_extension/ops.json
+var ops_default = [{
+	"id": "postgis.install-postgis-extension",
+	"label": "Enable extension \"postgis\"",
+	"operationClass": "additive",
+	"invariantId": "postgis:install-postgis-v1",
+	"target": {
+		"id": "postgres",
+		"details": {
+			"schema": "public",
+			"objectType": "dependency",
+			"name": "postgis"
+		}
+	},
+	"precheck": [{
+		"description": "verify extension \"postgis\" is not already enabled",
+		"sql": "SELECT NOT EXISTS (SELECT 1 FROM pg_extension WHERE extname = 'postgis')"
+	}],
+	"execute": [{
+		"description": "create extension \"postgis\"",
+		"sql": "CREATE EXTENSION IF NOT EXISTS postgis"
+	}],
+	"postcheck": [{
+		"description": "confirm extension \"postgis\" is enabled",
+		"sql": "SELECT EXISTS (SELECT 1 FROM pg_extension WHERE extname = 'postgis')"
+	}]
+}];
+//#endregion
+//#region migrations/refs/head.json
+var head_default = {
+	hash: "sha256:01622b3970e0ee2a582cc4c857bca7f6ed970f21b23f44e3f2781eea0be7d5eb",
+	invariants: ["postgis:install-postgis-v1"]
+};
+//#endregion
+//#region src/contract.json
+var contract_default = {
+	schemaVersion: "1",
+	targetFamily: "sql",
+	target: "postgres",
+	profileHash: "sha256:1a8dbe044289f30a1de958fe800cc5a8378b285d2e126a8c44b58864bac2c18e",
+	roots: {},
+	models: {},
+	storage: {
+		"storageHash": "sha256:01622b3970e0ee2a582cc4c857bca7f6ed970f21b23f44e3f2781eea0be7d5eb",
+		"tables": {},
+		"types": { "geometry": {
+			"codecId": "pg/geometry@1",
+			"nativeType": "geometry",
+			"typeParams": {}
+		} }
+	},
+	capabilities: {
+		"postgres": {
+			"jsonAgg": true,
+			"lateral": true,
+			"limit": true,
+			"orderBy": true,
+			"returning": true
+		},
+		"sql": {
+			"defaultInInsert": true,
+			"enums": true,
+			"returning": true
+		}
+	},
+	extensionPacks: {},
+	meta: {},
+	_generated: {
+		"warning": "⚠️  GENERATED FILE - DO NOT EDIT",
+		"message": "This file is automatically generated by \"prisma-next contract emit\".",
+		"regenerate": "To regenerate, run: prisma-next contract emit"
+	}
+};
+//#endregion
+//#region src/core/contract-space-constants.ts
+/**
+* Static names and identifiers used across postgis's contract space.
+*
+* Centralised here so the contract IR (`./contract`), the baseline
+* migration ops (`./migrations`), the head ref, and the descriptor
+* (`../exports/control`) all reference the same values without typos.
+*
+* The space identifier `'postgis'` is what the framework writes to
+* `migrations/` in the user's repo and what the marker table's
+* `space` column carries for postgis-owned rows.
+*
+* The `postgis:*` invariantId namespace is locked here — once
+* published, an invariantId is immutable so downstream consumers can
+* reference it by literal string match.
+*/
+const POSTGIS_SPACE_ID = "postgis";
+const POSTGIS_BASELINE_MIGRATION_NAME = "20260601T0000_install_postgis_extension";
+//#endregion
+//#region src/exports/control.ts
+const geometryControlPlaneHooks = {
+	expandNativeType: ({ nativeType, typeParams }) => {
+		const srid = typeParams?.["srid"];
+		if (typeof srid === "number" && Number.isInteger(srid) && srid >= 0) return `${nativeType}(Geometry,${srid})`;
+		return nativeType;
+	},
+	resolveIdentityValue: () => null
+};
+const postgisContractSpace = contractSpaceFromJson({
+	contractJson: contract_default,
+	migrations: [{
+		dirName: POSTGIS_BASELINE_MIGRATION_NAME,
+		metadata: migration_default,
+		ops: ops_default
+	}],
+	headRef: head_default
+});
+const postgisExtensionDescriptor = {
+	...postgisPackMeta,
+	id: POSTGIS_SPACE_ID,
+	contractSpace: postgisContractSpace,
+	types: {
+		...postgisPackMeta.types,
+		codecTypes: {
+			...postgisPackMeta.types.codecTypes,
+			controlPlaneHooks: { [POSTGIS_GEOMETRY_CODEC_ID]: geometryControlPlaneHooks }
+		}
+	},
+	queryOperations: () => postgisQueryOperations(),
+	create: () => ({
+		familyId: "sql",
+		targetId: "postgres"
+	})
+};
+//#endregion
+export { postgisExtensionDescriptor as default, postgisExtensionDescriptor };
+
+//# sourceMappingURL=control.mjs.map

package/dist/control.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"control.mjs","names":["baselineMetadata","baselineOps"],"sources":["../migrations/20260601T0000_install_postgis_extension/migration.json","../migrations/20260601T0000_install_postgis_extension/ops.json","../migrations/refs/head.json","../src/contract.json","../src/core/contract-space-constants.ts","../src/exports/control.ts"],"sourcesContent":["","","","","/**\n * Static names and identifiers used across postgis's contract space.\n *\n * Centralised here so the contract IR (`./contract`), the baseline\n * migration ops (`./migrations`), the head ref, and the descriptor\n * (`../exports/control`) all reference the same values without typos.\n *\n * The space identifier `'postgis'` is what the framework writes to\n * `migrations/` in the user's repo and what the marker table's\n * `space` column carries for postgis-owned rows.\n *\n * The `postgis:*` invariantId namespace is locked here — once\n * published, an invariantId is immutable so downstream consumers can\n * reference it by literal string match.\n */\n\nexport const POSTGIS_SPACE_ID = 'postgis' as const;\n\nexport const POSTGIS_NATIVE_TYPE = 'geometry' as const;\n\nexport const POSTGIS_BASELINE_MIGRATION_NAME = '20260601T0000_install_postgis_extension' as const;\n\n/**\n * `postgis:*` invariantIds emitted by the baseline migration. Each id,\n * once published, is immutable: downstream consumers (other extensions,\n * the marker table) reference them by literal string match.\n */\nexport const POSTGIS_INVARIANTS = {\n  installPostgis: 'postgis:install-postgis-v1',\n} as const;\n","/**\n * Control-plane descriptor for the postgis extension.\n *\n * **Contract-space package layout.** The extension's contract\n * + migrations are emitted by the same pipeline application authors use:\n *\n *   `prisma-next contract emit` → `<package>/src/contract.{json,d.ts}`\n *   `prisma-next migration plan` → `<package>/migrations/<dir>/...`\n *\n * The descriptor wires those JSON artefacts via JSON-import declarations\n * so they flow through the consuming application's module resolver\n * without filesystem assumptions, and synthesises the canonical\n * `MigrationPackage` shape for the framework's runner / verifier to\n * consume.\n *\n * Wired surfaces:\n *\n *   - `contractSpace.{contractJson,migrations,headRef}` — sourced from\n *     the on-disk artefacts emitted by `build:contract-space`.\n *   - `types.codecTypes.controlPlaneHooks[POSTGIS_GEOMETRY_CODEC_ID]` —\n *     codec control hooks (`expandNativeType`, `resolveIdentityValue`)\n *     the SQL planner extracts via `extractCodecControlHooks` and uses\n *     to render `geometry(Geometry,${srid})` column types.\n *\n * @see docs/architecture docs/adrs/ADR 212 - Contract spaces.md\n *   (contract-space package layout convention).\n */\n\nimport type { Contract } from '@prisma-next/contract/types';\nimport type {\n  CodecControlHooks,\n  SqlControlExtensionDescriptor,\n} from '@prisma-next/family-sql/control';\nimport { contractSpaceFromJson } from '@prisma-next/migration-tools/spaces';\nimport type { SqlStorage } from '@prisma-next/sql-contract/types';\nimport baselineMetadata from '../../migrations/20260601T0000_install_postgis_extension/migration.json' with {\n  type: 'json',\n};\nimport baselineOps from '../../migrations/20260601T0000_install_postgis_extension/ops.json' with {\n  type: 'json',\n};\nimport headRef from '../../migrations/refs/head.json' with { type: 'json' };\nimport contractJson from '../contract.json' with { type: 'json' };\nimport { POSTGIS_GEOMETRY_CODEC_ID } from '../core/constants';\nimport {\n  POSTGIS_BASELINE_MIGRATION_NAME,\n  POSTGIS_SPACE_ID,\n} from '../core/contract-space-constants';\nimport { postgisPackMeta, postgisQueryOperations } from '../core/descriptor-meta';\n\nconst geometryControlPlaneHooks: CodecControlHooks = {\n  expandNativeType: ({ nativeType, typeParams }) => {\n    const srid = typeParams?.['srid'];\n    if (typeof srid === 'number' && Number.isInteger(srid) && srid >= 0) {\n      // PostGIS prints the type-modifier list without a space — match\n      // it here so the verifier doesn't see `geometry(Geometry, 4326)`\n      // (DDL) mismatch `geometry(Geometry,4326)` (introspected).\n      return `${nativeType}(Geometry,${srid})`;\n    }\n    return nativeType;\n  },\n  // PostGIS has no canonical \"identity\" geometry; backfilling a\n  // non-null column requires the user to supply a valid value, so we\n  // don't synthesise one here.\n  resolveIdentityValue: () => null,\n};\n\nconst postgisContractSpace = contractSpaceFromJson<Contract<SqlStorage>>({\n  contractJson,\n  migrations: [\n    {\n      dirName: POSTGIS_BASELINE_MIGRATION_NAME,\n      metadata: baselineMetadata,\n      ops: baselineOps,\n    },\n  ],\n  headRef,\n});\n\nconst postgisExtensionDescriptor: SqlControlExtensionDescriptor<'postgres'> = {\n  ...postgisPackMeta,\n  id: POSTGIS_SPACE_ID,\n  contractSpace: postgisContractSpace,\n  types: {\n    ...postgisPackMeta.types,\n    codecTypes: {\n      ...postgisPackMeta.types.codecTypes,\n      controlPlaneHooks: {\n        [POSTGIS_GEOMETRY_CODEC_ID]: geometryControlPlaneHooks,\n      },\n    },\n  },\n  queryOperations: () => postgisQueryOperations(),\n  create: () => ({\n    familyId: 'sql' as const,\n    targetId: 'postgres' as const,\n  }),\n};\n\nexport { postgisExtensionDescriptor };\nexport default postgisExtensionDescriptor;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AIgBA,MAAa,mBAAmB;AAIhC,MAAa,kCAAkC;;;AC8B/C,MAAM,4BAA+C;CACnD,mBAAmB,EAAE,YAAY,iBAAiB;EAChD,MAAM,OAAO,aAAa;EAC1B,IAAI,OAAO,SAAS,YAAY,OAAO,UAAU,KAAK,IAAI,QAAQ,GAIhE,OAAO,GAAG,WAAW,YAAY,KAAK;EAExC,OAAO;;CAKT,4BAA4B;CAC7B;AAED,MAAM,uBAAuB,sBAA4C;CACvE,cAAA;CACA,YAAY,CACV;EACE,SAAS;EACT,UAAUA;EACV,KAAKC;EACN,CACF;CACD,SAAA;CACD,CAAC;AAEF,MAAM,6BAAwE;CAC5E,GAAG;CACH,IAAI;CACJ,eAAe;CACf,OAAO;EACL,GAAG,gBAAgB;EACnB,YAAY;GACV,GAAG,gBAAgB,MAAM;GACzB,mBAAmB,GAChB,4BAA4B,2BAC9B;GACF;EACF;CACD,uBAAuB,wBAAwB;CAC/C,eAAe;EACb,UAAU;EACV,UAAU;EACX;CACF"}