@serfab/quereus-plugin-sereus 0.11.0 → 0.13.0

package/src/connect-browser.ts

@@ -1,57 +1,58 @@
-import type { Database, VTablePluginInfo, FunctionPluginInfo, CollationPluginInfo } from '@quereus/quereus';
-import cryptoPlugin from '@optimystic/quereus-plugin-crypto/plugin';
-import { createLibp2pNode } from '@optimystic/db-p2p/rn';
-import { webSockets } from '@libp2p/websockets';
-import { circuitRelayTransport } from '@libp2p/circuit-relay-v2';
-import { IndexedDBRawStorage, openOptimysticWebDb } from '@optimystic/db-p2p-storage-web';
-import type { Libp2p } from '@libp2p/interface';
-import type { StrandConnectionOptions, SereusPluginResult } from './types.js';
-import { composeStrand, applyRegistrations } from './compose-strand.js';
-
-/** The subset of the crypto plugin result we register inline in the browser. */
-interface CryptoPluginResult {
-	vtables: VTablePluginInfo[];
-	functions: FunctionPluginInfo[];
-	collations: CollationPluginInfo[];
-}
-
-/**
- * Connect a Quereus Database to a Sereus strand from a browser/worker.
- *
- * Thin adapter over the shared {@link composeStrand} composition, supplying the
- * browser platform seams:
- *  - crypto registered inline (no runtime `@quereus/quereus` import, so the
- *    bundle does not duplicate the host's instance),
- *  - storage defaulting to `IndexedDBRawStorage` keyed by `sereus-strand-<id>`,
- *  - a node created via the TCP-free `@optimystic/db-p2p/rn` entry with explicit
- *    `webSockets()` + `circuitRelayTransport()` transports.
- */
-export async function connectToStrandBrowser(
-	db: Database,
-	options: StrandConnectionOptions,
-): Promise<SereusPluginResult> {
-	return composeStrand(db, options, {
-		registerCrypto(database) {
-			applyRegistrations(database, cryptoPlugin(database, {}) as unknown as CryptoPluginResult);
-		},
-		async resolveStorage({ strandId, resolvedTransactor, requestedStorage }) {
-			if (requestedStorage) return requestedStorage;
-			// Browsers always default to IndexedDB so a reload survives; the
-			// unit-test fake transactor needs no storage.
-			if (resolvedTransactor === 'test') return undefined;
-			const dbHandle = await openOptimysticWebDb(`sereus-strand-${strandId}`);
-			return new IndexedDBRawStorage(dbHandle);
-		},
-		async createNode({ networkName, bootstrapNodes, fretProfile, clusterSize, storage }) {
-			return createLibp2pNode({
-				transports: [webSockets(), circuitRelayTransport()],
-				listenAddrs: [],
-				bootstrapNodes,
-				networkName,
-				fretProfile,
-				clusterSize,
-				...(storage && { storage }),
-			}) as Promise<Libp2p>;
-		},
-	});
-}
+import type { Database, VTablePluginInfo, FunctionPluginInfo, CollationPluginInfo } from '@quereus/quereus';
+import cryptoPlugin from '@optimystic/quereus-plugin-crypto/plugin';
+import { createLibp2pNode } from '@optimystic/db-p2p/rn';
+import { webSockets } from '@libp2p/websockets';
+import { circuitRelayTransport } from '@libp2p/circuit-relay-v2';
+import { IndexedDBRawStorage, openOptimysticWebDb } from '@optimystic/db-p2p-storage-web';
+import type { Libp2p } from '@libp2p/interface';
+import type { StrandConnectionOptions, SereusPluginResult } from './types.js';
+import { composeStrand, applyRegistrations } from './compose-strand.js';
+
+/** The subset of the crypto plugin result we register inline in the browser. */
+interface CryptoPluginResult {
+	vtables: VTablePluginInfo[];
+	functions: FunctionPluginInfo[];
+	collations: CollationPluginInfo[];
+}
+
+/**
+ * Connect a Quereus Database to a Sereus strand from a browser/worker.
+ *
+ * Thin adapter over the shared {@link composeStrand} composition, supplying the
+ * browser platform seams:
+ *  - crypto registered inline (no runtime `@quereus/quereus` import, so the
+ *    bundle does not duplicate the host's instance),
+ *  - storage defaulting to `IndexedDBRawStorage` keyed by `sereus-strand-<id>`,
+ *  - a node created via the TCP-free `@optimystic/db-p2p/rn` entry with explicit
+ *    `webSockets()` + `circuitRelayTransport()` transports.
+ */
+export async function connectToStrandBrowser(
+	db: Database,
+	options: StrandConnectionOptions,
+): Promise<SereusPluginResult> {
+	return composeStrand(db, options, {
+		registerCrypto(database) {
+			applyRegistrations(database, cryptoPlugin(database, {}) as unknown as CryptoPluginResult);
+		},
+		async resolveStorage({ strandId, resolvedTransactor, requestedStorage }) {
+			if (requestedStorage) return requestedStorage;
+			// Browsers always default to IndexedDB so a reload survives; the
+			// unit-test fake transactor needs no storage.
+			if (resolvedTransactor === 'test') return undefined;
+			const dbHandle = await openOptimysticWebDb(`sereus-strand-${strandId}`);
+			return new IndexedDBRawStorage(dbHandle);
+		},
+		async createNode({ networkName, bootstrapNodes, fretProfile, clusterSize, clusterPolicy, storage }) {
+			return createLibp2pNode({
+				transports: [webSockets(), circuitRelayTransport()],
+				listenAddrs: [],
+				bootstrapNodes,
+				networkName,
+				fretProfile,
+				clusterSize,
+				clusterPolicy,
+				...(storage && { storage }),
+			}) as Promise<Libp2p>;
+		},
+	});
+}

