@haverstack/core 0.39.0 → 0.41.0

package/dist/stack.js

@@ -14,22 +14,24 @@
  * 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 { claimedFamilies, familyStanding, grantIsRequest, installAppLink, installGrantLink, installReader, linkedIds, namespaceOf, ownTypeIds, planFingerprint, sameRequest, snapshotManifest, validateInstall, INSTALL_APP_LABEL, INSTALL_GRANT_LABEL, } from './install.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 +237,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".`);
@@ -373,15 +377,25 @@ export class Stack {
      * the only way disk state changes version. Sweeps soft-deleted records
      * too, validates each result before writing, and aborts on the first
      * validation failure. See docs/spec/data-model.md § Type migrations.
+     *
+     * `sweep: 'listed'` is for a contained app over `APIAdapter`, which can
+     * neither enumerate unlisted records nor read a deleted one's content:
+     * it migrates live, listed records and counts the deleted ones it passed
+     * over in `skipped`. See docs/spec/apps.md § Migrating an installed app's types.
      */
-    async migrateAll(baseId) {
+    async migrateAll(baseId, opts = {}) {
         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) {
             throw new StackMigrationError(`migrateAll: no registered types found for baseId "${baseId}"`);
         }
+        const listedOnly = opts.sweep === 'listed';
         let migrated = 0;
+        let skipped = 0;
         for (const typeId of familyTypeIds) {
             const latestId = this.latestTypeId(typeId);
             if (typeId === latestId)
@@ -396,11 +410,15 @@ export class Stack {
             let cursor;
             do {
                 const result = await this.adapter.queryRecords({
-                    filter: { typeId, includeDeleted: true, includeUnlisted: true },
+                    filter: { typeId, includeDeleted: true, includeUnlisted: !listedOnly },
                     limit: 100,
                     cursor,
                 });
                 for (const record of result.records) {
+                    if (listedOnly && record.deletedAt) {
+                        skipped++;
+                        continue;
+                    }
                     // Same checked path commitMigration() takes — a migration
                     // function is no more entitled to move a DID binding or repoint
                     // an attachment than a request body is. No ifVersion: a batch
@@ -411,28 +429,18 @@ export class Stack {
                 cursor = result.cursor ?? undefined;
             } while (cursor);
         }
-        return { migrated };
+        return { migrated, skipped };
     }
-    // -------------------------------------------------------
-    // 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 +461,8 @@ export class Stack {
             ...validateContentKeys(content),
             ...validateContent(content, type.schema),
             ...validateGrantee(typeId, content),
+            ...validateGrantBaseId(typeId, content),
+            ...validateInstall(typeId, content),
             ...validateAssociations(opts.permissions, 'permissions'),
             ...validatePermissions(opts.permissions),
             ...validateAssociations(opts.associations),
@@ -564,35 +574,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 +649,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 +706,8 @@ export class Stack {
             const contentErrors = [
                 ...validateContent(merged, type.schema),
                 ...validateGrantee(existing.typeId, merged),
+                ...validateGrantBaseId(existing.typeId, merged),
+                ...validateInstall(existing.typeId, merged),
             ];
             if (contentErrors.length > 0)
                 throw new StackValidationError(contentErrors);
@@ -746,7 +754,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 +764,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, 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 revokeAccess(id, permission, opts = {}) {
+    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 +856,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 +1031,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 +1049,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 +1080,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 +1115,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 +1128,8 @@ export class Stack {
         const errors = [
             ...validateContent(target.content, type.schema),
             ...validateGrantee(target.typeId, target.content),
+            ...validateGrantBaseId(target.typeId, target.content),
+            ...validateInstall(target.typeId, target.content),
         ];
         if (errors.length > 0) {
             throw new StackValidationError(errors);
@@ -1206,17 +1195,20 @@ 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),
+            ...validateInstall(toTypeId, content),
         ];
         if (errors.length > 0) {
             throw new StackValidationError(errors);
@@ -1667,22 +1659,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 +1770,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 +1818,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 +1827,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 +1838,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) => {
@@ -1878,32 +1865,313 @@ export class Stack {
         return matches;
     }
     // -------------------------------------------------------
+    // App installs
+    // -------------------------------------------------------
+    /**
+     * What applying `manifest` for the key `did` would change, for the owner
+     * to review before installApp(). Writes nothing. Refuses outright what no
+     * approval could make valid: a type outside the app's own namespace and
+     * the commons, a request the grant rules refuse, or a `did` already
+     * registered to a different app. See docs/spec/apps.md § Plan, then apply.
+     */
+    async planInstall(submitted, opts) {
+        this.assertOpen();
+        const { did } = opts;
+        const manifest = snapshotManifest(submitted);
+        this.checkManifest(manifest, did);
+        const installs = await this.loadInstalls();
+        const existing = installs.find((r) => r.content.appId === manifest.appId) ?? null;
+        const ownVersions = ownTypeIds(manifest);
+        const ownFamilies = new Set(ownVersions.map(baseIdOf));
+        const card = await this.findAppCard(did);
+        if (card && card.content.appId !== manifest.appId) {
+            throw new StackConflictError(`${did} is registered to "${card.content.appId}", not "${manifest.appId}"`);
+        }
+        const claimed = existing ? claimedFamilies(existing.content) : new Set();
+        const defined = new Set(existing?.content.defines ?? []);
+        const prior = existing?.content.requests ?? [];
+        const foreignRequests = [];
+        for (const r of manifest.requests) {
+            const standing = familyStanding(r.baseId, manifest.appId);
+            if (standing === 'own')
+                continue;
+            const owner = standing === 'foreign'
+                ? namespaceOf(r.baseId)
+                : standing === 'commons'
+                    ? 'commons'
+                    : 'system';
+            foreignRequests.push({ ...r, owner });
+        }
+        const typeChanges = [];
+        for (const t of manifest.types) {
+            const current = await this.getTypeCached(t.id);
+            if (!current)
+                typeChanges.push({ id: t.id, change: 'new' });
+            else if (current.schemaHash !== (await hashSchema(t.schema))) {
+                // Refused here, not left to defineType(): installApp() defines types one
+                // by one, so a drift found there leaves the earlier ones written.
+                const violations = diffSchemas(current.schema, t.schema);
+                if (violations.length > 0)
+                    throw new StackSchemaDriftError(t.id, violations);
+                typeChanges.push({ id: t.id, change: 'schema' });
+            }
+            else if (current.name !== t.name)
+                typeChanges.push({ id: t.id, change: 'name' });
+        }
+        const linkedKeys = [];
+        for (const id of existing ? linkedIds(existing, INSTALL_APP_LABEL) : []) {
+            const key = (await this.get(id))?.content?.did;
+            if (typeof key === 'string')
+                linkedKeys.push(key);
+        }
+        return {
+            manifest,
+            did,
+            existing,
+            newFamilies: [...ownFamilies].filter((f) => !claimed.has(f)),
+            newVersions: ownVersions.filter((id) => !defined.has(id)),
+            requestsAdded: manifest.requests.filter((r) => !prior.some((p) => sameRequest(p, r))),
+            requestsRemoved: prior.filter((p) => !manifest.requests.some((r) => sameRequest(p, r))),
+            foreignRequests,
+            typeChanges,
+            newKey: !existing ||
+                !card ||
+                card.deletedAt !== undefined ||
+                !linkedIds(existing, INSTALL_APP_LABEL).includes(card.id),
+            linkedKeys,
+        };
+    }
+    /**
+     * Apply an approved plan: define the manifest's types, register the
+     * key's `_app` card if it has none, write the `_install` Record, and
+     * bring every linked key's grants to exactly what the manifest requests.
+     * Refuses a plan the stack has moved on from with StackConflictError, so
+     * what is applied is what was approved. Reinstalls a soft-deleted
+     * install. See docs/spec/apps.md § Plan, then apply.
+     */
+    async installApp(plan) {
+        this.assertOpen();
+        const fresh = await this.planInstall(plan.manifest, { did: plan.did });
+        if (planFingerprint(fresh) !== planFingerprint(plan)) {
+            throw new StackConflictError(`The stack changed since the install of "${plan.manifest.appId}" was planned; plan it again`);
+        }
+        const { manifest, did, existing } = fresh;
+        for (const type of manifest.types)
+            await this.defineType(type);
+        const card = await this.ensureAppCard(manifest, did);
+        const defines = [...new Set([...(existing?.content.defines ?? []), ...ownTypeIds(manifest)])];
+        const requests = manifest.requests.map((r) => ({
+            baseId: r.baseId,
+            actions: [...r.actions],
+        }));
+        let install;
+        if (!existing) {
+            install = await this.create(`${SYSTEM_TYPES.INSTALL}@1`, {
+                appId: manifest.appId,
+                name: manifest.name,
+                ...(manifest.version !== undefined && { version: manifest.version }),
+                defines,
+                requests,
+            }, { associations: [installAppLink(card.id)] });
+        }
+        else {
+            const current = existing.deletedAt ? await this.undelete(existing.id) : existing;
+            install = await this.patchContent(existing.id, { name: manifest.name, version: manifest.version ?? null, defines, requests }, { ifVersion: current.version });
+            if (!linkedIds(install, INSTALL_APP_LABEL).includes(card.id)) {
+                install = await this.associate(install.id, [installAppLink(card.id)]);
+            }
+        }
+        return (await this.reconcileInstallGrants(install));
+    }
+    /**
+     * Withdraw every grant an install produced and soft-delete it. The app's
+     * records and `_app` cards stay: the data is the owner's, and the cards
+     * are what its records' attribution resolves through. Returns the
+     * install's tombstone. See docs/spec/apps.md § Uninstalling.
+     */
+    async uninstallApp(appId) {
+        this.assertOpen();
+        const install = (await this.loadInstalls()).find((r) => r.content.appId === appId && !r.deletedAt);
+        if (!install)
+            throw new StackNotFoundError(`No install for "${appId}"`);
+        const edits = [];
+        for (const id of linkedIds(install, INSTALL_GRANT_LABEL)) {
+            if (await this.get(id))
+                await this.delete(id);
+            edits.push({ op: 'remove', association: installGrantLink(id) });
+        }
+        if (edits.length > 0)
+            await this.amendAssociations(install.id, edits);
+        const { record } = await this.deleteAndReturn(install.id);
+        return record;
+    }
+    /** A manifest's own shape, and every request held to grantType()'s rules. */
+    checkManifest(manifest, did) {
+        const errors = [];
+        if (typeof did !== 'string' || !did.startsWith('did:')) {
+            errors.push({ path: 'did', message: 'Expected a DID' });
+        }
+        if (typeof manifest.appId !== 'string' || manifest.appId === '') {
+            errors.push({ path: 'appId', message: 'Expected a non-empty appId' });
+        }
+        if (typeof manifest.name !== 'string' || manifest.name === '') {
+            errors.push({ path: 'name', message: 'Expected a non-empty name' });
+        }
+        const seen = new Set();
+        manifest.types.forEach((t, i) => {
+            if (seen.has(t.id)) {
+                errors.push({ path: `types[${i}].id`, message: `"${t.id}" is listed more than once` });
+            }
+            seen.add(t.id);
+            const schemaPath = `types[${i}].schema`;
+            const shapeErrors = validateSchemaShape(t.schema, schemaPath);
+            errors.push(...shapeErrors);
+            if (shapeErrors.length === 0) {
+                const schema = t.schema;
+                for (const e of validateSchemaReservedNames(schema)) {
+                    errors.push({ ...e, path: `${schemaPath}.${e.path}` });
+                }
+                validateSchemaFieldNames(schema, schemaPath, errors);
+            }
+            const parsed = parseTypeId(t.id);
+            if (!parsed) {
+                errors.push({ path: `types[${i}].id`, message: 'Expected a versioned TypeId' });
+            }
+            else {
+                const standing = familyStanding(parsed.baseId, manifest.appId);
+                if (standing === 'system' || standing === 'foreign') {
+                    errors.push({
+                        path: `types[${i}].id`,
+                        message: standing === 'system'
+                            ? `"${parsed.baseId}" is a system type; no app can define it`
+                            : `"${parsed.baseId}" is outside the namespace "${manifest.appId}"; request access to it instead of defining it`,
+                    });
+                }
+            }
+        });
+        if (errors.length > 0)
+            throw new StackValidationError(errors);
+        for (const r of manifest.requests)
+            this.checkGrantValid(r.baseId, r.actions);
+    }
+    /** Every `_install` Record, deleted and unlisted included — a deleted install keeps its claims. */
+    async loadInstalls() {
+        const records = await queryAllPages((q) => this.query(q), {
+            filter: { baseId: SYSTEM_TYPES.INSTALL, includeDeleted: true, includeUnlisted: true },
+        });
+        return records;
+    }
+    /** The `_app` card claiming `did`, deleted and unlisted included. */
+    findAppCard(did) {
+        return findFirstMatch((q) => this.query(q), {
+            filter: {
+                baseId: SYSTEM_TYPES.APP,
+                includeDeleted: true,
+                includeUnlisted: true,
+                ...(filtersContent(this.capabilities) && { content: { did } }),
+            },
+        }, (r) => r.content.did === did);
+    }
+    /** The key's `_app` card, created or undeleted as needed. */
+    async ensureAppCard(manifest, did) {
+        const card = await this.findAppCard(did);
+        if (!card) {
+            return this.create(`${SYSTEM_TYPES.APP}@1`, {
+                appId: manifest.appId,
+                name: manifest.name,
+                ...(manifest.version !== undefined && { version: manifest.version }),
+                did,
+            });
+        }
+        return card.deletedAt ? this.undelete(card.id) : card;
+    }
+    /**
+     * Make the grants linked to `install` exactly its `requests`, once per
+     * live linked key: withdraw any that no longer match, write any missing,
+     * and drop links to grants that are gone.
+     */
+    async reconcileInstallGrants(install) {
+        const { requests } = install.content;
+        const dids = [];
+        for (const id of linkedIds(install, INSTALL_APP_LABEL)) {
+            const did = (await this.get(id))?.content?.did;
+            if (typeof did === 'string')
+                dids.push(did);
+        }
+        const edits = [];
+        const held = [];
+        for (const id of linkedIds(install, INSTALL_GRANT_LABEL)) {
+            const grant = await this.get(id);
+            const content = grant?.content;
+            const wanted = content !== undefined &&
+                baseIdOf(grant.typeId) === SYSTEM_TYPES.GRANT &&
+                dids.some((did) => requests.some((r) => grantIsRequest(content, r, did)));
+            if (wanted) {
+                held.push(content);
+                continue;
+            }
+            if (grant)
+                await this.delete(id);
+            edits.push({ op: 'remove', association: installGrantLink(id) });
+        }
+        for (const did of dids) {
+            for (const r of requests) {
+                if (held.some((g) => grantIsRequest(g, r, did)))
+                    continue;
+                const grant = await this.grantType(r.baseId, {
+                    actions: r.actions,
+                    grantee: { kind: 'entity', entityId: did },
+                });
+                held.push(grant.content);
+                edits.push({ op: 'add', association: installGrantLink(grant.id) });
+            }
+        }
+        let result = edits.length > 0 ? await this.amendAssociations(install.id, edits) : install;
+        // Each linked key may read its own install, which is how an app learns
+        // what was approved; a key of this app no longer linked may not.
+        // See docs/spec/apps.md § Over the wire.
+        const appKeys = new Set((await queryAllPages((q) => this.query(q), {
+            filter: { baseId: SYSTEM_TYPES.APP, includeDeleted: true, includeUnlisted: true },
+        }))
+            .map((r) => r.content)
+            .filter((c) => c.appId === install.content.appId)
+            .map((c) => c.did));
+        const readerOf = (p) => p.kind === 'permission' && p.label === 'read' && p.grantee.kind === 'entity'
+            ? p.grantee.entityId
+            : null;
+        const current = (result.permissions ?? []).map(readerOf);
+        const access = [
+            ...dids
+                .filter((did) => !current.includes(did))
+                .map((entityId) => ({ op: 'add', association: installReader(entityId) })),
+            ...current
+                .filter((did) => did !== null && appKeys.has(did) && !dids.includes(did))
+                .map((entityId) => ({ op: 'remove', association: installReader(entityId) })),
+        ];
+        if (access.length > 0)
+            result = await this.amendAccess(install.id, access);
+        return result;
+    }
+    // -------------------------------------------------------
     // 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 +2181,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 +2230,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
@@ -1998,6 +2266,27 @@ export class Stack {
                 filename: { kind: 'string' },
             },
         });
+        await this.defineType({
+            id: `${SYSTEM_TYPES.INSTALL}@1`,
+            name: 'Install',
+            schema: {
+                appId: { kind: 'string', required: true },
+                name: { kind: 'string', required: true },
+                version: { kind: 'string' },
+                defines: { kind: 'array', items: { kind: 'string' }, required: true },
+                requests: {
+                    kind: 'array',
+                    required: true,
+                    items: {
+                        kind: 'object',
+                        properties: {
+                            baseId: { kind: 'string', required: true },
+                            actions: { kind: 'array', items: { kind: 'string' }, required: true },
+                        },
+                    },
+                },
+            },
+        });
     }
     /**
      * Fast-fail for the ifVersion precondition using the already-fetched