@haverstack/core 0.42.0 → 0.44.0

package/dist/scoped-stack/scoped-stack.js

@@ -20,29 +20,31 @@
  * refusals.
  *
  * Also holds the feed side of the same rule: a subscription's deliveries
- * run through the same canRead() a get() answers with, so a feed can never
- * disagree with a read about what a session sees.
+ * ask the same read reach a get() does, so a feed can never disagree with
+ * a read about what a session sees.
  *
  * See docs/spec/access-control.md and docs/spec/events.md § Permission scoping.
  */
 import { baseIdOf } from '../schema.js';
+import { createAssociations } from '../access.js';
 import { validatePatchValues } from '../validate.js';
 import { ChangeEmitter, assertSinceUsable } from '../stack/changes.js';
 import { SYSTEM_TYPES } from '../types/index.js';
-import { StackConflictError, StackNotFoundError, StackPermissionError, RelayScopeError, StackValidationError, } from '../errors.js';
-import { assertAssociationEdits, assertAssociationList, assertAuthorityAssociations, assertDataAssociations, } from '../associations/validation.js';
-import { associationDelta, associationEqual, editsOf } from '../associations/identity.js';
-import { isGroupRecord } from '../access.js';
-import { assertSortCapability, assertValidAssociationFilters, assertValidBaseIdFilter, assertValidSort, filtersContent, } from '../query-validation.js';
-import { bindingFieldsOf } from '../stack/identity-bindings.js';
+import { StackConflictError, StackNotFoundError, StackPermissionError, StackValidationError, } from '../errors.js';
+import { assertAssociationEdits } from '../associations/validation.js';
+import { addsOf, associationEqual } from '../associations/identity.js';
+import { assertQueryCapabilities, assertValidBaseIdFilter, splitQuery, filtersContent, } from '../query-validation.js';
 import { checkFamily, storedVersionDiffers, WRITE_EXPECTATION, } from '../stack/write-expectation.js';
+import { WRITE_GATE } from '../stack/write-gate.js';
 import { assertAttachmentSize } from '../stack/limits.js';
 import { validateIdTimestampSkew, validateRecordId } from '../stack/record-id.js';
-import { DEFAULT_QUERY_LIMIT, MAX_QUERY_LIMIT, findAppCardByDid, lookupEntityByDid, } from '../stack/reads.js';
-import { assertNonEmptyChangeSet, presentDeleted, withoutAuthorityChanges, } from '../record-changes.js';
+import { findAppCardByDid, lookupEntityByDid } from '../stack/reads.js';
+import { presentDeleted, withoutAuthorityChanges } from '../record-changes.js';
 import { createCollection } from '../collection.js';
 import { uploadContent } from '../stack/attachments.js';
+import { assertAssociationSet, assertContentPatch, assertParentArgument, assertUnlistedArgument, } from '../stack/arguments.js';
 import { ScopeAuthority } from './authority.js';
