tina4-nodejs 3.13.96 → 3.13.97

package/CLAUDE.md

@@ -1,10 +1,10 @@
-# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.95)
+# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.97)
 
 > This file helps AI assistants (Claude, Copilot, Cursor, etc.) understand and work on this codebase effectively.
 
 ## What This Project Is
 
-Tina4 for Node.js/TypeScript v3.13.95 - The Intelligent Native Application 4ramework. A convention-over-configuration structural paradigm. The developer writes TypeScript; Tina4 is invisible infrastructure.
+Tina4 for Node.js/TypeScript v3.13.97 - The Intelligent Native Application 4ramework. A convention-over-configuration structural paradigm. The developer writes TypeScript; Tina4 is invisible infrastructure.
 
 The philosophy: zero ceremony, batteries included, file system as source of truth.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tina4-nodejs",
-  "version": "3.13.96",
+  "version": "3.13.97",
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript - 54 built-in features, zero dependencies",
   "keywords": [

package/packages/cli/dist/bin.js

@@ -17346,10 +17346,17 @@ var init_session = __esm({
        *
        *   session.flash("message", "Saved!")  // set
        *   session.flash("message")            // get + auto-remove → "Saved!"
+       *   session.flash("message", null)      // get + auto-remove (null is a GET sentinel)
+       *
+       * `null` — NOT just `undefined` — is the GET sentinel, so `flash(key, null)`
+       * READS and clears rather than STORING null. This matches the Python master
+       * (`if value is not None`), PHP (`if ($value !== null)`) and Ruby
+       * (`if value.nil?`): passing the language's "no value" literal means GET. A
+       * caller wanting to persist an explicit null should store it with `set()`.
        */
       flash(key, value) {
         const flashKey = `${FLASH_PREFIX}${key}`;
-        if (value !== void 0) {
+        if (value !== void 0 && value !== null) {
           this.set(flashKey, value);
           return void 0;
         }
@@ -39205,16 +39212,8 @@ var init_rabbitmqBackend = __esm({
             process.stdout.write(String(msgCount));
             closeConnection();
           }
-          else if (operation === "purge") {
-            // Queue.Purge
-            const qBuf = Buffer.from(queueName, "utf-8");
-            const purgePayload = Buffer.alloc(4 + qBuf.length);
-            purgePayload.writeUInt16BE(0, 0);
-            purgePayload.writeUInt8(qBuf.length, 2);
-            qBuf.copy(purgePayload, 3);
-            purgePayload.writeUInt8(0, 3 + qBuf.length); // no-wait=false
-            sendMethod(1, 50, 30, purgePayload);
-          }
+          // No "purge" operation: clear()/purge() refuse by name (ADR-0022),
+          // so nothing ever sends Queue.Purge and the drain path is gone.
         }
         else if (classId === 60 && methodId === 71) {
           // Basic.Get-Ok \u2014 message body will follow in content frames
@@ -39225,11 +39224,6 @@ var init_rabbitmqBackend = __esm({
           process.stdout.write("__EMPTY__");
           closeConnection();
         }
-        else if (classId === 50 && methodId === 31) {
-          // Queue.Purge-Ok
-          process.stdout.write("__PURGED__");
-          closeConnection();
-        }
         else if (classId === 10 && methodId === 50) {
           // Connection.Close (server-initiated, e.g. a channel/protocol error)
           // \u2192 send Connection.Close-Ok and exit non-zero so the caller sees the
@@ -39359,8 +39353,15 @@ var init_rabbitmqBackend = __esm({
         const num = parseInt(result, 10);
         return isNaN(num) ? 0 : num;
       }
-      clear(queue) {
-        this.execSync("purge", queue);
+      clear(_queue) {
+        throw new Error(
+          "The rabbitmq queue backend cannot perform clear(): RabbitMQ cannot address messages by status (basic.get pops the head of the queue), so a status-addressed clear would have to drain the entire live queue and destroy pending work. Use the file or mongodb backend."
+        );
+      }
+      purge(_queue, _status) {
+        throw new Error(
+          "The rabbitmq queue backend cannot perform purge(): RabbitMQ cannot address messages by status (basic.get pops the head of the queue), so a status-addressed purge would have to drain the entire live queue and destroy pending work. Use the file or mongodb backend."
+        );
       }
     };
   }
@@ -39922,6 +39923,14 @@ var init_kafkaBackend = __esm({
         return 0;
       }
       clear(_queue) {
+        throw new Error(
+          "The kafka queue backend cannot perform clear(): Kafka has no notion of job status and cannot delete records on demand. A log is read in offset order and records leave only by retention. Use the file or mongodb backend."
+        );
+      }
+      purge(_queue, _status) {
+        throw new Error(
+          "The kafka queue backend cannot perform purge(): Kafka has no notion of job status to purge by. A log is read in offset order and records leave only by retention. Use the file or mongodb backend."
+        );
       }
     };
   }

package/packages/core/dist/index.js

@@ -17345,10 +17345,17 @@ var init_session = __esm({
        *
        *   session.flash("message", "Saved!")  // set
        *   session.flash("message")            // get + auto-remove → "Saved!"
+       *   session.flash("message", null)      // get + auto-remove (null is a GET sentinel)
+       *
+       * `null` — NOT just `undefined` — is the GET sentinel, so `flash(key, null)`
+       * READS and clears rather than STORING null. This matches the Python master
+       * (`if value is not None`), PHP (`if ($value !== null)`) and Ruby
+       * (`if value.nil?`): passing the language's "no value" literal means GET. A
+       * caller wanting to persist an explicit null should store it with `set()`.
        */
       flash(key, value) {
         const flashKey = `${FLASH_PREFIX}${key}`;
-        if (value !== void 0) {
+        if (value !== void 0 && value !== null) {
           this.set(flashKey, value);
           return void 0;
         }
@@ -39176,16 +39183,8 @@ var init_rabbitmqBackend = __esm({
             process.stdout.write(String(msgCount));
             closeConnection();
           }
-          else if (operation === "purge") {
-            // Queue.Purge
-            const qBuf = Buffer.from(queueName, "utf-8");
-            const purgePayload = Buffer.alloc(4 + qBuf.length);
-            purgePayload.writeUInt16BE(0, 0);
-            purgePayload.writeUInt8(qBuf.length, 2);
-            qBuf.copy(purgePayload, 3);
-            purgePayload.writeUInt8(0, 3 + qBuf.length); // no-wait=false
-            sendMethod(1, 50, 30, purgePayload);
-          }
+          // No "purge" operation: clear()/purge() refuse by name (ADR-0022),
+          // so nothing ever sends Queue.Purge and the drain path is gone.
         }
         else if (classId === 60 && methodId === 71) {
           // Basic.Get-Ok \u2014 message body will follow in content frames
@@ -39196,11 +39195,6 @@ var init_rabbitmqBackend = __esm({
           process.stdout.write("__EMPTY__");
           closeConnection();
         }
-        else if (classId === 50 && methodId === 31) {
-          // Queue.Purge-Ok
-          process.stdout.write("__PURGED__");
-          closeConnection();
-        }
         else if (classId === 10 && methodId === 50) {
           // Connection.Close (server-initiated, e.g. a channel/protocol error)
           // \u2192 send Connection.Close-Ok and exit non-zero so the caller sees the
@@ -39330,8 +39324,15 @@ var init_rabbitmqBackend = __esm({
         const num = parseInt(result, 10);
         return isNaN(num) ? 0 : num;
       }
-      clear(queue) {
-        this.execSync("purge", queue);
+      clear(_queue) {
+        throw new Error(
+          "The rabbitmq queue backend cannot perform clear(): RabbitMQ cannot address messages by status (basic.get pops the head of the queue), so a status-addressed clear would have to drain the entire live queue and destroy pending work. Use the file or mongodb backend."
+        );
+      }
+      purge(_queue, _status) {
+        throw new Error(
+          "The rabbitmq queue backend cannot perform purge(): RabbitMQ cannot address messages by status (basic.get pops the head of the queue), so a status-addressed purge would have to drain the entire live queue and destroy pending work. Use the file or mongodb backend."
+        );
       }
     };
   }
@@ -39893,6 +39894,14 @@ var init_kafkaBackend = __esm({
         return 0;
       }
       clear(_queue) {
+        throw new Error(
+          "The kafka queue backend cannot perform clear(): Kafka has no notion of job status and cannot delete records on demand. A log is read in offset order and records leave only by retention. Use the file or mongodb backend."
+        );
+      }
+      purge(_queue, _status) {
+        throw new Error(
+          "The kafka queue backend cannot perform purge(): Kafka has no notion of job status to purge by. A log is read in offset order and records leave only by retention. Use the file or mongodb backend."
+        );
       }
     };
   }

package/packages/core/src/queueBackends/kafkaBackend.ts

@@ -697,7 +697,28 @@ export class KafkaBackend implements QueueBackend {
   }
 
   clear(_queue: string): void {
-    // Kafka topics are cleared via retention policies, not purging
-    // This is a no-op for Kafka
+    // Not performable on Kafka - throws naming the backend and the operation.
+    // clear() empties the queue, but a Kafka log cannot delete records on
+    // demand: a partition is read in offset order and records leave only by
+    // retention. This used to be a silent no-op, which claimed the queue was
+    // emptied when it was untouched (ADR-0022 invariant 6). PHP, Python and
+    // Ruby already refuse by name; this brings the Node backend class in line.
+    throw new Error(
+      "The kafka queue backend cannot perform clear(): Kafka has no notion of " +
+        "job status and cannot delete records on demand. A log is read in " +
+        "offset order and records leave only by retention. Use the file or " +
+        "mongodb backend.",
+    );
+  }
+
+  purge(_queue: string, _status?: string): number {
+    // Not performable on Kafka - throws naming the backend and the operation.
+    // purge(status) removes jobs SELECTED BY STATUS; a Kafka log has no notion
+    // of status to purge by. Refusing by name is the honest answer.
+    throw new Error(
+      "The kafka queue backend cannot perform purge(): Kafka has no notion of " +
+        "job status to purge by. A log is read in offset order and records " +
+        "leave only by retention. Use the file or mongodb backend.",
+    );
   }
 }

package/packages/core/src/queueBackends/rabbitmqBackend.ts

@@ -471,16 +471,8 @@ export class RabbitMQBackend implements QueueBackend {
             process.stdout.write(String(msgCount));
             closeConnection();
           }
-          else if (operation === "purge") {
-            // Queue.Purge
-            const qBuf = Buffer.from(queueName, "utf-8");
-            const purgePayload = Buffer.alloc(4 + qBuf.length);
-            purgePayload.writeUInt16BE(0, 0);
-            purgePayload.writeUInt8(qBuf.length, 2);
-            qBuf.copy(purgePayload, 3);
-            purgePayload.writeUInt8(0, 3 + qBuf.length); // no-wait=false
-            sendMethod(1, 50, 30, purgePayload);
-          }
+          // No "purge" operation: clear()/purge() refuse by name (ADR-0022),
+          // so nothing ever sends Queue.Purge and the drain path is gone.
         }
         else if (classId === 60 && methodId === 71) {
           // Basic.Get-Ok — message body will follow in content frames
@@ -491,11 +483,6 @@ export class RabbitMQBackend implements QueueBackend {
           process.stdout.write("__EMPTY__");
           closeConnection();
         }
-        else if (classId === 50 && methodId === 31) {
-          // Queue.Purge-Ok
-          process.stdout.write("__PURGED__");
-          closeConnection();
-        }
         else if (classId === 10 && methodId === 50) {
           // Connection.Close (server-initiated, e.g. a channel/protocol error)
           // → send Connection.Close-Ok and exit non-zero so the caller sees the
@@ -633,7 +620,32 @@ export class RabbitMQBackend implements QueueBackend {
     return isNaN(num) ? 0 : num;
   }
 
-  clear(queue: string): void {
-    this.execSync("purge", queue);
+  clear(_queue: string): void {
+    // Not performable on RabbitMQ - throws naming the backend and the operation.
+    // clear() empties the queue, but RabbitMQ cannot address messages by status;
+    // the only thing it could do is queue.purge the WHOLE live queue. This used
+    // to do exactly that (execSync("purge", queue)), silently destroying every
+    // pending job. Draining a live broker on a status-addressed clear is data
+    // loss (ADR-0022 invariant 6), so it refuses by name instead. PHP, Python
+    // and Ruby already refuse; this brings the Node backend class in line.
+    throw new Error(
+      "The rabbitmq queue backend cannot perform clear(): RabbitMQ cannot " +
+        "address messages by status (basic.get pops the head of the queue), so " +
+        "a status-addressed clear would have to drain the entire live queue and " +
+        "destroy pending work. Use the file or mongodb backend.",
+    );
+  }
+
+  purge(_queue: string, _status?: string): number {
+    // Not performable on RabbitMQ - throws naming the backend and the operation.
+    // purge(status) removes jobs SELECTED BY STATUS; RabbitMQ has no status
+    // concept and could only drain the whole live queue. Refusing by name is
+    // the honest answer.
+    throw new Error(
+      "The rabbitmq queue backend cannot perform purge(): RabbitMQ cannot " +
+        "address messages by status (basic.get pops the head of the queue), so " +
+        "a status-addressed purge would have to drain the entire live queue and " +
+        "destroy pending work. Use the file or mongodb backend.",
+    );
   }
 }

package/packages/core/src/session.ts

@@ -711,10 +711,17 @@ export class Session {
    *
    *   session.flash("message", "Saved!")  // set
    *   session.flash("message")            // get + auto-remove → "Saved!"
+   *   session.flash("message", null)      // get + auto-remove (null is a GET sentinel)
+   *
+   * `null` — NOT just `undefined` — is the GET sentinel, so `flash(key, null)`
+   * READS and clears rather than STORING null. This matches the Python master
+   * (`if value is not None`), PHP (`if ($value !== null)`) and Ruby
+   * (`if value.nil?`): passing the language's "no value" literal means GET. A
+   * caller wanting to persist an explicit null should store it with `set()`.
    */
   flash(key: string, value?: unknown): unknown {
     const flashKey = `${FLASH_PREFIX}${key}`;
-    if (value !== undefined) {
+    if (value !== undefined && value !== null) {
       // Set mode
       this.set(flashKey, value);
       return undefined;

package/packages/orm/dist/index.js

@@ -7257,10 +7257,17 @@ var init_session = __esm({
        *
        *   session.flash("message", "Saved!")  // set
        *   session.flash("message")            // get + auto-remove → "Saved!"
+       *   session.flash("message", null)      // get + auto-remove (null is a GET sentinel)
+       *
+       * `null` — NOT just `undefined` — is the GET sentinel, so `flash(key, null)`
+       * READS and clears rather than STORING null. This matches the Python master
+       * (`if value is not None`), PHP (`if ($value !== null)`) and Ruby
+       * (`if value.nil?`): passing the language's "no value" literal means GET. A
+       * caller wanting to persist an explicit null should store it with `set()`.
        */
       flash(key, value) {
         const flashKey = `${FLASH_PREFIX}${key}`;
-        if (value !== void 0) {
+        if (value !== void 0 && value !== null) {
           this.set(flashKey, value);
           return void 0;
         }
@@ -29556,16 +29563,8 @@ var init_rabbitmqBackend = __esm({
             process.stdout.write(String(msgCount));
             closeConnection();
           }
-          else if (operation === "purge") {
-            // Queue.Purge
-            const qBuf = Buffer.from(queueName, "utf-8");
-            const purgePayload = Buffer.alloc(4 + qBuf.length);
-            purgePayload.writeUInt16BE(0, 0);
-            purgePayload.writeUInt8(qBuf.length, 2);
-            qBuf.copy(purgePayload, 3);
-            purgePayload.writeUInt8(0, 3 + qBuf.length); // no-wait=false
-            sendMethod(1, 50, 30, purgePayload);
-          }
+          // No "purge" operation: clear()/purge() refuse by name (ADR-0022),
+          // so nothing ever sends Queue.Purge and the drain path is gone.
         }
         else if (classId === 60 && methodId === 71) {
           // Basic.Get-Ok \u2014 message body will follow in content frames
@@ -29576,11 +29575,6 @@ var init_rabbitmqBackend = __esm({
           process.stdout.write("__EMPTY__");
           closeConnection();
         }
-        else if (classId === 50 && methodId === 31) {
-          // Queue.Purge-Ok
-          process.stdout.write("__PURGED__");
-          closeConnection();
-        }
         else if (classId === 10 && methodId === 50) {
           // Connection.Close (server-initiated, e.g. a channel/protocol error)
           // \u2192 send Connection.Close-Ok and exit non-zero so the caller sees the
@@ -29710,8 +29704,15 @@ var init_rabbitmqBackend = __esm({
         const num = parseInt(result, 10);
         return isNaN(num) ? 0 : num;
       }
-      clear(queue) {
-        this.execSync("purge", queue);
+      clear(_queue) {
+        throw new Error(
+          "The rabbitmq queue backend cannot perform clear(): RabbitMQ cannot address messages by status (basic.get pops the head of the queue), so a status-addressed clear would have to drain the entire live queue and destroy pending work. Use the file or mongodb backend."
+        );
+      }
+      purge(_queue, _status) {
+        throw new Error(
+          "The rabbitmq queue backend cannot perform purge(): RabbitMQ cannot address messages by status (basic.get pops the head of the queue), so a status-addressed purge would have to drain the entire live queue and destroy pending work. Use the file or mongodb backend."
+        );
       }
     };
   }
@@ -30273,6 +30274,14 @@ var init_kafkaBackend = __esm({
         return 0;
       }
       clear(_queue) {
+        throw new Error(
+          "The kafka queue backend cannot perform clear(): Kafka has no notion of job status and cannot delete records on demand. A log is read in offset order and records leave only by retention. Use the file or mongodb backend."
+        );
+      }
+      purge(_queue, _status) {
+        throw new Error(
+          "The kafka queue backend cannot perform purge(): Kafka has no notion of job status to purge by. A log is read in offset order and records leave only by retention. Use the file or mongodb backend."
+        );
       }
     };
   }

package/types/core/src/queueBackends/kafkaBackend.d.ts

@@ -114,4 +114,5 @@ export declare class KafkaBackend implements QueueBackend {
     pop(queue: string): QueueJob | null;
     size(_queue: string): number;
     clear(_queue: string): void;
+    purge(_queue: string, _status?: string): number;
 }

package/types/core/src/queueBackends/rabbitmqBackend.d.ts

@@ -51,5 +51,6 @@ export declare class RabbitMQBackend implements QueueBackend {
     push(queue: string, payload: unknown, _delay?: number): string;
     pop(queue: string): QueueJob | null;
     size(queue: string): number;
-    clear(queue: string): void;
+    clear(_queue: string): void;
+    purge(_queue: string, _status?: string): number;
 }

package/types/core/src/session.d.ts

@@ -233,6 +233,13 @@ export declare class Session {
      *
      *   session.flash("message", "Saved!")  // set
      *   session.flash("message")            // get + auto-remove → "Saved!"
+     *   session.flash("message", null)      // get + auto-remove (null is a GET sentinel)
+     *
+     * `null` — NOT just `undefined` — is the GET sentinel, so `flash(key, null)`
+     * READS and clears rather than STORING null. This matches the Python master
+     * (`if value is not None`), PHP (`if ($value !== null)`) and Ruby
+     * (`if value.nil?`): passing the language's "no value" literal means GET. A
+     * caller wanting to persist an explicit null should store it with `set()`.
      */
     flash(key: string, value?: unknown): unknown;
     /**