@authzflow/core 0.1.0-alpha.8 → 0.1.0-beta.1

package/README.md

@@ -1,6 +1,6 @@
 # @authzflow/core
 
-MIT-licensed alpha authorization-state runtime maintained by Accelflow Inc. Ships prebuilt Rust/Wasm, ESM JavaScript, TypeScript declarations and a checked reader. npm consumers need no Rust compiler.
+MIT-licensed beta authorization-state runtime maintained by Accelflow Inc. Ships prebuilt Rust/Wasm, ESM JavaScript, TypeScript declarations and a checked reader. npm consumers need no Rust compiler.
 
 ```js
 import { createRuntime, createCheckedReader } from '@authzflow/core';
@@ -10,7 +10,7 @@ The host supplies verified sessions, clocks, an atomic durable checkpoint store,
 
 See https://github.com/Accelflow/AuthzFlow/blob/main/docs-public/getting-started.md for installation and the executable example, and https://github.com/Accelflow/AuthzFlow/blob/main/docs-public/adapters.md for the full callback contract. Node 22/24, ESM, TypeScript 5.9+ and modern secure-context WebAssembly browsers are initial targets.
 
-Offline permissions expire at their original bounded deadline and are lost across reader/process restarts. Server-side revocation cannot instantly reach disconnected clients. Already returned plaintext, raw store bypasses, multi-owner coordination and stream recovery are outside alpha guarantees.
+Offline permissions expire at their original bounded deadline and are lost across reader/process restarts. Server-side revocation cannot instantly reach disconnected clients. Already returned plaintext, raw store bypasses, multi-owner coordination and stream recovery are outside beta guarantees.
 
 LICENSE and THIRD_PARTY_NOTICES.md are included; the latter contains dependency and Rust standard-library attributions and license texts. Security reporting: https://github.com/Accelflow/AuthzFlow/security/advisories/new .
 
@@ -35,3 +35,27 @@ do not supply that grant. A different cached value is rejected without destroyin
 the valid grant for the original content. Session/clock/revision failures fence it.
 Hosts can use this for secondary cache projections; normal screen revalidation
 continues to call `readWithPermit()`. It cannot turn a cached checkpoint into permission.
+
+### Optional Resource Group integration
+
+The opt-in `resource-group` entrypoint aggregates invalidations for related
+Resources. `createResourceGroupCoordinator` uses Rust protocol v2;
+`createNativeResourceGroupCoordinator` in `native-reader` uses the same Rust
+transitions. Attach it through the Resource authority's `groups` option and pass
+`resourceGroupId` on each Resource input. Do not enable the legacy `changes`
+option on that same authority.
+
+`group-sqlite`, `group-indexeddb`, and `group-notifications` provide shared-store
+and wakeup adapters. The host must retain session checks and atomic, term-fenced
+purge. Group registration, shared state and notifications never grant content;
+each reader retains its own fresh-check permit. Cold start cannot inherit another
+tab's permit. Close the authority before closing its host-owned coordinator.
+
+`readCachedManyWithPermit` checks up to 64 cached Resource inputs (4 MiB aggregate)
+without HTTP checks or deadline renewal. It returns ordered per-item results and
+rechecks shared fences before delivery. It does not load missing permits or make
+an entire search index readable offline.
+
+Versioned source contracts live under `contracts/`. Browser-tab and independent
+SQLite-process contracts are tested; each product still needs its own integration
+acceptance and revision-fenced purge implementation.

package/dist/group-indexeddb.d.ts

@@ -0,0 +1,3 @@
+import type { GroupCoordinationStorage } from './resource-group-driver.js';
+/** Pass the product's DB/store to share the transaction boundary with product replicas. */
+export declare function createIndexedDBGroupStorage(db: IDBDatabase, storeName: string): GroupCoordinationStorage;

package/dist/group-indexeddb.js

@@ -0,0 +1,37 @@
+/** Pass the product's DB/store to share the transaction boundary with product replicas. */
+export function createIndexedDBGroupStorage(db, storeName) {
+    if (!db.objectStoreNames.contains(storeName))
+        throw Error('group_store_missing');
+    const request = (r) => new Promise((resolve, reject) => { r.onsuccess = () => resolve(r.result); r.onerror = () => reject(r.error); });
+    const run = async (mode, work) => {
+        const tx = db.transaction([storeName], mode, { durability: 'strict' });
+        const done = new Promise((resolve, reject) => { tx.oncomplete = () => resolve(); tx.onabort = () => reject(tx.error ?? Error('group_transaction_aborted')); });
+        try {
+            const result = await work(tx.objectStore(storeName));
+            await done;
+            return result;
+        }
+        catch (error) {
+            try {
+                tx.abort();
+            }
+            catch { }
+            await done.catch(() => { });
+            throw error;
+        }
+    };
+    return {
+        async read(key) { return run('readonly', async (store) => (await request(store.get(key))) ?? null); },
+        async readMany(keys) { return run('readonly', async (store) => Promise.all(keys.map(async (key) => (await request(store.get(key))) ?? null))); },
+        async transaction(key, work) {
+            return run('readwrite', async (store) => {
+                const saved = (await request(store.get(key))) ?? null;
+                const { row, result } = work(saved);
+                if (new TextEncoder().encode(JSON.stringify(row)).byteLength > 1048576)
+                    throw Error('group_capacity');
+                await request(store.put(row, key));
+                return result;
+            });
+        },
+    };
+}

package/dist/group-notifications.d.ts

@@ -0,0 +1,6 @@
+import type { GroupNotice } from './resource-group-driver.js';
+/** Host creates/closes a same-profile channel. Messages only trigger durable reloads. */
+export declare function createGroupNotificationPort(channel: Pick<BroadcastChannel, 'postMessage' | 'addEventListener' | 'removeEventListener'>): {
+    notify(notice: GroupNotice): void;
+    listen(receive: (notice: unknown) => void): () => void;
+};

package/dist/group-notifications.js

@@ -0,0 +1,7 @@
+/** Host creates/closes a same-profile channel. Messages only trigger durable reloads. */
+export function createGroupNotificationPort(channel) {
+    return {
+        notify(notice) { channel.postMessage(notice); },
+        listen(receive) { const handler = (event) => receive(event.data); channel.addEventListener('message', handler); return () => channel.removeEventListener('message', handler); },
+    };
+}

package/dist/group-sqlite.d.ts

@@ -0,0 +1,4 @@
+import type { SQLiteDatabase } from './sqlite.js';
+import type { GroupCoordinationStorage } from './resource-group-driver.js';
+/** Uses the host connection; place content and Group fences in the same database for purge. */
+export declare function createSQLiteGroupStorage(db: SQLiteDatabase): GroupCoordinationStorage;

package/dist/group-sqlite.js

@@ -0,0 +1,40 @@
+/** Uses the host connection; place content and Group fences in the same database for purge. */
+export function createSQLiteGroupStorage(db) {
+    db.exec('CREATE TABLE IF NOT EXISTS authz_resource_groups (key TEXT PRIMARY KEY,payload TEXT NOT NULL) STRICT; PRAGMA busy_timeout=5000;');
+    const read = (key) => {
+        const row = db.prepare('SELECT payload FROM authz_resource_groups WHERE key=?').get(key);
+        if (!row)
+            return null;
+        if (typeof row.payload !== 'string' || row.payload.length > 1048576)
+            throw Error('group_state_invalid');
+        return JSON.parse(row.payload);
+    };
+    return {
+        async read(key) { return read(key); },
+        async readMany(keys) { db.exec('BEGIN'); try {
+            const result = keys.map(read);
+            db.exec('COMMIT');
+            return result;
+        }
+        catch (error) {
+            db.exec('ROLLBACK');
+            throw error;
+        } },
+        async transaction(key, work) {
+            db.exec('BEGIN IMMEDIATE');
+            try {
+                const { row, result } = work(read(key));
+                const payload = JSON.stringify(row);
+                if (new TextEncoder().encode(payload).byteLength > 1048576)
+                    throw Error('group_capacity');
+                db.prepare('INSERT OR REPLACE INTO authz_resource_groups VALUES(?,?)').run(key, payload);
+                db.exec('COMMIT');
+                return result;
+            }
+            catch (error) {
+                db.exec('ROLLBACK');
+                throw error;
+            }
+        },
+    };
+}

package/dist/index.d.ts

@@ -1,5 +1,8 @@
 export { createResourceAuthority, type ResourceAuthority, type ResourceAuthorityOptions, type ResourceReadInput, type ResourceReadLease, type ResourceIdentity, type ResourceAuthorityState, type ResourceAuthorityPhase, type ResourceAuthorityReason, type ResourceAuthorityEvent, type ResourceAuthorityEventCode, type ResourceAuthorityDiagnostic } from './resource-authority.js';
 export { createChangeConsumer, type ChangeConsumer, type ChangeConsumerOptions } from './change-consumer.js';
+export { createResourceGroupCoordinator } from './resource-group.js';
+export type * from './resource-group-driver.js';
+export type { CachedItemResult } from './resource-authority-driver.js';
 export { createCheckedReader, type CheckedRead, type CheckedReader, type CheckedReaderOptions } from './checked-reader.js';
 export interface Clock {
     boot: string;

package/dist/index.js

@@ -1,6 +1,7 @@
 export { createResourceAuthority } from './resource-authority.js';
 import { createDrivenRuntime } from './runtime-driver.js';
 export { createChangeConsumer } from './change-consumer.js';
+export { createResourceGroupCoordinator } from './resource-group.js';
 import init, { WasmRuntime, runtime_abi_version } from '../wasm/authzflow_wasm.js';
 export { createCheckedReader } from './checked-reader.js';
 /** Loads the Rust authority. Restored state always requires a fresh server check. */

package/dist/native-reader.d.ts

@@ -18,3 +18,8 @@ export declare function createNativeResourceAuthority<T = unknown>(options: Omit
     native: NativePort;
     randomUUID(): string;
 }): import("./resource-authority-driver.js").ResourceAuthority<T>;
+import { type ResourceGroupOptions } from './resource-group-driver.js';
+/** Requires native Group protocol support; no Wasm import or JavaScript fallback. */
+export declare function createNativeResourceGroupCoordinator(options: ResourceGroupOptions & {
+    native: NativePort;
+}): import("./resource-group-driver.js").ResourceGroupCoordinator;

package/dist/native-reader.js

@@ -41,3 +41,13 @@ import { createDrivenResourceAuthority } from './resource-authority-driver.js';
 export function createNativeResourceAuthority(options) {
     return createDrivenResourceAuthority({ ...options, clone: options.clone ?? (value => JSON.parse(JSON.stringify(value))), runtime: options.runtime ?? (settings => createNativeRuntime({ ...settings, native: options.native })), reader: options.reader ?? (settings => createNativeCheckedReader({ ...settings, native: options.native, randomUUID: options.randomUUID })) });
 }
+import { createDrivenResourceGroup } from './resource-group-driver.js';
+/** Requires native Group protocol support; no Wasm import or JavaScript fallback. */
+export function createNativeResourceGroupCoordinator(options) {
+    return createDrivenResourceGroup(options, request => {
+        const response = JSON.parse(options.native.call(JSON.stringify({ op: 'group', request })));
+        if (response?.ok !== true)
+            throw Error(typeof response?.error === 'string' ? response.error : 'native_response_invalid');
+        return response.value;
+    });
+}

package/dist/resource-authority-driver.d.ts

@@ -1,5 +1,6 @@
 import type { Checkpoint, Options, Plan, Runtime, RuntimeEvent } from './index.js';
 import type { CheckedReader, CheckedReaderOptions } from './checked-reader.js';
+import type { ResourceGroupCoordinator } from './resource-group-driver.js';
 export interface ResourceIdentity {
     binding: string;
     resourceId: string;
@@ -8,6 +9,7 @@ export interface ResourceIdentity {
 export interface ResourceReadInput<T = unknown> extends ResourceIdentity {
     content: string;
     target?: T;
+    resourceGroupId?: string;
 }
 export type ResourceAuthorityPhase = 'idle' | 'checking' | 'allowed' | 'revalidate' | 'denied' | 'expired' | 'closed';
 export type ResourceAuthorityReason = 'initial' | 'check_started' | 'online_grant' | 'offline_grant' | 'revalidation_required' | 'server_denied' | 'deadline_elapsed' | 'context_changed' | 'clock_discontinuity' | 'check_failed' | 'purge_blocked' | 'closed' | 'evicted';
@@ -37,6 +39,16 @@ export interface ResourceReadLease {
     validForMs: number;
     expiresAt: number;
 }
+export type CachedItemResult = {
+    status: 'allowed';
+    lease: ResourceReadLease;
+} | {
+    status: 'denied';
+    reason: 'access_denied';
+} | {
+    status: 'unavailable';
+    reason: 'permit_missing' | 'expired' | 'content_changed' | 'check_in_progress' | 'context_changed' | 'revalidation_required' | 'storage_failed';
+};
 type Response = {
     status: number;
     json(): Promise<unknown>;
@@ -65,6 +77,8 @@ export interface ResourceAuthorityOptions<T = unknown> {
             cursor: string;
         }): Promise<Response>;
     };
+    /** Mutually exclusive with the legacy per-Resource feed. Own/close this coordinator at host scope. */
+    groups?: ResourceGroupCoordinator;
     /** Trusted host storage proof, never a renderer-provided flag. Does not grant or renew. */
     ownsContent?(input: ResourceReadInput<T>): Promise<boolean>;
     onGranted?(input: ResourceReadInput<T>): Promise<void>;
@@ -84,6 +98,7 @@ export interface ResourceAuthorityOptions<T = unknown> {
 export interface ResourceAuthority<T = unknown> {
     readWithPermit(input: ResourceReadInput<T>): Promise<ResourceReadLease>;
     readCachedWithPermit(input: ResourceReadInput<T>): Promise<ResourceReadLease>;
+    readCachedManyWithPermit(inputs: readonly ResourceReadInput<T>[]): Promise<CachedItemResult[]>;
     /** Drops the old in-memory permit; only a fresh online full check can succeed. */
     revalidate(input: ResourceReadInput<T>): Promise<ResourceReadLease>;
     getState(input: ResourceIdentity): ResourceAuthorityState;

package/dist/resource-authority-driver.js

@@ -1,7 +1,7 @@
 import { createDrivenResourceChangeTracker } from './resource-change-tracker-driver.js';
 /** Bounded multi-resource coordination of Rust readers, durable cursors and host-owned replicas. */
 export function createDrivenResourceAuthority(options) {
-    if (options.changes && typeof options.onDenied !== 'function' || (options.runtime === undefined) !== (options.reader === undefined))
+    if (options.changes && typeof options.onDenied !== 'function' || options.changes && options.groups || (options.runtime === undefined) !== (options.reader === undefined))
         throw Error('authz_authority_config_invalid');
     const clone = options.clone ?? structuredClone;
     const readers = new Map();
@@ -104,6 +104,7 @@ export function createDrivenResourceAuthority(options) {
         readers.delete(key);
         entry?.reader?.close();
         entry?.tracker?.close();
+        entry?.groupOff?.();
         if (reason === 'evicted')
             observations.delete(key);
     };
@@ -141,14 +142,24 @@ export function createDrivenResourceAuthority(options) {
                     const version = owned.version;
                     return options.reader({ binding: input.binding, resourceId: resource, scopeId: input.scopeId, session: options.session, clock: options.clock, wasmBytes: options.wasmBytes, onEvent: runtimeEvent,
                         storage: { load: () => options.storage.load('reader', resource), commit: plan => options.storage.commit('reader', resource, plan) },
-                        check: async ({ requestId }) => { owned.readContent = undefined; try {
-                            return await options.check(owned.input, requestId);
-                        }
-                        catch (error) {
-                            if ((error instanceof TypeError || error?.name === 'TimeoutError') && owned.grantedContent && owned.input.content !== owned.grantedContent && await options.ownsContent?.(owned.input))
-                                owned.readContent = owned.grantedContent;
-                            throw error;
-                        } }, read: async () => owned.readContent ?? owned.input.content, contentHash: options.hash, }).then(reader => { if (closed || readers.get(key) !== owned || version !== owned.version) {
+                        check: async ({ requestId }) => {
+                            owned.readContent = undefined;
+                            owned.groupAnchor = undefined;
+                            try {
+                                const response = await options.check(owned.input, requestId);
+                                if (options.groups && response.status === 200) {
+                                    const body = await response.json();
+                                    owned.groupAnchor = await options.groups.acceptCheck({ ...owned.input, resourceGroupId: owned.input.resourceGroupId }, body?.resourceGroup);
+                                    return { status: response.status, json: async () => body };
+                                }
+                                return response;
+                            }
+                            catch (error) {
+                                if ((error instanceof TypeError || error?.name === 'TimeoutError') && owned.grantedContent && owned.input.content !== owned.grantedContent && await options.ownsContent?.(owned.input))
+                                    owned.readContent = owned.grantedContent;
+                                throw error;
+                            }
+                        }, read: async () => owned.readContent ?? owned.input.content, contentHash: options.hash, }).then(reader => { if (closed || readers.get(key) !== owned || version !== owned.version) {
                         reader.close();
                         throw Error('context_changed');
                     } owned.reader = reader; return reader; });
@@ -202,6 +213,8 @@ export function createDrivenResourceAuthority(options) {
                 void owned.trackerReady.catch(() => { });
             }
         }
+        if (entry.input.resourceGroupId !== input.resourceGroupId)
+            throw Error('group_membership_changed');
         if (entry.pending) {
             if (cached)
                 throw Error('check_in_progress');
@@ -219,6 +232,46 @@ export function createDrivenResourceAuthority(options) {
         const valid = () => { if (closed || readers.get(key) !== owned || owned.version !== turn)
             throw Error('context_changed'); };
         const run = Promise.resolve().then(async () => {
+            if (options.groups) {
+                if (!input.resourceGroupId)
+                    throw Error('group_identity_invalid');
+                const groupInput = { ...input, resourceGroupId: input.resourceGroupId };
+                if (!owned.groupOff)
+                    owned.groupOff = await options.groups.register(groupInput, action => {
+                        owned.version++;
+                        owned.reader?.close();
+                        owned.reader = undefined;
+                        owned.ready = undefined;
+                        owned.grantedContent = undefined;
+                        owned.groupStamp = undefined;
+                        publish(record, action === 'revoke' ? 'denied' : 'revalidate', action === 'revoke' ? 'server_denied' : 'revalidation_required');
+                        try {
+                            void Promise.resolve(options.onInvalidated?.(owned.input)).catch(() => { });
+                        }
+                        catch { }
+                    });
+                if (closed || readers.get(key) !== owned) {
+                    owned.groupOff?.();
+                    owned.groupOff = undefined;
+                    throw Error('context_changed');
+                }
+                if (owned.groupStamp) {
+                    try {
+                        await options.groups.guard(groupInput, owned.groupStamp);
+                    }
+                    catch (error) {
+                        owned.reader?.close();
+                        owned.reader = undefined;
+                        owned.ready = undefined;
+                        owned.grantedContent = undefined;
+                        owned.groupStamp = undefined;
+                        if (cached)
+                            throw error;
+                    }
+                }
+                else if (cached)
+                    throw Error('authz_cached_permit_missing');
+            }
             if (strict) {
                 owned.version++;
                 owned.reader?.close();
@@ -259,6 +312,17 @@ export function createDrivenResourceAuthority(options) {
                 await effect(owned, async () => { valid(); await options.onGranted?.(owned.input); valid(); });
                 owned.grantedContent = owned.input.content;
             }
+            if (options.groups) {
+                const groupInput = { ...input, resourceGroupId: input.resourceGroupId };
+                if (!cached && !result.offline) {
+                    if (!owned.groupAnchor)
+                        throw Error('group_revalidation_required');
+                    owned.groupStamp = await options.groups.granted(groupInput, owned.groupAnchor);
+                }
+                if (!owned.groupStamp)
+                    throw Error('group_revalidation_required');
+                await options.groups.guard(groupInput, owned.groupStamp);
+            }
             if (closed || readers.get(key) !== owned)
                 throw Error('context_changed');
             const now = options.clock();
@@ -303,6 +367,101 @@ export function createDrivenResourceAuthority(options) {
         return complete;
     };
     const api = { readWithPermit: input => verify(input), readCachedWithPermit: input => verify(input, true), revalidate: input => verify(input, false, true),
+        async readCachedManyWithPermit(inputs) {
+            if (!Array.isArray(inputs) || inputs.length > 64)
+                throw Error('authz_batch_invalid');
+            let bytes = 0;
+            const snapshot = clone(inputs);
+            for (const input of snapshot) {
+                keyOf(input);
+                if (typeof input.content !== 'string' || !input.content.length || input.content.length > 1048576)
+                    throw Error('authz_batch_invalid');
+                let itemBytes = 0;
+                // UTF-8 byte length without browser-only globals (native/Hermes uses this same path).
+                for (const point of input.content) {
+                    const code = point.codePointAt(0);
+                    itemBytes += code <= 0x7f ? 1 : code <= 0x7ff ? 2 : code <= 0xffff ? 3 : 4;
+                }
+                bytes += itemBytes;
+                if (itemBytes > 1048576)
+                    throw Error('authz_batch_invalid');
+                if (bytes > 4194304)
+                    throw Error('authz_batch_invalid');
+            }
+            const started = options.clock(), actor = clone(await options.session()), results = new Array(snapshot.length), deadlines = new Array(snapshot.length), fences = new Array(snapshot.length);
+            const classify = (error, input) => {
+                const message = error?.message;
+                const state = observations.get(keyOf(input))?.state;
+                if (message === 'authz_check_denied' || state?.phase === 'denied' && state.reason === 'server_denied')
+                    return { status: 'denied', reason: 'access_denied' };
+                return { status: 'unavailable', reason: message === 'authz_cached_permit_missing' ? 'permit_missing' : message === 'authz_offline_expired' ? 'expired' : message === 'authz_content_changed' ? 'content_changed' : message === 'check_in_progress' ? 'check_in_progress' : message === 'context_changed' || message === 'clock_discontinuity' ? 'context_changed' : message?.startsWith('group_') || message === 'runtime_unavailable' ? 'revalidation_required' : 'storage_failed' };
+            };
+            // Keep duplicates in one lane; each Resource's own reader serializes access.
+            const lanes = new Map();
+            snapshot.forEach((input, index) => { const key = keyOf(input); const lane = lanes.get(key) ?? []; lane.push(index); lanes.set(key, lane); });
+            const jobs = [...lanes.values()];
+            let at = 0;
+            await Promise.all(Array.from({ length: Math.min(8, jobs.length) }, async () => { while (at < jobs.length) {
+                const indices = jobs[at++];
+                for (const index of indices) {
+                    try {
+                        const lease = await verify(snapshot[index], true);
+                        results[index] = { status: 'allowed', lease };
+                        deadlines[index] = options.clock().now_ms + lease.validForMs;
+                    }
+                    catch (error) {
+                        results[index] = classify(error, snapshot[index]);
+                    }
+                }
+            } }));
+            for (let index = 0; index < snapshot.length; index++)
+                if (results[index]?.status === 'allowed') {
+                    try {
+                        const lease = await verify(snapshot[index], true);
+                        results[index] = { status: 'allowed', lease };
+                        deadlines[index] = Math.min(deadlines[index], options.clock().now_ms + lease.validForMs);
+                        const entry = readers.get(keyOf(snapshot[index]));
+                        fences[index] = { entry, version: entry?.version };
+                    }
+                    catch (error) {
+                        results[index] = classify(error, snapshot[index]);
+                    }
+                }
+            if (options.groups) {
+                const protectedItems = snapshot.map((input, index) => ({ input, index, entry: readers.get(keyOf(input)) })).filter(value => results[value.index]?.status === 'allowed');
+                try {
+                    const decisions = await options.groups.guardMany(protectedItems.map(({ input, entry }) => ({ input: { ...input, resourceGroupId: input.resourceGroupId }, stamp: entry?.groupStamp })));
+                    protectedItems.forEach((item, i) => { if (!decisions[i])
+                        results[item.index] = { status: 'unavailable', reason: 'revalidation_required' }; });
+                }
+                catch {
+                    for (const item of protectedItems)
+                        results[item.index] = { status: 'unavailable', reason: 'storage_failed' };
+                }
+            }
+            const current = await options.session(), now = options.clock();
+            const changed = closed || current.binding !== actor.binding || current.context !== actor.context || !actor.context || !Number.isSafeInteger(current.expiresAtMs) || !Number.isSafeInteger(actor.expiresAtMs) || now.wall_ms >= Math.min(current.expiresAtMs, actor.expiresAtMs) || now.boot !== started.boot || now.now_ms < started.now_ms || now.wall_ms < started.wall_ms;
+            if (changed)
+                return results.map(() => ({ status: 'unavailable', reason: 'context_changed' }));
+            const storageFailed = results.some(result => result.status === 'unavailable' && result.reason === 'storage_failed');
+            for (let i = 0; i < results.length; i++) {
+                const result = results[i];
+                if (result?.status !== 'allowed')
+                    continue;
+                if (storageFailed) {
+                    results[i] = { status: 'unavailable', reason: 'storage_failed' };
+                    continue;
+                }
+                const entry = readers.get(keyOf(snapshot[i])), fence = fences[i];
+                if (!entry || entry !== fence?.entry || entry.version !== fence.version) {
+                    results[i] = { status: 'unavailable', reason: 'revalidation_required' };
+                    continue;
+                }
+                const remaining = Math.floor(Math.min(deadlines[i] - now.now_ms, result.lease.expiresAt - now.wall_ms, current.expiresAtMs - now.wall_ms));
+                results[i] = remaining > 0 ? { status: 'allowed', lease: { allowed: true, validForMs: remaining, expiresAt: Math.min(result.lease.expiresAt, now.wall_ms + remaining) } } : { status: 'unavailable', reason: 'expired' };
+            }
+            return results;
+        },
         getState(input) { const key = keyOf(input), record = observations.get(key); return record ? sample(record) : initial(closed ? 'closed' : 'idle', closed ? 'closed' : 'initial'); },
         subscribe(input, listener) { if (typeof listener !== 'function')
             throw Error('authz_observer_invalid'); if (closed) {
@@ -314,6 +473,8 @@ export function createDrivenResourceAuthority(options) {
             record.timer = undefined;
         } }; },
         async catchUp() {
+            if (options.groups)
+                return options.groups.catchUp();
             if (polling)
                 return polling;
             const task = (async () => { let failure; const entries = [...readers.values()].filter(entry => entry.trackerReady); for (let index = 0; index < entries.length; index += 8) {

package/dist/resource-group-driver.d.ts

@@ -0,0 +1,119 @@
+/** Versioned host ports. Group metadata fences Resource permits; it never grants content. */
+export interface ResourceGroup {
+    binding: string;
+    resourceGroupId: string;
+}
+export interface GroupPosition {
+    epoch: string;
+    sequence: string;
+    cursor: string;
+}
+export interface GroupAnchor {
+    resourceGroupId: string;
+    epoch: string;
+    sequence: string;
+}
+export interface GroupCheckpoint extends ResourceGroup, GroupPosition {
+    schemaVersion: 2;
+    kind: 'resource_group';
+    generation: string;
+    revision: string;
+    resources: Record<string, {
+        grantGeneration: string | null;
+        intent: 'revoke' | 'revalidate' | null;
+    }>;
+}
+export interface GroupRow {
+    term: string;
+    owner: {
+        id: string;
+        context: string;
+        until: number;
+    } | null;
+    state: GroupCheckpoint | null;
+}
+export interface GroupCoordinationStorage {
+    read(key: string): Promise<GroupRow | null>;
+    /** One readonly transaction for the batch's common shared-store boundary. */
+    readMany(keys: readonly string[]): Promise<(GroupRow | null)[]>;
+    /** Runs a synchronous callback in a serializable durable transaction. No shared mutable references. */
+    transaction<T>(key: string, work: (row: GroupRow | null) => {
+        row: GroupRow;
+        result: T;
+    }): Promise<T>;
+}
+export interface GroupStamp extends ResourceGroup {
+    generation: string;
+    term: string;
+    epoch: string;
+    sequence: string;
+}
+export interface GroupNotice extends ResourceGroup {
+    schemaVersion: 1;
+    namespace: string;
+    term: string;
+    revision: string;
+}
+type Reply = {
+    status: number;
+    json(): Promise<unknown>;
+};
+export interface ResourceGroupOptions {
+    namespace: string;
+    storage: GroupCoordinationStorage;
+    session(): Promise<{
+        binding: string;
+        context: string;
+        expiresAtMs: number;
+    }>;
+    wall(): number;
+    randomUUID(): string;
+    transport: {
+        subscribe(group: ResourceGroup, requestId: string): Promise<Reply>;
+        fetch(group: ResourceGroup, query: {
+            requestId: string;
+            cursor: string;
+        }): Promise<Reply>;
+    };
+    /** Must compare expected term/generation inside the host's deletion transaction. */
+    purge(input: ResourceGroup & {
+        resourceId: string;
+        action: 'revoke' | 'revalidate';
+        expected: GroupStamp;
+        assertCurrent(): Promise<void>;
+    }): Promise<{
+        status: 'purged' | 'blocked';
+    }>;
+    notify?(notice: GroupNotice): void | Promise<void>;
+    listen?(receive: (notice: unknown) => void): () => void;
+    pollIntervalMs?: number;
+    ownerLeaseMs?: number;
+    clone?<T>(value: T): T;
+}
+export interface ResourceGroupCoordinator {
+    register(input: ResourceGroup & {
+        resourceId: string;
+    }, invalidate?: (action: 'revoke' | 'revalidate') => void): Promise<() => void>;
+    prepare(group: ResourceGroup): Promise<GroupStamp>;
+    catchUp(group?: ResourceGroup): Promise<void>;
+    acceptCheck(input: ResourceGroup & {
+        resourceId: string;
+    }, anchor: GroupAnchor): Promise<GroupAnchor>;
+    granted(input: ResourceGroup & {
+        resourceId: string;
+    }, anchor: GroupAnchor): Promise<GroupStamp>;
+    guard(input: ResourceGroup & {
+        resourceId: string;
+    }, stamp: GroupStamp): Promise<void>;
+    guardMany(inputs: readonly {
+        input: ResourceGroup & {
+            resourceId: string;
+        };
+        stamp: GroupStamp;
+    }[]): Promise<boolean[]>;
+    stamp(group: ResourceGroup): Promise<GroupStamp>;
+    close(): Promise<void>;
+}
+/** Runtime-neutral orchestration; the synchronous dispatch port executes real Rust. */
+export declare function createDrivenResourceGroup(options: ResourceGroupOptions, dispatch: (request: unknown) => unknown): ResourceGroupCoordinator;
+export {};

package/dist/resource-group-driver.js

@@ -0,0 +1,370 @@
+/** Runtime-neutral orchestration; the synchronous dispatch port executes real Rust. */
+export function createDrivenResourceGroup(options, dispatch) {
+    const clone = options.clone ?? ((v) => JSON.parse(JSON.stringify(v)));
+    const validId = (v) => typeof v === 'string' && v.length > 0 && v.length <= 4096;
+    if (!validId(options.namespace) || !options.storage || !options.purge)
+        throw Error('group_config_invalid');
+    const lease = options.ownerLeaseMs ?? 15000, interval = options.pollIntervalMs ?? 5000;
+    if (!Number.isSafeInteger(lease) || lease < 1000 || lease > 60000 || !Number.isSafeInteger(interval) || interval < 0 || interval >= lease)
+        throw Error('group_config_invalid');
+    const owner = options.randomUUID();
+    if (!validId(owner))
+        throw Error('group_config_invalid');
+    const groups = new Map(), membership = new Map();
+    let closed = false, lastWall = -1;
+    const clock = () => {
+        const value = options.wall();
+        if (!Number.isSafeInteger(value) || value < 0 || value < lastWall)
+            throw Error('clock_discontinuity');
+        lastWall = value;
+        return value;
+    };
+    const entry = (input) => {
+        if (closed)
+            throw Error('context_changed');
+        if (!input || !validId(input.binding) || !validId(input.resourceGroupId))
+            throw Error('group_identity_invalid');
+        const group = { binding: input.binding, resourceGroupId: input.resourceGroupId };
+        const key = JSON.stringify([options.namespace, 2, group.binding, group.resourceGroupId]);
+        let e = groups.get(key);
+        if (!e) {
+            if (groups.size >= 64)
+                throw Error('group_capacity');
+            e = { group, key, tail: Promise.resolve(), listeners: new Map() };
+            groups.set(key, e);
+        }
+        return e;
+    };
+    const current = async (e) => {
+        const actor = clone(await options.session());
+        if (closed || actor.binding !== e.group.binding || !validId(actor.context) || !Number.isSafeInteger(actor.expiresAtMs) || actor.expiresAtMs <= clock() || e.context && e.context !== actor.context)
+            throw Error('context_changed');
+        e.context ??= actor.context;
+        return actor;
+    };
+    const rust = (op, fields) => dispatch({ op, ...fields });
+    const stateOf = (e, row) => {
+        if (!row?.state || row.state.binding !== e.group.binding || row.state.resourceGroupId !== e.group.resourceGroupId)
+            throw Error('group_revalidation_required');
+        // The Rust guard validates the entire persisted checkpoint, even when no Resource is resident.
+        dispatch({ op: 'guard', state: row.state, resourceId: '', generation: row.state.generation });
+        if (!/^(0|[1-9][0-9]*)$/.test(row.term) || BigInt(row.term) > 18446744073709551615n)
+            throw Error('group_state_invalid');
+        if (row.owner && (!validId(row.owner.id) || !validId(row.owner.context) || !Number.isSafeInteger(row.owner.until) || row.owner.until < 0))
+            throw Error('group_state_invalid');
+        return row.state;
+    };
+    const makeStamp = (e, row) => {
+        const s = stateOf(e, row);
+        return { ...e.group, generation: s.generation, term: row.term, epoch: s.epoch, sequence: s.sequence };
+    };
+    const observed = (e, state, term) => {
+        const fence = JSON.stringify([term, state.generation]);
+        if (e.observed === fence)
+            return;
+        e.observed = fence;
+        for (const [id, listeners] of e.listeners) {
+            // Another process's fresh grant cannot revive this process's old permit or display.
+            const action = state.resources[id]?.intent ?? 'revalidate';
+            for (const listener of listeners) {
+                try {
+                    listener(action);
+                }
+                catch { /* Store fence remains authoritative. */ }
+            }
+        }
+    };
+    const announce = (e, row) => {
+        const state = stateOf(e, row);
+        observed(e, state, row.term);
+        try {
+            void Promise.resolve(options.notify?.({ schemaVersion: 1, namespace: options.namespace, ...e.group, term: row.term, revision: state.revision })).catch(() => { });
+        }
+        catch { /* Wakeups cannot change decisions. */ }
+    };
+    const serial = (e, work) => {
+        const task = e.tail.then(work);
+        e.tail = task.catch(() => { });
+        return task;
+    };
+    const owned = (e, row, term) => {
+        if (!row?.owner || row.owner.id !== owner || row.owner.context !== e.context || row.term !== term || row.owner.until <= clock())
+            throw Error('group_owner_changed');
+    };
+    const claim = async (e) => {
+        const actor = await current(e), now = clock();
+        return options.storage.transaction(e.key, saved => {
+            if (closed)
+                throw Error('context_changed');
+            const row = clone(saved ?? { term: '0', owner: null, state: null });
+            if (row.owner && row.owner.until > now && (row.owner.id !== owner || row.owner.context !== actor.context))
+                return { row, result: null };
+            if (!row.owner || row.owner.until <= now || row.owner.id !== owner || row.owner.context !== actor.context) {
+                const next = BigInt(row.term) + 1n;
+                if (next > 18446744073709551615n)
+                    throw Error('group_capacity');
+                row.term = String(next);
+            }
+            row.owner = { id: owner, context: actor.context, until: Math.min(now + lease, actor.expiresAtMs) };
+            return { row, result: row.term };
+        });
+    };
+    const update = async (e, term, work) => {
+        await current(e);
+        const row = await options.storage.transaction(e.key, saved => {
+            owned(e, saved, term);
+            const row = clone(saved);
+            row.state = work(row.state);
+            return { row, result: row };
+        });
+        await current(e);
+        announce(e, row);
+        return row;
+    };
+    const subscribe = async (e, term) => {
+        const requestId = options.randomUUID(), reply = await options.transport.subscribe(e.group, requestId);
+        await current(e);
+        if (reply.status !== 200)
+            throw Error('group_subscribe_failed');
+        const body = await reply.json();
+        await current(e);
+        if (body?.schemaVersion !== 2 || body.kind !== 'resource_group' || body.requestId !== requestId || body.binding !== e.group.binding || body.resourceGroupId !== e.group.resourceGroupId)
+            throw Error('group_response_invalid');
+        return update(e, term, state => state ? rust('reset', { state, position: body.position }) : rust('initialize', { identity: e.group, position: body.position }));
+    };
+    const fence = (e, term) => update(e, term, state => {
+        if (!state)
+            throw Error('group_revalidation_required');
+        return rust('fence', { state });
+    });
+    const recover = async (e, term) => {
+        const row = await options.storage.read(e.key), state = stateOf(e, row);
+        owned(e, row, term);
+        for (const [resourceId, r] of Object.entries(state.resources)) {
+            if (!r.intent)
+                continue;
+            const expected = makeStamp(e, row);
+            try {
+                const assertCurrent = async () => {
+                    await current(e);
+                    const latest = await options.storage.read(e.key);
+                    owned(e, latest, term);
+                    const s = stateOf(e, latest);
+                    if (s.generation !== expected.generation || s.resources[resourceId]?.grantGeneration !== null || s.resources[resourceId]?.intent !== r.intent)
+                        throw Error('group_check_raced');
+                };
+                await assertCurrent();
+                const outcome = await options.purge({ ...e.group, resourceId, action: r.intent, expected, assertCurrent });
+                if (outcome?.status === 'blocked')
+                    continue;
+                if (outcome?.status !== 'purged')
+                    throw Error('group_purge_invalid');
+                await assertCurrent();
+                await update(e, term, state => rust('purged', { state, resourceId, generation: expected.generation }));
+            }
+            catch { /* Intent is durable; one blocked/failed Resource must not stall the feed. */ }
+        }
+    };
+    const pull = async (e) => {
+        const term = await claim(e);
+        if (term === null) {
+            const row = await options.storage.read(e.key);
+            observed(e, stateOf(e, row), row.term);
+            return;
+        }
+        let row = await options.storage.read(e.key);
+        if (!row?.state)
+            row = await subscribe(e, term);
+        await recover(e, term);
+        for (let page = 0; page < 32; page++) {
+            row = await options.storage.read(e.key);
+            const state = stateOf(e, row);
+            owned(e, row, term);
+            const requestId = options.randomUUID();
+            let reply;
+            try {
+                reply = await options.transport.fetch(e.group, { requestId, cursor: state.cursor });
+            }
+            catch (error) {
+                if (!(error instanceof TypeError || error?.name === 'TimeoutError'))
+                    await fence(e, term);
+                throw error;
+            }
+            await current(e);
+            if (reply.status === 409) {
+                await fence(e, term);
+                await subscribe(e, term);
+                return;
+            }
+            if (reply.status !== 200) {
+                await fence(e, term);
+                throw Error('group_fetch_failed');
+            }
+            try {
+                const body = await reply.json();
+                await current(e);
+                if (body?.schemaVersion !== 2 || body.kind !== 'resource_group' || body.requestId !== requestId || typeof body.hasMore !== 'boolean')
+                    throw Error('group_response_invalid');
+                await update(e, term, latest => {
+                    if (latest?.epoch !== state.epoch || latest.sequence !== state.sequence || latest.cursor !== state.cursor)
+                        throw Error('group_check_raced');
+                    return rust('changes', { state: latest, batch: body.batch });
+                });
+                await recover(e, term);
+                if (!body.hasMore)
+                    return;
+                if (body.batch.throughSequence === body.batch.fromSequence)
+                    throw Error('group_response_invalid');
+            }
+            catch (error) {
+                await fence(e, term);
+                throw error;
+            }
+        }
+        throw Error('group_page_limit');
+    };
+    const api = {
+        async prepare(group) {
+            const e = entry(group);
+            await current(e);
+            if (!(await options.storage.read(e.key))?.state)
+                await serial(e, () => pull(e));
+            return api.stamp(group);
+        },
+        async register(input, invalidate) {
+            const copy = clone(input);
+            if (!validId(copy.resourceId))
+                throw Error('group_resource_invalid');
+            const e = entry(copy);
+            const identity = JSON.stringify([copy.binding, copy.resourceId]), previous = membership.get(identity);
+            if (previous && previous !== e.key)
+                throw Error('group_membership_changed');
+            if (!previous && membership.size >= 64)
+                throw Error('group_capacity');
+            await api.prepare(copy);
+            await current(e);
+            const registered = await options.storage.transaction(e.key, saved => {
+                const state = stateOf(e, saved), row = clone(saved);
+                row.state = rust('register', { state, resourceId: copy.resourceId });
+                return { row, result: row };
+            });
+            observed(e, stateOf(e, registered), registered.term);
+            membership.set(identity, e.key);
+            let listeners = e.listeners.get(copy.resourceId);
+            if (!listeners) {
+                listeners = new Set();
+                e.listeners.set(copy.resourceId, listeners);
+            }
+            if (listeners.size >= 64)
+                throw Error('group_capacity');
+            const listener = invalidate ?? (() => { });
+            listeners.add(listener);
+            return () => { listeners.delete(listener); if (!listeners.size) {
+                e.listeners.delete(copy.resourceId);
+                membership.delete(identity);
+            } };
+        },
+        async catchUp(group) {
+            const entries = group ? [entry(group)] : [...groups.values()];
+            for (const e of entries) {
+                if (e.polling) {
+                    await e.polling;
+                    continue;
+                }
+                const task = serial(e, () => pull(e));
+                e.polling = task;
+                try {
+                    await task;
+                }
+                finally {
+                    if (e.polling === task)
+                        e.polling = undefined;
+                }
+            }
+        },
+        async acceptCheck(input, anchor) {
+            const copy = clone(anchor), e = entry(input);
+            await current(e);
+            if (!copy || copy.resourceGroupId !== input.resourceGroupId)
+                throw Error('group_membership_changed');
+            await api.catchUp(input);
+            const state = stateOf(e, await options.storage.read(e.key));
+            // Rust validates canonical sequences, exact identity and the server watermark; this does not commit a grant.
+            rust('grant', { state, resourceId: input.resourceId, anchor: copy });
+            return copy;
+        },
+        async granted(input, anchor) {
+            const e = entry(input);
+            await current(e);
+            const row = await options.storage.transaction(e.key, saved => {
+                const state = stateOf(e, saved), row = clone(saved);
+                row.state = rust('grant', { state, resourceId: input.resourceId, anchor });
+                return { row, result: row };
+            });
+            await current(e);
+            return makeStamp(e, row);
+        },
+        async stamp(group) { const e = entry(group); await current(e); const row = await options.storage.read(e.key); await current(e); return makeStamp(e, row); },
+        async guard(input, stamp) {
+            const e = entry(input);
+            await current(e);
+            const row = await options.storage.read(e.key);
+            await current(e);
+            const state = stateOf(e, row);
+            observed(e, state, row.term);
+            if (!stamp || stamp.binding !== input.binding || stamp.resourceGroupId !== input.resourceGroupId || stamp.epoch !== state.epoch || stamp.term !== row.term
+                || dispatch({ op: 'guard', state, resourceId: input.resourceId, generation: stamp.generation }) !== true)
+                throw Error('group_revalidation_required');
+        },
+        async guardMany(inputs) {
+            const copies = clone(inputs), entries = copies.map(value => entry(value.input));
+            for (const e of new Set(entries))
+                await current(e);
+            const rows = await options.storage.readMany(entries.map(e => e.key));
+            if (closed || rows.length !== entries.length)
+                throw Error('context_changed');
+            return copies.map(({ input, stamp }, index) => {
+                const e = entries[index], state = stateOf(e, rows[index]);
+                observed(e, state, rows[index].term);
+                return !!stamp && stamp.binding === input.binding && stamp.resourceGroupId === input.resourceGroupId && stamp.epoch === state.epoch && stamp.term === rows[index].term && dispatch({ op: 'guard', state, resourceId: input.resourceId, generation: stamp.generation }) === true;
+            });
+        },
+        async close() {
+            if (closed)
+                return;
+            closed = true;
+            clearInterval(timer);
+            off?.();
+            await Promise.allSettled([...groups.values()].map(async (e) => {
+                await options.storage.transaction(e.key, saved => {
+                    const row = clone(saved ?? { term: '0', owner: null, state: null });
+                    if (row.owner?.id === owner)
+                        row.owner = null;
+                    return { row, result: null };
+                });
+            }));
+            groups.clear();
+            membership.clear();
+        },
+    };
+    const off = options.listen?.(notice => {
+        const n = notice;
+        if (closed || n?.schemaVersion !== 1 || n.namespace !== options.namespace || !validId(n.binding) || !validId(n.resourceGroupId))
+            return;
+        const key = JSON.stringify([options.namespace, 2, n.binding, n.resourceGroupId]), e = groups.get(key);
+        if (!e)
+            return;
+        void current(e).then(() => options.storage.read(key)).then(row => observed(e, stateOf(e, row), row.term)).catch(() => {
+            for (const listeners of e.listeners.values())
+                for (const listener of listeners) {
+                    try {
+                        listener('revalidate');
+                    }
+                    catch { }
+                }
+        });
+    });
+    const timer = interval ? setInterval(() => { void api.catchUp().catch(() => { }); }, interval) : undefined;
+    timer?.unref?.();
+    return api;
+}

package/dist/resource-group.d.ts

@@ -0,0 +1,6 @@
+import { type ResourceGroupOptions } from './resource-group-driver.js';
+export type * from './resource-group-driver.js';
+/** Wasm transport only; Group protocol and transition validation execute Rust. */
+export declare function createResourceGroupCoordinator(options: ResourceGroupOptions & {
+    wasmBytes?: Uint8Array<ArrayBuffer>;
+}): Promise<import("./resource-group-driver.js").ResourceGroupCoordinator>;

package/dist/resource-group.js

@@ -0,0 +1,7 @@
+import init, { dispatch } from '../wasm/authzflow_wasm.js';
+import { createDrivenResourceGroup } from './resource-group-driver.js';
+/** Wasm transport only; Group protocol and transition validation execute Rust. */
+export async function createResourceGroupCoordinator(options) {
+    await init(options.wasmBytes ? { module_or_path: options.wasmBytes } : undefined);
+    return createDrivenResourceGroup(options, request => JSON.parse(dispatch(JSON.stringify({ op: 'group', request }))));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@authzflow/core",
-  "version": "0.1.0-alpha.8",
+  "version": "0.1.0-beta.1",
   "private": false,
   "type": "module",
   "author": "Accelflow Inc.",
@@ -36,6 +36,22 @@
     "./native-reader": {
       "types": "./dist/native-reader.d.ts",
       "import": "./dist/native-reader.js"
+    },
+    "./resource-group": {
+      "types": "./dist/resource-group.d.ts",
+      "import": "./dist/resource-group.js"
+    },
+    "./group-sqlite": {
+      "types": "./dist/group-sqlite.d.ts",
+      "import": "./dist/group-sqlite.js"
+    },
+    "./group-indexeddb": {
+      "types": "./dist/group-indexeddb.d.ts",
+      "import": "./dist/group-indexeddb.js"
+    },
+    "./group-notifications": {
+      "types": "./dist/group-notifications.d.ts",
+      "import": "./dist/group-notifications.js"
     }
   },
   "files": [