@haverstack/core 0.42.0 → 0.43.0

package/dist/stack/stack.js

@@ -24,17 +24,18 @@ import { compareRecordedAttachments } from '../attachment-records.js';
 import { stampGroupAdmin, validatePermissions } from '../access.js';
 import { ChangeEmitter, RelayDelivery, PendingChange, assertSinceUsable } from './changes.js';
 import { SYSTEM_TYPES } from '../types/index.js';
-import { UseAfterCloseError, InvalidAdapterError, StackConflictError, StackMigrationError, StackNotFoundError, StackBadRequestError, StackSchemaDriftError, StackValidationError, StackVersionConflictError, ARGUMENTS_INVALID, SCHEMA_INVALID, } from '../errors.js';
-import { assertQueryCapabilities, assertValidContentByType, assertSortCapability, assertValidAssociationFilters, assertValidBaseIdFilter, assertValidJournalQuery, assertValidVersionsQuery, assertValidSort, normalizeSort, filtersContent, assertFamilyId, } from '../query-validation.js';
-import { assertAssociationEdits, assertAssociationList, assertAuthorityAssociations, assertDataAssociations, validateAssociations, } from '../associations/validation.js';
-import { applyAssociationEdits, associationDelta, editsOf } from '../associations/identity.js';
+import { ElementSetMovedError, UseAfterCloseError, ScopeUnavailableError, InvalidAdapterError, StackConflictError, StackMigrationError, StackNotFoundError, StackBadRequestError, StackSchemaDriftError, StackValidationError, StackVersionConflictError, ARGUMENTS_INVALID, SCHEMA_INVALID, softDeletedRefusal, } from '../errors.js';
+import { assertQueryCapabilities, assertValidBaseIdFilter, assertValidJournalQuery, assertValidVersionsQuery, resolveQuery, splitQuery, filtersContent, assertFamilyId, } from '../query-validation.js';
+import { assertAssociationEdits, assertAuthorityAssociations, assertDataAssociations, validateAssociations, } from '../associations/validation.js';
+import { applyAssociationEdits, associationDelta } from '../associations/identity.js';
 import { validateGrantee, validateGrantBaseId } from '../grants.js';
 import { bindingFieldsOf } from './identity-bindings.js';
 import { validateInstall } from '../install.js';
 import { assertAttachmentSize, assertContentSize } from './limits.js';
 import { validateRecordId, validateClockField, validateIdTimestampSkew, DEFAULT_ID_TIMESTAMP_SKEW_MS, } from './record-id.js';
-import { queryAllPages, lookupEntityByDid, MAX_QUERY_LIMIT } from './reads.js';
-import { assertNonEmptyChangeSet, bumpsVersion, changeSetOps, effectiveChanges, takesIfVersion, } from '../record-changes.js';
+import { queryAllPages, lookupEntityByDid } from './reads.js';
+import { contentEqual } from '../record-changes.js';
+import { assertAssociationSet, assertContentPatch, assertParentArgument, assertUnlistedArgument, } from './arguments.js';
 import { ScopedStack, scopeToken } from '../scoped-stack/scoped-stack.js';
 import { MigrationRegistry } from './migrations.js';
 import * as apps from './install-app.js';
@@ -43,6 +44,7 @@ import * as attachments from './attachments.js';
 import { assertAttachmentImmutable, assertGroupAdminRemains, assertNoParentCycle, assertParentExists, checkAttachmentAssociationPointers, checkAttachmentMimeTypeOnCreate, checkBindingImmutable, checkBindingsOnCreate, checkBindingsOnMigrate, checkBindingsOnUpdate, checkConfigEntityIdUnchanged, } from './integrity.js';
 import { systemTypeDefinitions } from './system-types.js';
 import { checkFamily, checkSnapshotFamily, checkStoredVersion, WRITE_EXPECTATION, } from './write-expectation.js';
+import { WRITE_GATE } from './write-gate.js';
 import { createCollection } from '../collection.js';
 // -------------------------------------------------------
 // Supporting definitions
@@ -66,8 +68,8 @@ function normalizeActor(actor) {
         ? { subjectId }
         : { subjectId, principalId };
 }
