jinaga-server 3.5.4 → 3.5.5

package/.github/workflows/publish.yml

@@ -7,14 +7,17 @@ on:
 jobs:
   build:
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
     steps:
       - uses: actions/checkout@v4
-      # Setup .npmrc file to publish to npm
       - uses: actions/setup-node@v4
         with:
           node-version: '20.x'
           registry-url: 'https://registry.npmjs.org'
+      - run: npm install -g npm@latest
       - run: npm install
       - run: npm publish
         env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NODE_AUTH_TOKEN: ''

package/.github/workflows/upgrade-jinaga.yml

@@ -0,0 +1,51 @@
+name: Upgrade jinaga
+
+on:
+  schedule:
+    - cron: '0 6 * * *'   # daily at 06:00 UTC
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  upgrade:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+
+      - name: Get versions
+        id: versions
+        run: |
+          CURRENT=$(node -p "require('./package.json').dependencies.jinaga.replace(/[\^~]/, '')")
+          LATEST=$(npm view jinaga dist-tags.latest)
+          echo "current=$CURRENT" >> "$GITHUB_OUTPUT"
+          echo "latest=$LATEST"   >> "$GITHUB_OUTPUT"
+
+      - name: Update root
+        if: steps.versions.outputs.current != steps.versions.outputs.latest
+        run: npm install jinaga@${{ steps.versions.outputs.latest }}
+
+      - name: Update integration-test
+        if: steps.versions.outputs.current != steps.versions.outputs.latest
+        working-directory: integration-test/jinaga-test
+        run: npm install jinaga@${{ steps.versions.outputs.latest }}
+
+      - name: Open PR
+        if: steps.versions.outputs.current != steps.versions.outputs.latest
+        uses: peter-evans/create-pull-request@v7
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          branch: upgrade/jinaga-${{ steps.versions.outputs.latest }}
+          commit-message: "Upgraded Jinaga to ${{ steps.versions.outputs.latest }}"
+          title: "Upgraded Jinaga to ${{ steps.versions.outputs.latest }}"
+          body: |
+            Automated upgrade of `jinaga` from `${{ steps.versions.outputs.current }}` to `${{ steps.versions.outputs.latest }}`.
+          labels: dependencies
+          delete-branch: true

package/CLAUDE.md

