@rehearsal-db/core 0.1.0-beta.15 → 0.1.0-beta.16

package/CHANGELOG.md

@@ -5,6 +5,36 @@ a Changelog, and versions will follow Semantic Versioning after the package exis
 
 ## Unreleased
 
+### Changed
+
+- The CLI now routes guided and scripted requests through focused typed command
+  handlers and one result/output contract. The executable retains only process
+  lifecycle, project locking, guided-loop coordination, and top-level error handling;
+  command-session caches no longer live in public parsed flags.
+- Configuration now passes through separate discovery, raw-schema validation,
+  normalization, project-root path resolution, project detection, and starter-rendering
+  modules behind the existing import path. Public declarations come from the same
+  TypeScript source, including the new `NormalizedRehearsalConfig` type.
+- Installed-consumer verification now shares one scenario catalog, artifact installer,
+  isolated workspace boundary, process boundary, and persistent application-session
+  helper. The complete release gate runs every scenario against one immutable tarball
+  and records its exact version, SHA-256, tool environment, commands, timings, and
+  results.
+- Identity policy validation, deterministic claim planning, SQL generation, local Auth
+  lookup, pure verification, and transactional execution now live in separate typed
+  stages behind the unchanged public claim API. Generated reference SQL is independently
+  testable, while only the executor can mutate the local database or Storage runtime.
+- PostgreSQL and Supabase now share one typed runtime lifecycle engine for command
+  dispatch, active-baseline loading, migration confirmation and receipts, runtime
+  markers, and rollback. Candidate receipts are bound to their exact database target,
+  while each driver retains its own ownership proof and database-specific behavior.
+- Privacy policy types, recipe normalization, dependency validation, deterministic
+  transforms, structured JSON, rule dispatch, row execution, and key handling now live
+  in focused typed stages behind the unchanged public privacy import. An explicit closed
+  registry covers every supported action and derivation without widening policy v2.
+
+## [0.1.0-beta.15] - 2026-10-08
+
 ### Added
 
 - A strict, no-emit TypeScript gate now checks the first shared runtime utilities and
@@ -482,7 +512,10 @@ a Changelog, and versions will follow Semantic Versioning after the package exis
   publication uses short-lived trusted OIDC, and every release tag must already exist on
   protected `main`.
 
