@haverstack/core 0.33.0 → 0.36.0

package/dist/stack.js

@@ -19,16 +19,16 @@ import { validateContent, validateContentKeys, validatePatchValues, validateRese
 import { applyMergePatch } from './merge.js';
 import { hasGroupAdmin, isGroupAdminAssociation, validatePermissions } from './access.js';
 import { compareRecordedAttachments } from './attachment-download.js';
-import { ChangeEmitter, RelayDelivery, buildEmission, buildJournalEntry, assertSinceUsable, } from './changes.js';
+import { ChangeEmitter, RelayDelivery, PendingChange, assertSinceUsable } from './changes.js';
 import { SYSTEM_TYPES } from './types.js';
 import { StackClosedError, StackConflictError, StackMigrationError, StackNotFoundError, StackPermissionError, StackQueryError, StackSchemaDriftError, StackValidationError, StackVersionConflictError, } from './errors.js';
-import { assertQueryCapabilities, assertSortCapability, assertValidRelatedTo, assertValidJournalQuery, assertValidSort, filtersContent, validateAssociation, validateAssociations, } from './query-validation.js';
-import { GRANT_ACTION_SET, READ_COMPANIONS, grantConveys, matchesGrantTarget, validateGrantTarget, grantCoversGrantee, UNGRANTABLE_SYSTEM_TYPES, loadGrantRecords, } from './grants.js';
+import { assertQueryCapabilities, assertSortCapability, assertValidRelatedTo, assertValidJournalQuery, assertValidSort, assertAuthorityAssociations, assertDataAssociations, filtersContent, validateAssociation, validateAssociations, } from './query-validation.js';
+import { GRANT_ACTION_SET, READ_COMPANIONS, grantConveys, grantReach, matchesGrantTarget, validateGrantTarget, validateGrantee, grantCoversGrantee, UNGRANTABLE_SYSTEM_TYPES, loadGrantRecords, } from './grants.js';
 import { bindingFieldsOf, uniqueBindingFieldsOf } from './identity-bindings.js';
 import { assertAttachmentSize, assertContentSize } from './limits.js';
 import { validateParentId, validateRecordId, validateClockField, validateIdTimestampSkew, DEFAULT_ID_TIMESTAMP_SKEW_MS, } from './record-id.js';
 import { queryAllPages, findFirstMatch, lookupEntityByDid, MAX_QUERY_LIMIT, } from './stack-reads.js';
-import { associationDelta, associationEqual, associationIdentical, assertNonEmptyChangeSet, changeSetOps, bumpsVersion, takesIfVersion, effectiveChanges, stampGroupAdmin, stripAssociationAnnotation, isGroupRecord, } from './record-changes.js';
+import { associationDelta, associationEqual, associationIdentical, assertNonEmptyChangeSet, changeSetOps, bumpsVersion, takesIfVersion, effectiveChanges, stampGroupAdmin, isGroupRecord, } from './record-changes.js';
 import { ScopedStack } from './scoped-stack.js';
 // -------------------------------------------------------
 // Supporting types
@@ -97,8 +97,8 @@ export class Stack {
      * and nothing about work they deferred. A handler cannot fail the write:
      * there is nothing left to fail. See docs/spec/events.md § Handlers.
      */
-    emitChange(op, record, opts = {}) {
-        this.changes.emit(buildEmission(op, record, opts));
+    announce(change, record, at) {
+        this.changes.emit(change.emission(record, at));
     }
     /**
      * The actor for a `create` journal entry, read off the record as just
@@ -433,26 +433,27 @@ export class Stack {
         if (!type) {
             throw new StackQueryError(`Unknown type: "${typeId}". Call defineType() first.`);
         }
-        // updatedAt defaults to createdAt, not to the actual current time, so a
-        // plain import doesn't fabricate a fake edit.
-        //
-        // Copied, never aliased: the caller keeps its own reference to any Date
-        // it passed, and an import loop that reuses one Date across rows
-        // (`d.setTime(...)` per record — the obvious way to write one) would
-        // otherwise retro-edit every record it had already written, with no
-        // version bump and no change event. createdAt drives updatedAt and
-        // unlistedAt below, so one copy taken here covers all three.
-        // `instanceof Date`, not `!== undefined`: this runs before the error
-        // block below, so a non-Date reaching here off the wire would throw a
-        // raw TypeError out of .getTime() before validateClockField() could
-        // report it. Falling back keeps this line total; the error it recorded
-        // still throws below, so the fallback value is never actually stored.
+        // Copied, never aliased: an import loop that reuses one Date across rows
+        // (`d.setTime(...)` per record) would otherwise retro-edit every record
+        // it had already written, with no version bump and no change event.
+        // `instanceof Date`, not `!== undefined`, because this runs ahead of the
+        // error block below and .getTime() on a non-Date off the wire would
+        // throw before validateClockField() could report it; the fallback value
+        // never reaches storage, since that recorded error still throws.
         const createdAt = opts.createdAt instanceof Date ? new Date(opts.createdAt.getTime()) : new Date();
         const updatedAt = opts.updatedAt instanceof Date ? new Date(opts.updatedAt.getTime()) : createdAt;
+        // Ahead of every other check on these two lists: a caller that named
+        // the wrong surface asked for something this layer does not offer, and
+        // reporting its grantee as a malformed relationship target would
+        // describe the mistake as the wrong kind of problem.
+        assertDataAssociations(opts.associations ?? [], 'associations');
+        assertAuthorityAssociations(opts.permissions ?? [], 'permissions');
         const errors = [
             ...validateReservedKeys(content),
             ...validateContentKeys(content),
             ...validateContent(content, type.schema),
+            ...validateGrantee(typeId, content),
+            ...validateAssociations(opts.permissions, 'permissions'),
             ...validatePermissions(opts.permissions),
             ...validateAssociations(opts.associations),
             ...validateClockField(opts.createdAt, 'createdAt'),
@@ -475,8 +476,8 @@ export class Stack {
         await this.checkBindingsOnCreate(typeId, content);
         if (opts.id !== undefined) {
             validateRecordId(opts.id);
-            // Only when both are explicit: an `id` alone (no createdAt) stays a
-            // pure position choice, exactly as before this option existed.
+            // Only when both are explicit: an `id` alone is a pure position
+            // choice, with no second timestamp to agree with.
             if (opts.createdAt !== undefined) {
                 validateIdTimestampSkew(opts.id, this.idTimestampSkewMsValue, opts.createdAt.getTime(), 'createdAt');
             }
@@ -491,31 +492,25 @@ export class Stack {
         const associations = baseIdOf(typeId) === SYSTEM_TYPES.GROUP
             ? stampGroupAdmin(opts.associations, opts.entityId ?? this.ownerEntityId)
             : opts.associations;
-        // createdAt (hoisted above, alongside its validation) drives the ID
-        // when the caller doesn't supply one, so the two agree by construction
-        // rather than by coincidence — the same relationship an explicit `id`
-        // is checked against above.
-        // An explicit createdAt mints via generateIdForTimestamp(), which never
-        // clamps to "now" — generateId()'s monotonic floor would otherwise
-        // silently pull a deliberately historical id forward once this process
-        // has minted any live id past it. The no-createdAt path keeps
-        // generateId(), unaffected and still monotonic-safe.
+        // createdAt drives the id, so the two agree by construction rather than
+        // by coincidence. An explicit one mints via generateIdForTimestamp(),
+        // which never clamps to "now": generateId()'s monotonic floor would
+        // otherwise pull a deliberately historical id forward once this process
+        // has minted any live id past it.
         const id = opts.id ??
             (opts.createdAt !== undefined
                 ? generateIdForTimestamp(createdAt.getTime())
                 : generateId(createdAt.getTime()));
         // An id field a caller supplies is a value or it is absent — never the
-        // empty string, which names nobody. Refused rather than dropped: an
-        // ignored field is the silent-normalization this mapper family was just
-        // fixed for, one layer up.
+        // empty string, which names nobody. Refused rather than dropped, so the
+        // caller is never silently ignored.
         for (const field of ['entityId', 'appId', 'principalId']) {
             if (opts[field] === '') {
                 throw new StackQueryError(`Invalid ${field}: the empty string is not an id.`);
             }
         }
         // Every create naming a parent owes the reference check, whether or not
-        // it supplied an id: a destination a caller names has to be one that
-        // exists. This is the read an ordinary create used to skip.
+        // it supplied an id: a destination a caller names has to exist.
         if (opts.parentId !== undefined)
             await this.assertParentExists(id, opts.parentId);
         const record = {
@@ -525,10 +520,8 @@ export class Stack {
             updatedAt,
             content,
             version: 1,
-            // Read for presence, not truthiness — every one of these is checked
-            // above, so '' never reaches here and absence is the only thing a
-            // falsy value could mean. Presence says that outright instead of
-            // relying on it.
+            // Presence, not truthiness: '' is refused above, so absence is the
+            // only thing a falsy value could mean here.
             ...(opts.parentId !== undefined && { parentId: opts.parentId }),
             ...(opts.entityId !== undefined && { entityId: opts.entityId }),
             ...(opts.appId !== undefined && { appId: opts.appId }),
@@ -542,10 +535,9 @@ export class Stack {
             ...(associations?.length && { associations }),
             ...(opts.unlisted && { unlistedAt: createdAt }),
         };
-        const created = await this.adapter.createRecord(record, {
-            journal: buildJournalEntry('create', { actor: Stack.createActor(record) }),
-        });
-        this.emitChange('create', created);
+        const change = new PendingChange('create', { actor: Stack.createActor(record) });
+        const created = await this.adapter.createRecord(record, { journal: change.journal });
+        this.announce(change, created);
         return created;
     }
     /**
@@ -589,20 +581,14 @@ export class Stack {
         return opts.presentAt === 'latest' ? this.presentAtLatest(record) : record;
     }
     /**
-     * Apply a change set — content patch, `parentId`, `permissions`,
-     * `associations`, `unlisted`, in any combination — as one atomic write
-     * producing one version and one snapshot. Keys are read for presence, so
-     * `unlisted: false` and `parentId: null` are changes.
-     *
-     * Every key present is checked against the record as it stands, and a
-     * change set already satisfied in all of them writes nothing and returns
-     * the record unchanged. The ops the change event carries are derived
-     * from that same comparison, so naming an aspect without moving it is
-     * never reported as moving it.
+     * Apply a change set as one atomic write — see the StackClient
+     * declaration above for what it accepts. Atomicity is what it is for: a
+     * publish is one act, so nothing it names may half-land.
      *
-     * Content is validated against the record's *current* stored type and
-     * `typeId` never changes (see docs/spec/data-model.md § Type
-     * migrations). See docs/spec/data-model.md § Mutations.
+     * Every key present is checked against the record as it stands, and a set
+     * already satisfied in all of them writes nothing. Content is validated
+     * against the record's *current* stored type; `typeId` never changes here.
+     * See docs/spec/data-model.md § Mutations.
      */
     async mutate(id, changes, opts = {}) {
         this.assertOpen();
@@ -625,19 +611,32 @@ export class Stack {
         // writes nothing.
         if (ops.length === 0)
             return existing;
-        // A change set touching only `associations` 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/updatedVia.
-        // See docs/spec/versioning.md § Version history.
+        // 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/updatedVia. See docs/spec/versioning.md § Version history.
         const bumps = bumpsVersion(ops);
         // Computed against the same before/after changeSetOps compared, so
-        // whether associate/dissociate appear in `ops` and what these list can
-        // never disagree. See docs/spec/events.md § The event shape.
-        const assocDelta = changes.associations
-            ? associationDelta(existing.associations ?? [], changes.associations)
-            : undefined;
+        // whether associate/dissociate/permissions appear in `ops` and what
+        // the journal lists can never disagree. Both halves of the partition
+        // produce the same tagged edits and travel as one list: the journal's
+        // argument is prior state, and an ACL element's is no different from a
+        // tag's. 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: Stack.actorFrom(opts),
+            ...(ops.includes('reparent') && { previousParentId }),
+            ...(assocDelta.length && { associations: assocDelta }),
+        });
         const updated = await this.adapter.mutateRecord(id, effectiveChanges(changes, ops), {
             ...(bumps
                 ? this.writeOptions(existing, opts)
@@ -646,22 +645,9 @@ export class Stack {
                     updatedVia: opts.updatedVia,
                 }),
             bumpsVersion: bumps,
-            journal: buildJournalEntry(ops, {
-                actor: Stack.actorFrom(opts),
-                ...(ops.includes('reparent') && { previousParentId }),
-                ...(assocDelta && {
-                    associationsAdded: assocDelta.added,
-                    associationsRemoved: assocDelta.removed,
-                    associationsReplaced: assocDelta.replaced,
-                }),
-            }),
-        });
-        this.emitChange(ops, updated, {
-            ...(ops.includes('reparent') && { previousParentId }),
-            ...(!bumps && { actor: Stack.actorFrom(opts) }),
-            ...(assocDelta?.added.length && { associationsAdded: assocDelta.added }),
-            ...(assocDelta?.removed.length && { associationsRemoved: assocDelta.removed }),
+            journal: change.journal,
         });
+        this.announce(change, updated);
         return updated;
     }
     /**
@@ -685,6 +671,15 @@ export class Stack {
      */
     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 errors = [
             ...(contentPatch
                 ? [
@@ -693,7 +688,9 @@ export class Stack {
                     ...validateContentKeys(contentPatch),
                 ]
                 : []),
-            ...(permissions ? validatePermissions(permissions) : []),
+            ...(permissions
+                ? [...validateAssociations(permissions, 'permissions'), ...validatePermissions(permissions)]
+                : []),
             ...(associations ? validateAssociations(associations) : []),
         ];
         if (errors.length > 0)
@@ -709,7 +706,10 @@ export class Stack {
                 throw new StackQueryError(`Unknown type: "${existing.typeId}"`);
             }
             merged = applyMergePatch(existing.content, contentPatch);
-            const contentErrors = validateContent(merged, type.schema);
+            const contentErrors = [
+                ...validateContent(merged, type.schema),
+                ...validateGrantee(existing.typeId, merged),
+            ];
             if (contentErrors.length > 0)
                 throw new StackValidationError(contentErrors);
             if (existing.typeId === `${SYSTEM_TYPES.ATTACHMENT}@1`) {
@@ -736,22 +736,15 @@ export class Stack {
         return merged;
     }
     /**
-     * Refuse a write that would leave a `_group` Record with no `admin` on
-     * its roster. Asked of the roster the write would *produce* — the one
-     * place a change-set check reads the post-state rather than the
-     * pre-state, because the rule is about what is left behind rather than
-     * what the caller named.
+     * Refuse a write that would leave a `_group` Record with no `admin` on its
+     * roster. Asked of the roster the write would *produce*, which is the
+     * whole of the self-removal question: an admin removing themselves passes
+     * while another remains and is refused when they are the last, without
+     * either case naming who is going.
      *
-     * That framing is the whole of the self-removal question: an `admin`
-     * removing themselves passes while another remains and is refused when
-     * they are the last, and neither case needs to know whose entry went.
-     *
-     * Lives here rather than in `ScopedStack` deliberately. Who may write a
-     * `_group` is a permission question and belongs to the gate up there;
-     * this is an integrity constraint on the Record, so it binds every
-     * requester — the stack owner included, who would otherwise be the hole
-     * that stops anything downstream relying on the invariant.
-     * See docs/spec/identity.md § Group.
+     * An integrity constraint on the Record, not a permission question, so it
+     * lives here rather than in `ScopedStack` and binds every requester — the
+     * stack owner included. See docs/spec/identity.md § Group.
      */
     assertGroupAdminRemains(record, next) {
         if (!isGroupRecord(record))
@@ -762,24 +755,19 @@ export class Stack {
             'least one `admin` relationship association. Name the incoming admin in the same write.');
     }
     /**
-     * Add an association to a record. Never bumps `version`/`updatedAt` and
-     * never snapshots — a set-add composes correctly regardless of write
-     * order, so it needs neither the OCC `ifVersion` guards content,
-     * `parentId` and `permissions`, nor the rollback history that guards.
-     * See docs/spec/versioning.md § Version history.
+     * Add an association to a record — no-bump and no snapshot, per the
+     * StackClient declaration above.
      *
      * An association the record already holds, saying the same thing, is a
      * no-op; one matching an existing association's identity but naming a
      * different `attachmentRecordId` — or none, which clears the one stored —
-     * re-points that association in place, rather than adding a second
-     * reference to the same file. The emitted event's `associationsAdded`
-     * carries the association as it now stands either way — a re-point's
-     * old `attachmentRecordId` is not reported anywhere; nothing keeps it
-     * once this call lands. See docs/spec/events.md § The event shape.
-     * Returns the record as it now stands — unchanged on a no-op.
+     * re-points it in place rather than adding a second reference to the same
+     * file. What a re-point overwrote is kept only by the journal, on that
+     * entry's `repoint`. See docs/spec/journal.md § The entry.
      */
     async associate(id, association, opts = {}) {
         this.assertOpen();
+        assertDataAssociations([association], 'associate()');
         const errors = validateAssociation(association);
         if (errors.length > 0)
             throw new StackValidationError(errors);
@@ -792,32 +780,28 @@ export class Stack {
         }
         const replaced = (existing.associations ?? []).find((a) => associationEqual(a, association));
         await this.checkAttachmentAssociationPointers([association]);
-        const updated = await this.adapter.associate(id, association, {
-            journal: buildJournalEntry('associate', {
-                actor: Stack.actorFrom(opts),
-                associationsAdded: [association],
-                // The association this call overwrites in place, if any. Nothing
-                // else retains the attachmentRecordId it carried.
-                ...(replaced && { associationsReplaced: [replaced] }),
-            }),
-        });
-        this.emitChange('associate', updated, {
+        const change = new PendingChange('associate', {
             actor: Stack.actorFrom(opts),
-            associationsAdded: [association],
+            // A re-point carries what it overwrote: nothing else retains the
+            // attachmentRecordId that association held.
+            associations: [
+                replaced ? { op: 'repoint', association, previous: replaced } : { op: 'add', association },
+            ],
         });
+        const updated = await this.adapter.associate(id, association, { journal: change.journal });
+        this.announce(change, updated);
         return updated;
     }
     /**
-     * Remove an association from a record. Never bumps `version`/`updatedAt`
-     * — see associate(). Matched by kind, label, and payload. No-op if not
-     * found. The emitted event's `associationsRemoved` names the association
-     * by identity only — an attachment's `attachmentRecordId` is not
-     * repeated there, since it no longer describes anything current. See
-     * docs/spec/events.md § The event shape. Returns the record as it now
-     * stands — unchanged on a no-op.
+     * Remove an association from a record — see associate(). Matched by kind,
+     * label and payload; a no-op if not found. The emitted event names the
+     * association by identity only, since an attachment's
+     * `attachmentRecordId` describes nothing current once it is gone; the
+     * journal is where it survives.
      */
     async dissociate(id, association, opts = {}) {
         this.assertOpen();
+        assertDataAssociations([association], 'dissociate()');
         const errors = validateAssociation(association);
         if (errors.length > 0)
             throw new StackValidationError(errors);
@@ -836,18 +820,84 @@ export class Stack {
         if (isGroupAdminAssociation(association)) {
             this.assertGroupAdminRemains(existing, (existing.associations ?? []).filter((a) => !associationEqual(a, association)));
         }
-        const updated = await this.adapter.dissociate(id, association, {
-            journal: buildJournalEntry('dissociate', {
-                actor: Stack.actorFrom(opts),
-                associationsRemoved: [stripAssociationAnnotation(matched)],
-            }),
+        const change = new PendingChange('dissociate', {
+            actor: Stack.actorFrom(opts),
+            // In full, annotation included — what makes a removal as undoable
+            // from the log as a re-point is. The frame this becomes still names
+            // identity only. See docs/spec/journal.md § The entry.
+            associations: [{ op: 'remove', previous: matched }],
         });
-        this.emitChange('dissociate', updated, {
+        const updated = await this.adapter.dissociate(id, association, { journal: change.journal });
+        this.announce(change, updated);
+        return updated;
+    }
+    /**
+     * Extend who reaches a record by one element. 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.
+     */
+    async grantAccess(id, permission, opts = {}) {
+        this.assertOpen();
+        assertAuthorityAssociations([permission], 'grantAccess()');
+        const errors = validateAssociation(permission, 'permission');
+        if (errors.length > 0)
+            throw new StackValidationError(errors);
+        const existing = await this.requireRecord(id);
+        const current = existing.permissions ?? [];
+        if (current.some((p) => associationEqual(p, permission)))
+            return existing;
+        this.assertPermissionSet([...current, permission]);
+        const change = new PendingChange('permissions', {
+            actor: Stack.actorFrom(opts),
+            associations: [{ op: 'add', association: permission }],
+        });
+        const updated = await this.adapter.associate(id, permission, { journal: change.journal });
+        this.announce(change, updated);
+        return updated;
+    }
+    /**
+     * Withdraw one element 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, permission, opts = {}) {
+        this.assertOpen();
+        assertAuthorityAssociations([permission], 'revokeAccess()');
+        const errors = validateAssociation(permission, 'permission');
+        if (errors.length > 0)
+            throw new StackValidationError(errors);
+        const existing = await this.requireRecord(id);
+        const current = existing.permissions ?? [];
+        const matched = current.find((p) => associationEqual(p, permission));
+        if (!matched)
+            return existing;
+        this.assertPermissionSet(current.filter((p) => !associationEqual(p, permission)));
+        const change = new PendingChange('permissions', {
             actor: Stack.actorFrom(opts),
-            associationsRemoved: [stripAssociationAnnotation(matched)],
+            associations: [{ op: 'remove', previous: matched }],
         });
+        const updated = await this.adapter.dissociate(id, permission, { journal: change.journal });
+        this.announce(change, updated);
         return updated;
     }
+    /**
+     * Hold a permission set to the cross-element invariant — see
+     * validatePermissions() in access.ts for why it reads the post-state.
+     */
+    assertPermissionSet(next) {
+        const errors = validatePermissions(next);
+        if (errors.length > 0)
+            throw new StackValidationError(errors);
+    }
+    /** The record, or the not-found refusal every mutating verb owes. */
+    async requireRecord(id) {
+        const record = await this.adapter.getRecord(id);
+        if (!record)
+            throw new StackNotFoundError(`Record not found: "${id}"`);
+        return record;
+    }
     /**
      * The checks a *caller-named* destination owes, before the cycle walk:
      * `parentId` is a real, well-formed record id. Format first, so a
@@ -868,24 +918,18 @@ export class Stack {
     }
     /**
      * Refuse an edge that would make a record its own ancestor — asked at
-     * every site that adds one: a change set naming `parentId`, a restore
-     * putting a container back, and a create naming both its own id and a parent. Nothing
-     * downstream (a generator deriving a page path, a folder view) is
-     * written to survive a cycle.
+     * every site that adds one. Nothing downstream (a generator deriving a
+     * page path, a folder view) is written to survive a cycle.
      *
-     * Walks with the unscoped adapter deliberately: a walk that skipped the
-     * links a requester cannot read would let a cycle be assembled through
-     * them and break the invariant for every reader. The walk is bounded
-     * because a chain long enough to exhaust it is already pathological.
+     * Walks with the unscoped adapter: a walk that skipped the links a
+     * requester cannot read would let a cycle be assembled through them and
+     * break the invariant for every reader.
      *
      * Read-then-write, so two moves racing on opposite ends of one chain can
-     * both pass — closing that means the invariant lives in the adapter,
-     * where the write is atomic, which puts a graph constraint in the
-     * storage contract every adapter then implements. Same deferral as
-     * checkBindingUnique() above. Consumers that walk `parentId` should
-     * carry a visited set rather than trust this alone; MAX_PARENT_DEPTH is
-     * the same posture applied here.
-     * See docs/spec/data-model.md § Reparenting.
+     * both pass — the same deferral as checkBindingUnique() above, since
+     * closing it would put a graph constraint in the storage contract.
+     * Consumers walking `parentId` should carry a visited set rather than
+     * trust this alone. See docs/spec/data-model.md § Reparenting.
      */
     async assertNoParentCycle(id, parentId) {
         let cursor = parentId;
@@ -909,6 +953,12 @@ export class Stack {
      * version; a no-op if already deleted. `_config` is never deletable
      * (docs/spec.md § The `_config` record). See docs/spec/versioning.md
      * § Deletion.
+     *
+     * A purge reports the files the record referenced. It deletes none of
+     * them — byte lifetime is not the purged record's to decide — but it
+     * destroys the only rows naming them, so a caller who means to erase the
+     * bytes too has nowhere else to read the argument from afterwards. See
+     * docs/spec/attachments.md § A purge strands the bytes it referenced.
      */
     async delete(id, opts = {}) {
         this.assertOpen();
@@ -920,27 +970,48 @@ export class Stack {
             // write: a read here instead would race the delete, and afterwards
             // there is nothing left to read. Null means there was no record, so
             // nothing was purged and nothing is announced.
+            const change = new PendingChange('hard-delete', { actor: Stack.actorFrom(opts) });
             const purged = await this.adapter.deleteRecord(id, {
                 hard: true,
                 expectedVersion: opts.ifVersion,
+                journal: change.journal,
             });
-            if (purged)
-                this.emitChange('hard-delete', purged, { actor: Stack.actorFrom(opts) });
-            return;
+            if (!purged)
+                return { referencedFileIds: [] };
+            this.announce(change, purged);
+            return { referencedFileIds: await this.referencedFileIds(purged) };
         }
         const existing = await this.adapter.getRecord(id);
         if (!existing) {
             throw new StackNotFoundError(`Record not found: "${id}"`);
         }
         this.checkIfVersion(existing, opts.ifVersion);
+        // A tombstone's references stand — undelete() must find its
+        // attachments intact — so nothing is stranded and nothing is reported.
         if (existing.deletedAt)
-            return;
+            return { referencedFileIds: [] };
+        const change = new PendingChange('delete', { actor: Stack.actorFrom(opts) });
         const deleted = await this.adapter.deleteRecord(id, {
             ...this.writeOptions(existing, opts),
-            journal: buildJournalEntry('delete', { actor: Stack.actorFrom(opts) }),
+            journal: change.journal,
         });
         if (deleted)
-            this.emitChange('delete', deleted);
+            this.announce(change, deleted);
+        return { referencedFileIds: [] };
+    }
+    /**
+     * The files a record references, by the same definition
+     * deleteAttachment() and the garbage sweep use: attachment associations
+     * and top-level `file-ref` content fields. An `_attachment` record's own
+     * `fileId` is a plain string by design and is not one, which is why
+     * purging a metadata record reports nothing — see initSystemTypes().
+     */
+    async referencedFileIds(record) {
+        const fromAssociations = (record.associations ?? []).flatMap((a) => a.kind === 'attachment' ? [a.fileId] : []);
+        const type = await this.getType(record.typeId);
+        const content = record.content;
+        const fromContent = Object.entries(type?.schema ?? {}).flatMap(([field, def]) => def.kind === 'file-ref' && typeof content[field] === 'string' ? [content[field]] : []);
+        return [...new Set([...fromAssociations, ...fromContent])];
     }
     /**
      * Reverse a soft delete. Idempotent — undeleting a record that isn't
@@ -957,11 +1028,12 @@ export class Stack {
         this.checkIfVersion(existing, opts.ifVersion);
         if (!existing.deletedAt)
             return existing;
+        const change = new PendingChange('undelete', { actor: Stack.actorFrom(opts) });
         const undeleted = await this.adapter.undeleteRecord(id, {
             ...this.writeOptions(existing, opts),
-            journal: buildJournalEntry('undelete', { actor: Stack.actorFrom(opts) }),
+            journal: change.journal,
         });
-        this.emitChange('undelete', undeleted);
+        this.announce(change, undeleted);
         return undeleted;
     }
     /**
@@ -1019,18 +1091,13 @@ export class Stack {
         return this.adapter.getVersions(id);
     }
     /**
-     * A record's change journal, oldest first — what moved, who moved it,
-     * and the association deltas nothing else retains. The mutation
-     * surface's read, on the same footing as getVersions(): a log of who
-     * changed what, gated on current read access, would make a record's past
-     * exactly as reachable as its present. `ScopedStack` applies that gate;
-     * this layer is unscoped and trusted by definition.
+     * A record's change journal, oldest first — what moved, who moved it, and
+     * the association deltas nothing else retains. `ScopedStack` applies the
+     * mutate-surface gate; this layer is unscoped and trusted by definition.
      *
-     * An adapter with no journal to read refuses rather than answering an
-     * empty log — "nothing changed" and "this stack does not remember" are
-     * not the same answer, and a caller reconstructing an association's
-     * history cannot tell them apart. The refusal is the adapter's own, so
-     * it can name why. See docs/spec/versioning.md § The change journal.
+     * A record that isn't there is StackNotFoundError, a purged one included:
+     * a destroyed log and an empty one are not the same answer.
+     * See docs/spec/journal.md § Reading it.
      */
     async getJournal(id, query = {}) {
         this.assertOpen();
@@ -1044,10 +1111,8 @@ export class Stack {
     /**
      * Restore a record to a previous version by creating a new version —
      * never rewrites history. The snapshot is validated against its own
-     * stored typeId (not the record's current type), restores `parentId`
-     * (absent on the snapshot is the root, so a restore always settles
-     * containment), and restores neither associations nor permissions. See
-     * docs/spec/versioning.md § Restore semantics.
+     * stored typeId, and puts back `content` and `typeId` alone: a snapshot
+     * carries nothing else. See docs/spec/versioning.md § Restore semantics.
      */
     async restoreVersion(id, version, opts = {}) {
         this.assertOpen();
@@ -1064,7 +1129,10 @@ export class Stack {
         if (!type) {
             throw new StackQueryError(`Unknown type: "${target.typeId}"`);
         }
-        const errors = validateContent(target.content, type.schema);
+        const errors = [
+            ...validateContent(target.content, type.schema),
+            ...validateGrantee(target.typeId, target.content),
+        ];
         if (errors.length > 0) {
             throw new StackValidationError(errors);
         }
@@ -1072,60 +1140,34 @@ export class Stack {
             this.checkConfigEntityIdUnchanged(existing.content.entityId, target.content.entityId);
         }
         // Restoring is a write like any other, so it owes the same immutability
-        // check a content patch pays — a snapshot taken before a card claimed its DID
-        // would otherwise move the binding by rolling content back. Uniqueness
-        // needs no separate check here: a restore can only put back a value this
-        // same card already held, which immutability already refuses to change.
+        // check a content patch pays: a snapshot taken before a card claimed
+        // its DID would otherwise move the binding by rolling content back.
+        // Uniqueness needs none — a restore can only put back a value this same
+        // card already held.
         for (const field of bindingFieldsOf(baseIdOf(target.typeId))) {
             this.checkBindingImmutable(baseIdOf(target.typeId), field, existing.content[field], target.content[field]);
         }
-        // A restore that puts a container back is an edge-adding site like
-        // a change set's `parentId`, and the chain above that container may have moved since
-        // the snapshot was taken. The cycle walk therefore applies — but
-        // assertParentExists() deliberately does not: a restore is not a caller
-        // naming a destination, it is history being put back, and the container
-        // may have been hard-deleted since. Refusing here would make an
-        // unrelated deletion cost the record its content rollback, which is the
-        // recoverability this whole verb exists for. A dangling parentId is
-        // legal at rest anyway — deleting a container never touches its
-        // children. See docs/spec/versioning.md § Restore semantics.
-        const previousParentId = existing.parentId ?? null;
-        const targetParentId = target.parentId ?? null;
-        const moves = targetParentId !== previousParentId;
-        if (moves && targetParentId !== null) {
-            await this.assertNoParentCycle(id, targetParentId);
-        }
-        // Associations never restore, for any Record — a snapshot never
-        // carries them, so there's nothing here for the adapter to roll back.
-        // See docs/spec/versioning.md § Restore semantics.
+        // A restore adds no containment edge and takes none away, so there is
+        // no cycle for it to close and nothing for the destination checks to
+        // gate. See docs/spec/versioning.md § Restore semantics.
+        const change = new PendingChange('restore', { actor: Stack.actorFrom(opts) });
         const restored = await this.adapter.restoreVersion(id, version, {
             ...this.writeOptions(existing, opts),
-            journal: buildJournalEntry('restore', {
-                actor: Stack.actorFrom(opts),
-                ...(moves && { previousParentId }),
-            }),
+            journal: change.journal,
         });
-        this.emitChange('restore', restored, moves ? { previousParentId } : {});
+        this.announce(change, restored);
         return restored;
     }
     /**
-     * Commit a per-record migration: replace `content` and `typeId` together
-     * in one step, validated against `toTypeId`'s schema exactly as
-     * create()/mutate() validate against a type's schema. The single-record
-     * counterpart to migrateAll() — content here is supplied by the caller
-     * (computed client-side by the type's owning app, per
-     * docs/spec/wire-format.md § Migration commit) rather than a registered
-     * Migration function. Snapshots the prior state to version history, same
-     * as mutate()/restoreVersion(), and takes the same optional `ifVersion`
-     * precondition every version-bumping mutation takes — checked atomically
-     * at the adapter, not here (see docs/spec/versioning.md § Optimistic
-     * concurrency).
+     * Commit a per-record migration — the single-record counterpart to
+     * migrateAll(), with `content` supplied by the caller rather than by a
+     * registered Migration function. See docs/spec/wire-format.md § Migration
+     * commit.
      *
      * Because `content` is a full replacement written under a new `typeId`,
      * this is create-shaped at the destination *and* update-shaped over the
-     * record as it stands, so it owes both sets of integrity checks — the
-     * binding rules, the attachment rules, and `_config`'s. Missing either
-     * half would make migrate a second, unguarded write path to the same
+     * record as it stands, so it owes both sets of integrity checks. Missing
+     * either half would make migrate a second, unguarded write path to a
      * state create()/mutate() refuse to reach.
      */
     async commitMigration(id, toTypeId, content, opts = {}) {
@@ -1162,6 +1204,7 @@ export class Stack {
             ...validateReservedKeys(content),
             ...validateContentKeys(content),
             ...validateContent(content, type.schema),
+            ...validateGrantee(toTypeId, content),
         ];
         if (errors.length > 0) {
             throw new StackValidationError(errors);
@@ -1196,11 +1239,12 @@ export class Stack {
         if (id === SYSTEM_TYPES.CONFIG) {
             this.checkConfigEntityIdUnchanged(existing.content.entityId, content.entityId);
         }
+        const change = new PendingChange('migrate', { actor: Stack.actorFrom(opts) });
         const migrated = await this.adapter.commitMigration(id, toTypeId, content, {
             ...this.writeOptions(existing, opts),
-            journal: buildJournalEntry('migrate', { actor: Stack.actorFrom(opts) }),
+            journal: change.journal,
         });
-        this.emitChange('migrate', migrated);
+        this.announce(change, migrated);
         return migrated;
     }
     /** Uniqueness for every unique binding field a newly created card claims. */
@@ -1229,18 +1273,14 @@ export class Stack {
         }
     }
     /**
-     * Bindings across a migration. `content` is a full replacement rather
-     * than a patch, so there is no "field absent from the patch" case to
-     * exempt: every binding field either keeps its value, moves to a new
-     * one, or is shed by omission — and immutability refuses the last two
-     * whichever family they happen in. Asked across the union of the two
-     * families' binding fields, so a card can neither shed its DID by
-     * migrating out of `_entity`/`_app` nor pick one up on the way in.
+     * Bindings across a migration. `content` is a full replacement, so every
+     * binding field either keeps its value, moves to a new one, or is shed by
+     * omission — and immutability refuses the last two. Asked across the
+     * union of both families' binding fields, so a card can neither shed its
+     * DID by migrating out of `_entity`/`_app` nor pick one up on the way in.
      *
-     * Uniqueness is asked only of the destination family, which is where the
-     * record's claim lives once the write lands, and excludes the record
-     * itself — re-sending the value it already holds claims nothing.
-     * See docs/spec/identity.md § DID bindings.
+     * Uniqueness is asked only of the destination family, excluding the
+     * record itself. See docs/spec/identity.md § DID bindings.
      */
     async checkBindingsOnMigrate(fromTypeId, toTypeId, id, existing, content) {
         const fromFamily = baseIdOf(fromTypeId);
@@ -1264,16 +1304,10 @@ export class Stack {
      * claiming one value would leave that lookup without a single answer, and
      * ambiguity is all an impersonating card needs. Enforced here rather than
      * by schema, since uniqueness is a property of the set, not of the value.
-     * Called by the paths that can introduce a binding: create and update.
      *
-     * Short-circuits on the first clash rather than materialising the family,
-     * so a stack whose `_entity` family is larger than a single scan settles
-     * the common case — the value is already taken — without walking the rest.
-     *
-     * Read-then-write, so two creates racing on one value can both pass.
-     * Closing that properly means a unique index over a JSON field, which
-     * each adapter would enforce separately — a decision about where
-     * uniqueness lives, not a local fix.
+     * Read-then-write, so two creates racing on one value can both pass:
+     * closing that means a unique index over a JSON field, which is a
+     * decision about where uniqueness lives rather than a local fix.
      * See docs/spec/identity.md § DID bindings.
      */
     async checkBindingUnique(family, field, value, excludeId) {
@@ -1437,7 +1471,11 @@ export class Stack {
             // The metadata record is written inside the adapter, so create()
             // never sees it and this is the only place it can be announced.
             const record = await this.adapter.putAttachmentWithMetadata(data, mimeType, filename, appId);
-            this.emitChange('create', record);
+            // The one emission with no journal half of its own: the far side
+            // wrote the record, so it appended the entry in that same write —
+            // the same division saveVersion() follows over this adapter. See
+            // docs/spec/journal.md § The entry set is the event set.
+            this.announce(new PendingChange('create'), record);
             return record;
         }
         const fileId = await this.adapter.putAttachment(data);
@@ -1503,7 +1541,7 @@ export class Stack {
             deletedRecords = await this.adapter.deleteUnreferencedAttachmentRecords(fileId, await this.attachmentTypeIds());
             const at = new Date();
             for (const record of deletedRecords) {
-                this.emitChange('hard-delete', record, { actor: Stack.actorFrom(opts), at });
+                this.announce(new PendingChange('hard-delete', { actor: Stack.actorFrom(opts) }), record, at);
             }
         }
         else {
@@ -1724,9 +1762,10 @@ export class Stack {
     // -------------------------------------------------------
     /**
      * Create _grant records authorizing entities to act on records of
-     * specific types; null target writes a default grant (any authenticated
-     * entity); `{ groupId }` targets a `_group` Record's roster instead of a
-     * single entity.
+     * specific types. The target is the grantee the record carries:
+     * `{ kind: 'entity' }` for one DID, `{ kind: 'group' }` for a `_group`
+     * Record's roster at a role, `{ kind: 'authenticated' }` for any
+     * authenticated entity.
      *
      * Granting an **app** a `-own` action does not contain it the way the
      * suffix suggests: when that app acts for someone, `-own` is read as the
@@ -1736,9 +1775,8 @@ export class Stack {
      * needs, not the suffix that looks narrowest. See
      * docs/spec/access-control.md § Delegation: principal and subject.
      *
-     * The grantee lives in content.granteeEntityId / content.granteeGroupId,
-     * not record.entityId. See docs/spec/access-control.md § Type-level
-     * grants.
+     * The grantee lives in content.grantee, not record.entityId. See
+     * docs/spec/access-control.md § Type-level grants.
      */
     async grant(target, grants) {
         this.assertOpen();
@@ -1749,37 +1787,43 @@ export class Stack {
             records.push(await this.create(`${SYSTEM_TYPES.GRANT}@1`, {
                 typeId: g.typeId,
                 actions: g.actions,
-                ...(typeof target === 'string' && { granteeEntityId: target }),
-                ...(target !== null && typeof target === 'object' && { granteeGroupId: target.groupId }),
+                grantee: target,
             }));
         }
         return records;
     }
     /**
-     * List _grant records. Omit `target` for all grants; pass null for only
-     * default grants; pass `{ groupId }` for grants naming that exact group;
-     * pass a specific entityId for the grants that currently apply to that
-     * entity (ones naming them, ones naming a group they belong to, plus
-     * every default grant) — the same resolution hasGrant() uses.
+     * List _grant records. Omit `query` for all grants;
+     * `{ kind: 'authenticated' }` for only default grants;
+     * `{ kind: 'group' }` for grants naming that exact group and role, or
+     * `role: 'any'` for every grant naming the group;
+     * `{ kind: 'entity' }` for the grants that currently apply to that entity
+     * (ones naming them, ones naming a group they belong to at a role they
+     * hold, plus every default grant) — the same resolution hasGrant() uses.
+     *
+     * Every arm but `entity` answers identity — what `grant()` would have
+     * written with the same argument. The `entity` arm answers coverage, so
+     * its result is not a preview of what `revoke()` would withdraw.
+     * See docs/spec/access-control.md § Type-level grants.
      */
-    async listGrants(target) {
+    async listGrants(query) {
         this.assertOpen();
-        if (target !== undefined)
-            validateGrantTarget(target);
+        if (query !== undefined)
+            validateGrantTarget(query, true);
         const all = await loadGrantRecords((q) => this.query(q));
-        if (target === undefined)
+        if (query === undefined)
             return all;
-        if (target === null || typeof target === 'object') {
-            return all.filter((r) => matchesGrantTarget(r.content, target));
+        if (query.kind !== 'entity') {
+            return all.filter((r) => matchesGrantTarget(r.content, query));
         }
-        // target is an EntityId: resolve group rosters, since a grant naming a
-        // group the entity belongs to also currently applies to them. Shares
+        // An entity query resolves group rosters, since a grant naming a group
+        // the entity belongs to also currently applies to them. Shares
         // grantCoversGrantee() with the access checks, so a listing can't
         // disagree with them about who a grant covers.
         const groupRoles = new Map();
         const result = [];
         for (const r of all) {
-            const covers = await grantCoversGrantee(r.content, target, {
+            const covers = await grantCoversGrantee(r.content, query.entityId, {
                 allowDefault: true,
                 allowGroup: true,
                 groupRoles,
@@ -1792,20 +1836,32 @@ export class Stack {
     }
     /**
      * The inverse of grant(): soft-deletes _grant records matching `target`
-     * (null for default grants) and each `{ typeId, actions }` pair, at the
-     * same granularity grant() writes. A soft delete like any other — the
-     * owner can undelete a revocation.
+     * and each `{ typeId, actions }` pair, at the same granularity grant()
+     * writes — the grantee is matched whole, role included. A soft delete
+     * like any other — the owner can undelete a revocation.
+     *
+     * Returns the grants it withdrew, as they stood, so a revocation that
+     * matched nothing says so rather than passing in silence. An empty result
+     * is not an error — a grant already withdrawn or never written is the
+     * ordinary case, and re-running a revocation has to stay safe.
+     * See docs/spec/access-control.md § Type-level grants.
      */
     async revoke(target, grants) {
         this.assertOpen();
         validateGrantTarget(target);
+        const revoked = [];
         const all = await loadGrantRecords((q) => this.query(q));
         for (const g of grants) {
             const familyId = baseIdOf(g.typeId);
             const actionSet = new Set(g.actions);
             const matches = all.filter((r) => {
                 const c = r.content;
-                if (baseIdOf(c.typeId) !== familyId)
+                // Establishes the family and that `actions` is a list, so the exact
+                // match below reads a real one. Matched against the stored list
+                // rather than the reach, so a grant carrying an action this
+                // vocabulary drops is not withdrawn by a target that omits it.
+                const reach = grantReach(c);
+                if (!reach || reach.familyId !== familyId)
                     return false;
                 if (!matchesGrantTarget(c, target))
                     return false;
@@ -1813,8 +1869,10 @@ export class Stack {
             });
             for (const match of matches) {
                 await this.delete(match.id);
+                revoked.push(match);
             }
         }
+        return revoked;
     }
     // -------------------------------------------------------
     // Private helpers
@@ -1892,8 +1950,22 @@ export class Stack {
         await this.defineType(`${SYSTEM_TYPES.GRANT}@1`, 'Grant', {
             typeId: { kind: 'string', required: true },
             actions: { kind: 'array', items: { kind: 'string' }, required: true },
-            granteeEntityId: { kind: 'string' },
-            granteeGroupId: { kind: 'string' },
+            // Required, and closed: a Grant's reach is spelled by its `grantee`,
+            // so a record arriving without one is refused here rather than read
+            // as a grant to every authenticated entity. The arms differ in which
+            // fields they carry, which a schema cannot express — evaluation reads
+            // the `kind` and confers nothing on one it does not recognize.
+            // See docs/spec/access-control.md § Type-level grants.
+            grantee: {
+                kind: 'object',
+                required: true,
+                properties: {
+                    kind: { kind: 'string', required: true },
+                    entityId: { kind: 'string' },
+                    groupId: { kind: 'string' },
+                    role: { kind: 'string' },
+                },
+            },
         });
         await this.defineType(`${SYSTEM_TYPES.ATTACHMENT}@1`, 'Attachment', {
             // Deliberately `string`, not `file-ref`: attachmentFileId matching
@@ -1937,13 +2009,12 @@ export class Stack {
     }
     /**
      * Snapshot of a record's prior state, passed with the mutating adapter
-     * call so snapshot and mutation land in one atomic write. `parentId` is
-     * always present (`null` where the record has none) so restore can
-     * distinguish "at the root" from a snapshot that omits the key entirely
-     * ("leave as-is"). Never carries `associations` — associate()/
-     * dissociate() don't bump, so no version ever snapshots the association
-     * set, and there is nothing for a restore to roll back to. See
-     * docs/spec/versioning.md § Version history.
+     * call so snapshot and mutation land in one atomic write. Carries what
+     * only a snapshot preserves: `content` and the `typeId` it is read
+     * under. Containment, listing and associations — the authority ones
+     * among them — are all kept by the journal instead, so no version ever
+     * snapshots them and there is nothing for a restore to roll them back
+     * to. See docs/spec/versioning.md § Version history.
      */
     buildVersionSnapshot(record) {
         return {
@@ -1954,8 +2025,6 @@ export class Stack {
             ...(record.entityId && { entityId: record.entityId }),
             ...(record.updatedBy && { updatedBy: record.updatedBy }),
             ...(record.updatedVia && { updatedVia: record.updatedVia }),
-            ...(record.parentId !== undefined && { parentId: record.parentId }),
-            ...(record.permissions && { permissions: record.permissions }),
         };
     }
 }