@haverstack/core 0.27.0 → 0.29.0

package/dist/stack.js

@@ -15,12 +15,12 @@
  */
 import { generateId, generateIdForTimestamp, isValidIdFormat, idTimestamp, MAX_ID_TIMESTAMP, } from './id.js';
 import { hashSchema, isCompatible, parseTypeId, baseIdOf, diffSchemas, isWellFormedTypeId, } from './schema.js';
-import { CONTENT_SEGMENT_METACHARACTERS, SEGMENT_METACHARACTER_RE, validateContent, validateContentKeys, validatePatchValues, validateReservedKeys, validateSchemaFieldNames, } from './validate.js';
+import { CONTENT_SEGMENT_METACHARACTERS, SEGMENT_METACHARACTER_RE, validateContent, validateContentKeys, validatePatchValues, validateReservedKeys, validateSchemaFieldNames, validateSchemaReservedNames, validateSchemaShape, } from './validate.js';
 import { applyMergePatch } from './merge.js';
-import { checkAccess, groupRoleFromAssociations, isOwnerActingAlone, validatePermissions, } from './access.js';
+import { checkAccess, groupRoleFromAssociations, hasGroupAdmin, isGroupAdminAssociation, isOwnerActingAlone, validatePermissions, } from './access.js';
 import { compareRecordedAttachments } from './attachment-download.js';
 import { ChangeEmitter, RelayDelivery, Subscription, buildEmission, matchesFilter, passesUnlistedBoundary, } from './changes.js';
-import { SYSTEM_TYPES, GRANT_ACTIONS } from './types.js';
+import { SYSTEM_TYPES, GRANT_ACTIONS, RECORD_CHANGE_KEYS } from './types.js';
 // -------------------------------------------------------
 // Supporting types
 // -------------------------------------------------------
@@ -532,7 +532,7 @@ function assertAttachmentSize(byteLength, attachmentBytes) {
 }
 /**
  * The content half of the same pre-check, on Stack.create() and
- * Stack.update(). Local adapters declare `limits.contentBytes: null` and skip
+ * Stack.mutate(). Local adapters declare `limits.contentBytes: null` and skip
  * the serialization entirely; only a server declares a ceiling, and its
  * own request-size limit stays authoritative — this just spares an app the
  * round trip and gives it a typed failure instead of a 413 it has to
@@ -657,6 +657,20 @@ const DEFAULT_GC_GRACE_MS = 24 * 60 * 60 * 1000;
  * pagination cursor a StackQueryError rather than a content-validation
  * failure. See StackQueryError's doc comment.
  */