-[Unreleased]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.12...HEAD
+[Unreleased]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.15...HEAD
+[0.1.0-beta.15]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.14...v0.1.0-beta.15
+[0.1.0-beta.14]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.13...v0.1.0-beta.14
+[0.1.0-beta.13]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.12...v0.1.0-beta.13
 [0.1.0-beta.12]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.11...v0.1.0-beta.12
 [0.1.0-beta.11]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.10...v0.1.0-beta.11
 [0.1.0-beta.10]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.9...v0.1.0-beta.10

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@rehearsal-db/core",
-    "version": "0.1.0-beta.15",
+    "version": "0.1.0-beta.16",
     "private": false,
     "description": "Safely rehearse PostgreSQL and Supabase migrations against sanitized, production-shaped data.",
     "repository": {
@@ -60,16 +60,17 @@
         "test:unit": "npm run build && vitest run tests/unit",
         "test:integration": "npm run build && vitest run tests/integration tests/contracts",
         "test:docs": "npm run build && vitest run tests/contracts/documentationCommands.test.mjs",
-        "test:fixture": "npm run build && node scripts/verification/fixtures/supabase.mjs",
-        "test:fixture:postgresql": "npm run build && node scripts/verification/fixtures/postgresql.mjs",
-        "test:fixture:dependent": "npm run build && node scripts/verification/fixtures/dependent.mjs",
-        "test:fixture:onboarding": "npm run build && node scripts/verification/fixtures/onboarding.mjs",
-        "test:fixture:typescript": "npm run build && node scripts/verification/fixtures/typescript.mjs",
-        "test:fixture:standalone": "npm run build && node scripts/verification/fixtures/standalone.mjs",
-        "test:fixture:privacy": "npm run build && node scripts/verification/fixtures/privacy.mjs",
+        "test:fixture": "npm run build && node scripts/verification/run_scenario.mjs supabase",
+        "test:fixture:postgresql": "npm run build && node scripts/verification/run_scenario.mjs postgresql",
+        "test:fixture:dependent": "npm run build && node scripts/verification/run_scenario.mjs dependent-target",
+        "test:fixture:onboarding": "npm run build && node scripts/verification/run_scenario.mjs onboarding",
+        "test:fixture:typescript": "npm run build && node scripts/verification/run_scenario.mjs typescript",
+        "test:fixture:standalone": "npm run build && node scripts/verification/run_scenario.mjs standalone",
+        "test:fixture:privacy": "npm run build && node scripts/verification/run_scenario.mjs privacy",
+        "release:verify": "node scripts/verification/release_gate.mjs",
         "check": "npm run check:syntax && npm run typecheck && npm run test && npm run docs:build && npm run format:check && npm run package:audit",
         "check:syntax": "find scripts tests -type f -name '*.mjs' -exec node --check {} +",
-        "typecheck": "tsc --project tsconfig.json",
+        "typecheck": "npm run build && tsc --project tsconfig.json",
         "format": "prettier --write .",
         "format:check": "prettier --check .",
         "package:audit": "node scripts/verification/audit_package.mjs"

package/dist/src/baseline/privacy_contract.d.mts

@@ -0,0 +1,147 @@
+/** Typed, normalized contract shared by privacy validation and execution stages. */
+export type PrivacyAction = "KEEP" | "PSEUDONYMIZE" | "REPLACE" | "EXCLUDE" | "DERIVE";
+export type PrivacyObject = Record<string, unknown>;
+export interface PseudonymRecipe {
+    format: "uuid" | "email" | "text" | "integer" | "hex" | "gtin" | "url";
+    namespace: string;
+    maxLength?: number;
+    length?: number;
+    allowedLengths?: readonly number[];
+    origin?: string;
+}
+export interface ConstantRecipe {
+    kind: "constant";
+    value: unknown;
+}
+export interface DateShiftRecipe {
+    kind: "date-shift";
+    days: number;
+    representation: "iso-string" | "epoch-milliseconds";
+    group?: string;
+}
+export interface EnumRecipe {
+    kind: "enum";
+    allowNull: boolean;
+    values: readonly (string | number | boolean)[];
+}
+export interface ValidatedStringRecipe {
+    kind: "validated-string";
+    format: "portable-code";
+    maximumBytes: number;
+    allowNull: boolean;
+}
+export interface DigestRecipe {
+    kind: "digest";
+    format: "hex";
+    length: number;
+    namespace: string;
+    inputs: readonly string[];
+}
+export interface BindingSubstituteRecipe {
+    kind: "binding-substitute";
+    binding: string;
+    format: "uuid";
+    namespace: string;
+    maximumBytes: number;
+}
+export interface PathMapRecipe {
+    kind: "path-map";
+    mapping: string;
+}
+export interface ApprovedOwnerRecipe {
+    kind: "approved-owner";
+    approved: NormalizedDeclaration;
+    otherwise: NormalizedDeclaration;
+}
+export interface JsonArrayRecipe {
+    kind: "json-array";
+    allowNull: boolean;
+    maximumBytes: number;
+    maximumDepth: number;
+    maximumItems: number;
+    items: NormalizedDeclaration;
+}
+export interface JsonObjectRecipe {
+    kind: "json-object";
+    allowNull: boolean;
+    maximumBytes: number;
+    maximumDepth: number;
+    fields: Readonly<Record<string, NormalizedDeclaration>>;
+}
+export interface JsonUnionRecipe {
+    kind: "json-union";
+    allowNull: boolean;
+    maximumBytes: number;
+    maximumDepth: number;
+    maximumItems: number;
+    variants: Readonly<Record<string, NormalizedDeclaration>>;
+}
+export interface JsonDictionaryRecipe {
+    kind: "json-dictionary";
+    allowNull: boolean;
+    maximumBytes: number;
+    maximumDepth: number;
+    maximumItems: number;
+    keys: Readonly<Record<string, unknown>>;
+    values: NormalizedDeclaration;
+}
+export type DerivationRecipe = DateShiftRecipe | EnumRecipe | ValidatedStringRecipe | DigestRecipe | BindingSubstituteRecipe | PathMapRecipe | ApprovedOwnerRecipe | JsonArrayRecipe | JsonObjectRecipe | JsonUnionRecipe | JsonDictionaryRecipe;
+export type NormalizedRecipe = PseudonymRecipe | ConstantRecipe | DerivationRecipe | null;
+export interface NormalizedDeclaration {
+    action: PrivacyAction;
+    recipe: NormalizedRecipe;
+    required?: boolean;
+}
+export interface PrivacyBinding {
+    environmentVariable: string;
+    approvedValueSha256: string;
+}
+export interface PrivacyPathMapping extends PseudonymRecipe {
+    binding: string;
+    format: "uuid" | "text";
+    maximumBytes: number;
+    maximumSegments: number;
+}
+export interface PrivacyForeignKey {
+    readonly schema: string;
+    readonly table: string;
+    readonly column: string;
+}
+export interface PrivacyColumn extends NormalizedDeclaration {
+    name: string;
+    generated: "ALWAYS" | "NEVER";
+    identity: "YES" | "NO";
+    foreignKey: PrivacyForeignKey | null;
+}
+export interface PrivacyTable {
+    schema: string;
+    name: string;
+    sourceRows: "STREAM AND SANITIZE" | "EXCLUDE";
+    ownerBinding: Readonly<{
+        binding: string;
+        columns: readonly string[];
+        match: "any";
+        nullBehavior?: "otherwise";
+    }> | null;
+    columns: readonly PrivacyColumn[];
+}
+export interface ExecutablePrivacyPolicy {
+    readonly policyVersion: 2;
+    readonly migrationCutoff: string;
+    readonly bindings: Readonly<Record<string, PrivacyBinding>>;
+    readonly pathMappings: Readonly<Record<string, PrivacyPathMapping>>;
+    readonly tables: readonly PrivacyTable[];
+}
+export interface PrivacySourceRecord {
+    schema?: string;
+    table: string;
+    row: Record<string, unknown>;
+}
+export interface PrivacyEngine {
+    readonly keyFingerprint: string;
+    remapPath(input: {
+        mapping: string;
+        value: string;
+    }): string;
+    sanitize(record: unknown): PrivacySourceRecord | null;
+}

package/dist/src/baseline/privacy_contract.mjs

@@ -0,0 +1,2 @@
+/** Typed, normalized contract shared by privacy validation and execution stages. */
+export {};

package/dist/src/baseline/privacy_dependency_graph.d.mts

@@ -0,0 +1,7 @@
+/** Validate cross-rule bindings, dependencies, and shared deterministic groups. */
+import type { PrivacyBinding, PrivacyPathMapping, PrivacyTable } from "./privacy_contract.mjs";
+export declare const validatePrivacyDependencyGraph: ({ tables, bindings, pathMappings, }: {
+    tables: readonly PrivacyTable[];
+    bindings: Readonly<Record<string, PrivacyBinding>>;
+    pathMappings: Readonly<Record<string, PrivacyPathMapping>>;
+}) => void;

package/dist/src/baseline/privacy_dependency_graph.mjs

@@ -0,0 +1,110 @@
+/** Validate cross-rule bindings, dependencies, and shared deterministic groups. */
+import { structuredJsonDeclarations } from "./privacy_structured_json.mjs";
+const usesApprovedOwner = (declaration) => (declaration.recipe !== null &&
+    "kind" in declaration.recipe &&
+    declaration.recipe.kind === "approved-owner") ||
+    structuredJsonDeclarations(declaration.recipe).some(usesApprovedOwner);
+const visitRecipes = (declaration, visit) => {
+    visit(declaration.recipe);
+    if (declaration.recipe !== null &&
+        "kind" in declaration.recipe &&
+        declaration.recipe.kind === "approved-owner") {
+        visitRecipes(declaration.recipe.approved, visit);
+        visitRecipes(declaration.recipe.otherwise, visit);
+    }
+    else {
+        structuredJsonDeclarations(declaration.recipe).forEach((nested) => visitRecipes(nested, visit));
+    }
+};
+const digestInputs = (declaration) => {
+    if (declaration.recipe !== null &&
+        "kind" in declaration.recipe &&
+        declaration.recipe.kind === "digest") {
+        return [...declaration.recipe.inputs];
+    }
+    if (declaration.recipe !== null &&
+        "kind" in declaration.recipe &&
+        declaration.recipe.kind === "approved-owner") {
+        return [
+            ...digestInputs(declaration.recipe.approved),
+            ...digestInputs(declaration.recipe.otherwise),
+        ];
+    }
+    return structuredJsonDeclarations(declaration.recipe).flatMap(digestInputs);
+};
+const validateTableDependencies = ({ table, index, bindings, pathMappings, }) => {
+    const label = `policy.tables[${index}]`;
+    if (table.columns.some(usesApprovedOwner) && !table.ownerBinding) {
+        throw new Error(`${label} uses approved-owner without ownerBinding.`);
+    }
+    for (const column of table.columns) {
+        visitRecipes(column, (recipe) => {
+            if (recipe &&
+                "kind" in recipe &&
+                recipe.kind === "path-map" &&
+                !Object.hasOwn(pathMappings, recipe.mapping)) {
+                throw new Error(`${label} references unknown path mapping ${recipe.mapping}.`);
+            }
+            if (recipe !== null &&
+                "kind" in recipe &&
+                recipe.kind === "binding-substitute" &&
+                !Object.hasOwn(bindings, recipe.binding)) {
+                throw new Error(`${label} references unknown privacy binding ${recipe.binding}.`);
+            }
+        });
+    }
+    const dependencies = new Map(table.columns.map((column) => [column.name, []]));
+    for (const column of table.columns) {
+        const inputs = [...new Set(digestInputs(column))];
+        for (const input of inputs) {
+            const inputColumn = table.columns.find((entry) => entry.name === input);
+            if (!inputColumn) {
+                throw new Error(`${label}.${column.name} digest references unknown column ${input}.`);
+            }
+            if (inputColumn.action === "EXCLUDE") {
+                throw new Error(`${label}.${column.name} digest input ${input} is excluded instead of sanitized.`);
+            }
+        }
+        dependencies.set(column.name, inputs);
+    }
+    const resolved = new Set();
+    const resolving = new Set();
+    const visitDependency = (columnName) => {
+        if (resolved.has(columnName))
+            return;
+        if (resolving.has(columnName)) {
+            throw new Error(`${label} contains a cyclic digest dependency.`);
+        }
+        resolving.add(columnName);
+        for (const input of dependencies.get(columnName) ?? []) {
+            visitDependency(input);
+        }
+        resolving.delete(columnName);
+        resolved.add(columnName);
+    };
+    table.columns.forEach((column) => visitDependency(column.name));
+};
+export const validatePrivacyDependencyGraph = ({ tables, bindings, pathMappings, }) => {
+    tables.forEach((table, index) => validateTableDependencies({ table, index, bindings, pathMappings }));
+    const dateShiftGroups = new Map();
+    const validateDateShiftGroup = (declaration) => {
+        const recipe = declaration.recipe;
+        if (!recipe || !("kind" in recipe))
+            return;
+        if (recipe.kind === "date-shift" && recipe.group) {
+            const existing = dateShiftGroups.get(recipe.group);
+            if (existing !== undefined && existing !== recipe.days) {
+                throw new Error(`Privacy date-shift group ${recipe.group} must use one days value.`);
+            }
+            dateShiftGroups.set(recipe.group, recipe.days);
+        }
+        if (recipe.kind === "approved-owner") {
+            validateDateShiftGroup(recipe.approved);
+            validateDateShiftGroup(recipe.otherwise);
+        }
+        else {
+            structuredJsonDeclarations(recipe).forEach(validateDateShiftGroup);
+        }
+    };
+    tables.forEach((table) => table.columns.forEach(validateDateShiftGroup));
+};

package/dist/src/baseline/privacy_engine.d.mts

@@ -1,162 +1,5 @@
-/**
- * Execute reviewed privacy policy version 2 without project-owned callbacks.
- * The engine is intentionally small and fail-closed: unsupported shapes and
- * recipes must be reviewed and added here instead of evaluated as code.
- */
-type PrivacyAction = "KEEP" | "PSEUDONYMIZE" | "REPLACE" | "EXCLUDE" | "DERIVE";
-interface PseudonymRecipe {
-    format: "uuid" | "email" | "text" | "integer" | "hex" | "gtin" | "url";
-    namespace: string;
-    maxLength?: number;
-    length?: number;
-    allowedLengths?: readonly number[];
-    origin?: string;
-}
-interface ConstantRecipe {
-    kind: "constant";
-    value: unknown;
-}
-interface DateShiftRecipe {
-    kind: "date-shift";
-    days: number;
-    representation: "iso-string" | "epoch-milliseconds";
-    group?: string;
-}
-interface EnumRecipe {
-    kind: "enum";
-    allowNull: boolean;
-    values: readonly (string | number | boolean)[];
-}
-interface ValidatedStringRecipe {
-    kind: "validated-string";
-    format: "portable-code";
-    maximumBytes: number;
-    allowNull: boolean;
-}
-interface DigestRecipe {
-    kind: "digest";
-    format: "hex";
-    length: number;
-    namespace: string;
-    inputs: readonly string[];
-}
-interface BindingSubstituteRecipe {
-    kind: "binding-substitute";
-    binding: string;
-    format: "uuid";
-    namespace: string;
-    maximumBytes: number;
-}
-interface PathMapRecipe {
-    kind: "path-map";
-    mapping: string;
-}
-interface ApprovedOwnerRecipe {
-    kind: "approved-owner";
-    approved: NormalizedDeclaration;
-    otherwise: NormalizedDeclaration;
-}
-interface JsonArrayRecipe {
-    kind: "json-array";
-    allowNull: boolean;
-    maximumBytes: number;
-    maximumDepth: number;
-    maximumItems: number;
-    items: NormalizedDeclaration;
-}
-interface JsonObjectRecipe {
-    kind: "json-object";
-    allowNull: boolean;
-    maximumBytes: number;
-    maximumDepth: number;
-    fields: Readonly<Record<string, NormalizedDeclaration>>;
-}
-interface JsonUnionRecipe {
-    kind: "json-union";
-    allowNull: boolean;
-    maximumBytes: number;
-    maximumDepth: number;
-    maximumItems: number;
-    variants: Readonly<Record<string, NormalizedDeclaration>>;
-}
-interface JsonDictionaryRecipe {
-    kind: "json-dictionary";
-    allowNull: boolean;
-    maximumBytes: number;
-    maximumDepth: number;
-    maximumItems: number;
-    keys: Readonly<Record<string, unknown>>;
-    values: NormalizedDeclaration;
-}
-type DerivationRecipe = DateShiftRecipe | EnumRecipe | ValidatedStringRecipe | DigestRecipe | BindingSubstituteRecipe | PathMapRecipe | ApprovedOwnerRecipe | JsonArrayRecipe | JsonObjectRecipe | JsonUnionRecipe | JsonDictionaryRecipe;
-type NormalizedRecipe = PseudonymRecipe | ConstantRecipe | DerivationRecipe | null;
-interface NormalizedDeclaration {
-    action: PrivacyAction;
-    recipe: NormalizedRecipe;
-    required?: boolean;
-}
-interface PrivacyBinding {
-    environmentVariable: string;
-    approvedValueSha256: string;
-}
-interface PrivacyPathMapping extends PseudonymRecipe {
-    binding: string;
-    format: "uuid" | "text";
-    maximumBytes: number;
-    maximumSegments: number;
-}
-export interface PrivacyForeignKey {
-    readonly schema: string;
-    readonly table: string;
-    readonly column: string;
-}
-export interface PrivacyColumn extends NormalizedDeclaration {
-    name: string;
-    generated: "ALWAYS" | "NEVER";
-    identity: "YES" | "NO";
-    foreignKey: PrivacyForeignKey | null;
-}
-export interface PrivacyTable {
-    schema: string;
-    name: string;
-    sourceRows: "STREAM AND SANITIZE" | "EXCLUDE";
-    ownerBinding: Readonly<{
-        binding: string;
-        columns: readonly string[];
-        match: "any";
-        nullBehavior?: "otherwise";
-    }> | null;
-    columns: readonly PrivacyColumn[];
-}
-export interface ExecutablePrivacyPolicy {
-    readonly policyVersion: 2;
-    readonly migrationCutoff: string;
-    readonly bindings: Readonly<Record<string, PrivacyBinding>>;
-    readonly pathMappings: Readonly<Record<string, PrivacyPathMapping>>;
-    readonly tables: readonly PrivacyTable[];
-}
-export declare const validateExecutablePrivacyPolicy: (policy: unknown) => ExecutablePrivacyPolicy;
-export interface PrivacySourceRecord {
-    schema?: string;
-    table: string;
-    row: Record<string, unknown>;
-}
-export interface PrivacyEngine {
-    readonly keyFingerprint: string;
-    remapPath(input: {
-        mapping: string;
-        value: string;
-    }): string;
-    sanitize(record: unknown): PrivacySourceRecord | null;
-}
-export declare const createPrivacyEngine: ({ policy, key, environment, }: {
-    policy: unknown;
-    key: Uint8Array | string;
-    environment?: NodeJS.ProcessEnv;
-}) => Readonly<PrivacyEngine>;
-export declare const createPrivacyKey: (path: string) => Promise<{
-    fingerprint: string;
-}>;
-export declare const readPrivacyKey: (path: string) => Promise<Buffer>;
-export declare const assertPrivacyKeyFingerprint: (key: Uint8Array, expected: unknown) => void;
-export {};
+/** Stable public facade for the versioned, fail-closed privacy pipeline. */
+export { validateExecutablePrivacyPolicy } from "./privacy_policy.mjs";
+export { createPrivacyEngine } from "./privacy_pipeline.mjs";
+export { assertPrivacyKeyFingerprint, createPrivacyKey, readPrivacyKey, } from "./privacy_key.mjs";
+export type { ExecutablePrivacyPolicy, PrivacyColumn, PrivacyEngine, PrivacyForeignKey, PrivacySourceRecord, PrivacyTable, } from "./privacy_policy.mjs";