@haverstack/core 0.38.0 → 0.40.0

package/dist/stack.js

@@ -14,22 +14,23 @@
  * Apps should never talk to a StackAdapter directly.
  */
 import { generateId, generateIdForTimestamp } from './id.js';
-import { hashSchema, isCompatible, parseTypeId, baseIdOf, diffSchemas, isWellFormedTypeId, } from './schema.js';
-import { validateContent, validateContentKeys, validatePatchValues, validateReservedKeys, validateSchemaFieldNames, validateSchemaReservedNames, validateSchemaShape, } from './validate.js';
+import { hashSchema, isCompatible, parseTypeId, baseIdOf, diffSchemas, familyIdProblem, } from './schema.js';
+import { dropAbsentFields, validateContent, validateContentKeys, validatePatchValues, validateReservedKeys, validateSchemaFieldNames, validateSchemaReservedNames, validateSchemaShape, } from './validate.js';
 import { applyMergePatch } from './merge.js';
-import { hasGroupAdmin, isGroupAdminAssociation, validatePermissions } from './access.js';
+import { hasGroupAdmin, validatePermissions } from './access.js';
 import { compareRecordedAttachments } from './attachment-download.js';
 import { ChangeEmitter, RelayDelivery, PendingChange, assertSinceUsable } from './changes.js';
 import { SYSTEM_TYPES } from './types.js';
 import { UseAfterCloseError, InvalidAdapterError, StackConflictError, StackMigrationError, StackNotFoundError, StackBadRequestError, StackSchemaDriftError, StackValidationError, StackVersionConflictError, } from './errors.js';
