@haverstack/core 0.39.0 → 0.41.0

package/dist/scoped-stack.js

@@ -22,14 +22,19 @@ import { validatePatchValues } from './validate.js';
 import { checkAccess, groupRoleFromAssociations, isOwnerActingAlone } from './access.js';
 import { ChangeEmitter, Subscription, matchesFilter, passesUnlistedBoundary, assertSinceUsable, } from './changes.js';
 import { SYSTEM_TYPES } from './types.js';
-import { StackConflictError, StackError, StackNotFoundError, StackPermissionError, RelayScopeError, StackValidationError, } from './errors.js';
-import { assertAuthorityAssociations, assertDataAssociations, assertSortCapability, assertValidAssociationFilters, assertValidSort, filtersContent, } from './query-validation.js';
+import { StackError, StackConflictError, StackNotFoundError, StackPermissionError, RelayScopeError, StackValidationError, } from './errors.js';
+import { assertAssociationEdits, assertAuthorityAssociations, assertDataAssociations, assertSortCapability, assertValidAssociationFilters, assertValidBaseIdFilter, assertValidSort, filtersContent, } from './query-validation.js';
 import { grantConveys, grantCoversGrantee, grantReach, loadGrantRecords, UNGRANTABLE_SYSTEM_TYPES, } from './grants.js';
 import { bindingFieldsOf } from './identity-bindings.js';
+import { claimedFamilies, familyStanding, linkedIds, INSTALL_APP_LABEL } from './install.js';
 import { assertAttachmentSize } from './limits.js';
 import { validateIdTimestampSkew, validateRecordId } from './record-id.js';
 import { DEFAULT_QUERY_LIMIT, MAX_QUERY_LIMIT, findFirstMatch, lookupEntityByDid, queryAllPages, } from './stack-reads.js';
 import { associationDelta, associationEqual, isGroupRecord, presentDeleted, withoutAuthorityChanges, assertNonEmptyChangeSet, } from './record-changes.js';
+// Every import from stack.js is type-only: a ScopedStack never constructs
+// a Stack, so nothing here closes a runtime cycle with stack.ts, which does
+// construct a ScopedStack.
+import { isTypeHandle, typedCreate, typedGet, typedMutate, typedQuery, typedSubscribe, } from './type-handle.js';
 /**
  * The authority lookups canRead needs, held for the life of one
  * subscription. A subscription is long-lived where a query is not, so the
@@ -196,7 +201,7 @@ export class ScopedStack {
     get capabilities() {
         return this.stack.capabilities;
     }
-    resolveRecord = (id) => this.stack.get(id);
+    resolveRecord = (id) => this.stack.get(id, { includeDeleted: true });
     /** Every `_grant` Record — see loadGrantRecords(). */
     loadGrants = () => loadGrantRecords((q) => this.stack.query(q));
     /** Whether a delegated app is acting for someone other than itself. */
