@haikit/postgres 0.3.0 → 0.3.1

package/README.md

@@ -59,6 +59,13 @@ import { sweepOrphans } from "@haikit/postgres";
 await sweepOrphans(pool, { olderThanMs: 24 * 60 * 60 * 1000 });
 ```
 
-Keep `olderThanMs` above your lease TTL. Conversations with a turn in flight are
-skipped regardless. Deleting whole conversations is retention policy, not
-garbage collection, and is left to you.
+A row is swept only when no history references it **and** the turn that wrote
+it can never save again — which is proven by the conversation's lease having
+been issued to someone else since. An expired lease is not enough: a turn slower
+than its TTL keeps running, and if nobody took over, its save still succeeds.
+So `olderThanMs` is a grace period, not a safety bound; no value of it can
+delete a payload a turn is still going to reference.
+
+A turn that crashed leaves its rows until the conversation is next used, since
+only then is a new token issued. Deleting whole conversations is retention
+policy, not garbage collection, and is left to you.

package/dist/index.d.ts

@@ -43,21 +43,27 @@ export declare function migrate(db: Queryable): Promise<void>;
 export declare function pgStore(db: Queryable, options?: PgStoreOptions): StoreAdapter;
 export interface SweepOptions {
     /**
-     * Only sweep rows at least this old. Keep it above your lease TTL: a turn
-     * inserts its payloads before it saves the history that references them, so
-     * a young row can look orphaned while its turn is still running.
+     * Only sweep rows at least this old. A grace period for operators, not a
+     * safety bound: whether a row is an orphan is decided by lease tokens below,
+     * so no value here can delete a payload a turn is still going to reference.
      */
     olderThanMs: number;
 }
 /**
- * Delete orphaned payloads: rows written by a turn that was then overtaken, so
- * the surviving history never recorded their handles. They are inert — an
- * interaction on one is refused — but they are still rows.
+ * Delete orphaned payloads: rows written by a turn that can never save the
+ * history that would reference them.
  *
- * Conversations with a live lease are skipped regardless of age, so an
- * in-flight turn's not-yet-recorded payloads are never touched. Deleting
- * conversations themselves is retention policy, not garbage collection, and is
- * left to you.
+ * A turn inserts its payloads before it saves, so an unreferenced row is not
+ * evidence of anything by itself — the turn may simply not have saved yet. Nor
+ * is an expired lease: a turn slower than its TTL keeps running, and if nobody
+ * took the conversation over, its save still succeeds. The only proof that a
+ * writer is finished is that the conversation's lease has since been issued to
+ * someone else. Every payload records the token its writer held, and a row is
+ * swept only when it is unreferenced *and* that token has been superseded.
+ *
+ * Consequence: a turn that crashed leaves its rows until the conversation is
+ * next used, since only then is a new token issued. That is the safe direction.
+ * Deleting conversations themselves is retention policy, and is left to you.
  */
 export declare function sweepOrphans(db: Queryable, options: SweepOptions): Promise<{
     deleted: number;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAKL,KAAK,YAAY,EAClB,MAAM,cAAc,CAAC;AAEtB;;;;;;;;GAQG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,GAAG,EAAE,CAAA;KAAE,CAAC,CAAC;CACnE;AAED,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAID;;;GAGG;AACH,eAAO,MAAM,MAAM,EAAE,SAAS,MAAM,EA0BnC,CAAC;AAEF,0DAA0D;AAC1D,wBAAsB,OAAO,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAI1D;AAqCD,wBAAgB,OAAO,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,GAAE,cAAmB,GAAG,YAAY,CAkIjF;AAED,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAYrG"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAKL,KAAK,YAAY,EAClB,MAAM,cAAc,CAAC;AAEtB;;;;;;;;GAQG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,GAAG,EAAE,CAAA;KAAE,CAAC,CAAC;CACnE;AAED,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAID;;;GAGG;AACH,eAAO,MAAM,MAAM,EAAE,SAAS,MAAM,EA6BnC,CAAC;AAEF,0DAA0D;AAC1D,wBAAsB,OAAO,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAI1D;AAyCD,wBAAgB,OAAO,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,GAAE,cAAmB,GAAG,YAAY,CAgJjF;AAED,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,YAAY,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAYrG"}

package/dist/index.js

@@ -38,6 +38,9 @@ export const schema = [
      version         integer NOT NULL,
      props           jsonb NOT NULL,
      mode            text NOT NULL,
+     -- the lease the writing turn held. Only a newer token proves that turn can
+     -- never save again, which is what makes an unreferenced row an orphan.
+     lease_token     text NOT NULL,
      created_at      timestamptz NOT NULL DEFAULT now(),
      PRIMARY KEY (conversation_id, handle)
    )`,
