@abloatai/humans 0.64.3 → 0.64.4

package/dist/local/BaseSyncedStore.d.ts

@@ -109,6 +109,8 @@ export interface UserContext {
      *  structure comes from schema-declared scopes and server-issued
      *  authorization. */
     syncGroups?: readonly string[];
+    /** Server-confirmed operation grants; also partition persisted replicas. */
+    operations?: readonly string[];
     /**
      * How aggressively this participant should pull baseline state at
      * startup.

package/dist/local/Database.d.ts

@@ -6,7 +6,7 @@
  * in-memory mirror of what this class persists.
  */
 import { type DatabaseInfo, type WorkspaceMetadata } from './stores/DatabaseManager.js';
-import type { PersistenceIdentity } from './stores/persistenceIdentity.js';
+import { type PersistenceIdentity } from './stores/persistenceIdentity.js';
 import { ModelRegistry } from './ModelRegistry.js';
 import { LoadStrategy } from '@abloatai/transaction/types';
 import type { RuntimeContext } from './RuntimeContext.js';

package/dist/local/Database.js

@@ -6,6 +6,7 @@
  * in-memory mirror of what this class persists.
  */
 import { DatabaseManager } from './stores/DatabaseManager.js';
+import { persistenceIdentityMatches } from './stores/persistenceIdentity.js';
 import { StoreManager } from './stores/StoreManager.js';
 import { ModelRegistry } from './ModelRegistry.js';
 import { LoadStrategy } from '@abloatai/transaction/types';
@@ -142,12 +143,16 @@ export class Database {
     async open(identity, version = 1) {
         this.isClosing = false;
         if (this.workspaceDb && this.currentDbInfo) {
+            if (!persistenceIdentityMatches(this.currentDbInfo, identity)) {
+                throw new AbloConnectionError('Dispose the client before changing persistence authority.', { code: 'db_identity_mismatch' });
+            }
             return;
         }
         // ── In-memory mode: skip IndexedDB entirely ──────────────────
         // Creates InMemoryObjectStore instances for all registered models.
         // Bootstrap via HTTP still works; only local persistence is skipped.
         if (this.inMemory) {
+            this.bootstrapHelper.setCacheScope(null);
             this.runtime.logger.debug('Opening in-memory database (headless mode)');
             const allModels = this.modelRegistry.getRegisteredModelNames();
             for (const modelName of allModels) {
@@ -164,6 +169,8 @@ export class Database {
         // Initialize meta database
         await this.databaseManager.initializeMetaDatabase();
         this.currentDbInfo = await this.databaseManager.calculateDatabaseInfo(identity, version);
+        // Both persistence layers must share the complete authenticated authority.
+        this.bootstrapHelper.setCacheScope(this.currentDbInfo.name);
         // Register database
         await this.databaseManager.registerDatabase(this.currentDbInfo);
         // Open workspace database
@@ -172,6 +179,20 @@ export class Database {
         });
         // Initialize stores
         await this.storeManager.initializeStores(this.workspaceDb);
+        // A live group addition can have widened a previous client's replica after
+        // it opened this namespace. Check persisted coverage before restoring rows
+        // or pending writes, not after the first WebSocket reconnect.
+        const metadata = await this.getWorkspaceMetadata();
+        const allowed = new Set(identity.syncGroups ?? []);
+        if (metadata?.subscribedSyncGroups.some(group => !allowed.has(group))) {
+            // Preserve pending writes for their original authority; never replay them
+            // into a narrower replica or silently discard them.
+            await this.close();
+            throw new AbloConnectionError('Persisted sync groups exceed the current authority.', {
+                code: 'db_identity_mismatch',
+            });
+        }
+        await this.updateWorkspaceMetadata({ subscribedSyncGroups: [...allowed] });
         const readiness = await this.storeManager.checkReadinessOfStores();
         this.runtime.logger.info(`Database opened: ${this.currentDbInfo.name} (${readiness.readyStores.length}/${readiness.totalStores} stores ready)`);
     }

package/dist/local/client/storeLifecycle.js

@@ -202,6 +202,7 @@ export function startStoreLifecycle(deps) {
                     capabilityToken,
                     syncGroups,
                     deliveryPartition,
+                    operations: resolved.authority.operations,
                     bootstrapMode: resolvedBootstrapMode,
                 });
                 let current = gen.next();

package/dist/local/stores/DatabaseManager.d.ts

@@ -17,6 +17,8 @@ export interface DatabaseInfo {
     projectId: string | null;
     branchId: string;
     branchRoot: boolean;
+    syncGroups?: readonly string[];
+    operations?: readonly string[];
     schemaHash: string;
     schemaVersion: number;
     userVersion?: number;

package/dist/local/stores/DatabaseManager.js

@@ -116,6 +116,8 @@ export class DatabaseManager {
             projectId: identity.projectId,
             branchId: identity.branchId,
             branchRoot: identity.branchRoot,
+            syncGroups: [...new Set(identity.syncGroups ?? [])].sort(),
+            operations: [...new Set(identity.operations ?? [])].sort(),
             schemaHash,
             schemaVersion,
             userVersion,

package/dist/local/stores/persistenceIdentity.d.ts

@@ -1,6 +1,5 @@
 /**
- * The complete authenticated branch that owns one local replica. A branch id
- * is authoritative.
+ * The authenticated branch, groups and permissions that own one local replica.
  */
 export interface PersistenceIdentity {
     readonly participantId: string;
@@ -9,6 +8,8 @@ export interface PersistenceIdentity {
     readonly projectId: string | null;
     readonly branchId: string;
     readonly branchRoot: boolean;
+    readonly syncGroups?: readonly string[];
+    readonly operations?: readonly string[];
 }
 export interface PersistedIdentityMetadata {
     readonly namespaceVersion?: number;
@@ -18,8 +19,10 @@ export interface PersistedIdentityMetadata {
     readonly projectId?: string | null;
     readonly branchId?: string;
     readonly branchRoot?: boolean;
+    readonly syncGroups?: readonly string[];
+    readonly operations?: readonly string[];
 }
-export declare const PERSISTENCE_NAMESPACE_VERSION = 4;
+export declare const PERSISTENCE_NAMESPACE_VERSION = 5;
 /** Collision-resistant IndexedDB name for one authenticated data plane. */
 export declare function persistenceDatabaseName(identity: PersistenceIdentity, userVersion?: number): Promise<string>;
 /** Defense-in-depth check after namespace lookup and before persisted reads. */

package/dist/local/stores/persistenceIdentity.js

@@ -1,5 +1,8 @@
 import { AbloConnectionError } from '@abloatai/transaction/errors';
-export const PERSISTENCE_NAMESPACE_VERSION = 4;
+export const PERSISTENCE_NAMESPACE_VERSION = 5;
+function scopeKey(values = []) {
+    return JSON.stringify([...new Set(values)].sort());
+}
 function canonicalIdentity(identity, userVersion) {
     return JSON.stringify([
         PERSISTENCE_NAMESPACE_VERSION,
@@ -8,6 +11,8 @@ function canonicalIdentity(identity, userVersion) {
         identity.organizationId,
         identity.participantKind,
         identity.participantId,
+        scopeKey(identity.syncGroups),
+        scopeKey(identity.operations),
         userVersion,
     ]);
 }
@@ -33,5 +38,7 @@ export function persistenceIdentityMatches(info, identity) {
         info.participantKind === identity.participantKind &&
         (info.projectId ?? null) === identity.projectId &&
         info.branchId === identity.branchId &&
-        (info.branchRoot ?? false) === identity.branchRoot);
+        (info.branchRoot ?? false) === identity.branchRoot &&
+        scopeKey(info.syncGroups) === scopeKey(identity.syncGroups) &&
+        scopeKey(info.operations) === scopeKey(identity.operations));
 }

package/dist/local/sync/BootstrapFetcher.d.ts

@@ -171,7 +171,7 @@ export declare class BootstrapFetcher {
      * Update the offline-cache namespace once auth has resolved the server-side
      * account scope. This is intentionally not a public organizationId input.
      */
-    setCacheScope(cacheScope: string): void;
+    setCacheScope(cacheScope: string | null): void;
     setSyncGroups(syncGroups: readonly string[] | undefined): void;
     /**
      * Sets a fixed credential for callers that construct the helper directly.

package/dist/local/sync/BootstrapFetcher.js

@@ -256,7 +256,7 @@ export class BootstrapFetcher {
      * account scope. This is intentionally not a public organizationId input.
      */
     setCacheScope(cacheScope) {
-        if (cacheScope.trim().length === 0)
+        if (cacheScope !== null && cacheScope.trim().length === 0)
             return;
         this.options.cacheScope = cacheScope;
     }
@@ -410,7 +410,7 @@ export class BootstrapFetcher {
                     : 0,
             });
             // Persist for offline fallback
-            if (this.options.cacheScope) {
+            if (!syncGroupsOverride && this.options.cacheScope) {
                 this.saveCachedBootstrap(this.options.cacheScope, data);
             }
             return data;
@@ -427,7 +427,7 @@ export class BootstrapFetcher {
                 throw ablo;
             }
             // Transient failure after exhausting retries → cached fallback.
-            const cached = this.options.cacheScope
+            const cached = !syncGroupsOverride && this.options.cacheScope
                 ? this.loadCachedBootstrap(this.options.cacheScope)
                 : null;
             if (cached) {
@@ -859,7 +859,7 @@ export class BootstrapFetcher {
     }
     // Cache helpers for offline bootstrap
     getBootstrapCacheKey(orgId) {
-        return `ablo:bootstrap:${orgId}`;
+        return `ablo:bootstrap:v5:${JSON.stringify([orgId, this.options.baseUrl, [...new Set(this.options.syncGroups)].sort()])}`;
     }
     saveCachedBootstrap(orgId, data) {
         if (typeof window === 'undefined')

package/dist/local/sync/initialize.js

@@ -3,6 +3,7 @@ export function* initialize(host, context, signal) {
     if (host.initialized)
         return { success: true };
     host.userContext = context;
+    let persistenceReady = false;
     try {
         host.updateSyncStatus({ state: 'syncing', progress: 0 });
         // The commit outbox and offline mutation journal live in IndexedDB.
@@ -15,7 +16,10 @@ export function* initialize(host, context, signal) {
             projectId: context.projectId ?? context.organizationId,
             branchId: context.branchId,
             branchRoot: context.branchRoot ?? false,
+            syncGroups: host.resolveSyncGroups(context),
+            operations: context.operations,
         });
+        persistenceReady = true;
         // Propagate identity only after storage is ready, then restore sealed
         // requests before accepting fresh mutations.
         yield host.syncClient.initialize(context.userId, context.organizationId);
@@ -117,13 +121,13 @@ export function* initialize(host, context, signal) {
             return { success: false, error: error };
         }
         // Fallback: show local data if available
-        if (host.objectPool.size === 0) {
+        if (persistenceReady && host.objectPool.size === 0) {
             try {
                 yield host.syncClient.hydrateFromDatabase();
             }
             catch { }
         }
-        if (host.objectPool.size > 0) {
+        if (persistenceReady && host.objectPool.size > 0) {
             host.dataReady = true;
             host.initialized = true;
             host.updateSyncStatus(host.syncWebSocket.isConnected()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/humans",
-  "version": "0.64.3",
+  "version": "0.64.4",
   "description": "The optional human-facing local-state package for Ablo: presence, live queries, and React bindings.",
   "license": "Apache-2.0",
   "type": "module",
@@ -85,7 +85,7 @@
     "directory": "packages/humans"
   },
   "dependencies": {
-    "@abloatai/transaction": "0.64.3",
+    "@abloatai/transaction": "0.64.4",
     "events": "^3.3.0",
     "mobx": "^6.13.7",
     "uuid": "^11.1.0",

package/src/local/BaseSyncedStore.ts

@@ -168,6 +168,8 @@ export interface UserContext {
    *  structure comes from schema-declared scopes and server-issued
    *  authorization. */
   syncGroups?: readonly string[];
+  /** Server-confirmed operation grants; also partition persisted replicas. */
+  operations?: readonly string[];
   /**
    * How aggressively this participant should pull baseline state at
    * startup.

package/src/local/Database.ts

@@ -6,7 +6,7 @@
  * in-memory mirror of what this class persists.
  */
 import { DatabaseManager, type DatabaseInfo, type WorkspaceMetadata } from './stores/DatabaseManager.js';
-import type { PersistenceIdentity } from './stores/persistenceIdentity.js';
+import { persistenceIdentityMatches, type PersistenceIdentity } from './stores/persistenceIdentity.js';
 import { StoreManager } from './stores/StoreManager.js';
 import { ModelRegistry } from './ModelRegistry.js';
 import { LoadStrategy } from '@abloatai/transaction/types';
@@ -226,6 +226,9 @@ export class Database {
     this.isClosing = false;
 
     if (this.workspaceDb && this.currentDbInfo) {
+      if (!persistenceIdentityMatches(this.currentDbInfo, identity)) {
+        throw new AbloConnectionError('Dispose the client before changing persistence authority.', { code: 'db_identity_mismatch' });
+      }
       return;
     }
 
@@ -233,6 +236,7 @@ export class Database {
     // Creates InMemoryObjectStore instances for all registered models.
     // Bootstrap via HTTP still works; only local persistence is skipped.
     if (this.inMemory) {
+      this.bootstrapHelper.setCacheScope(null);
       this.runtime.logger.debug('Opening in-memory database (headless mode)');
       const allModels = this.modelRegistry.getRegisteredModelNames();
       for (const modelName of allModels) {
@@ -264,6 +268,9 @@ export class Database {
       version
     );
 
+    // Both persistence layers must share the complete authenticated authority.
+    this.bootstrapHelper.setCacheScope(this.currentDbInfo.name);
+
     // Register database
     await this.databaseManager.registerDatabase(this.currentDbInfo);
 
@@ -278,6 +285,21 @@ export class Database {
     // Initialize stores
     await this.storeManager.initializeStores(this.workspaceDb);
 
+    // A live group addition can have widened a previous client's replica after
+    // it opened this namespace. Check persisted coverage before restoring rows
+    // or pending writes, not after the first WebSocket reconnect.
+    const metadata = await this.getWorkspaceMetadata();
+    const allowed = new Set(identity.syncGroups ?? []);
+    if (metadata?.subscribedSyncGroups.some(group => !allowed.has(group))) {
+      // Preserve pending writes for their original authority; never replay them
+      // into a narrower replica or silently discard them.
+      await this.close();
+      throw new AbloConnectionError('Persisted sync groups exceed the current authority.', {
+        code: 'db_identity_mismatch',
+      });
+    }
+    await this.updateWorkspaceMetadata({ subscribedSyncGroups: [...allowed] });
+
     const readiness = await this.storeManager.checkReadinessOfStores();
     this.runtime.logger.info(
       `Database opened: ${this.currentDbInfo.name} (${readiness.readyStores.length}/${readiness.totalStores} stores ready)`

package/src/local/client/storeLifecycle.ts

@@ -325,6 +325,7 @@ export function startStoreLifecycle<S extends SchemaRecord>(
           capabilityToken,
           syncGroups,
           deliveryPartition,
+          operations: resolved.authority.operations,
           bootstrapMode: resolvedBootstrapMode,
         });
         let current = gen.next();

package/src/local/stores/DatabaseManager.ts

@@ -33,6 +33,8 @@ export interface DatabaseInfo {
   projectId: string | null;
   branchId: string;
   branchRoot: boolean;
+  syncGroups?: readonly string[];
+  operations?: readonly string[];
   schemaHash: string;
   schemaVersion: number;
   userVersion?: number;
@@ -175,6 +177,8 @@ export class DatabaseManager {
       projectId: identity.projectId,
       branchId: identity.branchId,
       branchRoot: identity.branchRoot,
+      syncGroups: [...new Set(identity.syncGroups ?? [])].sort(),
+      operations: [...new Set(identity.operations ?? [])].sort(),
       schemaHash,
       schemaVersion,
       userVersion,

package/src/local/stores/persistenceIdentity.ts

@@ -1,8 +1,7 @@
 import { AbloConnectionError } from '@abloatai/transaction/errors';
 
 /**
- * The complete authenticated branch that owns one local replica. A branch id
- * is authoritative.
+ * The authenticated branch, groups and permissions that own one local replica.
  */
 export interface PersistenceIdentity {
   readonly participantId: string;
@@ -11,6 +10,8 @@ export interface PersistenceIdentity {
   readonly projectId: string | null;
   readonly branchId: string;
   readonly branchRoot: boolean;
+  readonly syncGroups?: readonly string[];
+  readonly operations?: readonly string[];
 }
 
 export interface PersistedIdentityMetadata {
@@ -21,9 +22,15 @@ export interface PersistedIdentityMetadata {
   readonly projectId?: string | null;
   readonly branchId?: string;
   readonly branchRoot?: boolean;
+  readonly syncGroups?: readonly string[];
+  readonly operations?: readonly string[];
 }
 
-export const PERSISTENCE_NAMESPACE_VERSION = 4;
+export const PERSISTENCE_NAMESPACE_VERSION = 5;
+
+function scopeKey(values: readonly string[] = []): string {
+  return JSON.stringify([...new Set(values)].sort());
+}
 
 function canonicalIdentity(
   identity: PersistenceIdentity,
@@ -36,6 +43,8 @@ function canonicalIdentity(
     identity.organizationId,
     identity.participantKind,
     identity.participantId,
+    scopeKey(identity.syncGroups),
+    scopeKey(identity.operations),
     userVersion,
   ]);
 }
@@ -76,6 +85,8 @@ export function persistenceIdentityMatches(
     info.participantKind === identity.participantKind &&
     (info.projectId ?? null) === identity.projectId &&
     info.branchId === identity.branchId &&
-    (info.branchRoot ?? false) === identity.branchRoot
+    (info.branchRoot ?? false) === identity.branchRoot &&
+    scopeKey(info.syncGroups) === scopeKey(identity.syncGroups) &&
+    scopeKey(info.operations) === scopeKey(identity.operations)
   );
 }

package/src/local/sync/BootstrapFetcher.ts

@@ -406,8 +406,8 @@ export class BootstrapFetcher {
    * Update the offline-cache namespace once auth has resolved the server-side
    * account scope. This is intentionally not a public organizationId input.
    */
-  setCacheScope(cacheScope: string): void {
-    if (cacheScope.trim().length === 0) return;
+  setCacheScope(cacheScope: string | null): void {
+    if (cacheScope !== null && cacheScope.trim().length === 0) return;
     this.options.cacheScope = cacheScope;
   }
 
@@ -587,7 +587,7 @@ export class BootstrapFetcher {
       });
 
       // Persist for offline fallback
-      if (this.options.cacheScope) {
+      if (!syncGroupsOverride && this.options.cacheScope) {
         this.saveCachedBootstrap(this.options.cacheScope, data);
       }
       return data;
@@ -604,7 +604,7 @@ export class BootstrapFetcher {
       }
 
       // Transient failure after exhausting retries → cached fallback.
-      const cached = this.options.cacheScope
+      const cached = !syncGroupsOverride && this.options.cacheScope
         ? this.loadCachedBootstrap(this.options.cacheScope)
         : null;
       if (cached) {
@@ -1129,7 +1129,7 @@ export class BootstrapFetcher {
 
   // Cache helpers for offline bootstrap
   private getBootstrapCacheKey(orgId: string): string {
-    return `ablo:bootstrap:${orgId}`;
+    return `ablo:bootstrap:v5:${JSON.stringify([orgId, this.options.baseUrl, [...new Set(this.options.syncGroups)].sort()])}`;
   }
   private saveCachedBootstrap(orgId: string, data: BootstrapData): void {
     if (typeof window === 'undefined') return;

package/src/local/sync/initialize.ts

@@ -42,6 +42,7 @@ export function* initialize<TCollaboration extends EventMap<TCollaboration>>(
     if (host.initialized) return { success: true };
 
     host.userContext = context;
+    let persistenceReady = false;
 
     try {
       host.updateSyncStatus({ state: 'syncing', progress: 0 });
@@ -56,8 +57,12 @@ export function* initialize<TCollaboration extends EventMap<TCollaboration>>(
         projectId: context.projectId ?? context.organizationId,
         branchId: context.branchId,
         branchRoot: context.branchRoot ?? false,
+        syncGroups: host.resolveSyncGroups(context),
+        operations: context.operations,
       });
 
+      persistenceReady = true;
+
       // Propagate identity only after storage is ready, then restore sealed
       // requests before accepting fresh mutations.
       yield host.syncClient.initialize(
@@ -182,13 +187,13 @@ export function* initialize<TCollaboration extends EventMap<TCollaboration>>(
       }
 
       // Fallback: show local data if available
-      if (host.objectPool.size === 0) {
+      if (persistenceReady && host.objectPool.size === 0) {
         try {
           yield host.syncClient.hydrateFromDatabase();
         } catch {}
       }
 
-      if (host.objectPool.size > 0) {
+      if (persistenceReady && host.objectPool.size > 0) {
         host.dataReady = true;
         host.initialized = true;
         host.updateSyncStatus(