@haverstack/core 0.11.0 → 0.11.2

package/dist/stack.js

@@ -17,8 +17,9 @@ import { generateId, isValidIdFormat, idTimestamp } from './id.js';
 import { hashSchema, isCompatible, parseTypeId, baseIdOf, diffSchemas, isWellFormedTypeId, } from './schema.js';
 import { validateContent, validateReservedKeys } from './validate.js';
 import { applyMergePatch } from './merge.js';
-import { checkAccess, groupRoleFromAssociations } from './access.js';
+import { checkAccess, groupRoleFromAssociations, validatePermissions } from './access.js';
 import { firstRecordedAttachment } from './attachment-download.js';
+import { ChangeEmitter, Subscription, buildEmission, matchesFilter } from './changes.js';
 import { SYSTEM_TYPES, GRANT_ACTIONS } from './types.js';
 // -------------------------------------------------------
 // Supporting types
@@ -31,6 +32,119 @@ const EMPTY_FAMILY = Symbol('empty-family');
  * itself derived from — so this can't drift from the type.
  */
 const GRANT_ACTION_SET = new Set(GRANT_ACTIONS);
+/**
+ * The read actions that make a mutate action coherent, scope for scope: a
+ * `-any` verb needs read over the same reach it can mutate, a `-own` verb
+ * needs read over its author's own. A grant carrying neither conveys the
+ * verb to nobody. `create` has no companion — writing a Record you then
+ * cannot read is the drop-box, and it discloses nothing.
+ * See docs/spec/access-control.md § Write implies read.
+ */
+const READ_COMPANIONS = new Map([
+    ['update-own', ['read-own', 'read-any']],
+    ['delete-own', ['read-own', 'read-any']],
+    ['update-any', ['read-any']],
+    ['delete-any', ['read-any']],
+]);
+/**
+ * Whether one grant's action list conveys `action`. The companion has to
+ * sit in the same `_grant` Record, not merely somewhere in the grantee's
+ * set: a grant is revoked whole, so a rule satisfied across two records
+ * would let revoking the read one leave a mutate-without-read grant
+ * standing — the configuration this rule exists to refuse, arrived at
+ * without anyone writing it.
+ */
+function grantConveys(actions, action) {
+    if (!actions.includes(action))
+        return false;
+    const companions = READ_COMPANIONS.get(action);
+    return !companions || companions.some((c) => actions.includes(c));
+}
+/** Direct (non-roster) match between a stored _grant's content and a GrantTarget. */
+function matchesGrantTarget(content, target) {
+    if (target !== null && typeof target === 'object') {
+        // Guarded so an absent groupId can't match the absent granteeGroupId on
+        // every entity-targeted and default grant — `undefined === undefined`
+        // would otherwise sweep them all into a revoke aimed at one group.
+        if (!target.groupId)
+            return false;
+        return content.granteeGroupId === target.groupId;
+    }
+    if (target === null) {
+        return !content.granteeEntityId && !content.granteeGroupId;
+    }
+    return content.granteeEntityId === target;
+}
+/**
+ * Reject a grant target that names nobody. An empty groupId or entityId is
+ * falsy, so a stored record carrying one reads as a *default* grant — every
+ * authenticated entity — instead of the target the caller meant. `null` is
+ * the only way to say "default".
+ */
+function validateGrantTarget(target) {
+    if (target === null)
+        return;
+    if (typeof target === 'string') {
+        if (target.length === 0) {
+            throw new StackQueryError('A grant target entityId cannot be empty. Pass null for a default grant.');
+        }
+        return;
+    }
+    if (typeof target.groupId !== 'string' || target.groupId.length === 0) {
+        throw new StackQueryError('A group grant target requires a non-empty groupId.');
+    }
+    // Not a format check: granteeGroupId is a reference to an existing
+    // Record, like parentId or an association's recordId, and none of those
+    // are parsed either. One that resolves to nothing simply denies.
+}
+/**
+ * Whether a stored _grant covers `grantee`: a direct DID match, roster
+ * membership when `allowGroup`, or a default when `allowDefault`. Presence
+ * decides the tier, never truthiness — an empty grantee field names nobody.
+ * Module-level so the access checks and listGrants() cannot drift apart.
+ * See docs/spec/access-control.md § Type-level grants.
+ */
+async function grantCoversGrantee(c, grantee, opts) {
+    const namesEntity = c.granteeEntityId !== undefined;
+    const namesGroup = c.granteeGroupId !== undefined;
+    if (!namesEntity && !namesGroup)
+        return opts.allowDefault;
+    if (namesEntity && c.granteeEntityId !== grantee)
+        return false;
+    if (namesGroup) {
+        if (!opts.allowGroup)
+            return false;
+        if (!c.granteeGroupId)
+            return false;
+        const role = await resolveGroupRoleMemoized(c.granteeGroupId, grantee, opts.groupRoles, opts.resolveRecord);
+        if (role === null)
+            return false;
+    }
+    return true;
+}
+/**
+ * An entity's role on a `_group` roster, memoized in the caller's
+ * `groupRoles` map. That map is built per operation and threaded alongside
+ * `prefetchedGrants`, so no resolved role outlives the operation that
+ * resolved it — removal from a group must never go stale.
+ * See docs/spec/access-control.md § Type-level grants.
+ */
+async function resolveGroupRoleMemoized(groupId, entityId, groupRoles, resolveRecord) {
+    const key = `${groupId}:${entityId}`;
+    const cached = groupRoles.get(key);
+    if (cached !== undefined)
+        return cached;
+    const group = await resolveRecord(groupId);
+    // Only a real `_group` Record carries a roster. Without the family check
+    // any Record's relationship associations would serve as one, and a group
+    // migrated out of the family would keep resolving after it had stopped
+    // being a group.
+    const role = group && baseIdOf(group.typeId) === SYSTEM_TYPES.GROUP
+        ? groupRoleFromAssociations(group.associations, entityId)
+        : null;
+    groupRoles.set(key, role);
+    return role;
+}
 /**
  * System type families grant() refuses to target: a grant on any of them
  * would let the grantee mint their own grants, touch stack config, or
@@ -394,10 +508,34 @@ export class Stack {
     typeCache = new Map();
     /** Set by close(). See docs/spec/adapters.md § Lifecycle. */
     closed = false;
