@powerhousedao/reactor 6.2.2-dev.49 → 6.2.2-dev.50

package/dist/index.js

@@ -1,10 +1,10 @@
-import { A as OptimisticLockError, B as ExcessiveReshuffleError, C as DocumentMetaCache, D as APPEND_CONDITION_FAILED_PREFIX, E as CollectionMembershipCache, F as ModuleNotFoundError, G as throwIfAborted, H as UpgradePreconditionFailedError, I as AuthTimestampNotMonotonicError, L as AuthorizationDeniedError, M as DuplicateManifestError, N as DuplicateModuleError, O as AppendConditionFailedError, P as InvalidModuleError, R as DocumentDeletedError, S as KyselyOperationIndex, T as createEmptyConsistencyToken, U as matchesScope, V as InvalidOperationTimestampError, W as parsePagingOptions, _ as KyselyExecutionScope, a as createForwardingPoolInstrumentation, b as EventBus, c as KyselyKeyframeStore, d as DriveCollectionId, f as decideAtHead, g as authDecisionModel, h as buildDecisionModel, i as runMigrations, j as RevisionMismatchError, k as DuplicateOperationError, l as DocumentModelRegistry, m as documentDecisionModel, n as REACTOR_SCHEMA, o as instrumentPgPool, p as selectDecisionModel, r as getMigrationStatus, s as KyselyOperationStore, t as DEFAULT_DRIVE_CONTAINER_TYPES, u as SimpleJobExecutor, v as FLAG_PREREQUISITES, w as createConsistencyToken, x as KyselyWriteCache, y as validateFeatureFlags, z as DocumentNotFoundError } from "./drive-container-types-h3M1AK3K.js";
+import { A as decideAtHead, B as InvalidOperationTimestampError, C as DuplicateOperationError, D as DuplicateModuleError, E as DuplicateManifestError, F as AuthTimestampNotMonotonicError, H as matchesScope, I as AuthorizationDeniedError, L as DocumentDeletedError, M as documentDecisionModel, N as authDecisionModel, O as InvalidModuleError, P as buildDecisionModel, R as DocumentNotFoundError, S as AppendConditionFailedError, T as RevisionMismatchError, U as parsePagingOptions, V as UpgradePreconditionFailedError, W as throwIfAborted, _ as DocumentMetaCache, a as createForwardingPoolInstrumentation, b as CollectionMembershipCache, c as KyselyKeyframeStore, d as DriveCollectionId, f as KyselyExecutionScope, g as KyselyOperationIndex, h as KyselyWriteCache, i as runMigrations, j as selectDecisionModel, k as ModuleNotFoundError, l as DocumentModelRegistry, m as EventBus, n as REACTOR_SCHEMA, o as instrumentPgPool, p as resolveFeatureFlags, r as getMigrationStatus, s as KyselyOperationStore, t as DEFAULT_DRIVE_CONTAINER_TYPES, u as SimpleJobExecutor, v as createConsistencyToken, w as OptimisticLockError, x as APPEND_CONDITION_FAILED_PREFIX, y as createEmptyConsistencyToken, z as ExcessiveReshuffleError } from "./drive-container-types-BoY5t12r.js";
 import { n as ReactorEventTypes, t as EventBusAggregateError } from "./types-DMKLa0Ok.js";
 import { i as WorkerInitFailedError, r as WorkerExitedError, t as WorkerAbortTimeoutError } from "./errors-D3S6Eysd.js";
-import { a as ReadModelCoordinator, i as KyselyDocumentView, n as ConsistencyTracker, o as BaseReadModel, r as makeConsistencyKey, t as KyselyDocumentIndexer } from "./document-indexer-BfdCgjG-.js";
+import { a as ReadModelCoordinator, i as KyselyDocumentView, n as ConsistencyTracker, o as BaseReadModel, r as makeConsistencyKey, t as KyselyDocumentIndexer } from "./document-indexer-DlpJB8AK.js";
 import { n as errorToInfo, r as sanitizeArg, t as createForwardingLogger } from "./forwarding-logger-BBkMSxuJ.js";
-import { t as workerEntryPath } from "./worker-CbtYMIju.js";
-import { DowngradeNotSupportedError, UnsupportedDocumentModelVersionError, actions, actions as documentActions, createPresignedHeader, decide, garbageCollect, generateId, groupDocumentType, groupMembershipActionTypes, hashDocumentStateForScope, normalizeDocumentModelVersion, sortOperations } from "@powerhousedao/shared/document-model";
+import { t as workerEntryPath } from "./worker-BCMw-hBw.js";
+import { DowngradeNotSupportedError, MAX_AUTH_GRANTS, UnsupportedDocumentModelVersionError, actions, actions as documentActions, createPresignedHeader, decide, garbageCollect, generateId, groupDocumentType, groupMembershipActionTypes, hashDocumentStateForScope, normalizeDocumentModelVersion, sortOperations } from "@powerhousedao/shared/document-model";
 import { addFile, addFolder, copyNode, deleteNode, driveCreateDocument, generateNodesCopy, getDescendants, handleTargetNameCollisions, isFileNode, isFolderNode, moveNode, updateNode } from "@powerhousedao/shared/document-drive";
 import { v4 } from "uuid";
 import { ConsoleLogger, childLogger } from "document-model";
