@rehearsal-db/core 0.1.0-beta.1 → 0.1.0-beta.3

package/scripts/lib/rehearsal/baseline_preparation.mjs

@@ -0,0 +1,201 @@
+/**
+ * Purpose: Inspect explicit local synthetic records and migration evidence, then
+ * create a fail-closed sanitization-policy draft for human review.
+ */
+
+import { createReadStream } from "node:fs";
+import { access, mkdir, open, readFile } from "node:fs/promises";
+import { createInterface } from "node:readline";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { loadRehearsalConfig } from "./configuration.mjs";
+import { buildMigrationLedgerInventory } from "./migration_history.mjs";
+
+const identifierPattern = /^[a-z][a-z0-9_]{0,62}$/u;
+
+const resolveProjectInput = (projectRoot, value, label) => {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`${label} is required.`);
+  }
+  const path = resolve(projectRoot, value);
+  const owned = relative(projectRoot, path);
+  if (
+    owned === "" ||
+    owned === ".." ||
+    owned.startsWith(`..${sep}`) ||
+    isAbsolute(owned)
+  ) {
+    throw new Error(`${label} must be a file inside the project root.`);
+  }
+  return path;
+};
+
+const pathExists = (path) =>
+  access(path)
+    .then(() => true)
+    .catch((error) => {
+      if (error?.code === "ENOENT") return false;
+      throw error;
+    });
+
+const inspectSyntheticRecords = async (path) => {
+  const tables = new Map();
+  let rowCount = 0;
+  const lines = createInterface({
+    input: createReadStream(path, { encoding: "utf8" }),
+    crlfDelay: Infinity,
+  });
+  for await (const line of lines) {
+    if (!line.trim()) continue;
+    let record;
+    try {
+      record = JSON.parse(line);
+    } catch (error) {
+      throw new Error("Synthetic baseline input contains invalid NDJSON.", {
+        cause: error,
+      });
+    }
+    if (
+      !record ||
+      !identifierPattern.test(record.table ?? "") ||
+      !record.row ||
+      typeof record.row !== "object" ||
+      Array.isArray(record.row)
+    ) {
+      throw new Error("A synthetic baseline record has an invalid shape.");
+    }
+    const columns = Object.keys(record.row);
+    if (
+      columns.length === 0 ||
+      columns.some((column) => !identifierPattern.test(column))
+    ) {
+      throw new Error(
+        `Synthetic baseline table ${record.table} has invalid or empty columns.`,
+      );
+    }
+    const table = tables.get(record.table) ?? {
+      name: record.table,
+      rowCount: 0,
+      columns: new Set(),
+    };
+    table.rowCount += 1;
+    for (const column of columns) table.columns.add(column);
+    tables.set(record.table, table);
+    rowCount += 1;
+  }
+  if (rowCount === 0) {
+    throw new Error("Synthetic baseline input contains no records.");
+  }
+  return {
+    rowCount,
+    tables: [...tables.values()]
+      .sort((left, right) => left.name.localeCompare(right.name))
+      .map((table) => ({
+        name: table.name,
+        rowCount: table.rowCount,
+        columns: [...table.columns].sort(),
+      })),
+  };
+};
+
+const renderPolicyDraft = ({ migrationCutoff, tables }) =>
+  `${JSON.stringify(
+    {
+      policyVersion: 1,
+      draft: true,
+      migrationCutoff,
+      tables: tables.map((table) => ({
+        name: table.name,
+        group: "synthetic",
+        sourceRows: "STREAM AND SANITIZE",
+        columns: table.columns.map((name) => ({
+          name,
+          action: "REVIEW REQUIRED",
+          generated: "REVIEW REQUIRED",
+          identity: "REVIEW REQUIRED",
+          foreignKey: "REVIEW REQUIRED",
+        })),
+      })),
+    },
+    null,
+    2,
+  )}\n`;
+
+export const planBaselinePreparation = async ({
+  projectRoot = process.cwd(),
+  configPath,
+  recordsPath,
+  ledgerPath,
+}) => {
+  const loaded = await loadRehearsalConfig({ projectRoot, configPath });
+  const records = resolveProjectInput(
+    loaded.projectRoot,
+    recordsPath,
+    "Synthetic records path",
+  );
+  const ledger = resolveProjectInput(
+    loaded.projectRoot,
+    ledgerPath,
+    "Migration ledger path",
+  );
+  const [inspection, ledgerRows] = await Promise.all([
+    inspectSyntheticRecords(records),
+    readFile(ledger, "utf8").then(JSON.parse),
+  ]);
+  const migrationHistory = buildMigrationLedgerInventory(
+    ledgerRows,
+    "Synthetic migration ledger",
+  );
+  const destination = loaded.paths.sanitizationPolicy;
+  if (await pathExists(destination)) {
+    throw new Error(
+      `Rehearsal baseline preparation will not overwrite ${relative(loaded.projectRoot, destination)}.`,
+    );
+  }
+  const migrationCutoff = migrationHistory.at(-1).version;
+  return {
+    projectRoot: loaded.projectRoot,
+    destination,
+    destinationRelative: relative(loaded.projectRoot, destination),
+    recordsPath: relative(loaded.projectRoot, records),
+    ledgerPath: relative(loaded.projectRoot, ledger),
+    migrationCutoff,
+    migrationCount: migrationHistory.length,
+    rowCount: inspection.rowCount,
+    tables: inspection.tables,
+    content: renderPolicyDraft({
+      migrationCutoff,
+      tables: inspection.tables,
+    }),
+  };
+};
+
+export const applyBaselinePreparation = async (plan) => {
+  if (await pathExists(plan.destination)) {
+    throw new Error(
+      `Rehearsal baseline preparation will not overwrite ${plan.destinationRelative}.`,
+    );
+  }
+  await mkdir(dirname(plan.destination), { recursive: true, mode: 0o700 });
+  const handle = await open(plan.destination, "wx", 0o600);
+  try {
+    await handle.writeFile(plan.content);
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+};
+
+export const summarizeBaselinePreparation = (plan, { mode }) => ({
+  mode,
+  destination: plan.destinationRelative,
+  recordsPath: plan.recordsPath,
+  ledgerPath: plan.ledgerPath,
+  migrationCutoff: plan.migrationCutoff,
+  migrationCount: plan.migrationCount,
+  rowCount: plan.rowCount,
+  tables: plan.tables,
+  nextAction:
+    mode === "written"
+      ? `Review every REVIEW REQUIRED decision in ${plan.destinationRelative}, remove draft only after review, then create the baseline.`
+      : "Review this schema-only summary, then rerun with --write to create the draft.",
+});

package/scripts/lib/rehearsal/configuration.d.mts

@@ -51,7 +51,13 @@ export declare const loadRehearsalConfig: (options?: {
 export declare const inspectDetectedProject: (options?: {
   projectRoot?: string;
 }) => Promise<unknown>;
-export declare const renderDetectedConfig: (detected: unknown) => string;
+export declare const renderDetectedConfig: (
+  detected: unknown,
+  options?: {
+    applicationUrl?: string;
+    ports?: { api: number; database: number; studio: number };
+  },
+) => string;
 export declare const SANITIZATION_ACTIONS: Readonly<{
   KEEP: "KEEP";
   PSEUDONYMIZE: "PSEUDONYMIZE";
@@ -75,6 +81,13 @@ export declare const validateSanitizationCoverage: (options: {
   columnCount: number;
   tables: ReadonlyArray<Record<string, unknown>>;
 }>;
+export declare const validateRuntimeSanitizationPolicy: (
+  policy: unknown,
+) => unknown;
+export declare const readBoundRuntimeSanitizationPolicy: (options: {
+  bytes: Uint8Array | string;
+  expectedSha256: string;
+}) => unknown;
 export declare const applySanitizationAction: (options: {
   action: string;
   value: unknown;

package/scripts/lib/rehearsal/configuration.mjs

@@ -13,7 +13,9 @@ export {
   SANITIZATION_ACTIONS,
   applySanitizationAction,
   normalizeSanitizationAction,
+  readBoundRuntimeSanitizationPolicy,
   validateSanitizationCoverage,
+  validateRuntimeSanitizationPolicy,
 } from "./sanitization_policy.mjs";
 
 export const REHEARSAL_CONFIG_VERSION = 1;
@@ -494,12 +496,15 @@ export const inspectDetectedProject = async ({
       ? "yarn"
       : "npm";
   const scripts = packageJson.scripts ?? {};
+  const normalizedProjectName = String(packageJson.name ?? basename(root))
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/gu, "-")
+    .replace(/^-|-$/gu, "");
+  const projectName =
+    normalizedProjectName.slice(0, 52).replace(/-$/u, "") ||
+    "rehearsal-project";
   return {
-    projectName:
-      String(packageJson.name ?? basename(root))
-        .toLowerCase()
-        .replace(/[^a-z0-9-]+/gu, "-")
-        .replace(/^-|-$/gu, "") || "rehearsal-project",
+    projectName,
     packageManager,
     hasSupabaseConfig: await hasPath("supabase/config.toml"),
     hasMigrations: await hasPath("supabase/migrations"),
@@ -517,7 +522,12 @@ export const inspectDetectedProject = async ({
 
 export const renderDetectedConfig = (
   detected,
-) => `import { defineRehearsalConfig } from "@rehearsal-db/core";
+  {
+    applicationUrl = "http://localhost:5175",
+    ports = { api: 58321, database: 58322, studio: 58323 },
+  } = {},
+) => `// @ts-check
+import { defineRehearsalConfig } from "@rehearsal-db/core";
 
 export default defineRehearsalConfig({
 	schemaVersion: 1,
@@ -538,11 +548,11 @@ export default defineRehearsalConfig({
 		environmentFile: ".rehearsal/runtime.env",
 	},
 	runtime: {
-		applicationUrl: "http://localhost:5175",
+		applicationUrl: ${JSON.stringify(applicationUrl)},
 		projectId: "${detected.projectName}-rehearsal",
-		apiPort: 58321,
-		databasePort: 58322,
-		studioPort: 58323,
+		apiPort: ${ports.api},
+		databasePort: ${ports.database},
+		studioPort: ${ports.studio},
 	},
 	safety: {
 		allowedHosts: ["127.0.0.1", "::1", "localhost"],

package/scripts/lib/rehearsal/diagnostics.mjs

@@ -7,7 +7,7 @@
 import { createHash } from "node:crypto";
 
 export const REHEARSAL_RESULT_VERSION = 1;
-export const REHEARSAL_VERSION = "0.1.0-beta.1";
+export const REHEARSAL_VERSION = "0.1.0-beta.3";
 
 export const REHEARSAL_EXIT_CODES = Object.freeze({
   success: 0,
@@ -96,7 +96,9 @@ const inferCategory = (error) => {
   if (/candidate|migration history diverges/iu.test(message)) {
     return "migration_candidate_failure";
   }
-  if (/baseline|artifact|generation/iu.test(message)) return "baseline_invalid";
+  if (/baseline|artifact|generation|sanitization policy/iu.test(message)) {
+    return "baseline_invalid";
+  }
   if (/migration|ledger|replay/iu.test(message)) {
     return "migration_verification_failure";
   }
@@ -106,7 +108,9 @@ const inferCategory = (error) => {
   if (/loopback|hosted|unsafe|credential|outbound/iu.test(message)) {
     return "unsafe_environment";
   }
-  if (/docker|supabase|runtime|command|enoent/iu.test(message)) {
+  if (
+    /docker|supabase|runtime|command|enoent|node\.js|ports?\b/iu.test(message)
+  ) {
     return "runtime_dependency_failure";
   }
   return "internal_failure";

package/scripts/lib/rehearsal/human_output.mjs

@@ -0,0 +1,4 @@
+/** Purpose: Keep human-facing Rehearsal counts grammatically consistent. */
+
+export const formatCount = (count, singular, plural = `${singular}s`) =>
+  `${count} ${count === 1 ? singular : plural}`;

package/scripts/lib/rehearsal/plan.mjs

@@ -19,6 +19,10 @@ import { createCandidateMigrationReceipt } from "./runtime_restore.mjs";
 import { readMigrationFileInventory } from "./migration_history.mjs";
 import { REHEARSAL_VERSION } from "./diagnostics.mjs";
 import { readRehearsalServiceEnvironment } from "./service_environment.mjs";
+import {
+  readBoundRuntimeSanitizationPolicy,
+  validateRuntimeSanitizationPolicy,
+} from "./sanitization_policy.mjs";
 
 const commandAvailable = (command, args = ["--version"]) => {
   const result = spawnSync(command, args, {
@@ -155,8 +159,15 @@ const assertConfiguredCommand = async ({ command, projectRoot }) => {
 
 const loadPlanInputs = async (options = {}) => {
   const loaded = await loadRehearsalConfig(options);
-  const baseline = await verifyActiveBaseline({
-    artifactRoot: loaded.paths.artifactDirectory,
+  const [baseline, policyBytes] = await Promise.all([
+    verifyActiveBaseline({
+      artifactRoot: loaded.paths.artifactDirectory,
+    }),
+    readFile(loaded.paths.sanitizationPolicy),
+  ]);
+  readBoundRuntimeSanitizationPolicy({
+    bytes: policyBytes,
+    expectedSha256: baseline.sanitizationPolicySha256,
   });
   const currentFiles = await readMigrationFileInventory(
     new URL("./", pathToFileURL(`${loaded.paths.migrationDirectory}/`)),
@@ -412,6 +423,18 @@ export const runRehearsalDoctor = async (options = {}) => {
       remediation:
         "Correct the missing project path in the Rehearsal configuration.",
     },
+    {
+      id: "sanitization-policy",
+      label: "Reviewed sanitization policy",
+      run: async () => {
+        const policy = validateRuntimeSanitizationPolicy(
+          JSON.parse(await readFile(paths.sanitizationPolicy, "utf8")),
+        );
+        return `${policy.tables.length} table classifications reviewed through ${policy.migrationCutoff}`;
+      },
+      remediation:
+        "Complete every REVIEW REQUIRED decision, remove draft only after review, and retry.",
+    },
     {
       id: "runtime-isolation",
       label: "Runtime target isolation",

package/scripts/lib/rehearsal/sanitization_policy.mjs

@@ -3,6 +3,8 @@
  * Projects own the policy, schema inventory, pseudonym keys, and derivation logic.
  */
 
+import { createHash } from "node:crypto";
+
 export const SANITIZATION_ACTIONS = Object.freeze({
   KEEP: "KEEP",
   PSEUDONYMIZE: "PSEUDONYMIZE",
@@ -44,6 +46,114 @@ export const normalizeSanitizationAction = (action) => {
   return normalized;
 };
 
+export const validateRuntimeSanitizationPolicy = (policy) => {
+  if (!policy || typeof policy !== "object" || Array.isArray(policy)) {
+    throw new Error("A Rehearsal sanitization policy object is required.");
+  }
+  if (policy.draft === true) {
+    throw new Error(
+      "The sanitization policy is still a REVIEW REQUIRED draft.",
+    );
+  }
+  if (policy.policyVersion !== 1) {
+    throw new Error("The sanitization policy must use policyVersion 1.");
+  }
+  if (!/^\d{14}$/u.test(policy.migrationCutoff ?? "")) {
+    throw new Error(
+      "The sanitization policy must declare a timestamp migrationCutoff.",
+    );
+  }
+  if (!Array.isArray(policy.tables) || policy.tables.length === 0) {
+    throw new Error("The sanitization policy does not list tables.");
+  }
+  const tables = new Set();
+  for (const table of policy.tables) {
+    const tableName = assertIdentifier(
+      table?.name,
+      "Sanitization policy table name",
+    );
+    if (tables.has(tableName)) {
+      throw new Error(`Sanitization policy duplicates table ${tableName}.`);
+    }
+    tables.add(tableName);
+    if (!["STREAM AND SANITIZE", "EXCLUDE"].includes(table.sourceRows)) {
+      throw new Error(
+        `Sanitization policy table ${tableName} has an invalid sourceRows decision.`,
+      );
+    }
+    if (!Array.isArray(table.columns) || table.columns.length === 0) {
+      throw new Error(
+        `Sanitization policy table ${tableName} must list its columns.`,
+      );
+    }
+    const columns = new Set();
+    for (const column of table.columns) {
+      const columnName = assertIdentifier(
+        column?.name,
+        `Sanitization policy column in ${tableName}`,
+      );
+      if (columns.has(columnName)) {
+        throw new Error(
+          `Sanitization policy duplicates column ${tableName}.${columnName}.`,
+        );
+      }
+      columns.add(columnName);
+      normalizeSanitizationAction(column.action);
+      if (!["ALWAYS", "NEVER"].includes(column.generated)) {
+        throw new Error(
+          `Sanitization policy column ${tableName}.${columnName} must classify generated as ALWAYS or NEVER.`,
+        );
+      }
+      if (!["YES", "NO"].includes(column.identity)) {
+        throw new Error(
+          `Sanitization policy column ${tableName}.${columnName} must classify identity as YES or NO.`,
+        );
+      }
+      if (column.foreignKey !== null) {
+        if (
+          !column.foreignKey ||
+          typeof column.foreignKey !== "object" ||
+          Array.isArray(column.foreignKey)
+        ) {
+          throw new Error(
+            `Sanitization policy column ${tableName}.${columnName} has an invalid foreignKey decision.`,
+          );
+        }
+        assertIdentifier(
+          column.foreignKey.schema,
+          `Foreign-key schema for ${tableName}.${columnName}`,
+        );
+        assertIdentifier(
+          column.foreignKey.table,
+          `Foreign-key table for ${tableName}.${columnName}`,
+        );
+        assertIdentifier(
+          column.foreignKey.column,
+          `Foreign-key column for ${tableName}.${columnName}`,
+        );
+      }
+    }
+  }
+  return policy;
+};
+
+export const readBoundRuntimeSanitizationPolicy = ({
+  bytes,
+  expectedSha256,
+}) => {
+  const source = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes);
+  const policy = validateRuntimeSanitizationPolicy(
+    JSON.parse(source.toString("utf8")),
+  );
+  const actualSha256 = createHash("sha256").update(source).digest("hex");
+  if (actualSha256 !== expectedSha256) {
+    throw new Error(
+      "The active sanitization policy does not match the reviewed baseline policy checksum.",
+    );
+  }
+  return policy;
+};
+
 const indexTables = (tables, label) => {
   if (!Array.isArray(tables)) throw new Error(`${label} must be an array.`);
   const index = new Map();