+    /**
+     * Every change made through this Stack. `ScopedStack` filters this same
+     * stream rather than opening its own, so no scoped view can observe a
+     * change the stack did not emit. See docs/spec/events.md.
+     */
+    changes = new ChangeEmitter();
     constructor(adapter, idTimestampSkewMsValue) {
         this.adapter = adapter;
         this.idTimestampSkewMsValue = idTimestampSkewMsValue;
     }
+    /**
+     * Announce a mutation that has already been persisted. Called after the
+     * adapter write resolves and before the mutating method settles, so
+     * `await stack.update(...)` 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.
+     */
+    emitChange(op, record, opts = {}) {
+        this.changes.emit(buildEmission(op, record, opts));
+    }
+    /**
+     * The requester behind a hard delete, which stamps nothing on a record
+     * that no longer exists. Owner-acting-alone is the only way to reach the
+     * verb, so there is never a principal to name beside the subject.
+     */
+    static purgeActor(opts) {
+        return opts.updatedBy ? { entityId: opts.updatedBy } : undefined;
+    }
     async getTypeCached(id) {
         const cached = this.typeCache.get(id);
         if (cached)
@@ -468,7 +606,7 @@ export class Stack {
         if (opts.onBehalfOf && !entityId) {
             throw new StackPermissionError('An anonymous principal cannot act on behalf of an entity');
         }
-        return new ScopedStack(this, entityId, opts.onBehalfOf ?? entityId, this.idTimestampSkewMsValue, this.adapter);
+        return new ScopedStack(this, entityId, opts.onBehalfOf ?? entityId, this.idTimestampSkewMsValue, this.adapter, this.changes);
     }
     /**
      * Scope to an authenticated session — what StackTokenStore.lookupToken()
@@ -675,7 +813,11 @@ export class Stack {
         if (!type) {
             throw new Error(`Unknown type: "${typeId}". Call defineType() first.`);
         }
-        const errors = [...validateReservedKeys(content), ...validateContent(content, type.schema)];
+        const errors = [
+            ...validateReservedKeys(content),
+            ...validateContent(content, type.schema),
+            ...validatePermissions(opts.permissions),
+        ];
         if (errors.length > 0) {
             throw new StackValidationError(errors);
         }
@@ -701,10 +843,17 @@ export class Stack {
             ...(opts.entityId && { entityId: opts.entityId }),
             ...(opts.appId && { appId: opts.appId }),
             ...(opts.principalId && { principalId: opts.principalId }),
+            // A create's actor is its author, so these are derived rather than
+            // taken: stamping them here keeps "absent means an unscoped write"
+            // true of version 1 as it is of every later version.
+            ...(opts.entityId && { updatedBy: opts.entityId }),
+            ...(opts.principalId && { updatedVia: opts.principalId }),
             ...(opts.permissions?.length && { permissions: opts.permissions }),
             ...(associations?.length && { associations }),
         };
-        return this.adapter.createRecord(record);
+        const created = await this.adapter.createRecord(record);
+        this.emitChange('create', created);
+        return created;
     }
     /**
      * Apply the registered migration chain in memory, for presentAt:
@@ -787,10 +936,14 @@ export class Stack {
         if (id === SYSTEM_TYPES.CONFIG) {
             this.checkConfigEntityIdUnchanged(existing.content.entityId, merged.entityId);
         }
-        return this.adapter.patchContent(id, content, {
+        const updated = await this.adapter.patchContent(id, content, {
             expectedVersion: opts.ifVersion,
             snapshot: this.buildVersionSnapshot(existing),
+            updatedBy: opts.updatedBy,
+            updatedVia: opts.updatedVia,
         });
+        this.emitChange('update', updated);
+        return updated;
     }
     /**
      * Add an association to a record. Snapshots the record's prior state and
@@ -807,10 +960,13 @@ export class Stack {
         this.checkIfVersion(existing, opts.ifVersion);
         if ((existing.associations ?? []).some((a) => associationEqual(a, association)))
             return;
-        await this.adapter.associate(id, association, {
+        const updated = await this.adapter.associate(id, association, {
             expectedVersion: opts.ifVersion,
             snapshot: this.buildVersionSnapshot(existing),
+            updatedBy: opts.updatedBy,
+            updatedVia: opts.updatedVia,
         });
+        this.emitChange('associate', updated);
     }
     /**
      * Remove an association from a record. Snapshots and bumps version, same
@@ -825,10 +981,13 @@ export class Stack {
         this.checkIfVersion(existing, opts.ifVersion);
         if (!(existing.associations ?? []).some((a) => associationEqual(a, association)))
             return;
-        await this.adapter.dissociate(id, association, {
+        const updated = await this.adapter.dissociate(id, association, {
             expectedVersion: opts.ifVersion,
             snapshot: this.buildVersionSnapshot(existing),
+            updatedBy: opts.updatedBy,
+            updatedVia: opts.updatedVia,
         });
+        this.emitChange('dissociate', updated);
     }
     /**
      * Replace all permissions on a record. Snapshots and bumps version, same
@@ -837,6 +996,10 @@ export class Stack {
      */
     async setPermissions(id, permissions, opts = {}) {
         this.assertOpen();
+        const errors = validatePermissions(permissions);
+        if (errors.length > 0) {
+            throw new StackValidationError(errors);
+        }
         const existing = await this.adapter.getRecord(id);
         if (!existing) {
             throw new StackNotFoundError(`Record not found: "${id}"`);
@@ -844,10 +1007,13 @@ export class Stack {
         this.checkIfVersion(existing, opts.ifVersion);
         if (permissionsEqual(existing.permissions ?? [], permissions))
             return;
-        await this.adapter.setPermissions(id, permissions, {
+        const updated = await this.adapter.setPermissions(id, permissions, {
             expectedVersion: opts.ifVersion,
             snapshot: this.buildVersionSnapshot(existing),
+            updatedBy: opts.updatedBy,
+            updatedVia: opts.updatedVia,
         });
+        this.emitChange('permissions', updated);
     }
     /**
      * Soft-delete a record (default) or hard-delete it permanently, removing
@@ -862,7 +1028,17 @@ export class Stack {
             throw new StackConflictError("Cannot delete the _config record: it holds the stack's identity and is required for every permission check.");
         }
         if (opts.hard) {
-            return this.adapter.deleteRecord(id, { hard: true, expectedVersion: opts.ifVersion });
+            // The adapter hands back what it destroyed, captured inside the same
+            // 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 purged = await this.adapter.deleteRecord(id, {
+                hard: true,
+                expectedVersion: opts.ifVersion,
+            });
+            if (purged)
+                this.emitChange('hard-delete', purged, { actor: Stack.purgeActor(opts) });
+            return;
         }
         const existing = await this.adapter.getRecord(id);
         if (!existing) {
@@ -871,10 +1047,14 @@ export class Stack {
         this.checkIfVersion(existing, opts.ifVersion);
         if (existing.deletedAt)
             return;
-        await this.adapter.deleteRecord(id, {
+        const deleted = await this.adapter.deleteRecord(id, {
             expectedVersion: opts.ifVersion,
             snapshot: this.buildVersionSnapshot(existing),
+            updatedBy: opts.updatedBy,
+            updatedVia: opts.updatedVia,
         });
+        if (deleted)
+            this.emitChange('delete', deleted);
     }
     /**
      * Reverse a soft delete. Idempotent — undeleting a record that isn't
@@ -891,10 +1071,14 @@ export class Stack {
         this.checkIfVersion(existing, opts.ifVersion);
         if (!existing.deletedAt)
             return existing;
-        return this.adapter.undeleteRecord(id, {
+        const undeleted = await this.adapter.undeleteRecord(id, {
             expectedVersion: opts.ifVersion,
             snapshot: this.buildVersionSnapshot(existing),
+            updatedBy: opts.updatedBy,
+            updatedVia: opts.updatedVia,
         });
+        this.emitChange('undelete', undeleted);
+        return undeleted;
     }
     /**
      * Query records. filter.baseId matches every version of a type family,
@@ -988,10 +1172,14 @@ export class Stack {
         for (const field of bindingFieldsOf(baseIdOf(target.typeId))) {
             this.checkBindingImmutable(baseIdOf(target.typeId), field, existing.content[field], target.content[field]);
         }
-        return this.adapter.restoreVersion(id, version, {
+        const restored = await this.adapter.restoreVersion(id, version, {
             expectedVersion: opts.ifVersion,
             snapshot: this.buildVersionSnapshot(existing),
+            updatedBy: opts.updatedBy,
+            updatedVia: opts.updatedVia,
         });
+        this.emitChange('restore', restored);
+        return restored;
     }
     /**
      * Commit a per-record migration: replace `content` and `typeId` together
@@ -1020,7 +1208,7 @@ export class Stack {
             throw new StackNotFoundError(`Record not found: "${id}"`);
         }
         this.checkIfVersion(existing, opts.ifVersion);
-        return this.commitMigrationChecked(existing, toTypeId, content, opts.ifVersion);
+        return this.commitMigrationChecked(existing, toTypeId, content, opts);
     }
     /**
      * The checked migration write, shared by commitMigration() and
@@ -1037,7 +1225,7 @@ export class Stack {
      * can cross type families; family-crossing is exactly what the checks
      * below care about.
      */
-    async commitMigrationChecked(existing, toTypeId, content, ifVersion) {
+    async commitMigrationChecked(existing, toTypeId, content, opts = {}) {
         const id = existing.id;
         const type = await this.getTypeCached(toTypeId);
         if (!type) {
@@ -1074,10 +1262,14 @@ export class Stack {
         if (id === SYSTEM_TYPES.CONFIG) {
             this.checkConfigEntityIdUnchanged(existing.content.entityId, content.entityId);
         }
-        return this.adapter.commitMigration(id, toTypeId, content, {
-            expectedVersion: ifVersion,
+        const migrated = await this.adapter.commitMigration(id, toTypeId, content, {
+            expectedVersion: opts.ifVersion,
             snapshot: this.buildVersionSnapshot(existing),
+            updatedBy: opts.updatedBy,
+            updatedVia: opts.updatedVia,
         });
+        this.emitChange('migrate', migrated);
+        return migrated;
     }
     /** Uniqueness for every unique binding field a newly created card claims. */
     async checkBindingsOnCreate(typeId, content) {
@@ -1314,7 +1506,10 @@ export class Stack {
         this.assertOpen();
         assertAttachmentSize(data.byteLength, this.features.maxAttachmentBytes);
         if (this.adapter.putAttachmentWithMetadata) {
+            // 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);
             return record;
         }
         const fileId = await this.adapter.putAttachment(data);
@@ -1334,13 +1529,24 @@ export class Stack {
      * Throws StackConflictError if any record in the stack still references the file.
      * Throws StackNotFoundError if neither metadata records nor bytes exist.
      */
-    async deleteAttachment(fileId) {
+    async deleteAttachment(fileId, opts = {}) {
         this.assertOpen();
         const metadataTypeId = `${SYSTEM_TYPES.ATTACHMENT}@1`;
-        const deletedRecordIds = this.adapter.deleteUnreferencedAttachmentRecords
-            ? await this.adapter.deleteUnreferencedAttachmentRecords(fileId, metadataTypeId)
-            : await this.deleteUnreferencedAttachmentRecordsFallback(fileId, metadataTypeId);
-        if (!deletedRecordIds.length) {
+        let deletedRecords;
+        if (this.adapter.deleteUnreferencedAttachmentRecords) {
+            // 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, metadataTypeId);
+            const at = new Date();
+            for (const record of deletedRecords) {
+                this.emitChange('hard-delete', record, { actor: Stack.purgeActor(opts), at });
+            }
+        }
+        else {
+            deletedRecords = await this.deleteUnreferencedAttachmentRecordsFallback(fileId, metadataTypeId, opts);
+        }
+        if (!deletedRecords.length) {
             try {
                 await this.adapter.getAttachment(fileId);
             }
@@ -1355,7 +1561,7 @@ export class Stack {
      * deleteUnreferencedAttachmentRecords(): a concurrent associate() can
      * race between the reference check below and the deletes it guards.
      */
-    async deleteUnreferencedAttachmentRecordsFallback(fileId, metadataTypeId) {
+    async deleteUnreferencedAttachmentRecordsFallback(fileId, metadataTypeId, opts = {}) {
         // A soft-deleted record still counts as a reference — it must find its
         // attachments intact on undelete. See docs/spec/attachments.md
         // § Deleting attachments.
@@ -1379,9 +1585,9 @@ export class Stack {
             ? metaResults
             : metaResults.filter((r) => r.content.fileId === fileId);
         for (const record of metaRecords) {
-            await this.delete(record.id, { hard: true });
+            await this.delete(record.id, { hard: true, ...opts });
         }
-        return metaRecords.map((r) => r.id);
+        return metaRecords;
     }
     /**
      * Sweep for attachment bytes unreachable from any record — live or
@@ -1440,7 +1646,7 @@ export class Stack {
                 continue;
             }
             try {
-                await this.deleteAttachment(fileId);
+                await this.deleteAttachment(fileId, { updatedBy: opts.updatedBy });
             }
             catch (err) {
                 // Raced with a new reference, or another sweep/call already removed
@@ -1463,6 +1669,20 @@ export class Stack {
      * ones that buffer, and for checkpointing a stack that stays open —
      * close() covers the teardown case on its own.
      */
+    /**
+     * Observe every change made through this Stack. Unscoped, so no
+     * permission filter applies — a caller holding a `Stack` already reaches
+     * every record by other means; `ScopedStack.subscribe()` is the filtered
+     * view. See docs/spec/events.md.
+     *
+     * Async so that a remote stack can resolve once its feed is live, which
+     * makes subscribe-then-query the gap-free startup order everywhere. A
+     * local stack is live immediately.
+     */
+    async subscribe(handler, opts = {}) {
+        this.assertOpen();
+        return this.changes.subscribe(handler, opts);
+    }
     async flush() {
         this.assertOpen();
         await this.adapter.flush?.();
@@ -1480,6 +1700,7 @@ export class Stack {
         // half-open and invite a second close() onto an already-closed adapter.
         // Flushes through the adapter directly, past the now-tripped guard.
         this.closed = true;
+        this.changes.closeAll();
         try {
             await this.adapter.flush?.();
         }
@@ -1500,8 +1721,9 @@ export class Stack {
     // -------------------------------------------------------
     /**
      * Create _grant records authorizing entities to act on records of
-     * specific types; null entityId writes a default grant (any
-     * authenticated entity).
+     * specific types; null target writes a default grant (any authenticated
+     * entity); `{ groupId }` targets a `_group` Record's roster instead of a
+     * single 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
@@ -1511,51 +1733,71 @@ 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,
+     * The grantee lives in content.granteeEntityId / content.granteeGroupId,
      * not record.entityId. See docs/spec/access-control.md § Type-level
      * grants.
      */
-    async grant(entityId, grants) {
+    async grant(target, grants) {
         this.assertOpen();
+        validateGrantTarget(target);
         this.checkGrantsValid(grants);
         const records = [];
         for (const g of grants) {
             records.push(await this.create(`${SYSTEM_TYPES.GRANT}@1`, {
                 typeId: g.typeId,
                 actions: g.actions,
-                ...(entityId && { granteeEntityId: entityId }),
+                ...(typeof target === 'string' && { granteeEntityId: target }),
+                ...(target !== null && typeof target === 'object' && { granteeGroupId: target.groupId }),
             }));
         }
         return records;
     }
     /**
-     * List _grant records. Omit `entityId` for all grants; pass null for
-     * only default grants; pass a specific entityId for the grants that
-     * currently apply to that entity (ones naming them, plus every default
-     * grant) — the same resolution hasGrant() uses.
+     * 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.
      */
-    async listGrants(entityId) {
+    async listGrants(target) {
         this.assertOpen();
+        if (target !== undefined)
+            validateGrantTarget(target);
         const all = await queryAllPages((q) => this.query(q), {
             filter: { typeId: `${SYSTEM_TYPES.GRANT}@1` },
         });
-        if (entityId === undefined)
+        if (target === undefined)
             return all;
-        return all.filter((r) => {
-            const granteeEntityId = r.content.granteeEntityId;
-            return entityId === null
-                ? !granteeEntityId
-                : !granteeEntityId || granteeEntityId === entityId;
-        });
+        if (target === null || typeof target === 'object') {
+            return all.filter((r) => matchesGrantTarget(r.content, target));
+        }
+        // target is an EntityId: resolve 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, {
+                allowDefault: true,
+                allowGroup: true,
+                groupRoles,
+                resolveRecord: (id) => this.get(id),
+            });
+            if (covers)
+                result.push(r);
+        }
+        return result;
     }
     /**
-     * The inverse of grant(): soft-deletes _grant records matching `entityId`
+     * 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.
      */
-    async revoke(entityId, grants) {
+    async revoke(target, grants) {
         this.assertOpen();
+        validateGrantTarget(target);
         const all = await queryAllPages((q) => this.query(q), {
             filter: { typeId: `${SYSTEM_TYPES.GRANT}@1` },
         });
@@ -1566,7 +1808,7 @@ export class Stack {
                 const c = r.content;
                 if (baseIdOf(c.typeId) !== familyId)
                     return false;
-                if ((c.granteeEntityId ?? null) !== entityId)
+                if (!matchesGrantTarget(c, target))
                     return false;
                 return c.actions.length === actionSet.size && c.actions.every((a) => actionSet.has(a));
             });
@@ -1610,6 +1852,17 @@ export class Stack {
                     message: `Cannot grant on "${baseIdOf(g.typeId)}": grants on ${refused} are refused to prevent privilege escalation`,
                 });
             }
+            g.actions.forEach((action, j) => {
+                if (grantConveys(g.actions, action))
+                    return;
+                const companions = READ_COMPANIONS.get(action);
+                if (!companions)
+                    return;
+                errors.push({
+                    path: `grants[${i}].actions[${j}]`,
+                    message: `"${action}" requires ${companions.map((c) => `"${c}"`).join(' or ')} in the same grant: a mutate verb reaches the record and its history, so it conveys nothing without read`,
+                });
+            });
         });
         if (errors.length > 0) {
             throw new StackValidationError(errors);
@@ -1641,6 +1894,7 @@ export class Stack {
             typeId: { kind: 'string', required: true },
             actions: { kind: 'array', items: { kind: 'string' }, required: true },
             granteeEntityId: { kind: 'string' },
+            granteeGroupId: { kind: 'string' },
         });
         await this.defineType(`${SYSTEM_TYPES.ATTACHMENT}@1`, 'Attachment', {
             fileId: { kind: 'string', required: true },
@@ -1674,6 +1928,8 @@ export class Stack {
             content: record.content,
             updatedAt: record.updatedAt,
             ...(record.entityId && { entityId: record.entityId }),
+            ...(record.updatedBy && { updatedBy: record.updatedBy }),
+            ...(record.updatedVia && { updatedVia: record.updatedVia }),
             associations: record.associations ?? [],
             ...(record.permissions && { permissions: record.permissions }),
         };
@@ -1761,23 +2017,128 @@ function stripVersionPermissions(version) {
  * grants). Under delegation both halves apply, and a mistake on the
  * authority side is an escalation rather than a preference.
  */
+/**
+ * The authority lookups canRead needs, held for the life of one
+ * subscription. A subscription is long-lived where a query is not, so the
+ * cache is only safe because every write that can change canRead's answer
+ * arrives as an event that drops it — see ScopedSubscription.
+ */
+class FeedAuthorityCache {
+    grantRecords = null;
+    /**
+     * Bumped by every invalidation, so a load that was already in flight can
+     * tell that its result is stale before seating it.
+     */
+    generation = 0;
+    /** Roster roles, memoized per group, as ScopedStack.query() does per query. */
+    roles = new Map();
+    /** Every `_grant` record, refilled through `load` after an invalidation. */
+    async grants(load) {
+        if (this.grantRecords !== null)
+            return this.grantRecords;
+        const generation = this.generation;
+        const loaded = await load();
+        // An invalidation during the load already dropped the set these
+        // replace, so seating them would outlive the write that expired them
+        // and no later event would drop them again. The event being decided
+        // precedes that write, so it is still decided on what was loaded.
+        if (this.generation === generation)
+            this.grantRecords = loaded;
+        return loaded;
+    }
+    invalidateFor(typeFamily) {
+        if (typeFamily === SYSTEM_TYPES.GRANT) {
+            this.grantRecords = null;
+            this.generation++;
+        }
+        if (typeFamily === SYSTEM_TYPES.GROUP)
+            this.roles = new Map();
+    }
+}
+/**
+ * A ScopedStack's delivery: canRead per event, with the grant and roster
+ * lookups it needs cached for the life of the subscription and dropped the
+ * moment anything that feeds them changes.
+ *
+ * Two properties do the work, and neither is optional:
+ *
+ * **Deliveries are serialized.** The permission decision is asynchronous,
+ * so without a queue two changes to one record could resolve out of order
+ * and be delivered newest-first — breaking the one ordering guarantee the
+ * feed makes. Every emission is appended to a chain instead.
+ *
+ * **The filter fails closed.** A permission check that throws drops the
+ * event and reports the error; it never delivers on the assumption that a
+ * failed check would have passed.
+ *
+ * See docs/spec/events.md § Permission scoping.
+ */
+class ScopedSubscription extends Subscription {
+    canRead;
+    cache = new FeedAuthorityCache();
+    /** Tail of the delivery chain — see the class comment. */
+    queue = Promise.resolve();
+    constructor(canRead, handler, opts) {
+        super(handler, opts);
+        this.canRead = canRead;
+    }
+    accept(emission) {
+        // Invalidation reads every emission, including the ones this
+        // subscriber may not see: a revocation the subscriber cannot read is
+        // exactly the one that must still expire its cache.
+        this.invalidateFor(emission);
+        if (!matchesFilter(emission, this.opts.filter))
+            return;
+        this.queue = this.queue.then(() => this.filterAndDeliver(emission));
+    }
+    /**
+     * A cached grant set outlives the write that revokes it unless something
+     * drops it. Both writes that can change canRead's answer — a `_grant`
+     * record, or a `_group` roster — arrive here as ordinary events, which
+     * is what makes the cache safe to hold at all. A future authority change
+     * that did not emit would silently strand it.
+     */
+    invalidateFor(emission) {
+        this.cache.invalidateFor(baseIdOf(emission.change.typeId));
+    }
+    async filterAndDeliver(emission) {
+        if (this.isClosed)
+            return;
+        try {
+            if (!(await this.canRead(emission.record, this.cache)))
+                return;
+        }
+        catch (err) {
+            // Fail closed: an undecided permission question is not a yes.
+            this.reportError(err);
+            return;
+        }
+        this.deliver(emission);
+    }
+}
 export class ScopedStack {
     stack;
     principalEntityId;
     subjectEntityId;
     idTimestampSkewMs;
     adapter;
+    changes;
     constructor(stack, principalEntityId, subjectEntityId, idTimestampSkewMs, 
     // Bytes-storage primitive for putAttachment(). Held directly because
     // ScopedStack always composes bytes + its own create() — the record
     // must carry the subject's entityId and the principal behind it,
     // neither of which the adapter-level atomic capability takes.
-    adapter) {
+    adapter, 
+    // The stack's own stream, filtered by subscribe(). Held here rather
+    // than reached through a method on Stack so the unfiltered stream
+    // stays inside this module.
+    changes) {
         this.stack = stack;
         this.principalEntityId = principalEntityId;
         this.subjectEntityId = subjectEntityId;
         this.idTimestampSkewMs = idTimestampSkewMs;
         this.adapter = adapter;
+        this.changes = changes;
     }
     get features() {
         return this.stack.features;
@@ -1787,6 +2148,21 @@ export class ScopedStack {
     get delegated() {
         return this.subjectEntityId !== this.principalEntityId;
     }
+    /**
+     * Who this request is, for stamping onto whatever it mutates. Attribution
+     * follows record-level authorship: the subject is the actor, and the
+     * principal is named beside it only when the two differ.
+     * See docs/spec/data-model.md § Authorship and attribution.
+     */
+    get actor() {
+        // Both keys are always present, so spreading this last overrides
+        // anything a caller passed: a scoped requester names itself by making
+        // the request, never by describing itself in the options.
+        return {
+            updatedBy: this.subjectEntityId ?? undefined,
+            updatedVia: this.delegated ? (this.principalEntityId ?? undefined) : undefined,
+        };
+    }
     /**
      * Whether unconditional owner authority applies — the owner acting as
      * itself. The verbs that rest on it are irreversible or disclose the
@@ -1817,9 +2193,13 @@ export class ScopedStack {
      * See docs/spec/access-control.md § Type-level grants.
      */
     async hasGrant(typeId, actions, opts) {
-        const { grantee, record, prefetchedGrants, matchOwn = true, allowDefault = true } = opts;
+        const { grantee, record, prefetchedGrants, matchOwn = true, allowDefault = true, allowGroup = true, } = opts;
         if (!grantee)
             return false;
+        // Absent when the caller has no operation-scoped map to share — one
+        // call's worth of memoization, which is still every grant record in
+        // this loop naming the same group.
+        const groupRoles = opts.groupRoles ?? new Map();
         const familyId = baseIdOf(typeId);
         // grant() refuses to write these, but a _grant record is an ordinary
         // Record: an unscoped Stack, an import, or a server mapping a request
@@ -1839,22 +2219,29 @@ export class ScopedStack {
                 filter: { typeId: `${SYSTEM_TYPES.GRANT}@1` },
             });
         }
-        return grantRecords.some((r) => {
+        for (const r of grantRecords) {
             const c = r.content;
             if (baseIdOf(c.typeId) !== familyId)
-                return false;
-            if (!c.granteeEntityId && !allowDefault)
-                return false;
-            if (c.granteeEntityId && c.granteeEntityId !== grantee)
-                return false;
-            return actions.some((action) => {
-                if (!c.actions.includes(action))
+                continue;
+            const covers = await grantCoversGrantee(c, grantee, {
+                allowDefault,
+                allowGroup,
+                groupRoles,
+                resolveRecord: this.resolveRecord,
+            });
+            if (!covers)
+                continue;
+            const matches = actions.some((action) => {
+                if (!grantConveys(c.actions, action))
                     return false;
                 if (matchOwn && action.endsWith('-own'))
                     return record?.entityId === grantee;
                 return true;
             });
-        });
+            if (matches)
+                return true;
+        }
+        return false;
     }
     /**
      * The principal half of a delegated request's authority: does the app
@@ -1868,6 +2255,11 @@ export class ScopedStack {
      * people who turn up, not software the owner installed — an app reaches
      * only the types named to it, which is the whole of what containment
      * promises.
+     *
+     * Group-targeted grants don't count here either, one step removed: a
+     * roster is editable by any of the group's admins, so authority reaching
+     * a principal through one would let someone other than the owner name an
+     * app to a type. See docs/spec/access-control.md § Type-level grants.
      */
     principalAllows(typeId, actions, prefetchedGrants) {
         if (!this.delegated)
@@ -1879,6 +2271,7 @@ export class ScopedStack {
             prefetchedGrants,
             matchOwn: false,
             allowDefault: false,
+            allowGroup: false,
         });
     }
     /**
@@ -1895,13 +2288,15 @@ export class ScopedStack {
             grantee: this.subjectEntityId,
             record: opts.record,
             prefetchedGrants: opts.prefetchedGrants,
+            groupRoles: opts.groupRoles,
         });
     }
-    async canRead(record, prefetchedGrants) {
+    async canRead(record, prefetchedGrants, groupRoles) {
         const reachable = (await this.checkRead(record)) ||
             (await this.subjectAllows(record.typeId, ['read-own', 'read-any'], {
                 record,
                 prefetchedGrants,
+                groupRoles,
             }));
         if (!reachable)
             return false;
@@ -2004,7 +2399,8 @@ export class ScopedStack {
                 filter: { typeId: `${SYSTEM_TYPES.GRANT}@1` },
             })
             : undefined;
-        const match = await findFirstMatch((q) => this.stack.query(q), { filter: { attachmentFileId: fileId } }, (record) => this.canRead(record, prefetchedGrants));
+        const groupRoles = new Map();
+        const match = await findFirstMatch((q) => this.stack.query(q), { filter: { attachmentFileId: fileId } }, (record) => this.canRead(record, prefetchedGrants, groupRoles));
         return match !== undefined;
     }
     /**
@@ -2182,12 +2578,16 @@ export class ScopedStack {
                 filter: { typeId: `${SYSTEM_TYPES.GRANT}@1` },
             })
             : undefined;
+        // Scoped to this query, like prefetchedGrants beside it: every
+        // candidate Record shares one roster resolution per group, and nothing
+        // is carried into the next operation.
+        const groupRoles = new Map();
         let page = { records: [], cursor: query.cursor ?? null, total: null };
         do {
             page = await this.stack.query({ ...query, cursor: page.cursor ?? undefined });
             totalFetched += page.records.length;
             for (const record of page.records) {
-                if (await this.canRead(record, prefetchedGrants))
+                if (await this.canRead(record, prefetchedGrants, groupRoles))
                     records.push(record);
             }
         } while (records.length < limit && page.cursor && totalFetched < maxFetched);
@@ -2206,7 +2606,7 @@ export class ScopedStack {
             this.requireOwnerForOwnerDid(record.typeId, content.did);
         }
         await this.requireFileRefAccess(record.typeId, content);
-        return this.stack.update(id, content, opts);
+        return this.stack.update(id, content, { ...opts, ...this.actor });
     }
     /**
      * Naming the software behind a key is the trust decision the `_app`
@@ -2298,11 +2698,11 @@ export class ScopedStack {
     async associate(id, association, opts = {}) {
         const record = await this.requireUpdatable(id);
         await this.requireAssociationAccess(record.typeId, association);
-        return this.stack.associate(id, association, opts);
+        return this.stack.associate(id, association, { ...opts, ...this.actor });
     }
     async dissociate(id, association, opts = {}) {
         await this.requireUpdatable(id);
-        return this.stack.dissociate(id, association, opts);
+        return this.stack.dissociate(id, association, { ...opts, ...this.actor });
     }
     async setPermissions(id, permissions, opts = {}) {
         const record = await this.stack.get(id);
@@ -2328,7 +2728,7 @@ export class ScopedStack {
                 throw new StackPermissionError();
             }
         }
-        return this.stack.setPermissions(id, permissions, opts);
+        return this.stack.setPermissions(id, permissions, { ...opts, ...this.actor });
     }
     /**
      * Hard delete is owner-only: it is irreversible and destroys version
@@ -2341,7 +2741,7 @@ export class ScopedStack {
         if (opts.hard && !this.ownerActingAlone) {
             throw new StackPermissionError('Hard delete is owner-only');
         }
-        return this.stack.delete(id, opts);
+        return this.stack.delete(id, { ...opts, ...this.actor });
     }
     /**
      * Reverse a soft delete. Gated the same as delete() — undelete is the
@@ -2350,7 +2750,7 @@ export class ScopedStack {
      */
     async undelete(id, opts = {}) {
         await this.requireDeletable(id);
-        return this.stack.undelete(id, opts);
+        return this.stack.undelete(id, { ...opts, ...this.actor });
     }
     /**
      * History is the mutation/recovery surface, not a read surface — gated
@@ -2398,7 +2798,7 @@ export class ScopedStack {
                 }
             }
         }
-        return this.stack.restoreVersion(id, version, opts);
+        return this.stack.restoreVersion(id, version, { ...opts, ...this.actor });
     }
     /**
      * Commit a per-record migration — **the owner acting alone, only**.
@@ -2431,7 +2831,7 @@ export class ScopedStack {
         if (!this.ownerActingAlone) {
             throw new StackPermissionError('Only the stack owner may commit a migration');
         }
-        return this.stack.commitMigration(id, toTypeId, content, opts);
+        return this.stack.commitMigration(id, toTypeId, content, { ...opts, ...this.actor });
     }
     /**
      * Store bytes and create an _attachment@1 metadata record (create grant
@@ -2482,7 +2882,7 @@ export class ScopedStack {
         if (!this.ownerActingAlone) {
             throw new StackPermissionError('Only the stack owner can delete attachments');
         }
-        return this.stack.deleteAttachment(fileId);
+        return this.stack.deleteAttachment(fileId, this.actor);
     }
     /**
      * Sweep for unreferenced attachment bytes and delete them. Only the stack
@@ -2492,7 +2892,35 @@ export class ScopedStack {
         if (!this.ownerActingAlone) {
             throw new StackPermissionError('Only the stack owner can collect attachment garbage');
         }
-        return this.stack.collectAttachmentGarbage(opts);
+        return this.stack.collectAttachmentGarbage({ ...opts, ...this.actor });
+    }
+    /**
+     * Observe the changes this request may read. The predicate is canRead
+     * applied per event — the same one get() and query() answer with, so a
+     * feed can't disagree with them about what this session sees.
+     *
+     * A record the subscriber cannot read produces no event at all, rather
+     * than an empty or redacted one: the existence of a change is itself a
+     * disclosure, the same reasoning that keeps query()'s `total` null.
+     * See docs/spec/events.md § Permission scoping.
+     */
+    async subscribe(handler, opts = {}) {
+        this.stack.assertOpen();
+        return this.changes.add(new ScopedSubscription((record, cache) => this.canReadCached(record, cache), handler, opts));
+    }
+    /**
+     * canRead for one event, through the subscription's own cache. Grants
+     * are prefetched once and refilled after an invalidation rather than
+     * re-queried per event, which would be a `_grant` scan for every change
+     * the stack makes.
+     */
+    async canReadCached(record, cache) {
+        const grants = this.principalEntityId
+            ? await cache.grants(() => queryAllPages((q) => this.stack.query(q), {
+                filter: { typeId: `${SYSTEM_TYPES.GRANT}@1` },
+            }))
+            : undefined;
+        return this.canRead(record, grants, cache.roles);
     }
 }
 //# sourceMappingURL=stack.js.map