@@ -393,7 +393,7 @@ var DriveClient = class {
 		}] }, signal);
 		const completedJobs = await Promise.all(Object.values(batchResult.jobs).map((job) => this.client.waitForJob(job, signal)));
 		for (const job of completedJobs) if (job.status === JobStatus.FAILED) throw new Error(job.error?.message);
-		return this.reactor.get(documentId);
+		return this.client.get(documentId, void 0, signal);
 	}
 	async addFolder(driveIdentifier, name, parentFolder, signal) {
 		this.logger.verbose("drives.addFolder(@driveIdentifier, @name, @parentFolder)", driveIdentifier, name, parentFolder);
@@ -402,7 +402,7 @@ var DriveClient = class {
 			id: folderId,
 			name,
 			parentFolder
-		})], signal)).state.global.nodes.find((n) => n.id === folderId);
+		})], signal)).state.global?.nodes.find((n) => n.id === folderId);
 		if (!node || !isFolderNode(node)) throw new Error("Folder creation failed");
 		return node;
 	}
@@ -429,7 +429,7 @@ var DriveClient = class {
 		const node = (await this.client.execute(driveIdentifier, "main", [updateNode({
 			id: nodeId,
 			name
-		})], signal)).state.global.nodes.find((n) => n.id === nodeId);
+		})], signal)).state.global?.nodes.find((n) => n.id === nodeId);
 		if (!node) throw new Error("Node missing from drive after rename");
 		return node;
 	}
@@ -686,20 +686,267 @@ let DocumentChangeType = /* @__PURE__ */ function(DocumentChangeType) {
 	return DocumentChangeType;
 }({});
 //#endregion
-//#region src/client/util.ts
+//#region src/decision/read-gate.ts
+/**
+* Scopes every holder of a document may read, whatever the grants say. Denying
+* the policy itself would let a replica sync a document without it, read the
+* auth scope as uninitialized, and allow every operation it holds, so replicas
+* would diverge permanently. The document scope carries the metadata the same
+* argument covers. Grants gate domain-scope reads only.
+*/
 const ALWAYS_READABLE_SCOPES = new Set(["auth", "document"]);
