@haverstack/core 0.8.0 → 0.10.0

package/dist/stack.js

@@ -7,73 +7,442 @@
  *  - ID generation
  *  - Type definition and schema hashing
  *  - Content validation on write
- *  - Migration registry and auto-migration on read
+ *  - Migration registry and explicit, owner-driven migrateAll()
  *  - Version snapshotting on update
  *  - Soft and hard delete
  *
  * Apps should never talk to a StackAdapter directly.
  */
-import { generateId } from './id.js';
-import { hashSchema, isCompatible, parseTypeId } from './schema.js';
-import { validateContent } from './validate.js';
-import { checkAccess } from './access.js';
-import { SYSTEM_TYPES } from './types.js';
-export class StackValidationError extends Error {
+import { generateId, isValidIdFormat, idTimestamp } from './id.js';
+import { hashSchema, isCompatible, parseTypeId, baseIdOf, diffSchemas, isWellFormedTypeId, } from './schema.js';
+import { validateContent, validateReservedKeys } from './validate.js';
+import { applyMergePatch } from './merge.js';
+import { checkAccess, groupRoleFromAssociations } from './access.js';
+import { firstRecordedAttachment } from './attachment-download.js';
+import { SYSTEM_TYPES, GRANT_ACTIONS } from './types.js';
+// -------------------------------------------------------
+// Supporting types
+// -------------------------------------------------------
+/** Sentinel: filter.baseId resolved to zero matching types. */
+const EMPTY_FAMILY = Symbol('empty-family');
+/**
+ * Valid GrantAction values, for runtime validation in Stack.grant().
+ * Built from GRANT_ACTIONS (types.ts), the source of truth GrantAction is
+ * itself derived from — so this can't drift from the type.
+ */
+const GRANT_ACTION_SET = new Set(GRANT_ACTIONS);
+/**
+ * System type families grant() refuses to target: a grant on any of them
+ * would let the grantee mint their own grants, touch stack config, or
+ * register an app card claiming a DID that isn't theirs — the last of
+ * which is what verified app attribution rests on. See
+ * docs/spec/access-control.md § Type-level grants.
+ */
+const UNGRANTABLE_SYSTEM_TYPES = new Set([
+    SYSTEM_TYPES.GRANT,
+    SYSTEM_TYPES.CONFIG,
+    SYSTEM_TYPES.APP,
+]);
+/**
+ * Content fields that are lookup keys rather than display values: a card
+ * claims one, and something later resolves through it. Every one of them is
+ * immutable once set. See docs/spec/identity.md § DID bindings.
+ */
+const BINDING_FIELDS = new Map([
+    [SYSTEM_TYPES.APP, ['did', 'appId']],
+    [SYSTEM_TYPES.ENTITY, ['did']],
+]);
+/**
+ * The subset that is additionally unique per stack: the fields something
+ * resolves *by*. A Record's `principalId` finds its card by `_app.did` and
+ * its `entityId` by `_entity.did`, so a second card claiming either leaves
+ * that lookup without a single answer — and ambiguity is all an
+ * impersonating card needs.
+ *
+ * `_app.appId` is deliberately absent. Nothing resolves a card by it — the
+ * cross-check reaches the card by `did` and only compares `appId` — so
+ * uniqueness would buy no disambiguation, while forbidding the second card
+ * key rotation is supposed to produce: `appId` is required, so a
+ * replacement card for the same software necessarily repeats it. Moving one
+ * card onto another's `appId` is what immutability already refuses.
+ * See docs/spec/identity.md § DID bindings.
+ */
+const UNIQUE_BINDING_FIELDS = new Map([
+    [SYSTEM_TYPES.APP, ['did']],
+    [SYSTEM_TYPES.ENTITY, ['did']],
+]);
+const bindingFieldsOf = (family) => BINDING_FIELDS.get(family) ?? [];
+const uniqueBindingFieldsOf = (family) => UNIQUE_BINDING_FIELDS.get(family) ?? [];
+/**
+ * Root of the Stack error taxonomy. A single `instanceof StackError` answers
+ * "is this a Stack-domain error or a bug?" — the question a server's error
+ * middleware asks before serializing a wire body, and one a nine-arm
+ * instanceof ladder answers only by exhaustion. Every subclass carries its
+ * discriminator as an instance `code`, so serialization is a lookup rather
+ * than a chain of class tests.
+ *
+ * Membership implies a wire mapping: every code has an entry in
+ * WIRE_ERROR_STATUS. Errors with no wire representation (IdGenerationError,
+ * InvalidDidError) deliberately stay outside this hierarchy.
+ *
+ * Subclassing adds no hierarchy beyond this root — notably
+ * StackVersionConflictError is a sibling of StackConflictError, not a
+ * subtype. See docs/spec/wire-format.md § Error responses.
+ */
+export class StackError extends Error {
+}
+export class StackValidationError extends StackError {
     errors;
+    static code = 'validation';
+    code = StackValidationError.code;
     constructor(errors) {
         super(`Content validation failed:\n` + errors.map((e) => `  ${e.path}: ${e.message}`).join('\n'));
         this.errors = errors;
         this.name = 'StackValidationError';
     }
 }
-export class StackMigrationError extends Error {
+export class StackMigrationError extends StackError {
+    static code = 'migration';
+    code = StackMigrationError.code;
     constructor(message) {
         super(message);
         this.name = 'StackMigrationError';
     }
 }
 /** Thrown by ScopedStack when a requester lacks permission for the operation. */
-export class StackPermissionError extends Error {
+export class StackPermissionError extends StackError {
+    static code = 'permission';
+    code = StackPermissionError.code;
     constructor(message = 'Permission denied') {
         super(message);
         this.name = 'StackPermissionError';
     }
 }
 /** Thrown when a record (or specific version) does not exist. */
-export class StackNotFoundError extends Error {
+export class StackNotFoundError extends StackError {
+    static code = 'not_found';
+    code = StackNotFoundError.code;
     constructor(message) {
         super(message);
         this.name = 'StackNotFoundError';
     }
 }
 /** Thrown when an operation cannot proceed due to a constraint violation (e.g. deleting an attachment that is still referenced). */
-export class StackConflictError extends Error {
+export class StackConflictError extends StackError {
+    static code = 'conflict';
+    code = StackConflictError.code;
     constructor(message) {
         super(message);
         this.name = 'StackConflictError';
     }
 }
+/**
+ * Thrown when an `ifVersion` precondition doesn't match a record's current
+ * version. Deliberately not a StackConflictError subtype — the two have
+ * different recovery stories and HTTP statuses (409 vs. 412). See
+ * docs/spec/versioning.md § Optimistic concurrency (`ifVersion`).
+ */
+export class StackVersionConflictError extends StackError {
+    recordId;
+    expectedVersion;
+    actualVersion;
+    static code = 'version_conflict';
+    code = StackVersionConflictError.code;
+    constructor(message, recordId, expectedVersion, actualVersion) {
+        super(message);
+        this.recordId = recordId;
+        this.expectedVersion = expectedVersion;
+        this.actualVersion = actualVersion;
+        this.name = 'StackVersionConflictError';
+    }
+}
+/**
+ * Thrown when a request is structurally malformed — not a content-validation
+ * failure, but input the adapter/server can't even interpret (e.g. an
+ * undecodable pagination cursor). Distinct from StackValidationError, which
+ * means the request was well-formed but content failed schema validation.
+ */
+export class StackQueryError extends StackError {
+    static code = 'bad_request';
+    code = StackQueryError.code;
+    constructor(message) {
+        super(message);
+        this.name = 'StackQueryError';
+    }
+}
+/**
+ * Fail loud rather than silently widen: a filter the adapter can't honor
+ * would otherwise be dropped, returning an unfiltered superset presented
+ * as the filtered result. Shared by Stack.query() and
+ * APIAdapter.queryRecords(). See docs/spec/data-model.md
+ * § Capability-gated filters.
+ */
+export function assertQueryCapabilities(filter, capabilities) {
+    if (filter?.search && !capabilities.fullTextSearch) {
+        throw new StackQueryError('Query uses filter.search, but this adapter does not declare the fullTextSearch capability.');
+    }
+    if (filter?.content && !capabilities.contentFieldQuery) {
+        throw new StackQueryError('Query uses filter.content, but this adapter does not declare the contentFieldQuery capability.');
+    }
+}
+/**
+ * Thrown when an attachment upload exceeds the adapter's declared
+ * `maxAttachmentBytes` ceiling — checked client-side before any bytes are
+ * sent; a server still enforces 413 authoritatively regardless. See
+ * docs/spec/wire-format.md § Attachments.
+ */
+export class StackPayloadTooLargeError extends StackError {
+    static code = 'payload_too_large';
+    code = StackPayloadTooLargeError.code;
+    constructor(message) {
+        super(message);
+        this.name = 'StackPayloadTooLargeError';
+    }
+}
+/**
+ * Thrown when a server abandons an operation for taking too long — in
+ * practice a full-text search, the one query whose cost the sanitizers
+ * bound the *grammar* of but not the execution of (see
+ * docs/spec/data-model.md § Capability-gated filters).
+ *
+ * Never produced in-process: both SQLite engines run synchronously, so
+ * there is nothing to interrupt from inside the call. It exists so a
+ * server that bounds query time has a class to serialize, and so the app
+ * catching it can tell "too expensive, narrow it and retry" from
+ * StackQueryError's "malformed, don't bother retrying" — the distinction
+ * that would be lost if a timeout reused `bad_request`.
+ */
+export class StackTimeoutError extends StackError {
+    static code = 'timeout';
+    code = StackTimeoutError.code;
+    constructor(message) {
+        super(message);
+        this.name = 'StackTimeoutError';
+    }
+}
+/** Shared by Stack.putAttachment() and ScopedStack.putAttachment(). */
+function assertAttachmentSize(byteLength, maxAttachmentBytes) {
+    if (maxAttachmentBytes !== null && byteLength > maxAttachmentBytes) {
+        throw new StackPayloadTooLargeError(`Attachment (${byteLength} bytes) exceeds the ${maxAttachmentBytes}-byte limit.`);
+    }
+}
+/**
+ * The content half of the same pre-check, on Stack.create() and
+ * Stack.update(). Local adapters declare `maxContentBytes: 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
+ * interpret. See docs/spec/wire-format.md § Request size limits.
+ */
+function assertContentSize(content, maxContentBytes, what) {
+    if (maxContentBytes === null)
+        return;
+    const byteLength = new TextEncoder().encode(JSON.stringify(content)).length;
+    if (byteLength > maxContentBytes) {
+        throw new StackPayloadTooLargeError(`${what} (${byteLength} bytes) exceeds the ${maxContentBytes}-byte limit.`);
+    }
+}
+/**
+ * Thrown by defineType() when redefining an existing typeId with a schema
+ * change beyond additive evolution. The remedy is a new version, never an
+ * in-place redefinition. See docs/spec/data-model.md § Schema drift
+ * detection.
+ */
+export class StackSchemaDriftError extends StackError {
+    typeId;
+    violations;
+    static code = 'schema_drift';
+    code = StackSchemaDriftError.code;
+    constructor(typeId, violations) {
+        super(`Schema drift detected for type "${typeId}": the stored schema and the new definition ` +
+            `differ beyond additive evolution (new optional fields only). Bump the version instead ` +
+            `of redefining "${typeId}" in place — e.g. defineType(\`${baseIdOf(typeId)}@${(parseTypeId(typeId)?.version ?? 0) + 1}\`, ...) plus registerMigration().\n` +
+            violations.map((v) => `  ${v.path || '(root)'}: ${v.message}`).join('\n'));
+        this.typeId = typeId;
+        this.violations = violations;
+        this.name = 'StackSchemaDriftError';
+    }
+}
+/**
+ * Thrown when a Stack or ScopedStack is used after close(). Deliberately
+ * outside the StackError taxonomy, alongside IdGenerationError and
+ * InvalidDidError: a caller holding a closed client is a local programming
+ * error with no wire representation — no server ever responds with it.
+ * See docs/spec/adapters.md § Lifecycle.
+ */
+export class StackClosedError extends Error {
+    constructor(message = 'This Stack has been closed.') {
+        super(message);
+        this.name = 'StackClosedError';
+    }
+}
+// -------------------------------------------------------
+// Record ID validation
+// -------------------------------------------------------
+const RESERVED_ID_PREFIX = '_';
+const DEFAULT_ID_TIMESTAMP_SKEW_MS = 24 * 60 * 60 * 1000;
+/**
+ * Default grace period for Stack.collectAttachmentGarbage(), covering the
+ * upload-then-associate window. See docs/spec/attachments.md § Garbage
+ * collection.
+ */
+const DEFAULT_GC_GRACE_MS = 24 * 60 * 60 * 1000;
+/**
+ * Format and reserved-prefix checks — full-trust context (Stack.create()).
+ * Checked before the format check: the Crockford charset already excludes
+ * "_", so a reserved-looking id (e.g. "_config") would otherwise just fail
+ * as a generic format error instead of a specific, actionable one.
+ *
+ * Throws StackQueryError, not StackValidationError: a malformed id is
+ * structurally bad input the request never gets past — it doesn't reach
+ * type-schema validation — the same reasoning that makes an undecodable
+ * pagination cursor a StackQueryError rather than a content-validation
+ * failure. See StackQueryError's doc comment.
+ */
+function validateRecordId(id) {
+    if (id.startsWith(RESERVED_ID_PREFIX)) {
+        throw new StackQueryError(`ID "${id}" uses the reserved "${RESERVED_ID_PREFIX}" prefix.`);
+    }
+    if (!isValidIdFormat(id)) {
+        throw new StackQueryError(`Invalid ID "${id}": expected 12 lowercase Crockford base-32 characters.`);
+    }
+}
+/**
+ * Timestamp-prefix plausibility check for grantee-minted IDs
+ * (ScopedStack.create()) — a grantee is untrusted and could otherwise mint
+ * an ID that forges its sort position. Pass null to disable.
+ */
+function validateIdTimestampSkew(id, toleranceMs) {
+    if (toleranceMs === null)
+        return;
+    const skew = Math.abs(Date.now() - idTimestamp(id));
+    if (skew > toleranceMs) {
+        throw new StackValidationError([
+            {
+                path: 'id',
+                message: `ID "${id}" timestamp is outside the allowed clock-skew tolerance (${toleranceMs}ms).`,
+            },
+        ]);
+    }
+}
+// -------------------------------------------------------
+// Query helpers
+// -------------------------------------------------------
+/**
+ * Walks `cursor` to exhaustion for the internal call sites that need every
+ * match (grant checks, attachment cleanup) — query() itself always
+ * paginates. Throws StackQueryError past `max` rather than silently
+ * truncating a runaway scan. Not a public API.
+ */
+async function queryAllPages(run, query, max = QUERY_ALL_MAX) {
+    const records = [];
+    let cursor = query.cursor;
+    do {
+        const page = await run({ ...query, cursor });
+        records.push(...page.records);
+        if (records.length > max) {
+            throw new StackQueryError(`queryAllPages: exceeded max of ${max} records without exhausting the cursor`);
+        }
+        cursor = page.cursor ?? undefined;
+    } while (cursor);
+    return records;
+}
+/** Safety cap for queryAllPages() — generous for personal-stack scale. */
+const QUERY_ALL_MAX = 10_000;
+/**
+ * Cursor-walks `run(query)` looking for the first record matching
+ * `predicate`, short-circuiting on a match. Same bounded-scan discipline
+ * as queryAllPages(): a match past page one is still found, and a
+ * non-terminating scan throws StackQueryError.
+ */
+async function findFirstMatch(run, query, predicate, max = QUERY_ALL_MAX) {
+    let cursor = query.cursor;
+    let totalFetched = 0;
+    do {
+        const page = await run({ ...query, cursor });
+        totalFetched += page.records.length;
+        if (totalFetched > max) {
+            throw new StackQueryError(`findFirstMatch: exceeded max of ${max} records without exhausting the cursor`);
+        }
+        for (const record of page.records) {
+            if (await predicate(record))
+                return record;
+        }
+        cursor = page.cursor ?? undefined;
+    } while (cursor);
+    return undefined;
+}
 // -------------------------------------------------------
 // Stack class
 // -------------------------------------------------------
 export class Stack {
     adapter;
+    idTimestampSkewMsValue;
     migrations = new Map();
-    constructor(adapter) {
+    /**
+     * Highest version this instance has defineType()'d, per baseId — what
+     * this app process understands, as distinct from what exists in shared
+     * storage. Used to detect the stale-writer case in presentAtLatest().
+     */
+    maxDefinedVersion = new Map();
+    /**
+     * Types this instance has fetched or defined, keyed by versioned id. A
+     * Type's schema is immutable once defined, so entries are never
+     * invalidated, only added; listTypes() refreshes wholesale. See
+     * docs/spec/data-model.md § Type cache.
+     */
+    typeCache = new Map();
+    /** Set by close(). See docs/spec/adapters.md § Lifecycle. */
+    closed = false;
+    constructor(adapter, idTimestampSkewMsValue) {
         this.adapter = adapter;
+        this.idTimestampSkewMsValue = idTimestampSkewMsValue;
+    }
+    async getTypeCached(id) {
+        const cached = this.typeCache.get(id);
+        if (cached)
+            return cached;
+        const type = await this.adapter.getType(id);
+        if (type)
+            this.typeCache.set(id, type);
+        return type;
     }
     /**
      * Create a Stack instance. Reads ownerEntityId and timezone from the adapter.
      */
-    static async create(adapter) {
+    static async create(adapter, opts = {}) {
         if (!adapter.ownerEntityId) {
             throw new Error('Stack misconfiguration: adapter has no ownerEntityId. ' +
                 'Initialise the adapter with an entityId before calling Stack.create().');
         }
-        const stack = new Stack(adapter);
+        const stack = new Stack(adapter, opts.idTimestampSkewMs === undefined ? DEFAULT_ID_TIMESTAMP_SKEW_MS : opts.idTimestampSkewMs);
         await stack.seedSystemTypes();
+        if (opts.ownerProfile) {
+            await stack.ensureOwnerEntity(opts.ownerProfile);
+        }
         return stack;
     }
+    /**
+     * Idempotent bootstrap for StackOptions.ownerProfile. Filters by family
+     * only (contentFieldQuery is capability-gated) and matches `content.did`
+     * in memory, cursor-walking so an owner card past page one isn't missed
+     * and duplicated. The probe must be blind to nothing the binding rules
+     * see, or it mints a card they then refuse and the stack won't open with
+     * `ownerProfile`: soft-deleted cards still reserve their `did`, and a card
+     * migrated to a later version still holds one.
+     * See docs/spec/identity.md § DID bindings.
+     */
+    async ensureOwnerEntity(profile) {
+        const entityTypeId = `${SYSTEM_TYPES.ENTITY}@1`;
+        const existing = await findFirstMatch((q) => this.query(q), { filter: { baseId: SYSTEM_TYPES.ENTITY, includeDeleted: true } }, (r) => r.content.did === this.ownerEntityId);
+        if (existing)
+            return;
+        await this.create(entityTypeId, {
+            did: this.ownerEntityId,
+            name: profile.name,
+            ...(profile.handle && { handle: profile.handle }),
+        });
+    }
     get ownerEntityId() {
         return this.adapter.ownerEntityId;
     }
@@ -84,33 +453,76 @@ export class Stack {
         return this.adapter.capabilities;
     }
     /**
-     * Get a permission-scoped view of this Stack, as if the request came from
-     * the given entity. Pass null for an anonymous/unauthenticated requester.
-     * Reads and writes are checked against each Record's `permissions`; the
-     * owner always has full access.
+     * Get a permission-scoped view of this Stack, as if requests came from
+     * the given principal (null = anonymous). Plain Stack methods are
+     * unscoped; use asEntity() when one Stack serves multiple, possibly
+     * untrusted, entities.
+     *
+     * `onBehalfOf` names the subject a delegated app acts for: authority is
+     * then the intersection of both parties' grants, while authorship and
+     * `-own` resolve against the subject. See
+     * docs/spec/access-control.md § Enforcement: Stack.asEntity().
+     */
+    asEntity(entityId, opts = {}) {
+        this.assertOpen();
+        if (opts.onBehalfOf && !entityId) {
+            throw new StackPermissionError('An anonymous principal cannot act on behalf of an entity');
+        }
+        return new ScopedStack(this, entityId, opts.onBehalfOf ?? entityId, this.idTimestampSkewMsValue, this.adapter);
+    }
+    /**
+     * Scope to an authenticated session — what StackTokenStore.lookupToken()
+     * returns. Equivalent to asEntity(principalId, { onBehalfOf: subjectId }),
+     * and what a server should reach for at its request boundary.
      *
-     * Plain Stack methods are unscoped and skip permission checks entirely —
-     * correct for single-entity embedded use, where there's no requester
-     * distinct from the app itself. Use asEntity() when one Stack instance
-     * serves requests from multiple, possibly untrusted, entities (e.g. a
-     * multi-tenant API server).
+     * Both identities are DIDs, so passing them positionally leaves nothing
+     * to catch a swap, and a swapped pair is undetectable in the undelegated
+     * case where they are equal — it would surface only once delegation is in
+     * use, as authority no longer fenced by the app's grants and every write
+     * attributed to the app rather than the person. Taking the pair whole
+     * removes the order to get wrong. See
+     * docs/spec/access-control.md § Delegation: principal and subject.
      */
-    asEntity(entityId) {
-        return new ScopedStack(this, entityId);
+    forSession(session) {
+        return this.asEntity(session.principalId, { onBehalfOf: session.subjectId });
     }
     // -------------------------------------------------------
     // Types
     // -------------------------------------------------------
     /**
-     * Define and persist a new Type. Computes the schemaHash automatically.
-     * Should be called at app startup before creating any records of this type.
+     * Define and persist a Type; call at app startup before creating records
+     * of the type. Redefining an existing typeId is checked against the
+     * stored schema: identical is a no-op, a name-only change persists, and
+     * anything beyond additive evolution throws StackSchemaDriftError. See
+     * docs/spec/data-model.md § Schema drift detection.
      */
     async defineType(id, name, schema, opts = {}) {
+        this.assertOpen();
         const parsed = parseTypeId(id);
         if (!parsed) {
             throw new Error(`Invalid TypeId format: "${id}". Expected "namespace/name@version", e.g. "com.example.myapp/note@1".`);
         }
+        // Register this version even on the idempotent-no-op path —
+        // presentAtLatest()'s stale-writer detection depends on it.
+        const priorMax = this.maxDefinedVersion.get(parsed.baseId) ?? 0;
+        if (parsed.version > priorMax)
+            this.maxDefinedVersion.set(parsed.baseId, parsed.version);
         const schemaHash = await hashSchema(schema);
+        const existing = await this.getTypeCached(id);
+        if (existing) {
+            if (existing.schemaHash === schemaHash) {
+                if (existing.name === name)
+                    return existing;
+                // else: name-only change — falls through to the write below,
+                // schema/hash/createdAt all carried over unchanged.
+            }
+            else {
+                const violations = diffSchemas(existing.schema, schema);
+                if (violations.length > 0) {
+                    throw new StackSchemaDriftError(id, violations);
+                }
+            }
+        }
         const type = {
             id,
             baseId: parsed.baseId,
@@ -118,24 +530,32 @@ export class Stack {
             name,
             schema,
             schemaHash,
-            createdAt: new Date(),
+            createdAt: existing?.createdAt ?? new Date(),
             ...(opts.migratesFrom && { migratesFrom: opts.migratesFrom }),
         };
         await this.adapter.saveType(type);
+        this.typeCache.set(id, type);
         return type;
     }
     async getType(id) {
-        return this.adapter.getType(id);
+        this.assertOpen();
+        return this.getTypeCached(id);
     }
+    /** Refreshes typeCache wholesale — the explicit way to see a rename made by another writer. */
     async listTypes() {
-        return this.adapter.listTypes();
+        this.assertOpen();
+        const types = await this.adapter.listTypes();
+        for (const type of types)
+            this.typeCache.set(type.id, type);
+        return types;
     }
     /**
      * Check whether a record's type is compatible with a required schema.
      * Useful for duck-typed consumption across types.
      */
     async typeIsCompatible(typeId, requiredSchema) {
-        const type = await this.adapter.getType(typeId);
+        this.assertOpen();
+        const type = await this.getTypeCached(typeId);
         if (!type)
             return false;
         return isCompatible(type.schema, requiredSchema);
@@ -144,14 +564,13 @@ export class Stack {
     // Migration registry
     // -------------------------------------------------------
     /**
-     * Register a migration function between two adjacent Type versions.
-     * Call at app startup after defineType(). The library composes
-     * adjacent migrations into chains automatically.
-     *
-     * Migrations run in-memory — they do not write to the adapter unless
-     * you call migrateAll() explicitly.
+     * Register a migration function between two adjacent Type versions; call
+     * at app startup after defineType(). Runs in-memory — nothing is written
+     * until migrateAll(). Adjacent migrations are composed into chains
+     * automatically.
      */
     registerMigration(migration) {
+        this.assertOpen();
         if (this.migrations.has(migration.from)) {
             throw new StackMigrationError(`A migration from "${migration.from}" is already registered.`);
         }
@@ -197,17 +616,13 @@ export class Stack {
         return current;
     }
     /**
-     * Eagerly migrate all records of a type family to the latest version,
-     * committing the results to disk immediately.
-     *
-     * Normally migration is lazy — records are migrated in memory on read
-     * and written back only when next updated. Call migrateAll() when you
-     * want to commit all pending migrations in one deliberate pass, for
-     * example before a deployment or after a major schema change.
-     *
-     * Previous content is preserved in version history before each write.
+     * Eagerly migrate all records of a type family to the latest version —
+     * 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.
      */
     async migrateAll(baseTypeId) {
+        this.assertOpen();
         const types = await this.adapter.listTypes();
         const familyTypeIds = types.filter((t) => t.baseId === baseTypeId).map((t) => t.id);
         if (familyTypeIds.length === 0) {
@@ -221,22 +636,23 @@ export class Stack {
             const migrateFn = this.resolveMigrationPath(typeId, latestId);
             if (!migrateFn)
                 continue;
+            const latestType = await this.getTypeCached(latestId);
+            if (!latestType) {
+                throw new StackMigrationError(`migrateAll: target type "${latestId}" is not defined.`);
+            }
             let cursor;
             do {
                 const result = await this.adapter.queryRecords({
-                    filter: { typeId },
+                    filter: { typeId, includeDeleted: true },
                     limit: 100,
                     cursor,
                 });
                 for (const record of result.records) {
-                    await this.saveVersion(record);
-                    const migratedContent = migrateFn(record.content);
-                    await this.adapter.updateRecord(record.id, {
-                        typeId: latestId,
-                        content: migratedContent,
-                        updatedAt: new Date(),
-                        version: record.version + 1,
-                    });
+                    // 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
+                    // pass doesn't know each record's version going in.
+                    await this.commitMigrationChecked(record, latestId, migrateFn(record.content));
                     migrated++;
                 }
                 cursor = result.cursor ?? undefined;
@@ -249,19 +665,33 @@ export class Stack {
     // -------------------------------------------------------
     /**
      * 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(). See docs/spec/identity.md § Group.
      */
     async create(typeId, content, opts = {}) {
-        const type = await this.adapter.getType(typeId);
+        this.assertOpen();
+        const type = await this.getTypeCached(typeId);
         if (!type) {
             throw new Error(`Unknown type: "${typeId}". Call defineType() first.`);
         }
-        const errors = validateContent(content, type.schema);
+        const errors = [...validateReservedKeys(content), ...validateContent(content, type.schema)];
         if (errors.length > 0) {
             throw new StackValidationError(errors);
         }
+        assertContentSize(content, this.features.maxContentBytes, 'Content');
+        if (typeId === `${SYSTEM_TYPES.ATTACHMENT}@1`) {
+            await this.checkAttachmentMimeTypeOnCreate(content);
+        }
+        await this.checkBindingsOnCreate(typeId, content);
+        if (opts.id !== undefined)
+            validateRecordId(opts.id);
+        const associations = baseIdOf(typeId) === SYSTEM_TYPES.GROUP
+            ? stampGroupAdmin(opts.associations, opts.entityId ?? this.ownerEntityId)
+            : opts.associations;
         const now = new Date();
         const record = {
-            id: generateId(),
+            id: opts.id ?? generateId(),
             typeId,
             createdAt: now,
             updatedAt: now,
@@ -270,284 +700,937 @@ export class Stack {
             ...(opts.parentId && { parentId: opts.parentId }),
             ...(opts.entityId && { entityId: opts.entityId }),
             ...(opts.appId && { appId: opts.appId }),
+            ...(opts.principalId && { principalId: opts.principalId }),
             ...(opts.permissions?.length && { permissions: opts.permissions }),
-            ...(opts.associations?.length && { associations: opts.associations }),
+            ...(associations?.length && { associations }),
         };
         return this.adapter.createRecord(record);
     }
     /**
-     * Get a record by ID.
-     *
-     * If the record is on an older type version and a migration path is
-     * registered, the content is migrated in memory and returned at the
-     * latest type version — but nothing is written to disk. Migration is
-     * only persisted when the record is next updated via update().
-     *
-     * Pass { migrate: false } to get the raw stored record without migration.
+     * Apply the registered migration chain in memory, for presentAt:
+     * 'latest'. Never writes back. Throws StackMigrationError when the
+     * record's version can't be reconciled with what this instance has
+     * registered — the stale-writer case. See docs/spec/data-model.md
+     * § Type migrations.
+     */
+    presentAtLatest(record) {
+        const latestId = this.latestTypeId(record.typeId);
+        if (latestId !== record.typeId) {
+            // latestTypeId() found this by walking the same migration graph
+            // resolveMigrationPath() walks, from the same starting point, so a
+            // path is always resolvable here.
+            const migrateFn = this.resolveMigrationPath(record.typeId, latestId);
+            return { ...record, typeId: latestId, content: migrateFn(record.content) };
+        }
+        const parsed = parseTypeId(record.typeId);
+        const knownMax = parsed ? this.maxDefinedVersion.get(parsed.baseId) : undefined;
+        if (parsed && knownMax !== undefined && parsed.version !== knownMax) {
+            const direction = parsed.version > knownMax
+                ? `the record is newer than this app instance understands — update the app, or register the missing migrations`
+                : `no registered migration bridges the gap — call stack.registerMigration()`;
+            throw new StackMigrationError(`Record "${record.id}" is at "${record.typeId}", but this app instance has defined ` +
+                `up to "${parsed.baseId}@${knownMax}": ${direction}. Omit presentAt: "latest" to ` +
+                `read the record as stored.`);
+        }
+        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 = {}) {
+        this.assertOpen();
         const record = await this.adapter.getRecord(id);
         if (!record)
             return null;
-        const shouldMigrate = opts.migrate !== false;
-        if (!shouldMigrate)
-            return record;
-        const latestId = this.latestTypeId(record.typeId);
-        if (latestId === record.typeId)
-            return record;
-        const migrateFn = this.resolveMigrationPath(record.typeId, latestId);
-        if (!migrateFn) {
-            console.warn(`[Stack] No migration path from "${record.typeId}" to "${latestId}" for record "${id}". ` +
-                `Returning raw record. Register migrations with stack.registerMigration().`);
-            return record;
-        }
-        return {
-            ...record,
-            typeId: latestId,
-            content: migrateFn(record.content),
-        };
+        return opts.presentAt === 'latest' ? this.presentAtLatest(record) : record;
     }
     /**
-     * Update a record's content. Accepts a partial content object — only the
-     * fields provided are changed. Omitted fields retain their current values.
-     *
-     * To remove an optional field, set it explicitly to null:
-     *   stack.update(id, { title: null })  // removes 'title' from content
-     *
-     * If the record is on an older type version, its content is migrated
-     * in memory first, then the patch is applied. The updated record is
-     * written at the latest type version — this is when lazy migration
-     * is committed to disk.
-     *
-     * Validates the merged result against the type's schema. Saves the
-     * previous state to version history before updating.
-     *
-     * For association or permission changes, use associate(), dissociate(),
-     * and setPermissions() instead.
+     * 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.
      */
-    async update(id, content) {
+    async update(id, content, opts = {}) {
+        this.assertOpen();
         const existing = await this.adapter.getRecord(id);
         if (!existing) {
             throw new StackNotFoundError(`Record not found: "${id}"`);
         }
-        // Resolve the latest type version and migrate existing content
-        // in memory before applying the patch. This is when lazy migration
-        // from get() gets committed to disk.
-        const latestTypeId = this.latestTypeId(existing.typeId);
-        const migrateFn = this.resolveMigrationPath(existing.typeId, latestTypeId);
-        const existingContent = migrateFn ? migrateFn(existing.content) : existing.content;
-        const type = await this.adapter.getType(latestTypeId);
+        this.checkIfVersion(existing, opts.ifVersion);
+        const type = await this.getTypeCached(existing.typeId);
         if (!type) {
-            throw new Error(`Unknown type: "${latestTypeId}"`);
-        }
-        // Shallow merge: start with (migrated) existing content, apply changes.
-        // null values mean "delete this field" (RFC 7396 / JSON Merge Patch).
-        const merged = { ...existingContent };
-        for (const [key, value] of Object.entries(content)) {
-            if (value === null) {
-                delete merged[key];
-            }
-            else {
-                merged[key] = value;
-            }
+            throw new Error(`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, so a check on
+        // the merged result would never see it. See validateReservedKeys().
+        const patchErrors = validateReservedKeys(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.maxContentBytes, '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);
         }
-        // Snapshot the raw stored state before overwriting
-        await this.saveVersion(existing);
-        return this.adapter.updateRecord(id, {
-            typeId: latestTypeId,
-            content: merged,
-            updatedAt: new Date(),
-            version: existing.version + 1,
+        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);
+        }
+        return this.adapter.patchContent(id, content, {
+            expectedVersion: opts.ifVersion,
+            snapshot: this.buildVersionSnapshot(existing),
         });
     }
     /**
-     * Add an association to a record.
+     * Add an association to a record. Snapshots the record's prior state and
+     * bumps version, same as update() — 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.
      */
-    async associate(id, association) {
-        return this.adapter.associate(id, association);
+    async associate(id, association, opts = {}) {
+        this.assertOpen();
+        const existing = await this.adapter.getRecord(id);
+        if (!existing) {
+            throw new StackNotFoundError(`Record not found: "${id}"`);
+        }
+        this.checkIfVersion(existing, opts.ifVersion);
+        if ((existing.associations ?? []).some((a) => associationEqual(a, association)))
+            return;
+        await this.adapter.associate(id, association, {
+            expectedVersion: opts.ifVersion,
+            snapshot: this.buildVersionSnapshot(existing),
+        });
     }
     /**
-     * Remove an association from a record.
-     * Matched by kind, label, and payload. No-op if not found.
+     * Remove an association from a record. Snapshots and bumps version, same
+     * as associate(). Matched by kind, label, and payload. No-op if not found.
      */
-    async dissociate(id, association) {
-        return this.adapter.dissociate(id, association);
+    async dissociate(id, association, opts = {}) {
+        this.assertOpen();
+        const existing = await this.adapter.getRecord(id);
+        if (!existing) {
+            throw new StackNotFoundError(`Record not found: "${id}"`);
+        }
+        this.checkIfVersion(existing, opts.ifVersion);
+        if (!(existing.associations ?? []).some((a) => associationEqual(a, association)))
+            return;
+        await this.adapter.dissociate(id, association, {
+            expectedVersion: opts.ifVersion,
+            snapshot: this.buildVersionSnapshot(existing),
+        });
     }
     /**
-     * Replace all permissions on a record.
-     * Pass an empty array to make the record private (the default).
+     * 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.
      */
-    async setPermissions(id, permissions) {
+    async setPermissions(id, permissions, opts = {}) {
+        this.assertOpen();
         const existing = await this.adapter.getRecord(id);
         if (!existing) {
             throw new StackNotFoundError(`Record not found: "${id}"`);
         }
-        await this.adapter.updateRecord(id, { permissions });
+        this.checkIfVersion(existing, opts.ifVersion);
+        if (permissionsEqual(existing.permissions ?? [], permissions))
+            return;
+        await this.adapter.setPermissions(id, permissions, {
+            expectedVersion: opts.ifVersion,
+            snapshot: this.buildVersionSnapshot(existing),
+        });
     }
     /**
-     * Soft-delete a record (default) or hard-delete it permanently.
-     * Soft-deleted records are excluded from queries unless includeDeleted is set.
-     * Hard-deleted records and all their version history are permanently removed.
+     * Soft-delete a record (default) or hard-delete it permanently, removing
+     * the record and its version history. Soft delete snapshots and bumps
+     * version; a no-op if already deleted. `_config` is never deletable
+     * (docs/spec.md § The `_config` record). See docs/spec/versioning.md
+     * § Deletion.
      */
     async delete(id, opts = {}) {
-        return this.adapter.deleteRecord(id, opts);
+        this.assertOpen();
+        if (id === SYSTEM_TYPES.CONFIG) {
+            throw new StackConflictError("Cannot delete the _config record: it holds the stack's identity and is required for every permission check.");
+        }
+        if (opts.hard) {
+            return this.adapter.deleteRecord(id, { hard: true, expectedVersion: opts.ifVersion });
+        }
+        const existing = await this.adapter.getRecord(id);
+        if (!existing) {
+            throw new StackNotFoundError(`Record not found: "${id}"`);
+        }
+        this.checkIfVersion(existing, opts.ifVersion);
+        if (existing.deletedAt)
+            return;
+        await this.adapter.deleteRecord(id, {
+            expectedVersion: opts.ifVersion,
+            snapshot: this.buildVersionSnapshot(existing),
+        });
+    }
+    /**
+     * Reverse a soft delete. Idempotent — undeleting a record that isn't
+     * deleted returns it unchanged. Hard-deleted records are gone, so this
+     * throws StackNotFoundError for them just like any other missing record.
+     * Snapshots and bumps version, same as delete().
+     */
+    async undelete(id, opts = {}) {
+        this.assertOpen();
+        const existing = await this.adapter.getRecord(id);
+        if (!existing) {
+            throw new StackNotFoundError(`Record not found: "${id}"`);
+        }
+        this.checkIfVersion(existing, opts.ifVersion);
+        if (!existing.deletedAt)
+            return existing;
+        return this.adapter.undeleteRecord(id, {
+            expectedVersion: opts.ifVersion,
+            snapshot: this.buildVersionSnapshot(existing),
+        });
     }
     /**
-     * Query records. See StackQuery for filter, sort, and pagination options.
+     * 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 = {}) {
-        const limit = query.limit !== undefined ? Math.min(query.limit, MAX_QUERY_LIMIT) : undefined;
-        return this.adapter.queryRecords(limit !== undefined ? { ...query, limit } : query);
+        this.assertOpen();
+        const { presentAt, filter, limit: rawLimit, ...rest } = query;
+        assertQueryCapabilities(filter, this.adapter.capabilities);
+        const limit = rawLimit !== undefined ? Math.min(rawLimit, MAX_QUERY_LIMIT) : undefined;
+        const resolvedFilter = await this.resolveBaseIdFilter(filter);
+        if (resolvedFilter === EMPTY_FAMILY) {
+            return { records: [], cursor: null, total: 0 };
+        }
+        const result = await this.adapter.queryRecords({
+            ...rest,
+            ...(resolvedFilter !== undefined && { filter: resolvedFilter }),
+            ...(limit !== undefined && { limit }),
+        });
+        if (presentAt !== 'latest')
+            return result;
+        return { ...result, records: result.records.map((r) => this.presentAtLatest(r)) };
+    }
+    /**
+     * Resolve filter.baseId into a concrete typeId set (intersected with
+     * filter.typeId when both are given), so adapters never need their own
+     * baseId concept. Returns EMPTY_FAMILY when the resolved set is empty so
+     * the caller can short-circuit without an adapter round trip.
+     */
+    async resolveBaseIdFilter(filter) {
+        if (filter?.baseId === undefined)
+            return filter;
+        const { baseId, typeId, ...rest } = filter;
+        const requestedBaseIds = Array.isArray(baseId) ? baseId : [baseId];
+        const types = await this.adapter.listTypes();
+        const familyTypeIds = types.filter((t) => requestedBaseIds.includes(t.baseId)).map((t) => t.id);
+        const resolvedTypeIds = typeId === undefined
+            ? familyTypeIds
+            : familyTypeIds.filter((id) => Array.isArray(typeId) ? typeId.includes(id) : typeId === id);
+        if (resolvedTypeIds.length === 0)
+            return EMPTY_FAMILY;
+        return { ...rest, typeId: resolvedTypeIds };
     }
     // -------------------------------------------------------
     // Versions
     // -------------------------------------------------------
     async getVersions(id) {
+        this.assertOpen();
         return this.adapter.getVersions(id);
     }
     async getVersion(id, version) {
+        this.assertOpen();
         return this.adapter.getVersion(id, version);
     }
     /**
-     * Restore a record to a previous version by creating a new version
-     * with the old content. Never rewrites history.
+     * 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.
      */
-    async restoreVersion(id, version) {
+    async restoreVersion(id, version, opts = {}) {
+        this.assertOpen();
         const existing = await this.adapter.getRecord(id);
         if (!existing) {
             throw new StackNotFoundError(`Record not found: "${id}"`);
         }
+        this.checkIfVersion(existing, opts.ifVersion);
         const target = await this.adapter.getVersion(id, version);
         if (!target) {
             throw new StackNotFoundError(`Version ${version} not found for record "${id}"`);
         }
-        // Snapshot current state before restoring
-        await this.saveVersion(existing);
-        return this.adapter.updateRecord(id, {
-            content: target.content,
-            updatedAt: new Date(),
-            version: existing.version + 1,
+        const type = await this.getTypeCached(target.typeId);
+        if (!type) {
+            throw new Error(`Unknown type: "${target.typeId}"`);
+        }
+        const errors = validateContent(target.content, type.schema);
+        if (errors.length > 0) {
+            throw new StackValidationError(errors);
+        }
+        if (id === SYSTEM_TYPES.CONFIG) {
+            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
+        // 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]);
+        }
+        return this.adapter.restoreVersion(id, version, {
+            expectedVersion: opts.ifVersion,
+            snapshot: this.buildVersionSnapshot(existing),
         });
     }
-    // -------------------------------------------------------
-    // Attachments
-    // -------------------------------------------------------
     /**
-     * Store raw bytes and return the content-addressed file ID.
-     * Does not create an _attachment@1 record — use putAttachment() or
-     * ScopedStack.putAttachment() for the full upload flow.
+     * 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
+     * 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`
+     * precondition every version-bumping mutation takes — checked atomically
+     * at the adapter, not here (see docs/spec/versioning.md § Optimistic
+     * concurrency).
+     *
+     * Because `content` is a full replacement written under a new `typeId`,
+     * this is create-shaped at the destination *and* update-shaped over the
+     * 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.
      */
-    async putAttachmentBytes(data) {
-        return this.adapter.putAttachment(data);
+    async commitMigration(id, toTypeId, content, opts = {}) {
+        this.assertOpen();
+        const existing = await this.adapter.getRecord(id);
+        if (!existing) {
+            throw new StackNotFoundError(`Record not found: "${id}"`);
+        }
+        this.checkIfVersion(existing, opts.ifVersion);
+        return this.commitMigrationChecked(existing, toTypeId, content, opts.ifVersion);
     }
     /**
-     * Store bytes and create an _attachment@1 metadata record (owner-attributed,
-     * no entityId). Use ScopedStack.putAttachment() when the uploader is a
-     * specific entity rather than the stack owner.
+     * The checked migration write, shared by commitMigration() and
+     * migrateAll(). Takes the record already in hand rather than an id: a
+     * batch pass holds each record from its own query page, and re-fetching
+     * per record would cost a read apiece for nothing.
+     *
+     * Both callers owe the same checks. migrateAll()'s content comes from a
+     * registered Migration function rather than a request body, but "app
+     * code" is not a trust boundary here — the app calling commitMigration()
+     * is the same app that registered the function, and neither may move a
+     * DID binding or repoint an attachment. registerMigration() also places
+     * no constraint on `from` and `to` sharing a baseId, so a migration path
+     * can cross type families; family-crossing is exactly what the checks
+     * below care about.
      */
-    async putAttachment(data, mimeType, filename) {
-        const fileId = await this.putAttachmentBytes(data);
-        await this.create(`${SYSTEM_TYPES.ATTACHMENT}@1`, {
-            fileId,
-            mimeType,
-            size: data.byteLength,
-            ...(filename && { filename }),
+    async commitMigrationChecked(existing, toTypeId, content, ifVersion) {
+        const id = existing.id;
+        const type = await this.getTypeCached(toTypeId);
+        if (!type) {
+            throw new Error(`Unknown type: "${toTypeId}". Call defineType() first.`);
+        }
+        const errors = [...validateReservedKeys(content), ...validateContent(content, type.schema)];
+        if (errors.length > 0) {
+            throw new StackValidationError(errors);
+        }
+        assertContentSize(content, this.features.maxContentBytes, 'Content');
+        const fromFamily = baseIdOf(existing.typeId);
+        const toFamily = baseIdOf(toTypeId);
+        const existingContent = existing.content;
+        // A `_group` record's `admin` roster entry is stamped by create(), the
+        // single site that does it — migrate cannot, since the adapter's
+        // commitMigration() writes `typeId` and `content` alone and leaves
+        // associations untouched. Minting one here would produce a group with
+        // an empty roster, manageable by nobody but the owner, so migrating
+        // *into* the family is refused. Version-to-version stays open and
+        // carries the existing roster with it.
+        if (toFamily === SYSTEM_TYPES.GROUP && fromFamily !== SYSTEM_TYPES.GROUP) {
+            throw new StackConflictError('Cannot migrate a record into _group: a group’s admin roster is stamped at creation. ' +
+                'Create the group instead.');
+        }
+        if (fromFamily === SYSTEM_TYPES.ATTACHMENT) {
+            this.checkAttachmentImmutableOnMigrate(existingContent, content);
+        }
+        else if (toFamily === SYSTEM_TYPES.ATTACHMENT) {
+            // A record arriving from outside the family stakes a fresh claim on
+            // its fileId, exactly as create() does — so it owes create()'s check.
+            await this.checkAttachmentMimeTypeOnCreate(content);
+        }
+        await this.checkBindingsOnMigrate(existing.typeId, toTypeId, id, existingContent, content);
+        if (id === SYSTEM_TYPES.CONFIG) {
+            this.checkConfigEntityIdUnchanged(existing.content.entityId, content.entityId);
+        }
+        return this.adapter.commitMigration(id, toTypeId, content, {
+            expectedVersion: ifVersion,
+            snapshot: this.buildVersionSnapshot(existing),
         });
-        return fileId;
     }
-    async getAttachment(fileId) {
-        return this.adapter.getAttachment(fileId);
+    /** Uniqueness for every unique binding field a newly created card claims. */
+    async checkBindingsOnCreate(typeId, content) {
+        const family = baseIdOf(typeId);
+        for (const field of uniqueBindingFieldsOf(family)) {
+            await this.checkBindingUnique(family, field, content[field]);
+        }
     }
     /**
-     * Delete an attachment's bytes and its _attachment@1 metadata record(s).
-     * Throws StackConflictError if any record in the stack still references the file.
-     * Throws StackNotFoundError if neither metadata records nor bytes exist.
+     * 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
+     * card already holds.
      */
-    async deleteAttachment(fileId) {
-        const refResult = await this.query({ filter: { attachmentFileId: fileId }, limit: 1 });
-        if (refResult.records.length > 0) {
-            throw new StackConflictError('Attachment is still referenced by one or more records');
-        }
-        const metaResult = await this.query({
-            filter: {
-                typeId: `${SYSTEM_TYPES.ATTACHMENT}@1`,
-                ...(this.features.contentFieldQuery && { content: { fileId } }),
-            },
-        });
-        const metaRecords = this.features.contentFieldQuery
-            ? metaResult.records
-            : metaResult.records.filter((r) => r.content.fileId === fileId);
-        if (!metaRecords.length) {
-            try {
-                await this.adapter.getAttachment(fileId);
+    async checkBindingsOnUpdate(typeId, id, patch, existing, merged) {
+        const family = baseIdOf(typeId);
+        const unique = uniqueBindingFieldsOf(family);
+        for (const field of bindingFieldsOf(family)) {
+            if (!(field in patch))
+                continue;
+            this.checkBindingImmutable(family, field, existing[field], merged[field]);
+            if (unique.includes(field)) {
+                await this.checkBindingUnique(family, field, merged[field], id);
             }
-            catch {
-                throw new StackNotFoundError(`Attachment not found: "${fileId}"`);
+        }
+    }
+    /**
+     * Bindings across a migration. `content` is a full replacement rather
+     * than a patch, so there is no "field absent from the patch" case to
+     * exempt: every binding field either keeps its value, moves to a new
+     * one, or is shed by omission — and immutability refuses the last two
+     * whichever family they happen in. Asked across the union of the two
+     * families' binding fields, so a card can neither shed its DID by
+     * migrating out of `_entity`/`_app` nor pick one up on the way in.
+     *
+     * Uniqueness is asked only of the destination family, which is where the
+     * record's claim lives once the write lands, and excludes the record
+     * itself — re-sending the value it already holds claims nothing.
+     * See docs/spec/identity.md § DID bindings.
+     */
+    async checkBindingsOnMigrate(fromTypeId, toTypeId, id, existing, content) {
+        const fromFamily = baseIdOf(fromTypeId);
+        const toFamily = baseIdOf(toTypeId);
+        const checked = new Set();
+        for (const family of fromFamily === toFamily ? [fromFamily] : [fromFamily, toFamily]) {
+            for (const field of bindingFieldsOf(family)) {
+                if (checked.has(field))
+                    continue;
+                checked.add(field);
+                this.checkBindingImmutable(family, field, existing[field], content[field]);
             }
         }
-        for (const record of metaRecords) {
-            await this.delete(record.id, { hard: true });
+        for (const field of uniqueBindingFieldsOf(toFamily)) {
+            await this.checkBindingUnique(toFamily, field, content[field], id);
         }
-        await this.adapter.deleteAttachment(fileId);
     }
-    // -------------------------------------------------------
-    // Lifecycle
-    // -------------------------------------------------------
     /**
-     * Flush any pending writes to the underlying storage.
-     * For adapters that write immediately (SQLite, JSON), this is a no-op.
-     * For the API adapter, this commits the offline write queue to the server.
-     * Safe to call at any time — always resolves, never rejects on its own.
+     * A unique binding field is what a lookup resolves *by* — a record's
+     * `principalId` by `_app.did`, its `entityId` by `_entity.did`. Two cards
+     * claiming one value would leave that lookup without a single answer, and
+     * ambiguity is all an impersonating card needs. Enforced here rather than
+     * by schema, since uniqueness is a property of the set, not of the value.
+     * Called by the paths that can introduce a binding: create and update.
+     *
+     * Short-circuits on the first clash rather than materialising the family,
+     * so a stack whose `_entity` family is larger than a single scan settles
+     * the common case — the value is already taken — without walking the rest.
+     *
+     * Read-then-write, so two creates racing on one value can both pass.
+     * Closing that properly means a unique index over a JSON field, which
+     * each adapter would enforce separately — a decision about where
+     * uniqueness lives, not a local fix.
+     * See docs/spec/identity.md § DID bindings.
      */
-    async flush() {
-        await this.adapter.flush?.();
+    async checkBindingUnique(family, field, value, excludeId) {
+        if (typeof value !== 'string' || value === '')
+            return;
+        const clash = await findFirstMatch((q) => this.query(q), {
+            filter: {
+                baseId: family,
+                includeDeleted: true,
+                ...(this.features.contentFieldQuery && { content: { [field]: value } }),
+            },
+        }, (r) => r.id !== excludeId && r.content[field] === value);
+        if (clash) {
+            throw new StackConflictError(`Another ${family} record already claims the ${field} "${value}"`);
+        }
     }
     /**
-     * Release any resources held by the adapter (connections, file handles, timers).
-     * Call this when the stack is no longer needed — especially important for the
-     * API adapter, which holds an open connection and retry timers.
-     * Safe to call even if the adapter has no resources to release.
+     * A binding is permanent once made: uniqueness stops a second card
+     * claiming a value, but only immutability stops an existing card being
+     * moved onto one, which reaches the same impersonation by another route.
+     * Adopting a value is therefore a one-way step, and a subject whose key
+     * changes gets a new card — matching identity.md's deferral of key
+     * rotation, where a new key is a new identity rather than the same one
+     * relabelled. See docs/spec/identity.md § DID bindings.
      */
-    async close() {
-        await this.adapter.close?.();
+    checkBindingImmutable(family, field, existing, next) {
+        if (typeof existing !== 'string' || existing === '')
+            return;
+        if (next === existing)
+            return;
+        throw new StackValidationError([
+            {
+                path: field,
+                message: `${field} is immutable once set; register a new ${family} record instead`,
+            },
+        ]);
     }
     // -------------------------------------------------------
-    // Grants
+    // Attachments
     // -------------------------------------------------------
     /**
-     * Create _grant records that allow entities to call ScopedStack.create()
-     * for specific record types. Pass null as entityId for a default grant
-     * that applies to any authenticated entity.
+     * mimeType is a property of the fileId, not the uploader's perspective:
+     * the first metadata record for a fileId fixes it, and a conflicting
+     * later upload is rejected. Cursor-walked so earlier records past page
+     * one are seen. See docs/spec/attachments.md § The `_attachment` record
+     * type.
      *
-     * The _grant@1 type is defined automatically on first use.
+     * Best-effort by construction — check-then-create with no storage-level
+     * uniqueness behind it, so two racing first uploads can both land on a
+     * concurrent server. What survives that race is the *resolution*: which
+     * record establishes the type is firstRecordedAttachment()'s total
+     * order, the same one a server serving Content-Type applies, so both
+     * sides name the same winner however many records exist.
      */
-    async grant(entityId, grants) {
-        const records = [];
-        for (const g of grants) {
-            records.push(await this.create(`${SYSTEM_TYPES.GRANT}@1`, { typeId: g.typeId, actions: g.actions }, entityId ? { entityId } : {}));
+    async checkAttachmentMimeTypeOnCreate(content) {
+        const { fileId, mimeType } = content;
+        if (typeof fileId !== 'string')
+            return; // schema validation already rejected this
+        const metadataTypeId = `${SYSTEM_TYPES.ATTACHMENT}@1`;
+        const results = await queryAllPages((q) => this.query(q), {
+            filter: {
+                typeId: metadataTypeId,
+                includeDeleted: true,
+                ...(this.features.contentFieldQuery && { content: { fileId } }),
+            },
+        });
+        const existing = this.features.contentFieldQuery
+            ? results
+            : results.filter((r) => r.content.fileId === fileId);
+        if (existing.length === 0)
+            return;
+        const first = firstRecordedAttachment(existing);
+        const establishedMimeType = first.content.mimeType;
+        if (mimeType !== establishedMimeType) {
+            // Deliberately does not name the established mimeType — that would
+            // confirm a guessed fileId's content type. See the anti-oracle rule
+            // in docs/spec/attachments.md.
+            throw new StackValidationError([
+                {
+                    path: 'mimeType',
+                    message: 'mimeType conflicts with the mimeType already established for this fileId',
+                },
+            ]);
         }
-        return records;
     }
-    // -------------------------------------------------------
-    // Private helpers
-    // -------------------------------------------------------
-    async seedSystemTypes() {
+    /**
+     * filename is the only mutable field on an _attachment@1 record; fileId,
+     * size, and mimeType are immutable (even a same-value mimeType rewrite
+     * is refused). The correction flow is delete + re-upload. See
+     * docs/spec/attachments.md § The `_attachment` record type.
+     */
+    checkAttachmentImmutableFields(patch, existing, merged) {
+        const errors = [];
+        if (Object.prototype.hasOwnProperty.call(patch, 'mimeType')) {
+            errors.push({
+                path: 'mimeType',
+                message: 'mimeType is immutable after creation; delete and re-upload to change it',
+            });
+        }
+        if (Object.prototype.hasOwnProperty.call(patch, 'fileId') &&
+            merged.fileId !== existing.fileId) {
+            errors.push({ path: 'fileId', message: 'fileId is immutable' });
+        }
+        if (Object.prototype.hasOwnProperty.call(patch, 'size') && merged.size !== existing.size) {
+            errors.push({ path: 'size', message: 'size is immutable' });
+        }
+        if (errors.length > 0) {
+            throw new StackValidationError(errors);
+        }
+    }
+    /**
+     * The same immutability checkAttachmentImmutableFields() enforces, asked
+     * value-wise instead of presence-wise: a migration replaces content
+     * wholesale, so it necessarily re-sends `mimeType`, `fileId` and `size`
+     * (all required) and a presence check would refuse every migration. Only
+     * an actual change is a violation.
+     *
+     * Repointing `fileId` is the one that matters most: an `_attachment@1`
+     * record naming a fileId is what canAccessFile()'s uploader clause reads,
+     * so moving an existing record onto another file's hash is a route to
+     * bytes the record's author never uploaded.
+     */
+    checkAttachmentImmutableOnMigrate(existing, next) {
+        const errors = [];
+        if (next.mimeType !== existing.mimeType) {
+            errors.push({
+                path: 'mimeType',
+                message: 'mimeType is immutable after creation; delete and re-upload to change it',
+            });
+        }
+        if (next.fileId !== existing.fileId) {
+            errors.push({ path: 'fileId', message: 'fileId is immutable' });
+        }
+        if (next.size !== existing.size) {
+            errors.push({ path: 'size', message: 'size is immutable' });
+        }
+        if (errors.length > 0) {
+            throw new StackValidationError(errors);
+        }
+    }
+    /**
+     * `_config.entityId` defines stack ownership; neither update() nor
+     * restoreVersion() may change it. A conflict with stack integrity, not a
+     * schema violation — hence StackConflictError. See docs/spec.md § The
+     * `_config` record.
+     */
+    checkConfigEntityIdUnchanged(existingEntityId, newEntityId) {
+        if (newEntityId !== existingEntityId) {
+            throw new StackConflictError('Cannot change _config.entityId: it defines stack ownership. ' +
+                'Ownership transfer is not a supported operation.');
+        }
+    }
+    /**
+     * Store bytes and create an _attachment@1 metadata record (owner-
+     * attributed, no entityId), returning that record — `content.fileId`
+     * addresses the bytes, `id` addresses the metadata. Delegates to the
+     * adapter's atomic putAttachmentWithMetadata() when implemented, trusting
+     * the returned record as backend-authoritative; otherwise falls back to
+     * bytes-then-create(). See docs/spec/wire-format.md § Attachments.
+     */
+    async putAttachment(data, mimeType, filename, appId) {
+        this.assertOpen();
+        assertAttachmentSize(data.byteLength, this.features.maxAttachmentBytes);
+        if (this.adapter.putAttachmentWithMetadata) {
+            const record = await this.adapter.putAttachmentWithMetadata(data, mimeType, filename, appId);
+            return record;
+        }
+        const fileId = await this.adapter.putAttachment(data);
+        return this.create(`${SYSTEM_TYPES.ATTACHMENT}@1`, {
+            fileId,
+            mimeType,
+            size: data.byteLength,
+            ...(filename && { filename }),
+        }, { appId });
+    }
+    async getAttachment(fileId) {
+        this.assertOpen();
+        return this.adapter.getAttachment(fileId);
+    }
+    /**
+     * Delete an attachment's bytes and its _attachment@1 metadata record(s).
+     * Throws StackConflictError if any record in the stack still references the file.
+     * Throws StackNotFoundError if neither metadata records nor bytes exist.
+     */
+    async deleteAttachment(fileId) {
+        this.assertOpen();
+        const metadataTypeId = `${SYSTEM_TYPES.ATTACHMENT}@1`;
+        const deletedRecordIds = this.adapter.deleteUnreferencedAttachmentRecords
+            ? await this.adapter.deleteUnreferencedAttachmentRecords(fileId, metadataTypeId)
+            : await this.deleteUnreferencedAttachmentRecordsFallback(fileId, metadataTypeId);
+        if (!deletedRecordIds.length) {
+            try {
+                await this.adapter.getAttachment(fileId);
+            }
+            catch {
+                throw new StackNotFoundError(`Attachment not found: "${fileId}"`);
+            }
+        }
+        await this.adapter.deleteAttachment(fileId);
+    }
+    /**
+     * Non-atomic fallback for adapters that don't implement
+     * deleteUnreferencedAttachmentRecords(): a concurrent associate() can
+     * race between the reference check below and the deletes it guards.
+     */
+    async deleteUnreferencedAttachmentRecordsFallback(fileId, metadataTypeId) {
+        // A soft-deleted record still counts as a reference — it must find its
+        // attachments intact on undelete. See docs/spec/attachments.md
+        // § Deleting attachments.
+        const refResult = await this.query({
+            filter: { attachmentFileId: fileId, includeDeleted: true },
+            limit: 1,
+        });
+        if (refResult.records.length > 0) {
+            throw new StackConflictError('Attachment is still referenced by one or more records');
+        }
+        // Cursor-walk with includeDeleted: metadata past page one, or soft-
+        // deleted, must be cleaned up too — not left pointing at deleted bytes.
+        const metaResults = await queryAllPages((q) => this.query(q), {
+            filter: {
+                typeId: metadataTypeId,
+                includeDeleted: true,
+                ...(this.features.contentFieldQuery && { content: { fileId } }),
+            },
+        });
+        const metaRecords = this.features.contentFieldQuery
+            ? metaResults
+            : metaResults.filter((r) => r.content.fileId === fileId);
+        for (const record of metaRecords) {
+            await this.delete(record.id, { hard: true });
+        }
+        return metaRecords.map((r) => r.id);
+    }
+    /**
+     * Sweep for attachment bytes unreachable from any record — live or
+     * soft-deleted — and delete bytes + metadata. Deletion goes through
+     * deleteAttachment(), so a file re-referenced by sweep time is skipped,
+     * not a failure. See docs/spec/attachments.md § Garbage collection.
+     */
+    async collectAttachmentGarbage(opts = {}) {
+        this.assertOpen();
+        const graceMs = opts.graceMs ?? DEFAULT_GC_GRACE_MS;
+        const dryRun = opts.dryRun ?? false;
+        const now = Date.now();
+        const metadataTypeId = `${SYSTEM_TYPES.ATTACHMENT}@1`;
+        const metaRecords = await queryAllPages((q) => this.query(q), {
+            filter: { typeId: metadataTypeId, includeDeleted: true },
+        });
+        // Newest metadata record's createdAt per fileId, and its size (constant
+        // across records sharing a fileId, since content-addressing guarantees
+        // identical bytes) — used for the grace check and reclaimedBytes.
+        const metaByFile = new Map();
+        for (const record of metaRecords) {
+            const content = record.content;
+            const createdAt = record.createdAt.getTime();
+            const existing = metaByFile.get(content.fileId);
+            if (!existing || createdAt > existing.newestAt) {
+                metaByFile.set(content.fileId, { newestAt: createdAt, size: content.size });
+            }
+        }
+        // Bare-bytes orphans: blobs with zero metadata records, only
+        // discoverable if the blob adapter implements listFiles().
+        const blobByFile = new Map();
+        if (this.adapter.listFiles) {
+            for (const file of await this.adapter.listFiles()) {
+                blobByFile.set(file.fileId, { modifiedAt: file.modifiedAt.getTime(), size: file.size });
+            }
+        }
+        const candidateFileIds = new Set([...metaByFile.keys(), ...blobByFile.keys()]);
+        const deleted = [];
+        let reclaimedBytes = 0;
+        for (const fileId of candidateFileIds) {
+            const refResult = await this.query({
+                filter: { attachmentFileId: fileId, includeDeleted: true },
+                limit: 1,
+            });
+            if (refResult.records.length > 0)
+                continue;
+            const meta = metaByFile.get(fileId);
+            const blob = blobByFile.get(fileId);
+            const newestAt = meta?.newestAt ?? blob?.modifiedAt;
+            if (newestAt !== undefined && now - newestAt < graceMs)
+                continue;
+            const size = meta?.size ?? blob?.size ?? 0;
+            if (dryRun) {
+                deleted.push(fileId);
+                reclaimedBytes += size;
+                continue;
+            }
+            try {
+                await this.deleteAttachment(fileId);
+            }
+            catch (err) {
+                // Raced with a new reference, or another sweep/call already removed
+                // it — not a sweep failure, just move on to the next candidate.
+                if (err instanceof StackConflictError || err instanceof StackNotFoundError)
+                    continue;
+                throw err;
+            }
+            deleted.push(fileId);
+            reclaimedBytes += size;
+        }
+        return { deleted, reclaimedBytes };
+    }
+    // -------------------------------------------------------
+    // Lifecycle
+    // -------------------------------------------------------
+    /**
+     * Flush pending writes to the underlying storage. A no-op for adapters
+     * that commit on every call (SQLite, the API adapter); meaningful for
+     * ones that buffer, and for checkpointing a stack that stays open —
+     * close() covers the teardown case on its own.
+     */
+    async flush() {
+        this.assertOpen();
+        await this.adapter.flush?.();
+    }
+    /**
+     * Flush, then release any resources the adapter holds (connections, file
+     * handles, lock files). A failed flush still releases them before it
+     * propagates: an unwritable stack must not also leak a lock file.
+     * See docs/spec/adapters.md § Lifecycle.
+     */
+    async close() {
+        if (this.closed)
+            return;
+        // Marked closed up front so a failed flush can't leave the stack
+        // half-open and invite a second close() onto an already-closed adapter.
+        // Flushes through the adapter directly, past the now-tripped guard.
+        this.closed = true;
+        try {
+            await this.adapter.flush?.();
+        }
+        finally {
+            await this.adapter.close?.();
+        }
+    }
+    /**
+     * Throws once close() has run. Public only so ScopedStack can gate the
+     * one path it takes to the adapter directly; not an app-facing API.
+     */
+    assertOpen() {
+        if (this.closed)
+            throw new StackClosedError();
+    }
+    // -------------------------------------------------------
+    // Grants
+    // -------------------------------------------------------
+    /**
+     * Create _grant records authorizing entities to act on records of
+     * specific types; null entityId writes a default grant (any
+     * authenticated entity).
+     *
+     * Granting an **app** a `-own` action does not contain it the way the
+     * suffix suggests: when that app acts for someone, `-own` is read as the
+     * bare verb and the subject decides which records are in reach, so in a
+     * personal stack — where nearly every record is owner-authored — a
+     * delegated `read-own` is close to `read-any`. Grant an app the types it
+     * needs, not the suffix that looks narrowest. See
+     * docs/spec/access-control.md § Delegation: principal and subject.
+     *
+     * The grantee lives in content.granteeEntityId,
+     * not record.entityId. See docs/spec/access-control.md § Type-level
+     * grants.
+     */
+    async grant(entityId, grants) {
+        this.assertOpen();
+        this.checkGrantsValid(grants);
+        const records = [];
+        for (const g of grants) {
+            records.push(await this.create(`${SYSTEM_TYPES.GRANT}@1`, {
+                typeId: g.typeId,
+                actions: g.actions,
+                ...(entityId && { granteeEntityId: entityId }),
+            }));
+        }
+        return records;
+    }
+    /**
+     * List _grant records. Omit `entityId` for all grants; pass null for
+     * only default grants; pass a specific entityId for the grants that
+     * currently apply to that entity (ones naming them, plus every default
+     * grant) — the same resolution hasGrant() uses.
+     */
+    async listGrants(entityId) {
+        this.assertOpen();
+        const all = await queryAllPages((q) => this.query(q), {
+            filter: { typeId: `${SYSTEM_TYPES.GRANT}@1` },
+        });
+        if (entityId === undefined)
+            return all;
+        return all.filter((r) => {
+            const granteeEntityId = r.content.granteeEntityId;
+            return entityId === null
+                ? !granteeEntityId
+                : !granteeEntityId || granteeEntityId === entityId;
+        });
+    }
+    /**
+     * The inverse of grant(): soft-deletes _grant records matching `entityId`
+     * (null for default grants) and each `{ typeId, actions }` pair, at the
+     * same granularity grant() writes. A soft delete like any other — the
+     * owner can undelete a revocation.
+     */
+    async revoke(entityId, grants) {
+        this.assertOpen();
+        const all = await queryAllPages((q) => this.query(q), {
+            filter: { typeId: `${SYSTEM_TYPES.GRANT}@1` },
+        });
+        for (const g of grants) {
+            const familyId = baseIdOf(g.typeId);
+            const actionSet = new Set(g.actions);
+            const matches = all.filter((r) => {
+                const c = r.content;
+                if (baseIdOf(c.typeId) !== familyId)
+                    return false;
+                if ((c.granteeEntityId ?? null) !== entityId)
+                    return false;
+                return c.actions.length === actionSet.size && c.actions.every((a) => actionSet.has(a));
+            });
+            for (const match of matches) {
+                await this.delete(match.id);
+            }
+        }
+    }
+    // -------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------
+    /**
+     * Validates the whole grant batch before any record is created, so a bad
+     * entry fails clean rather than leaving a partial set written. Actions
+     * must be known GrantAction values, typeIds must be well-formed, and the
+     * _grant/_config families are refused — see docs/spec/access-control.md
+     * § Type-level grants.
+     */
+    checkGrantsValid(grants) {
+        const errors = [];
+        grants.forEach((g, i) => {
+            g.actions.forEach((action, j) => {
+                if (!GRANT_ACTION_SET.has(action)) {
+                    errors.push({
+                        path: `grants[${i}].actions[${j}]`,
+                        message: `Unknown grant action "${action}"`,
+                    });
+                }
+            });
+            if (!isWellFormedTypeId(g.typeId)) {
+                errors.push({
+                    path: `grants[${i}].typeId`,
+                    message: `"${g.typeId}" is not a well-formed baseId or versioned TypeId (expected "baseId" or "baseId@version")`,
+                });
+                return;
+            }
+            if (UNGRANTABLE_SYSTEM_TYPES.has(baseIdOf(g.typeId))) {
+                const refused = [...UNGRANTABLE_SYSTEM_TYPES].join(', ');
+                errors.push({
+                    path: `grants[${i}].typeId`,
+                    message: `Cannot grant on "${baseIdOf(g.typeId)}": grants on ${refused} are refused to prevent privilege escalation`,
+                });
+            }
+        });
+        if (errors.length > 0) {
+            throw new StackValidationError(errors);
+        }
+    }
+    async seedSystemTypes() {
         await this.defineType(`${SYSTEM_TYPES.CONFIG}@1`, 'Config', {
             entityId: { kind: 'string', required: true },
-            timezone: { kind: 'string', required: true },
+            // Optional passthrough app metadata — see ConfigContent.timezone.
+            timezone: { kind: 'string' },
         });
         await this.defineType(`${SYSTEM_TYPES.ENTITY}@1`, 'Entity', {
+            did: { kind: 'string', required: true },
             name: { kind: 'string', required: true },
             handle: { kind: 'string' },
         });
         await this.defineType(`${SYSTEM_TYPES.APP}@1`, 'App', {
+            appId: { kind: 'string', required: true },
             name: { kind: 'string', required: true },
             version: { kind: 'string' },
+            did: { kind: 'string' },
         });
         await this.defineType(`${SYSTEM_TYPES.GROUP}@1`, 'Group', {
             name: { kind: 'string', required: true },
@@ -557,6 +1640,7 @@ export class Stack {
         await this.defineType(`${SYSTEM_TYPES.GRANT}@1`, 'Grant', {
             typeId: { kind: 'string', required: true },
             actions: { kind: 'array', items: { kind: 'string' }, required: true },
+            granteeEntityId: { kind: 'string' },
         });
         await this.defineType(`${SYSTEM_TYPES.ATTACHMENT}@1`, 'Attachment', {
             fileId: { kind: 'string', required: true },
@@ -565,131 +1649,514 @@ export class Stack {
             filename: { kind: 'string' },
         });
     }
-    async saveVersion(record) {
-        const version = {
+    /**
+     * Fast-fail for the ifVersion precondition using the already-fetched
+     * record. The adapter re-checks atomically at write time (the source of
+     * truth for concurrent writers) — this just skips validation and
+     * snapshotting work when the mismatch is already visible.
+     */
+    checkIfVersion(existing, ifVersion) {
+        if (ifVersion === undefined || existing.version === ifVersion)
+            return;
+        throw new StackVersionConflictError(`Record "${existing.id}" is at version ${existing.version}, expected ${ifVersion}`, existing.id, ifVersion, existing.version);
+    }
+    /**
+     * 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
+     * docs/spec/versioning.md § Version history.
+     */
+    buildVersionSnapshot(record) {
+        return {
             version: record.version,
+            typeId: record.typeId,
             content: record.content,
             updatedAt: record.updatedAt,
             ...(record.entityId && { entityId: record.entityId }),
+            associations: record.associations ?? [],
+            ...(record.permissions && { permissions: record.permissions }),
         };
-        await this.adapter.saveVersion(record.id, version);
     }
 }
 // -------------------------------------------------------
+// Equality helpers
+// -------------------------------------------------------
+/**
+ * Matches the SQLite adapter's association primary key (kind, label,
+ * file_id, related_id).
+ */
+function associationEqual(a, b) {
+    if (a.kind !== b.kind || a.label !== b.label)
+        return false;
+    if (a.kind === 'attachment' && b.kind === 'attachment')
+        return a.fileId === b.fileId;
+    if (a.kind === 'relationship' && b.kind === 'relationship')
+        return a.recordId === b.recordId;
+    return true;
+}
+function permissionEqual(a, b) {
+    if (a.access !== b.access)
+        return false;
+    if (a.access === 'public')
+        return true;
+    if (a.access === 'entity' && b.access === 'entity') {
+        return a.entityId === b.entityId && a.read === b.read && a.write === b.write;
+    }
+    if (a.access === 'group' && b.access === 'group') {
+        return a.groupId === b.groupId && a.role === b.role && a.read === b.read && a.write === b.write;
+    }
+    return false;
+}
+function permissionsEqual(a, b) {
+    return a.length === b.length && a.every((p, i) => permissionEqual(p, b[i]));
+}
+// -------------------------------------------------------
 // ScopedStack
 // -------------------------------------------------------
 /** Default page size used to fill a permission-filtered query result. */
 const DEFAULT_QUERY_LIMIT = 50;
 const MAX_QUERY_LIMIT = 1000;
 /**
- * A permission-enforcing view of a Stack for a single requester. Obtained
- * via `stack.asEntity(entityId)` — see there for when to use it.
+ * Ensures `creator` carries an `admin` relationship association, adding one
+ * if it's not already present. Used to bootstrap a `_group` record's first
+ * admin at create time.
+ */
+function stampGroupAdmin(associations, creator) {
+    const list = associations ?? [];
+    const alreadyAdmin = list.some((a) => a.kind === 'relationship' && a.label === 'admin' && a.recordId === creator);
+    if (alreadyAdmin)
+        return list;
+    return [...list, { kind: 'relationship', label: 'admin', recordId: creator }];
+}
+/**
+ * Drops a snapshot's `permissions` — owner-only audit data, never served
+ * to a non-owner history reader. `entityId` (change attribution) stays.
+ * See docs/spec/versioning.md § History access.
+ */
+function stripVersionPermissions(version) {
+    if (version.permissions === undefined)
+        return version;
+    const { permissions: _permissions, ...rest } = version;
+    return rest;
+}
+/**
+ * A permission-enforcing view of a Stack for a single (principal, subject)
+ * pair, obtained
+ * via `stack.asEntity(entityId)`. Missing records throw StackNotFoundError
+ * (or return null on reads); existing-but-inaccessible ones throw
+ * StackPermissionError. See docs/spec/access-control.md.
+ *
+ * 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
+ * access at create time) key on `principalEntityId`; authorship, `-own`
+ * matching, record-level permission resolution, and "files I uploaded"
+ * lookups key on `subjectEntityId`.
  *
- * Read methods return null for a Record that doesn't exist, and throw
- * StackPermissionError for one that exists but isn't readable by the requester.
- * Write methods throw StackNotFoundError for a missing Record and
- * StackPermissionError for one that exists but isn't writable. This lets
- * callers distinguish "not found" from "forbidden".
+ * Unconditional owner access follows that same split rather than one
+ * identity: it answers *what data is reachable* for the subject (an owner
+ * subject resolves past every permission check) and *who may exercise a
+ * privileged verb* for the principal (an owner app is not bounded by
+ * grants). Under delegation both halves apply, and a mistake on the
+ * authority side is an escalation rather than a preference.
  */
 export class ScopedStack {
     stack;
-    requesterEntityId;
-    constructor(stack, requesterEntityId) {
+    principalEntityId;
+    subjectEntityId;
+    idTimestampSkewMs;
+    adapter;
+    constructor(stack, principalEntityId, subjectEntityId, idTimestampSkewMs, 
+    // Bytes-storage primitive for putAttachment(). Held directly because
+    // ScopedStack always composes bytes + its own create() — the record
+    // must carry the subject's entityId and the principal behind it,
+    // neither of which the adapter-level atomic capability takes.
+    adapter) {
         this.stack = stack;
-        this.requesterEntityId = requesterEntityId;
+        this.principalEntityId = principalEntityId;
+        this.subjectEntityId = subjectEntityId;
+        this.idTimestampSkewMs = idTimestampSkewMs;
+        this.adapter = adapter;
     }
     get features() {
         return this.stack.features;
     }
-    resolveRecord = (id) => this.stack.get(id, { migrate: false });
+    resolveRecord = (id) => this.stack.get(id);
+    /** Whether a delegated app is acting for someone other than itself. */
+    get delegated() {
+        return this.subjectEntityId !== this.principalEntityId;
+    }
+    /**
+     * Whether unconditional owner authority applies — the owner acting as
+     * itself. The verbs that rest on it are irreversible or disclose the
+     * sharing graph, so delegation never carries one to a subject, whichever
+     * side the owner is on. See
+     * docs/spec/access-control.md § Delegation: principal and subject.
+     */
+    get ownerActingAlone() {
+        return !this.delegated && this.principalEntityId === this.stack.ownerEntityId;
+    }
     checkRead(record) {
-        return checkAccess(record, this.requesterEntityId, this.stack.ownerEntityId, 'read', this.resolveRecord);
+        return checkAccess(record, this.subjectEntityId, this.stack.ownerEntityId, 'read', this.resolveRecord);
     }
     checkWrite(record) {
-        return checkAccess(record, this.requesterEntityId, this.stack.ownerEntityId, 'write', this.resolveRecord);
+        return checkAccess(record, this.subjectEntityId, this.stack.ownerEntityId, 'write', this.resolveRecord);
     }
     /**
-     * Check whether the requester holds a _grant record covering at least one
-     * of the given actions for the given type. For -own actions, additionally
-     * requires that `record.entityId` matches the requester (authorship check).
-     * Anonymous requesters always return false.
+     * Whether `grantee` holds a _grant covering one of `actions` for the
+     * type's family (grants match by baseId, so a version bump never orphans
+     * one). -own actions additionally require record.entityId === grantee,
+     * unless `matchOwn` is false — on the principal side of a delegated
+     * request the suffix is read as the bare verb, since which records are
+     * reachable is the subject's business. `allowDefault` decides whether a
+     * grant naming nobody counts. Anonymous grantees always return false.
+     *
+     * Reached only through subjectAllows()/principalAllows(), which fix those
+     * two flags per side of the intersection. Call one of those instead.
+     * See docs/spec/access-control.md § Type-level grants.
      */
-    async hasGrant(typeId, actions, record, prefetchedGrants) {
-        if (!this.requesterEntityId)
+    async hasGrant(typeId, actions, opts) {
+        const { grantee, record, prefetchedGrants, matchOwn = true, allowDefault = true } = opts;
+        if (!grantee)
+            return false;
+        const familyId = baseIdOf(typeId);
+        // grant() refuses to write these, but a _grant record is an ordinary
+        // Record: an unscoped Stack, an import, or a server mapping a request
+        // body onto Stack can mint one anyway. Refusing at the point of use is
+        // what makes the rule hold regardless of how the record got there.
+        if (UNGRANTABLE_SYSTEM_TYPES.has(familyId))
             return false;
         let grantRecords;
         if (prefetchedGrants !== undefined) {
             grantRecords = prefetchedGrants;
         }
         else {
-            const result = await this.stack.query({
-                filter: {
-                    typeId: `${SYSTEM_TYPES.GRANT}@1`,
-                    ...(this.stack.features.contentFieldQuery && { content: { typeId } }),
-                },
+            // No content-field prefilter: a stored grant's typeId may be a bare
+            // baseId or versioned, so exact matching would wrongly exclude family
+            // versions. Cursor-walked to see grants past page one.
+            grantRecords = await queryAllPages((q) => this.stack.query(q), {
+                filter: { typeId: `${SYSTEM_TYPES.GRANT}@1` },
             });
-            grantRecords = result.records;
         }
         return grantRecords.some((r) => {
             const c = r.content;
-            if (c.typeId !== typeId)
+            if (baseIdOf(c.typeId) !== familyId)
+                return false;
+            if (!c.granteeEntityId && !allowDefault)
                 return false;
-            if (r.entityId && r.entityId !== this.requesterEntityId)
+            if (c.granteeEntityId && c.granteeEntityId !== grantee)
                 return false;
             return actions.some((action) => {
                 if (!c.actions.includes(action))
                     return false;
-                if (action.endsWith('-own'))
-                    return record?.entityId === this.requesterEntityId;
+                if (matchOwn && action.endsWith('-own'))
+                    return record?.entityId === grantee;
                 return true;
             });
         });
     }
+    /**
+     * The principal half of a delegated request's authority: does the app
+     * hold any grant permitting these verbs on this type at all. Bounds what
+     * the subject's own authority can reach through it, so a powerful app
+     * can never lend its reach to a weaker subject — nor the reverse.
+     * Vacuously true when there's no delegation, where the principal and
+     * subject checks would be the same question asked twice.
+     *
+     * Default grants don't count here. "Any authenticated entity" is about
+     * people who turn up, not software the owner installed — an app reaches
+     * only the types named to it, which is the whole of what containment
+     * promises.
+     */
+    principalAllows(typeId, actions, prefetchedGrants) {
+        if (!this.delegated)
+            return Promise.resolve(true);
+        if (this.principalEntityId === this.stack.ownerEntityId)
+            return Promise.resolve(true);
+        return this.hasGrant(typeId, actions, {
+            grantee: this.principalEntityId,
+            prefetchedGrants,
+            matchOwn: false,
+            allowDefault: false,
+        });
+    }
+    /**
+     * The subject half: which records are reachable, answered with `-own`
+     * matching and default grants both in force — the ordinary reading of a
+     * grant, since the subject is the entity a grant is written about.
+     *
+     * Paired with principalAllows() so that the two halves of the
+     * intersection are the only callers of hasGrant(): its flags differ per
+     * side and mean nothing on their own, so no call site sets them by hand.
+     */
+    subjectAllows(typeId, actions, opts = {}) {
+        return this.hasGrant(typeId, actions, {
+            grantee: this.subjectEntityId,
+            record: opts.record,
+            prefetchedGrants: opts.prefetchedGrants,
+        });
+    }
     async canRead(record, prefetchedGrants) {
-        return ((await this.checkRead(record)) ||
-            (await this.hasGrant(record.typeId, ['read-own', 'read-any'], record, prefetchedGrants)));
+        const reachable = (await this.checkRead(record)) ||
+            (await this.subjectAllows(record.typeId, ['read-own', 'read-any'], {
+                record,
+                prefetchedGrants,
+            }));
+        if (!reachable)
+            return false;
+        return this.principalAllows(record.typeId, ['read-own', 'read-any'], prefetchedGrants);
     }
     async checkCreateGrant(typeId) {
-        if (this.requesterEntityId === this.stack.ownerEntityId)
+        if (this.ownerActingAlone)
             return true;
-        return this.hasGrant(typeId, ['create']);
+        const reachable = this.subjectEntityId === this.stack.ownerEntityId ||
+            (await this.subjectAllows(typeId, ['create']));
+        if (!reachable)
+            return false;
+        return this.principalAllows(typeId, ['create']);
+    }
+    /**
+     * `_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.
+     */
+    isGroupManager(record) {
+        if (!this.managesGroup(this.principalEntityId, record))
+            return false;
+        return !this.delegated || this.managesGroup(this.subjectEntityId, record);
     }
-    /** Fetch a record the requester can update (via permissions or an update grant), or throw. */
-    async requireUpdatable(id) {
-        const record = await this.stack.get(id, { migrate: false });
+    /** Whether one identity, on its own, manages `record` — see isGroupManager(). */
+    managesGroup(entityId, record) {
+        if (!entityId)
+            return false;
+        if (entityId === this.stack.ownerEntityId)
+            return true;
+        return groupRoleFromAssociations(record.associations, entityId) === 'admin';
+    }
+    /**
+     * Fetch a record the subject can reach and the principal holds `update` on
+     * (via permissions or an update grant), or throw. `mutating: false` marks
+     * the history readers, which borrow this gate without changing anything —
+     * the one way through it a `_grant` Record stays open to.
+     */
+    async requireUpdatable(id, opts = {}) {
+        const record = await this.stack.get(id);
         if (!record)
             throw new StackNotFoundError(`Record not found: "${id}"`);
-        const allowed = (await this.checkWrite(record)) ||
-            (await this.hasGrant(record.typeId, ['update-own', 'update-any'], record));
+        if (opts.mutating ?? true)
+            this.requireOwnerForGrantRecord(record.typeId);
+        if (baseIdOf(record.typeId) === SYSTEM_TYPES.GROUP) {
+            if (!this.isGroupManager(record))
+                throw new StackPermissionError();
+            return record;
+        }
+        const allowed = ((await this.checkWrite(record)) ||
+            (await this.subjectAllows(record.typeId, ['update-own', 'update-any'], { record }))) &&
+            (await this.principalAllows(record.typeId, ['update-own', 'update-any']));
         if (!allowed)
             throw new StackPermissionError();
         return record;
     }
-    /** Fetch a record the requester can delete (via permissions or a delete grant), or throw. */
+    /**
+     * Fetch a record the subject can reach and the principal holds `delete` on
+     * (via permissions or a delete grant), or throw.
+     */
     async requireDeletable(id) {
-        const record = await this.stack.get(id, { migrate: false });
+        const record = await this.stack.get(id);
         if (!record)
             throw new StackNotFoundError(`Record not found: "${id}"`);
-        const allowed = (await this.checkWrite(record)) ||
-            (await this.hasGrant(record.typeId, ['delete-own', 'delete-any'], record));
+        this.requireOwnerForGrantRecord(record.typeId);
+        if (baseIdOf(record.typeId) === SYSTEM_TYPES.GROUP) {
+            if (!this.isGroupManager(record))
+                throw new StackPermissionError();
+            return record;
+        }
+        const allowed = ((await this.checkWrite(record)) ||
+            (await this.subjectAllows(record.typeId, ['delete-own', 'delete-any'], { record }))) &&
+            (await this.principalAllows(record.typeId, ['delete-own', 'delete-any']));
         if (!allowed)
             throw new StackPermissionError();
         return record;
     }
     /**
-     * Create a new record on behalf of the authenticated requester.
-     * Requires either an entity-specific _grant or a default _grant for
-     * the target type. Anonymous requesters (null entityId) are always denied.
-     * The created record's entityId is always set to the requester.
+     * Whether this request may reference `recordId` (as a parentId or
+     * relationship target). Missing and unreadable both return false —
+     * indistinguishable, so this can't probe for a record's existence.
+     */
+    async canReadReferent(recordId) {
+        const record = await this.stack.get(recordId);
+        if (!record)
+            return false;
+        return this.canRead(record);
+    }
+    /**
+     * Whether this request can read some record referencing `fileId` —
+     * shared by canAccessFile() and the non-owner _attachment@1 create()
+     * carve-out, which deliberately excludes the uploader clause. Walks
+     * every referencing record, short-circuiting on the first readable one.
+     * See docs/spec/attachments.md § Creating `_attachment@1` records directly.
+     */
+    async hasReadableReference(fileId) {
+        const prefetchedGrants = this.subjectEntityId
+            ? await queryAllPages((q) => this.stack.query(q), {
+                filter: { typeId: `${SYSTEM_TYPES.GRANT}@1` },
+            })
+            : undefined;
+        const match = await findFirstMatch((q) => this.stack.query(q), { filter: { attachmentFileId: fileId } }, (record) => this.canRead(record, prefetchedGrants));
+        return match !== undefined;
+    }
+    /**
+     * Whether this request may reference or download `fileId` — the dual of
+     * getAttachment()'s access rule. Nonexistent and inaccessible are
+     * indistinguishable (both false), so no confirmation oracle for guessed
+     * hashes. See docs/spec/access-control.md § Reference-creation gating.
+     */
+    async canAccessFile(fileId) {
+        if (this.ownerActingAlone)
+            return true;
+        // Reaching a file through a record this request can read is already
+        // fully intersected — canRead() applied the principal's mask against
+        // that record's own type, which is the type the reference lives on.
+        if (await this.hasReadableReference(fileId))
+            return true;
+        if (!this.subjectEntityId)
+            return false;
+        // The remaining paths are authorship facts about the subject, so they
+        // decide *which* files match — they are not themselves a grant, and the
+        // principal still needs one of its own on the attachment type.
+        if (!(await this.principalAllows(`${SYSTEM_TYPES.ATTACHMENT}@1`, ['read-own', 'read-any']))) {
+            return false;
+        }
+        if (this.subjectEntityId === this.stack.ownerEntityId)
+            return true;
+        return this.stack.features.contentFieldQuery
+            ? (await this.stack.query({
+                filter: {
+                    typeId: `${SYSTEM_TYPES.ATTACHMENT}@1`,
+                    entityId: this.subjectEntityId,
+                    content: { fileId },
+                },
+                limit: 1,
+            })).records.length > 0
+            : (await queryAllPages((q) => this.stack.query(q), {
+                filter: { typeId: `${SYSTEM_TYPES.ATTACHMENT}@1`, entityId: this.subjectEntityId },
+            })).some((r) => r.content.fileId === fileId);
+    }
+    /** Names of the type's top-level file-ref fields — the content-reference half of attachmentFileId matching. */
+    async fileRefFieldNames(typeId) {
+        const type = await this.stack.getType(typeId);
+        if (!type)
+            return [];
+        return Object.entries(type.schema)
+            .filter(([, def]) => def.kind === 'file-ref')
+            .map(([field]) => field);
+    }
+    /**
+     * 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
+     * carry no new reference).
+     */
+    async requireFileRefAccess(typeId, content) {
+        for (const field of await this.fileRefFieldNames(typeId)) {
+            const value = content[field];
+            if (typeof value !== 'string')
+                continue;
+            if (!(await this.canAccessFile(value)))
+                throw new StackPermissionError();
+        }
+    }
+    /**
+     * Reference-creation gate for one association: `attachment` requires
+     * file access, `relationship` read access to its target; `tag` is
+     * unchecked, and `_group` roster associations are gated by the stricter
+     * isGroupManager() instead. See docs/spec/access-control.md
+     * § Reference-creation gating.
+     */
+    async requireAssociationAccess(typeId, association) {
+        if (association.kind === 'attachment') {
+            if (!(await this.canAccessFile(association.fileId)))
+                throw new StackPermissionError();
+        }
+        else if (association.kind === 'relationship' && baseIdOf(typeId) !== SYSTEM_TYPES.GROUP) {
+            if (!(await this.canReadReferent(association.recordId)))
+                throw new StackPermissionError();
+        }
+    }
+    /**
+     * Create a record on behalf of the subject: create grant required,
+     * anonymous denied, entityId set to the subject, client IDs skew-checked,
+     * reference-creating options gated, and non-owner `_attachment@1`
+     * creation refused save one carve-out. A scoped create always stamps
+     * authorship — an absent entityId means an unscoped `Stack` wrote it.
+     * See docs/spec/access-control.md and docs/spec/attachments.md.
      */
     async create(typeId, content, opts = {}) {
-        const requester = this.requesterEntityId;
-        if (!requester)
+        const principal = this.principalEntityId;
+        if (!principal)
             throw new StackPermissionError('Anonymous requesters cannot create records');
         if (!(await this.checkCreateGrant(typeId))) {
             throw new StackPermissionError(`No create grant for type "${typeId}"`);
         }
-        return this.stack.create(typeId, content, { ...opts, entityId: requester });
+        // The exemption is the owner's own, so delegation doesn't carry it: an
+        // owner principal acting for someone else would otherwise let that
+        // subject name any fileId and reach the bytes through the uploader
+        // clause, which matches on the subject this create stamps.
+        if (!this.ownerActingAlone && baseIdOf(typeId) === SYSTEM_TYPES.ATTACHMENT) {
+            const fileId = content.fileId;
+            if (typeof fileId !== 'string' || !(await this.hasReadableReference(fileId))) {
+                throw new StackPermissionError();
+            }
+        }
+        if (opts.permissions?.length && !this.mayGrantAccess()) {
+            throw new StackPermissionError('A delegated principal cannot set permissions, at create time or after');
+        }
+        this.requireOwnerForOwnerDid(typeId, content.did);
+        await this.requireAppIdMatchesPrincipal(opts.appId);
+        if (opts.id !== undefined) {
+            validateRecordId(opts.id);
+            validateIdTimestampSkew(opts.id, this.idTimestampSkewMs);
+        }
+        if (opts.parentId !== undefined && !(await this.canReadReferent(opts.parentId))) {
+            throw new StackPermissionError();
+        }
+        for (const assoc of opts.associations ?? []) {
+            await this.requireAssociationAccess(typeId, assoc);
+        }
+        await this.requireFileRefAccess(typeId, content);
+        return this.stack.create(typeId, content, {
+            ...opts,
+            entityId: this.subjectEntityId ?? undefined,
+            principalId: this.delegated ? principal : undefined,
+        });
+    }
+    /**
+     * Whether this request may decide who else reaches a record — the rule
+     * setPermissions() 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
+     * believes it published something it didn't. Not `ownerActingAlone`:
+     * the record is the subject's own, so an owner principal grants it no
+     * reach the subject lacks.
+     * See docs/spec/access-control.md § Delegation: principal and subject.
+     */
+    mayGrantAccess() {
+        return !this.delegated || this.principalEntityId === this.stack.ownerEntityId;
+    }
+    /**
+     * Whether one identity, on its own, may decide who else reaches `record`
+     * — the owner-or-creator rule setPermissions() enforces, asked of one
+     * side at a time. See
+     * docs/spec/access-control.md § Delegation: principal and subject.
+     */
+    mayReshare(entityId, record) {
+        if (!entityId)
+            return false;
+        return entityId === this.stack.ownerEntityId || entityId === record.entityId;
     }
     async get(id, opts = {}) {
         const record = await this.stack.get(id, opts);
@@ -700,26 +2167,20 @@ export class ScopedStack {
         return record;
     }
     /**
-     * Query records, filtered to only those the requester can read.
-     *
-     * Pagination is filtered-then-refilled: each adapter page is fetched in
-     * full and entirely evaluated before deciding whether to fetch another,
-     * so the returned page may overshoot `limit` slightly, but never skips a
-     * record that shared a page with the one that crossed the threshold (the
-     * adapter's cursor can't address a position mid-page).
-     *
-     * `total` is always null — see the QueryResult.total doc comment.
-     *
-     * Grant records are pre-fetched once before the pagination loop so read
-     * grants don't trigger a separate _grant@1 query per record.
+     * Query records, filtered to those this request can read. Pages are
+     * filtered then refilled, so a page may slightly overshoot `limit` but
+     * never skips a record. `total` is always null (see QueryResult.total).
+     * Grants are prefetched once, cursor-walked to exhaustion.
      */
     async query(query = {}) {
         const limit = Math.min(query.limit ?? DEFAULT_QUERY_LIMIT, MAX_QUERY_LIMIT);
         const records = [];
         const maxFetched = limit * 10;
         let totalFetched = 0;
-        const prefetchedGrants = this.requesterEntityId
-            ? (await this.stack.query({ filter: { typeId: `${SYSTEM_TYPES.GRANT}@1` } })).records
+        const prefetchedGrants = this.principalEntityId
+            ? await queryAllPages((q) => this.stack.query(q), {
+                filter: { typeId: `${SYSTEM_TYPES.GRANT}@1` },
+            })
             : undefined;
         let page = { records: [], cursor: query.cursor ?? null, total: null };
         do {
@@ -732,115 +2193,306 @@ export class ScopedStack {
         } while (records.length < limit && page.cursor && totalFetched < maxFetched);
         return { records, cursor: page.cursor, total: null };
     }
-    async update(id, content) {
-        await this.requireUpdatable(id);
-        return this.stack.update(id, content);
+    async update(id, content, opts = {}) {
+        const record = await this.requireUpdatable(id);
+        // 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);
     }
-    async associate(id, association) {
-        await this.requireUpdatable(id);
-        return this.stack.associate(id, association);
+    /**
+     * Naming the software behind a key is the trust decision the `_app`
+     * registry exists to record, so both halves of that binding — `did` and
+     * `appId` — belong to the owner alone. Same reasoning that makes `_app`
+     * ungrantable, applied to the fields a lookup reads. Registering a card
+     * is already owner-only; without this, record-level `write` shared on a
+     * card would be a second way in: a card carrying no DID yet could be
+     * pointed at a write-holder's own key while keeping the name the owner
+     * gave it, or relabelled to claim another app's `appId`. `name` and
+     * `version` stay writable — they are display, not lookup.
+     *
+     * Owner *acting alone*, in both directions: a delegated app never holds
+     * it, and an owner principal doesn't lend it to a subject holding
+     * record-level `write` on a card — which would reopen the same route
+     * from the other side.
+     *
+     * `_entity` deliberately does not get this rule: naming people is what a
+     * contacts app does, so its cards stay writable by grant. Uniqueness and
+     * immutability still bind them. See docs/spec/identity.md § DID bindings.
+     */
+    requireOwnerForAppIdentity(typeId, touches) {
+        if (baseIdOf(typeId) !== SYSTEM_TYPES.APP)
+            return;
+        if (!bindingFieldsOf(SYSTEM_TYPES.APP).some(touches))
+            return;
+        if (!this.ownerActingAlone) {
+            throw new StackPermissionError('Only the stack owner may set an _app record’s did or appId');
+        }
     }
-    async dissociate(id, association) {
+    /**
+     * A self-reported `appId` must agree with the `_app` card naming the
+     * principal's DID, where the owner registered one. `principalId` is
+     * verified, so letting the pair disagree would leave a verified principal
+     * claiming a name the owner gave different software — the cross-check the
+     * registry exists for, refused at the write instead of left to each reader.
+     * A principal with no card keeps `appId` as the bare self-report it is for
+     * every undelegated writer.
+     * See docs/spec/identity.md § Attribution and what can be trusted.
+     */
+    async requireAppIdMatchesPrincipal(appId) {
+        if (appId === undefined || !this.delegated)
+            return;
+        const card = await findFirstMatch((q) => this.stack.query(q), {
+            filter: {
+                baseId: SYSTEM_TYPES.APP,
+                includeDeleted: true,
+                ...(this.stack.features.contentFieldQuery && {
+                    content: { did: this.principalEntityId },
+                }),
+            },
+        }, (r) => r.content.did === this.principalEntityId);
+        if (card && card.content.appId !== appId) {
+            throw new StackPermissionError(`appId "${appId}" is not the appId registered for this principal`);
+        }
+    }
+    /**
+     * The owner's own DID is the one `_entity` binding a grantee may not claim.
+     * `ownerProfile` adopts whichever card holds it, so a card minted by
+     * someone else becomes the stack's own profile, and uniqueness then makes
+     * that permanent. Every other DID stays open to a contacts app, which is
+     * the reach `_entity` is grantable for.
+     * See docs/spec/identity.md § DID bindings.
+     */
+    requireOwnerForOwnerDid(typeId, did) {
+        if (baseIdOf(typeId) !== SYSTEM_TYPES.ENTITY)
+            return;
+        if (did !== this.stack.ownerEntityId)
+            return;
+        if (!this.ownerActingAlone) {
+            throw new StackPermissionError('Only the stack owner may claim the owner’s own did');
+        }
+    }
+    /**
+     * A `_grant` Record *is* authority, so rewriting one is the escalation
+     * UNGRANTABLE_SYSTEM_TYPES refuses at evaluation, reached by editing an
+     * existing grant rather than minting a fresh one. `grant()` and `revoke()`
+     * live on `Stack`, never `StackClient`, so no scoped write is lost. Writes
+     * only: reading a grant Record and its history stays on the ordinary gate.
+     * See docs/spec/access-control.md § Type-level grants.
+     */
+    requireOwnerForGrantRecord(typeId) {
+        if (baseIdOf(typeId) !== SYSTEM_TYPES.GRANT)
+            return;
+        if (!this.ownerActingAlone) {
+            throw new StackPermissionError('Only the stack owner may write a _grant record');
+        }
+    }
+    async associate(id, association, opts = {}) {
+        const record = await this.requireUpdatable(id);
+        await this.requireAssociationAccess(record.typeId, association);
+        return this.stack.associate(id, association, opts);
+    }
+    async dissociate(id, association, opts = {}) {
         await this.requireUpdatable(id);
-        return this.stack.dissociate(id, association);
+        return this.stack.dissociate(id, association, opts);
     }
-    async setPermissions(id, permissions) {
-        const record = await this.stack.get(id, { migrate: false });
+    async setPermissions(id, permissions, opts = {}) {
+        const record = await this.stack.get(id);
         if (!record)
             throw new StackNotFoundError(`Record not found: "${id}"`);
-        const isOwner = this.requesterEntityId === this.stack.ownerEntityId;
-        const isCreator = this.requesterEntityId === record.entityId;
-        if (!isOwner && !isCreator)
-            throw new StackPermissionError();
-        return this.stack.setPermissions(id, permissions);
+        this.requireOwnerForGrantRecord(record.typeId);
+        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 new StackPermissionError();
+        }
+        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 new StackPermissionError();
+            if (this.delegated && !this.mayReshare(this.subjectEntityId, record)) {
+                throw new StackPermissionError();
+            }
+        }
+        return this.stack.setPermissions(id, permissions, opts);
     }
+    /**
+     * Hard delete is owner-only: it is irreversible and destroys version
+     * history, so neither the write bit nor delete-own/delete-any grants
+     * reach it, and delegation doesn't carry it either. Everyone else is
+     * limited to soft delete.
+     */
     async delete(id, opts = {}) {
         await this.requireDeletable(id);
+        if (opts.hard && !this.ownerActingAlone) {
+            throw new StackPermissionError('Hard delete is owner-only');
+        }
         return this.stack.delete(id, opts);
     }
+    /**
+     * Reverse a soft delete. Gated the same as delete() — undelete is the
+     * inverse of soft delete, so granting one direction without the other
+     * would be backwards. Idempotent, per Stack.undelete().
+     */
+    async undelete(id, opts = {}) {
+        await this.requireDeletable(id);
+        return this.stack.undelete(id, opts);
+    }
+    /**
+     * History is the mutation/recovery surface, not a read surface — gated
+     * like update(), 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
+     * alone: seeing how a Record you can already read got that way is not
+     * the escalation that fence exists to stop, and losing it would leave a
+     * write-holder unable to audit the Record they hold.
+     * See docs/spec/versioning.md § History access.
+     */
     async getVersions(id) {
-        const existing = await this.stack.get(id, { migrate: false });
-        if (!existing)
-            throw new StackNotFoundError(`Record not found: "${id}"`);
-        if (!(await this.canRead(existing)))
-            throw new StackPermissionError();
-        return this.stack.getVersions(id);
+        await this.requireUpdatable(id, { mutating: false });
+        const versions = await this.stack.getVersions(id);
+        return this.ownerActingAlone ? versions : versions.map(stripVersionPermissions);
     }
+    /** See getVersions() — same mutate-surface gate, same permissions stripping. */
     async getVersion(id, version) {
-        const existing = await this.stack.get(id, { migrate: false });
-        if (!existing)
-            throw new StackNotFoundError(`Record not found: "${id}"`);
-        if (!(await this.canRead(existing)))
-            throw new StackPermissionError();
-        return this.stack.getVersion(id, version);
+        await this.requireUpdatable(id, { mutating: false });
+        const target = await this.stack.getVersion(id, version);
+        if (!target)
+            return null;
+        return this.ownerActingAlone ? target : stripVersionPermissions(target);
     }
-    async restoreVersion(id, version) {
-        await this.requireUpdatable(id);
-        return this.stack.restoreVersion(id, version);
+    /**
+     * 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.
+     */
+    async restoreVersion(id, version, opts = {}) {
+        const record = await this.requireUpdatable(id);
+        if (!this.ownerActingAlone) {
+            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.
+                this.requireOwnerForAppIdentity(record.typeId, (field) => target.content[field] !==
+                    record.content[field]);
+                await this.requireFileRefAccess(target.typeId, target.content);
+                for (const association of target.associations ?? []) {
+                    await this.requireAssociationAccess(target.typeId, association);
+                }
+            }
+        }
+        return this.stack.restoreVersion(id, version, opts);
     }
     /**
-     * Store bytes and create an _attachment@1 metadata record owned by the
-     * requester. Requires a `create` grant on `_attachment@1`.
-     * Anonymous requesters are always denied.
+     * Commit a per-record migration — **the owner acting alone, only**.
+     *
+     * Migration is owner-driven by design: `migrateAll()`, the bulk path,
+     * lives on `Stack` and is deliberately absent from `StackClient`, the
+     * same way `grant()`/`revoke()` are. This is its per-record counterpart
+     * and carries the same restriction, rather than inventing a grant model
+     * that the bulk path deliberately doesn't have.
+     *
+     * 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
+     * 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
+     * to any record they authored could migrate that record into the family
+     * naming any `fileId`, then read the bytes through canAccessFile()'s
+     * uploader clause — the exact escalation that carve-out exists to refuse
+     * (see docs/spec/attachments.md § Creating `_attachment@1` records
+     * directly). Ordinary write access to a record is not consent to move it
+     * between families.
+     *
+     * A server implementing `POST /records/:id/migrate` therefore serves it
+     * to the stack owner and answers 403 otherwise. See
+     * docs/spec/data-model.md § Type migrations.
+     */
+    async commitMigration(id, toTypeId, content, opts = {}) {
+        if (!this.ownerActingAlone) {
+            throw new StackPermissionError('Only the stack owner may commit a migration');
+        }
+        return this.stack.commitMigration(id, toTypeId, content, opts);
+    }
+    /**
+     * Store bytes and create an _attachment@1 metadata record (create grant
+     * on `_attachment@1` required; anonymous denied), returning that record.
+     * Authorship and principal are stamped exactly as create() does.
      */
-    async putAttachment(data, mimeType, filename) {
-        const requester = this.requesterEntityId;
-        if (!requester) {
+    async putAttachment(data, mimeType, filename, appId) {
+        // The one ScopedStack path that reaches the adapter without going
+        // through Stack first — without this, a closed stack would still write
+        // bytes before the delegated create() refused.
+        this.stack.assertOpen();
+        const principal = this.principalEntityId;
+        if (!principal) {
             throw new StackPermissionError('Anonymous requesters cannot upload attachments');
         }
         if (!(await this.checkCreateGrant(`${SYSTEM_TYPES.ATTACHMENT}@1`))) {
             throw new StackPermissionError(`No create grant for type "${SYSTEM_TYPES.ATTACHMENT}@1"`);
         }
-        const fileId = await this.stack.putAttachmentBytes(data);
-        await this.stack.create(`${SYSTEM_TYPES.ATTACHMENT}@1`, {
+        await this.requireAppIdMatchesPrincipal(appId);
+        assertAttachmentSize(data.byteLength, this.features.maxAttachmentBytes);
+        const fileId = await this.adapter.putAttachment(data);
+        return this.stack.create(`${SYSTEM_TYPES.ATTACHMENT}@1`, {
             fileId,
             mimeType,
             size: data.byteLength,
             ...(filename && { filename }),
-        }, { entityId: requester });
-        return fileId;
+        }, {
+            entityId: this.subjectEntityId ?? undefined,
+            principalId: this.delegated ? principal : undefined,
+            appId,
+        });
     }
     /**
-     * Download attachment bytes. Accessible if the requester is the owner,
-     * can read any record referencing the file, or uploaded the file themselves
-     * and it hasn't been associated with a record yet.
+     * Download attachment bytes. Accessible to the owner, a reader of any
+     * referencing record, or the uploader pre-association — the same
+     * predicate as the reference-creation gate (canAccessFile).
      */
     async getAttachment(fileId) {
-        if (this.requesterEntityId === this.stack.ownerEntityId) {
-            return this.stack.getAttachment(fileId);
-        }
-        // Accessible if the requester can read any record that references this file
-        const refResult = await this.query({ filter: { attachmentFileId: fileId }, limit: 1 });
-        if (refResult.records.length > 0) {
-            return this.stack.getAttachment(fileId);
-        }
-        // Accessible if the requester uploaded it and it hasn't been associated yet
-        if (this.requesterEntityId) {
-            const uploadResult = await this.stack.query({
-                filter: {
-                    typeId: `${SYSTEM_TYPES.ATTACHMENT}@1`,
-                    entityId: this.requesterEntityId,
-                    ...(this.stack.features.contentFieldQuery && { content: { fileId } }),
-                },
-                limit: 1,
-            });
-            const hasUpload = this.stack.features.contentFieldQuery
-                ? uploadResult.records.length > 0
-                : uploadResult.records.some((r) => r.content.fileId === fileId);
-            if (hasUpload)
-                return this.stack.getAttachment(fileId);
-        }
-        throw new StackPermissionError();
+        if (!(await this.canAccessFile(fileId)))
+            throw new StackPermissionError();
+        return this.stack.getAttachment(fileId);
     }
     /**
      * Delete an attachment. Only the stack owner may delete attachments.
      * Delegates to Stack.deleteAttachment(), which enforces the "not referenced" check.
      */
     async deleteAttachment(fileId) {
-        if (this.requesterEntityId !== this.stack.ownerEntityId) {
+        if (!this.ownerActingAlone) {
             throw new StackPermissionError('Only the stack owner can delete attachments');
         }
         return this.stack.deleteAttachment(fileId);
     }
+    /**
+     * Sweep for unreferenced attachment bytes and delete them. Only the stack
+     * owner may run this. Delegates to Stack.collectAttachmentGarbage().
+     */
+    async collectAttachmentGarbage(opts) {
+        if (!this.ownerActingAlone) {
+            throw new StackPermissionError('Only the stack owner can collect attachment garbage');
+        }
+        return this.stack.collectAttachmentGarbage(opts);
+    }
 }
 //# sourceMappingURL=stack.js.map