(TML-2397) M3 — Contract spaces: cipherstash extension as a contract space

packages/1-framework/3-tooling/cli/src/utils/contract-space-extension-migrations-pass.ts

@@ -1,17 +1,15 @@
-import { stat } from 'node:fs/promises';
-import { materialiseMigrationPackage } from '@prisma-next/migration-tools/io';
+import { materialiseExtensionMigrationPackageIfMissing } from '@prisma-next/migration-tools/io';
 import type { MigrationMetadata } from '@prisma-next/migration-tools/metadata';
 import type { MigrationOps } from '@prisma-next/migration-tools/package';
 import {
   planAllSpaces,
   type SpacePlanOutput,
   spaceMigrationDirectory,
 } from '@prisma-next/migration-tools/spaces';
-import { join } from 'pathe';
 
 /**
  * In-memory authored migration package shipped by an extension descriptor.
- * Mirrors `MigrationPackageContents` from `@prisma-next/migration-tools/io`
+ * Mirrors `MigrationPackage` from `@prisma-next/migration-tools/io`
  * (the on-disk shape minus `dirPath`); redeclared structurally here so
  * the CLI helper does not couple to the SQL family's `ExtensionMigrationPackage`
  * type — any family that ships pre-built migration packages can pass them
@@ -109,26 +107,14 @@ export async function runContractSpaceExtensionMigrationsPass(
   for (const space of planned) {
     const spaceDir = spaceMigrationDirectory(inputs.migrationsDir, space.spaceId);
     for (const pkg of space.migrationPackages) {
-      const pkgPath = join(spaceDir, pkg.dirName);
-      const exists = await pathExists(pkgPath);
-      if (exists) {
+      const { written } = await materialiseExtensionMigrationPackageIfMissing(spaceDir, pkg);
+      if (written) {
+        emitted.push({ spaceId: space.spaceId, dirName: pkg.dirName });
+      } else {
         skipped.push({ spaceId: space.spaceId, dirName: pkg.dirName });
-        continue;
       }
-      await materialiseMigrationPackage(spaceDir, pkg);
-      emitted.push({ spaceId: space.spaceId, dirName: pkg.dirName });
     }
   }
 
   return { emitted, skipped };
 }
-
-async function pathExists(p: string): Promise<boolean> {
-  try {
-    await stat(p);
-    return true;
-  } catch (error) {
-    if ((error as { code?: string }).code === 'ENOENT') return false;
-    throw error;
-  }
-}

packages/1-framework/3-tooling/migration/src/exports/io.ts

@@ -1,6 +1,7 @@
 export {
   copyFilesWithRename,
   formatMigrationDirName,
+  materialiseExtensionMigrationPackageIfMissing,
   materialiseMigrationPackage,
   readMigrationPackage,
   readMigrationsDir,

packages/1-framework/3-tooling/migration/src/invariants.ts

@@ -16,8 +16,19 @@ export function validateInvariantId(invariantId: string): boolean {
 /**
  * Walk a migration's operations and produce its `providedInvariants`
  * aggregate: the sorted, deduplicated list of `invariantId`s declared
- * by data-transform ops. Ops without `operationClass === 'data'` are
- * skipped; data ops without an `invariantId` are skipped.
+ * by ops in the migration. Ops without an `invariantId` are skipped.
+ *
+ * Both `data`-class ops (data-transforms, e.g. backfills) and
+ * `additive`-class opaque DDL (e.g. cipherstash's vendored EQL bundle
+ * via `installEqlBundleOp`) may declare invariantIds: the
+ * `operationClass` axis classifies *policy gating* (which kinds of ops
+ * a `db init` / `db update` policy permits), while `invariantId`
+ * classifies *marker bookkeeping* (which named bundles of work a
+ * future regeneration knows to skip). The two concerns are
+ * intentionally orthogonal — an extension can ship additive
+ * non-IR-derivable DDL (the only way the planner can know the bundle
+ * is already applied is via the invariantId on the marker) without
+ * needing to mis-classify it as `data`-class.
  *
  * Throws `MIGRATION.INVALID_INVARIANT_ID` on a malformed id and
  * `MIGRATION.DUPLICATE_INVARIANT_IN_EDGE` on duplicates.
@@ -39,7 +50,7 @@ export function deriveProvidedInvariants(ops: MigrationOps): readonly string[] {
 }
 
 function readInvariantId(op: MigrationPlanOperation): string | undefined {
-  if (op.operationClass !== 'data') return undefined;
+  if (!Object.hasOwn(op, 'invariantId')) return undefined;
   const candidate = (op as { invariantId?: unknown }).invariantId;
   return typeof candidate === 'string' ? candidate : undefined;
 }

packages/1-framework/3-tooling/migration/src/io.ts

@@ -124,6 +124,48 @@ export async function materialiseMigrationPackage(
   });
 }
 
+/**
+ * Idempotent variant of {@link materialiseMigrationPackage}: writes the
+ * package only if `<targetDir>/<pkg.dirName>/` does not already exist on
+ * disk as a directory; returns `{ written: false }` when the package
+ * directory is present (no rewrite, no comparison — by-existence skip).
+ *
+ * Concretely:
+ *   - existing directory → skip silently, return `{ written: false }`.
+ *   - missing path → write three files via {@link materialiseMigrationPackage},
+ *     return `{ written: true }`.
+ *   - path exists but is not a directory (file/symlink) → treated as
+ *     missing; {@link materialiseMigrationPackage} will attempt creation
+ *     and fail with an appropriate OS error.
+ *   - any other I/O error from `stat` → propagated unchanged.
+ *
+ * Used by the CLI's `runContractSpaceExtensionMigrationsPass` to
+ * materialise extension migration packages into a project's
+ * `migrations/<spaceId>/` directory, and by extension-package tests
+ * that mirror the same idempotent-rematerialise property locally
+ * without taking a CLI dependency.
+ */
+export async function materialiseExtensionMigrationPackageIfMissing(
+  targetDir: string,
+  pkg: MigrationPackage,
+): Promise<{ readonly written: boolean }> {
+  const pkgDir = join(targetDir, pkg.dirName);
+  if (await directoryExists(pkgDir)) {
+    return { written: false };
+  }
+  await materialiseMigrationPackage(targetDir, pkg);
+  return { written: true };
+}
+
+async function directoryExists(p: string): Promise<boolean> {
+  try {
+    return (await stat(p)).isDirectory();
+  } catch (error) {
+    if (hasErrnoCode(error, 'ENOENT')) return false;
+    throw error;
+  }
+}
+
 /**
  * Copy a list of files into `destDir`, optionally renaming each one.
  *

packages/1-framework/3-tooling/migration/test/invariants.test.ts

@@ -58,18 +58,22 @@ describe('deriveProvidedInvariants', () => {
     expect(deriveProvidedInvariants([nonDataOp('add-table'), dataOp('cleanup')])).toEqual([]);
   });
 
-  it('skips non-data ops', () => {
+  it('includes invariantIds from additive ops alongside data ops', () => {
+    // Both data-class and additive-class ops may declare invariantIds for
+    // marker bookkeeping. operationClass governs policy gating; invariantId
+    // governs replay tracking. Cipherstash's `installEqlBundle` and
+    // structural `create-*` ops are the canonical additive-with-invariantId
+    // case (sub-spec § 3 / cipherstash-migration.spec.md).
     expect(
       deriveProvidedInvariants([
         nonDataOp('add-table'),
-        // additive ops with stray invariantId-like fields are ignored
-        { ...nonDataOp('phantom'), invariantId: 'should-be-ignored' } as MigrationPlanOperation,
+        { ...nonDataOp('install-bundle'), invariantId: 'ext:bundle-v1' } as MigrationPlanOperation,
         dataOp('phone-backfill', 'phone-backfill'),
       ]),
-    ).toEqual(['phone-backfill']);
+    ).toEqual(['ext:bundle-v1', 'phone-backfill']);
   });
 
-  it('returns sorted, deduplicated invariantIds across data ops', () => {
+  it('returns sorted, deduplicated invariantIds across all ops', () => {
     expect(
       deriveProvidedInvariants([dataOp('z', 'zebra'), dataOp('a', 'apple'), dataOp('m', 'mango')]),
     ).toEqual(['apple', 'mango', 'zebra']);

packages/1-framework/3-tooling/migration/test/materialise-extension-migration-package-if-missing.test.ts

@@ -0,0 +1,80 @@
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'pathe';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { materialiseExtensionMigrationPackageIfMissing } from '../src/io';
+import { createTestMetadata, createTestOps } from './fixtures';
+
+describe('materialiseExtensionMigrationPackageIfMissing', () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'materialise-if-missing-'));
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('writes the package and returns { written: true } on first run', async () => {
+    const ops = createTestOps();
+    const metadata = createTestMetadata({}, ops);
+    const pkg = { dirName: 'baseline', metadata, ops };
+
+    const result = await materialiseExtensionMigrationPackageIfMissing(tmpDir, pkg);
+
+    expect(result.written).toBe(true);
+    const manifest = await readFile(join(tmpDir, pkg.dirName, 'migration.json'), 'utf-8');
+    expect(manifest).toContain(metadata.migrationHash);
+  });
+
+  it('returns { written: false } when <targetDir>/<pkg.dirName>/ already exists', async () => {
+    const ops = createTestOps();
+    const metadata = createTestMetadata({}, ops);
+    const pkg = { dirName: 'baseline', metadata, ops };
+
+    await materialiseExtensionMigrationPackageIfMissing(tmpDir, pkg);
+    const second = await materialiseExtensionMigrationPackageIfMissing(tmpDir, pkg);
+
+    expect(second.written).toBe(false);
+  });
+
+  it('leaves on-disk content byte-identical when the dir already exists (AC-7 / AM12)', async () => {
+    const ops = createTestOps();
+    const metadata = createTestMetadata({}, ops);
+    const pkg = { dirName: 'baseline', metadata, ops };
+
+    await materialiseExtensionMigrationPackageIfMissing(tmpDir, pkg);
+
+    const before = await Promise.all(
+      ['migration.json', 'ops.json', 'contract.json'].map((name) =>
+        readFile(join(tmpDir, pkg.dirName, name), 'utf-8'),
+      ),
+    );
+
+    await materialiseExtensionMigrationPackageIfMissing(tmpDir, pkg);
+
+    const after = await Promise.all(
+      ['migration.json', 'ops.json', 'contract.json'].map((name) =>
+        readFile(join(tmpDir, pkg.dirName, name), 'utf-8'),
+      ),
+    );
+
+    expect(after).toEqual(before);
+  });
+
+  it('creates the parent target directory if it does not yet exist', async () => {
+    const nested = join(tmpDir, 'cipherstash');
+    const pkg = {
+      dirName: 'baseline',
+      metadata: createTestMetadata({}, []),
+      ops: [],
+    };
+
+    const result = await materialiseExtensionMigrationPackageIfMissing(nested, pkg);
+
+    expect(result.written).toBe(true);
+    const manifest = await readFile(join(nested, pkg.dirName, 'migration.json'), 'utf-8');
+    expect(manifest).toBeDefined();
+  });
+});

packages/3-extensions/cipherstash/README.md

@@ -0,0 +1,61 @@
+# @prisma-next/extension-cipherstash
+
+[CipherStash](https://cipherstash.com) extension for Prisma Next: searchable
+application-layer encryption for Postgres via the EQL bundle.
+
+## Status
+
+Work in progress. This package documents the current supported behavior only.
+
+This package authors CipherStash's database scaffolding (the
+`eql_v2_configuration` table, the `eql_v2_encrypted` / `ore_*` composite
+types, the `eql_v2.bloom_filter` / `hmac_256` / `blake3` domains, and the
+EQL bundle SQL) as a **contract space** so the Prisma Next framework can
+plan, apply, and verify it the same way it manages an application's own
+schema.
+
+The `searchable: true` codec lifecycle hook (`add_search_config` /
+`remove_search_config` ops) is wired up — see `src/exports/control.ts`. The
+codec runtime (encoding/decoding `Encrypted<string>` payloads at query time)
+is not yet implemented.
+
+## What this package contributes
+
+- `contractSpace.contractJson` — the typed objects EQL exposes that user
+  columns can name as `nativeType`. Per the IR vocabulary boundary,
+  this carries tables / enums / composite types / domains only; functions /
+  operators / casts / op classes live below the boundary as opaque DDL inside
+  the `installEqlBundle` migration op.
+- `contractSpace.migrations` — the baseline migration that installs the
+  vendored EQL bundle SQL (one `cipherstash:install-eql-bundle-v1` op
+  carrying the bundle byte-for-byte) plus the structural ops that create
+  the typed objects above. Each op carries a `cipherstash:*` invariantId.
+- `contractSpace.headRef` — `(hash, invariants)` describing the current
+  target state of the contract space. The framework consumes this at
+  `migrate` time to materialise pinned per-space artefacts under
+  `migrations/cipherstash/` in the user's repo.
+
+## Usage (preview)
+
+```ts
+import { defineConfig } from 'prisma-next';
+import cipherstash from '@prisma-next/extension-cipherstash/control';
+
+export default defineConfig({
+  extensionPacks: [cipherstash],
+});
+```
+
+After `prisma-next migrate`, the user's repo gains
+`migrations/cipherstash/contract.json`,
+`migrations/cipherstash/contract.d.ts`,
+`migrations/cipherstash/refs/head.json`, and
+`migrations/cipherstash/<name>/` migration directories. `db apply` then
+runs CipherStash's migrations against the live database in the same
+transaction as any application-space migration emitted in the same
+`migrate` invocation.
+
+## See also
+
+- Reference fixture: [`packages/3-extensions/test-contract-space`](../test-contract-space)
+- Reference shape: [`packages/3-extensions/pgvector`](../pgvector)

packages/3-extensions/cipherstash/biome.jsonc

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.3.11/schema.json",
+  "extends": "//"
+}

packages/3-extensions/cipherstash/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@prisma-next/extension-cipherstash",
+  "version": "0.0.1",
+  "license": "Apache-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "description": "CipherStash EQL extension for Prisma Next: contract-space authoring of the encrypted-column scaffolding (eql_v2_configuration table, eql_v2_encrypted/ore_* composite types, eql_v2 domains) plus a baseline migration that installs the vendored EQL bundle SQL byte-for-byte.",
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --project tsconfig.json --noEmit",
+    "lint": "biome check . --error-on-warnings",
+    "lint:fix": "biome check --write .",
+    "lint:fix:unsafe": "biome check --write --unsafe .",
+    "clean": "rm -rf dist dist-tsc dist-tsc-prod coverage .tmp-output"
+  },
+  "dependencies": {
+    "@prisma-next/contract": "workspace:*",
+    "@prisma-next/family-sql": "workspace:*",
+    "@prisma-next/framework-components": "workspace:*",
+    "@prisma-next/migration-tools": "workspace:*",
+    "@prisma-next/sql-contract": "workspace:*"
+  },
+  "devDependencies": {
+    "@prisma-next/adapter-postgres": "workspace:*",
+    "@prisma-next/cli": "workspace:*",
+    "@prisma-next/driver-postgres": "workspace:*",
+    "@prisma-next/sql-schema-ir": "workspace:*",
+    "@prisma-next/target-postgres": "workspace:*",
+    "@prisma-next/test-utils": "workspace:*",
+    "@prisma-next/tsconfig": "workspace:*",
+    "@prisma-next/tsdown": "workspace:*",
+    "tsdown": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    "./control": "./dist/control.mjs",
+    "./package.json": "./package.json"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/prisma/prisma-next.git",
+    "directory": "packages/3-extensions/cipherstash"
+  }
+}