@haverstack/core 0.37.0 → 0.38.0

package/dist/stack.js

@@ -9,7 +9,7 @@
  *  - Content validation on write
  *  - Migration registry and explicit, owner-driven migrateAll()
  *  - Version snapshotting on update
- *  - Soft and hard delete
+ *  - Soft delete and purge
  *
  * Apps should never talk to a StackAdapter directly.
  */
@@ -21,15 +21,15 @@ import { hasGroupAdmin, isGroupAdminAssociation, validatePermissions } from './a
 import { compareRecordedAttachments } from './attachment-download.js';
 import { ChangeEmitter, RelayDelivery, PendingChange, assertSinceUsable } from './changes.js';
 import { SYSTEM_TYPES } from './types.js';
-import { StackClosedError, StackConflictError, StackMigrationError, StackNotFoundError, StackPermissionError, StackQueryError, StackSchemaDriftError, StackValidationError, StackVersionConflictError, } from './errors.js';
-import { assertQueryCapabilities, assertSortCapability, assertValidRelatedTo, assertValidJournalQuery, assertValidSort, assertAuthorityAssociations, assertDataAssociations, filtersContent, validateAssociation, validateAssociations, } from './query-validation.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 { 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 { ScopedStack } from './scoped-stack.js';
+import { ScopedStack, scopeToken } from './scoped-stack.js';
 // -------------------------------------------------------
 // Supporting types
 // -------------------------------------------------------
@@ -46,6 +46,25 @@ const DEFAULT_GC_GRACE_MS = 24 * 60 * 60 * 1000;
  * § Reparenting.
  */
 const MAX_PARENT_DEPTH = 64;