+/**
+ * The same format rule applied to a `parentId` a caller names. Separate
+ * from validateRecordId() only for its message: the id under discussion is
+ * the destination, not the record being written, and a shared message would
+ * report the wrong one. See docs/spec/data-model.md § Reparenting.
+ */
+function validateParentId(parentId) {
+    if (parentId.startsWith(RESERVED_ID_PREFIX)) {
+        throw new StackQueryError(`Invalid parentId "${parentId}": uses the reserved "${RESERVED_ID_PREFIX}" prefix.`);
+    }
+    if (!isValidIdFormat(parentId)) {
+        throw new StackQueryError(`Invalid parentId "${parentId}": expected 12 lowercase Crockford base-32 characters.`);
+    }
+}
 function validateRecordId(id) {
     if (id.startsWith(RESERVED_ID_PREFIX)) {
         throw new StackQueryError(`ID "${id}" uses the reserved "${RESERVED_ID_PREFIX}" prefix.`);
@@ -840,7 +854,7 @@ export class Stack {
     /**
      * Announce a mutation that has already been persisted. Called after the
      * adapter write resolves and before the mutating method settles, so
-     * `await stack.update(...)` guarantees subscribers have been notified —
+     * `await stack.mutate(...)` guarantees subscribers have been notified —
      * and nothing about work they deferred. A handler cannot fail the write:
      * there is nothing left to fail. See docs/spec/events.md § Handlers.
      */
@@ -970,7 +984,17 @@ export class Stack {
         const priorMax = this.maxDefinedVersion.get(parsed.baseId) ?? 0;
         if (parsed.version > priorMax)
             this.maxDefinedVersion.set(parsed.baseId, parsed.version);
-        const nameErrors = validateSchemaFieldNames(schema);
+        // Shape first: the name checks and hashSchema() below both read the
+        // schema as a well-formed one, and a schema off the wire is parsed
+        // JSON that no compiler has seen.
+        const shapeErrors = validateSchemaShape(schema);
+        if (shapeErrors.length > 0) {
+            throw new StackValidationError(shapeErrors);
+        }
+        const nameErrors = [
+            ...validateSchemaReservedNames(schema),
+            ...validateSchemaFieldNames(schema),
+        ];
         if (nameErrors.length > 0) {
             throw new StackValidationError(nameErrors);
         }
@@ -1193,6 +1217,13 @@ export class Stack {
             if (opts.createdAt !== undefined) {
                 validateIdTimestampSkew(opts.id, this.idTimestampSkewMsValue, opts.createdAt.getTime(), 'createdAt');
             }
+            // A generated id names nothing, so a create under a parent cannot
+            // close a loop. A caller-supplied one can: existing records may
+            // already point at it, and the chain above the parent can lead back
+            // to it — so the walk is asked only for that combination.
+            // See docs/spec/data-model.md § Reparenting.
+            if (opts.parentId !== undefined)
+                await this.assertNoParentCycle(opts.id, opts.parentId);
         }
         const associations = baseIdOf(typeId) === SYSTEM_TYPES.GROUP
             ? stampGroupAdmin(opts.associations, opts.entityId ?? this.ownerEntityId)
@@ -1210,6 +1241,20 @@ export class Stack {
             (opts.createdAt !== undefined
                 ? generateIdForTimestamp(createdAt.getTime())
                 : generateId(createdAt.getTime()));
+        // An id field a caller supplies is a value or it is absent — never the
+        // empty string, which names nobody. Refused rather than dropped: an
+        // ignored field is the silent-normalization this mapper family was just
+        // fixed for, one layer up.
+        for (const field of ['entityId', 'appId', 'principalId']) {
+            if (opts[field] === '') {
+                throw new StackQueryError(`Invalid ${field}: 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 be one that
+        // exists. This is the read an ordinary create used to skip.
+        if (opts.parentId !== undefined)
+            await this.assertParentExists(id, opts.parentId);
         const record = {
             id,
             typeId,
@@ -1217,10 +1262,14 @@ export class Stack {
             updatedAt,
             content,
             version: 1,
-            ...(opts.parentId && { parentId: opts.parentId }),
-            ...(opts.entityId && { entityId: opts.entityId }),
-            ...(opts.appId && { appId: opts.appId }),
-            ...(opts.principalId && { principalId: opts.principalId }),
+            // Read for presence, not truthiness — every one of these is checked
+            // above, so '' never reaches here and absence is the only thing a
+            // falsy value could mean. Presence says that outright instead of
+            // relying on it.
+            ...(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"
             // true of version 1 as it is of every later version.
@@ -1275,64 +1324,140 @@ export class Stack {
         return opts.presentAt === 'latest' ? this.presentAtLatest(record) : record;
     }
     /**
-     * Update a record's content via JSON Merge Patch: omitted fields are
-     * kept, null removes a field. Validates the merged result against the
-     * record's *current* stored type and never changes typeId (see
-     * docs/spec/data-model.md § Type migrations); snapshots the prior state
-     * to version history. Associations and permissions have their own methods.
+     * Apply a change set — content patch, `parentId`, `permissions`,
+     * `associations`, `unlisted`, in any combination — as one atomic write
+     * producing one version and one snapshot. Keys are read for presence, so
+     * `unlisted: false` and `parentId: null` are changes.
+     *
+     * Every key present is checked against the record as it stands, and a
+     * change set already satisfied in all of them writes nothing and returns
+     * the record unchanged. The ops the change event carries are derived
+     * from that same comparison, so naming an aspect without moving it is
+     * never reported as moving it.
+     *
+     * Content is validated against the record's *current* stored type and
+     * `typeId` never changes (see docs/spec/data-model.md § Type
+     * migrations). See docs/spec/data-model.md § Mutations.
      */
-    async update(id, content, opts = {}) {
+    async mutate(id, changes, opts = {}) {
         this.assertOpen();
+        assertNonEmptyChangeSet(changes);
         const existing = await this.adapter.getRecord(id);
         if (!existing) {
             throw new StackNotFoundError(`Record not found: "${id}"`);
         }
         this.checkIfVersion(existing, opts.ifVersion);
-        const type = await this.getTypeCached(existing.typeId);
-        if (!type) {
-            throw new StackQueryError(`Unknown type: "${existing.typeId}"`);
-        }
-        // Checked on the raw patch, before the merge: a reserved key in a
-        // patch is lost by applyMergePatch rather than stored, and an
-        // `undefined` value is indistinguishable from an absent field once
-        // merged, so a check on the merged result would see neither. See
-        // validateReservedKeys() and validatePatchValues().
-        const patchErrors = [
-            ...validateReservedKeys(content),
-            ...validatePatchValues(content),
-            ...validateContentKeys(content),
-        ];
-        if (patchErrors.length > 0) {
-            throw new StackValidationError(patchErrors);
-        }
-        // 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(content, this.features.limits.contentBytes, 'Patch');
-        // Merge (RFC 7396 / JSON Merge Patch): null values delete a field.
-        const merged = applyMergePatch(existing.content, content);
-        const errors = validateContent(merged, type.schema);
-        if (errors.length > 0) {
-            throw new StackValidationError(errors);
-        }
-        if (existing.typeId === `${SYSTEM_TYPES.ATTACHMENT}@1`) {
-            this.checkAttachmentImmutableFields(content, existing.content, merged);
-        }
-        await this.checkBindingsOnUpdate(existing.typeId, id, content, existing.content, merged);
-        if (id === SYSTEM_TYPES.CONFIG) {
-            this.checkConfigEntityIdUnchanged(existing.content.entityId, merged.entityId);
-        }
-        const updated = await this.adapter.patchContent(id, content, {
+        const merged = await this.validateChangeSet(id, existing, changes);
+        const ops = changeSetOps(existing, changes, merged);
+        // Nothing moved, so there is nothing to version. Decided here rather
+        // than in the adapter: "did this change anything" is a question about
+        // the record's meaning, and an adapter is never handed a write that
+        // writes nothing.
+        if (ops.length === 0)
+            return existing;
+        const previousParentId = existing.parentId ?? null;
+        const updated = await this.adapter.mutateRecord(id, effectiveChanges(changes, ops), {
             expectedVersion: opts.ifVersion,
             snapshot: this.buildVersionSnapshot(existing),
             updatedBy: opts.updatedBy,
             updatedVia: opts.updatedVia,
         });
-        this.emitChange('update', updated);
+        this.emitChange(ops, updated, ops.includes('reparent') ? { previousParentId } : {});
         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);
+    }
+    /**
+     * Every check a change set owes before anything is written, in one pass:
+     * one refused key refuses the call, so none of them may run after a
+     * partial write. Returns the merged content when the set carries a
+     * content patch, since the caller needs it to decide whether content
+     * actually moved.
+     *
+     * Parent existence and acyclicity are asked only when the destination
+     * differs from where the record already sits — a move to where it
+     * already is names no new edge, and would otherwise cost a read apiece.
+     */
+    async validateChangeSet(id, existing, changes) {
+        const { contentPatch, permissions, associations, parentId } = changes;
+        const errors = [
+            ...(contentPatch
+                ? [
+                    ...validateReservedKeys(contentPatch),
+                    ...validatePatchValues(contentPatch),
+                    ...validateContentKeys(contentPatch),
+                ]
+                : []),
+            ...(permissions ? validatePermissions(permissions) : []),
+            ...(associations ? validateAssociations(associations) : []),
+        ];
+        if (errors.length > 0)
+            throw new StackValidationError(errors);
+        let merged;
+        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');
+            const type = await this.getTypeCached(existing.typeId);
+            if (!type) {
+                throw new StackQueryError(`Unknown type: "${existing.typeId}"`);
+            }
+            merged = applyMergePatch(existing.content, contentPatch);
+            const contentErrors = validateContent(merged, type.schema);
+            if (contentErrors.length > 0)
+                throw new StackValidationError(contentErrors);
+            if (existing.typeId === `${SYSTEM_TYPES.ATTACHMENT}@1`) {
+                this.checkAttachmentImmutableFields(contentPatch, existing.content, merged);
+            }
+            await this.checkBindingsOnUpdate(existing.typeId, id, contentPatch, existing.content, merged);
+            if (id === SYSTEM_TYPES.CONFIG) {
+                this.checkConfigEntityIdUnchanged(existing.content.entityId, merged.entityId);
+            }
+        }
+        if (associations !== undefined) {
+            this.assertGroupAdminRemains(existing, associations);
+        }
+        if (parentId !== undefined && parentId !== null && parentId !== (existing.parentId ?? null)) {
+            await this.assertParentExists(id, parentId);
+            await this.assertNoParentCycle(id, parentId);
+        }
+        return merged;
+    }
+    /**
+     * Refuse a write that would leave a `_group` Record with no `admin` on
+     * its roster. Asked of the roster the write would *produce* — the one
+     * place a change-set check reads the post-state rather than the
+     * pre-state, because the rule is about what is left behind rather than
+     * what the caller named.
+     *
+     * That framing is the whole of the self-removal question: an `admin`
+     * removing themselves passes while another remains and is refused when
+     * they are the last, and neither case needs to know whose entry went.
+     *
+     * Lives here rather than in `ScopedStack` deliberately. Who may write a
+     * `_group` is a permission question and belongs to the gate up there;
+     * this is an integrity constraint on the Record, so it binds every
+     * requester — the stack owner included, who would otherwise be the hole
+     * that stops anything downstream relying on the invariant.
+     * See docs/spec/identity.md § Group.
+     */
+    assertGroupAdminRemains(record, next) {
+        if (!isGroupRecord(record))
+            return;
+        if (hasGroupAdmin(next))
+            return;
+        throw new StackConflictError(`Cannot leave group "${record.id}" without an admin: a _group record's roster keeps at ` +
+            'least one `admin` relationship association. Name the incoming admin in the same write.');
+    }
     /**
      * Add an association to a record. Snapshots the record's prior state and
-     * bumps version, same as update() — associations are covered by the same
+     * bumps version, same as patchContent() — associations are covered by the same
      * versioning rule as content.
      * If the association already exists (same kind, label, and payload), this
      * is a no-op. Returns the record as it now stands — unchanged on a no-op.
@@ -1377,6 +1502,13 @@ export class Stack {
         if (!(existing.associations ?? []).some((a) => associationEqual(a, association))) {
             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 updated = await this.adapter.dissociate(id, association, {
             expectedVersion: opts.ifVersion,
             snapshot: this.buildVersionSnapshot(existing),
@@ -1387,63 +1519,59 @@ export class Stack {
         return updated;
     }
     /**
-     * Replace all permissions on a record. Snapshots and bumps version, same
-     * as associate(). Pass an empty array to make the record private (the
-     * default). No-op if the new set is deep-equal to the current one. Returns
-     * the record as it now stands — unchanged on a no-op.
-     */
-    async setPermissions(id, permissions, opts = {}) {
-        this.assertOpen();
-        const errors = validatePermissions(permissions);
-        if (errors.length > 0) {
-            throw new StackValidationError(errors);
-        }
-        const existing = await this.adapter.getRecord(id);
-        if (!existing) {
-            throw new StackNotFoundError(`Record not found: "${id}"`);
-        }
-        this.checkIfVersion(existing, opts.ifVersion);
-        if (permissionsEqual(existing.permissions ?? [], permissions))
-            return existing;
-        const updated = await this.adapter.setPermissions(id, permissions, {
-            expectedVersion: opts.ifVersion,
-            snapshot: this.buildVersionSnapshot(existing),
-            updatedBy: opts.updatedBy,
-            updatedVia: opts.updatedVia,
-        });
-        this.emitChange('permissions', updated);
-        return updated;
-    }
-    /**
-     * Withhold a record from enumeration, or restore it. Orthogonal to
-     * setPermissions(): it says nothing about who may read the record, only
-     * whether `query()` and the change feed enumerate it by default. No-op if
-     * already in the requested state. Returns the record as it now stands —
-     * unchanged on a no-op. See docs/spec/access-control.md §
-     * Unlisted records.
+     * Refuse an edge that would make a record its own ancestor — asked at
+     * every site that adds one: a change set naming `parentId`, a restore
+     * putting a container back, and a create naming both its own id and a parent. Nothing
+     * downstream (a generator deriving a page path, a folder view) is
+     * written to survive a cycle.
      *
-     * The op passed to emitChange() carries the transition direction —
-     * `unlist` (kind `deleted`, so subscribers already holding the record are
-     * told to drop it) or `list` (kind `changed`, an upsert like `undelete`,
-     * for the record's publish moment).
-     */
-    async setUnlisted(id, unlisted, opts = {}) {
-        this.assertOpen();
-        const existing = await this.adapter.getRecord(id);
-        if (!existing) {
-            throw new StackNotFoundError(`Record not found: "${id}"`);
+     * Walks with the unscoped adapter deliberately: a walk that skipped the
+     * links a requester cannot read would let a cycle be assembled through
+     * them and break the invariant for every reader. The walk is bounded
+     * because a chain long enough to exhaust it is already pathological.
+     *
+     * Read-then-write, so two moves racing on opposite ends of one chain can
+     * both pass — closing that means the invariant lives in the adapter,
+     * where the write is atomic, which puts a graph constraint in the
+     * storage contract every adapter then implements. Same deferral as
+     * checkBindingUnique() above. Consumers that walk `parentId` should
+     * carry a visited set rather than trust this alone; MAX_PARENT_DEPTH is
+     * the same posture applied here.
+     * See docs/spec/data-model.md § Reparenting.
+     */
+    /**
+     * The checks a *caller-named* destination owes, before the cycle walk:
+     * `parentId` is a real, well-formed record id. Format first, so a
+     * malformed one is a 400 naming the problem rather than a read that
+     * cannot match. Existence closes the gap between the owner path and a
+     * non-owner's, where canReadReferent() already refuses a parent that
+     * isn't there.
+     *
+     * restoreVersion() deliberately does not call this — see its own comment.
+     * See docs/spec/data-model.md § Reparenting.
+     */
+    async assertParentExists(id, parentId) {
+        validateParentId(parentId);
+        if (!(await this.adapter.getRecord(parentId))) {
+            throw new StackConflictError(`Cannot parent record "${id}" to "${parentId}": no such record. A container has to ` +
+                'exist when it is named.');
+        }
+    }
+    async assertNoParentCycle(id, parentId) {
+        let cursor = parentId;
+        for (let depth = 0; cursor !== undefined; depth++) {
+            if (cursor === id) {
+                throw new StackConflictError(`Cannot parent record "${id}" to "${parentId}": it is a descendant of "${id}", ` +
+                    'and the move would make the record its own ancestor.');
+            }
+            // The cap bounds work, and guarantees this terminates on a chain that
+            // is already cyclic. It does not refuse the move: a chain this long is
+            // past what the check can speak to, not evidence of a loop, and
+            // refusing it would claim an invariant core does not maintain.
+            if (depth >= MAX_PARENT_DEPTH)
+                return;
+            cursor = (await this.adapter.getRecord(cursor))?.parentId;
         }
-        this.checkIfVersion(existing, opts.ifVersion);
-        if (Boolean(existing.unlistedAt) === unlisted)
-            return existing;
-        const updated = await this.adapter.setUnlisted(id, unlisted, {
-            expectedVersion: opts.ifVersion,
-            snapshot: this.buildVersionSnapshot(existing),
-            updatedBy: opts.updatedBy,
-            updatedVia: opts.updatedVia,
-        });
-        this.emitChange(unlisted ? 'unlist' : 'list', updated);
-        return updated;
     }
     /**
      * Soft-delete a record (default) or hard-delete it permanently, removing
@@ -1571,9 +1699,10 @@ export class Stack {
     /**
      * Restore a record to a previous version by creating a new version —
      * never rewrites history. The snapshot is validated against its own
-     * stored typeId (not the record's current type), restores associations,
-     * and never restores permissions. See docs/spec/versioning.md § Restore
-     * semantics.
+     * stored typeId (not the record's current type), restores associations
+     * and `parentId` (absent on the snapshot is the root, so a restore
+     * always settles containment), and never restores permissions. See
+     * docs/spec/versioning.md § Restore semantics.
      */
     async restoreVersion(id, version, opts = {}) {
         this.assertOpen();
@@ -1598,31 +1727,50 @@ export class Stack {
             this.checkConfigEntityIdUnchanged(existing.content.entityId, target.content.entityId);
         }
         // Restoring is a write like any other, so it owes the same immutability
-        // check update() pays — a snapshot taken before a card claimed its DID
+        // check a content patch pays — a snapshot taken before a card claimed its DID
         // would otherwise move the binding by rolling content back. Uniqueness
         // needs no separate check here: a restore can only put back a value this
         // same card already held, which immutability already refuses to change.
         for (const field of bindingFieldsOf(baseIdOf(target.typeId))) {
             this.checkBindingImmutable(baseIdOf(target.typeId), field, existing.content[field], target.content[field]);
         }
+        // A restore that puts a container back is an edge-adding site like
+        // a change set's `parentId`, and the chain above that container may have moved since
+        // the snapshot was taken. The cycle walk therefore applies — but
+        // assertParentExists() deliberately does not: a restore is not a caller
+        // naming a destination, it is history being put back, and the container
+        // may have been hard-deleted since. Refusing here would make an
+        // unrelated deletion cost the record its content rollback, which is the
+        // recoverability this whole verb exists for. A dangling parentId is
+        // legal at rest anyway — deleting a container never touches its
+        // children. See docs/spec/versioning.md § Restore semantics.
+        const previousParentId = existing.parentId ?? null;
+        const targetParentId = target.parentId ?? null;
+        const moves = targetParentId !== previousParentId;
+        if (moves && targetParentId !== null) {
+            await this.assertNoParentCycle(id, targetParentId);
+        }
+        // A `_group`'s roster is authority, not data: it does not roll back.
+        // See docs/spec/versioning.md § Restore semantics.
         const restored = await this.adapter.restoreVersion(id, version, {
             expectedVersion: opts.ifVersion,
             snapshot: this.buildVersionSnapshot(existing),
             updatedBy: opts.updatedBy,
             updatedVia: opts.updatedVia,
+            ...(isGroupRecord(existing) && { restoreAssociations: false }),
         });
-        this.emitChange('restore', restored);
+        this.emitChange('restore', restored, moves ? { previousParentId } : {});
         return restored;
     }
     /**
      * Commit a per-record migration: replace `content` and `typeId` together
      * in one step, validated against `toTypeId`'s schema exactly as
-     * create()/update() validate against a type's schema. The single-record
+     * create()/mutate() validate against a type's schema. The single-record
      * counterpart to migrateAll() — content here is supplied by the caller
      * (computed client-side by the type's owning app, per
      * docs/spec/wire-format.md § Migration commit) rather than a registered
      * Migration function. Snapshots the prior state to version history, same
-     * as update()/restoreVersion(), and takes the same optional `ifVersion`
+     * as mutate()/restoreVersion(), and takes the same optional `ifVersion`
      * precondition every version-bumping mutation takes — checked atomically
      * at the adapter, not here (see docs/spec/versioning.md § Optimistic
      * concurrency).
@@ -1632,7 +1780,7 @@ export class Stack {
      * record as it stands, so it owes both sets of integrity checks — the
      * binding rules, the attachment rules, and `_config`'s. Missing either
      * half would make migrate a second, unguarded write path to the same
-     * state create()/update() refuse to reach.
+     * state create()/mutate() refuse to reach.
      */
     async commitMigration(id, toTypeId, content, opts = {}) {
         this.assertOpen();
@@ -1718,7 +1866,7 @@ export class Stack {
     /**
      * Immutability for every binding field a patch touches, then uniqueness
      * for the subset that carries it. Fields absent from the patch carry no
-     * new claim — update() is a merge, so an untouched binding is the one the
+     * new claim — a content patch is a merge, so an untouched binding is the one the
      * card already holds.
      */
     async checkBindingsOnUpdate(typeId, id, patch, existing, merged) {
@@ -1909,7 +2057,7 @@ export class Stack {
         }
     }
     /**
-     * `_config.entityId` defines stack ownership; neither update() nor
+     * `_config.entityId` defines stack ownership; neither patchContent() nor
      * restoreVersion() may change it. A conflict with stack integrity, not a
      * schema violation — hence StackConflictError. See docs/spec.md § The
      * `_config` record.
@@ -2424,8 +2572,9 @@ export class Stack {
     /**
      * Snapshot of a record's prior state, passed with the mutating adapter
      * call so snapshot and mutation land in one atomic write. `associations`
-     * is always present ([] when empty) so restore can distinguish "cleared"
-     * from a snapshot that omits the key entirely ("leave as-is"). See
+     * and `parentId` are always present (`[]` and `null` where the record has
+     * neither) so restore can distinguish "cleared" and "at the root" from a
+     * snapshot that omits the key entirely ("leave as-is"). See
      * docs/spec/versioning.md § Version history.
      */
     buildVersionSnapshot(record) {
@@ -2437,6 +2586,7 @@ export class Stack {
             ...(record.entityId && { entityId: record.entityId }),
             ...(record.updatedBy && { updatedBy: record.updatedBy }),
             ...(record.updatedVia && { updatedVia: record.updatedVia }),
+            ...(record.parentId !== undefined && { parentId: record.parentId }),
             associations: record.associations ?? [],
             ...(record.permissions && { permissions: record.permissions }),
         };
@@ -2485,6 +2635,89 @@ function permissionEqual(a, b) {
     }
     return false;
 }
+/**
+ * A change set has to name at least one aspect. Refused rather than read
+ * as a no-op: it addresses nothing, so there is nothing it could have
+ * failed to satisfy, and every way of producing one is a caller bug —
+ * typically a conditional that built an empty object.
+ * See docs/spec/data-model.md § Mutations.
+ */
+function assertNonEmptyChangeSet(changes) {
+    // Presence, not truthiness: `unlisted: false` and `parentId: null` are
+    // aspects this call names, and reading them as absent would drop a
+    // change the caller asked for.
+    if (RECORD_CHANGE_KEYS.some((key) => changes[key] !== undefined))
+        return;
+    throw new StackQueryError('A change set names at least one of: ' + RECORD_CHANGE_KEYS.join(', ') + '.');
+}
+/**
+ * Which aspects a change set actually moves, against the record as it
+ * stands — the no-op decision and the change event's `ops` are the same
+ * comparison, so they can never disagree. A key naming the value a record
+ * already holds contributes nothing.
+ *
+ * `merged` is the content the patch produces, computed once by the
+ * caller that had to validate it anyway.
+ * See docs/spec/events.md § The event shape.
+ */
+function changeSetOps(existing, changes, merged) {
+    const ops = [];
+    if (merged !== undefined && !contentEqual(existing.content, merged))
+        ops.push('patch');
+    if (changes.parentId !== undefined && changes.parentId !== (existing.parentId ?? null)) {
+        ops.push('reparent');
+    }
+    if (changes.permissions && !permissionsEqual(existing.permissions ?? [], changes.permissions)) {
+        ops.push('permissions');
+    }
+    if (changes.associations) {
+        const before = existing.associations ?? [];
+        const after = changes.associations;
+        if (after.some((a) => !before.some((b) => associationEqual(a, b))))
+            ops.push('associate');
+        if (before.some((b) => !after.some((a) => associationEqual(a, b))))
+            ops.push('dissociate');
+    }
+    if (changes.unlisted !== undefined && Boolean(existing.unlistedAt) !== changes.unlisted) {
+        ops.push(changes.unlisted ? 'unlist' : 'list');
+    }
+    return ops;
+}
+/**
+ * The change set narrowed to the aspects that actually moved. An adapter
+ * is handed this rather than what the caller wrote, so restating an aspect
+ * cannot rewrite it: `unlisted: true` on an already-unlisted record would
+ * otherwise drag `unlistedAt` forward, moving the record's publish moment
+ * with no op reporting it. It also keeps the adapter contract honest —
+ * every key an adapter receives is one it must write.
+ */
+function effectiveChanges(changes, ops) {
+    const effective = {};
+    if (ops.includes('patch'))
+        effective.contentPatch = changes.contentPatch;
+    if (ops.includes('reparent'))
+        effective.parentId = changes.parentId;
+    if (ops.includes('permissions'))
+        effective.permissions = changes.permissions;
+    if (ops.includes('associate') || ops.includes('dissociate')) {
+        effective.associations = changes.associations;
+    }
+    if (ops.includes('unlist') || ops.includes('list'))
+        effective.unlisted = changes.unlisted;
+    return effective;
+}
+/**
+ * Whether a merge patch produced the content the record already held.
+ * Compared by serialization: content is JSON by construction — it round
+ * trips through storage that way — and a patch preserves key order for
+ * every field it does not name, so the encoding of an unchanged record is
+ * stable. A reordering patch that changes nothing else is the one case
+ * this reports as a change, which costs an empty version rather than a
+ * wrong answer.
+ */
+function contentEqual(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
 function permissionsEqual(a, b) {
     return a.length === b.length && a.every((p, i) => permissionEqual(p, b[i]));
 }
@@ -2494,6 +2727,13 @@ function permissionsEqual(a, b) {
 /** Default page size used to fill a permission-filtered query result. */
 const DEFAULT_QUERY_LIMIT = 50;
 const MAX_QUERY_LIMIT = 1000;
+/**
+ * How far a change set's `parentId` will walk a proposed ancestor chain before refusing
+ * the move. Bounds the reads one call can cost; a hierarchy deeper than
+ * this is beyond what `parentId` is for. See docs/spec/data-model.md
+ * § Reparenting.
+ */
+const MAX_PARENT_DEPTH = 64;
 /**
  * Ensures `creator` carries an `admin` relationship association, adding one
  * if it's not already present. Used to bootstrap a `_group` record's first
@@ -2512,6 +2752,13 @@ function stampGroupAdmin(associations, creator) {
         { kind: 'relationship', label: 'admin', target: { scope: 'entity', entityId: creator } },
     ];
 }
+/**
+ * Whether a Record is a `_group`, in any of its type versions — the family
+ * whose roster rules apply.
+ */
+function isGroupRecord(record) {
+    return baseIdOf(record.typeId) === SYSTEM_TYPES.GROUP;
+}
 /**
  * Drops a snapshot's `permissions` — owner-only audit data, never served
  * to a non-owner history reader. `entityId` (change attribution) stays.
@@ -2554,7 +2801,7 @@ const presentDeleted = (record) => record.deletedAt ? tombstoneOf(record) : reco
  *
  * Two identities, one rule: **the principal governs authority, the subject
  * governs attribution.** Grant lookup and the privilege-bearing gates that
- * no grant reaches (setPermissions, group management, hard delete, widening
+ * no grant reaches (resharing, group management, hard delete, widening
  * access at create time) key on `principalEntityId`; authorship, `-own`
  * matching, record-level permission resolution, and "files I uploaded"
  * lookups key on `subjectEntityId`.
@@ -2897,7 +3144,7 @@ export class ScopedStack {
      * `_group` records are managed, not merely written: only the owner or an
      * `admin` roster holder may mutate them — ordinary write permissions and
      * grants don't apply. Asked of both identities under delegation, like
-     * setPermissions(). See docs/spec/identity.md § Group.
+     * a reshare. See docs/spec/identity.md § Group.
      */
     isGroupManager(record) {
         if (!this.managesGroup(this.principalEntityId, record))
@@ -3059,7 +3306,7 @@ export class ScopedStack {
      * Gates file-ref content fields on file access, mirroring the
      * attachment-association gate — a file-ref field conveys attachment
      * access exactly like an `attachment` association. Only fields present
-     * in `content` are checked (update() is a merge patch; untouched fields
+     * in `content` are checked (a content patch is a merge patch; untouched fields
      * carry no new reference).
      */
     async requireFileRefAccess(typeId, content) {
@@ -3178,7 +3425,7 @@ export class ScopedStack {
     }
     /**
      * Whether this request may decide who else reaches a record — the rule
-     * setPermissions() enforces, asked at create time too so the reach it
+     * a reshare enforces, asked at create time too so the reach it
      * withholds can't be taken one step earlier while authoring. A delegated
      * app is denied it: widening access is the one thing containment most
      * needs to hold. Refused rather than silently ignored, so an app never
@@ -3192,7 +3439,7 @@ export class ScopedStack {
     }
     /**
      * Whether one identity, on its own, may decide who else reaches `record`
-     * — the owner-or-creator rule setPermissions() enforces, asked of one
+     * — the owner-or-creator rule a reshare enforces, asked of one
      * side at a time. See
      * docs/spec/access-control.md § Delegation: principal and subject.
      */
@@ -3268,28 +3515,105 @@ export class ScopedStack {
         } while (records.length < limit && page.cursor && totalFetched < maxFetched);
         return { records, cursor: page.cursor };
     }
-    async update(id, content, opts = {}) {
-        const record = await this.requireUpdatable(id);
-        // Ahead of the binding fences below, which compare the patch's value
-        // for a field against the stored one: `undefined` names a field
-        // without claiming a value, so it is refused as a malformed patch
-        // rather than read as a change. See Stack.update() for the same check
-        // on every other path into a patch.
-        const patchErrors = validatePatchValues(content);
-        if (patchErrors.length > 0)
-            throw new StackValidationError(patchErrors);
-        // Value-wise, not presence-wise: a client that reads a card, edits its
-        // `name` and sends the whole content object back is not setting the
-        // binding it round-trips, and `name` is writable by record-level
-        // permission. Same predicate restoreVersion() applies to a snapshot.
-        this.requireOwnerForAppIdentity(record.typeId, (field) => field in content && content[field] !== record.content[field]);
-        // Likewise value-wise: re-sending the DID a card already holds claims
-        // nothing, and immutability refuses changing it regardless.
-        if ('did' in content && content.did !== record.content.did) {
-            this.requireOwnerForOwnerDid(record.typeId, content.did);
-        }
-        await this.requireFileRefAccess(record.typeId, content);
-        return this.stack.update(id, content, { ...opts, ...this.actor });
+    /**
+     * Apply a change set on behalf of the subject. Authority is resolved
+     * **per key** and every gate reads the record as it stands, never as the
+     * change set would leave it: a widened `permissions` never satisfies the
+     * read check on a `parentId` named in the same call, and a `_group`
+     * roster never satisfies the admin check that same call has to pass.
+     * One refused key refuses the whole call, so nothing is partially
+     * applied and no key is silently dropped.
+     * See docs/spec/access-control.md § Composing a change set.
+     */
+    async mutate(id, changes, opts = {}) {
+        // Ahead of every gate: a malformed change set is a validation error
+        // for every requester, rather than one for the owner and a permission
+        // refusal for everyone else.
+        assertNonEmptyChangeSet(changes);
+        if (changes.contentPatch) {
+            const patchErrors = validatePatchValues(changes.contentPatch);
+            if (patchErrors.length > 0)
+                throw new StackValidationError(patchErrors);
+        }
+        const reshares = changes.permissions !== undefined || changes.unlisted !== undefined;
+        const writes = changes.contentPatch !== undefined ||
+            changes.associations !== undefined ||
+            changes.parentId !== undefined;
+        // requireUpdatable() reads the record and applies the write gate; the
+        // reshare keys need the record before their own gate, and a change set
+        // carrying only those must not be held to the write gate it doesn't
+        // need. One read either way.
+        const record = writes ? await this.requireUpdatable(id) : await this.requireReshareable(id);
+        if (writes && reshares)
+            await this.requireReshareOf(record);
+        if (changes.contentPatch) {
+            const patch = changes.contentPatch;
+            // Value-wise, not presence-wise: a client that reads a card, edits
+            // its `name` and sends the whole content object back is not setting
+            // the binding it round-trips, and `name` is writable by record-level
+            // permission. Same predicate restoreVersion() applies to a snapshot.
+            this.requireOwnerForAppIdentity(record.typeId, (field) => field in patch && patch[field] !== record.content[field]);
+            // Likewise value-wise: re-sending the DID a card already holds
+            // claims nothing, and immutability refuses changing it regardless.
+            if ('did' in patch && patch.did !== record.content.did) {
+                this.requireOwnerForOwnerDid(record.typeId, patch.did);
+            }
+            await this.requireFileRefAccess(record.typeId, patch);
+        }
+        // Every association the change set would add is a reference this
+        // requester has to be allowed to create — asked against the stored
+        // set, so an association already on the record is not re-gated.
+        for (const assoc of changes.associations ?? []) {
+            if ((record.associations ?? []).some((a) => associationEqual(a, assoc)))
+                continue;
+            await this.requireAssociationAccess(record.typeId, assoc);
+        }
+        if (changes.parentId != null && !(await this.canReadReferent(changes.parentId))) {
+            throw new StackPermissionError();
+        }
+        return this.stack.mutate(id, changes, { ...opts, ...this.actor });
+    }
+    async patchContent(id, patch, opts = {}) {
+        return this.mutate(id, { contentPatch: patch }, opts);
+    }
+    /**
+     * The record, having established that this request may decide who else
+     * reaches it — the owner-or-creator rule, asked of both sides of a
+     * delegation, or a Group's admin rule for a `_group`. The gate the
+     * `permissions` and `unlisted` keys carry, which the write bit
+     * deliberately does not confer.
+     */
+    async requireReshareable(id) {
+        const record = await this.stack.get(id);
+        if (!record)
+            throw new StackNotFoundError(`Record not found: "${id}"`);
+        await this.requireOwnerForGrantRecord(record);
+        await this.requireReshareOf(record);
+        // Reached through its own gate rather than requireUpdatable(), so the
+        // soft-delete refusal has to be asked here too — after the authority
+        // decision above, for the reason refuseIfDeleted() gives.
+        return this.refuseIfDeleted(record, true);
+    }
+    /** The reshare decision alone, for a record already read and write-gated. */
+    async requireReshareOf(record) {
+        if (baseIdOf(record.typeId) === SYSTEM_TYPES.GROUP) {
+            // Group management, not authorship: a creator later demoted from the
+            // admin roster shouldn't retain a side door to reassign who can read
+            // or write the group record.
+            if (!this.isGroupManager(record))
+                throw await this.denialFor(record);
+            return;
+        }
+        // Intersected like every other authority here: the principal must hold
+        // the verb, and the subject must be able to reach this record —
+        // without which an owner principal would carry its subject to records
+        // the subject cannot touch. create() withholds the same reach via
+        // mayGrantAccess().
+        if (!this.mayReshare(this.principalEntityId, record))
+            throw await this.denialFor(record);
+        if (this.delegated && !this.mayReshare(this.subjectEntityId, record)) {
+            throw await this.denialFor(record);
+        }
     }
     /**
      * Naming the software behind a key is the trust decision the `_app`
@@ -3388,62 +3712,6 @@ export class ScopedStack {
         await this.requireUpdatable(id);
         return this.stack.dissociate(id, association, { ...opts, ...this.actor });
     }
-    async setPermissions(id, permissions, opts = {}) {
-        const record = await this.stack.get(id);
-        if (!record)
-            throw new StackNotFoundError(`Record not found: "${id}"`);
-        await this.requireOwnerForGrantRecord(record);
-        if (baseIdOf(record.typeId) === SYSTEM_TYPES.GROUP) {
-            // Group management, not authorship: a creator later demoted from the
-            // admin roster shouldn't retain a side door to reassign who can read
-            // or write the group record. Same gate as update/associate/delete.
-            if (!this.isGroupManager(record))
-                throw await this.denialFor(record);
-        }
-        else {
-            // Intersected like every other authority here: the principal must
-            // hold the verb, and the subject must be able to reach this record —
-            // without which an owner principal would carry its subject to records
-            // the subject cannot touch. create() withholds the same reach via
-            // mayGrantAccess().
-            if (!this.mayReshare(this.principalEntityId, record))
-                throw await this.denialFor(record);
-            if (this.delegated && !this.mayReshare(this.subjectEntityId, record)) {
-                throw await this.denialFor(record);
-            }
-        }
-        // Reached through its own gate rather than requireUpdatable(), so the
-        // soft-delete refusal has to be asked here too — after the authority
-        // decision above, for the reason refuseIfDeleted() gives.
-        this.refuseIfDeleted(record, true);
-        return this.stack.setPermissions(id, permissions, { ...opts, ...this.actor });
-    }
-    /**
-     * Withhold a record from enumeration, or restore it — gated exactly like
-     * setPermissions(), since both decide who or what can discover the
-     * record rather than merely read it once found. See
-     * docs/spec/unlisted.md.
-     */
-    async setUnlisted(id, unlisted, opts = {}) {
-        const record = await this.stack.get(id);
-        if (!record)
-            throw new StackNotFoundError(`Record not found: "${id}"`);
-        await this.requireOwnerForGrantRecord(record);
-        if (baseIdOf(record.typeId) === SYSTEM_TYPES.GROUP) {
-            if (!this.isGroupManager(record))
-                throw await this.denialFor(record);
-        }
-        else {
-            if (!this.mayReshare(this.principalEntityId, record))
-                throw await this.denialFor(record);
-            if (this.delegated && !this.mayReshare(this.subjectEntityId, record)) {
-                throw await this.denialFor(record);
-            }
-        }
-        // See setPermissions() above — same gate, same reason.
-        this.refuseIfDeleted(record, true);
-        return this.stack.setUnlisted(id, unlisted, { ...opts, ...this.actor });
-    }
     /**
      * Hard delete is owner-only: it is irreversible and destroys version
      * history, so neither the write bit nor delete-own/delete-any grants
@@ -3468,7 +3736,7 @@ export class ScopedStack {
     }
     /**
      * History is the mutation/recovery surface, not a read surface — gated
-     * like update(), with snapshot `permissions` stripped for everyone but
+     * like patchContent(), with snapshot `permissions` stripped for everyone but
      * the owner acting alone — a snapshot's permissions are the stack's
      * sharing graph, which delegation is not a route to. Reading history
      * changes nothing, so it is the one path the `_grant` write fence leaves
@@ -3493,9 +3761,11 @@ export class ScopedStack {
     /**
      * Re-runs the reference-creation checks against the snapshot, so a
      * restore can't re-convey access to a file or record the subject can no
-     * longer reach today. Only the owner acting alone is exempt: under
-     * delegation the checks resolve against the subject, which is whose reach
-     * the restore would widen. See docs/spec/versioning.md § Restore semantics.
+     * longer reach today — the snapshot's `parentId` among them, gated
+     * exactly as a change set's `parentId` gates a destination named directly. Only the
+     * owner acting alone is exempt: under delegation the checks resolve
+     * against the subject, which is whose reach the restore would widen.
+     * See docs/spec/versioning.md § Restore semantics.
      */
     async restoreVersion(id, version, opts = {}) {
         const record = await this.requireUpdatable(id);
@@ -3503,12 +3773,29 @@ export class ScopedStack {
             const target = await this.stack.getVersion(id, version);
             if (target) {
                 // A rollback that would move a card's binding is the same trust
-                // decision update() reserves to the owner, reached by another route.
+                // decision a content patch reserves to the owner, reached by another route.
                 this.requireOwnerForAppIdentity(record.typeId, (field) => target.content[field] !==
                     record.content[field]);
+                // Only a restore that moves the record *into* a container creates a
+                // reference. A snapshot at the root names nothing, and a parentId
+                // the restore would not change is not re-gated: the record is
+                // already there, so a content rollback is not refused over a move
+                // it isn't making.
+                if (target.parentId !== undefined &&
+                    target.parentId !== record.parentId &&
+                    !(await this.canReadReferent(target.parentId))) {
+                    throw new StackPermissionError();
+                }
                 await this.requireFileRefAccess(target.typeId, target.content);
-                for (const association of target.associations ?? []) {
-                    await this.requireAssociationAccess(target.typeId, association);
+                // Gated against the associations the restore will actually write.
+                // A `_group`'s don't roll back at all, so such a restore introduces
+                // no association and there is nothing here to gate — the same
+                // reason a `parentId` the restore would not change is not re-gated
+                // above.
+                if (!isGroupRecord(record)) {
+                    for (const association of target.associations ?? []) {
+                        await this.requireAssociationAccess(target.typeId, association);
+                    }
                 }
             }
         }
@@ -3526,7 +3813,7 @@ export class ScopedStack {
      * The restriction is what makes the verb safe to expose at all. Migrate
      * replaces `content` and `typeId` wholesale, so a grant-based version
      * would have to re-derive every gate `create()` applies at the
-     * destination *and* every gate `update()` applies over the existing
+     * destination *and* every gate `mutate()` applies over the existing
      * content, and would reopen each one it missed. The sharpest is the
      * non-owner `_attachment@1` refusal create() carries: without it, a
      * requester holding a create grant on `_attachment@1` and write access