package/src/connect.ts

@@ -1,38 +1,39 @@
-import type { Database } from '@quereus/quereus';
-import { registerPlugin } from '@quereus/quereus';
-import cryptoPlugin from '@optimystic/quereus-plugin-crypto/plugin';
-import type { Libp2p } from '@libp2p/interface';
-import type { StrandConnectionOptions, SereusPluginResult } from './types.js';
-import { composeStrand } from './compose-strand.js';
-
-/**
- * Connect a Quereus Database to a Sereus strand (Node).
- *
- * Thin adapter over the shared {@link composeStrand} composition, supplying the
- * Node platform seams: crypto via `@quereus/quereus`'s `registerPlugin`, and a
- * TCP libp2p node created (only when not injected) via `@optimystic/db-p2p`.
- */
-export async function connectToStrand(
-	db: Database,
-	options: StrandConnectionOptions,
-): Promise<SereusPluginResult> {
-	return composeStrand(db, options, {
-		async registerCrypto(database) {
-			await registerPlugin(database, cryptoPlugin);
-		},
-		async createNode({ networkName, bootstrapNodes, fretProfile, port, clusterSize, storage }) {
-			// Dynamically import to keep the module cross-platform friendly: this
-			// pulls the Node-only `@optimystic/db-p2p` (TCP) entry, and is only
-			// reached when actually creating a node (never for injected nodes).
-			const { createLibp2pNode } = await import('@optimystic/db-p2p');
-			return createLibp2pNode({
-				port,
-				bootstrapNodes,
-				networkName,
-				fretProfile,
-				clusterSize,
-				...(storage && { storage }),
-			}) as Promise<Libp2p>;
-		},
-	});
-}
+import type { Database } from '@quereus/quereus';
+import { registerPlugin } from '@quereus/quereus';
+import cryptoPlugin from '@optimystic/quereus-plugin-crypto/plugin';
+import type { Libp2p } from '@libp2p/interface';
+import type { StrandConnectionOptions, SereusPluginResult } from './types.js';
+import { composeStrand } from './compose-strand.js';
+
+/**
+ * Connect a Quereus Database to a Sereus strand (Node).
+ *
+ * Thin adapter over the shared {@link composeStrand} composition, supplying the
+ * Node platform seams: crypto via `@quereus/quereus`'s `registerPlugin`, and a
+ * TCP libp2p node created (only when not injected) via `@optimystic/db-p2p`.
+ */
+export async function connectToStrand(
+	db: Database,
+	options: StrandConnectionOptions,
+): Promise<SereusPluginResult> {
+	return composeStrand(db, options, {
+		async registerCrypto(database) {
+			await registerPlugin(database, cryptoPlugin);
+		},
+		async createNode({ networkName, bootstrapNodes, fretProfile, port, clusterSize, clusterPolicy, storage }) {
+			// Dynamically import to keep the module cross-platform friendly: this
+			// pulls the Node-only `@optimystic/db-p2p` (TCP) entry, and is only
+			// reached when actually creating a node (never for injected nodes).
+			const { createLibp2pNode } = await import('@optimystic/db-p2p');
+			return createLibp2pNode({
+				port,
+				bootstrapNodes,
+				networkName,
+				fretProfile,
+				clusterSize,
+				clusterPolicy,
+				...(storage && { storage }),
+			}) as Promise<Libp2p>;
+		},
+	});
+}