+/**
+ * An Actor in the one form `Stack` stores: a `principalId` equal to the
+ * subject is dropped, so "acted as itself" has a single spelling, and an
+ * empty id is refused rather than stored as a name for nobody.
+ * See docs/spec/data-model.md § Actor.
+ */
+export function normalizeActor(actor) {
+    if (!actor)
+        return undefined;
+    for (const field of ['subjectId', 'principalId']) {
+        if (actor[field] === '') {
+            throw new StackBadRequestError(`Invalid ${field}: the empty string is not an id.`);
+        }
+    }
+    const { subjectId, principalId } = actor;
+    return principalId === undefined || principalId === subjectId
+        ? { subjectId }
+        : { subjectId, principalId };
+}
 /** Sentinel: filter.baseId resolved to zero matching types. */
 const EMPTY_FAMILY = Symbol('empty-family');
 /**
@@ -109,27 +128,7 @@ export class Stack {
     static createActor(record) {
         if (!record.updatedBy)
             return undefined;
-        return {
-            entityId: record.updatedBy,
-            ...(record.updatedVia !== undefined && { principalId: record.updatedVia }),
-            ...(record.appId !== undefined && { appId: record.appId }),
-        };
-    }
-    /**
-     * The requester behind a write that stamps nothing on the record itself —
-     * a hard delete, which leaves no record to stamp, and associate()/
-     * dissociate(), which don't bump and so don't touch updatedBy/updatedVia.
-     * Hard delete is owner-acting-alone only, so it never has a principal to
-     * name beside the subject; associate()/dissociate() can run delegated,
-     * so `updatedVia` rides along here when present.
-     */
-    static actorFrom(opts) {
-        if (!opts.updatedBy)
-            return undefined;
-        return {
-            entityId: opts.updatedBy,
-            ...(opts.updatedVia !== undefined && { principalId: opts.updatedVia }),
-        };
+        return { ...record.updatedBy, ...(record.appId !== undefined && { appId: record.appId }) };
     }
     async getTypeCached(id) {
         const cached = this.typeCache.get(id);
@@ -141,12 +140,12 @@ export class Stack {
         return type;
     }
     /**
-     * Create a Stack instance. Reads ownerEntityId and timezone from the adapter.
+     * Open a Stack over an adapter. Reads ownerEntityId and timezone from the adapter.
      */
-    static async create(adapter, opts = {}) {
+    static async open(adapter, opts = {}) {
         if (!adapter.ownerEntityId) {
-            throw new Error('Stack misconfiguration: adapter has no ownerEntityId. ' +
-                'Initialise the adapter with an entityId before calling Stack.create().');
+            throw new InvalidAdapterError('Invalid adapter: adapter has no ownerEntityId. ' +
+                'Initialize the adapter with an ownerEntityId before calling Stack.open().');
         }
         const stack = new Stack(adapter, opts.idTimestampSkewMs === undefined ? DEFAULT_ID_TIMESTAMP_SKEW_MS : opts.idTimestampSkewMs);
         await stack.seedSystemTypes();
@@ -180,7 +179,7 @@ export class Stack {
         return this.adapter.ownerEntityId;
     }
     async getEntityByDid(did) {
-        return lookupEntityByDid((q) => this.query(q), did, filtersContent(this.features), true);
+        return lookupEntityByDid((q) => this.query(q), did, filtersContent(this.capabilities), true);
     }
     async getOwnerEntity() {
         return this.getEntityByDid(this.ownerEntityId);
@@ -188,42 +187,43 @@ export class Stack {
     get timezone() {
         return this.adapter.timezone;
     }
-    get features() {
+    get capabilities() {
         return this.adapter.capabilities;
     }
     /**
      * Get a permission-scoped view of this Stack, as if requests came from
-     * the given principal (null = anonymous). Plain Stack methods are
-     * unscoped; use asEntity() when one Stack serves multiple, possibly
-     * untrusted, entities.
-     *
-     * `onBehalfOf` names the subject a delegated app acts for: authority is
-     * then the intersection of both parties' grants, while authorship and
-     * `-own` resolve against the subject. See
+     * the given entity acting as itself (null = anonymous). Plain Stack
+     * methods are unscoped; use asEntity() when one Stack serves multiple,
+     * possibly untrusted, entities. See
      * docs/spec/access-control.md § Enforcement: Stack.asEntity().
      */
-    asEntity(entityId, opts = {}) {
-        this.assertOpen();
-        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, this.changes);
+    asEntity(entityId) {
+        return entityId === null ? this.scope(null, null) : this.asActor({ subjectId: entityId });
     }
     /**
-     * Scope to an authenticated session — what StackTokenStore.lookupToken()
-     * returns. Equivalent to asEntity(principalId, { onBehalfOf: subjectId }),
-     * and what a server should reach for at its request boundary.
-     *
-     * Both identities are DIDs, so passing them positionally leaves nothing
-     * to catch a swap, and a swapped pair is undetectable in the undelegated
-     * case where they are equal — it would surface only once delegation is in
-     * use, as authority no longer fenced by the app's grants and every write
-     * attributed to the app rather than the person. Taking the pair whole
-     * removes the order to get wrong. See
-     * docs/spec/access-control.md § Delegation: principal and subject.
+     * Scope to an Actor — a delegated app acting for its user, or a
+     * TokenSession exactly as StackTokenStore.lookupToken() returns it, which
+     * is what a server should reach for at its request boundary. Authority is
+     * the intersection of both parties' grants, while authorship and `-own`
+     * resolve against the subject. Taking the pair whole leaves no order to
+     * swap. See docs/spec/access-control.md § Delegation: principal and subject.
      */
-    forSession(session) {
-        return this.asEntity(session.principalId, { onBehalfOf: session.subjectId });
+    asActor(actor) {
+        const { subjectId, principalId = subjectId } = normalizeActor(actor);
+        return this.scope(principalId, subjectId);
+    }
+    scope(principalId, subjectId) {
+        this.assertOpen();
+        return new ScopedStack(scopeToken, {
+            stack: this,
+            principalId,
+            subjectId,
+            idTimestampSkewMs: this.idTimestampSkewMsValue,
+            adapter: this.adapter,
+            changes: this.changes,
+            assertOpen: () => this.assertOpen(),
+            relaysChanges: this.relaysChanges,
+        });
     }
     // -------------------------------------------------------
     // Types
@@ -235,11 +235,11 @@ export class Stack {
      * anything beyond additive evolution throws StackSchemaDriftError. See
      * docs/spec/data-model.md § Schema drift detection.
      */
-    async defineType(id, name, schema, opts = {}) {
+    async defineType({ id, name, schema, migratesFrom }) {
         this.assertOpen();
         const parsed = parseTypeId(id);
         if (!parsed) {
-            throw new StackQueryError(`Invalid TypeId format: "${id}". Expected "namespace/name@version", e.g. "com.example.myapp/note@1".`);
+            throw new StackBadRequestError(`Invalid TypeId format: "${id}". Expected "namespace/name@version", e.g. "com.example.myapp/note@1".`);
         }
         // Register this version even on the idempotent-no-op path —
         // presentAtLatest()'s stale-writer detection depends on it.
@@ -284,7 +284,7 @@ export class Stack {
             schema,
             schemaHash,
             createdAt: existing?.createdAt ?? new Date(),
-            ...(opts.migratesFrom && { migratesFrom: opts.migratesFrom }),
+            ...(migratesFrom && { migratesFrom }),
         };
         await this.adapter.saveType(type);
         this.typeCache.set(id, type);
@@ -374,12 +374,12 @@ export class Stack {
      * too, validates each result before writing, and aborts on the first
      * validation failure. See docs/spec/data-model.md § Type migrations.
      */
-    async migrateAll(baseTypeId) {
+    async migrateAll(baseId) {
         this.assertOpen();
         const types = await this.adapter.listTypes();
-        const familyTypeIds = types.filter((t) => t.baseId === baseTypeId).map((t) => t.id);
+        const familyTypeIds = types.filter((t) => t.baseId === baseId).map((t) => t.id);
         if (familyTypeIds.length === 0) {
-            throw new StackMigrationError(`migrateAll: no registered types found for baseTypeId "${baseTypeId}"`);
+            throw new StackMigrationError(`migrateAll: no registered types found for baseId "${baseId}"`);
         }
         let migrated = 0;
         for (const typeId of familyTypeIds) {
@@ -431,7 +431,7 @@ export class Stack {
         this.assertOpen();
         const type = await this.getTypeCached(typeId);
         if (!type) {
-            throw new StackQueryError(`Unknown type: "${typeId}". Call defineType() first.`);
+            throw new StackBadRequestError(`Unknown type: "${typeId}". Call defineType() first.`);
         }
         // Copied, never aliased: an import loop that reuses one Date across rows
         // (`d.setTime(...)` per record) would otherwise retro-edit every record
@@ -468,7 +468,7 @@ export class Stack {
         if (errors.length > 0) {
             throw new StackValidationError(errors);
         }
-        assertContentSize(content, this.features.limits.contentBytes, 'Content');
+        assertContentSize(content, this.capabilities.limits.contentBytes, 'Content');
         if (typeId === `${SYSTEM_TYPES.ATTACHMENT}@1`) {
             await this.checkAttachmentMimeTypeOnCreate(content);
         }
@@ -489,8 +489,9 @@ export class Stack {
             if (opts.parentId !== undefined)
                 await this.assertNoParentCycle(opts.id, opts.parentId);
         }
+        const createdBy = normalizeActor(opts.createdBy);
         const associations = baseIdOf(typeId) === SYSTEM_TYPES.GROUP
-            ? stampGroupAdmin(opts.associations, opts.entityId ?? this.ownerEntityId)
+            ? stampGroupAdmin(opts.associations, createdBy?.subjectId ?? this.ownerEntityId)
             : opts.associations;
         // createdAt drives the id, so the two agree by construction rather than
         // by coincidence. An explicit one mints via generateIdForTimestamp(),
@@ -504,10 +505,8 @@ export class Stack {
         // An id field a caller supplies is a value or it is absent — never the
         // empty string, which names nobody. Refused rather than dropped, so the
         // caller is never silently ignored.
-        for (const field of ['entityId', 'appId', 'principalId']) {
-            if (opts[field] === '') {
-                throw new StackQueryError(`Invalid ${field}: the empty string is not an id.`);
-            }
+        if (opts.appId === '') {
+            throw new StackBadRequestError('Invalid appId: the empty string is not an id.');
         }
         // Every create naming a parent owes the reference check, whether or not
         // it supplied an id: a destination a caller names has to exist.
@@ -523,14 +522,11 @@ export class Stack {
             // Presence, not truthiness: '' is refused above, so absence is the
             // only thing a falsy value could mean here.
             ...(opts.parentId !== undefined && { parentId: opts.parentId }),
-            ...(opts.entityId !== undefined && { entityId: opts.entityId }),
             ...(opts.appId !== undefined && { appId: opts.appId }),
-            ...(opts.principalId !== undefined && { 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"
+            // A create's actor is its author, so `updatedBy` is derived rather
+            // than taken: stamping it 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 }),
+            ...(createdBy && { createdBy, updatedBy: createdBy }),
             ...(opts.permissions?.length && { permissions: opts.permissions }),
             ...(associations?.length && { associations }),
             ...(opts.unlisted && { unlistedAt: createdAt }),
@@ -614,11 +610,11 @@ export class Stack {
         // A change set naming only aspects the journal already keeps in full
         // doesn't bump — the same rule associate()/dissociate() follow
         // unconditionally. Its actor travels as an explicit opt rather than a
-        // record stamp, since a non-bumping write never touches
-        // updatedBy/updatedVia. See docs/spec/versioning.md § Version history.
+        // record stamp, since a non-bumping write never touches `updatedBy`.
+        // See docs/spec/versioning.md § Version history.
         const bumps = bumpsVersion(ops);
         // Computed against the same before/after changeSetOps compared, so
-        // whether associate/dissociate/permissions appear in `ops` and what
+        // whether associate/dissociate/reshare appear in `ops` and what
         // the journal lists can never disagree. Both halves of the partition
         // produce the same tagged edits and travel as one list: the journal's
         // argument is prior state, and an ACL element's is no different from a
@@ -633,17 +629,12 @@ export class Stack {
         ];
         const previousParentId = existing.parentId ?? null;
         const change = new PendingChange(ops, {
-            actor: Stack.actorFrom(opts),
+            actor: normalizeActor(opts.actor),
             ...(ops.includes('reparent') && { previousParentId }),
             ...(assocDelta.length && { associations: assocDelta }),
         });
         const updated = await this.adapter.mutateRecord(id, effectiveChanges(changes, ops), {
-            ...(bumps
-                ? this.writeOptions(existing, opts)
-                : {
-                    updatedBy: opts.updatedBy,
-                    updatedVia: opts.updatedVia,
-                }),
+            ...(bumps ? this.writeOptions(existing, opts) : { actor: normalizeActor(opts.actor) }),
             bumpsVersion: bumps,
             journal: change.journal,
         });
@@ -700,10 +691,10 @@ export class Stack {
         if (contentPatch) {
             // The patch is what travels, so the patch is what's measured — a
             // small patch against a large record is not an oversized request.
-            assertContentSize(contentPatch, this.features.limits.contentBytes, 'Patch');
+            assertContentSize(contentPatch, this.capabilities.limits.contentBytes, 'Patch');
             const type = await this.getTypeCached(existing.typeId);
             if (!type) {
-                throw new StackQueryError(`Unknown type: "${existing.typeId}"`);
+                throw new StackBadRequestError(`Unknown type: "${existing.typeId}"`);
             }
             merged = applyMergePatch(existing.content, contentPatch);
             const contentErrors = [
@@ -781,7 +772,7 @@ export class Stack {
         const replaced = (existing.associations ?? []).find((a) => associationEqual(a, association));
         await this.checkAttachmentAssociationPointers([association]);
         const change = new PendingChange('associate', {
-            actor: Stack.actorFrom(opts),
+            actor: normalizeActor(opts.actor),
             // A re-point carries what it overwrote: nothing else retains the
             // attachmentRecordId that association held.
             associations: [
@@ -821,7 +812,7 @@ export class Stack {
             this.assertGroupAdminRemains(existing, (existing.associations ?? []).filter((a) => !associationEqual(a, association)));
         }
         const change = new PendingChange('dissociate', {
-            actor: Stack.actorFrom(opts),
+            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.
@@ -849,8 +840,8 @@ export class Stack {
         if (current.some((p) => associationEqual(p, permission)))
             return existing;
         this.assertPermissionSet([...current, permission]);
-        const change = new PendingChange('permissions', {
-            actor: Stack.actorFrom(opts),
+        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 });
@@ -874,8 +865,8 @@ export class Stack {
         if (!matched)
             return existing;
         this.assertPermissionSet(current.filter((p) => !associationEqual(p, permission)));
-        const change = new PendingChange('permissions', {
-            actor: Stack.actorFrom(opts),
+        const change = new PendingChange('reshare', {
+            actor: normalizeActor(opts.actor),
             associations: [{ op: 'remove', previous: matched }],
         });
         const updated = await this.adapter.dissociate(id, permission, { journal: change.journal });
@@ -948,7 +939,7 @@ export class Stack {
         }
     }
     /**
-     * Soft-delete a record (default) or hard-delete it permanently, removing
+     * Soft-delete a record (default) or purge it permanently, removing
      * the record and its version history. Soft delete snapshots and bumps
      * version; a no-op if already deleted. `_config` is never deletable
      * (docs/spec.md § The `_config` record). See docs/spec/versioning.md
@@ -971,8 +962,8 @@ export class Stack {
     }
     /**
      * delete(), reporting the record it acted on alongside the files it
-     * stranded: as it stood immediately before destruction for a hard
-     * delete, or as the resulting tombstone for a soft delete. Both are
+     * stranded: as it stood immediately before destruction for a
+     * purge, or as the resulting tombstone for a soft delete. Both are
      * captured inside the same write that destroys or tombstones the record,
      * never a read beforehand — a read-then-delete would leave a window
      * where a concurrent write can land, get destroyed or overwritten by
@@ -983,15 +974,15 @@ export class Stack {
         if (id === SYSTEM_TYPES.CONFIG) {
             throw new StackConflictError("Cannot delete the _config record: it holds the stack's identity and is required for every permission check.");
         }
-        if (opts.hard) {
+        if (opts.purge) {
             // 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 change = new PendingChange('hard-delete', { actor: Stack.actorFrom(opts) });
+            const change = new PendingChange('purge', { actor: normalizeActor(opts.actor) });
             const purged = await this.adapter.deleteRecord(id, {
-                hard: true,
-                expectedVersion: opts.ifVersion,
+                purge: true,
+                ifVersion: opts.ifVersion,
                 journal: change.journal,
             });
             if (!purged)
@@ -1008,7 +999,7 @@ export class Stack {
         // attachments intact — so nothing is stranded and nothing is reported.
         if (existing.deletedAt)
             return { record: existing, referencedFileIds: [] };
-        const change = new PendingChange('delete', { actor: Stack.actorFrom(opts) });
+        const change = new PendingChange('delete', { actor: normalizeActor(opts.actor) });
         const deleted = await this.adapter.deleteRecord(id, {
             ...this.writeOptions(existing, opts),
             journal: change.journal,
@@ -1033,7 +1024,7 @@ export class Stack {
     }
     /**
      * Reverse a soft delete. Idempotent — undeleting a record that isn't
-     * deleted returns it unchanged. Hard-deleted records are gone, so this
+     * deleted returns it unchanged. Purged records are gone, so this
      * throws StackNotFoundError for them just like any other missing record.
      * Snapshots and bumps version, same as delete().
      */
@@ -1046,7 +1037,7 @@ export class Stack {
         this.checkIfVersion(existing, opts.ifVersion);
         if (!existing.deletedAt)
             return existing;
-        const change = new PendingChange('undelete', { actor: Stack.actorFrom(opts) });
+        const change = new PendingChange('undelete', { actor: normalizeActor(opts.actor) });
         const undeleted = await this.adapter.undeleteRecord(id, {
             ...this.writeOptions(existing, opts),
             journal: change.journal,
@@ -1066,7 +1057,7 @@ export class Stack {
         assertQueryCapabilities(filter, this.adapter.capabilities);
         assertValidSort(query.sort);
         assertSortCapability(query.sort, this.adapter.capabilities);
-        assertValidRelatedTo(filter?.relatedTo);
+        assertValidAssociationFilters(filter);
         const limit = rawLimit !== undefined ? Math.min(rawLimit, MAX_QUERY_LIMIT) : undefined;
         const resolvedFilter = await this.resolveBaseIdFilter(filter);
         if (resolvedFilter === EMPTY_FAMILY) {
@@ -1145,7 +1136,7 @@ export class Stack {
         }
         const type = await this.getTypeCached(target.typeId);
         if (!type) {
-            throw new StackQueryError(`Unknown type: "${target.typeId}"`);
+            throw new StackBadRequestError(`Unknown type: "${target.typeId}"`);
         }
         const errors = [
             ...validateContent(target.content, type.schema),
@@ -1168,7 +1159,10 @@ export class Stack {
         // A restore adds no containment edge and takes none away, so there is
         // no cycle for it to close and nothing for the destination checks to
         // gate. See docs/spec/versioning.md § Restore semantics.
-        const change = new PendingChange('restore', { actor: Stack.actorFrom(opts) });
+        const change = new PendingChange('restore', {
+            actor: normalizeActor(opts.actor),
+            previousTypeId: existing.typeId,
+        });
         const restored = await this.adapter.restoreVersion(id, version, {
             ...this.writeOptions(existing, opts),
             journal: change.journal,
@@ -1216,7 +1210,7 @@ export class Stack {
         const id = existing.id;
         const type = await this.getTypeCached(toTypeId);
         if (!type) {
-            throw new StackQueryError(`Unknown type: "${toTypeId}". Call defineType() first.`);
+            throw new StackBadRequestError(`Unknown type: "${toTypeId}". Call defineType() first.`);
         }
         const errors = [
             ...validateReservedKeys(content),
@@ -1227,7 +1221,7 @@ export class Stack {
         if (errors.length > 0) {
             throw new StackValidationError(errors);
         }
-        assertContentSize(content, this.features.limits.contentBytes, 'Content');
+        assertContentSize(content, this.capabilities.limits.contentBytes, 'Content');
         const fromFamily = baseIdOf(existing.typeId);
         const toFamily = baseIdOf(toTypeId);
         const existingContent = existing.content;
@@ -1257,7 +1251,10 @@ export class Stack {
         if (id === SYSTEM_TYPES.CONFIG) {
             this.checkConfigEntityIdUnchanged(existing.content.entityId, content.entityId);
         }
-        const change = new PendingChange('migrate', { actor: Stack.actorFrom(opts) });
+        const change = new PendingChange('migrate', {
+            actor: normalizeActor(opts.actor),
+            previousTypeId: existing.typeId,
+        });
         const migrated = await this.adapter.commitMigration(id, toTypeId, content, {
             ...this.writeOptions(existing, opts),
             journal: change.journal,
@@ -1317,8 +1314,8 @@ export class Stack {
         }
     }
     /**
-     * A unique binding field is what a lookup resolves *by* — a record's
-     * `principalId` by `_app.did`, its `entityId` by `_entity.did`. Two cards
+     * A unique binding field is what a lookup resolves *by* — an Actor's
+     * `principalId` by `_app.did`, its `subjectId` by `_entity.did`. Two cards
      * claiming one value would leave that lookup without a single answer, and
      * ambiguity is all an impersonating card needs. Enforced here rather than
      * by schema, since uniqueness is a property of the set, not of the value.
@@ -1336,7 +1333,7 @@ export class Stack {
                 baseId: family,
                 includeDeleted: true,
                 includeUnlisted: true,
-                ...(filtersContent(this.features) && { content: { [field]: value } }),
+                ...(filtersContent(this.capabilities) && { content: { [field]: value } }),
             },
         }, (r) => r.id !== excludeId && r.content[field] === value);
         if (clash) {
@@ -1476,19 +1473,20 @@ export class Stack {
     }
     /**
      * Store bytes and create an _attachment@1 metadata record (owner-
-     * attributed, no entityId), returning that record — `content.fileId`
+     * attributed, no createdBy), returning that record — `content.fileId`
      * addresses the bytes, `id` addresses the metadata. Delegates to the
      * adapter's atomic putAttachmentWithMetadata() when implemented, trusting
      * the returned record as backend-authoritative; otherwise falls back to
      * bytes-then-create(). See docs/spec/wire-format.md § Attachments.
      */
-    async putAttachment(data, mimeType, filename, appId) {
+    async putAttachment(data, opts) {
+        const { mimeType, filename, appId } = opts;
         this.assertOpen();
-        assertAttachmentSize(data.byteLength, this.features.limits.attachmentBytes);
+        assertAttachmentSize(data.byteLength, this.capabilities.limits.attachmentBytes);
         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);
+            const record = await this.adapter.putAttachmentWithMetadata(data, opts);
             // The one emission with no journal half of its own: the far side
             // wrote the record, so it appended the entry in that same write —
             // the same division saveVersion() follows over this adapter. See
@@ -1496,7 +1494,7 @@ export class Stack {
             this.announce(new PendingChange('create'), record);
             return record;
         }
-        const fileId = await this.adapter.putAttachment(data);
+        const fileId = await this.adapter.putBlob(data);
         return this.create(`${SYSTEM_TYPES.ATTACHMENT}@1`, {
             fileId,
             mimeType,
@@ -1506,7 +1504,7 @@ export class Stack {
     }
     async getAttachment(fileId) {
         this.assertOpen();
-        return this.adapter.getAttachment(fileId);
+        return this.adapter.getBlob(fileId);
     }
     /**
      * Every `_attachment` record describing `fileId`, earliest-recorded
@@ -1527,7 +1525,7 @@ export class Stack {
                 baseId: SYSTEM_TYPES.ATTACHMENT,
                 includeDeleted: true,
                 includeUnlisted: true,
-                ...(filtersContent(this.features) && { content: { fileId } }),
+                ...(filtersContent(this.capabilities) && { content: { fileId } }),
             },
         });
         return results
@@ -1559,7 +1557,7 @@ export class Stack {
             deletedRecords = await this.adapter.deleteUnreferencedAttachmentRecords(fileId, await this.attachmentTypeIds());
             const at = new Date();
             for (const record of deletedRecords) {
-                this.announce(new PendingChange('hard-delete', { actor: Stack.actorFrom(opts) }), record, at);
+                this.announce(new PendingChange('purge', { actor: normalizeActor(opts.actor) }), record, at);
             }
         }
         else {
@@ -1567,13 +1565,13 @@ export class Stack {
         }
         if (!deletedRecords.length) {
             try {
-                await this.adapter.getAttachment(fileId);
+                await this.adapter.getBlob(fileId);
             }
             catch {
                 throw new StackNotFoundError(`Attachment not found: "${fileId}"`);
             }
         }
-        await this.adapter.deleteAttachment(fileId);
+        await this.adapter.deleteBlob(fileId);
     }
     /**
      * Non-atomic fallback for adapters that don't implement
@@ -1585,7 +1583,7 @@ export class Stack {
         // must find its attachments intact on undelete or relisting. See
         // docs/spec/attachments.md § Deleting attachments.
         const refResult = await this.query({
-            filter: { attachmentFileId: fileId, includeDeleted: true, includeUnlisted: true },
+            filter: { referencesFileId: fileId, includeDeleted: true, includeUnlisted: true },
             limit: 1,
         });
         if (refResult.records.length > 0) {
@@ -1595,7 +1593,7 @@ export class Stack {
         // too — none of it may be left pointing at deleted bytes.
         const metaRecords = await this.getAttachmentRecords(fileId);
         for (const record of metaRecords) {
-            await this.delete(record.id, { hard: true, ...opts });
+            await this.delete(record.id, { purge: true, ...opts });
         }
         return metaRecords;
     }
@@ -1626,19 +1624,19 @@ export class Stack {
             }
         }
         // Bare-bytes orphans: blobs with zero metadata records, only
-        // discoverable if the blob adapter implements listFiles().
+        // discoverable if the blob adapter implements listBlobs().
         const blobByFile = new Map();
-        if (this.adapter.listFiles) {
-            for (const file of await this.adapter.listFiles()) {
+        if (this.adapter.listBlobs) {
+            for (const file of await this.adapter.listBlobs()) {
                 blobByFile.set(file.fileId, { modifiedAt: file.modifiedAt.getTime(), size: file.size });
             }
         }
         const candidateFileIds = new Set([...metaByFile.keys(), ...blobByFile.keys()]);
-        const deleted = [];
+        const deletedFileIds = [];
         let reclaimedBytes = 0;
         for (const fileId of candidateFileIds) {
             const refResult = await this.query({
-                filter: { attachmentFileId: fileId, includeDeleted: true, includeUnlisted: true },
+                filter: { referencesFileId: fileId, includeDeleted: true, includeUnlisted: true },
                 limit: 1,
             });
             if (refResult.records.length > 0)
@@ -1650,12 +1648,12 @@ export class Stack {
                 continue;
             const size = meta?.size ?? blob?.size ?? 0;
             if (dryRun) {
-                deleted.push(fileId);
+                deletedFileIds.push(fileId);
                 reclaimedBytes += size;
                 continue;
             }
             try {
-                await this.deleteAttachment(fileId, { updatedBy: opts.updatedBy });
+                await this.deleteAttachment(fileId, { actor: opts.actor });
             }
             catch (err) {
                 // Raced with a new reference, or another sweep/call already removed
@@ -1664,10 +1662,10 @@ export class Stack {
                     continue;
                 throw err;
             }
-            deleted.push(fileId);
+            deletedFileIds.push(fileId);
             reclaimedBytes += size;
         }
-        return { deleted, reclaimedBytes };
+        return { deletedFileIds, reclaimedBytes };
     }
     // -------------------------------------------------------
     // Lifecycle
@@ -1708,7 +1706,7 @@ export class Stack {
      *
      * The subscription's own filter goes to the relay rather than being
      * applied on the way back: the emitter at the far end holds the record,
-     * so it can answer `entityId` and `parentId`, which the envelope
+     * so it can answer `createdBy` and `parentId`, which the envelope
      * deliberately does not carry. That is also why a relay is opened per
      * subscription rather than shared.
      */
@@ -1729,10 +1727,7 @@ export class Stack {
             void stop();
         };
     }
-    /**
-     * Whether changes reach this stack from elsewhere. Public only so
-     * ScopedStack can refuse a scope it cannot honor; not an app-facing API.
-     */
+    /** Whether changes reach this stack from elsewhere. */
     get relaysChanges() {
         return typeof this.adapter.subscribeChanges === 'function';
     }
@@ -1767,23 +1762,20 @@ export class Stack {
             await this.adapter.close?.();
         }
     }
-    /**
-     * Throws once close() has run. Public only so ScopedStack can gate the
-     * one path it takes to the adapter directly; not an app-facing API.
-     */
+    /** Throws once close() has run. */
     assertOpen() {
         if (this.closed)
-            throw new StackClosedError();
+            throw new UseAfterCloseError();
     }
     // -------------------------------------------------------
     // Grants
     // -------------------------------------------------------
     /**
-     * Create _grant records authorizing entities to act on records of
-     * specific types. The target is the grantee the record carries:
-     * `{ kind: 'entity' }` for one DID, `{ kind: 'group' }` for a `_group`
-     * Record's roster at a role, `{ kind: 'authenticated' }` for any
-     * authenticated entity.
+     * Create a _grant record authorizing `grantee` to take `actions` on
+     * records of `typeId`: `{ kind: 'entity' }` for one DID, `{ kind: 'group' }`
+     * for a `_group` Record's roster at a role, `{ kind: 'authenticated' }` for
+     * any authenticated entity. The type-level mirror of grantAccess() —
+     * subject first, grantee inside the element.
      *
      * 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
@@ -1793,22 +1785,19 @@ 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.grantee, not record.entityId. See
+     * `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.
      */
-    async grant(target, grants) {
+    async grantType(typeOrBaseId, grant) {
         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,
-                grantee: target,
-            }));
-        }
-        return records;
+        validateGrantTarget(grant.grantee);
+        this.checkGrantValid(typeOrBaseId, grant.actions);
+        return this.create(`${SYSTEM_TYPES.GRANT}@1`, {
+            typeId: typeOrBaseId,
+            actions: grant.actions,
+            grantee: grant.grantee,
+        });
     }
     /**
      * List _grant records. Omit `query` for all grants;
@@ -1819,12 +1808,12 @@ export class Stack {
      * (ones naming them, ones naming a group they belong to at a role they
      * hold, plus every default grant) — the same resolution hasGrant() uses.
      *
-     * Every arm but `entity` answers identity — what `grant()` would have
+     * Every arm but `entity` answers identity — what `grantType()` would have
      * written with the same argument. The `entity` arm answers coverage, so
-     * its result is not a preview of what `revoke()` would withdraw.
+     * its result is not a preview of what `revokeType()` would withdraw.
      * See docs/spec/access-control.md § Type-level grants.
      */
-    async listGrants(query) {
+    async listTypeGrants(query) {
         this.assertOpen();
         if (query !== undefined)
             validateGrantTarget(query, true);
@@ -1853,90 +1842,78 @@ export class Stack {
         return result;
     }
     /**
-     * The inverse of grant(): soft-deletes _grant records matching `target`
-     * and each `{ typeId, actions }` pair, at the same granularity grant()
-     * writes — the grantee is matched whole, role included. A soft delete
-     * like any other — the owner can undelete a revocation.
+     * The inverse of grantType(): soft-deletes the _grant records on
+     * `typeOrBaseId`'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.
      *
-     * Returns the grants it withdrew, as they stood, so a revocation that
-     * matched nothing says so rather than passing in silence. An empty result
-     * is not an error — a grant already withdrawn or never written is the
-     * ordinary case, and re-running a revocation has to stay safe.
-     * See docs/spec/access-control.md § Type-level grants.
+     * Returns the grants it withdrew, as they stood: an array, where
+     * revokeAccess() returns one Record, because one target can match several
+     * _grant records. An empty result is not an error — re-running a
+     * revocation has to stay safe. See
+     * docs/spec/access-control.md § Listing and revoking.
      */
-    async revoke(target, grants) {
+    async revokeType(typeOrBaseId, grant) {
         this.assertOpen();
-        validateGrantTarget(target);
-        const revoked = [];
+        validateGrantTarget(grant.grantee);
+        const familyId = baseIdOf(typeOrBaseId);
+        const actionSet = new Set(grant.actions);
         const all = await loadGrantRecords((q) => this.query(q));
-        for (const g of grants) {
-            const familyId = baseIdOf(g.typeId);
-            const actionSet = new Set(g.actions);
-            const matches = all.filter((r) => {
-                const c = r.content;
-                // Establishes the family and that `actions` is a list, so the exact
-                // match below reads a real one. Matched against the stored list
-                // rather than the reach, so a grant carrying an action this
-                // vocabulary drops is not withdrawn by a target that omits it.
-                const reach = grantReach(c);
-                if (!reach || reach.familyId !== familyId)
-                    return false;
-                if (!matchesGrantTarget(c, target))
-                    return false;
-                return c.actions.length === actionSet.size && c.actions.every((a) => actionSet.has(a));
-            });
-            for (const match of matches) {
-                await this.delete(match.id);
-                revoked.push(match);
-            }
-        }
-        return revoked;
+        const matches = all.filter((r) => {
+            const c = r.content;
+            // Establishes the family and that `actions` is a list, so the exact
+            // match below reads a real one. Matched against the stored list
+            // rather than the reach, so a grant carrying an action this
+            // vocabulary drops is not withdrawn by a target that omits it.
+            const reach = grantReach(c);
+            if (!reach || reach.familyId !== familyId)
+                return false;
+            if (!matchesGrantTarget(c, grant.grantee))
+                return false;
+            return c.actions.length === actionSet.size && c.actions.every((a) => actionSet.has(a));
+        });
+        for (const match of matches)
+            await this.delete(match.id);
+        return matches;
     }
     // -------------------------------------------------------
     // Private helpers
     // -------------------------------------------------------
     /**
-     * Validates the whole grant batch before any record is created, so a bad
-     * entry fails clean rather than leaving a partial set written. 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, typeIds must be well-formed,
+     * and the _grant/_config families are refused — see
+     * docs/spec/access-control.md § Type-level grants.
      */
-    checkGrantsValid(grants) {
+    checkGrantValid(typeId, actions) {
         const errors = [];
-        grants.forEach((g, i) => {
-            g.actions.forEach((action, j) => {
-                if (!GRANT_ACTION_SET.has(action)) {
-                    errors.push({
-                        path: `grants[${i}].actions[${j}]`,
-                        message: `Unknown grant action "${action}"`,
-                    });
-                }
+        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")`,
             });
-            if (!isWellFormedTypeId(g.typeId)) {
-                errors.push({
-                    path: `grants[${i}].typeId`,
-                    message: `"${g.typeId}" is not a well-formed baseId or versioned TypeId (expected "baseId" or "baseId@version")`,
-                });
+        }
+        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`,
+            });
+        }
+        actions.forEach((action, j) => {
+            if (grantConveys(actions, action))
                 return;
-            }
-            if (UNGRANTABLE_SYSTEM_TYPES.has(baseIdOf(g.typeId))) {
-                const refused = [...UNGRANTABLE_SYSTEM_TYPES].join(', ');
-                errors.push({
-                    path: `grants[${i}].typeId`,
-                    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`,
-                });
+            const companions = READ_COMPANIONS.get(action);
+            if (!companions)
+                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`,
             });
         });
         if (errors.length > 0) {
@@ -1944,58 +1921,82 @@ export class Stack {
         }
     }
     async seedSystemTypes() {
-        await this.defineType(`${SYSTEM_TYPES.CONFIG}@1`, 'Config', {
-            entityId: { kind: 'string', required: true },
-            // Optional passthrough app metadata — see ConfigContent.timezone.
-            timezone: { kind: 'string' },
+        await this.defineType({
+            id: `${SYSTEM_TYPES.CONFIG}@1`,
+            name: 'Config',
+            schema: {
+                entityId: { kind: 'string', required: true },
+                // Optional passthrough app metadata — see ConfigContent.timezone.
+                timezone: { kind: 'string' },
+            },
         });
-        await this.defineType(`${SYSTEM_TYPES.ENTITY}@1`, 'Entity', {
-            did: { kind: 'string', required: true },
-            name: { kind: 'string', required: true },
-            handle: { kind: 'string' },
+        await this.defineType({
+            id: `${SYSTEM_TYPES.ENTITY}@1`,
+            name: 'Entity',
+            schema: {
+                did: { kind: 'string', required: true },
+                name: { kind: 'string', required: true },
+                handle: { kind: 'string' },
+            },
         });
-        await this.defineType(`${SYSTEM_TYPES.APP}@1`, 'App', {
-            appId: { kind: 'string', required: true },
-            name: { kind: 'string', required: true },
-            version: { kind: 'string' },
-            did: { kind: 'string' },
+        await this.defineType({
+            id: `${SYSTEM_TYPES.APP}@1`,
+            name: 'App',
+            schema: {
+                appId: { kind: 'string', required: true },
+                name: { kind: 'string', required: true },
+                version: { kind: 'string' },
+                did: { kind: 'string' },
+            },
         });
-        await this.defineType(`${SYSTEM_TYPES.GROUP}@1`, 'Group', {
-            name: { kind: 'string', required: true },
-            handle: { kind: 'string' },
-            stackUrl: { kind: 'string' },
+        await this.defineType({
+            id: `${SYSTEM_TYPES.GROUP}@1`,
+            name: 'Group',
+            schema: {
+                name: { kind: 'string', required: true },
+                handle: { kind: 'string' },
+                stackUrl: { kind: 'string' },
+            },
         });
-        await this.defineType(`${SYSTEM_TYPES.GRANT}@1`, 'Grant', {
-            typeId: { 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
-            // as a grant to every authenticated entity. The arms differ in which
-            // fields they carry, which a schema cannot express — evaluation reads
-            // the `kind` and confers nothing on one it does not recognize.
-            // See docs/spec/access-control.md § Type-level grants.
-            grantee: {
-                kind: 'object',
-                required: true,
-                properties: {
-                    kind: { kind: 'string', required: true },
-                    entityId: { kind: 'string' },
-                    groupId: { kind: 'string' },
-                    role: { kind: 'string' },
+        await this.defineType({
+            id: `${SYSTEM_TYPES.GRANT}@1`,
+            name: 'Grant',
+            schema: {
+                typeId: { 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
+                // as a grant to every authenticated entity. The arms differ in which
+                // fields they carry, which a schema cannot express — evaluation reads
+                // the `kind` and confers nothing on one it does not recognize.
+                // See docs/spec/access-control.md § Type-level grants.
+                grantee: {
+                    kind: 'object',
+                    required: true,
+                    properties: {
+                        kind: { kind: 'string', required: true },
+                        entityId: { kind: 'string' },
+                        groupId: { kind: 'string' },
+                        role: { kind: 'string' },
+                    },
                 },
             },
         });
-        await this.defineType(`${SYSTEM_TYPES.ATTACHMENT}@1`, 'Attachment', {
-            // Deliberately `string`, not `file-ref`: attachmentFileId matching
-            // (deleteAttachment()/collectAttachmentGarbage()'s reference scan) is
-            // schema-driven, so a `file-ref` fileId here would make every
-            // metadata record its own file's reference — nothing would ever be
-            // deletable or collectible. See docs/spec/attachments.md § Deleting
-            // attachments / Garbage collection.
-            fileId: { kind: 'string', required: true },
-            mimeType: { kind: 'string', required: true },
-            size: { kind: 'number', required: true },
-            filename: { kind: 'string' },
+        await this.defineType({
+            id: `${SYSTEM_TYPES.ATTACHMENT}@1`,
+            name: 'Attachment',
+            schema: {
+                // Deliberately `string`, not `file-ref`: referencesFileId matching
+                // (deleteAttachment()/collectAttachmentGarbage()'s reference scan) is
+                // schema-driven, so a `file-ref` fileId here would make every
+                // metadata record its own file's reference — nothing would ever be
+                // deletable or collectible. See docs/spec/attachments.md § Deleting
+                // attachments / Garbage collection.
+                fileId: { kind: 'string', required: true },
+                mimeType: { kind: 'string', required: true },
+                size: { kind: 'number', required: true },
+                filename: { kind: 'string' },
+            },
         });
     }
     /**
@@ -2013,16 +2014,15 @@ export class Stack {
      * The options every version-bumping adapter write carries: the `ifVersion`
      * precondition, the prior-state snapshot that has to land in the same
      * atomic write, and who to attribute the change to. Taken together so a
-     * new mutating verb cannot quietly omit one — `updatedVia` most of all,
-     * whose absence reads as an undelegated write.
+     * new mutating verb cannot quietly omit one — the actor's `principalId`
+     * most of all, whose absence reads as an undelegated write.
      * See docs/spec/versioning.md § Version history.
      */
     writeOptions(existing, opts) {
         return {
-            expectedVersion: opts.ifVersion,
+            ifVersion: opts.ifVersion,
             snapshot: this.buildVersionSnapshot(existing),
-            updatedBy: opts.updatedBy,
-            updatedVia: opts.updatedVia,
+            actor: normalizeActor(opts.actor),
         };
     }
     /**
@@ -2040,9 +2040,8 @@ export class Stack {
             typeId: record.typeId,
             content: record.content,
             updatedAt: record.updatedAt,
-            ...(record.entityId && { entityId: record.entityId }),
+            ...(record.createdBy && { createdBy: record.createdBy }),
             ...(record.updatedBy && { updatedBy: record.updatedBy }),
-            ...(record.updatedVia && { updatedVia: record.updatedVia }),
         };
     }
 }