@tangen/db 0.1.59 → 0.1.60

package/drizzle/0062_revision_correlation.sql

@@ -0,0 +1,26 @@
+-- P5: durable operation correlation, and the hold that protects its evidence.
+--
+-- `correlation_id` is NULLABLE on purpose: every existing writer keeps working
+-- and records nothing, so the column is additive and separately revertible.
+-- The lookup scope is (workspace_id, object_id, correlation_id) - the scope a
+-- recovery scan asks in - which is what the index serves.
+ALTER TABLE "_revisions" ADD COLUMN IF NOT EXISTS "correlation_id" text;
+CREATE INDEX IF NOT EXISTS "revisions_correlation" ON "_revisions" ("workspace_id", "object_id", "correlation_id");
+
+-- The hold is GENERIC: it knows a correlation id and an expiry, and nothing
+-- about who took it or why. Retention joins THIS table, never an extension's
+-- own ledger, so core carries no dependency on an extension's schema.
+--
+-- A hold is scoped by workspace AND object, so one workspace's hold cannot
+-- protect another's revision. `expires_at` is what bounds growth: an expired
+-- hold does not protect, and the sweeper reclaims the row.
+CREATE TABLE IF NOT EXISTS "revision_holds" (
+  "workspace_id"   text NOT NULL,
+  "object_id"      text NOT NULL,
+  "correlation_id" text NOT NULL,
+  "holder"         text NOT NULL,
+  "expires_at"     timestamptz NOT NULL,
+  "created_at"     timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY ("workspace_id", "object_id", "correlation_id")
+);
+CREATE INDEX IF NOT EXISTS "revision_holds_expiry" ON "revision_holds" ("expires_at");

package/drizzle/meta/_journal.json

@@ -428,6 +428,13 @@
       "when": 1787500380000,
       "tag": "0061_object_type_path",
       "breakpoints": true