@@ -286,9 +291,8 @@ export class ScopedStack {
             grantRecords = prefetchedGrants;
         }
         else {
-            // No content-field prefilter: a stored grant's typeId may be a bare
-            // baseId or versioned, so exact matching would wrongly exclude family
-            // versions. Cursor-walked to see grants past page one.
+            // Cursor-walked to see grants past page one. A stored baseId is
+            // judged by grantReach(), which refuses a versioned one.
             grantRecords = await this.loadGrants();
         }
         for (const r of grantRecords) {
@@ -424,13 +428,11 @@ export class ScopedStack {
      * the one way through it a `_grant` Record stays open to.
      */
     async requireUpdatable(id, opts = {}) {
-        const mutating = opts.mutating ?? true;
         // The `_grant` write fence applies to mutating callers only: reading a
         // grant Record's history is not the escalation that fence exists to stop.
-        const record = await this.requireVerb(id, ['update-own', 'update-any'], {
-            fenceGrantRecord: mutating,
+        return this.requireVerb(id, ['update-own', 'update-any'], {
+            fenceGrantRecord: opts.mutating ?? true,
         });
-        return this.refuseIfDeleted(record, mutating);
     }
     /**
      * The write gate both requireUpdatable() and requireDeletable() are: the
@@ -440,33 +442,26 @@ export class ScopedStack {
      * See docs/spec/access-control.md § Delegation: principal and subject.
      */
     async requireVerb(id, actions, opts) {
-        const record = await this.stack.get(id);
+        const record = await this.stack.get(id, { includeDeleted: true });
         if (!record)
             throw new StackNotFoundError(`Record not found: "${id}"`);
         if (opts.fenceGrantRecord)
             await this.requireOwnerForGrantRecord(record);
         if (isGroupRecord(record)) {
-            if (!this.isGroupManager(record))
-                throw await this.denialFor(record);
+            if (!this.isGroupManager(record)) {
+                throw await this.denialFor(record, `Cannot change group "${id}": only its admins can manage it`);
+            }
             return record;
         }
-        const allowed = ((await this.checkWrite(record)) ||
-            (await this.subjectAllows(record.typeId, actions, { record }))) &&
-            (await this.principalAllows(record.typeId, actions));
-        if (!allowed)
-            throw await this.denialFor(record);
-        return record;
-    }
-    /**
-     * Refuse a mutation aimed at a soft-deleted Record. Asked only of a
-     * mutating caller, so the history readers borrowing this gate still work,
-     * and only after the authority decision, so "exists but deleted" is never
-     * a probe a stranger can run. See docs/spec/versioning.md § Mutations are
-     * refused, not applied to a tombstone.
-     */
-    refuseIfDeleted(record, mutating) {
-        if (mutating && record.deletedAt) {
-            throw new StackConflictError(`Record "${record.id}" is soft-deleted; undelete it before mutating it.`);
+        const subjectReaches = (await this.checkWrite(record)) ||
+            (await this.subjectAllows(record.typeId, actions, { record }));
+        const principalHolds = await this.principalAllows(record.typeId, actions);
+        if (!subjectReaches || !principalHolds) {
+            const verb = actions[0].split('-')[0];
+            const what = `Cannot ${verb} "${id}" (${record.typeId})`;
+            throw await this.denialFor(record, subjectReaches
+                ? `${what}: the app acting for this entity holds no ${verb} grant`
+                : `${what}: requires ${actions.join(' or ')}`);
         }
         return record;
     }
@@ -492,7 +487,7 @@ export class ScopedStack {
     async canReadReferent(recordId) {
         if (this.ownerActingAlone)
             return true;
-        const record = await this.stack.get(recordId);
+        const record = await this.stack.get(recordId, { includeDeleted: true });
         if (!record)
             return false;
         return this.canRead(record);
@@ -582,8 +577,9 @@ export class ScopedStack {
             const value = content[field];
             if (typeof value !== 'string')
                 continue;
-            if (!(await this.canAccessFile(value)))
-                throw new StackPermissionError();
+            if (!(await this.canAccessFile(value))) {
+                throw new StackPermissionError(`Cannot reference file "${value}" in field "${field}": it does not exist or you cannot read it`);
+            }
         }
     }
     /**
@@ -600,8 +596,9 @@ export class ScopedStack {
      */
     async requireAssociationAccess(typeId, association) {
         if (association.kind === 'attachment') {
-            if (!(await this.canAccessFile(association.fileId)))
-                throw new StackPermissionError();
+            if (!(await this.canAccessFile(association.fileId))) {
+                throw new StackPermissionError(`Cannot reference file "${association.fileId}": it does not exist or you cannot read it`);
+            }
         }
         else if (association.kind === 'relationship' && baseIdOf(typeId) !== SYSTEM_TYPES.GROUP) {
             const { target } = association;
@@ -611,22 +608,16 @@ export class ScopedStack {
             // leave one spelling of a local Record ungated.
             if (target.kind !== 'record' || target.stackUrl)
                 return;
-            if (!(await this.canReadReferent(target.recordId)))
-                throw new StackPermissionError();
+            if (!(await this.canReadReferent(target.recordId))) {
+                throw new StackPermissionError(`Cannot reference record "${target.recordId}": it does not exist or you cannot read it`);
+            }
         }
     }
-    /**
-     * Create a record on behalf of the subject: create grant required,
-     * anonymous denied, `createdBy` set to the requester, client IDs skew-checked,
-     * reference-creating options gated, and non-owner `_attachment@1`
-     * creation refused save one carve-out. A scoped create always stamps
-     * authorship — an absent `createdBy` means an unscoped `Stack` wrote it.
-     * `createdAt`/`updatedAt` are refused to everyone but the owner acting
-     * alone, rather than dropped, so an app never believes it published
-     * something it didn't. See docs/spec/access-control.md and
-     * docs/spec/data-model.md § Record IDs.
-     */
-    async create(typeId, content, opts = {}) {
+    async create(typeIdOrHandle, content, opts = {}) {
+        if (isTypeHandle(typeIdOrHandle)) {
+            return typedCreate(this, typeIdOrHandle, content, opts);
+        }
+        const typeId = typeIdOrHandle;
         const principal = this.#principalId;
         if (!principal)
             throw new StackPermissionError('Anonymous requesters cannot create records');
@@ -648,7 +639,7 @@ export class ScopedStack {
         if (!this.ownerActingAlone && baseIdOf(typeId) === SYSTEM_TYPES.ATTACHMENT) {
             const fileId = content.fileId;
             if (typeof fileId !== 'string' || !(await this.hasReadableReference(fileId))) {
-                throw new StackPermissionError();
+                throw new StackPermissionError(`Cannot reference file "${String(fileId)}": it does not exist or you cannot read it`);
             }
         }
         if (opts.permissions?.length && !this.mayGrantAccess()) {
@@ -672,7 +663,7 @@ export class ScopedStack {
             }
         }
         if (opts.parentId !== undefined && !(await this.canReadReferent(opts.parentId))) {
-            throw new StackPermissionError();
+            throw new StackPermissionError(`Cannot reference record "${opts.parentId}" as parent: it does not exist or you cannot read it`);
         }
         for (const assoc of opts.associations ?? []) {
             await this.requireAssociationAccess(typeId, assoc);
@@ -708,13 +699,11 @@ export class ScopedStack {
             return false;
         return entityId === this.stack.ownerEntityId || entityId === record.createdBy?.subjectId;
     }
-    /**
-     * A record this request may read, or null. Never throws
-     * StackPermissionError: an unreadable record answers exactly as a missing
-     * one does, so a caller learns only what it may read.
-     * See docs/spec/disclosure.md § Which refusal a Record answers with.
-     */
-    async get(id, opts = {}) {
+    async get(idOrHandle, idOrOpts = {}) {
+        if (isTypeHandle(idOrHandle))
+            return typedGet(this, idOrHandle, idOrOpts);
+        const id = idOrHandle;
+        const opts = idOrOpts;
         const record = await this.stack.get(id, opts);
         if (!record)
             return null;
@@ -734,16 +723,14 @@ export class ScopedStack {
     async getOwnerEntity() {
         return this.getEntityByDid(this.stack.ownerEntityId);
     }
-    /**
-     * Query records, filtered to those this request can read. Pages are
-     * filtered then refilled, so a page may slightly overshoot `limit` but
-     * never skips a record. Grants are prefetched once, cursor-walked to
-     * exhaustion.
-     */
-    async query(query = {}) {
+    async query(first = {}, typedQueryArg) {
+        if (isTypeHandle(first))
+            return typedQuery(this, first, typedQueryArg);
+        const query = first;
         assertValidSort(query.sort);
         assertSortCapability(query.sort, this.stack.capabilities);
         assertValidAssociationFilters(query.filter);
+        assertValidBaseIdFilter(query.filter);
         if (query.filter?.includeUnlisted && !this.ownerActingAlone) {
             throw new StackPermissionError('includeUnlisted is owner-only');
         }
@@ -771,17 +758,13 @@ export class ScopedStack {
         } while (records.length < limit && page.cursor && totalFetched < maxFetched);
         return { records, cursor: page.cursor };
     }
-    /**
-     * Apply a change set on behalf of the subject. Authority is resolved
-     * **per key** and every gate reads the record as it stands, never as the
-     * change set would leave it: a widened `permissions` never satisfies the
-     * read check on a `parentId` named in the same call, and a `_group`
-     * roster never satisfies the admin check that same call has to pass.
-     * One refused key refuses the whole call, so nothing is partially
-     * applied and no key is silently dropped.
-     * See docs/spec/access-control.md § Composing a change set.
-     */
-    async mutate(id, changes, opts = {}) {
+    async mutate(first, second, third, fourth = {}) {
+        if (isTypeHandle(first)) {
+            return typedMutate(this, first, second, third, fourth);
+        }
+        const id = first;
+        const changes = second;
+        const opts = (third ?? {});
         // Ahead of every gate: a malformed change set is a validation error
         // for every requester, rather than one for the owner and a permission
         // refusal for everyone else.
@@ -856,12 +839,15 @@ export class ScopedStack {
             await this.requireAssociationAccess(record.typeId, assoc);
         }
         if (changes.parentId != null && !(await this.canReadReferent(changes.parentId))) {
-            throw new StackPermissionError();
+            throw new StackPermissionError(`Cannot reference record "${changes.parentId}" as parent: it does not exist or you cannot read it`);
         }
         return this.stack.mutate(id, authorized, { ...opts, ...this.actor });
     }
-    async patchContent(id, patch, opts = {}) {
-        return this.mutate(id, { contentPatch: patch }, opts);
+    async patchContent(first, second, third, fourth) {
+        if (isTypeHandle(first)) {
+            return this.mutate(first, second, { contentPatch: third }, fourth);
+        }
+        return this.mutate(first, { contentPatch: second }, third);
     }
     /**
      * The record, having established that this request may decide who else
@@ -871,15 +857,12 @@ export class ScopedStack {
      * deliberately does not confer.
      */
     async requireReshareable(id) {
-        const record = await this.stack.get(id);
+        const record = await this.stack.get(id, { includeDeleted: true });
         if (!record)
             throw new StackNotFoundError(`Record not found: "${id}"`);
         await this.requireOwnerForGrantRecord(record);
         await this.requireReshareOf(record);
-        // Reached through its own gate rather than requireUpdatable(), so the
-        // soft-delete refusal has to be asked here too — after the authority
-        // decision above, for the reason refuseIfDeleted() gives.
-        return this.refuseIfDeleted(record, true);
+        return record;
     }
     /**
      * Whether a change set's `permissions` key actually moves the ACL. Read
@@ -896,8 +879,9 @@ export class ScopedStack {
     }
     /** The reshare decision alone, for a record already read and write-gated. */
     async requireReshareOf(record) {
-        if (!this.canReshare(record))
-            throw await this.denialFor(record);
+        if (!this.canReshare(record)) {
+            throw await this.denialFor(record, `Cannot change permissions on "${record.id}": only its author or the stack owner can reshare it`);
+        }
     }
     /**
      * Whether this request may decide who else reaches `record` — the
@@ -980,35 +964,46 @@ export class ScopedStack {
     /**
      * A `_grant` Record *is* authority, so rewriting one is the escalation
      * UNGRANTABLE_SYSTEM_TYPES refuses at evaluation, reached by editing an
-     * existing grant rather than minting a fresh one. `grantType()` and `revokeType()`
-     * live on `Stack`, never `StackClient`, so no scoped write is lost. Writes
-     * only: reading a grant Record and its history stays on the ordinary gate.
-     * See docs/spec/access-control.md § Type-level grants.
+     * existing grant rather than minting a fresh one. An `_install` decides
+     * grants and migration authority, so it is fenced the same way. The verbs
+     * that write either live on `Stack`, never `StackClient`, so no scoped
+     * write is lost. Writes only: reading one and its history stays on the
+     * ordinary gate. See docs/spec/access-control.md § Type-level grants.
      */
     async requireOwnerForGrantRecord(record) {
-        if (baseIdOf(record.typeId) !== SYSTEM_TYPES.GRANT)
+        const family = baseIdOf(record.typeId);
+        if (family !== SYSTEM_TYPES.GRANT && family !== SYSTEM_TYPES.INSTALL)
             return;
         if (this.ownerActingAlone)
             return;
-        throw await this.denialFor(record, 'Only the stack owner may write a _grant record');
+        throw await this.denialFor(record, `Only the stack owner may write a ${family} record`);
     }
     /**
-     * Gated on the write bit alone, which is why the kind refusal comes
-     * first: authority reached through this verb would be exactly the
+     * Gated on the write bit alone, which is why the list is held to its
+     * rules first: authority reached through this verb would be exactly the
      * escalation the partition exists to stop, decided before any record is
      * read so it cannot depend on who is asking.
      */
-    async associate(id, association) {
-        assertDataAssociations([association], 'associate()');
-        const record = await this.requireUpdatable(id);
-        await this.requireAssociationAccess(record.typeId, association);
-        return this.stack.associate(id, association, this.actor);
+    async associate(id, associations) {
+        return this.amendAssociations(id, associations.map((association) => ({ op: 'add', association })), 'associate()');
     }
     /** See associate() — the same write gate, the same kind refusal. */
-    async dissociate(id, association) {
-        assertDataAssociations([association], 'dissociate()');
-        await this.requireUpdatable(id);
-        return this.stack.dissociate(id, association, this.actor);
+    async dissociate(id, associations) {
+        return this.amendAssociations(id, associations.map((association) => ({ op: 'remove', association })), 'dissociate()');
+    }
+    /**
+     * The write gate, plus the per-element reference gate on each add: what a
+     * remove names is already on the record, so it is gated by the write bit
+     * alone. See associate().
+     */
+    async amendAssociations(id, changes, surface = 'amendAssociations()') {
+        assertAssociationEdits(changes, surface, 'data');
+        const record = await this.requireUpdatable(id);
+        for (const change of changes) {
+            if (change.op === 'add')
+                await this.requireAssociationAccess(record.typeId, change.association);
+        }
+        return this.stack.amendAssociations(id, changes, this.actor, surface);
     }
     /**
      * Extend who reaches a record — the reshare gate's own verb, on the
@@ -1018,16 +1013,18 @@ export class ScopedStack {
      * scoping access is for.
      * See docs/spec/access-control.md § Record-level permissions.
      */
-    async grantAccess(id, permission) {
-        assertAuthorityAssociations([permission], 'grantAccess()');
-        await this.requireReshareable(id);
-        return this.stack.grantAccess(id, permission, this.actor);
+    async grantAccess(id, permissions) {
+        return this.amendAccess(id, permissions.map((association) => ({ op: 'add', association })), 'grantAccess()');
+    }
+    /** Withdraw elements of who reaches a record — see grantAccess(). */
+    async revokeAccess(id, permissions) {
+        return this.amendAccess(id, permissions.map((association) => ({ op: 'remove', association })), 'revokeAccess()');
     }
-    /** Withdraw one element of who reaches a record — see grantAccess(). */
-    async revokeAccess(id, permission) {
-        assertAuthorityAssociations([permission], 'revokeAccess()');
+    /** The reshare gate over an edit list — see grantAccess(). */
+    async amendAccess(id, changes, surface = 'amendAccess()') {
+        assertAssociationEdits(changes, surface, 'authority');
         await this.requireReshareable(id);
-        return this.stack.revokeAccess(id, permission, this.actor);
+        return this.stack.amendAccess(id, changes, this.actor, surface);
     }
     /**
      * Purge is owner-only: it is irreversible and destroys version
@@ -1069,9 +1066,9 @@ export class ScopedStack {
      * already read got that way is not the escalation that fence exists to
      * stop. See docs/spec/versioning.md § History access.
      */
-    async getVersions(id) {
+    async getVersions(id, query = {}) {
         await this.requireUpdatable(id, { mutating: false });
-        return this.stack.getVersions(id);
+        return this.stack.getVersions(id, query);
     }
     /**
      * See getVersions() — the same mutate-surface gate, for the same reason.
@@ -1118,8 +1115,10 @@ export class ScopedStack {
         return this.stack.restoreVersion(id, version, { ...opts, ...this.actor });
     }
     /**
-     * Commit a per-record migration — **the owner acting alone, only**, the
-     * same restriction the bulk `migrateAll()` carries by living on `Stack`.
+     * Commit a per-record migration — **the owner acting alone**, the same
+     * restriction the bulk `migrateAll()` carries by living on `Stack`, with
+     * one exception: an installed app migrating within its own families (see
+     * installMayMigrate()).
      *
      * Migrate replaces `content` and `typeId` wholesale, so a grant-based
      * version would have to re-derive every gate `create()` applies at the
@@ -1132,9 +1131,86 @@ export class ScopedStack {
      * See docs/spec/data-model.md § Type migrations.
      */
     async commitMigration(id, toTypeId, content, opts = {}) {
-        this.requireOwnerActingAlone('Only the stack owner may commit a migration');
+        if (!this.ownerActingAlone && !(await this.installMayMigrate(id, toTypeId))) {
+            throw new StackPermissionError('Only the stack owner, or an installed app within the type families it defines, may commit a migration');
+        }
+        // The new content is a fresh set of file references, so an app is held
+        // to the gate create() applies; otherwise a migration could point one of
+        // its records at any attachment and read the bytes through it.
+        if (!this.ownerActingAlone)
+            await this.requireFileRefAccess(toTypeId, content);
         return this.stack.commitMigration(id, toTypeId, content, { ...opts, ...this.actor });
     }
+    /**
+     * Whether this request is an installed app migrating a record within its
+     * own families: the app acting as itself, its key linked to the one live
+     * install claiming both families in its own namespace, `toTypeId` a version the owner
+     * approved, and an `update-any` grant on each family made out to the key
+     * directly. Read as data, so a family two installs claim — however that
+     * came to be — confers nothing.
+     *
+     * The reasons migration is otherwise owner-only do not reach this case:
+     * no install can claim a system family, so neither an `_attachment` nor
+     * a DID binding is in reach, and the owner's approval of the version is
+     * the consent. See docs/spec/apps.md § Migrating an installed app's types.
+     */
+    async installMayMigrate(id, toTypeId) {
+        const principal = this.#principalId;
+        if (!principal || this.delegated)
+            return false;
+        const record = await this.stack.get(id, { includeDeleted: true });
+        if (!record)
+            return false;
+        const families = new Set([baseIdOf(record.typeId), baseIdOf(toTypeId)]);
+        const installs = (await queryAllPages((q) => this.stack.query(q), {
+            filter: { baseId: SYSTEM_TYPES.INSTALL, includeDeleted: true, includeUnlisted: true },
+        }));
+        let install;
+        for (const family of families) {
+            const claimants = installs.filter((r) => claimedFamilies(r.content).has(family));
+            if (claimants.length !== 1)
+                return false;
+            if (familyStanding(family, claimants[0].content.appId) !== 'own')
+                return false;
+            if (install && install.id !== claimants[0].id)
+                return false;
+            install = claimants[0];
+        }
+        if (!install || install.deletedAt)
+            return false;
+        if (!Array.isArray(install.content.defines) || !install.content.defines.includes(toTypeId)) {
+            return false;
+        }
+        let linked = false;
+        for (const cardId of linkedIds(install, INSTALL_APP_LABEL)) {
+            const card = await this.stack.get(cardId);
+            if (card && baseIdOf(card.typeId) === SYSTEM_TYPES.APP) {
+                if (card.content.did === principal)
+                    linked = true;
+            }
+        }
+        if (!linked)
+            return false;
+        const grants = await this.loadGrants();
+        for (const family of families) {
+            const held = await this.hasGrant(`${family}@1`, ['update-any'], {
+                grantee: principal,
+                prefetchedGrants: grants,
+                matchOwn: false,
+                allowDefault: false,
+                allowGroup: false,
+            });
+            if (!held)
+                return false;
+        }
+        // Asked only once authority is settled, as every mutating verb asks it.
+        // The owner may migrate a tombstone; an app sees it without content.
+        // See docs/spec/apps.md § Migrating an installed app's types.
+        if (record.deletedAt) {
+            throw new StackConflictError(`Record "${id}" is soft-deleted; undelete it before migrating it.`);
+        }
+        return true;
+    }
     /**
      * Store bytes and create an _attachment@1 metadata record (create grant
      * on `_attachment@1` required; anonymous denied), returning that record.
@@ -1169,8 +1245,9 @@ export class ScopedStack {
      * predicate as the reference-creation gate (canAccessFile).
      */
     async getAttachment(fileId) {
-        if (!(await this.canAccessFile(fileId)))
-            throw new StackPermissionError();
+        if (!(await this.canAccessFile(fileId))) {
+            throw new StackPermissionError(`Cannot read file "${fileId}": it does not exist or you cannot read it`);
+        }
         return this.stack.getAttachment(fileId);
     }
     /**
@@ -1189,17 +1266,12 @@ export class ScopedStack {
         this.requireOwnerActingAlone('Only the stack owner can collect attachment garbage');
         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 a count of the whole match
-     * off a query result. See docs/spec/events.md § Permission scoping.
-     */
-    async subscribe(handler, opts = {}) {
+    async subscribe(first, second, third) {
+        if (isTypeHandle(first)) {
+            return typedSubscribe(this, first, second, third);
+        }
+        const handler = first;
+        const opts = (second ?? {});
         this.assertStackOpen();
         if (this.relaysChanges) {
             throw new RelayScopeError('This stack relays changes from elsewhere, and a scoped view cannot narrow that feed: ' +
@@ -1209,6 +1281,7 @@ export class ScopedStack {
         // A relaying stack was already refused above, so relaysChanges is
         // always false here — `since` never has a cursor to mean anything by.
         assertSinceUsable(opts.since, false);
+        assertValidBaseIdFilter(opts.filter);
         if (opts.includeUnlisted && !this.ownerActingAlone) {
             throw new StackPermissionError('includeUnlisted is owner-only');
         }