@@ -0,0 +1,77 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+npm run build          # Compile TypeScript to dist/
+npm test               # Type-check + run Jest tests
+npm run test:watch     # Jest in watch mode
+npm run clean          # Remove dist/ and integration-test artifacts
+npm run integration    # Full build + integration tests (requires Postgres)
+npm run debug          # Run debug.ts entry point (configure DB in src/debug.ts first)
+```
+
+Run a single test file:
+```bash
+npx jest test/postgres/postgresReadSpec.ts
+```
+
+Run tests matching a pattern:
+```bash
+npx jest --testNamePattern="should read"
+```
+
+## Architecture
+
+Jinaga Server is a middle-tier backend that syncs immutable facts between clients and PostgreSQL. Facts are append-only records (never mutated), signed by user/device identities, and queried via declarative Specifications rather than SQL.
+
+### Layers (top to bottom)
+
+**HTTP** (`src/http/router.ts`) — Express router with three endpoints:
+- `POST /jinaga/write` — accept FactEnvelopes from clients
+- `POST /jinaga/read` — query facts by Specification
+- `POST /jinaga/feed` — long-lived streaming subscription (`application/x-jinaga-feed-stream`)
+
+**Authentication** (`src/authentication/`) — Associates each request with a user/device identity. `AuthenticationDevice` is for server-local operations; `AuthenticationSession` is for per-request user context.
+
+**Authorization** (`src/authorization/authorization-keystore.ts`) — Enforces who can write facts and who can receive them, using `AuthorizationEngine` and `DistributionEngine` from the `jinaga` core library.
+
+**Core** — `FactManager` from the `jinaga` library handles fact storage coordination. This server implements the `Storage` and `Keystore` interfaces that `FactManager` depends on.
+
+**Storage** (`src/postgres/`, `src/memory/`) — Two implementations:
+- `PostgresStore` + `PostgresKeystore` — production persistence in PostgreSQL
+- `MemoryKeystore` (in-memory) — used in tests and development
+
+### Assembly
+
+`JinagaServer.create(config)` in `src/jinaga-server.ts` wires everything together via dependency injection. It reads the config to determine which storage strategy, fork strategy (pass-through, transient, or persistent for upstream replication), and authorization/distribution rules to use.
+
+### Specification → SQL
+
+The most complex translation in the codebase is in `src/postgres/specification-sql.ts`, which converts a `Specification` object (from the `jinaga` library's query DSL) into SQL JOIN queries. Related: `src/postgres/specification-result-sql.ts` for result projection and `src/postgres/purge-sql.ts` for deletions.
+
+### Feed streaming
+
+`src/http/stream.ts` manages long-lived HTTP connections. When new facts arrive that match a subscription, they're pushed to all connected clients via the queue-based event system.
+
+### Fork strategies
+
+Forks determine how facts propagate upstream:
+- `PassThroughFork` — no upstream, single-server
+- `TransientFork` — in-memory queue (dev/test)
+- `PersistentFork` — `postgres-queue.ts` backed queue for reliable upstream replication to other Jinaga servers
+
+## Key interfaces
+
+- `Storage` (from `jinaga`) — `save()`, `read()`, `feed()`, `remove()`
+- `Keystore` (`src/keystore.ts`) — `getOrCreateUserFact()`, `signFacts()`, etc.
+
+## Database schema
+
+`setup.sql` initializes the schema. Key tables: `fact`, `fact_type`, `role`, `ancestor`, `signature`, `public_key`, `user`, `device`. Facts are immutable once written. The `ancestor` table tracks relationships between facts (predecessor/successor edges).
+
+## Testing
+
+Tests live in `test/` matching pattern `**/test/**/*Spec.ts`. Tests use the in-memory keystore and often the actual `PostgresStore` against a real database for integration-level unit tests. See `test/models/blog.ts` for the canonical test data model.

package/docs/analysis/feed-builder-nested-existential-bug.md

@@ -0,0 +1,191 @@
+# Bug Analysis: Feed Builder Strips Inner Negative Existential Conditions
+
+**Date:** 2026-03-30
+**Area:** `jinaga` package — `feed-builder.js` / `specification-sql.ts`
+**Symptom:** EventName facts not delivered to clients for events that have been deleted and restored
+
+---
+
+## Observed Symptom
+
+The LaunchKings admin portal Events dropdown shows the raw fact hash prefix (e.g. `65bc55e`) instead of the event's human-readable name ("LATAM test"). The `CodeLaunch.Event.Name` fact exists in the database and the distribution rules authorize it, but it is never delivered to the client via feeds.
+
+## Database State That Triggers the Bug
+
+```
+CodeLaunch.Event         1 fact   — id: 65bc55e9-495a-4418-9744-3dea6f8c8f2a
+CodeLaunch.Event.Name    1 fact   — value: "LATAM test"  (EXISTS — not missing)
+CodeLaunch.Event.Delete  2 facts  — deleted twice
+CodeLaunch.Event.Restore 2 facts  — restored twice → event is currently active
+```
+
+The event is logically active (every delete has a matching restore), but its presence of any `EventDelete` facts triggers the bug.
+
+---
+
+## Root Cause
+
+### The Specification
+
+The `eventsListInTenant` specification uses `Event.in(tenant)`:
+
+```typescript
+static in(tenant: LabelOf<Tenant>) {
+    return tenant.successors(Event, event => event.tenant)
+        .notExists(event =>
+            event.successors(EventDelete, d => d.event)
+                .notExists(d =>
+                    d.successors(EventRestore, r => r.eventDelete)
+                )
+        );
+}
+```
+
+The full `!E` condition is:
+```
+!E { EventDelete [ u2->event = u1,  !E { EventRestore [ u3->eventDelete = u2 ] } ] }
+```
+Meaning: *no un-restored EventDelete exists for this event*.
+
+### What `buildFeeds` Produces
+
+`buildFeeds` calls `buildExistentialCondition` to create a simplified version of negative existential conditions for use in feed specifications. The relevant code:
+
+```js
+// feed-builder.js — buildExistentialCondition()
+for (const match of matches) {
+    existentialCondition = {
+        ...existentialCondition,
+        matches: [...existentialCondition.matches, {
+            ...match,
+            conditions: match.conditions.filter(isPathCondition)  // strips ALL existential conditions
+        }]
+    };
+
+    for (const innerExistentialCondition of match.conditions.filter(isExistentialCondition)) {
+        if (innerExistentialCondition.exists) {
+            // ✓ positive inner existentials are recursively included
+        }
+        // ✗ negative inner existentials (exists=false) are silently dropped
+    }
+}
+```
+
+The inner `!E{EventRestore}` condition has `exists=false` and is therefore **dropped**. The simplified condition produced is:
+
+```
+!E { EventDelete [ u2->event = u1 ] }
+```
+Meaning: *no EventDelete at all*.
+
+### The Five Feeds for `eventsListInTenant`
+
+`buildFeeds` produces these feeds:
+
+| Feed | Purpose | Condition on Event |
+|---|---|---|
+| FeedA | Detect EventRestore arrivals | none (bare join) |
+| FeedB | Detect EventDelete arrivals | none (bare join) |
+| FeedC | Deliver Event facts | `!E{EventDelete}` ← simplified |
+| FeedD | Detect EventName supersession | `!E{EventDelete}` ← inherited |
+| FeedE | **Deliver EventName facts** | `!E{EventDelete}` ← **BUG** |
+
+FeedE inherits FeedC's simplified condition via `addProjections(FeedC, ...)`. FeedE's SQL is therefore:
+
+```sql
+SELECT f_name.hash, sort(array[f_name.fact_id], 'desc') as bookmark
+FROM fact f_tenant
+JOIN edge e1 ON e1.predecessor_fact_id = f_tenant.fact_id AND e1.role_id = $event_tenant_role
+JOIN fact f_event ON f_event.fact_id = e1.successor_fact_id
+JOIN edge e2 ON e2.predecessor_fact_id = f_event.fact_id AND e2.role_id = $eventname_event_role
+JOIN fact f_name ON f_name.fact_id = e2.successor_fact_id
+WHERE f_tenant.fact_type_id = $tenant_type AND f_tenant.hash = $tenant_hash
+AND NOT EXISTS (
+    SELECT 1 FROM edge e_del
+    WHERE e_del.predecessor_fact_id = f_event.fact_id
+    AND e_del.role_id = $eventdelete_event_role
+    -- ↑ checks for ANY EventDelete, not just un-restored ones
+)
+AND NOT EXISTS (
+    SELECT 1 FROM edge e_prior
+    WHERE e_prior.predecessor_fact_id = f_name.fact_id
+    AND e_prior.role_id = $eventname_prior_role
+)
+AND sort(array[f_name.fact_id], 'desc') > $bookmark
+ORDER BY bookmark ASC LIMIT 100
+```
+
+Because the "LATAM test" event has `EventDelete` facts (regardless of `EventRestore`), the `NOT EXISTS (EventDelete)` clause is false, the event is excluded, and **the query returns zero rows**.
+
+### Why the Listener Doesn't Rescue It
+
+The observer also registers inverse specification listeners. When FeedA delivers `EventRestore` facts, the listener fires and calls `notifyAdded` — which reads EventName from the **local IndexedDB store**. Because FeedE never delivered EventName to the local store, the re-evaluation finds nothing, and names remain absent.
+
+---
+
+## Impact
+
+Any event that has ever been deleted (even if subsequently restored) will have its name and other projection facts permanently withheld from all projection feeds, while the base `Event` fact itself still appears (for example via FeedC). This affects:
+
+- `CodeLaunch.Event.Name` — event name not shown in nav dropdown
+- `CodeLaunch.Event.Date` — event dates not shown
+- Any other projected facts on events from `eventsListInTenant` or similar specs
+
+In this environment the event was deleted and restored twice, making it the only event and confirming 100% reproduction.
+
+---
+
+## The Fix
+
+### Option A — Support Nested NOT EXISTS in Feed SQL (Correct but Complex)
+
+Extend `buildExistentialCondition` to recursively include negative inner existential conditions:
+
+```js
+// feed-builder.js — buildExistentialCondition()
+for (const innerExistentialCondition of match.conditions.filter(isExistentialCondition)) {
+    if (innerExistentialCondition.exists) {
+        // existing logic — keep positive existentials
+        const { existentialCondition: newEC, ... } = buildExistentialCondition(...);
+        existentialCondition = newEC;
+    } else {
+        // NEW: also recurse into negative existentials
+        const { existentialCondition: newEC, ... } = buildExistentialCondition(
+            innerExistentialCondition, innerExistentialCondition.matches, ...
+        );
+        existentialCondition = { ...existentialCondition, innerConditions: [..., newEC] };
+    }
+}
+```
+
+This also requires:
+1. Adding a `innerConditions` (or `notExistsConditions`) field to `ExistentialConditionDescription`
+2. Updating `generateNotExistsWhereClause` in `specification-sql.ts` to recurse into nested conditions
+3. Updating `notExistsConditionsEqual` in `distribution-engine.ts` if nested conditions need to be compared
+
+### Option B — Omit Outer Not-Exists from Projection Feeds (Simpler)
+
+When `addProjections` builds projection feeds (FeedD, FeedE), start from a version of the specification that **drops all not-exists conditions on the base matches**. Projection feeds would then return facts for all events (active or not), and the full specification read handles the correct filtering.
+
+```js
+// feed-builder.js — buildFeeds()
+const baseFeed = stripNotExistsConditions(finalFeed); // new helper
+const feedsWithProjections = addProjections(baseFeed, unusedGivens, specification.projection.components);
+```
+
+This is safe because:
+- FeedA and FeedB already handle re-evaluation when delete/restore facts arrive
+- The actual filtering is done by `factManager.read()` using the full specification
+- Feeds are designed to be a **superset** of relevant facts; over-delivery is intentional
+
+Option B is simpler, has no SQL changes, and aligns with the documented design principle that "feeds are not executed with nested existential conditions."
+
+---
+
+## Files Involved
+
+| File | Role |
+|---|---|
+| `jinaga/src/specification/feed-builder.ts` | `buildExistentialCondition` — drops inner `!E` conditions |
+| `src/postgres/specification-sql.ts` | `generateNotExistsWhereClause` — only handles flat conditions |
+| `jinaga/src/distribution/distribution-engine.ts` | `notExistsConditionsEqual` — explicitly skips nested comparison |

package/integration-test/jinaga-test/package-lock.json

@@ -14,7 +14,7 @@
         "express": "^4.21.2",
         "jest": "^29.7.0",
         "jest-compact-reporter": "^1.2.9",
-        "jinaga": "^6.7.13",
+        "jinaga": "^6.7.25",
         "node-forge": "^1.3.0",
         "pg": "^8.13.1"
       },
@@ -3195,9 +3195,9 @@
       }
     },
     "node_modules/jinaga": {
-      "version": "6.7.13",
-      "resolved": "https://registry.npmjs.org/jinaga/-/jinaga-6.7.13.tgz",
-      "integrity": "sha512-WhSg3bWvUr1WnC4lnpzswJIZ45bMWxRlKXlEhOsofI86jXJSH7tHUqXWKZ9UJihc5/8iGxJUnM65zWZmPa+aFA==",
+      "version": "6.7.25",
+      "resolved": "https://registry.npmjs.org/jinaga/-/jinaga-6.7.25.tgz",
+      "integrity": "sha512-J+9KjHYdDkemO5xTau20P+NV1p2DMFodFwE/ulBFTYLA+4jG7YFOxEYN9n6Irn0Wv3itz5PvRUMpVEmzovj2Hw==",
       "license": "MIT",
       "dependencies": {
         "@stablelib/base64": "^1.0.1",

package/integration-test/jinaga-test/package.json

@@ -18,7 +18,7 @@
     "express": "^4.21.2",
     "jest": "^29.7.0",
     "jest-compact-reporter": "^1.2.9",
-    "jinaga": "^6.7.13",
+    "jinaga": "^6.7.25",
     "node-forge": "^1.3.0",
     "pg": "^8.13.1"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jinaga-server",
-  "version": "3.5.4",
+  "version": "3.5.5",
   "description": "Data management for web and mobile applications.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -49,7 +49,7 @@
   "dependencies": {
     "csv-stringify": "^6.6.0",
     "express": "^4.21.2",
-    "jinaga": "^6.7.14",
+    "jinaga": "^6.7.25",
     "pg": "^8.13.1"
   }
 }