+    },
+    {
+      "idx": 61,
+      "version": "6",
+      "when": 1787500440000,
+      "tag": "0062_revision_correlation",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangen/db",
-  "version": "0.1.59",
+  "version": "0.1.60",
   "description": "Database client and system schema (Drizzle + postgres.js) for the Tangen headless CMS",
   "homepage": "https://github.com/raghunathj/tangen#readme",
   "bugs": {
@@ -79,7 +79,7 @@
   "dependencies": {
     "drizzle-orm": "^0.45.2",
     "postgres": "^3.4.4",
-    "@tangen/types": "^0.6.1"
+    "@tangen/types": "^0.6.3"
   },
   "devDependencies": {
     "drizzle-kit": "^0.31.11"

package/src/content-ddl.ts

@@ -33,7 +33,16 @@ export function contentTableDdl(tableName: string, fieldColsSql: string): string
           updated_by TEXT,
           created_by_kind TEXT,
           updated_by_kind TEXT,
-          published_by_kind TEXT${fieldColsSql ? ',\n    ' + fieldColsSql : ''},
+          published_by_kind TEXT,
+          -- P1: the row's semantic version. Written by a trigger, never by a
+          -- caller, so a conditional write is decidable and no writer - not a
+          -- buggy one, not a direct SQL session - can set it backwards.
+          version BIGINT NOT NULL DEFAULT 1,
+          -- P1: the second of the two numbers. It counts only changes to the
+          -- CONTAINER KEY SET of the row, which is what can orphan a locale
+          -- overlay. A translator holds this one, so a base title edit does
+          -- not refuse their write and a removed block does.
+          structure_version BIGINT NOT NULL DEFAULT 1${fieldColsSql ? ',\n    ' + fieldColsSql : ''},
           PRIMARY KEY (id)
         )
       `
@@ -48,6 +57,10 @@ export function i18nTableDdl(tableName: string): string {
         locale TEXT NOT NULL,
         "__title" TEXT,
         updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+        -- P1: this locale's own version, maintained by tangen_bump_locale_version.
+        -- One number per locale row, so two translators in two languages never
+        -- refuse each other.
+        version BIGINT NOT NULL DEFAULT 1,
         PRIMARY KEY (object_id, locale)
       )
     `
@@ -68,3 +81,131 @@ export function pkeyColumnsQuery(tableName: string): string {
     GROUP BY c.conname
   `
 }
+
+/**
+ * P1: the version trigger.
+ *
+ * ONE function per database, then one trigger per content table. `BEFORE
+ * UPDATE`, so the new value is visible to `RETURNING` in the same statement
+ * that performs the conditional write.
+ *
+ * IT DECIDES FOR ITSELF WHETHER THE WRITE WAS SEMANTIC.
+ *
+ * The first version took a transaction-local setting - the caller declared
+ * "this is metadata only" and the trigger believed it. That is not an
+ * authorization boundary: `SET LOCAL tangen.metadata_only = 'on'` is
+ * available to any session that can issue SQL, so a semantic write could
+ * decline to advance the version simply by saying so, which is precisely
+ * the lost update the version exists to prevent.
+ *
+ * So the trigger compares the row instead. Everything except the bookkeeping
+ * columns below is semantic, and ANY change to it advances the version; a
+ * write that touches only bookkeeping does not. No caller is consulted and
+ * none can opt out, which is what makes it enforcement rather than a
+ * convention.
+ *
+ * The exclusion list is deliberately short. `status` and the `published_*`
+ * columns are NOT on it: publishing changes what a visitor sees, so it is
+ * semantic. Over-advancing costs a stale editor one reload; under-advancing
+ * loses an edit, so the asymmetry decides the doubtful cases.
+ *
+ * TWO NUMBERS, not one. `version` moves on every semantic change; the
+ * structure digest below reduces the row to the set of container `_key`
+ * values it holds, at any depth, so `structure_version` moves only when a
+ * block or repeater row appears or disappears. That is the write which can
+ * orphan a locale overlay, and it is therefore the only base-row change a
+ * translator's precondition has to care about. Editing a block's text, or
+ * the title, leaves the digest alone and leaves every open translation
+ * valid. Reordering leaves it alone too: the keys a locale references all
+ * still exist.
+ */
+
+/** The digest a `structure_version` is decided by: the row's container keys. */
+export const CONTENT_STRUCTURE_DIGEST_SQL = `
+  CREATE OR REPLACE FUNCTION tangen_structure_digest(row_json JSONB) RETURNS TEXT AS $$
+    SELECT md5(coalesce(string_agg(k, ',' ORDER BY k), ''))
+      FROM (SELECT jsonb_array_elements_text(
+              coalesce(jsonb_path_query_array(row_json, '$.**."_key"'), '[]'::jsonb)) AS k) s
+  $$ LANGUAGE sql IMMUTABLE
+`
+
+export const CONTENT_VERSION_FUNCTION_SQL = `
+  CREATE OR REPLACE FUNCTION tangen_bump_content_version() RETURNS trigger AS $$
+  DECLARE
+    bookkeeping text[] := ARRAY['version', 'structure_version', 'updated_at', 'updated_by', 'updated_by_kind'];
+    old_sem jsonb := to_jsonb(OLD) - bookkeeping;
+    new_sem jsonb := to_jsonb(NEW) - bookkeeping;
+  BEGIN
+    IF new_sem IS DISTINCT FROM old_sem THEN
+      NEW.version := OLD.version + 1;
+      NEW.structure_version := OLD.structure_version
+        + CASE WHEN tangen_structure_digest(new_sem) IS DISTINCT FROM tangen_structure_digest(old_sem)
+               THEN 1 ELSE 0 END;
+    ELSE
+      NEW.version := OLD.version;
+      NEW.structure_version := OLD.structure_version;
+    END IF;
+    RETURN NEW;
+  END $$ LANGUAGE plpgsql
+`
+
+/**
+ * P1: the locale row's version.
+ *
+ * A separate function from the content one because an `_i18n` row has no
+ * `structure_version` and assigning to a field a row does not have is a
+ * runtime error in plpgsql, not a no-op. The rule is otherwise identical:
+ * the trigger compares the row and no caller is consulted.
+ */
+export const LOCALE_VERSION_FUNCTION_SQL = `
+  CREATE OR REPLACE FUNCTION tangen_bump_locale_version() RETURNS trigger AS $$
+  DECLARE
+    bookkeeping text[] := ARRAY['version', 'updated_at'];
+  BEGIN
+    IF (to_jsonb(NEW) - bookkeeping) IS DISTINCT FROM (to_jsonb(OLD) - bookkeeping) THEN
+      NEW.version := OLD.version + 1;
+    ELSE
+      NEW.version := OLD.version;
+    END IF;
+    RETURN NEW;
+  END $$ LANGUAGE plpgsql
+`
+
+/**
+ * The trigger for one content table, as TWO statements.
+ *
+ * Not one string with a semicolon in it: a simple or parameterised query
+ * carries a single statement in most drivers, and PGlite refuses the pair.
+ */
+export function contentVersionTriggerSql(tableName: string): string[] {
+  return [
+    `DROP TRIGGER IF EXISTS tangen_version ON "${tableName}"`,
+    `CREATE TRIGGER tangen_version BEFORE UPDATE ON "${tableName}" FOR EACH ROW EXECUTE FUNCTION tangen_bump_content_version()`,
+  ]
+}
+
+/** Does this table already carry the version trigger? */
+export function contentVersionTriggerQuery(tableName: string): string {
+  return `
+    SELECT 1 FROM pg_trigger t
+    JOIN pg_class c ON c.oid = t.tgrelid
+    WHERE c.relname = '${tableName}' AND t.tgname = 'tangen_version' AND NOT t.tgisinternal
+  `
+}
+
+/** The locale-version trigger for one `_i18n` side table, as TWO statements. */
+export function localeVersionTriggerSql(tableName: string): string[] {
+  return [
+    `DROP TRIGGER IF EXISTS tangen_locale_version ON "${tableName}"`,
+    `CREATE TRIGGER tangen_locale_version BEFORE UPDATE ON "${tableName}" FOR EACH ROW EXECUTE FUNCTION tangen_bump_locale_version()`,
+  ]
+}
+
+/** Does this side table already carry the locale-version trigger? */
+export function localeVersionTriggerQuery(tableName: string): string {
+  return `
+    SELECT 1 FROM pg_trigger t
+    JOIN pg_class c ON c.oid = t.tgrelid
+    WHERE c.relname = '${tableName}' AND t.tgname = 'tangen_locale_version' AND NOT t.tgisinternal
+  `
+}

package/src/schema/objects.ts

@@ -9,7 +9,7 @@
  * Dependencies/Notes: drizzle-orm/pg-core; authoritative live content lives in
  *   per-type tables provisioned by `tangen push` — this table only holds snapshots.
  */
-import { pgTable, text, timestamp, jsonb, integer, index, uniqueIndex } from 'drizzle-orm/pg-core'
+import { pgTable, text, timestamp, jsonb, integer, index, uniqueIndex, primaryKey } from 'drizzle-orm/pg-core'
 
 // Immutable point-in-time snapshots used for version history.
 // Authoritative live content lives in per-type tables created by `tangen push`.
@@ -30,9 +30,52 @@ export const revisions = pgTable('_revisions', {
   createdBy: text('created_by'),
   /** The locale this revision captured (K5); null for the base row. */
   locale: text('locale'),
+  /**
+   * P5: the operation this revision came from, as the originator minted it.
+   *
+   * Nullable, which is what makes it backward compatible: every existing
+   * writer keeps working and records nothing. A recovery scan asks
+   * (workspace_id, object_id, correlation_id) - never the row's current
+   * version, which cannot tell "my write never landed" from "my write landed
+   * and three others followed".
+   */
+  correlationId: text('correlation_id'),
 }, (t) => ({
   idxObject: index('revisions_object').on(t.workspaceId, t.objectId, t.createdAt),
+  idxCorrelation: index('revisions_correlation').on(t.workspaceId, t.objectId, t.correlationId),
   // The invariant the allocator relies on: one version number per object, ever.
   // Scope matches the allocation scope (workspace + object, not env).
   uniqObjectVersion: uniqueIndex('_revisions_object_version_uniq').on(t.workspaceId, t.objectId, t.version),
 }))
+
+/**
+ * P5: a durable claim that one correlated operation's evidence must survive
+ * retention.
+ *
+ * `createRevision` trims to `maxVersions` oldest-first, so ten subsequent
+ * writes to the same object erase the revision a recovery scan would have
+ * decided from - minutes on a busy page, not days. A hold is the pin.
+ *
+ * GENERIC by construction: the table knows a correlation id and an expiry.
+ * Retention joins THIS, never an extension's ledger, so core gains no
+ * dependency on an extension's schema and any writer that correlates its
+ * operations gets the same protection.
+ *
+ * The hold is taken BEFORE the content mutation. Taken afterwards it leaves a
+ * window in which a crash loses the protection and the next trim erases the
+ * evidence; taken first it may protect nothing, which costs one row that
+ * expires. That is the cheap direction to be wrong in.
+ */
+export const revisionHolds = pgTable('revision_holds', {
+  workspaceId: text('workspace_id').notNull(),
+  objectId: text('object_id').notNull(),
+  correlationId: text('correlation_id').notNull(),
+  /** Who took it, for diagnosis - never for authority. */
+  holder: text('holder').notNull(),
+  /** An expired hold does not protect, and the sweeper reclaims the row. */
+  expiresAt: timestamp('expires_at', { withTimezone: true }).notNull(),
+  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+}, (t) => ({
+  pk: primaryKey({ columns: [t.workspaceId, t.objectId, t.correlationId] }),
+  idxExpiry: index('revision_holds_expiry').on(t.expiresAt),
+}))