-import { assertQueryCapabilities, assertSortCapability, assertValidAssociationFilters, 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 { assertQueryCapabilities, assertSortCapability, assertValidAssociationFilters, assertValidBaseIdFilter, assertValidJournalQuery, assertValidVersionsQuery, assertValidSort, normalizeSort, assertAssociationEdits, assertAuthorityAssociations, assertDataAssociations, filtersContent, validateAssociations, } from './query-validation.js';
+import { GRANT_ACTION_SET, READ_COMPANIONS, grantConveys, grantReach, matchesGrantTarget, validateGrantTarget, validateGrantee, validateGrantBaseId, grantCoversGrantee, 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, isGroupRecord, } from './record-changes.js';
+import { applyAssociationEdits, associationDelta, associationIdentical, assertNonEmptyChangeSet, changeSetOps, bumpsVersion, takesIfVersion, effectiveChanges, stampGroupAdmin, isGroupRecord, } from './record-changes.js';
 import { ScopedStack, scopeToken } from './scoped-stack.js';
+import { isTypeHandle, typedCreate, typedGet, typedMutate, typedQuery, typedSubscribe, } from './type-handle.js';
 // -------------------------------------------------------
 // Supporting types
 // -------------------------------------------------------
@@ -235,8 +236,10 @@ export class Stack {
      * anything beyond additive evolution throws StackSchemaDriftError. See
      * docs/spec/data-model.md § Schema drift detection.
      */
-    async defineType({ id, name, schema, migratesFrom }) {
+    async defineType({ id, name, schema: declared, migratesFrom, }) {
         this.assertOpen();
+        // Only read below; the readonly view exists so a handle's literal fits.
+        const schema = declared;
         const parsed = parseTypeId(id);
         if (!parsed) {
             throw new StackBadRequestError(`Invalid TypeId format: "${id}". Expected "namespace/name@version", e.g. "com.example.myapp/note@1".`);
@@ -376,6 +379,9 @@ export class Stack {
      */
     async migrateAll(baseId) {
         this.assertOpen();
+        const problem = familyIdProblem(baseId, 'migrateAll');
+        if (problem)
+            throw new StackValidationError([{ path: 'baseId', message: problem }]);
         const types = await this.adapter.listTypes();
         const familyTypeIds = types.filter((t) => t.baseId === baseId).map((t) => t.id);
         if (familyTypeIds.length === 0) {
@@ -413,26 +419,16 @@ export class Stack {
         }
         return { migrated };
     }
-    // -------------------------------------------------------
-    // Records
-    // -------------------------------------------------------
-    /**
-     * Create a new record. Validates content against the type's schema.
-     * `_group` records get their author stamped as the first `admin` roster
-     * association here — the single stamping site for both Stack.create()
-     * and ScopedStack.create(). `opts.createdAt`/`updatedAt` let a caller
-     * backdate an imported record's clock fields — unconditionally here;
-     * ScopedStack.create() forwards to this same method, but only reaches
-     * this far with them when the requester is the stack owner acting alone
-     * — see BackdatableCreateRecordOptions and docs/spec/data-model.md §
-     * Record IDs.
-     */
-    async create(typeId, content, opts = {}) {
+    async create(typeIdOrHandle, input, opts = {}) {
+        if (isTypeHandle(typeIdOrHandle))
+            return typedCreate(this, typeIdOrHandle, input, opts);
+        const typeId = typeIdOrHandle;
         this.assertOpen();
         const type = await this.getTypeCached(typeId);
         if (!type) {
             throw new StackBadRequestError(`Unknown type: "${typeId}". Call defineType() first.`);
         }
+        const content = dropAbsentFields(input, type.schema);
         // 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.
@@ -453,6 +449,7 @@ export class Stack {
             ...validateContentKeys(content),
             ...validateContent(content, type.schema),
             ...validateGrantee(typeId, content),
+            ...validateGrantBaseId(typeId, content),
             ...validateAssociations(opts.permissions, 'permissions'),
             ...validatePermissions(opts.permissions),
             ...validateAssociations(opts.associations),
@@ -564,35 +561,33 @@ export class Stack {
         }
         return record;
     }
-    /**
-     * Get a record by ID, exactly as stored — no implicit migration. Pass
-     * { presentAt: 'latest' } to migrate in memory; only migrateAll()
-     * commits migrations to disk.
-     */
-    async get(id, opts = {}) {
+    async get(idOrHandle, idOrOpts = {}) {
+        if (isTypeHandle(idOrHandle))
+            return typedGet(this, idOrHandle, idOrOpts);
+        const id = idOrHandle;
+        const opts = idOrOpts;
         this.assertOpen();
         const record = await this.adapter.getRecord(id);
         if (!record)
             return null;
+        if (record.deletedAt && !opts.includeDeleted)
+            return null;
         return opts.presentAt === 'latest' ? this.presentAtLatest(record) : record;
     }
-    /**
-     * 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.
-     *
-     * 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 = {}) {
+    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 ?? {});
         this.assertOpen();
         assertNonEmptyChangeSet(changes);
         const existing = await this.adapter.getRecord(id);
         if (!existing) {
             throw new StackNotFoundError(`Record not found: "${id}"`);
         }
+        this.refuseIfDeleted(existing);
         // Checked before validation, so a caller that lost the race learns its
         // version is stale rather than that its patch is bad, and before the
         // no-op short-circuit below, so a precondition is never satisfied by a
@@ -641,13 +636,11 @@ export class Stack {
         this.announce(change, updated);
         return updated;
     }
-    /**
-     * mutate() with `contentPatch` alone. The common case by a wide margin,
-     * and named for what it does rather than for a symmetry with create()
-     * that a patch does not have.
-     */
-    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);
     }
     /**
      * Every check a change set owes before anything is written, in one pass:
@@ -700,6 +693,7 @@ export class Stack {
             const contentErrors = [
                 ...validateContent(merged, type.schema),
                 ...validateGrantee(existing.typeId, merged),
+                ...validateGrantBaseId(existing.typeId, merged),
             ];
             if (contentErrors.length > 0)
                 throw new StackValidationError(contentErrors);
@@ -746,7 +740,7 @@ export class Stack {
             'least one `admin` relationship association. Name the incoming admin in the same write.');
     }
     /**
-     * Add an association to a record — no-bump and no snapshot, per the
+     * Add associations 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
@@ -756,120 +750,86 @@ export class Stack {
      * 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);
-        const existing = await this.adapter.getRecord(id);
-        if (!existing) {
-            throw new StackNotFoundError(`Record not found: "${id}"`);
-        }
-        if ((existing.associations ?? []).some((a) => associationIdentical(a, association))) {
-            return existing;
-        }
-        const replaced = (existing.associations ?? []).find((a) => associationEqual(a, association));
-        await this.checkAttachmentAssociationPointers([association]);
-        const change = new PendingChange('associate', {
-            actor: normalizeActor(opts.actor),
-            // 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;
+    async associate(id, associations, opts = {}) {
+        return this.amendAssociations(id, associations.map((association) => ({ op: 'add', association })), opts, 'associate()');
     }
     /**
-     * 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
+     * Remove associations from a record — see associate(). Matched by kind,
+     * label and payload; an element not found is a no-op. The emitted event
+     * names each association by identity only, since an attachment's
      * `attachmentRecordId` describes nothing current once it is gone; the
      * journal is where it survives.
      */
-    async dissociate(id, association, opts = {}) {
-        this.assertOpen();
-        assertDataAssociations([association], 'dissociate()');
-        const errors = validateAssociation(association);
-        if (errors.length > 0)
-            throw new StackValidationError(errors);
-        const existing = await this.adapter.getRecord(id);
-        if (!existing) {
-            throw new StackNotFoundError(`Record not found: "${id}"`);
-        }
-        const matched = (existing.associations ?? []).find((a) => associationEqual(a, association));
-        if (!matched) {
-            return existing;
-        }
-        // Removing anything else cannot take the roster to zero, so only an
-        // admin entry is worth deriving the post-state for. Derived rather than
-        // counted so this path and the change set's reach the invariant through
-        // the same helper, asking the same question of the same shape of list.
-        if (isGroupAdminAssociation(association)) {
-            this.assertGroupAdminRemains(existing, (existing.associations ?? []).filter((a) => !associationEqual(a, association)));
-        }
-        const change = new PendingChange('dissociate', {
-            actor: normalizeActor(opts.actor),
-            // 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 }],
-        });
-        const updated = await this.adapter.dissociate(id, association, { journal: change.journal });
-        this.announce(change, updated);
-        return updated;
+    async dissociate(id, associations, opts = {}) {
+        return this.amendAssociations(id, associations.map((association) => ({ op: 'remove', association })), opts, 'dissociate()');
     }
     /**
-     * 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.
+     * The atomic form of associate() and dissociate(): one list of adds and
+     * removes, one adapter write, one journal entry. The journal records each
+     * element in full — a remove with its annotation, a re-point with what it
+     * overwrote — so the entry is as undoable as a single-element one.
+     * See docs/spec/data-model.md § Mutations.
      */
-    async grantAccess(id, permission, opts = {}) {
+    async amendAssociations(id, changes, opts = {}, surface = 'amendAssociations()') {
         this.assertOpen();
-        assertAuthorityAssociations([permission], 'grantAccess()');
-        const errors = validateAssociation(permission, 'permission');
-        if (errors.length > 0)
-            throw new StackValidationError(errors);
+        assertAssociationEdits(changes, surface, 'data');
         const existing = await this.requireRecord(id);
-        const current = existing.permissions ?? [];
-        if (current.some((p) => associationEqual(p, permission)))
+        this.refuseIfDeleted(existing);
+        const current = existing.associations ?? [];
+        const next = applyAssociationEdits(current, changes);
+        const delta = associationDelta(current, next);
+        if (delta.length === 0)
             return existing;
-        this.assertPermissionSet([...current, permission]);
-        const change = new PendingChange('reshare', {
-            actor: normalizeActor(opts.actor),
-            associations: [{ op: 'add', association: permission }],
-        });
-        const updated = await this.adapter.associate(id, permission, { journal: change.journal });
+        // Only a roster can lose its last admin, and only the post-state says so.
+        this.assertGroupAdminRemains(existing, next);
+        await this.checkAttachmentAssociationPointers(changes.flatMap((c) => (c.op === 'add' ? [c.association] : [])), current);
+        const change = new PendingChange([
+            ...(delta.some((c) => c.op !== 'remove') ? ['associate'] : []),
+            ...(delta.some((c) => c.op === 'remove') ? ['dissociate'] : []),
+        ], { actor: normalizeActor(opts.actor), associations: delta });
+        const updated = await this.adapter.amendAssociations(id, changes, { journal: change.journal });
         this.announce(change, updated);
         return updated;
     }
     /**
-     * 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.
+     * Extend who reaches a record. The spelling that survives two admins
+     * sharing a record at once: a `permissions` key write replaces the whole
+     * set, so the later of two concurrent ones drops what the earlier
+     * granted. No-bump, like associate(); an element the record already
+     * carries is a no-op. `write` never implies `read` — name both.
+     */
+    async grantAccess(id, permissions, opts = {}) {
+        return this.amendAccess(id, permissions.map((association) => ({ op: 'add', association })), opts, 'grantAccess()');
+    }
+    /**
+     * Withdraw elements of who reaches a record — see grantAccess() for why
+     * this is a verb rather than a key write. An element the record does not
+     * carry is a no-op. Returns the record as it now stands.
      */
-    async revokeAccess(id, permission, opts = {}) {
+    async revokeAccess(id, permissions, opts = {}) {
+        return this.amendAccess(id, permissions.map((association) => ({ op: 'remove', association })), opts, 'revokeAccess()');
+    }
+    /**
+     * The atomic form of grantAccess() and revokeAccess(). The
+     * write-implies-read invariant is asked once, of the set the whole list
+     * produces. See docs/spec/access-control.md § Write implies read.
+     */
+    async amendAccess(id, changes, opts = {}, surface = 'amendAccess()') {
         this.assertOpen();
-        assertAuthorityAssociations([permission], 'revokeAccess()');
-        const errors = validateAssociation(permission, 'permission');
-        if (errors.length > 0)
-            throw new StackValidationError(errors);
+        assertAssociationEdits(changes, surface, 'authority');
         const existing = await this.requireRecord(id);
+        this.refuseIfDeleted(existing);
         const current = existing.permissions ?? [];
-        const matched = current.find((p) => associationEqual(p, permission));
-        if (!matched)
+        const next = applyAssociationEdits(current, changes);
+        const delta = associationDelta(current, next);
+        if (delta.length === 0)
             return existing;
-        this.assertPermissionSet(current.filter((p) => !associationEqual(p, permission)));
+        this.assertPermissionSet(next);
         const change = new PendingChange('reshare', {
             actor: normalizeActor(opts.actor),
-            associations: [{ op: 'remove', previous: matched }],
+            associations: delta,
         });
-        const updated = await this.adapter.dissociate(id, permission, { journal: change.journal });
+        const updated = await this.adapter.amendAssociations(id, changes, { journal: change.journal });
         this.announce(change, updated);
         return updated;
     }
@@ -882,6 +842,18 @@ export class Stack {
         if (errors.length > 0)
             throw new StackValidationError(errors);
     }
+    /**
+     * A soft-deleted record has no current state to edit, so the verbs that
+     * edit one refuse it; undelete() and commitMigration() do not call this.
+     * Asked after the record is found and, under ScopedStack, after the
+     * authority decision. See docs/spec/versioning.md § Mutations are refused,
+     * not applied to a tombstone.
+     */
+    refuseIfDeleted(record) {
+        if (record.deletedAt) {
+            throw new StackConflictError(`Record "${record.id}" is soft-deleted; undelete it before mutating it.`);
+        }
+    }
     /** The record, or the not-found refusal every mutating verb owes. */
     async requireRecord(id) {
         const record = await this.adapter.getRecord(id);
@@ -1045,19 +1017,17 @@ export class Stack {
         this.announce(change, undeleted);
         return undeleted;
     }
-    /**
-     * Query records. filter.baseId matches every version of a type family,
-     * resolved against registered Types. Results come back exactly as
-     * stored; pass presentAt: 'latest' to migrate in memory. See
-     * docs/spec/data-model.md § Queries.
-     */
-    async query(query = {}) {
+    async query(first = {}, typedQueryArg) {
+        if (isTypeHandle(first))
+            return typedQuery(this, first, typedQueryArg);
+        const query = first;
         this.assertOpen();
         const { presentAt, filter, limit: rawLimit, ...rest } = query;
         assertQueryCapabilities(filter, this.adapter.capabilities);
         assertValidSort(query.sort);
         assertSortCapability(query.sort, this.adapter.capabilities);
         assertValidAssociationFilters(filter);
+        assertValidBaseIdFilter(filter);
         const limit = rawLimit !== undefined ? Math.min(rawLimit, MAX_QUERY_LIMIT) : undefined;
         const resolvedFilter = await this.resolveBaseIdFilter(filter);
         if (resolvedFilter === EMPTY_FAMILY) {
@@ -1065,6 +1035,7 @@ export class Stack {
         }
         const result = await this.adapter.queryRecords({
             ...rest,
+            ...(query.sort && { sort: normalizeSort(query.sort) }),
             ...(resolvedFilter !== undefined && { filter: resolvedFilter }),
             ...(limit !== undefined && { limit }),
         });
@@ -1095,9 +1066,10 @@ export class Stack {
     // -------------------------------------------------------
     // Versions
     // -------------------------------------------------------
-    async getVersions(id) {
+    async getVersions(id, query = {}) {
         this.assertOpen();
-        return this.adapter.getVersions(id);
+        assertValidVersionsQuery(query);
+        return this.adapter.getVersions(id, query);
     }
     /**
      * A record's change journal, oldest first — what moved, who moved it, and
@@ -1129,6 +1101,7 @@ export class Stack {
         if (!existing) {
             throw new StackNotFoundError(`Record not found: "${id}"`);
         }
+        this.refuseIfDeleted(existing);
         this.checkIfVersion(existing, opts.ifVersion);
         const target = await this.adapter.getVersion(id, version);
         if (!target) {
@@ -1141,6 +1114,7 @@ export class Stack {
         const errors = [
             ...validateContent(target.content, type.schema),
             ...validateGrantee(target.typeId, target.content),
+            ...validateGrantBaseId(target.typeId, target.content),
         ];
         if (errors.length > 0) {
             throw new StackValidationError(errors);
@@ -1206,17 +1180,19 @@ export class Stack {
      * can cross type families; family-crossing is exactly what the checks
      * below care about.
      */
-    async commitMigrationChecked(existing, toTypeId, content, opts = {}) {
+    async commitMigrationChecked(existing, toTypeId, input, opts = {}) {
         const id = existing.id;
         const type = await this.getTypeCached(toTypeId);
         if (!type) {
             throw new StackBadRequestError(`Unknown type: "${toTypeId}". Call defineType() first.`);
         }
+        const content = dropAbsentFields(input, type.schema);
         const errors = [
             ...validateReservedKeys(content),
             ...validateContentKeys(content),
             ...validateContent(content, type.schema),
             ...validateGrantee(toTypeId, content),
+            ...validateGrantBaseId(toTypeId, content),
         ];
         if (errors.length > 0) {
             throw new StackValidationError(errors);
@@ -1667,22 +1643,15 @@ export class Stack {
         }
         return { deletedFileIds, reclaimedBytes };
     }
-    // -------------------------------------------------------
-    // Lifecycle
-    // -------------------------------------------------------
-    /**
-     * 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 = {}) {
+    async subscribe(first, second, third) {
+        if (isTypeHandle(first)) {
+            return typedSubscribe(this, first, second, third);
+        }
+        const handler = first;
+        const opts = (second ?? {});
         this.assertOpen();
         assertSinceUsable(opts.since, this.relaysChanges);
+        assertValidBaseIdFilter(opts.filter);
         const unsubscribe = this.changes.subscribe(handler, opts);
         let stopRelay;
         try {
@@ -1785,16 +1754,15 @@ export class Stack {
      * needs, not the suffix that looks narrowest. See
      * docs/spec/access-control.md § Delegation: principal and subject.
      *
-     * `typeOrBaseId` is a versioned TypeId (`"baseId@version"`) or a bare
-     * baseId; either names the whole family. See
-     * docs/spec/access-control.md § Type-level grants.
+     * `baseId` names the whole family and is refused when it carries an
+     * `@version` suffix. See docs/spec/access-control.md § Type-level grants.
      */
-    async grantType(typeOrBaseId, grant) {
+    async grantType(baseId, grant) {
         this.assertOpen();
         validateGrantTarget(grant.grantee);
-        this.checkGrantValid(typeOrBaseId, grant.actions);
+        this.checkGrantValid(baseId, grant.actions);
         return this.create(`${SYSTEM_TYPES.GRANT}@1`, {
-            typeId: typeOrBaseId,
+            baseId,
             actions: grant.actions,
             grantee: grant.grantee,
         });
@@ -1834,7 +1802,7 @@ export class Stack {
                 allowDefault: true,
                 allowGroup: true,
                 groupRoles,
-                resolveRecord: (id) => this.get(id),
+                resolveRecord: (id) => this.get(id, { includeDeleted: true }),
             });
             if (covers)
                 result.push(r);
@@ -1843,7 +1811,7 @@ export class Stack {
     }
     /**
      * The inverse of grantType(): soft-deletes the _grant records on
-     * `typeOrBaseId`'s family matching `grant`, at the same granularity
+     * `baseId`'s family matching `grant`, at the same granularity
      * grantType() writes — the grantee is matched whole, role included, and
      * the actions exactly. A soft delete like any other — the owner can
      * undelete a revocation.
@@ -1854,10 +1822,13 @@ export class Stack {
      * revocation has to stay safe. See
      * docs/spec/access-control.md § Listing and revoking.
      */
-    async revokeType(typeOrBaseId, grant) {
+    async revokeType(baseId, grant) {
         this.assertOpen();
         validateGrantTarget(grant.grantee);
-        const familyId = baseIdOf(typeOrBaseId);
+        const problem = familyIdProblem(baseId, 'revokeType');
+        if (problem)
+            throw new StackValidationError([{ path: 'baseId', message: problem }]);
+        const familyId = baseId;
         const actionSet = new Set(grant.actions);
         const all = await loadGrantRecords((q) => this.query(q));
         const matches = all.filter((r) => {
@@ -1881,29 +1852,22 @@ export class Stack {
     // Private helpers
     // -------------------------------------------------------
     /**
-     * Actions must be known GrantAction values, typeIds must be well-formed,
-     * and the _grant/_config families are refused — see
-     * docs/spec/access-control.md § Type-level grants.
+     * Actions must be known GrantAction values; the target is held to the
+     * same rule every `_grant` write meets — see validateGrantBaseId().
      */
-    checkGrantValid(typeId, actions) {
+    checkGrantValid(baseId, actions) {
         const errors = [];
         actions.forEach((action, j) => {
             if (!GRANT_ACTION_SET.has(action)) {
                 errors.push({ path: `actions[${j}]`, message: `Unknown grant action "${action}"` });
             }
         });
-        if (!isWellFormedTypeId(typeId)) {
-            errors.push({
-                path: 'typeId',
-                message: `"${typeId}" is not a well-formed baseId or versioned TypeId (expected "baseId" or "baseId@version")`,
-            });
+        const problem = familyIdProblem(baseId, 'grantType');
+        if (problem) {
+            errors.push({ path: 'baseId', message: problem });
         }
-        else if (UNGRANTABLE_SYSTEM_TYPES.has(baseIdOf(typeId))) {
-            const refused = [...UNGRANTABLE_SYSTEM_TYPES].join(', ');
-            errors.push({
-                path: 'typeId',
-                message: `Cannot grant on "${baseIdOf(typeId)}": grants on ${refused} are refused to prevent privilege escalation`,
-            });
+        else {
+            errors.push(...validateGrantBaseId(`${SYSTEM_TYPES.GRANT}@1`, { baseId }));
         }
         actions.forEach((action, j) => {
             if (grantConveys(actions, action))
@@ -1913,7 +1877,7 @@ export class Stack {
                 return;
             errors.push({
                 path: `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`,
+                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. Name both in one grant: actions: [${companions.map((c) => `'${c}'`).join(' | ')}, '${action}']`,
             });
         });
         if (errors.length > 0) {
@@ -1962,7 +1926,7 @@ export class Stack {
             id: `${SYSTEM_TYPES.GRANT}@1`,
             name: 'Grant',
             schema: {
-                typeId: { kind: 'string', required: true },
+                baseId: { kind: 'string', required: true },
                 actions: { kind: 'array', items: { kind: 'string' }, required: true },
                 // Required, and closed: a Grant's reach is spelled by its `grantee`,
                 // so a record arriving without one is refused here rather than read