+/**
+* The branch a group is read on. A group's member list lives on its main
+* branch whatever branch the document naming it is on, and the reference
+* relation records no branch of its own.
+*/
+const GROUP_BRANCH = "main";
+/**
+* The scope of a group document that holds its member list. It is the only
+* scope group serving reaches, because it is the only one the audience must
+* fold in order to evaluate auth with the group.
+*/
+const GROUP_MEMBERSHIP_SCOPE = "global";
+/**
+* How many of a group's referencing documents are examined before a read of
+* that group gives up and withholds. Each one costs a model build, and the
+* relation is append-only, so an old and briefly-held reference still counts.
+* Truncating denies, which is the direction that withholds. It is the cap a
+* version-1 policy carries on its own grant list, taken from there rather than
+* restated: raising that cap raises the read fan-out here.
+*/
+const MAX_EXAMINED_REFERENCERS = MAX_AUTH_GRANTS;
+/**
+* How many referencers are probed at once. The reactor's Postgres pool size is
+* optional and defaults to ten, and a listing resolves one gate per result, so
+* per-gate fan-out multiplies: a handful keeps one group read from claiming the
+* whole pool while still cutting the walk several times over. On PGlite the
+* queries serialize regardless, so a larger number buys nothing in a browser.
+*/
+const REFERENCER_PROBE_CONCURRENCY = 4;
+/**
+* The policy carried on a document, if it carries one. A document handed to the
+* gate with no state at all is not policied, so it is not gated.
+*/
+function authOf(document) {
+	return document.state?.auth;
+}
+/**
+* The model reads enforce. Below `authEnforcement` there is no model to
+* enforce: the document-only model ignores the auth scope entirely, so reading
+* through it would serve every domain scope of a policied document to anyone.
+* Undefined therefore means "evaluate the policy alone", which is what the read
+* surface did before the model existed.
+*/
+function readDecisionModel(flags, registry) {
+	return flags.authEnforcement ? selectDecisionModel(flags, registry) : void 0;
+}
+/**
+* Evaluates the policy on its own, with no groups map and no condition context.
+* A `{ group }` or conditional grant therefore never applies: an allow that
+* does not apply withholds access, so this cannot widen a policy, but a policy
+* relying on a conditional deny is weaker here than it is written.
+*/
+var BareReadGate = class {
+	scopePredicate(document, subject) {
+		const auth = authOf(document);
+		return Promise.resolve((scope) => ALWAYS_READABLE_SCOPES.has(scope) || decide(auth, subject, {
+			verb: "read",
+			scope
+		}) === "allow");
+	}
+};
+/**
+* Answers a stream read from the document already fetched, and anything else
+* through the read side.
+*
+* The seed is why routing reads through a decision model costs no extra I/O for
+* the document being read: its `document` and `auth` scopes are the two static
+* projections, and the caller has both in hand. Only a group stream the grant
+* list names is fetched.
+*/
+var SeededStateReader = class {
+	constructor(documentView, seed, branch) {
+		this.documentView = documentView;
+		this.seed = seed;
+		this.branch = branch;
+	}
+	/**
+	* A stream this replica does not hold has to reach buildDecisionModel as the
+	* absence it recognises, or the whole read fails instead of leaving the group
+	* out of the model, where its principal does not match and the policy fails
+	* closed. The read side reports absence as a plain Error, so the absence is
+	* confirmed rather than inferred from the message: a transient failure must
+	* surface, not silently deny.
+	*/
+	async getState(documentId, scope, branch, targetRevision, signal) {
+		if (targetRevision === void 0 && documentId === this.seed.header.id && branch === this.branch && scope in this.seed.state) return this.seed;
+		try {
+			return await this.documentView.get(documentId, {
+				branch,
+				scopes: [scope]
+			}, void 0, signal);
+		} catch (error) {
+			await this.assertAbsent(documentId, error, signal);
+			throw new DocumentNotFoundError(documentId);
+		}
+	}
+	async assertAbsent(documentId, error, signal) {
+		if (DocumentNotFoundError.isError(error)) return;
+		let exists;
+		try {
+			exists = await this.documentView.exists([documentId], void 0, signal);
+		} catch {
+			throw error;
+		}
+		if (exists[0]) throw error;
+	}
+};
+/**
+* Evaluates a read against the registered decision model, built at the stream
+* heads. This is what makes `{ group }` principals and conditional grants apply
+* to a read: the model supplies the groups map and the scope's own state, the
+* same two things admission supplies.
+*
+* A read has no action, so a condition on `action.input.*` never holds for one.
+*
+* State is read through the read side rather than the write cache. The write
+* cache is invalidated by whichever process runs the executor, so a reactor
+* running its executors in worker processes would answer reads in the parent
+* from state no commit ever invalidates.
+*/
+var ModelReadGate = class {
+	constructor(model, documentView, servesGroups, operationIndex, logger) {
+		this.model = model;
+		this.documentView = documentView;
+		this.servesGroups = servesGroups;
+		this.operationIndex = operationIndex;
+		this.logger = logger;
+	}
+	/**
+	* A served group yields its member list and nothing else. What the audience
+	* is owed is the state it must fold to evaluate auth with the group; a
+	* group's other scopes are its own business and stay behind its own grants.
+	*/
+	async scopePredicate(document, subject, branch, signal) {
+		const own = await this.ownPolicyPredicate(document, subject, branch, signal);
+		if (!this.servesGroup(document) || own(GROUP_MEMBERSHIP_SCOPE)) return own;
+		const audience = await this.servesGroupTo(document.header.id, subject, signal);
+		return (scope) => own(scope) || audience && scope === GROUP_MEMBERSHIP_SCOPE;
+	}
+	/**
+	* Whether the subject is served this group because a policy names it.
+	*
+	* A replica must fold a group's membership to evaluate auth with it, so a
+	* group a grant names is served to the audience of the document that names
+	* it, whatever the group's own read grants say. Naming a group in a policy
+	* publishes its roster to that policy's audience; a group whose membership
+	* must stay confidential does not belong in a grant.
+	*
+	* The referencing document's own domain scopes are the test. Its `auth` and
+	* `document` scopes are readable by every holder, so testing those would
+	* serve every referenced group to everybody.
+	*
+	* One level only. A referencer that is itself a group is skipped, and a
+	* referencer's own readability is decided from its policy alone, so a
+	* reference cycle terminates. Cycles are reachable: the reference relation
+	* is recorded from an operation's input, including one later stored denied,
+	* so a refused grant naming a group from inside another group leaves a row
+	* behind that validation never saw.
+	*
+	* The referencers are probed a few at a time and the walk stops at the first
+	* that serves, because a subject outside the audience is the case that runs to
+	* the bound, and it is the common one. A probe that failed decides only when
+	* nothing served: serving rests on a real allow, so this cannot widen, and it
+	* stops one unreachable referencer from turning an allow already in hand into
+	* a denial. A read records no operation, so replicas differing over a
+	* transient failure has no consensus consequence.
+	*
+	* The probes are awaited together rather than raced, so none is ever left
+	* running with nobody awaiting it, which is where unhandled rejections come
+	* from.
+	*/
+	async servesGroupTo(groupId, subject, signal) {
+		if (!this.operationIndex) return false;
+		const referencers = await this.operationIndex.getGroupReferencers(groupId, signal);
+		const examined = referencers.slice(0, MAX_EXAMINED_REFERENCERS);
+		if (examined.length < referencers.length) this.logger?.warn(`Group ${groupId} is referenced by ${referencers.length} documents; only the first ${MAX_EXAMINED_REFERENCERS} decide whether it is served`);
+		const walk = {
+			next: 0,
+			served: false,
+			failure: void 0
+		};
+		const probe = async () => {
+			while (!walk.served && walk.next < examined.length) {
+				const referencerId = examined[walk.next++];
+				let serves = false;
+				try {
+					serves = await this.servesThrough(referencerId, subject, signal);
+				} catch (error) {
+					walk.failure ??= Error.isError(error) ? error : /* @__PURE__ */ new Error(`Probing referencer ${referencerId} failed`);
+				}
+				if (serves) walk.served = true;
+			}
+		};
+		await Promise.all(Array.from({ length: Math.min(REFERENCER_PROBE_CONCURRENCY, examined.length) }, probe));
+		if (!walk.served && walk.failure) throw walk.failure;
+		return walk.served;
+	}
+	/**
+	* Whether one referencing document serves the subject any domain scope. A
+	* referencer this replica does not hold serves nothing, which fails closed
+	* the same way a group it does not hold does.
+	*/
+	async servesThrough(referencerId, subject, signal) {
+		let referencer;
+		try {
+			referencer = await this.documentView.get(referencerId, { branch: GROUP_BRANCH }, void 0, signal);
+		} catch {
+			return false;
+		}
+		if (this.servesGroup(referencer)) return false;
+		const readable = await this.ownPolicyPredicate(referencer, subject, GROUP_BRANCH, signal);
+		return Object.keys(referencer.state ?? {}).filter((scope) => !ALWAYS_READABLE_SCOPES.has(scope)).some((scope) => readable(scope));
+	}
+	servesGroup(document) {
+		return this.servesGroups && this.operationIndex !== void 0 && document.header.documentType === groupDocumentType;
+	}
+	/**
+	* What this document's own policy says, with no group serving applied.
+	*
+	* An unpoliced document is readable in full, which is the common case and the
+	* one worth answering without building anything. The test is the one
+	* `evaluate` makes: a legacy `{}` auth scope and version 0 both mean
+	* uninitialized, and "no grants" does not, because a policy with a version and
+	* an empty grant list denies everything.
+	*/
+	async ownPolicyPredicate(document, subject, branch, signal) {
+		const auth = authOf(document);
+		if (!auth || !auth.version) return () => true;
+		const target = {
+			documentId: document.header.id,
+			branch
+		};
+		const built = await buildDecisionModel(new SeededStateReader(this.documentView, document, branch), this.model, target, signal);
+		const definition = this.model(target);
+		const scopeStates = document.state ?? {};
+		return (scope) => ALWAYS_READABLE_SCOPES.has(scope) || definition.decide(built.model, subject, {
+			verb: "read",
+			scope
+		}, {
+			scopeState: scopeStates[scope],
+			actionInput: void 0
+		}).decision === "allow";
+	}
+};
+//#endregion
+//#region src/client/util.ts
 function authSubjectFromSigner(signer) {
 	return {
 		address: signer.user?.address,
 		key: signer.app?.key
 	};
 }
