fix(#1392): hash-ledger migrations + install-time schema verification (closes #1392, closes #1402) (#1403)

Co-authored-by: ops-deploy-01 <[email protected]>
2026-08-24 23:11:50 +00:00
parent d790572e2e
commit 4d24ae8618
9 changed files with 805 additions and 74 deletions
@@ -0,0 +1,107 @@
+/**
+ * Install-time database schema verification (#1392).
+ *
+ * Fresh standalone (postgres) installs once ended "healthy" with a completely
+ * empty database: the resolved dependency set shipped no migrations at all
+ * (#1389), the gateway started fine, and nothing failed until the first real
+ * query. The issue's own conclusion: the installer must "instruct and verify".
+ *
+ * This check runs AFTER migrations have been (re-)applied, so the only way it
+ * fails is a genuinely broken migration set or database — which is exactly
+ * when install must not report success. Failure is fatal by design (fast-fail
+ * STANDARDS); callers print the remediation text and exit non-zero.
+ */
+
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { loadConfig } from '@mosaicstack/config';
+
+export interface SchemaStatusCounts {
+  appliedCount: number;
+  expectedCount: number;
+  expectedLastTag: string;
+  complete: boolean;
+}
+
+/** Injectable migration surface — keeps this unit-testable without a DB. */
+export interface SchemaCheckDeps {
+  runMigrations(url: string): Promise<void>;
+  getMigrationStatus(url: string): Promise<SchemaStatusCounts>;
+}
+
+export type SchemaCheckResult =
+  | { status: 'ok'; detail: string }
+  | { status: 'skipped'; detail: string }
+  | { status: 'fail'; detail: string; remediation: string };
+
+export const SCHEMA_FAIL_REMEDIATION = [
+  'The gateway database does not carry the full schema.',
+  'Causes seen in the wild: dependency set resolved without migrations (#1389), or a partially-migrated database (#1402).',
+  'Remediation:',
+  '  1. Re-run: mosaic gateway install  (applies migrations and verifies again)',
+  '  2. Check the resolved @mosaicstack/db version is the same pipeline as the gateway (npm ls -g @mosaicstack/db)',
+  '  3. Manual apply: run runMigrations() from @mosaicstack/db against the storage URL, then re-verify',
+].join('\n');
+
+/**
+ * Resolve the config the INSTALLED gateway would use — same priority the
+ * daemon applies (apps/gateway/src/env.ts resolveGatewayConfigPath), minus
+ * the source-tree anchors that do not exist on an installed host. Verifying
+ * against any other config could green-light a database the daemon never
+ * reads (#1392: verify what runs, not what happens to lie in cwd).
+ */
+export function resolveSchemaCheckConfigPath(explicit?: string): string | undefined {
+  if (explicit) return resolve(explicit);
+  const candidates = [
+    process.env['MOSAIC_CONFIG'],
+    join(homedir(), '.config', 'mosaic', 'gateway', 'mosaic.config.json'), // daemon-written
+    resolve(process.cwd(), 'mosaic.config.json'),
+    join(homedir(), '.mosaic', 'mosaic.config.json'),
+  ];
+  for (const c of candidates) {
+    if (c && existsSync(c)) return c;
+  }
+  return undefined; // loadConfig falls back to env-var detection
+}
+
+export async function checkDatabaseSchema(
+  deps: SchemaCheckDeps,
+  configPath?: string,
+): Promise<SchemaCheckResult> {
+  const config = loadConfig(resolveSchemaCheckConfigPath(configPath));
+
+  // Local tier: the gateway itself runs PGlite migrations at startup (see
+  // DatabaseModule.onModuleInit), and a broken local tier fails the health
+  // check instead. Nothing for the installer to verify here.
+  if (config.storage.type !== 'postgres') {
+    return {
+      status: 'skipped',
+      detail: 'database schema (local tier — migrated by gateway at startup)',
+    };
+  }
+
+  const url = config.storage.url;
+  try {
+    await deps.runMigrations(url);
+    const status = await deps.getMigrationStatus(url);
+    if (status.complete) {
+      return {
+        status: 'ok',
+        detail: `database schema (${status.appliedCount.toString()}/${status.expectedCount.toString()} migrations)`,
+      };
+    }
+    return {
+      status: 'fail',
+      detail: `database schema incomplete (${status.appliedCount.toString()}/${status.expectedCount.toString()} applied, last expected: ${status.expectedLastTag})`,
+      remediation: SCHEMA_FAIL_REMEDIATION,
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return {
+      status: 'fail',
+      detail: `database schema check errored: ${msg}`,
+      remediation: SCHEMA_FAIL_REMEDIATION,
+    };
+  }
+}