@@ -50,14 +53,18 @@ export async function migrate(db) {
     for (const statement of schema)
         await db.query(statement);
 }
+// jsonb is always read as text and parsed here. Drivers disagree on whether
+// they parse jsonb themselves, and guessing from the result's type cannot work:
+// a jsonb string scalar parsed by the driver is a JS string too, and parsing it
+// a second time throws. Taking text every time removes the guess.
 const CONVERSATION_COLUMNS = `
-  id, status, messages, handles, frozen, pending, lease_token,
+  id, status, messages::text AS messages, handles::text AS handles,
+  frozen::text AS frozen, pending::text AS pending, lease_token,
   (extract(epoch FROM lease_until) * 1000)::float8 AS lease_until_ms`;
 const PAYLOAD_COLUMNS = `
-  handle, conversation_id, component, version, props, mode,
+  handle, conversation_id, component, version, props::text AS props, mode,
   (extract(epoch FROM created_at) * 1000)::float8 AS created_at_ms`;
-/** Most drivers parse jsonb into values; a few hand back text. Accept both. */
-const json = (value) => (typeof value === "string" ? JSON.parse(value) : value);
+const json = (text) => JSON.parse(text);
 const toConversation = (row) => ({
     id: row.id,
     status: row.status,
@@ -81,6 +88,13 @@ const newToken = () => globalThis.crypto.randomUUID();
 const newId = () => `conv_${globalThis.crypto.randomUUID().replaceAll("-", "")}`;
 export function pgStore(db, options = {}) {
     const leaseMs = options.leaseMs ?? LEASE_MS;
+    // Zero or negative makes every lease expire the moment it is taken, so every
+    // load acquires and the one-turn-in-flight guarantee silently disappears.
+    // Infinity would strand a crashed turn's conversation forever. Refuse both
+    // here, loudly, rather than run with no mutual exclusion at all.
+    if (!Number.isFinite(leaseMs) || leaseMs <= 0) {
+        throw new RangeError(`leaseMs must be a positive, finite number of milliseconds (got ${leaseMs})`);
+    }
     /** A fenced write matched nothing. Say which of the two reasons applies. */
     async function stale(conversationId) {
         const { rows } = await db.query(`SELECT 1 FROM haikit_conversations WHERE id = $1`, [conversationId]);
@@ -150,14 +164,14 @@ export function pgStore(db, options = {}) {
             const { rows } = await db.query(`WITH owner AS (
            UPDATE haikit_conversations
               SET handle_seq = handle_seq + 1
-            WHERE id = $1::text AND lease_token = $2
+            WHERE id = $1::text AND lease_token = $2::text
             RETURNING handle_seq
          )
-         INSERT INTO haikit_payloads (conversation_id, handle, component, version, props, mode)
+         INSERT INTO haikit_payloads (conversation_id, handle, component, version, props, mode, lease_token)
          SELECT $1::text,
                 -- ui_01 … ui_09, ui_10 … ui_99, ui_100: pad, never truncate
                 'ui_' || CASE WHEN handle_seq < 10 THEN '0' ELSE '' END || handle_seq,
-                $3::text, $4::integer, $5::jsonb, $6::text
+                $3::text, $4::integer, $5::jsonb, $6::text, $2::text
            FROM owner
          RETURNING handle`, [
                 record.conversationId,
@@ -184,27 +198,40 @@ export function pgStore(db, options = {}) {
             const { rows } = await db.query(`SELECT ${PAYLOAD_COLUMNS} FROM haikit_payloads
           WHERE conversation_id = $1
             AND handle IN (SELECT jsonb_array_elements_text($2::jsonb))`, [conversationId, JSON.stringify(handles)]);
-            const order = new Map(handles.map((h, i) => [h, i]));
-            return rows.map(toPayload).sort((a, b) => order.get(a.handle) - order.get(b.handle));
+            // `IN` returns each row once; the contract is one result per input
+            // handle, duplicates and order included — map the input, not the rows.
+            // Each occurrence is a deep copy, as a separate getPayload would be: a
+            // shallow spread would hand two results one shared `props` object.
+            const byHandle = new Map(rows.map((row) => [row.handle, toPayload(row)]));
+            return handles.flatMap((h) => {
+                const record = byHandle.get(h);
+                return record ? [structuredClone(record)] : [];
+            });
         },
     };
 }
 /**
- * Delete orphaned payloads: rows written by a turn that was then overtaken, so
- * the surviving history never recorded their handles. They are inert — an
- * interaction on one is refused — but they are still rows.
+ * Delete orphaned payloads: rows written by a turn that can never save the
+ * history that would reference them.
+ *
+ * A turn inserts its payloads before it saves, so an unreferenced row is not
+ * evidence of anything by itself — the turn may simply not have saved yet. Nor
+ * is an expired lease: a turn slower than its TTL keeps running, and if nobody
+ * took the conversation over, its save still succeeds. The only proof that a
+ * writer is finished is that the conversation's lease has since been issued to
+ * someone else. Every payload records the token its writer held, and a row is
+ * swept only when it is unreferenced *and* that token has been superseded.
  *
- * Conversations with a live lease are skipped regardless of age, so an
- * in-flight turn's not-yet-recorded payloads are never touched. Deleting
- * conversations themselves is retention policy, not garbage collection, and is
- * left to you.
+ * Consequence: a turn that crashed leaves its rows until the conversation is
+ * next used, since only then is a new token issued. That is the safe direction.
+ * Deleting conversations themselves is retention policy, and is left to you.
  */
 export async function sweepOrphans(db, options) {
     const { rows } = await db.query(`DELETE FROM haikit_payloads p
       USING haikit_conversations c
       WHERE p.conversation_id = c.id
         AND p.created_at < now() - $1::float8 * interval '1 millisecond'
-        AND (c.lease_until IS NULL OR c.lease_until <= now())
+        AND p.lease_token IS DISTINCT FROM c.lease_token
         AND NOT (c.handles @> jsonb_build_array(p.handle))
       RETURNING p.handle`, [options.olderThanMs]);
     return { deleted: rows.length };

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haikit/postgres",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Postgres store adapter for haikit: durable conversations, fenced turn leases, write-once payloads. Bring your own driver.",
   "keywords": [
     "haikit",
@@ -34,7 +34,7 @@
     "prepack": "npm --prefix ../.. run build"
   },
   "dependencies": {
-    "@haikit/core": "0.2.0"
+    "@haikit/core": "0.3.1"
   },
   "publishConfig": {
     "access": "public"

package/src/index.ts

@@ -69,6 +69,9 @@ export const schema: readonly string[] = [
      version         integer NOT NULL,
      props           jsonb NOT NULL,
      mode            text NOT NULL,
+     -- the lease the writing turn held. Only a newer token proves that turn can
+     -- never save again, which is what makes an unreferenced row an orphan.
+     lease_token     text NOT NULL,
      created_at      timestamptz NOT NULL DEFAULT now(),
      PRIMARY KEY (conversation_id, handle)
    )`,
@@ -82,16 +85,20 @@ export async function migrate(db: Queryable): Promise<void> {
   for (const statement of schema) await db.query(statement);
 }
 
+// jsonb is always read as text and parsed here. Drivers disagree on whether
+// they parse jsonb themselves, and guessing from the result's type cannot work:
+// a jsonb string scalar parsed by the driver is a JS string too, and parsing it
+// a second time throws. Taking text every time removes the guess.
 const CONVERSATION_COLUMNS = `
-  id, status, messages, handles, frozen, pending, lease_token,
+  id, status, messages::text AS messages, handles::text AS handles,
+  frozen::text AS frozen, pending::text AS pending, lease_token,
   (extract(epoch FROM lease_until) * 1000)::float8 AS lease_until_ms`;
 
 const PAYLOAD_COLUMNS = `
-  handle, conversation_id, component, version, props, mode,
+  handle, conversation_id, component, version, props::text AS props, mode,
   (extract(epoch FROM created_at) * 1000)::float8 AS created_at_ms`;
 
-/** Most drivers parse jsonb into values; a few hand back text. Accept both. */
-const json = (value: unknown) => (typeof value === "string" ? JSON.parse(value) : value);
+const json = (text: string) => JSON.parse(text);
 
 const toConversation = (row: any): Conversation => ({
   id: row.id,
@@ -119,6 +126,13 @@ const newId = () => `conv_${globalThis.crypto.randomUUID().replaceAll("-", "")}`
 
 export function pgStore(db: Queryable, options: PgStoreOptions = {}): StoreAdapter {
   const leaseMs = options.leaseMs ?? LEASE_MS;
+  // Zero or negative makes every lease expire the moment it is taken, so every
+  // load acquires and the one-turn-in-flight guarantee silently disappears.
+  // Infinity would strand a crashed turn's conversation forever. Refuse both
+  // here, loudly, rather than run with no mutual exclusion at all.
+  if (!Number.isFinite(leaseMs) || leaseMs <= 0) {
+    throw new RangeError(`leaseMs must be a positive, finite number of milliseconds (got ${leaseMs})`);
+  }
 
   /** A fenced write matched nothing. Say which of the two reasons applies. */
   async function stale(conversationId: string): Promise<never> {
@@ -201,14 +215,14 @@ export function pgStore(db: Queryable, options: PgStoreOptions = {}): StoreAdapt
         `WITH owner AS (
            UPDATE haikit_conversations
               SET handle_seq = handle_seq + 1
-            WHERE id = $1::text AND lease_token = $2
+            WHERE id = $1::text AND lease_token = $2::text
             RETURNING handle_seq
          )
-         INSERT INTO haikit_payloads (conversation_id, handle, component, version, props, mode)
+         INSERT INTO haikit_payloads (conversation_id, handle, component, version, props, mode, lease_token)
          SELECT $1::text,
                 -- ui_01 … ui_09, ui_10 … ui_99, ui_100: pad, never truncate
                 'ui_' || CASE WHEN handle_seq < 10 THEN '0' ELSE '' END || handle_seq,
-                $3::text, $4::integer, $5::jsonb, $6::text
+                $3::text, $4::integer, $5::jsonb, $6::text, $2::text
            FROM owner
          RETURNING handle`,
         [
@@ -243,30 +257,43 @@ export function pgStore(db: Queryable, options: PgStoreOptions = {}): StoreAdapt
             AND handle IN (SELECT jsonb_array_elements_text($2::jsonb))`,
         [conversationId, JSON.stringify(handles)],
       );
-      const order = new Map(handles.map((h, i) => [h, i] as const));
-      return rows.map(toPayload).sort((a, b) => order.get(a.handle)! - order.get(b.handle)!);
+      // `IN` returns each row once; the contract is one result per input
+      // handle, duplicates and order included — map the input, not the rows.
+      // Each occurrence is a deep copy, as a separate getPayload would be: a
+      // shallow spread would hand two results one shared `props` object.
+      const byHandle = new Map(rows.map((row) => [row.handle, toPayload(row)] as const));
+      return handles.flatMap((h) => {
+        const record = byHandle.get(h);
+        return record ? [structuredClone(record)] : [];
+      });
     },
   };
 }
 
 export interface SweepOptions {
   /**
-   * Only sweep rows at least this old. Keep it above your lease TTL: a turn
-   * inserts its payloads before it saves the history that references them, so
-   * a young row can look orphaned while its turn is still running.
+   * Only sweep rows at least this old. A grace period for operators, not a
+   * safety bound: whether a row is an orphan is decided by lease tokens below,
+   * so no value here can delete a payload a turn is still going to reference.
    */
   olderThanMs: number;
 }
 
 /**
- * Delete orphaned payloads: rows written by a turn that was then overtaken, so
- * the surviving history never recorded their handles. They are inert — an
- * interaction on one is refused — but they are still rows.
+ * Delete orphaned payloads: rows written by a turn that can never save the
+ * history that would reference them.
+ *
+ * A turn inserts its payloads before it saves, so an unreferenced row is not
+ * evidence of anything by itself — the turn may simply not have saved yet. Nor
+ * is an expired lease: a turn slower than its TTL keeps running, and if nobody
+ * took the conversation over, its save still succeeds. The only proof that a
+ * writer is finished is that the conversation's lease has since been issued to
+ * someone else. Every payload records the token its writer held, and a row is
+ * swept only when it is unreferenced *and* that token has been superseded.
  *
- * Conversations with a live lease are skipped regardless of age, so an
- * in-flight turn's not-yet-recorded payloads are never touched. Deleting
- * conversations themselves is retention policy, not garbage collection, and is
- * left to you.
+ * Consequence: a turn that crashed leaves its rows until the conversation is
+ * next used, since only then is a new token issued. That is the safe direction.
+ * Deleting conversations themselves is retention policy, and is left to you.
  */
 export async function sweepOrphans(db: Queryable, options: SweepOptions): Promise<{ deleted: number }> {
   const { rows } = await db.query(
@@ -274,7 +301,7 @@ export async function sweepOrphans(db: Queryable, options: SweepOptions): Promis
       USING haikit_conversations c
       WHERE p.conversation_id = c.id
         AND p.created_at < now() - $1::float8 * interval '1 millisecond'
-        AND (c.lease_until IS NULL OR c.lease_until <= now())
+        AND p.lease_token IS DISTINCT FROM c.lease_token
         AND NOT (c.handles @> jsonb_build_array(p.handle))
       RETURNING p.handle`,
     [options.olderThanMs],