-function canReadScope(auth, subject, scope) {
-	return ALWAYS_READABLE_SCOPES.has(scope) || decide(auth, subject, {
-		verb: "read",
-		scope
-	}) === "allow";
-}
 function withAuthScope(view) {
 	if (view?.scopes && view.scopes.length > 0) return {
 		...view,
@@ -707,11 +954,14 @@ function withAuthScope(view) {
 	};
 	return view;
 }
-function filterReadableScopes(document, subject) {
+/**
+* Drops the scopes the predicate refuses. The predicate is resolved by the read
+* gate, which decides against the whole policy once per document; this only
+* applies the answer, so it stays synchronous.
+*/
+function filterReadableScopes(document, readable) {
 	const state = document.state;
 	if (!state) return document;
-	const auth = document.state.auth;
-	const readable = (scope) => canReadScope(auth, subject, scope);
 	return {
 		...document,
 		state: keepReadableScopes(state, readable),
@@ -744,8 +994,9 @@ var ReactorClient = class {
 	jobAwaiter;
 	documentIndexer;
 	documentView;
+	readGate;
 	drives;
-	constructor(logger, reactor, signer, subscriptionManager, jobAwaiter, documentIndexer, documentView) {
+	constructor(logger, reactor, signer, subscriptionManager, jobAwaiter, documentIndexer, documentView, readGate = new BareReadGate()) {
 		this.logger = logger;
 		this.reactor = reactor;
 		this.signer = signer;
@@ -753,6 +1004,7 @@ var ReactorClient = class {
 		this.jobAwaiter = jobAwaiter;
 		this.documentIndexer = documentIndexer;
 		this.documentView = documentView;
+		this.readGate = readGate;
 		this.drives = new DriveClient(this, logger, reactor, signer);
 		this.logger.verbose("ReactorClient initialized");
 	}
@@ -760,6 +1012,25 @@ var ReactorClient = class {
 		return subject ?? authSubjectFromSigner(this.signer);
 	}
 	/**
+	* Which scopes of one document the subject may read. Resolved once per
+	* document, so the gate builds its model once however many scopes are then
+	* tested, and the filtering itself stays synchronous.
+	*/
+	readableScopes(document, view, signal) {
+		return this.readGate.scopePredicate(document, this.readSubject(view?.subject), view?.branch ?? "main", signal);
+	}
+	/**
+	* One document, filtered to the scopes the subject may read. Every method
+	* that hands a document back goes through here, including the ones that
+	* follow a write: a document returned from a mutation is a read like any
+	* other, and returning it whole served scopes the same subject would be
+	* refused by `get`. Its author still sees what it wrote, because an allow on
+	* execute confers read of that scope.
+	*/
+	async gateDocument(document, view, signal) {
+		return filterReadableScopes(document, await this.readableScopes(document, view, signal));
+	}
+	/**
 	* Retrieves a list of document model modules.
 	*/
 	async getDocumentModelModules(namespace, paging, signal) {
@@ -810,7 +1081,8 @@ var ReactorClient = class {
 	*/
 	async get(identifier, view, signal) {
 		this.logger.verbose("get(@identifier, @view)", identifier, view);
-		return filterReadableScopes(await this.reactor.getByIdOrSlug(identifier, withAuthScope(view), void 0, signal), this.readSubject(view?.subject));
+		const document = await this.reactor.getByIdOrSlug(identifier, withAuthScope(view), void 0, signal);
+		return this.gateDocument(document, view, signal);
 	}
 	/**
 	* Resolves an identifier (id or slug) to the canonical document id, using the
@@ -826,12 +1098,8 @@ var ReactorClient = class {
 	async getOperations(documentIdentifier, view, filter, paging, signal) {
 		this.logger.verbose("getOperations(@documentIdentifier, @view, @filter, @paging)", documentIdentifier, view, filter, paging);
 		const documentId = await this.documentView.resolveIdOrSlug(documentIdentifier, view, void 0, signal);
-		const authDoc = await this.reactor.getByIdOrSlug(documentId, {
-			scopes: ["auth"],
-			branch: view?.branch
-		}, void 0, signal);
-		const subject = this.readSubject(view?.subject);
-		const canRead = (scope) => canReadScope(authDoc?.state.auth, subject, scope);
+		const gated = await this.reactor.getByIdOrSlug(documentId, withAuthScope(view), void 0, signal);
+		const canRead = await this.readableScopes(gated, view, signal);
 		if (paging?.cursor && isCompositeCursor(paging.cursor)) return this.getOperationsWithCompositeCursor(documentId, view, filter, paging, signal, canRead);
 		const operationsByScope = await this.reactor.getOperations(documentId, view, filter, paging, void 0, signal);
 		for (const scope of Object.keys(operationsByScope)) if (!canRead(scope)) delete operationsByScope[scope];
@@ -925,10 +1193,9 @@ var ReactorClient = class {
 	async find(search, view, paging, signal) {
 		this.logger.verbose("find(@search, @view, @paging)", search, view, paging);
 		const results = await this.reactor.find(search, withAuthScope(view), paging, void 0, signal);
-		const readSubject = this.readSubject(view?.subject);
 		return {
 			...results,
-			results: results.results.map((doc) => filterReadableScopes(doc, readSubject))
+			results: await Promise.all(results.results.map(async (doc) => filterReadableScopes(doc, await this.readableScopes(doc, view, signal))))
 		};
 	}
 	/**
@@ -982,7 +1249,8 @@ var ReactorClient = class {
 		const batchResult = await this.reactor.executeBatch({ jobs }, signal);
 		const completedJobs = await Promise.all(Object.values(batchResult.jobs).map((job) => this.waitForJob(job, signal)));
 		for (const job of completedJobs) if (job.status === JobStatus.FAILED) throw new Error(job.error?.message);
-		return await this.reactor.get(documentId);
+		const created = await this.reactor.get(documentId);
+		return this.gateDocument(created, void 0, signal);
 	}
 	/**
 	* Creates an empty document and waits for completion
@@ -1029,7 +1297,7 @@ var ReactorClient = class {
 			const fromVersion = normalizeDocumentModelVersion(document.state.document?.version);
 			let targetVersion = toVersion;
 			if (targetVersion === void 0) targetVersion = normalizeDocumentModelVersion((await this.getDocumentModelModule(documentType)).version);
-			if (targetVersion === fromVersion) return document;
+			if (targetVersion === fromVersion) return this.gateDocument(document, { branch }, signal);
 			if (targetVersion < fromVersion) throw new DowngradeNotSupportedError(documentType, fromVersion, targetVersion);
 			const signedActions = await signActions([upgradeDocumentAction({
 				documentId,
@@ -1040,7 +1308,10 @@ var ReactorClient = class {
 			})], this.signer, signal);
 			const jobInfo = await this.reactor.execute(documentId, branch, signedActions, signal);
 			const completedJob = await this.waitForJob(jobInfo, signal);
-			if (completedJob.status !== JobStatus.FAILED) return await this.reactor.getByIdOrSlug(documentId, { branch }, completedJob.consistencyToken, signal);
+			if (completedJob.status !== JobStatus.FAILED) {
+				const upgraded = await this.reactor.getByIdOrSlug(documentId, { branch }, completedJob.consistencyToken, signal);
+				return this.gateDocument(upgraded, { branch }, signal);
+			}
 			if (completedJob.error?.name !== "UpgradePreconditionFailedError") throw new Error(completedJob.error?.message);
 			lastConflictMessage = completedJob.error.message;
 		}
@@ -1066,7 +1337,8 @@ var ReactorClient = class {
 		const completedJob = await this.waitForJob(jobInfo, signal);
 		if (completedJob.status === JobStatus.FAILED) throw new Error(completedJob.error?.message);
 		const view = { branch };
-		return await this.reactor.getByIdOrSlug(documentIdentifier, view, completedJob.consistencyToken, signal);
+		const result = await this.reactor.getByIdOrSlug(documentIdentifier, view, completedJob.consistencyToken, signal);
+		return this.gateDocument(result, view, signal);
 	}
 	/**
 	* Submits a list of actions to a document
@@ -1110,7 +1382,8 @@ var ReactorClient = class {
 		const jobInfo = await this.reactor.addRelationship(sourceIdentifier, targetIdentifier, relationshipType, branch, this.signer, signal);
 		const completedJob = await this.waitForJob(jobInfo, signal);
 		if (completedJob.status === JobStatus.FAILED) throw new Error(completedJob.error?.message);
-		return await this.reactor.getByIdOrSlug(sourceIdentifier, { branch }, completedJob.consistencyToken, signal);
+		const result = await this.reactor.getByIdOrSlug(sourceIdentifier, { branch }, completedJob.consistencyToken, signal);
+		return this.gateDocument(result, { branch }, signal);
 	}
 	/**
 	* Removes a relationship between two documents and waits for completion.
@@ -1120,7 +1393,8 @@ var ReactorClient = class {
 		const jobInfo = await this.reactor.removeRelationship(sourceIdentifier, targetIdentifier, relationshipType, branch, this.signer, signal);
 		const completedJob = await this.waitForJob(jobInfo, signal);
 		if (completedJob.status === JobStatus.FAILED) throw new Error(completedJob.error?.message);
-		return await this.reactor.getByIdOrSlug(sourceIdentifier, { branch }, completedJob.consistencyToken, signal);
+		const result = await this.reactor.getByIdOrSlug(sourceIdentifier, { branch }, completedJob.consistencyToken, signal);
+		return this.gateDocument(result, { branch }, signal);
 	}
 	/**
 	* Moves a relationship from one source document to another and waits for completion.
@@ -1133,9 +1407,11 @@ var ReactorClient = class {
 		const addJobInfo = await this.reactor.addRelationship(targetParentIdentifier, targetIdentifier, relationshipType, branch, this.signer, signal);
 		const addCompletedJob = await this.waitForJob(addJobInfo, signal);
 		if (addCompletedJob.status === JobStatus.FAILED) throw new Error(addCompletedJob.error?.message);
+		const sourceResult = await this.reactor.getByIdOrSlug(sourceParentIdentifier, { branch }, removeCompletedJob.consistencyToken, signal);
+		const targetResult = await this.reactor.getByIdOrSlug(targetParentIdentifier, { branch }, addCompletedJob.consistencyToken, signal);
 		return {
-			source: await this.reactor.getByIdOrSlug(sourceParentIdentifier, { branch }, removeCompletedJob.consistencyToken, signal),
-			target: await this.reactor.getByIdOrSlug(targetParentIdentifier, { branch }, addCompletedJob.consistencyToken, signal)
+			source: await this.gateDocument(sourceResult, { branch }, signal),
+			target: await this.gateDocument(targetResult, { branch }, signal)
 		};
 	}
 	async loadBatch(request, signal) {
@@ -1208,34 +1484,56 @@ var ReactorClient = class {
 	*/
 	subscribe(search, callback, view) {
 		this.logger.verbose("subscribe(@search, @view)", search, view);
-		const subject = this.readSubject(view?.subject);
-		const readable = (document) => filterReadableScopes(document, subject);
+		const readable = async (document) => filterReadableScopes(document, await this.readableScopes(document, view));
+		let disposed = false;
+		let delivering = Promise.resolve();
+		/**
+		* Queues one event behind those already queued. Gating an event resolves
+		* asynchronously, so an event needing a group fetch would otherwise be
+		* overtaken by the one behind it, and one still in flight would reach a
+		* subscriber that has already unsubscribed. Only delivery is ordered, not
+		* the gating: a single subscription can cover every document in the
+		* reactor, so serializing that work would make its delivery rate the sum
+		* of every gate build rather than the slowest. An event that cannot be
+		* gated is withheld, because serving it unfiltered would leak the scopes
+		* the gate did not clear -- but it is logged rather than swallowed, since
+		* the gate rethrows a transient failure precisely so it is not read as a
+		* denial.
+		*/
+		const deliver = (event) => {
+			Promise.resolve(event).catch(() => void 0);
+			delivering = delivering.then(async () => {
+				const built = await event;
+				if (disposed) return;
+				callback(built);
+			}).catch((error) => {
+				this.logger.error("Subscription delivery failed for @search: @Error", { search }, error);
+			});
+		};
 		const unsubscribeCreated = this.subscriptionManager.onDocumentCreated((result) => {
-			(async () => {
-				try {
-					const documents = await Promise.all(result.results.map((id) => this.reactor.get(id, withAuthScope(view), void 0, void 0)));
-					callback({
-						type: DocumentChangeType.Created,
-						documents: documents.map(readable)
-					});
-				} catch {}
-			})();
+			deliver((async () => {
+				const documents = await Promise.all(result.results.map((id) => this.reactor.get(id, withAuthScope(view), void 0, void 0)));
+				return {
+					type: DocumentChangeType.Created,
+					documents: await Promise.all(documents.map(readable))
+				};
+			})());
 		}, search);
 		const unsubscribeDeleted = this.subscriptionManager.onDocumentDeleted((documentIds) => {
-			callback({
+			deliver({
 				type: DocumentChangeType.Deleted,
 				documents: [],
 				context: { childId: documentIds[0] }
 			});
 		}, search);
 		const unsubscribeUpdated = this.subscriptionManager.onDocumentStateUpdated((result) => {
-			callback({
+			deliver((async () => ({
 				type: DocumentChangeType.Updated,
-				documents: result.results.map(readable)
-			});
+				documents: await Promise.all(result.results.map(readable))
+			}))());
 		}, search, view);
 		const unsubscribeRelationship = this.subscriptionManager.onRelationshipChanged((parentId, childId, changeType) => {
-			callback({
+			deliver({
 				type: changeType === RelationshipChangeType.Added ? DocumentChangeType.ChildAdded : DocumentChangeType.ChildRemoved,
 				documents: [],
 				context: {
@@ -1245,6 +1543,7 @@ var ReactorClient = class {
 			});
 		}, search);
 		return () => {
+			disposed = true;
 			unsubscribeCreated();
 			unsubscribeDeleted();
 			unsubscribeUpdated();
@@ -7116,7 +7415,7 @@ var ReactorBuilder = class {
 	}
 	async buildModule() {
 		if (!this.logger) this.logger = new ConsoleLogger(["reactor"]);
-		validateFeatureFlags(this.executorConfig.featureFlags ?? {}, FLAG_PREREQUISITES);
+		const featureFlags = resolveFeatureFlags(this.executorConfig.featureFlags);
 		if (this.projectionShardConfig !== void 0 && this.readModelFactories.length > 0) throw new Error("withProjectionShards does not support read models registered through withReadModelFactory; projection workers cannot receive host-only factory dependencies");
 		const resolvedSources = await resolveModelSources(this.documentModelSources);
 		if (this.workerPool) {
@@ -7175,7 +7474,7 @@ var ReactorBuilder = class {
 		await executorManager.start(executorStartCount);
 		const readModelInstances = Array.from(new Set([...this.readModels]));
 		const documentViewConsistencyTracker = new ConsistencyTracker();
-		const documentView = new KyselyDocumentView(database, operationStore, operationIndex, writeCache, documentViewConsistencyTracker, this.executorConfig.featureFlags?.documentDecisions ?? false);
+		const documentView = new KyselyDocumentView(database, operationStore, operationIndex, writeCache, documentViewConsistencyTracker, featureFlags.documentDecisions);
 		try {
 			await documentView.init();
 		} catch (error) {
@@ -7220,13 +7519,14 @@ var ReactorBuilder = class {
 			await syncModule.syncManager.startup();
 		}
 		let groupReevaluationTrigger;
-		if (this.executorConfig.featureFlags?.authGroups) {
+		if (featureFlags.authGroups) {
 			groupReevaluationTrigger = new GroupReevaluationTrigger(this.logger, eventBus, queue, operationIndex);
 			groupReevaluationTrigger.startup();
 		}
 		const module = {
 			eventBus,
 			documentModelRegistry,
+			featureFlags,
 			queue,
 			jobTracker,
 			executorManager,
@@ -7320,7 +7620,7 @@ var ReactorBuilder = class {
 		const [{ WorkerHandle }, { createThreadTransport }, { workerEntryPath }] = await Promise.all([
 			import("./worker-handle-CrERzl8s.js"),
 			import("./transport-ByGviWdZ.js"),
-			import("./worker-CbtYMIju.js").then((n) => n.n)
+			import("./worker-BCMw-hBw.js").then((n) => n.n)
 		]);
 		const poolConfig = {
 			enabled: true,
@@ -7463,6 +7763,7 @@ var ReactorClientBuilder = class {
 	subscriptionManager;
 	jobAwaiter;
 	documentModelLoader;
+	readGate;
 	/**
 	* Sets the logger for the ReactorClient.
 	* @param logger - The logger to use.
@@ -7515,6 +7816,29 @@ var ReactorClientBuilder = class {
 		this.documentModelLoader = loader;
 		return this;
 	}
+	/**
+	* Overrides how reads are gated. A client built from a ReactorBuilder derives
+	* this from that reactor's flags; one built from `withReactor` cannot, because
+	* it is handed no flags and no registry, so it gates on the policy alone
+	* unless a gate is supplied here.
+	*/
+	withReadGate(readGate) {
+		this.readGate = readGate;
+		return this;
+	}
+	/**
+	* The gate this reactor's flags call for. Below authEnforcement there is no
+	* model to enforce -- the registered one ignores the auth scope -- so the
+	* policy is evaluated on its own, which is what reads did before the model
+	* existed. Group serving turns on with authGroups, because below it a
+	* `{ group }` grant does not match, so a served roster is one no grant can
+	* use.
+	*/
+	resolveReadGate(reactorModule, documentView) {
+		if (!reactorModule) return new BareReadGate();
+		const model = readDecisionModel(reactorModule.featureFlags, reactorModule.documentModelRegistry);
+		return model === void 0 ? new BareReadGate() : new ModelReadGate(model, documentView, reactorModule.featureFlags.authGroups, reactorModule.operationIndex, this.logger);
+	}
 	async build() {
 		return (await this.buildModule()).client;
 	}
@@ -7544,7 +7868,7 @@ var ReactorClientBuilder = class {
 		const subscriptionManager = this.subscriptionManager ?? reactorModule?.subscriptionManager ?? new ReactorSubscriptionManager(new DefaultSubscriptionErrorHandler());
 		const jobAwaiter = this.jobAwaiter ?? new JobAwaiter(eventBus, (jobId, signal) => reactor.getJobStatus(jobId, signal));
 		return {
-			client: new ReactorClient(this.logger, reactor, signer, subscriptionManager, jobAwaiter, documentIndexer, documentView),
+			client: new ReactorClient(this.logger, reactor, signer, subscriptionManager, jobAwaiter, documentIndexer, documentView, this.readGate ?? this.resolveReadGate(reactorModule, documentView)),
 			reactor,
 			eventBus,
 			documentIndexer,
@@ -7745,6 +8069,6 @@ var DocumentIntegrityService = class {
 	}
 };
 //#endregion
-export { APPEND_CONDITION_FAILED_PREFIX, AppendConditionFailedError, BaseReadModel, ChannelError, ChannelErrorSource, ChannelScheme, ConsistencyTracker, DEFAULT_DRIVE_CONTAINER_TYPES, DRIVE_AUTH_ERROR_MESSAGES, DefaultSubscriptionErrorHandler, DocumentChangeType, DocumentIntegrityService, DocumentModelRegistry, DocumentModelResolver, DriveClient, DriveCollectionId, DuplicateManifestError, DuplicateModuleError, DuplicateOperationError, EventBus, EventBusAggregateError, GqlRequestChannel, GqlRequestChannelFactory, GqlResponseChannel, GqlResponseChannelFactory, SimpleJobExecutor as InMemoryJobExecutor, SimpleJobExecutor, InMemoryJobTracker, InMemoryQueue, IntervalPollTimer, InvalidModuleError, JobAwaiter, JobExecutorEventTypes, JobStatus, KyselyDocumentIndexer, KyselyDocumentView, KyselyKeyframeStore, KyselyOperationStore, KyselySyncCursorStorage, KyselySyncRemoteStorage, KyselyWriteCache, Mailbox, ModuleNotFoundError, NullDocumentModelResolver, OptimisticLockError, PollBehavior, PollingChannelError, ProcessorManager, PropagationMode, QueueEventTypes, REACTOR_SCHEMA, Reactor, ReactorBuilder, ReactorClient, ReactorClientBuilder, ReactorEventTypes, ReactorSubscriptionManager, ReadModelCoordinator, RelationalDbProcessor, RelationshipChangeType, RetryAccounting, RevisionMismatchError, SimpleJobExecutorManager, SyncBuilder, SyncEventTypes, SyncOperation, SyncOperationAggregateError, SyncOperationStatus, SyncStatus, SyncStatusTracker, addRelationshipAction, authDecisionModel, batchOperationsByDocument, buildDecisionModel, classifyJobFailure, consolidateSyncOperations, createDocumentAction, createForwardingLogger, createMutableShutdownStatus, createRelationalDb, decideAtHead, deleteDocumentAction, documentActions, documentDecisionModel, driveIdFromUrl, envelopesToSyncOperations, errorToInfo, firstOutOfOrderPair, getMigrationStatus, instrumentPgPool, isDriveAuthError, makeConsistencyKey, parseDriveUrl, parsePagingOptions, quarantinesDocument, removeRelationshipAction, runMigrations, sanitizeArg, selectDecisionModel, supportsLiveReadModelRegistration, syncOperationErrorType, trimMailboxFromAckOrdinal, updateRelationshipAction, upgradeDocumentAction, workerEntryPath };
+export { ALWAYS_READABLE_SCOPES, APPEND_CONDITION_FAILED_PREFIX, AppendConditionFailedError, BareReadGate, BaseReadModel, ChannelError, ChannelErrorSource, ChannelScheme, ConsistencyTracker, DEFAULT_DRIVE_CONTAINER_TYPES, DRIVE_AUTH_ERROR_MESSAGES, DefaultSubscriptionErrorHandler, DocumentChangeType, DocumentIntegrityService, DocumentModelRegistry, DocumentModelResolver, DriveClient, DriveCollectionId, DuplicateManifestError, DuplicateModuleError, DuplicateOperationError, EventBus, EventBusAggregateError, GqlRequestChannel, GqlRequestChannelFactory, GqlResponseChannel, GqlResponseChannelFactory, SimpleJobExecutor as InMemoryJobExecutor, SimpleJobExecutor, InMemoryJobTracker, InMemoryQueue, IntervalPollTimer, InvalidModuleError, JobAwaiter, JobExecutorEventTypes, JobStatus, KyselyDocumentIndexer, KyselyDocumentView, KyselyKeyframeStore, KyselyOperationStore, KyselySyncCursorStorage, KyselySyncRemoteStorage, KyselyWriteCache, Mailbox, ModelReadGate, ModuleNotFoundError, NullDocumentModelResolver, OptimisticLockError, PollBehavior, PollingChannelError, ProcessorManager, PropagationMode, QueueEventTypes, REACTOR_SCHEMA, Reactor, ReactorBuilder, ReactorClient, ReactorClientBuilder, ReactorEventTypes, ReactorSubscriptionManager, ReadModelCoordinator, RelationalDbProcessor, RelationshipChangeType, RetryAccounting, RevisionMismatchError, SimpleJobExecutorManager, SyncBuilder, SyncEventTypes, SyncOperation, SyncOperationAggregateError, SyncOperationStatus, SyncStatus, SyncStatusTracker, addRelationshipAction, authDecisionModel, batchOperationsByDocument, buildDecisionModel, classifyJobFailure, consolidateSyncOperations, createDocumentAction, createForwardingLogger, createMutableShutdownStatus, createRelationalDb, decideAtHead, deleteDocumentAction, documentActions, documentDecisionModel, driveIdFromUrl, envelopesToSyncOperations, errorToInfo, firstOutOfOrderPair, getMigrationStatus, instrumentPgPool, isDriveAuthError, makeConsistencyKey, parseDriveUrl, parsePagingOptions, quarantinesDocument, readDecisionModel, removeRelationshipAction, runMigrations, sanitizeArg, selectDecisionModel, supportsLiveReadModelRegistration, syncOperationErrorType, trimMailboxFromAckOrdinal, updateRelationshipAction, upgradeDocumentAction, workerEntryPath };
 
 //# sourceMappingURL=index.js.map