package/src/index.ts

@@ -5,7 +5,10 @@ export {
 	CONTROL_CLUSTER_POLICY,
 	DEFAULT_STRAND_CLUSTER_SIZE,
 	STRAND_CLUSTER_POLICY,
-	resolveStrandClusterSize
+	resolveStrandClusterSize,
+	resolveRepairYardstick,
+	controlClusterPolicy,
+	strandClusterPolicy
 } from './cluster-size.js';
 export { wrapStorageWithCache, disposeStorageCache } from './cached-storage.js';
 export type { StrandConnectionOptions, SereusPluginResult, StrandTransactor } from './types.js';

package/src/strand-schema.ts

@@ -13,8 +13,9 @@
  *
  * Drift discipline: the table declarations here MUST stay byte-equivalent to the
  * body of `schemas/strand.qsql` (the on-disk canonical copy). Any edit here must
- * be mirrored there and vice versa — the same invariant the planned
- * `control-schema-drift-guard` enforces for the control schema.
+ * be mirrored there and vice versa. `test/strand-schema-drift.spec.ts` enforces it
+ * — but only from THIS package, so an edit made in `schemas/strand.qsql` alone
+ * stays green everywhere its author is likely to look; run that spec after either.
  *
  * Crypto idiom (matches `schemas/control.qsql` and the sApp RBAC fixture
  * `packages/integration-tests/fixtures/simple-sapp.qsql`): every signed write