+import { familyPolicy, ownerFieldRefusal } from './family-policy.js';
 import { ScopedSubscription } from './subscription.js';
 /**
  * Held by Stack alone: the index re-exports ScopedStack but not this, so
@@ -63,21 +65,21 @@ export class ScopedStack {
     adapter;
     changes;
     assertStackOpen;
-    relaysChanges;
     migrations;
+    queryReadable;
     /** Not callable from outside the package — see ScopedStackInit. */
     constructor(token, init) {
         if (token !== scopeToken) {
             throw new TypeError('A ScopedStack is obtained through Stack.asEntity() or Stack.asActor()');
         }
         this.stack = init.stack;
-        this.#authority = new ScopeAuthority(init.stack, init.principalId, init.subjectId);
+        this.#authority = new ScopeAuthority(init.stack, init.principalId, init.subjectId, init.queryReadable);
         this.idTimestampSkewMs = init.idTimestampSkewMs;
         this.adapter = init.adapter;
         this.changes = init.changes;
         this.assertStackOpen = init.assertOpen;
-        this.relaysChanges = init.relaysChanges;
         this.migrations = init.migrations;
+        this.queryReadable = init.queryReadable;
     }
     collection(handle) {
         this.assertStackOpen();
@@ -106,9 +108,9 @@ export class ScopedStack {
         // request, never by describing itself in the options.
         return { actor: this.#authority.requester };
     }
-    /** Refuse a create this request holds no grant for — see ScopeAuthority.checkCreateGrant(). */
-    async requireCreateGrant(typeId) {
-        if (!(await this.#authority.checkCreateGrant(typeId))) {
+    /** Refuse a create outside this request's reach — see ScopeAuthority.canCreate(). */
+    async requireCreateGrant(typeId, snapshot) {
+        if (!(await this.#authority.canCreate(typeId, snapshot))) {
             throw new StackPermissionError(`No create grant for type "${typeId}"`);
         }
     }
@@ -123,13 +125,10 @@ export class ScopedStack {
      * the history readers, which borrow this gate without changing anything —
      * the one way through it a `_grant` Record stays open to.
      */
-    async requireUpdatable(id, opts = {}) {
+    async requireUpdatable(id, opts, snapshot) {
         // The `_grant` write fence applies to mutating callers only: reading a
         // grant Record's history is not the escalation that fence exists to stop.
-        return this.requireVerb(id, ['update-own', 'update-any'], {
-            fenceGrantRecord: opts.mutating ?? true,
-            expect: opts.expect,
-        });
+        return this.requireVerb(id, 'update', { fenceGrantRecord: opts.mutating ?? true, expect: opts.expect }, snapshot);
     }
     /**
      * The write gate both requireUpdatable() and requireDeletable() are: the
@@ -138,41 +137,43 @@ export class ScopedStack {
      * stricter management rule that no grant reaches.
      * See docs/spec/access-control.md § Delegation: principal and subject.
      */
-    async requireVerb(id, actions, opts) {
+    async requireVerb(id, verb, opts, snapshot) {
         const record = await this.stack.get(id, { includeDeleted: true });
         if (!record)
             throw new StackNotFoundError(`Record not found: "${id}"`);
         // Ahead of the gate, so another family's record is not found whatever
         // this requester may do to it — the answer a collection's get() gives.
         checkFamily(record, opts.expect);
-        if (opts.fenceGrantRecord)
-            await this.requireOwnerForGrantRecord(record);
-        if (isGroupRecord(record)) {
-            if (!this.#authority.isGroupManager(record)) {
-                throw await this.#authority.denialFor(record, `Cannot change group "${id}": only its admins can manage it`);
-            }
-            return record;
-        }
-        const subjectReaches = (await this.#authority.recordPermits(record, 'write')) ||
-            (await this.#authority.subjectAllows(record.typeId, actions, { record }));
-        const principalHolds = await this.#authority.principalAllows(record.typeId, actions);
-        if (!subjectReaches || !principalHolds) {
-            const verb = actions[0].split('-')[0];
-            const what = `Cannot ${verb} "${id}" (${record.typeId})`;
-            throw await this.#authority.denialFor(record, subjectReaches
-                ? `${what}: the app acting for this entity holds no ${verb} grant`
-                : `${what}: requires ${actions.join(' or ')}`);
-        }
+        await this.gateVerb(record, verb, opts.fenceGrantRecord, snapshot);
         return record;
     }
+    /** requireVerb()'s gate, asked of a record already found in its family. */
+    async gateVerb(record, verb, fenceGrantRecord, snapshot) {
+        const { id } = record;
+        const { writers } = familyPolicy(record.typeId);
+        // The owner-alone fence is on writes only: reading how a grant came to
+        // be is not the escalation it exists to stop.
+        if (fenceGrantRecord || writers !== 'owner-alone') {
+            await this.requireFamilyWriter(record, snapshot);
+        }
+        // Management replaces the write bit and grants for a Group.
+        if (writers === 'group-managers')
+            return;
+        if (await this.#authority.may(verb, record, snapshot))
+            return;
+        const what = `Cannot ${verb} "${id}" (${record.typeId})`;
+        throw await this.#authority.denialFor(record, (await this.#authority.subjectMay(verb, record, snapshot))
+            ? `${what}: the app acting for this entity holds no ${verb} grant`
+            : `${what}: requires ${verb}-own or ${verb}-any`, snapshot);
+    }
     /**
      * Fetch a record the subject can reach and the principal holds `delete` on
      * (via permissions or a delete grant), or throw.
      */
-    requireDeletable(id, expect) {
+    requireDeletable(id, expect, snapshot) {
         // No soft-delete refusal: undelete() shares this gate, and a tombstone
         // is exactly what it addresses.
-        return this.requireVerb(id, ['delete-own', 'delete-any'], { fenceGrantRecord: true, expect });
+        return this.requireVerb(id, 'delete', { fenceGrantRecord: true, expect }, snapshot);
     }
     /**
      * Gates file-ref content fields on file access, mirroring the
@@ -181,12 +182,12 @@ export class ScopedStack {
      * in `content` are checked (a content patch is a merge patch; untouched fields
      * carry no new reference).
      */
-    async requireFileRefAccess(typeId, content) {
+    async requireFileRefAccess(typeId, content, snapshot) {
         for (const field of await this.#authority.fileRefFieldNames(typeId)) {
             const value = content[field];
             if (typeof value !== 'string')
                 continue;
-            if (!(await this.#authority.canAccessFile(value))) {
+            if (!(await this.#authority.canAccessFile(value, snapshot))) {
                 throw new StackPermissionError(`Cannot reference file "${value}" in field "${field}": it does not exist or you cannot read it`);
             }
         }
@@ -198,13 +199,13 @@ export class ScopedStack {
      * stricter management gate. See docs/spec/access-control.md
      * § Reference-creation gating.
      */
-    async requireAssociationAccess(typeId, association) {
+    async requireAssociationAccess(typeId, association, snapshot) {
         if (association.kind === 'attachment') {
-            if (!(await this.#authority.canAccessFile(association.fileId))) {
+            if (!(await this.#authority.canAccessFile(association.fileId, snapshot))) {
                 throw new StackPermissionError(`Cannot reference file "${association.fileId}": it does not exist or you cannot read it`);
             }
         }
-        else if (association.kind === 'relationship' && baseIdOf(typeId) !== SYSTEM_TYPES.GROUP) {
+        else if (association.kind === 'relationship' && !familyPolicy(typeId).rosterAssociations) {
             const { target } = association;
             // `stackUrl` is tested for a value, not for presence: absent and
             // empty are one target — storage, targetEqual() and the filter all
@@ -212,7 +213,7 @@ export class ScopedStack {
             // leave one spelling of a local Record ungated.
             if (target.kind !== 'record' || target.stackUrl)
                 return;
-            if (!(await this.#authority.canReadReferent(target.recordId))) {
+            if (!(await this.#authority.canReadReferent(target.recordId, snapshot))) {
                 throw new StackPermissionError(`Cannot reference record "${target.recordId}": it does not exist or you cannot read it`);
             }
         }
@@ -229,31 +230,29 @@ export class ScopedStack {
             throw new StackPermissionError('Anonymous requesters cannot create records');
         // A grantee is exactly the untrusted actor the `id` skew check below
         // exists to stop from forging a sort position, and a delegated app
-        // acting for the owner inherits none of the owner's extra trust — same
-        // reasoning as ScopeAuthority.mayGrantAccess(). Asked value-wise, since an
-        // `undefined` carries no date and Stack.create() reads it as absent.
+        // acting for the owner inherits none of the owner's extra trust. Asked
+        // value-wise, since an `undefined` carries no date and Stack.create()
+        // reads it as absent.
         if ((opts.createdAt !== undefined || opts.updatedAt !== undefined) &&
             !this.#authority.ownerActingAlone) {
             throw new StackPermissionError('createdAt/updatedAt can only be set by the stack owner acting alone; a grantee or delegated create always stamps the current time.');
         }
-        await this.requireCreateGrant(typeId);
+        const snapshot = this.#authority.snapshot();
+        await this.requireCreateGrant(typeId, snapshot);
         // The exemption is the owner's own, so delegation doesn't carry it: an
         // owner principal acting for someone else would otherwise let that
         // subject name any fileId and reach the bytes through the uploader
         // clause, which matches on the subject this create stamps.
-        if (!this.#authority.ownerActingAlone && baseIdOf(typeId) === SYSTEM_TYPES.ATTACHMENT) {
-            const fileId = content.fileId;
-            if (typeof fileId !== 'string' || !(await this.#authority.hasReadableReference(fileId))) {
+        const namesFile = familyPolicy(typeId).createNamesFile;
+        if (!this.#authority.ownerActingAlone && namesFile !== undefined) {
+            const fileId = content[namesFile];
+            if (typeof fileId !== 'string' ||
+                !(await this.#authority.hasReadableReference(fileId, snapshot))) {
                 throw new StackPermissionError(`Cannot reference file "${String(fileId)}": it does not exist or you cannot read it`);
             }
         }
-        if (opts.permissions?.length && !this.#authority.mayGrantAccess()) {
-            throw new StackPermissionError('A delegated principal cannot set permissions, at create time or after');
-        }
-        if (opts.unlisted && !this.#authority.mayGrantAccess()) {
-            throw new StackPermissionError('A delegated principal cannot create an unlisted record, at create time or after');
-        }
-        this.requireOwnerForOwnerDid(typeId, content.did);
+        await this.requireAuthorityAtCreate(typeId, opts, snapshot);
+        this.requireOwnerFields(typeId, undefined, content);
         await this.requireAppIdMatchesPrincipal(opts.appId);
         if (opts.id !== undefined) {
             validateRecordId(opts.id);
@@ -264,13 +263,14 @@ export class ScopedStack {
                 validateIdTimestampSkew(opts.id, this.idTimestampSkewMs, Date.now(), 'the current time');
             }
         }
-        if (opts.parentId !== undefined && !(await this.#authority.canReadReferent(opts.parentId))) {
+        if (opts.parentId !== undefined &&
+            !(await this.#authority.canReadReferent(opts.parentId, snapshot))) {
             throw new StackPermissionError(`Cannot reference record "${opts.parentId}" as parent: it does not exist or you cannot read it`);
         }
         for (const assoc of opts.associations ?? []) {
-            await this.requireAssociationAccess(typeId, assoc);
+            await this.requireAssociationAccess(typeId, assoc, snapshot);
         }
-        await this.requireFileRefAccess(typeId, content);
+        await this.requireFileRefAccess(typeId, content, snapshot);
         return this.stack.create(typeId, content, {
             ...opts,
             createdBy: this.#authority.requester,
@@ -286,14 +286,14 @@ export class ScopedStack {
         const record = await this.stack.get(id, opts);
         if (!record)
             return null;
-        if (!(await this.#authority.canRead(record)))
+        if (!(await this.#authority.canRead(record, this.#authority.snapshot())))
             return null;
         return presentDeleted(record);
     }
     /**
-     * Runs through this.query(), so canRead() still applies — this answers a
-     * question the caller asks on its own behalf. includeUnlisted is passed
-     * only when the request is the owner acting alone, per
+     * Runs through this.query(), so the read reach still applies — this
+     * answers a question the caller asks on its own behalf. includeUnlisted
+     * is passed only when the request is the owner acting alone, per
      * docs/spec/identity.md § DID bindings.
      */
     async getEntityByDid(did) {
@@ -303,177 +303,195 @@ export class ScopedStack {
         return this.getEntityByDid(this.stack.ownerEntityId);
     }
     /**
-     * Query records, filtered to those this request can read. Pages are
-     * filtered then refilled, so a page may slightly overshoot `limit` but
-     * never skips a record. Grants are prefetched once, cursor-walked to
-     * exhaustion.
+     * Query records, among those this request can read: the adapter matches
+     * the request's read reach as one more condition of the query, so a page,
+     * its cursor and whether one comes back are decided among readable
+     * Records alone. See docs/spec/disclosure.md § What a query reveals.
      */
     async query(query = {}) {
-        assertValidSort(query.sort);
-        assertSortCapability(query.sort, this.stack.capabilities);
-        assertValidAssociationFilters(query.filter);
-        assertValidBaseIdFilter(query.filter);
+        const split = splitQuery(query);
+        assertQueryCapabilities(split.query, this.stack.capabilities);
         if (query.filter?.includeUnlisted && !this.#authority.ownerActingAlone) {
             throw new StackPermissionError('includeUnlisted is owner-only');
         }
-        const limit = Math.min(query.limit ?? DEFAULT_QUERY_LIMIT, MAX_QUERY_LIMIT);
-        const records = [];
-        const maxFetched = limit * 10;
-        let totalFetched = 0;
-        const prefetchedGrants = this.#authority.identified
-            ? await this.#authority.loadGrants()
-            : undefined;
-        // Scoped to this query, like prefetchedGrants beside it: every
-        // candidate Record shares one roster resolution per group, and nothing
-        // is carried into the next operation.
-        const groupRoles = new Map();
-        let page = { records: [], cursor: query.cursor ?? null };
-        do {
-            page = await this.stack.query({ ...query, cursor: page.cursor ?? undefined });
-            totalFetched += page.records.length;
-            for (const record of page.records) {
-                // Projected here as well as in get(), or `includeDeleted` would be
-                // a strictly better read channel than the fetch-by-ID it is
-                // supposed to match.
-                if (await this.#authority.canRead(record, prefetchedGrants, groupRoles)) {
-                    records.push(presentDeleted(record));
-                }
-            }
-        } while (records.length < limit && page.cursor && totalFetched < maxFetched);
-        return { records, cursor: page.cursor };
-    }
-    /**
-     * Apply a change set on behalf of the subject. Each key is gated against
-     * the record as it stands, never as the set would leave it, and one
-     * refused key refuses the call. See docs/spec/access-control.md
-     * § Composing a change set.
-     */
-    async mutate(id, changes, opts = {}) {
-        // Ahead of every gate: a malformed change set is a validation error
-        // for every requester, rather than one for the owner and a permission
-        // refusal for everyone else.
-        assertNonEmptyChangeSet(changes);
-        if (changes.contentPatch) {
-            const patchErrors = validatePatchValues(changes.contentPatch);
-            if (patchErrors.length > 0)
-                throw new StackValidationError(patchErrors);
-        }
-        // Refused here as well as in `Stack` below, so the partition is a
-        // refusal rather than a permission question: an `associations` key
-        // naming an authority kind is the wrong surface for every requester,
-        // owner included.
-        if (changes.associations)
-            assertDataAssociations(changes.associations, 'associations');
-        if (changes.permissions)
-            assertAuthorityAssociations(changes.permissions, 'permissions');
-        const writes = changes.contentPatch !== undefined ||
-            changes.associations !== undefined ||
-            changes.parentId !== undefined;
-        // `unlisted` reshares on presence alone; a restated `permissions` set
-        // does not, which permissionsMove() decides once the record is in hand.
-        // See docs/spec/access-control.md § Storage unifies; the API does not.
-        const unlists = changes.unlisted !== undefined;
-        // requireUpdatable() reads the record and applies the write gate; the
-        // reshare keys need the record before their own gate, and a change set
-        // carrying only those must not be held to the write gate it doesn't
-        // need. One read either way.
-        const record = writes
-            ? await this.requireUpdatable(id, { expect: opts })
-            : await this.requireReshareable(id, opts);
-        // A key the gate read as inert is dropped, not forwarded: `Stack`
-        // recomputes the delta from its own read, and must not write an ACL on
-        // the strength of this one. See docs/spec/access-control.md
-        // § Storage unifies; the API does not.
-        let authorized = changes;
-        if (writes) {
-            const moves = this.permissionsMove(record, changes);
-            if (unlists || moves)
-                await this.requireReshareOf(record);
-            if (changes.permissions !== undefined && !moves && !this.#authority.canReshare(record)) {
-                const { permissions: _inert, ...rest } = changes;
-                authorized = rest;
-            }
-        }
+        const reach = await this.#authority.snapshot().reach('read');
+        const page = await this.queryReadable(split, reach);
+        // Projected here as well as in get(), or `includeDeleted` would be a
+        // strictly better read channel than the fetch-by-ID it is supposed to
+        // match.
+        return { records: page.records.map(presentDeleted), cursor: page.cursor };
+    }
+    /**
+     * Patch content on behalf of the subject, on the write gate, plus the
+     * gates a content value can carry: a card's binding fields and the files
+     * a `file-ref` field names. See docs/spec/access-control.md § Per-verb gates.
+     */
+    async patchContent(id, patch, opts = {}) {
+        // Every argument check sits ahead of the gate, here and in each write
+        // verb below, so a malformed call earns one refusal from every requester.
+        assertContentPatch(patch);
+        const patchErrors = validatePatchValues(patch);
+        if (patchErrors.length > 0)
+            throw new StackValidationError(patchErrors);
+        const snapshot = this.#authority.snapshot();
+        const record = await this.requireUpdatable(id, { expect: opts }, snapshot);
         // A patch for another version is refused by `Stack`, which owes the
         // tombstone and `ifVersion` refusals first; the content gates would read
         // a stored Type it was not written for. Pinned to this read, `Stack`
         // cannot find a record the patch lands on.
-        const mismatched = storedVersionDiffers(record, opts, changes.contentPatch !== undefined);
-        if (changes.contentPatch && !mismatched) {
-            const patch = changes.contentPatch;
+        const mismatched = storedVersionDiffers(record, opts, true);
+        if (!mismatched) {
             // Value-wise, not presence-wise: a client that reads a card, edits
             // its `name` and sends the whole content object back is not setting
             // the binding it round-trips, and `name` is writable by record-level
-            // permission. Same predicate restoreVersion() applies to a snapshot.
-            this.requireOwnerForAppIdentity(record.typeId, (field) => field in patch && patch[field] !== record.content[field]);
-            // Likewise value-wise: re-sending the DID a card already holds
-            // claims nothing, and immutability refuses changing it regardless.
-            if ('did' in patch && patch.did !== record.content.did) {
-                this.requireOwnerForOwnerDid(record.typeId, patch.did);
-            }
-            await this.requireFileRefAccess(record.typeId, patch);
+            // permission.
+            const content = record.content;
+            this.requireOwnerFields(record.typeId, content, { ...content, ...patch });
+            await this.requireFileRefAccess(record.typeId, patch, snapshot);
         }
-        // Every association the change set would add is a reference this
-        // requester has to be allowed to create — asked against the stored
-        // set, so an association already on the record is not re-gated.
-        for (const assoc of changes.associations ?? []) {
-            if ((record.associations ?? []).some((a) => associationEqual(a, assoc)))
-                continue;
-            await this.requireAssociationAccess(record.typeId, assoc);
+        const ifVersion = mismatched ? (opts.ifVersion ?? record.version) : opts.ifVersion;
+        return this.stack.patchContent(id, patch, { ...opts, ifVersion, ...this.actor });
+    }
+    /**
+     * The write gate, plus read access to the destination: a container is a
+     * reference the requester has to be allowed to create.
+     */
+    async setParent(id, parentId, opts = {}) {
+        assertParentArgument(parentId);
+        const snapshot = this.#authority.snapshot();
+        const record = await this.requireUpdatable(id, { expect: opts }, snapshot);
+        if (typeof parentId === 'string' &&
+            parentId !== (record.parentId ?? null) &&
+            !(await this.#authority.canReadReferent(parentId, snapshot))) {
+            throw new StackPermissionError(`Cannot reference record "${parentId}" as parent: it does not exist or you cannot read it`);
         }
-        if (changes.parentId != null && !(await this.#authority.canReadReferent(changes.parentId))) {
-            throw new StackPermissionError(`Cannot reference record "${changes.parentId}" as parent: it does not exist or you cannot read it`);
+        return this.stack.setParent(id, parentId, { ...opts, ...this.actor });
+    }
+    /**
+     * Listing decides who can enumerate a record, so it carries the reshare
+     * gate rather than the write bit. See docs/spec/unlisted.md.
+     */
+    async setUnlisted(id, unlisted, opts = {}) {
+        assertUnlistedArgument(unlisted);
+        await this.requireReshareable(id, opts, this.#authority.snapshot());
+        return this.stack.setUnlisted(id, unlisted, { ...opts, ...this.actor });
+    }
+    /**
+     * The write gate, plus the reference gate on each add new to the record:
+     * a remove, or an add of an identity already held, names a reference the
+     * record carries, so it is gated by the write bit alone.
+     */
+    async editAssociations(id, edits, opts = {}) {
+        assertAssociationEdits(edits, 'editAssociations()', 'data');
+        const snapshot = this.#authority.snapshot();
+        return this.stack.editAssociations(id, edits, {
+            ...opts,
+            ...this.actor,
+            [WRITE_GATE]: (record) => this.gateAssociationWrite(record, addsOf(edits), snapshot),
+        });
+    }
+    /** editAssociations()'s gates, with every element new to the set an add. */
+    async setAssociations(id, associations, opts = {}) {
+        assertAssociationSet(associations, 'associations');
+        const snapshot = this.#authority.snapshot();
+        return this.stack.setAssociations(id, associations, {
+            ...opts,
+            ...this.actor,
+            [WRITE_GATE]: (record) => this.gateAssociationWrite(record, associations, snapshot),
+        });
+    }
+    /**
+     * The write gate, then the reference gate over the elements a write adds,
+     * asked against the stored set so an association the record already
+     * carries is not re-gated. `Stack` asks it of each read it writes from,
+     * so a retried write is gated on the set it lands on.
+     */
+    async gateAssociationWrite(record, added, snapshot) {
+        await this.gateVerb(record, 'update', true, snapshot);
+        for (const association of added) {
+            if ((record.associations ?? []).some((a) => associationEqual(a, association)))
+                continue;
+            await this.requireAssociationAccess(record.typeId, association, snapshot);
         }
-        const ifVersion = mismatched ? (opts.ifVersion ?? record.version) : opts.ifVersion;
-        return this.stack.mutate(id, authorized, { ...opts, ifVersion, ...this.actor });
     }
-    async patchContent(id, patch, opts) {
-        return this.mutate(id, { contentPatch: patch }, opts);
+    /**
+     * Extend or withdraw who reaches a record, on the reshare gate. The write
+     * bit does not confer it, or a write-holder could decide who else reaches
+     * the record. See docs/spec/access-control.md § Record-level permissions.
+     */
+    async editAccess(id, edits, opts = {}) {
+        assertAssociationEdits(edits, 'editAccess()', 'authority');
+        const snapshot = this.#authority.snapshot();
+        return this.stack.editAccess(id, edits, {
+            ...opts,
+            ...this.actor,
+            [WRITE_GATE]: (record) => this.gateReshare(record, snapshot),
+        });
+    }
+    /** See editAccess() — the same gate. */
+    async setAccess(id, permissions, opts = {}) {
+        assertAssociationSet(permissions, 'permissions');
+        const snapshot = this.#authority.snapshot();
+        return this.stack.setAccess(id, permissions, {
+            ...opts,
+            ...this.actor,
+            [WRITE_GATE]: (record) => this.gateReshare(record, snapshot),
+        });
     }
     /**
      * The record, having established that this request may decide who else
      * reaches it — the owner-or-creator rule, asked of both sides of a
-     * delegation, or a Group's admin rule for a `_group`. The gate the
-     * `permissions` and `unlisted` keys carry, which the write bit
-     * deliberately does not confer.
+     * delegation, or a Group's admin rule for a `_group`. The gate the access
+     * and listing verbs carry, which the write bit deliberately does not confer.
      */
-    async requireReshareable(id, expect) {
+    async requireReshareable(id, expect, snapshot) {
         const record = await this.stack.get(id, { includeDeleted: true });
         if (!record)
             throw new StackNotFoundError(`Record not found: "${id}"`);
         checkFamily(record, expect);
-        await this.requireOwnerForGrantRecord(record);
-        await this.requireReshareOf(record);
+        await this.gateReshare(record, snapshot);
         return record;
     }
     /**
-     * Whether a change set's `permissions` key moves the ACL, read off the
-     * computed delta so a replacement that drops everything — naming nothing
-     * — still counts. See docs/spec/access-control.md § Record-level permissions.
-     */
-    permissionsMove(record, changes) {
-        if (changes.permissions === undefined)
-            return false;
-        return associationDelta(record.permissions ?? [], changes.permissions).length > 0;
+     * Authority a create writes — a Group's roster, the Record's permissions
+     * and listing — gated as a later write of it would be, asked of the
+     * Record the create would make. That Record carries none of the authority
+     * being written, so no call can satisfy its own gate.
+     * See docs/spec/access-control.md § Write implies read.
+     */
+    async requireAuthorityAtCreate(typeId, opts, snapshot) {
+        const createdBy = this.#authority.requester;
+        const record = {
+            typeId,
+            createdBy,
+            associations: createAssociations(typeId, undefined, createdBy, this.stack.ownerEntityId),
+        };
+        if (!this.#authority.passesWriterFence(record)) {
+            throw new StackPermissionError(writerFenceRefusal(typeId));
+        }
+        if ((opts.permissions?.length || opts.unlisted) &&
+            !(await this.#authority.canReshare(record, snapshot))) {
+            throw new StackPermissionError(`Cannot set permissions or listing on a new ${typeId} record: only its author or the stack owner can decide who else reaches it`);
+        }
     }
-    /** The reshare decision alone, for a record already read and write-gated. */
-    async requireReshareOf(record) {
-        if (!this.#authority.canReshare(record)) {
-            throw await this.#authority.denialFor(record, `Cannot change permissions on "${record.id}": only its author or the stack owner can reshare it`);
+    /** requireReshareable()'s gate, asked of a record already found in its family. */
+    async gateReshare(record, snapshot) {
+        await this.requireFamilyWriter(record, snapshot);
+        if (!(await this.#authority.canReshare(record, snapshot))) {
+            throw await this.#authority.denialFor(record, `Cannot change permissions on "${record.id}": only its author or the stack owner can reshare it`, snapshot);
         }
     }
     /**
-     * An `_app` card's `did` and `appId` are the owner's alone to set, or
-     * record-level `write` would be a second way to name the software behind
-     * a key. `_entity` cards stay writable by grant, as a contacts app needs.
-     * See docs/spec/identity.md § DID bindings.
+     * Refuse a write moving content its family reserves to the owner acting
+     * alone — an `_app` card's bindings, the owner's own DID on an `_entity`
+     * — whichever verb carries it. See docs/spec/identity.md § DID bindings.
      */
-    requireOwnerForAppIdentity(typeId, touches) {
-        if (baseIdOf(typeId) !== SYSTEM_TYPES.APP)
-            return;
-        if (!bindingFieldsOf(SYSTEM_TYPES.APP).some(touches))
+    requireOwnerFields(typeId, before, after) {
+        if (this.#authority.ownerActingAlone)
             return;
-        this.requireOwnerActingAlone('Only the stack owner may set an _app record’s did or appId');
+        const refusal = ownerFieldRefusal(typeId, before, after, this.stack.ownerEntityId);
+        if (refusal)
+            throw new StackPermissionError(refusal);
     }
     /**
      * A delegated write's `appId` must match the `_app` card the owner
@@ -491,79 +509,14 @@ export class ScopedStack {
         }
     }
     /**
-     * The owner's own DID is the one `_entity` binding a grantee may not
-     * claim: `ownerProfile` adopts whichever card holds it.
-     * See docs/spec/identity.md § DID bindings.
+     * Refuse a write its family fences off — see
+     * ScopeAuthority.passesWriterFence() — with the refusal an unreadable
+     * Record answers with.
      */
-    requireOwnerForOwnerDid(typeId, did) {
-        if (baseIdOf(typeId) !== SYSTEM_TYPES.ENTITY)
+    async requireFamilyWriter(record, snapshot) {
+        if (this.#authority.passesWriterFence(record))
             return;
-        if (did !== this.stack.ownerEntityId)
-            return;
-        this.requireOwnerActingAlone('Only the stack owner may claim the owner’s own did');
-    }
-    /**
-     * `_grant` and `_install` Records are authority, so only the owner acting
-     * alone may write one; reading them stays on the ordinary gate.
-     * See docs/spec/access-control.md § What a grant covers.
-     */
-    async requireOwnerForGrantRecord(record) {
-        const family = baseIdOf(record.typeId);
-        if (family !== SYSTEM_TYPES.GRANT && family !== SYSTEM_TYPES.INSTALL)
-            return;
-        if (this.#authority.ownerActingAlone)
-            return;
-        throw await this.#authority.denialFor(record, `Only the stack owner may write a ${family} record`);
-    }
-    /**
-     * Gated on the write bit alone, which is why the list is held to its
-     * rules first: authority reached through this verb would be exactly the
-     * escalation the partition exists to stop, decided before any record is
-     * read so it cannot depend on who is asking.
-     */
-    async associate(id, associations, opts = {}) {
-        assertAssociationList(associations, 'associate()', 'associations', 'data');
-        return this.amendAssociations(id, editsOf('add', associations), opts, 'associate()');
-    }
-    /** See associate() — the same write gate, the same kind refusal. */
-    async dissociate(id, associations, opts = {}) {
-        assertAssociationList(associations, 'dissociate()', 'associations', 'data');
-        return this.amendAssociations(id, editsOf('remove', associations), opts, 'dissociate()');
-    }
-    /**
-     * The write gate, plus the per-element reference gate on each add: what a
-     * remove names is already on the record, so it is gated by the write bit
-     * alone. See associate().
-     */
-    async amendAssociations(id, changes, opts = {}, surface = 'amendAssociations()') {
-        assertAssociationEdits(changes, surface, 'data');
-        const record = await this.requireUpdatable(id, { expect: opts });
-        for (const change of changes) {
-            if (change.op === 'add')
-                await this.requireAssociationAccess(record.typeId, change.association);
-        }
-        return this.stack.amendAssociations(id, changes, { ...opts, ...this.actor }, surface);
-    }
-    /**
-     * Extend who reaches a record, on the reshare gate the `permissions` key
-     * carries. The write bit does not confer it, or a write-holder could
-     * decide who else reaches the record.
-     * See docs/spec/access-control.md § Record-level permissions.
-     */
-    async grantAccess(id, permissions, opts = {}) {
-        assertAssociationList(permissions, 'grantAccess()', 'permissions', 'authority');
-        return this.amendAccess(id, editsOf('add', permissions), opts, 'grantAccess()');
-    }
-    /** Withdraw elements of who reaches a record — see grantAccess(). */
-    async revokeAccess(id, permissions, opts = {}) {
-        assertAssociationList(permissions, 'revokeAccess()', 'permissions', 'authority');
-        return this.amendAccess(id, editsOf('remove', permissions), opts, 'revokeAccess()');
-    }
-    /** The reshare gate over an edit list — see grantAccess(). */
-    async amendAccess(id, changes, opts = {}, surface = 'amendAccess()') {
-        assertAssociationEdits(changes, surface, 'authority');
-        await this.requireReshareable(id, opts);
-        return this.stack.amendAccess(id, changes, { ...opts, ...this.actor }, surface);
+        throw await this.#authority.denialFor(record, writerFenceRefusal(record.typeId, record.id), snapshot);
     }
     /**
      * Purge is owner-only: it is irreversible and destroys version
@@ -572,31 +525,24 @@ export class ScopedStack {
      * limited to soft delete.
      */
     async delete(id, opts = {}) {
-        const { referencedFileIds } = await this.deleteAndReturn(id, opts);
-        return { referencedFileIds };
-    }
-    /**
-     * delete(), plus the record it acted on. Gated identically — the
-     * existence/visibility check that produces a 404 ahead of the 403
-     * permission gate still runs via requireDeletable() before either kind
-     * of delete, so this changes what a successful call reports, not the
-     * disclosure ordering a refused one follows.
-     */
-    async deleteAndReturn(id, opts = {}) {
-        const record = await this.requireDeletable(id, opts);
+        const record = await this.requireDeletable(id, opts, this.#authority.snapshot());
         if (opts.purge && !this.#authority.ownerActingAlone) {
             throw new StackPermissionError('Purge is owner-only');
         }
-        if (!opts[WRITE_EXPECTATION])
-            return this.stack.deleteAndReturn(id, { ...opts, ...this.actor });
         // Checked against the read above, which the delete is pinned to.
         // Forwarded, it would cost a purge the read `Stack` otherwise skips.
-        const { [WRITE_EXPECTATION]: _checked, ...rest } = opts;
-        return this.stack.deleteAndReturn(id, {
+        const { [WRITE_EXPECTATION]: expectation, ...rest } = opts;
+        const result = await this.stack.delete(id, {
             ...rest,
-            ifVersion: opts.ifVersion ?? record.version,
+            ...(expectation && { ifVersion: opts.ifVersion ?? record.version }),
             ...this.actor,
         });
+        // A soft delete's record reaches the caller as every scoped read
+        // presents one; a purge is the owner's, and reports what it destroyed.
+        // See docs/spec/versioning.md § The tombstone is literal.
+        return opts.purge || !result.record
+            ? result
+            : { ...result, record: presentDeleted(result.record) };
     }
     /**
      * Reverse a soft delete. Gated the same as delete() — undelete is the
@@ -604,7 +550,7 @@ export class ScopedStack {
      * would be backwards. Idempotent, per Stack.undelete().
      */
     async undelete(id, opts = {}) {
-        await this.requireDeletable(id, opts);
+        await this.requireDeletable(id, opts, this.#authority.snapshot());
         return this.stack.undelete(id, { ...opts, ...this.actor });
     }
     /**
@@ -615,7 +561,7 @@ export class ScopedStack {
      * stop. See docs/spec/versioning.md § History access.
      */
     async getVersions(id, query = {}) {
-        await this.requireUpdatable(id, { mutating: false });
+        await this.requireUpdatable(id, { mutating: false }, this.#authority.snapshot());
         return this.stack.getVersions(id, query);
     }
     /**
@@ -624,13 +570,16 @@ export class ScopedStack {
      * See docs/spec/journal.md § Reading it.
      */
     async getJournal(id, query = {}) {
-        const record = await this.requireUpdatable(id, { mutating: false });
+        const snapshot = this.#authority.snapshot();
+        const record = await this.requireUpdatable(id, { mutating: false }, snapshot);
         const entries = await this.stack.getJournal(id, query);
-        return this.#authority.canReshare(record) ? entries : entries.map(withoutAuthorityChanges);
+        return (await this.#authority.canReshare(record, snapshot))
+            ? entries
+            : entries.map(withoutAuthorityChanges);
     }
     /** See getVersions() — the same mutate-surface gate. */
     async getVersion(id, version) {
-        await this.requireUpdatable(id, { mutating: false });
+        await this.requireUpdatable(id, { mutating: false }, this.#authority.snapshot());
         return this.stack.getVersion(id, version);
     }
     /**
@@ -641,15 +590,15 @@ export class ScopedStack {
      * restore would widen. See docs/spec/versioning.md § Restore semantics.
      */
     async restoreVersion(id, version, opts = {}) {
-        const record = await this.requireUpdatable(id, { expect: opts });
+        const snapshot = this.#authority.snapshot();
+        const record = await this.requireUpdatable(id, { expect: opts }, snapshot);
         if (!this.#authority.ownerActingAlone) {
             const target = await this.stack.getVersion(id, version);
             if (target) {
-                // A rollback that would move a card's binding is the same trust
-                // decision a content patch reserves to the owner, reached by another route.
-                this.requireOwnerForAppIdentity(record.typeId, (field) => target.content[field] !==
-                    record.content[field]);
-                await this.requireFileRefAccess(target.typeId, target.content);
+                // A rollback moving a reserved value is the same trust decision a
+                // content patch reserves to the owner, reached by another route.
+                this.requireOwnerFields(record.typeId, record.content, target.content);
+                await this.requireFileRefAccess(target.typeId, target.content, snapshot);
                 // Content's file refs are the only reference a restore can put
                 // back: containment and associations are not on a snapshot at all,
                 // so a restore never introduces either — see
@@ -665,13 +614,15 @@ export class ScopedStack {
      * See docs/spec/access-control.md § What a grant covers.
      */
     async commitMigration(id, toTypeId, content, opts = {}) {
-        if (!this.#authority.ownerActingAlone)
-            await this.requireInstallMigration(id, toTypeId);
-        // The new content is a fresh set of file references, so an app is held
-        // to the gate create() applies; otherwise a migration could point one of
-        // its records at any attachment and read the bytes through it.
-        if (!this.#authority.ownerActingAlone)
-            await this.requireFileRefAccess(toTypeId, content);
+        if (!this.#authority.ownerActingAlone) {
+            const snapshot = this.#authority.snapshot();
+            const record = await this.requireInstallMigration(id, toTypeId, snapshot);
+            this.requireOwnerFields(toTypeId, record.content, content);
+            // The new content is a fresh set of file references, so an app is held
+            // to the gate create() applies; otherwise a migration could point one
+            // of its records at any attachment and read the bytes through it.
+            await this.requireFileRefAccess(toTypeId, content, snapshot);
+        }
         return this.stack.commitMigration(id, toTypeId, content, { ...opts, ...this.actor });
     }
     /**
@@ -681,14 +632,15 @@ export class ScopedStack {
      * owner may migrate a tombstone; an app sees it without content.
      * See docs/spec/apps.md § Migrating an installed app's types.
      */
-    async requireInstallMigration(id, toTypeId) {
+    async requireInstallMigration(id, toTypeId, snapshot) {
         const record = await this.stack.get(id, { includeDeleted: true });
-        if (!record || !(await this.#authority.installMayMigrate(record, toTypeId))) {
+        if (!record || !(await this.#authority.installMayMigrate(record, toTypeId, snapshot))) {
             throw new StackPermissionError('Only the stack owner, or an installed app within the type families it defines, may commit a migration');
         }
         if (record.deletedAt) {
             throw new StackConflictError(`Record "${id}" is soft-deleted; undelete it before migrating it.`);
         }
+        return record;
     }
     /**
      * Store bytes and create an _attachment@1 metadata record (create grant
@@ -705,7 +657,7 @@ export class ScopedStack {
         if (!principal) {
             throw new StackPermissionError('Anonymous requesters cannot upload attachments');
         }
-        await this.requireCreateGrant(`${SYSTEM_TYPES.ATTACHMENT}@1`);
+        await this.requireCreateGrant(`${SYSTEM_TYPES.ATTACHMENT}@1`, this.#authority.snapshot());
         await this.requireAppIdMatchesPrincipal(appId);
         assertAttachmentSize(data.byteLength, this.capabilities.limits.attachmentBytes);
         const fileId = await this.adapter.putBlob(data);
@@ -717,7 +669,7 @@ export class ScopedStack {
      * predicate as the reference-creation gate (canAccessFile).
      */
     async getAttachment(fileId) {
-        if (!(await this.#authority.canAccessFile(fileId))) {
+        if (!(await this.#authority.canAccessFile(fileId, this.#authority.snapshot()))) {
             throw new StackPermissionError(`Cannot read file "${fileId}": it does not exist or you cannot read it`);
         }
         return this.stack.getAttachment(fileId);
@@ -740,37 +692,27 @@ export class ScopedStack {
     }
     /**
      * Observe the changes this request may read, decided per event by the
-     * same canRead() that get() and query() use. An unreadable record yields
+     * same read reach that get() and query() ask. An unreadable record yields
      * no event at all, since a change's existence is itself a disclosure.
      * See docs/spec/events.md § Permission scoping.
      */
     async subscribe(handler, opts = {}) {
         this.assertStackOpen();
-        if (this.relaysChanges) {
-            throw new RelayScopeError('This stack relays changes from elsewhere, and a scoped view cannot narrow that feed: ' +
-                'a relayed frame was already scoped by the session that opened it, and a purge leaves ' +
-                'no record to re-check. Subscribe with a session-scoped stack instead.');
-        }
-        // A relaying stack was already refused above, so relaysChanges is
-        // always false here — `since` never has a cursor to mean anything by.
+        // A scoped view exists only over a stack that relays nothing, so
+        // `since` never has a cursor to mean anything by.
         assertSinceUsable(opts.since, false);
         assertValidBaseIdFilter(opts.filter);
-        if (opts.includeUnlisted && !this.#authority.ownerActingAlone) {
+        if (opts.filter?.includeUnlisted && !this.#authority.ownerActingAlone) {
             throw new StackPermissionError('includeUnlisted is owner-only');
         }
-        return this.changes.add(new ScopedSubscription((record, cache) => this.canReadCached(record, cache), handler, opts));
+        return this.changes.add(new ScopedSubscription(this.#authority.snapshot(), (record, snapshot) => this.#authority.canRead(record, snapshot), handler, opts));
     }
-    /**
-     * canRead for one event, through the subscription's own cache. Grants
-     * are prefetched once and refilled after an invalidation rather than
-     * re-queried per event, which would be a `_grant` scan for every change
-     * the stack makes.
-     */
-    async canReadCached(record, cache) {
-        const grants = this.#authority.identified
-            ? await cache.grants(() => this.#authority.loadGrants())
-            : undefined;
-        return this.#authority.canRead(record, grants, cache.roles);
+}
+/** Why a family fence refused a write: to `id`, or to a new Record when absent. */
+function writerFenceRefusal(typeId, id) {
+    if (familyPolicy(typeId).writers === 'group-managers') {
+        return `Cannot ${id ? `change group "${id}"` : 'create this group'}: only its admins can manage it`;
     }
+    return `Only the stack owner may write a ${baseIdOf(typeId)} record`;
 }
 //# sourceMappingURL=scoped-stack.js.map