-/** Sentinel: filter.baseId resolved to zero matching types. */
-const EMPTY_FAMILY = Symbol('empty-family');
+/** How many Records migrateAll() reads and migrates per page. */
+const MIGRATE_ALL_BATCH = 100;
 /**
  * One refusal for every problem a call carries, content and arguments alike,
  * so a caller fixes them in one round trip. Content is itself an argument,
@@ -123,7 +125,7 @@ export class Stack {
     /**
      * Announce a mutation that has already been persisted. Called after the
      * adapter write resolves and before the mutating method settles, so
-     * `await stack.mutate(...)` guarantees subscribers have been notified —
+     * `await stack.patchContent(...)` guarantees subscribers have been notified —
      * and nothing about work they deferred. A handler cannot fail the write:
      * there is nothing left to fail. See docs/spec/events.md § Handlers.
      */
@@ -218,8 +220,24 @@ export class Stack {
         const { subjectId, principalId = subjectId } = normalizeActor(actor);
         return this.scope(principalId, subjectId);
     }
+    /**
+     * A scoped view needs a stack that owns its storage: one whose adapter
+     * queries within a reach and relays no changes from elsewhere. A
+     * server-backed stack is scoped by the session that opened it instead.
+     * See docs/spec/access-control.md § Enforcement: Stack.asEntity().
+     */
     scope(principalId, subjectId) {
         this.assertOpen();
+        const queryReadable = this.adapter.queryReadable?.bind(this.adapter);
+        if (!queryReadable) {
+            throw new ScopeUnavailableError('This stack cannot be scoped: its adapter does not implement queryReadable(), so a ' +
+                "query could not be kept to the requester's reach. Every local adapter must; a " +
+                'server-backed stack is scoped by opening it with the session you mean.');
+        }
+        if (this.relaysChanges) {
+            throw new ScopeUnavailableError('This stack cannot be scoped: it relays changes made elsewhere, whose frames were ' +
+                'scoped by the session that opened the feed. Open it with the session you mean.');
+        }
         return new ScopedStack(scopeToken, {
             stack: this,
             principalId,
@@ -228,8 +246,8 @@ export class Stack {
             adapter: this.adapter,
             changes: this.changes,
             assertOpen: () => this.assertOpen(),
-            relaysChanges: this.relaysChanges,
             migrations: this.migrations,
+            queryReadable: (split, reach) => this.dispatchQuery(split, (resolved) => queryReadable(resolved, reach)),
         });
     }
     collection(handle) {
@@ -335,7 +353,7 @@ export class Stack {
     async migrateAll(baseId, opts = {}) {
         this.assertOpen();
         assertFamilyId(baseId, 'migrateAll');
-        const familyTypeIds = await this.familyTypeIds([baseId]);
+        const familyTypeIds = typeIdsOfFamilies(await this.adapter.listTypes(), [baseId]);
         if (familyTypeIds.length === 0) {
             throw new StackMigrationError(`migrateAll: no registered types found for baseId "${baseId}"`);
         }
@@ -355,11 +373,11 @@ export class Stack {
             }
             let cursor;
             do {
-                const result = await this.adapter.queryRecords({
+                const result = await this.adapter.queryRecords(resolveQuery({
                     filter: { typeId, includeDeleted: true, includeUnlisted: !listedOnly },
-                    limit: 100,
+                    limit: MIGRATE_ALL_BATCH,
                     cursor,
-                });
+                }));
                 for (const record of result.records) {
                     if (listedOnly && record.deletedAt) {
                         skipped++;
@@ -508,230 +526,210 @@ export class Stack {
         return opts.presentAt === 'latest' ? this.migrations.presentAtLatest(record) : record;
     }
     /**
-     * Apply a change set as one atomic write — see StackClient.mutate(). A
-     * set the record already satisfies writes nothing, and content is checked
-     * against the record's current stored type.
+     * Merge a patch into a record's content, checked against its current
+     * stored type. A patch the content already satisfies writes nothing.
      * See docs/spec/data-model.md § Mutations.
      */
-    async mutate(id, changes, opts = {}) {
+    async patchContent(id, patch, opts = {}) {
         this.assertOpen();
-        assertNonEmptyChangeSet(changes);
-        const existing = await this.requireRecord(id);
-        checkFamily(existing, opts);
-        this.refuseIfDeleted(existing);
-        // Checked before validation, so a caller that lost the race learns its
-        // version is stale rather than that its patch is bad, and before the
-        // no-op short-circuit below, so a precondition is never satisfied by a
-        // write that turned out to move nothing.
-        if (takesIfVersion(changes))
-            this.checkIfVersion(existing, opts.ifVersion);
-        checkStoredVersion(existing, opts, changes.contentPatch !== undefined);
-        const merged = await this.validateChangeSet(id, existing, changes);
-        const ops = changeSetOps(existing, changes, merged);
-        // Nothing moved, so there is nothing to version. Decided here rather
-        // than in the adapter: "did this change anything" is a question about
-        // the record's meaning, and an adapter is never handed a write that
-        // writes nothing.
-        if (ops.length === 0)
+        assertContentPatch(patch);
+        const existing = await this.requireWritable(id, opts, true);
+        const merged = await this.validatePatch(id, existing, patch);
+        if (contentEqual(existing.content, merged))
             return existing;
-        // A change set naming only aspects the journal already keeps in full
-        // doesn't bump — the same rule associate()/dissociate() follow
-        // unconditionally. Its actor travels as an explicit opt rather than a
-        // record stamp, since a non-bumping write never touches `updatedBy`.
-        // See docs/spec/versioning.md § Version history.
-        const bumps = bumpsVersion(ops);
-        // From the same before/after changeSetOps compared, so `ops` and the
-        // journal cannot disagree; ACL and data edits travel as one list.
-        // See docs/spec/events.md § The event shape.
-        const assocDelta = [
-            ...(changes.associations
-                ? associationDelta(existing.associations ?? [], changes.associations)
-                : []),
-            ...(changes.permissions
-                ? associationDelta(existing.permissions ?? [], changes.permissions)
-                : []),
-        ];
-        const previousParentId = existing.parentId ?? null;
-        const change = new PendingChange(ops, {
-            actor: normalizeActor(opts.actor),
-            ...(ops.includes('reparent') && { previousParentId }),
-            ...(assocDelta.length && { associations: assocDelta }),
-        });
-        const updated = await this.adapter.mutateRecord(id, effectiveChanges(changes, ops), {
-            ...(bumps ? this.writeOptions(existing, opts) : { actor: normalizeActor(opts.actor) }),
-            bumpsVersion: bumps,
+        const change = new PendingChange('patch', { actor: normalizeActor(opts.actor) });
+        const updated = await this.adapter.patchContent(id, patch, {
+            ...this.writeOptions(existing, opts),
             journal: change.journal,
         });
         this.announce(change, updated);
         return updated;
     }
     /**
-     * mutate() with `contentPatch` alone. The common case by a wide margin,
-     * and named for what it does rather than for a symmetry with create()
-     * that a patch does not have.
+     * Every check a content patch owes, all before anything is written.
+     * Returns the merged content, which the caller compares to decide whether
+     * content moved.
      */
-    async patchContent(id, patch, opts) {
-        return this.mutate(id, { contentPatch: patch }, opts);
-    }
-    /**
-     * Every check a change set owes, all before anything is written. Returns
-     * the merged content for a content patch, which the caller compares to
-     * decide whether content moved. A parent is checked only when it changes.
-     */
-    async validateChangeSet(id, existing, changes) {
-        const { contentPatch, permissions, associations, parentId } = changes;
-        // Each key replaces only within its own domain. Asked before the
-        // shape checks below so a misrouted element is reported as the wrong
-        // surface rather than as a malformed value of the right one, and
-        // asked here rather than in `ScopedStack` so an unscoped `Stack`, an
-        // import and a server mapping a request body are all held to it.
-        if (associations)
-            assertDataAssociations(associations, 'associations');
-        if (permissions)
-            assertAuthorityAssociations(permissions, 'permissions');
-        const argumentErrors = [
-            ...(permissions
-                ? [...validateAssociations(permissions, 'permissions'), ...validatePermissions(permissions)]
-                : []),
-            ...(associations ? validateAssociations(associations) : []),
+    async validatePatch(id, existing, patch) {
+        const patchErrors = [
+            ...validateReservedKeys(patch),
+            ...validatePatchValues(patch),
+            ...validateContentKeys(patch),
         ];
-        const patchErrors = contentPatch
-            ? [
-                ...validateReservedKeys(contentPatch),
-                ...validatePatchValues(contentPatch),
-                ...validateContentKeys(contentPatch),
-            ]
-            : [];
-        throwValidation(patchErrors, argumentErrors);
-        await checkAttachmentAssociationPointers(this.readRecord, associations, existing.associations);
-        let merged;
-        if (contentPatch) {
-            // The patch is what travels, so the patch is what's measured — a
-            // small patch against a large record is not an oversized request.
-            assertContentSize(contentPatch, this.capabilities.limits.contentBytes, 'Patch');
-            const type = await this.getTypeCached(existing.typeId);
-            if (!type) {
-                throw new StackBadRequestError(`Unknown type: "${existing.typeId}"`);
-            }
-            merged = applyMergePatch(existing.content, contentPatch);
-            const contentErrors = typedContentErrors(existing.typeId, merged, type.schema);
-            if (contentErrors.length > 0)
-                throw new StackValidationError(contentErrors);
-            if (existing.typeId === `${SYSTEM_TYPES.ATTACHMENT}@1`) {
-                // Presence decides mimeType and value decides the rest: re-sending
-                // the mimeType a record already holds is refused outright, while a
-                // client round-tripping fileId or size unchanged has claimed nothing.
-                assertAttachmentImmutable((field) => Object.prototype.hasOwnProperty.call(contentPatch, field) &&
-                    (field === 'mimeType' ||
-                        merged[field] !==
-                            existing.content[field]));
-            }
-            await checkBindingsOnUpdate(this, existing.typeId, id, contentPatch, existing.content, merged);
-            if (id === SYSTEM_TYPES.CONFIG) {
-                checkConfigEntityIdUnchanged(existing.content.entityId, merged.entityId);
-            }
+        if (patchErrors.length > 0)
+            throw new StackValidationError(patchErrors);
+        // The patch is what travels, so the patch is what's measured — a
+        // small patch against a large record is not an oversized request.
+        assertContentSize(patch, this.capabilities.limits.contentBytes, 'Patch');
+        const type = await this.getTypeCached(existing.typeId);
+        if (!type) {
+            throw new StackBadRequestError(`Unknown type: "${existing.typeId}"`);
+        }
+        const merged = applyMergePatch(existing.content, patch);
+        const contentErrors = typedContentErrors(existing.typeId, merged, type.schema);
+        if (contentErrors.length > 0)
+            throw new StackValidationError(contentErrors);
+        if (existing.typeId === `${SYSTEM_TYPES.ATTACHMENT}@1`) {
+            // Presence decides mimeType and value decides the rest: re-sending
+            // the mimeType a record already holds is refused outright, while a
+            // client round-tripping fileId or size unchanged has claimed nothing.
+            assertAttachmentImmutable((field) => Object.prototype.hasOwnProperty.call(patch, field) &&
+                (field === 'mimeType' ||
+                    merged[field] !==
+                        existing.content[field]));
         }
-        if (associations !== undefined) {
-            assertGroupAdminRemains(existing, associations);
+        await checkBindingsOnUpdate(this, existing.typeId, id, patch, existing.content, merged);
+        if (id === SYSTEM_TYPES.CONFIG) {
+            checkConfigEntityIdUnchanged(existing.content.entityId, merged.entityId);
         }
-        if (parentId !== undefined && parentId !== null && parentId !== (existing.parentId ?? null)) {
+        return merged;
+    }
+    /**
+     * Move a record under another, or to the root with `null`. The
+     * destination is checked only when it changes: it has to exist, and the
+     * move must not make the record its own ancestor.
+     * See docs/spec/data-model.md § Reparenting.
+     */
+    async setParent(id, parentId, opts = {}) {
+        this.assertOpen();
+        assertParentArgument(parentId);
+        const existing = await this.requireWritable(id, opts);
+        const previousParentId = existing.parentId ?? null;
+        if (parentId === previousParentId)
+            return existing;
+        if (parentId !== null) {
             await assertParentExists(this.readRecord, id, parentId);
             await assertNoParentCycle(this.readRecord, id, parentId);
         }
-        return merged;
+        const change = new PendingChange('reparent', {
+            actor: normalizeActor(opts.actor),
+            previousParentId,
+        });
+        return this.writeAspect(change, opts, (o) => this.adapter.setParent(id, parentId, o));
     }
     /**
-     * Add associations to a record, without a version bump. One matching an
-     * existing association's identity but a different `attachmentRecordId`
-     * re-points it in place. See docs/spec/attachments.md § Naming the upload
-     * a reference came from.
+     * Withhold a record from enumeration, or restore it. Restating the
+     * current state writes nothing, so `unlistedAt` is never dragged forward.
+     * See docs/spec/unlisted.md.
      */
-    async associate(id, associations, opts = {}) {
-        assertAssociationList(associations, 'associate()', 'associations', 'data');
-        return this.amendAssociations(id, editsOf('add', associations), opts, 'associate()');
+    async setUnlisted(id, unlisted, opts = {}) {
+        this.assertOpen();
+        assertUnlistedArgument(unlisted);
+        const existing = await this.requireWritable(id, opts);
+        if (Boolean(existing.unlistedAt) === unlisted)
+            return existing;
+        const change = new PendingChange(unlisted ? 'unlist' : 'list', {
+            actor: normalizeActor(opts.actor),
+        });
+        return this.writeAspect(change, opts, (o) => this.adapter.setUnlisted(id, unlisted, o));
     }
     /**
-     * Remove associations from a record — see associate(). Matched by kind,
-     * label and payload; an element not found is a no-op. The emitted event
-     * names each association by identity only, since an attachment's
-     * `attachmentRecordId` describes nothing current once it is gone; the
-     * journal is where it survives.
+     * Apply adds and removes to a record's data associations: one adapter
+     * write, one journal entry carrying each element in full, so the entry is
+     * as undoable as a single-element one. An add naming a held identity with
+     * a new `attachmentRecordId` re-points it — see docs/spec/attachments.md
+     * § Naming the upload a reference came from.
      */
-    async dissociate(id, associations, opts = {}) {
-        assertAssociationList(associations, 'dissociate()', 'associations', 'data');
-        return this.amendAssociations(id, editsOf('remove', associations), opts, 'dissociate()');
+    async editAssociations(id, edits, opts = {}) {
+        this.assertOpen();
+        assertAssociationEdits(edits, 'editAssociations()', 'data');
+        return this.untilSetHolds(async () => {
+            const existing = await this.requireWritable(id, opts);
+            const next = applyAssociationEdits(existing.associations ?? [], edits);
+            return this.writeAssociations(existing, next, opts, (o) => this.adapter.editAssociations(id, edits, o));
+        });
     }
     /**
-     * The atomic form of associate() and dissociate(): one list of adds and
-     * removes, one adapter write, one journal entry. The journal records each
-     * element in full — a remove with its annotation, a re-point with what it
-     * overwrote — so the entry is as undoable as a single-element one.
-     * See docs/spec/data-model.md § Mutations.
+     * Make a record's data associations exactly `associations`. Its
+     * permissions are another aspect, which this never reads or writes.
      */
-    async amendAssociations(id, changes, opts = {}, surface = 'amendAssociations()') {
+    async setAssociations(id, associations, opts = {}) {
         this.assertOpen();
-        assertAssociationEdits(changes, surface, 'data');
-        const existing = await this.requireRecord(id);
-        checkFamily(existing, opts);
-        this.refuseIfDeleted(existing);
+        assertAssociationSet(associations, 'associations');
+        return this.untilSetHolds(async () => {
+            const existing = await this.requireWritable(id, opts);
+            return this.writeAssociations(existing, associations, opts, (o) => this.adapter.setAssociations(id, associations, o));
+        });
+    }
+    /**
+     * The shared half of the two data-association writes, from the set the
+     * write would leave: nothing moved writes nothing, a roster keeps an
+     * admin, and every new attachment pointer names its own upload.
+     */
+    async writeAssociations(existing, next, opts, write) {
         const current = existing.associations ?? [];
-        const next = applyAssociationEdits(current, changes);
         const delta = associationDelta(current, next);
         if (delta.length === 0)
             return existing;
-        // Only a roster can lose its last admin, and only the post-state says so.
         assertGroupAdminRemains(existing, next);
-        await checkAttachmentAssociationPointers(this.readRecord, changes.flatMap((c) => (c.op === 'add' ? [c.association] : [])), current);
+        await checkAttachmentAssociationPointers(this.readRecord, next, current);
         const change = new PendingChange([
             ...(delta.some((c) => c.op !== 'remove') ? ['associate'] : []),
             ...(delta.some((c) => c.op === 'remove') ? ['dissociate'] : []),
         ], { actor: normalizeActor(opts.actor), associations: delta });
-        const updated = await this.adapter.amendAssociations(id, changes, { journal: change.journal });
-        this.announce(change, updated);
-        return updated;
+        return this.writeAspect(change, opts, (o) => write({ ...o, expectSet: current }));
     }
     /**
-     * Extend who reaches a record. The spelling that survives two admins
-     * sharing a record at once: a `permissions` key write replaces the whole
-     * set, so the later of two concurrent ones drops what the earlier
-     * granted. No-bump, like associate(); an element the record already
-     * carries is a no-op. `write` never implies `read` — name both.
+     * Apply adds and removes to who reaches a record. The write-implies-read
+     * invariant is asked once, of the set the whole list produces, so a
+     * downgrade is one call. See docs/spec/access-control.md § Write implies read.
      */
-    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() for why
-     * this is a verb rather than a key write. An element the record does not
-     * carry is a no-op. Returns the record as it now stands.
-     */
-    async revokeAccess(id, permissions, opts = {}) {
-        assertAssociationList(permissions, 'revokeAccess()', 'permissions', 'authority');
-        return this.amendAccess(id, editsOf('remove', permissions), opts, 'revokeAccess()');
+    async editAccess(id, edits, opts = {}) {
+        this.assertOpen();
+        assertAssociationEdits(edits, 'editAccess()', 'authority');
+        return this.untilSetHolds(async () => {
+            const existing = await this.requireWritable(id, opts);
+            const next = applyAssociationEdits(existing.permissions ?? [], edits);
+            return this.writeAccess(existing, next, opts, (o) => this.adapter.editAccess(id, edits, o));
+        });
     }
-    /**
-     * The atomic form of grantAccess() and revokeAccess(). The
-     * write-implies-read invariant is asked once, of the set the whole list
-     * produces. See docs/spec/access-control.md § Write implies read.
-     */
-    async amendAccess(id, changes, opts = {}, surface = 'amendAccess()') {
+    /** Make who reaches a record exactly `permissions`; `[]` is private. */
+    async setAccess(id, permissions, opts = {}) {
         this.assertOpen();
-        assertAssociationEdits(changes, surface, 'authority');
-        const existing = await this.requireRecord(id);
-        checkFamily(existing, opts);
-        this.refuseIfDeleted(existing);
+        assertAssociationSet(permissions, 'permissions');
+        return this.untilSetHolds(async () => {
+            const existing = await this.requireWritable(id, opts);
+            return this.writeAccess(existing, permissions, opts, (o) => this.adapter.setAccess(id, permissions, o));
+        });
+    }
+    async writeAccess(existing, next, opts, write) {
         const current = existing.permissions ?? [];
-        const next = applyAssociationEdits(current, changes);
         const delta = associationDelta(current, next);
         if (delta.length === 0)
             return existing;
+        // After the no-op check: a call that moves nothing is not refused for
+        // a stored set it did not write.
         this.assertPermissionSet(next);
         const change = new PendingChange('reshare', {
             actor: normalizeActor(opts.actor),
             associations: delta,
         });
-        const updated = await this.adapter.amendAssociations(id, changes, { journal: change.journal });
+        return this.writeAspect(change, opts, (o) => write({ ...o, expectSet: current }));
+    }
+    /**
+     * Run an element-set write from its read onward, again from a fresh read
+     * each time the adapter finds the set moved since the last one, so the
+     * rules over the resulting set are asked of the set the write lands on.
+     * Unbounded: each refusal means another write landed.
+     * See docs/spec/versioning.md § Element-set writes compare the set they read.
+     */
+    async untilSetHolds(attempt) {
+        for (;;) {
+            try {
+                return await attempt();
+            }
+            catch (err) {
+                if (!(err instanceof ElementSetMovedError))
+                    throw err;
+            }
+        }
+    }
+    /**
+     * Land a write that never bumps. Its precondition and journal entry
+     * travel together here, so no aspect verb can drop either.
+     */
+    async writeAspect(change, opts, write) {
+        const updated = await write({ ifVersion: opts.ifVersion, journal: change.journal });
         this.announce(change, updated);
         return updated;
     }
@@ -752,9 +750,24 @@ export class Stack {
      * not applied to a tombstone.
      */
     refuseIfDeleted(record) {
-        if (record.deletedAt) {
-            throw new StackConflictError(`Record "${record.id}" is soft-deleted; undelete it before mutating it.`);
-        }
+        if (record.deletedAt)
+            throw softDeletedRefusal(record.id);
+    }
+    /**
+     * The record a write addresses, past every refusal owed before
+     * validation: missing, another family, a caller's gate, soft-deleted,
+     * then a stale `ifVersion` — before validation, so a caller that lost the
+     * race hears that first, and before any no-op, so a write that moved
+     * nothing never satisfies a precondition.
+     */
+    async requireWritable(id, opts, patchesContent = false) {
+        const existing = await this.requireRecord(id);
+        checkFamily(existing, opts);
+        await opts[WRITE_GATE]?.(existing);
+        this.refuseIfDeleted(existing);
+        this.checkIfVersion(existing, opts.ifVersion);
+        checkStoredVersion(existing, opts, patchesContent);
+        return existing;
     }
     /**
      * A by-id read straight from the adapter, for the integrity checks a write
@@ -770,22 +783,13 @@ export class Stack {
         return record;
     }
     /**
-     * Soft-delete a record, or purge it with its history. A purge reports
-     * the files the record referenced, deleting none of them. Use
-     * deleteAndReturn() when the record is needed too. See
-     * docs/spec/versioning.md § Deletion and docs/spec/attachments.md § A
-     * purge strands the bytes it referenced.
+     * Soft-delete a record, or purge it with its history, reporting the
+     * record as the write left it — or as a purge destroyed it — captured in
+     * the same write, so nothing lands unseen between a read and the delete.
+     * See docs/spec/versioning.md § Deletion and docs/spec/attachments.md
+     * § A purge strands the bytes it referenced.
      */
     async delete(id, opts = {}) {
-        const { referencedFileIds } = await this.deleteAndReturn(id, opts);
-        return { referencedFileIds };
-    }
-    /**
-     * delete(), plus the record it acted on — before destruction for a purge,
-     * the tombstone for a soft delete — captured inside the same write, so no
-     * concurrent write can land unseen between a read and the delete.
-     */
-    async deleteAndReturn(id, opts = {}) {
         this.assertOpen();
         if (id === SYSTEM_TYPES.CONFIG) {
             throw new StackConflictError("Cannot delete the _config record: it holds the stack's identity and is required for every permission check.");
@@ -869,61 +873,27 @@ export class Stack {
         return undeleted;
     }
     /**
-     * Query records. filter.baseId matches every version of a type family,
-     * resolved against registered Types. Results come back exactly as
-     * stored; pass presentAt: 'latest' to migrate in memory. See
-     * docs/spec/data-model.md § Queries.
+     * Query records. filter.baseId matches every version of a type family.
+     * Results come back exactly as stored; pass presentAt: 'latest' to
+     * migrate in memory. See docs/spec/data-model.md § Queries.
      */
     async query(query = {}) {
         this.assertOpen();
-        const { presentAt, filter, limit: rawLimit, ...rest } = query;
-        assertValidContentByType(filter);
-        assertQueryCapabilities(filter, this.adapter.capabilities);
-        assertValidSort(query.sort);
-        assertSortCapability(query.sort, this.adapter.capabilities);
-        assertValidAssociationFilters(filter);
-        assertValidBaseIdFilter(filter);
-        const limit = rawLimit !== undefined ? Math.min(rawLimit, MAX_QUERY_LIMIT) : undefined;
-        const resolvedFilter = await this.resolveBaseIdFilter(filter);
-        if (resolvedFilter === EMPTY_FAMILY) {
-            return { records: [], cursor: null };
-        }
-        const result = await this.adapter.queryRecords({
-            ...rest,
-            ...(query.sort && { sort: normalizeSort(query.sort) }),
-            ...(resolvedFilter !== undefined && { filter: resolvedFilter }),
-            ...(limit !== undefined && { limit }),
-        });
-        if (presentAt !== 'latest')
-            return result;
-        return { ...result, records: result.records.map((r) => this.migrations.presentAtLatest(r)) };
-    }
-    /**
-     * Resolve filter.baseId into a concrete typeId set (intersected with
-     * filter.typeId when both are given), so adapters never need their own
-     * baseId concept. Returns EMPTY_FAMILY when the resolved set is empty so
-     * the caller can short-circuit without an adapter round trip.
-     */
-    async resolveBaseIdFilter(filter) {
-        if (filter?.baseId === undefined)
-            return filter;
-        const { baseId, typeId, ...rest } = filter;
-        const requestedBaseIds = Array.isArray(baseId) ? baseId : [baseId];
-        const familyTypeIds = await this.familyTypeIds(requestedBaseIds);
-        const resolvedTypeIds = typeId === undefined
-            ? familyTypeIds
-            : familyTypeIds.filter((id) => Array.isArray(typeId) ? typeId.includes(id) : typeId === id);
-        if (resolvedTypeIds.length === 0)
-            return EMPTY_FAMILY;
-        return { ...rest, typeId: resolvedTypeIds };
+        const split = splitQuery(query);
+        assertQueryCapabilities(split.query, this.adapter.capabilities);
+        return this.dispatchQuery(split, (q) => this.adapter.queryRecords(q));
     }
     /**
-     * Every registered version of the named families, as concrete typeIds —
-     * resolved here because an adapter has no baseId concept of its own.
+     * Everything query() does around the adapter call once the query is
+     * split and checked: the migration on the way out. `read` is the call,
+     * so a scoped query within a reach gets the same treatment as any other.
      */
-    async familyTypeIds(baseIds) {
-        const types = await this.adapter.listTypes();
-        return types.filter((t) => baseIds.includes(t.baseId)).map((t) => t.id);
+    async dispatchQuery({ query, presentAt }, read) {
+        this.assertOpen();
+        const result = await read(query);
+        if (presentAt !== 'latest')
+            return result;
+        return { ...result, records: result.records.map((r) => this.migrations.presentAtLatest(r)) };
     }
     // -------------------------------------------------------
     // Versions
@@ -1132,7 +1102,7 @@ export class Stack {
             // Purged inside the adapter's own transaction, so these never reach
             // delete() and are announced here instead — from the records it
             // hands back, which are the last copies that will ever exist.
-            deletedRecords = await this.adapter.deleteUnreferencedAttachmentRecords(fileId, await this.familyTypeIds([SYSTEM_TYPES.ATTACHMENT]));
+            deletedRecords = await this.adapter.deleteUnreferencedAttachmentRecords(fileId, SYSTEM_TYPES.ATTACHMENT);
             const at = new Date();
             for (const record of deletedRecords) {
                 this.announce(new PendingChange('purge', { actor: normalizeActor(opts.actor) }), record, at);
@@ -1203,7 +1173,6 @@ export class Stack {
             ...(opts.filter !== undefined && { filter: opts.filter }),
             ...(opts.since !== undefined && { since: opts.since }),
             ...(opts.includeRecords !== undefined && { includeRecords: opts.includeRecords }),
-            ...(opts.includeUnlisted !== undefined && { includeUnlisted: opts.includeUnlisted }),
             ...(opts.onError !== undefined && { onError: opts.onError }),
             ...(opts.onReset !== undefined && { onReset: opts.onReset }),
         }, (change) => delivery.deliver(change));
@@ -1363,4 +1332,8 @@ export class Stack {
         };
     }
 }
+/** Every registered version of the named families, as concrete TypeIds. */
+function typeIdsOfFamilies(types, baseIds) {
+    return types.filter((t) => baseIds.includes(t.baseId)).map((t) => t.id);
+}
 //# sourceMappingURL=stack.js.map