turbine-orm 0.49.0 → 0.50.0

package/dist/cli/migrate.js

@@ -41,6 +41,20 @@ export function collectUpDestructive(files) {
 // Tracking table management
 // ---------------------------------------------------------------------------
 const TRACKING_TABLE = '_turbine_migrations';
+/**
+ * The dialect the migration runner speaks.
+ *
+ * The runner connects with `pg.Client`, so Postgres (and the Postgres-compatible
+ * engines behind `adapters/`) is the only thing it can actually reach. The
+ * dialect is still threaded through every tracking-table statement, so making
+ * migrations dialect-aware is a matter of teaching this layer to build the
+ * engine's own client. Until then there is deliberately NO caller-supplied
+ * dialect option: accepting one would advertise sqlite/mysql/mssql migrations
+ * that silently run their SQL against Postgres.
+ */
+function migrationDialect() {
+    return postgresDialect;
+}
 function quotedTrackingTable(dialect) {
     return dialect.quoteIdentifier(TRACKING_TABLE);
 }
@@ -342,9 +356,53 @@ export function parseMigrationSQL(filePath) {
 function checksum(content) {
     return createHash('sha256').update(content, 'utf-8').digest('hex');
 }
-/** Detect legacy djb2 checksums (short alphanumeric strings, pre-v0.6) */
+/**
+ * The pre-v0.6 checksum algorithm (a 32-bit rolling hash rendered as base36).
+ * Kept verbatim so a legacy stored value can be RE-DERIVED from the current
+ * file content before we upgrade the row to SHA-256. Never used for new rows.
+ */
+function legacyChecksum(content) {
+    let hash = 0;
+    for (let i = 0; i < content.length; i++) {
+        const chr = content.charCodeAt(i);
+        hash = ((hash << 5) - hash + chr) | 0;
+    }
+    return Math.abs(hash).toString(36);
+}
+/**
+ * Detect legacy checksums (short alphanumeric strings, pre-v0.6).
+ * An EMPTY checksum is never legacy: blessing it would silently disarm drift
+ * detection for a row whose stored hash was lost or never written.
+ */
 function isLegacyChecksum(hash) {
-    return hash.length < 64;
+    return hash.length > 0 && hash.length < 64;
+}
+/**
+ * Can a stored pre-v0.6 checksum be safely upgraded to SHA-256?
+ *
+ * Only when the LEGACY algorithm, run over the file's CURRENT content,
+ * reproduces the stored value: that is what proves the file has not changed
+ * since it was applied. Upgrading without this proof blesses whatever the file
+ * says today and permanently disables drift detection for that migration.
+ *
+ * @internal exported for tests.
+ */
+export function canUpgradeLegacyChecksum(stored, content) {
+    return isLegacyChecksum(stored) && legacyChecksum(content) === stored;
+}
+/**
+ * Is an applied migration's stored checksum still valid for the file on disk?
+ *
+ * A SHA-256 match is the normal case. A pre-v0.6 row that {@link
+ * canUpgradeLegacyChecksum} would upgrade counts as valid too: `migrate up`
+ * accepts and upgrades it, so reporting it as invalid in `migrate status` would
+ * have the two commands disagree about the same unchanged file. Genuine drift
+ * (a legacy hash the current content no longer reproduces) still reports false.
+ *
+ * @internal exported for tests.
+ */
+export function isChecksumValid(stored, content) {
+    return checksum(content) === stored || canUpgradeLegacyChecksum(stored, content);
 }
 /** The sanctioned two-phase (add nullable, batched backfill, swap) recipe. */
 function buildBackfillRecipe() {
@@ -592,11 +650,42 @@ async function releaseLock(client, lockId, adapter) {
     const a = adapter ?? postgresql;
     await a.releaseLock(client, lockId);
 }
+/**
+ * Run one migration body (UP or DOWN) plus its tracking-table write inside a
+ * single transaction. Returns `null` on success, or the error message on
+ * failure, leaving the caller to record it and stop.
+ *
+ * The ROLLBACK is best-effort: if the connection died, ROLLBACK throws too, and
+ * letting that escape would replace the real migration failure with a
+ * connection error. Same guard as `client.ts`, `query/builder.ts`, `dialect.ts`.
+ *
+ * @internal exported for tests; not part of the CLI's public surface.
+ */
+export async function runMigrationInTransaction(client, body, tracking) {
+    try {
+        await client.query('BEGIN');
+        await client.query(body);
+        await client.query(tracking.sql, tracking.params);
+        await client.query('COMMIT');
+        return null;
+    }
+    catch (err) {
+        try {
+            await client.query('ROLLBACK');
+        }
+        catch {
+            // Best effort: the original error below is what the user needs to see.
+        }
+        return err instanceof Error ? err.message : String(err);
+    }
+}
 /**
  * Validate that applied migration files have not been modified or deleted since they were run.
  * Returns an array of mismatched migrations (empty if all are clean).
+ *
+ * @internal exported for tests; not part of the CLI's public surface.
  */
-async function validateChecksums(client, migrationsDir, dialect = postgresDialect) {
+export async function validateChecksums(client, migrationsDir, dialect = postgresDialect) {
     const applied = await getAppliedMigrations(client, dialect);
     const allFiles = listMigrationFiles(migrationsDir);
     const fileMap = new Map(allFiles.map((f) => [f.name, f]));
@@ -615,8 +704,11 @@ async function validateChecksums(client, migrationsDir, dialect = postgresDialec
         const content = readFileSync(file.path, 'utf-8');
         const currentHash = checksum(content);
         if (currentHash !== migration.checksum) {
-            // Auto-upgrade legacy djb2 checksums to SHA-256 without flagging as modified
-            if (isLegacyChecksum(migration.checksum)) {
+            // Auto-upgrade a pre-v0.6 checksum to SHA-256 without flagging it as
+            // modified, but ONLY when the legacy hash of the current content still
+            // matches what was stored. A legacy row whose file HAS changed falls
+            // through to the mismatch path below (bypassable with --allow-drift).
+            if (canUpgradeLegacyChecksum(migration.checksum, content)) {
                 await client.query(dialect.buildMigrationUpdateChecksum(quotedTrackingTable(dialect)), [
                     currentHash,
                     migration.name,
@@ -683,8 +775,11 @@ export function planMigrationDeploy(migrationsDir, applied) {
             });
             continue;
         }
-        const currentHash = checksum(readFileSync(file.path, 'utf-8'));
-        if (currentHash !== migration.checksum && !isLegacyChecksum(migration.checksum)) {
+        const content = readFileSync(file.path, 'utf-8');
+        const currentHash = checksum(content);
+        // A pre-v0.6 checksum is only forgiven when the legacy algorithm over the
+        // current content still reproduces it: otherwise the file really has drifted.
+        if (currentHash !== migration.checksum && !canUpgradeLegacyChecksum(migration.checksum, content)) {
             mismatches.push({
                 name: migration.name,
                 expected: migration.checksum,
@@ -701,10 +796,10 @@ export function planMigrationDeploy(migrationsDir, applied) {
 /**
  * Inspect deploy status without applying migrations.
  */
-export async function inspectMigrationDeploy(connectionString, migrationsDir, options) {
+export async function inspectMigrationDeploy(connectionString, migrationsDir) {
     const client = new pg.Client({ connectionString });
     await client.connect();
-    const dialect = options?.dialect ?? postgresDialect;
+    const dialect = migrationDialect();
     try {
         await ensureTrackingTable(client, dialect);
         const mismatches = await validateChecksums(client, migrationsDir, dialect);
@@ -738,7 +833,7 @@ export async function migrateUp(connectionString, migrationsDir, options) {
     await client.connect();
     // Treat `force` as an alias for `allowDrift` for backwards compatibility.
     const allowDrift = options?.allowDrift === true || options?.force === true;
-    const dialect = options?.dialect ?? postgresDialect;
+    const dialect = migrationDialect();
     try {
         // Derive an advisory lock ID per-database so concurrent migrations in
         // sibling databases on the same Postgres cluster do not contend.
@@ -845,21 +940,17 @@ export async function migrateUp(connectionString, migrationsDir, options) {
                     }
                     continue;
                 }
-                try {
-                    await client.query('BEGIN');
-                    await client.query(up);
-                    await client.query(insertApplied, [file.name, hash]);
-                    await client.query('COMMIT');
-                    results.push(file);
-                    flagOutOfOrder(file);
-                }
-                catch (err) {
-                    await client.query('ROLLBACK');
-                    const msg = err instanceof Error ? err.message : String(err);
-                    errors.push({ file, error: msg });
+                const failure = await runMigrationInTransaction(client, up, {
+                    sql: insertApplied,
+                    params: [file.name, hash],
+                });
+                if (failure !== null) {
+                    errors.push({ file, error: failure });
                     // Stop on first error
                     break;
                 }
+                results.push(file);
+                flagOutOfOrder(file);
             }
             return { applied: results, errors, destructive, outOfOrder, noTransaction: noTransactionApplied };
         }
@@ -882,7 +973,6 @@ export async function migrateDeploy(connectionString, migrationsDir, options) {
         allowDrift: options?.allowDrift === true,
         allowDestructive: true,
         adapter: options?.adapter,
-        dialect: options?.dialect,
     });
 }
 /**
@@ -896,7 +986,7 @@ export async function migrateDeploy(connectionString, migrationsDir, options) {
 export async function migrateDown(connectionString, migrationsDir, options) {
     const client = new pg.Client({ connectionString });
     await client.connect();
-    const dialect = options?.dialect ?? postgresDialect;
+    const dialect = migrationDialect();
     try {
         // Derive a per-database advisory lock ID so concurrent migrations in
         // sibling databases on the same cluster do not contend.
@@ -982,19 +1072,15 @@ export async function migrateDown(connectionString, migrationsDir, options) {
                     }
                     continue;
                 }
-                try {
-                    await client.query('BEGIN');
-                    await client.query(down);
-                    await client.query(deleteApplied, [migration.name]);
-                    await client.query('COMMIT');
-                    results.push(file);
-                }
-                catch (err) {
-                    await client.query('ROLLBACK');
-                    const msg = err instanceof Error ? err.message : String(err);
-                    errors.push({ file, error: msg });
+                const failure = await runMigrationInTransaction(client, down, {
+                    sql: deleteApplied,
+                    params: [migration.name],
+                });
+                if (failure !== null) {
+                    errors.push({ file, error: failure });
                     break;
                 }
+                results.push(file);
             }
             return { rolledBack: results, errors };
         }
@@ -1008,12 +1094,15 @@ export async function migrateDown(connectionString, migrationsDir, options) {
 }
 /**
  * Get the status of all migrations (applied vs pending).
- * Includes checksum validation for applied migrations.
+ *
+ * Applied rows carry `checksumValid`, decided by {@link isChecksumValid} so an
+ * unchanged pre-v0.6 row reports the same way `migrate up` treats it (valid,
+ * pending an in-place hash upgrade) rather than looking like drift.
  */
-export async function migrateStatus(connectionString, migrationsDir, options) {
+export async function migrateStatus(connectionString, migrationsDir) {
     const client = new pg.Client({ connectionString });
     await client.connect();
-    const dialect = options?.dialect ?? postgresDialect;
+    const dialect = migrationDialect();
     try {
         await ensureTrackingTable(client, dialect);
         const applied = await getAppliedMigrations(client, dialect);
@@ -1024,9 +1113,7 @@ export async function migrateStatus(connectionString, migrationsDir, options) {
             const record = appliedMap.get(file.name);
             let checksumValid;
             if (record) {
-                const content = readFileSync(file.path, 'utf-8');
-                const currentHash = checksum(content);
-                checksumValid = currentHash === record.checksum;
+                checksumValid = isChecksumValid(record.checksum, readFileSync(file.path, 'utf-8'));
             }
             return {
                 file,

package/dist/cli/observe-ui.d.ts

@@ -1 +1 @@
-export declare const OBSERVE_HTML = "<!doctype html>\n<html lang=\"en\">\n<head>\n  <meta charset=\"utf-8\" />\n  <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\" />\n  <meta name=\"color-scheme\" content=\"dark\" />\n  <title>Turbine Observe</title>\n  <style>\n    :root {\n      --bg: #0a0a0b;\n      --bg-elev: #111113;\n      --bg-hover: #1a1a1d;\n      --border: #26262b;\n      --text: #e6e6ea;\n      --text-dim: #8a8a93;\n      --accent: #60a5fa;\n      --green: #4ade80;\n      --red: #f87171;\n      --orange: #fb923c;\n      --purple: #a78bfa;\n      --mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;\n      --sans: system-ui, -apple-system, sans-serif;\n      --radius: 6px;\n    }\n    * { margin: 0; padding: 0; box-sizing: border-box; }\n    body { background: var(--bg); color: var(--text); font-family: var(--sans); font-size: 14px; padding: 24px; }\n    h1 { font-size: 20px; margin-bottom: 4px; }\n    .subtitle { color: var(--text-dim); margin-bottom: 24px; }\n    .controls { display: flex; gap: 8px; margin-bottom: 24px; }\n    .controls button {\n      background: var(--bg-elev); border: 1px solid var(--border); border-radius: var(--radius);\n      color: var(--text); padding: 6px 12px; cursor: pointer; font-size: 13px;\n    }\n    .controls button.active { border-color: var(--accent); color: var(--accent); }\n    .card {\n      background: var(--bg-elev); border: 1px solid var(--border); border-radius: var(--radius);\n      padding: 16px; margin-bottom: 16px;\n    }\n    .card h2 { font-size: 14px; color: var(--text-dim); margin-bottom: 12px; text-transform: uppercase; letter-spacing: 0.5px; }\n    table { width: 100%; border-collapse: collapse; font-family: var(--mono); font-size: 12px; }\n    th { text-align: left; padding: 6px 8px; color: var(--text-dim); border-bottom: 1px solid var(--border); }\n    td { padding: 6px 8px; border-bottom: 1px solid var(--border); }\n    .num { text-align: right; }\n    .error-rate { color: var(--red); }\n    .low-error { color: var(--green); }\n    svg { width: 100%; height: 200px; }\n    .chart-line { fill: none; stroke-width: 1.5; }\n    .line-avg { stroke: var(--accent); }\n    .line-p95 { stroke: var(--orange); }\n    .line-p99 { stroke: var(--red); }\n    .legend { display: flex; gap: 16px; margin-top: 8px; font-size: 12px; color: var(--text-dim); }\n    .legend span::before { content: ''; display: inline-block; width: 12px; height: 2px; margin-right: 4px; vertical-align: middle; }\n    .legend .l-avg::before { background: var(--accent); }\n    .legend .l-p95::before { background: var(--orange); }\n    .legend .l-p99::before { background: var(--red); }\n    .empty { color: var(--text-dim); text-align: center; padding: 40px; }\n  </style>\n</head>\n<body>\n  <h1>Turbine Observe</h1>\n  <p class=\"subtitle\">Query performance metrics</p>\n  <div class=\"controls\">\n    <button data-range=\"1h\" class=\"active\">1h</button>\n    <button data-range=\"6h\">6h</button>\n    <button data-range=\"24h\">24h</button>\n    <button data-range=\"7d\">7d</button>\n  </div>\n  <div class=\"card\" id=\"latency-card\">\n    <h2>Latency over time</h2>\n    <div id=\"chart\"></div>\n    <div class=\"legend\">\n      <span class=\"l-avg\">avg</span>\n      <span class=\"l-p95\">p95</span>\n      <span class=\"l-p99\">p99</span>\n    </div>\n  </div>\n  <div class=\"card\" id=\"models-card\">\n    <h2>Top models</h2>\n    <div id=\"models-table\"></div>\n  </div>\n  <div class=\"card\" id=\"errors-card\">\n    <h2>Error rates</h2>\n    <div id=\"errors-table\"></div>\n  </div>\n  <script>\n    let currentRange = '1h';\n    const token = document.cookie.match(/turbine_observe_token=([a-f0-9]+)/)?.[1] || '';\n    const headers = { 'x-turbine-token': token };\n\n    document.querySelector('.controls').addEventListener('click', e => {\n      if (e.target.tagName !== 'BUTTON') return;\n      document.querySelectorAll('.controls button').forEach(b => b.classList.remove('active'));\n      e.target.classList.add('active');\n      currentRange = e.target.dataset.range;\n      refresh();\n    });\n\n    async function fetchJson(path) {\n      const res = await fetch(path, { headers });\n      if (!res.ok) return null;\n      return res.json();\n    }\n\n    function buildSvgPath(points, width, height, maxY) {\n      if (points.length === 0) return '';\n      const xStep = width / Math.max(points.length - 1, 1);\n      return points.map((y, i) => {\n        const px = i * xStep;\n        const py = height - (y / maxY) * height;\n        return (i === 0 ? 'M' : 'L') + px.toFixed(1) + ',' + py.toFixed(1);\n      }).join(' ');\n    }\n\n    function renderChart(data) {\n      const el = document.getElementById('chart');\n      if (!data || data.length === 0) { el.innerHTML = '<p class=\"empty\">No data yet</p>'; return; }\n      const width = 800; const height = 180;\n      const allVals = data.flatMap(d => [d.avg_ms, d.p95_ms, d.p99_ms]);\n      const maxY = Math.max(...allVals, 1) * 1.1;\n      const avgPath = buildSvgPath(data.map(d => d.avg_ms), width, height, maxY);\n      const p95Path = buildSvgPath(data.map(d => d.p95_ms), width, height, maxY);\n      const p99Path = buildSvgPath(data.map(d => d.p99_ms), width, height, maxY);\n      el.innerHTML = '<svg viewBox=\"0 0 ' + width + ' ' + height + '\" preserveAspectRatio=\"none\">'\n        + '<path class=\"chart-line line-avg\" d=\"' + avgPath + '\"/>'\n        + '<path class=\"chart-line line-p95\" d=\"' + p95Path + '\"/>'\n        + '<path class=\"chart-line line-p99\" d=\"' + p99Path + '\"/>'\n        + '</svg>';\n    }\n\n    function escapeHtml(s) {\n      if (s == null) return '';\n      return String(s)\n        .replace(/&/g, '&amp;')\n        .replace(/</g, '&lt;')\n        .replace(/>/g, '&gt;')\n        .replace(/\"/g, '&quot;')\n        .replace(/'/g, '&#39;');\n    }\n\n    function renderModels(data) {\n      const el = document.getElementById('models-table');\n      if (!data || data.length === 0) { el.innerHTML = '<p class=\"empty\">No data yet</p>'; return; }\n      let html = '<table><thead><tr><th>Model</th><th>Action</th><th class=\"num\">Count</th><th class=\"num\">Avg (ms)</th><th class=\"num\">P95 (ms)</th><th class=\"num\">P99 (ms)</th></tr></thead><tbody>';\n      for (const row of data) {\n        html += '<tr><td>' + escapeHtml(row.model) + '</td><td>' + escapeHtml(row.action) + '</td>'\n          + '<td class=\"num\">' + row.count + '</td>'\n          + '<td class=\"num\">' + row.avg_ms.toFixed(1) + '</td>'\n          + '<td class=\"num\">' + row.p95_ms.toFixed(1) + '</td>'\n          + '<td class=\"num\">' + row.p99_ms.toFixed(1) + '</td></tr>';\n      }\n      html += '</tbody></table>';\n      el.innerHTML = html;\n    }\n\n    function renderErrors(data) {\n      const el = document.getElementById('errors-table');\n      if (!data || data.length === 0) { el.innerHTML = '<p class=\"empty\">No errors</p>'; return; }\n      let html = '<table><thead><tr><th>Model</th><th>Action</th><th class=\"num\">Total</th><th class=\"num\">Errors</th><th class=\"num\">Rate</th></tr></thead><tbody>';\n      for (const row of data) {\n        const rate = row.count > 0 ? (row.error_count / row.count * 100).toFixed(1) : '0.0';\n        const cls = parseFloat(rate) > 5 ? 'error-rate' : 'low-error';\n        html += '<tr><td>' + escapeHtml(row.model) + '</td><td>' + escapeHtml(row.action) + '</td>'\n          + '<td class=\"num\">' + row.count + '</td>'\n          + '<td class=\"num\">' + row.error_count + '</td>'\n          + '<td class=\"num ' + cls + '\">' + rate + '%</td></tr>';\n      }\n      html += '</tbody></table>';\n      el.innerHTML = html;\n    }\n\n    async function refresh() {\n      const [latency, models] = await Promise.all([\n        fetchJson('/api/latency?range=' + currentRange),\n        fetchJson('/api/models?range=' + currentRange),\n      ]);\n      renderChart(latency);\n      renderModels(models);\n      // Derive errors from models data\n      const withErrors = (models || []).filter(m => m.error_count > 0);\n      renderErrors(withErrors);\n    }\n\n    refresh();\n    setInterval(refresh, 60000);\n  </script>\n</body>\n</html>";
+export declare const OBSERVE_HTML = "<!doctype html>\n<html lang=\"en\">\n<head>\n  <meta charset=\"utf-8\" />\n  <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\" />\n  <meta name=\"color-scheme\" content=\"dark\" />\n  <title>Turbine Observe</title>\n  <style>\n    :root {\n      --bg: #0a0a0b;\n      --bg-elev: #111113;\n      --bg-hover: #1a1a1d;\n      --border: #26262b;\n      --text: #e6e6ea;\n      --text-dim: #8a8a93;\n      --accent: #60a5fa;\n      --green: #4ade80;\n      --red: #f87171;\n      --orange: #fb923c;\n      --purple: #a78bfa;\n      --mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;\n      --sans: system-ui, -apple-system, sans-serif;\n      --radius: 6px;\n    }\n    * { margin: 0; padding: 0; box-sizing: border-box; }\n    body { background: var(--bg); color: var(--text); font-family: var(--sans); font-size: 14px; padding: 24px; }\n    h1 { font-size: 20px; margin-bottom: 4px; }\n    .subtitle { color: var(--text-dim); margin-bottom: 24px; }\n    .controls { display: flex; gap: 8px; margin-bottom: 24px; }\n    .controls button {\n      background: var(--bg-elev); border: 1px solid var(--border); border-radius: var(--radius);\n      color: var(--text); padding: 6px 12px; cursor: pointer; font-size: 13px;\n    }\n    .controls button.active { border-color: var(--accent); color: var(--accent); }\n    .card {\n      background: var(--bg-elev); border: 1px solid var(--border); border-radius: var(--radius);\n      padding: 16px; margin-bottom: 16px;\n    }\n    .card h2 { font-size: 14px; color: var(--text-dim); margin-bottom: 12px; text-transform: uppercase; letter-spacing: 0.5px; }\n    table { width: 100%; border-collapse: collapse; font-family: var(--mono); font-size: 12px; }\n    th { text-align: left; padding: 6px 8px; color: var(--text-dim); border-bottom: 1px solid var(--border); }\n    td { padding: 6px 8px; border-bottom: 1px solid var(--border); }\n    .num { text-align: right; }\n    .error-rate { color: var(--red); }\n    .low-error { color: var(--green); }\n    svg { width: 100%; height: 200px; }\n    .chart-line { fill: none; stroke-width: 1.5; }\n    .line-avg { stroke: var(--accent); }\n    .line-p95 { stroke: var(--orange); }\n    .line-p99 { stroke: var(--red); }\n    .legend { display: flex; gap: 16px; margin-top: 8px; font-size: 12px; color: var(--text-dim); }\n    .legend span::before { content: ''; display: inline-block; width: 12px; height: 2px; margin-right: 4px; vertical-align: middle; }\n    .legend .l-avg::before { background: var(--accent); }\n    .legend .l-p95::before { background: var(--orange); }\n    .legend .l-p99::before { background: var(--red); }\n    .empty { color: var(--text-dim); text-align: center; padding: 40px; }\n  </style>\n</head>\n<body>\n  <h1>Turbine Observe</h1>\n  <p class=\"subtitle\">Query performance metrics</p>\n  <div class=\"controls\">\n    <button data-range=\"1h\" class=\"active\">1h</button>\n    <button data-range=\"6h\">6h</button>\n    <button data-range=\"24h\">24h</button>\n    <button data-range=\"7d\">7d</button>\n  </div>\n  <div class=\"card\" id=\"latency-card\">\n    <h2>Latency over time</h2>\n    <div id=\"chart\"></div>\n    <div class=\"legend\">\n      <span class=\"l-avg\">avg</span>\n      <span class=\"l-p95\">p95</span>\n      <span class=\"l-p99\">p99</span>\n    </div>\n  </div>\n  <div class=\"card\" id=\"models-card\">\n    <h2>Top models</h2>\n    <div id=\"models-table\"></div>\n  </div>\n  <div class=\"card\" id=\"errors-card\">\n    <h2>Error rates</h2>\n    <div id=\"errors-table\"></div>\n  </div>\n  <script nonce=\"__CSP_NONCE__\">\n    let currentRange = '1h';\n    // Anchored on a cookie boundary so a decoy cookie whose name ends with this\n    // one cannot shadow the real token.\n    const token = document.cookie.match(/(?:^|;\\s*)turbine_observe_token=([a-f0-9]+)/)?.[1] || '';\n    const headers = { 'x-turbine-token': token };\n\n    document.querySelector('.controls').addEventListener('click', e => {\n      if (e.target.tagName !== 'BUTTON') return;\n      document.querySelectorAll('.controls button').forEach(b => b.classList.remove('active'));\n      e.target.classList.add('active');\n      currentRange = e.target.dataset.range;\n      refresh();\n    });\n\n    async function fetchJson(path) {\n      const res = await fetch(path, { headers });\n      if (!res.ok) return null;\n      return res.json();\n    }\n\n    function buildSvgPath(points, width, height, maxY) {\n      if (points.length === 0) return '';\n      const xStep = width / Math.max(points.length - 1, 1);\n      return points.map((y, i) => {\n        const px = i * xStep;\n        const py = height - (y / maxY) * height;\n        return (i === 0 ? 'M' : 'L') + px.toFixed(1) + ',' + py.toFixed(1);\n      }).join(' ');\n    }\n\n    function renderChart(data) {\n      const el = document.getElementById('chart');\n      if (!data || data.length === 0) { el.innerHTML = '<p class=\"empty\">No data yet</p>'; return; }\n      const width = 800; const height = 180;\n      const allVals = data.flatMap(d => [d.avg_ms, d.p95_ms, d.p99_ms]);\n      const maxY = Math.max(...allVals, 1) * 1.1;\n      const avgPath = buildSvgPath(data.map(d => d.avg_ms), width, height, maxY);\n      const p95Path = buildSvgPath(data.map(d => d.p95_ms), width, height, maxY);\n      const p99Path = buildSvgPath(data.map(d => d.p99_ms), width, height, maxY);\n      el.innerHTML = '<svg viewBox=\"0 0 ' + width + ' ' + height + '\" preserveAspectRatio=\"none\">'\n        + '<path class=\"chart-line line-avg\" d=\"' + avgPath + '\"/>'\n        + '<path class=\"chart-line line-p95\" d=\"' + p95Path + '\"/>'\n        + '<path class=\"chart-line line-p99\" d=\"' + p99Path + '\"/>'\n        + '</svg>';\n    }\n\n    function escapeHtml(s) {\n      if (s == null) return '';\n      return String(s)\n        .replace(/&/g, '&amp;')\n        .replace(/</g, '&lt;')\n        .replace(/>/g, '&gt;')\n        .replace(/\"/g, '&quot;')\n        .replace(/'/g, '&#39;');\n    }\n\n    // Numeric sink: counts are integer aggregates, but they are still values\n    // arriving over the wire, so coerce rather than interpolating them raw.\n    function num(v) {\n      const n = Number(v);\n      return Number.isFinite(n) ? String(n) : '0';\n    }\n\n    function renderModels(data) {\n      const el = document.getElementById('models-table');\n      if (!data || data.length === 0) { el.innerHTML = '<p class=\"empty\">No data yet</p>'; return; }\n      let html = '<table><thead><tr><th>Model</th><th>Action</th><th class=\"num\">Count</th><th class=\"num\">Avg (ms)</th><th class=\"num\">P95 (ms)</th><th class=\"num\">P99 (ms)</th></tr></thead><tbody>';\n      for (const row of data) {\n        html += '<tr><td>' + escapeHtml(row.model) + '</td><td>' + escapeHtml(row.action) + '</td>'\n          + '<td class=\"num\">' + num(row.count) + '</td>'\n          + '<td class=\"num\">' + row.avg_ms.toFixed(1) + '</td>'\n          + '<td class=\"num\">' + row.p95_ms.toFixed(1) + '</td>'\n          + '<td class=\"num\">' + row.p99_ms.toFixed(1) + '</td></tr>';\n      }\n      html += '</tbody></table>';\n      el.innerHTML = html;\n    }\n\n    function renderErrors(data) {\n      const el = document.getElementById('errors-table');\n      if (!data || data.length === 0) { el.innerHTML = '<p class=\"empty\">No errors</p>'; return; }\n      let html = '<table><thead><tr><th>Model</th><th>Action</th><th class=\"num\">Total</th><th class=\"num\">Errors</th><th class=\"num\">Rate</th></tr></thead><tbody>';\n      for (const row of data) {\n        const rate = row.count > 0 ? (row.error_count / row.count * 100).toFixed(1) : '0.0';\n        const cls = parseFloat(rate) > 5 ? 'error-rate' : 'low-error';\n        html += '<tr><td>' + escapeHtml(row.model) + '</td><td>' + escapeHtml(row.action) + '</td>'\n          + '<td class=\"num\">' + num(row.count) + '</td>'\n          + '<td class=\"num\">' + num(row.error_count) + '</td>'\n          + '<td class=\"num ' + cls + '\">' + rate + '%</td></tr>';\n      }\n      html += '</tbody></table>';\n      el.innerHTML = html;\n    }\n\n    async function refresh() {\n      const [latency, models] = await Promise.all([\n        fetchJson('/api/latency?range=' + currentRange),\n        fetchJson('/api/models?range=' + currentRange),\n      ]);\n      renderChart(latency);\n      renderModels(models);\n      // Derive errors from models data\n      const withErrors = (models || []).filter(m => m.error_count > 0);\n      renderErrors(withErrors);\n    }\n\n    refresh();\n    setInterval(refresh, 60000);\n  </script>\n</body>\n</html>";

package/dist/cli/observe-ui.js

@@ -84,9 +84,11 @@ export const OBSERVE_HTML = `<!doctype html>
     <h2>Error rates</h2>
     <div id="errors-table"></div>
   </div>
-  <script>
+  <script nonce="__CSP_NONCE__">
     let currentRange = '1h';
-    const token = document.cookie.match(/turbine_observe_token=([a-f0-9]+)/)?.[1] || '';
+    // Anchored on a cookie boundary so a decoy cookie whose name ends with this
+    // one cannot shadow the real token.
+    const token = document.cookie.match(/(?:^|;\\s*)turbine_observe_token=([a-f0-9]+)/)?.[1] || '';
     const headers = { 'x-turbine-token': token };
 
     document.querySelector('.controls').addEventListener('click', e => {
@@ -139,13 +141,20 @@ export const OBSERVE_HTML = `<!doctype html>
         .replace(/'/g, '&#39;');
     }
 
+    // Numeric sink: counts are integer aggregates, but they are still values
+    // arriving over the wire, so coerce rather than interpolating them raw.
+    function num(v) {
+      const n = Number(v);
+      return Number.isFinite(n) ? String(n) : '0';
+    }
+
     function renderModels(data) {
       const el = document.getElementById('models-table');
       if (!data || data.length === 0) { el.innerHTML = '<p class="empty">No data yet</p>'; return; }
       let html = '<table><thead><tr><th>Model</th><th>Action</th><th class="num">Count</th><th class="num">Avg (ms)</th><th class="num">P95 (ms)</th><th class="num">P99 (ms)</th></tr></thead><tbody>';
       for (const row of data) {
         html += '<tr><td>' + escapeHtml(row.model) + '</td><td>' + escapeHtml(row.action) + '</td>'
-          + '<td class="num">' + row.count + '</td>'
+          + '<td class="num">' + num(row.count) + '</td>'
           + '<td class="num">' + row.avg_ms.toFixed(1) + '</td>'
           + '<td class="num">' + row.p95_ms.toFixed(1) + '</td>'
           + '<td class="num">' + row.p99_ms.toFixed(1) + '</td></tr>';
@@ -162,8 +171,8 @@ export const OBSERVE_HTML = `<!doctype html>
         const rate = row.count > 0 ? (row.error_count / row.count * 100).toFixed(1) : '0.0';
         const cls = parseFloat(rate) > 5 ? 'error-rate' : 'low-error';
         html += '<tr><td>' + escapeHtml(row.model) + '</td><td>' + escapeHtml(row.action) + '</td>'
-          + '<td class="num">' + row.count + '</td>'
-          + '<td class="num">' + row.error_count + '</td>'
+          + '<td class="num">' + num(row.count) + '</td>'
+          + '<td class="num">' + num(row.error_count) + '</td>'
           + '<td class="num ' + cls + '">' + rate + '%</td></tr>';
       }
       html += '</tbody></table>';

package/dist/cli/observe.d.ts

@@ -1,10 +1,12 @@
 /**
- * turbine-orm CLI — Observe
+ * turbine-orm CLI: Observe
  *
  * A local, read-only dashboard for viewing query metrics stored in
  * _turbine_metrics. Same security model as Studio: loopback binding,
  * random token, HttpOnly cookie, CSP headers, read-only transactions.
  */
+import { type IncomingMessage, type ServerResponse } from 'node:http';
+import pg from 'pg';
 export interface ObserveOptions {
     url: string;
     port: number;
@@ -17,3 +19,7 @@ export interface ObserveServerHandle {
     url: string;
 }
 export declare function startObserve(options: ObserveOptions): Promise<ObserveServerHandle>;
+export declare function handleRequest(req: IncomingMessage, res: ServerResponse, pool: pg.Pool, options: ObserveOptions, authToken: string, rateLimiter: Map<string, {
+    count: number;
+    resetAt: number;
+}>): Promise<void>;

package/dist/cli/observe.js

@@ -1,5 +1,5 @@
 /**
- * turbine-orm CLI — Observe
+ * turbine-orm CLI: Observe
  *
  * A local, read-only dashboard for viewing query metrics stored in
  * _turbine_metrics. Same security model as Studio: loopback binding,
@@ -9,6 +9,7 @@ import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
 import { createServer } from 'node:http';
 import pg from 'pg';
 import { OBSERVE_HTML } from './observe-ui.js';
+import { callerKey, checkRateLimit } from './rate-limit.js';
 // ---------------------------------------------------------------------------
 // Main entry point
 // ---------------------------------------------------------------------------
@@ -26,8 +27,9 @@ export async function startObserve(options) {
         probe.release();
     }
     const authToken = randomBytes(24).toString('hex');
+    const rateLimiter = new Map();
     const server = createServer((req, res) => {
-        handleRequest(req, res, pool, options, authToken).catch((err) => {
+        handleRequest(req, res, pool, options, authToken, rateLimiter).catch((err) => {
             sendJson(res, 500, { error: err instanceof Error ? err.message : String(err) });
         });
     });
@@ -55,7 +57,7 @@ export async function startObserve(options) {
 // ---------------------------------------------------------------------------
 // Request routing
 // ---------------------------------------------------------------------------
-async function handleRequest(req, res, pool, options, authToken) {
+export async function handleRequest(req, res, pool, options, authToken, rateLimiter) {
     const hostPart = options.host.includes(':') && !options.host.startsWith('[') ? `[${options.host}]` : options.host;
     const expectedOrigin = `http://${hostPart}:${options.port}`;
     const origin = req.headers.origin;
@@ -79,10 +81,21 @@ async function handleRequest(req, res, pool, options, authToken) {
             res.end();
             return;
         }
-        sendHtml(res, 200, OBSERVE_HTML);
+        sendHtml(res, 200, OBSERVE_HTML, cspNonce());
         return;
     }
-    if (!isAuthorized(req, authToken)) {
+    // Rate limiting: the same fixed window as Studio (shared implementation), applied
+    // before the auth gate so unauthenticated probing is throttled too, and keyed
+    // per caller so the two never share a bucket.
+    const authorized = isAuthorized(req, authToken);
+    const rateLimitResult = checkRateLimit(rateLimiter, `${authorized ? 'session' : 'anon'}:${callerKey(req)}`);
+    if (!rateLimitResult.allowed) {
+        const retryAfter = Math.ceil((rateLimitResult.resetAt - Date.now()) / 1000);
+        res.setHeader('Retry-After', String(retryAfter));
+        sendJson(res, 429, { error: 'Rate limit exceeded', retryAfter });
+        return;
+    }
+    if (!authorized) {
         sendJson(res, 401, { error: 'unauthorized' });
         return;
     }
@@ -103,7 +116,10 @@ function isAuthorized(req, expectedToken) {
         return true;
     }
     const cookieHeader = req.headers.cookie ?? '';
-    const match = /turbine_observe_token=([a-f0-9]+)/.exec(cookieHeader);
+    // Anchored on a cookie boundary: unanchored, a decoy cookie whose name merely
+    // ENDS with this one (`x_turbine_observe_token=...`) matched first and the real
+    // token was never compared, denying the legitimate session.
+    const match = /(?:^|;\s*)turbine_observe_token=([a-f0-9]+)/.exec(cookieHeader);
     if (match?.[1] && constantTimeEqual(match[1], expectedToken)) {
         return true;
     }
@@ -200,19 +216,39 @@ const SECURITY_HEADERS = {
     'X-Content-Type-Options': 'nosniff',
     'X-Frame-Options': 'DENY',
     'Referrer-Policy': 'no-referrer',
-    'Content-Security-Policy': "default-src 'self'; script-src 'unsafe-inline'; style-src 'unsafe-inline'",
 };
+/**
+ * A fresh CSP nonce for one HTML response, matching Studio's posture: the value
+ * is stamped into both the header and the inline `<script nonce="...">` tag so
+ * script-src drops `unsafe-inline`.
+ */
+function cspNonce() {
+    return randomBytes(16).toString('base64');
+}
+/** Non-document responses render no markup, so no inline script is allowed at all. */
+const JSON_CSP = "default-src 'none'; script-src 'self'; style-src 'self' 'unsafe-inline'; frame-ancestors 'none'";
 function sendJson(res, status, body) {
     const payload = JSON.stringify(body);
-    res.writeHead(status, { ...SECURITY_HEADERS, 'Content-Type': 'application/json' });
+    res.writeHead(status, {
+        ...SECURITY_HEADERS,
+        'Content-Security-Policy': JSON_CSP,
+        'Content-Type': 'application/json',
+    });
     res.end(payload);
 }
-function sendHtml(res, status, html) {
-    res.writeHead(status, { ...SECURITY_HEADERS, 'Content-Type': 'text/html; charset=utf-8' });
-    res.end(html);
+function sendHtml(res, status, html, nonce) {
+    const body = html.replaceAll('__CSP_NONCE__', nonce);
+    res.writeHead(status, {
+        ...SECURITY_HEADERS,
+        // style-src keeps 'unsafe-inline' (the dashboard styles inline, and nonces
+        // do not cover style attributes); script-src moves to the per-request nonce.
+        'Content-Security-Policy': `default-src 'none'; script-src 'self' 'nonce-${nonce}'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self'; font-src 'self'; frame-ancestors 'none'`,
+        'Content-Type': 'text/html; charset=utf-8',
+    });
+    res.end(body);
 }
 function sendText(res, status, text) {
-    res.writeHead(status, { ...SECURITY_HEADERS, 'Content-Type': 'text/plain' });
+    res.writeHead(status, { ...SECURITY_HEADERS, 'Content-Security-Policy': JSON_CSP, 'Content-Type': 'text/plain' });
     res.end(text);
 }
 // ---------------------------------------------------------------------------

package/dist/cli/prisma-report.d.ts

@@ -13,7 +13,21 @@ export interface ReportOptions {
  * Build the full Markdown migration report.
  */
 export declare function formatPrismaReport(result: ResolutionResult, options?: ReportOptions): string;
+/** One resolved many-to-many relation, named from both sides. */
+interface ManyToManyCallSite {
+    /** `Model.field` as written in schema.prisma (what application code says). */
+    prismaPath: string;
+    /** The Prisma field name on its own (what to grep for). */
+    prismaField: string;
+    /** The Turbine relation name (what `generated/metadata.ts` says). */
+    turbineName: string;
+    /** Junction table, when it could be named. */
+    junction?: string;
+}
+/** Every resolved manyToMany relation in the result, in model/field order. */
+export declare function manyToManyCallSites(result: ResolutionResult): ManyToManyCallSite[];
 /** Flat list of unresolved item descriptions across the whole result. */
 export declare function collectUnresolved(result: ResolutionResult): string[];
 /** A one-line-per-model console summary for the CLI. */
 export declare function summaryLines(result: ResolutionResult): string[];
+export {};

package/dist/cli/prisma-report.js

@@ -107,6 +107,8 @@ export function formatPrismaReport(result, options = {}) {
             L.push('');
         }
     }
+    // ---- Many-to-many call sites -----------------------------------------
+    L.push(...manyToManySection(result));
     // ---- Junction tables --------------------------------------------------
     const junctions = new Set();
     for (const m of result.models) {
@@ -156,6 +158,71 @@ export function formatPrismaReport(result, options = {}) {
     L.push(SEMANTIC_DIVERGENCE);
     return `${L.join('\n')}\n`;
 }
+/** Every resolved manyToMany relation in the result, in model/field order. */
+export function manyToManyCallSites(result) {
+    const out = [];
+    for (const m of result.models) {
+        for (const r of m.relations) {
+            if (r.status !== 'resolved' || !r.turbineName)
+                continue;
+            if (!r.manyToMany && !r.junction)
+                continue;
+            out.push({
+                prismaPath: `${m.prismaName}.${r.prismaName}`,
+                prismaField: r.prismaName,
+                turbineName: r.turbineName,
+                junction: r.junction,
+            });
+        }
+    }
+    return out;
+}
+/**
+ * The many-to-many audit section.
+ *
+ * A migration audit that greps the TURBINE relation names cannot find anything:
+ * application code written against the compat client uses the PRISMA field
+ * names, and the two are related only through `PRISMA_MAP`. That is true of
+ * every compat integration, so the report resolves the pairing itself rather
+ * than leaving it to a recipe the reader has to get right.
+ */
+function manyToManySection(result) {
+    const sites = manyToManyCallSites(result);
+    if (sites.length === 0) {
+        if (!result.noDb)
+            return [];
+        return [
+            '## Many-to-many relations (audit these call sites)',
+            '',
+            'Not determined: many-to-many relations are recognized from the live database.',
+            'Re-run without `--no-db` to get the audit list.',
+            '',
+        ];
+    }
+    const L = [];
+    L.push('## Many-to-many relations (audit these call sites)');
+    L.push('');
+    L.push('Turbine and Prisma name these relations differently, and your application code');
+    L.push('uses the PRISMA name. Grepping the Turbine relation name (for example');
+    L.push('`grep -rn "manyToMany" generated/`, then searching for the names it prints) finds');
+    L.push('nothing and silently reports a clean audit. Both names are paired below.');
+    L.push('');
+    L.push('| Prisma call site | Turbine relation | Junction table |');
+    L.push('| --- | --- | --- |');
+    for (const s of sites) {
+        L.push(`| \`${s.prismaPath}\` | \`${s.turbineName}\` | ${s.junction ? `\`${s.junction}\`` : '-'} |`);
+    }
+    L.push('');
+    L.push('Audit every write whose `data` nests one of the Prisma field names above');
+    L.push('(`connect`, `disconnect`, `set`, `connectOrCreate`, `create`, `update`, `upsert`,');
+    L.push('`delete`): those are the many-to-many writes in your codebase.');
+    L.push('');
+    L.push('```bash');
+    L.push(`grep -rEn "\\b(${[...new Set(sites.map((s) => s.prismaField))].sort().join('|')})\\b" src`);
+    L.push('```');
+    L.push('');
+    return L;
+}
 /** Flat list of unresolved item descriptions across the whole result. */
 export function collectUnresolved(result) {
     const out = [];
@@ -195,6 +262,11 @@ phase-2 \`turbine-orm/prisma-compat\` adapter handles most of these translations
 - Aggregate / groupBy \`_count\`. Prisma returns \`_count\` as a record
   (\`{ _all: n }\` / per-field counts). Turbine's scalar \`_count: true\` returns a
   number. Reshape as needed (the phase-2 adapter does this both directions).
+- Paginated reads. Prisma appends an implicit \`ORDER BY <primary key> ASC\` to a
+  \`findMany\` with \`take\`/\`skip\`; core Turbine emits a bare \`LIMIT\`, which is not
+  deterministic (a row can appear on two pages or on none). The phase-2
+  \`prisma-compat\` adapter restores Prisma's ordering; on the core client, pass an
+  explicit \`orderBy\` or set \`implicitPkOrdering: true\`.
 - Relation-array order. Without an \`orderBy\` on a \`with\`/\`include\` clause, the
   order of a to-many relation array is unspecified in Turbine (\`json_agg\` order).
   Add an explicit \`orderBy\` where order matters.

package/dist/cli/prisma-resolve.d.ts

@@ -34,6 +34,12 @@ export interface ResolvedRelation {
     targetModel: string;
     /** Junction table for an m2m relation, if resolved. */
     junction?: string;
+    /**
+     * True when the resolved Turbine relation is `manyToMany`. Distinct from
+     * {@link ResolvedRelation.junction}, which is absent when the junction table
+     * itself could not be named.
+     */
+    manyToMany?: boolean;
     status: ResolveStatus;
     reason?: string;
 }

package/dist/cli/prisma-resolve.js

@@ -341,6 +341,7 @@ function resolveRelation(model, fieldName, targetModelName, isList, modelTable,
             turbineName: def.name,
             cardinality,
             junction: def.type === 'manyToMany' ? def.through?.table : undefined,
+            manyToMany: def.type === 'manyToMany' ? true : undefined,
             status: 'resolved',
         };
     }