@@ -108,6 +109,22 @@ export const STRAND_SCHEMA = `    table Header (
         -- rows — no caller-supplied context decides admission (unlike NotExpired's Now).
         constraint NotCancelled check on insert (
             not exists (select 1 from CancelledInvite C where C.InviteKey = new.InviteKey)
+        ),
+        -- A SEALED strand (a closed strand whose Manager table its sole manager has
+        -- deliberately emptied — see the Manager table comment) admits nobody, and that
+        -- includes the holder of an unspent invitation issued BEFORE the seal.
+        -- cancelInvite itself needs a manager, so after sealing nobody could kill such
+        -- an invitation — this gate is what kills it. The subquery reads the LIVE
+        -- Manager table and defers to commit, so it sees the post-image: at least one
+        -- manager must survive the transaction, and sealing plus consuming in the SAME
+        -- transaction is rejected too. Blocking this insert blocks the whole join, for
+        -- exactly the reason NotCancelled gives above.
+        -- The Manager rows this reads are the ones THIS NODE can see, so the gate binds
+        -- only once the seal has reached here — on a node still behind on the seal it
+        -- passes, and a stranger holding a pre-seal invitation joins (the Manager table's
+        -- seal-propagation NOTE).
+        constraint NotSealed check on insert (
+            exists (select 1 from Manager)
         )
     ) with context (InviteSignature text null, Now datetime null);
 
@@ -136,7 +153,8 @@ export const STRAND_SCHEMA = `    table Header (
     -- "forever".
     -- NOTE: a cancellation must PROPAGATE before the holder redeems — a holder consuming
     -- on a node that has not yet seen this row still gets in. Same convergence class as
-    -- the NotRevoked / MinOneMember / MinOneManager local-visibility notes; not solved here.
+    -- the NotRevoked / MinOneMember local-visibility notes and the Manager table's
+    -- seal-propagation note; not solved here.
     table CancelledInvite (
         InviteKey text primary key,
         constraint OnlyClosed check (
@@ -382,7 +400,7 @@ export const STRAND_SCHEMA = `    table Header (
         -- NOTE: a per-transaction check against locally visible rows. Two partitioned nodes
         -- — one promoting X, one removing X's Member and Manager rows — can each pass
         -- locally and converge to a Manager row with no Member row. Same convergence class
-        -- as the MinOneMember / MinOneManager / NotRevoked notes; not solved here.
+        -- as the MinOneMember / NotRevoked / seal-propagation notes; not solved here.
         constraint MemberExists check on insert (
             exists (select 1 from Member M where M.Key = new.MemberKey)
         ),
@@ -390,17 +408,26 @@ export const STRAND_SCHEMA = `    table Header (
         -- (which proves only that old.MemberKey consented) double as a hand-off: the
         -- former-manager branch would accept re-pointing the row at any new key.
         constraint NoUpdate check on update (false),
-        -- A closed strand must never lose its last manager. Every admit path (Invite,
-        -- addMemberByManager, addManager) requires an existing Manager row, so an
-        -- admin-less strand can never admit anyone again. Deferred (subquery), so the
-        -- count it sees is the POST-delete count.
-        -- NOTE: this is a per-transaction check against locally visible rows. Two nodes
-        -- that concurrently remove different managers can each see a surviving one and
-        -- still converge to zero; if partitioned rotation ever becomes a real workflow,
-        -- the floor needs a cross-node guard, not a local count.
-        constraint MinOneManager check on delete (
-            (select count(1) from Manager) >= 1
-        ),
+        -- A closed strand loses its LAST manager only by SEALING — a distinct,
+        -- self-signed act (the 'seal' branch of Authorized below), never an ordinary
+        -- resignation and never an admin removal. There is deliberately NO
+        -- min-one-manager floor: a strand with no managers is frozen, not bricked.
+        -- Every admission path (Invite, addMemberByManager, addManager) requires a
+        -- Manager row, so a sealed strand's membership can never grow again — and that
+        -- freeze is the privacy guarantee its remaining members are buying: nobody
+        -- holds the power to admit a party who would then read the strand's whole
+        -- history. Sealing is irreversible: the founding branch of Authorized closes
+        -- for good once any manager stamp has been retired into Revocation.
+        -- NOTE: a seal must PROPAGATE before it binds a given node — a node that has
+        -- not yet converged on the delete still shows the manager row, so until the
+        -- delete arrives that node admits as if unsealed. It is NOT only the
+        -- ex-manager's own key that gains: every gate here reads the LOCALLY visible
+        -- Manager rows, and ConsumedInvite.NotSealed is one of them, so a STRANGER
+        -- holding an invitation issued before the seal can redeem it on such a node.
+        -- Same convergence class as the MinOneMember / NotRevoked local-visibility
+        -- notes; not solved here. Arrival IS covered, on the converged side:
+        -- integration-tests' strand-membership-closed-strand-e2e gates a second node on
+        -- the seal and then requires it to refuse every admission path.
         constraint Authorized check on insert, delete (
             -- Every signed branch below is a domain/action-tagged digest bound to the
             -- row's StampId — the same single-use idiom as Member.Authorized: an
@@ -415,23 +442,47 @@ export const STRAND_SCHEMA = `    table Header (
             -- is belt-and-braces since MemberExists above enforces it on EVERY insert —
             -- kept so this branch's own claim ("this manager IS that member") reads in
             -- place rather than by cross-reference.
+            -- The Revocation gate closes this branch FOREVER once any manager seat has
+            -- been retired: founding happens exactly once per strand (Header, then
+            -- Member, then Manager, with no Revocation rows in existence), so on a
+            -- SEALED strand a lone surviving member cannot re-seat itself as a
+            -- generation-0 founder and start admitting. Accepted, deliberate: between
+            -- its own founding Member and Manager inserts a founder could, with its own
+            -- key, file a junk Revocation('Manager', ...) tombstone (RowIsGone permits
+            -- stamps naming no real row) and permanently block its own founding — pure
+            -- self-harm needing the founder's private key; no other party can reach
+            -- that window (there are no other committed members yet).
             (old.MemberKey is null
                 and new.Generation = 0
                 and (select count(1) from Manager) <= 1
                 and (select count(1) from Member) <= 1
-                and exists (select 1 from Member M where M.Key = new.MemberKey))
+                and exists (select 1 from Member M where M.Key = new.MemberKey)
+                and not exists (select 1 from Revocation R where R.TableName = 'Manager'))
 
-                -- or authorized by this former manager (self-resignation), over the
-                -- resign-tagged digest bound to its own row's stamp. The 'resign' tag
-                -- (vs the admin branch's 'remove') is belt-and-braces — the two
-                -- branches verify against different keys; the anti-replay fix is the
-                -- stamp: once this manager is re-promoted under a fresh stamp, a
-                -- captured resignation no longer removes it.
+                -- or removed by the departing manager ITSELF, over one of two
+                -- self-signed, action-tagged digests bound to its own row's stamp. The
+                -- POST-image manager count is what distinguishes the two: 'resign' is
+                -- an ordinary departure that leaves at least one manager standing,
+                -- while 'seal' is the delete that empties the table and permanently
+                -- freezes admission (see the table comment above). The tag is what
+                -- makes each a signed statement of THAT intent — a captured
+                -- resignation approval can never seal, nor a seal approval merely
+                -- resign — and the stamp is still what makes each single-use: once
+                -- this manager is re-promoted under a fresh stamp, neither captured
+                -- approval removes the new row. Both counts are subqueries, so the
+                -- whole check defers to commit and the counts are the post-image.
                 or (
                     old.MemberKey is not null
                         and old.MemberKey = context.ManagerKey
+                        and (select count(1) from Manager) >= 1
                         and verify(digest('Strand.Manager', 'resign', old.MemberKey, old.StampId), context.Signature, old.MemberKey, 'ed25519')
                 )
+                or (
+                    old.MemberKey is not null
+                        and old.MemberKey = context.ManagerKey
+                        and (select count(1) from Manager) = 0
+                        and verify(digest('Strand.Manager', 'seal', old.MemberKey, old.StampId), context.Signature, old.MemberKey, 'ed25519')
+                )
 
                 -- or a promotion signed by an EARLIER-generation manager, over the
                 -- add-tagged digest binding (MemberKey, Generation, StampId) — so a
@@ -483,7 +534,7 @@ export const STRAND_SCHEMA = `    table Header (
     -- NOTE: the guarded tables' NotRevoked CHECK runs against locally visible rows, so
     -- a node that has not yet converged on a Revocation row can still accept a replayed
     -- add and the resurrected row coexists with the tombstone after merge — the same
-    -- convergence class as the MinOneMember / MinOneManager local-count notes.
+    -- convergence class as the MinOneMember / Manager seal-propagation notes.
     -- NOTE: this table only grows — one row per membership deletion, plus any junk any
     -- member chooses to file, and Immutable means rows never go away. Fine at strand
     -- scale; if membership churn ever gets large it needs pruning bounded by something