@haverstack/core 0.8.0 → 0.10.0

package/dist/stack.d.ts

@@ -7,51 +7,240 @@
  *  - 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 type { SchemaDriftViolation } from './schema.js';
 import type { ValidationError } from './validate.js';
-import type { StackRecord, StackType, TypeSchema, TypeId, StackAdapter, StackQuery, QueryResult, Association, Permission, Migration, RecordVersion, StackFeatures, GrantAction } from './types.js';
+import type { StackRecord, StackType, TypeSchema, TypeId, StackAdapter, StackQuery, RecordFilter, QueryResult, Association, Permission, Migration, RecordVersion, StackFeatures, GrantAction, AttachmentContent, EntityId, AppId, TokenSession } from './types.js';
 export type CreateRecordOptions = {
+    /**
+     * Client-minted record ID. Must be 12 lowercase Crockford base-32
+     * characters and may not use the reserved `_` prefix. Omit to let the
+     * library generate one. See Stack.create() and ScopedStack.create()
+     * for the validation each applies.
+     */
+    id?: string;
     parentId?: string;
-    entityId?: string;
-    appId?: string;
+    entityId?: EntityId;
+    /** Reverse-DNS identifier of the writing software — see AppId. */
+    appId?: AppId;
+    /**
+     * The authenticated principal, when it isn't the author. ScopedStack sets
+     * this from its own principal; callers of plain Stack supply it only when
+     * reconstructing a delegated write. See StackRecord.principalId.
+     */
+    principalId?: EntityId;
     permissions?: Permission[];
     associations?: Association[];
 };
+export type ScopedStackOptions = {
+    /**
+     * The entity a delegated app acts for. Omit when the principal acts as
+     * itself — the case for an app riding its user's identity, which needs
+     * no delegation. See docs/spec/identity.md § App.
+     */
+    onBehalfOf?: EntityId;
+};
+export type StackOptions = {
+    /**
+     * Ensures the owner's own `_entity` profile record exists, creating it on
+     * first run. Idempotent — safe to pass on every open. See
+     * docs/spec/identity.md § Entity.
+     */
+    ownerProfile?: {
+        name: string;
+        handle?: string;
+    };
+    /**
+     * Clock-skew tolerance (ms) for the timestamp-prefix check
+     * ScopedStack.create() runs on grantee-supplied IDs; unscoped
+     * Stack.create() never runs it. Default: 24 hours; null disables.
+     * See docs/spec/data-model.md § Record IDs.
+     */
+    idTimestampSkewMs?: number | null;
+};
+export type CollectAttachmentGarbageOptions = {
+    /**
+     * How recent an unreferenced file must be to survive collection, covering
+     * the upload-then-associate window. Default: 24 hours. Pass 0 to collect
+     * anything unreferenced right now.
+     */
+    graceMs?: number;
+    /** Compute what would be deleted without deleting anything. Default: false. */
+    dryRun?: boolean;
+};
+export type CollectAttachmentGarbageResult = {
+    deleted: string[];
+    reclaimedBytes: number;
+};
 export type GetRecordOptions = {
-    /** If false, return the raw stored record without auto-migrating. Default: true */
-    migrate?: boolean;
+    /**
+     * Records are returned exactly as stored by default. Pass "latest" to
+     * apply the registered migration chain in memory — never written back.
+     * See docs/spec/data-model.md § Type migrations.
+     */
+    presentAt?: 'stored' | 'latest';
 };
-export type DeleteRecordOptions = {
+/**
+ * Opt-in optimistic-concurrency precondition, accepted by every mutation
+ * that bumps a record's version. On mismatch the mutation throws
+ * StackVersionConflictError and changes nothing; omit to keep
+ * last-writer-wins. See docs/spec/versioning.md § Optimistic concurrency (`ifVersion`).
+ */
+export type IfVersionOptions = {
+    ifVersion?: number;
+};
+export type DeleteRecordOptions = IfVersionOptions & {
     /** If true, permanently remove the record and all its history. Default: false */
     hard?: boolean;
 };
 export type DefineTypeOptions = {
     migratesFrom?: TypeId;
 };
-export declare class StackValidationError extends Error {
+/**
+ * The wire-protocol discriminator vocabulary, one code per Stack-domain
+ * error class. Lives here rather than in @haverstack/wire-types because the
+ * classes that carry these codes are defined here; wire-types re-exports it
+ * as WireErrorCode. See docs/spec/wire-format.md § Wire error body.
+ */
+export type StackErrorCode = 'bad_request' | 'permission' | 'not_found' | 'conflict' | 'version_conflict' | 'validation' | 'migration' | 'schema_drift' | 'payload_too_large' | 'timeout';
+/**
+ * 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 declare abstract class StackError extends Error {
+    abstract readonly code: StackErrorCode;
+}
+export declare class StackValidationError extends StackError {
     readonly errors: ValidationError[];
+    static readonly code: "validation";
+    readonly code: "validation";
     constructor(errors: ValidationError[]);
 }
-export declare class StackMigrationError extends Error {
+export declare class StackMigrationError extends StackError {
+    static readonly code: "migration";
+    readonly code: "migration";
     constructor(message: string);
 }
 /** Thrown by ScopedStack when a requester lacks permission for the operation. */
-export declare class StackPermissionError extends Error {
+export declare class StackPermissionError extends StackError {
+    static readonly code: "permission";
+    readonly code: "permission";
     constructor(message?: string);
 }
 /** Thrown when a record (or specific version) does not exist. */
-export declare class StackNotFoundError extends Error {
+export declare class StackNotFoundError extends StackError {
+    static readonly code: "not_found";
+    readonly code: "not_found";
     constructor(message: string);
 }
 /** Thrown when an operation cannot proceed due to a constraint violation (e.g. deleting an attachment that is still referenced). */
-export declare class StackConflictError extends Error {
+export declare class StackConflictError extends StackError {
+    static readonly code: "conflict";
+    readonly code: "conflict";
+    constructor(message: string);
+}
+/**
+ * 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 declare class StackVersionConflictError extends StackError {
+    readonly recordId: string;
+    readonly expectedVersion: number;
+    readonly actualVersion: number;
+    static readonly code: "version_conflict";
+    readonly code: "version_conflict";
+    constructor(message: string, recordId: string, expectedVersion: number, actualVersion: number);
+}
+/**
+ * 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 declare class StackQueryError extends StackError {
+    static readonly code: "bad_request";
+    readonly code: "bad_request";
+    constructor(message: string);
+}
+/**
+ * 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 declare function assertQueryCapabilities(filter: RecordFilter | undefined, capabilities: Pick<StackFeatures, 'fullTextSearch' | 'contentFieldQuery'>): void;
+/**
+ * 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 declare class StackPayloadTooLargeError extends StackError {
+    static readonly code: "payload_too_large";
+    readonly code: "payload_too_large";
+    constructor(message: string);
+}
+/**
+ * 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 declare class StackTimeoutError extends StackError {
+    static readonly code: "timeout";
+    readonly code: "timeout";
     constructor(message: string);
 }
+/**
+ * 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 declare class StackSchemaDriftError extends StackError {
+    readonly typeId: TypeId;
+    readonly violations: SchemaDriftViolation[];
+    static readonly code: "schema_drift";
+    readonly code: "schema_drift";
+    constructor(typeId: TypeId, violations: SchemaDriftViolation[]);
+}
+/**
+ * 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 declare class StackClosedError extends Error {
+    constructor(message?: string);
+}
 /**
  * The app-facing record API, implemented by both Stack and ScopedStack.
  * Accept this type in plugin or extension code to remain adapter-agnostic
@@ -64,48 +253,106 @@ export interface StackClient {
     }>;
     get(id: string, opts?: GetRecordOptions): Promise<StackRecord | null>;
     query(query?: StackQuery): Promise<QueryResult>;
-    update(id: string, content: Record<string, unknown | null>): Promise<StackRecord>;
-    associate(id: string, association: Association): Promise<void>;
-    dissociate(id: string, association: Association): Promise<void>;
-    setPermissions(id: string, permissions: Permission[]): Promise<void>;
+    update(id: string, content: Record<string, unknown | null>, opts?: IfVersionOptions): Promise<StackRecord>;
+    associate(id: string, association: Association, opts?: IfVersionOptions): Promise<void>;
+    dissociate(id: string, association: Association, opts?: IfVersionOptions): Promise<void>;
+    setPermissions(id: string, permissions: Permission[], opts?: IfVersionOptions): Promise<void>;
     delete(id: string, opts?: DeleteRecordOptions): Promise<void>;
+    undelete(id: string, opts?: IfVersionOptions): Promise<StackRecord>;
     getVersions(id: string): Promise<RecordVersion[]>;
     getVersion(id: string, version: number): Promise<RecordVersion | null>;
-    restoreVersion(id: string, version: number): Promise<StackRecord>;
+    restoreVersion(id: string, version: number, opts?: IfVersionOptions): Promise<StackRecord>;
+    /**
+     * Commit a per-record migration: change `typeId` and `content` together,
+     * validated against `toTypeId`'s schema. The only way a record's typeId
+     * changes after creation — see docs/spec/wire-format.md § Migration
+     * commit. Takes `ifVersion` like every other mutation that bumps a
+     * record's version (see docs/spec/versioning.md § Optimistic
+     * concurrency); over the wire that is `If-Match`.
+     */
+    commitMigration(id: string, toTypeId: TypeId, content: Record<string, unknown>, opts?: IfVersionOptions): Promise<StackRecord>;
     getAttachment(fileId: string): Promise<Uint8Array>;
-    putAttachment(data: Uint8Array, mimeType: string, filename?: string): Promise<string>;
+    putAttachment(data: Uint8Array, mimeType: string, filename?: string, appId?: AppId): Promise<StackRecord & {
+        content: AttachmentContent;
+    }>;
     deleteAttachment(fileId: string): Promise<void>;
+    collectAttachmentGarbage(opts?: CollectAttachmentGarbageOptions): Promise<CollectAttachmentGarbageResult>;
 }
 export declare class Stack implements StackClient {
     private readonly adapter;
+    private readonly idTimestampSkewMsValue;
     private readonly migrations;
+    /**
+     * 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().
+     */
+    private readonly maxDefinedVersion;
+    /**
+     * 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.
+     */
+    private readonly typeCache;
+    /** Set by close(). See docs/spec/adapters.md § Lifecycle. */
+    private closed;
     private constructor();
+    private getTypeCached;
     /**
      * Create a Stack instance. Reads ownerEntityId and timezone from the adapter.
      */
-    static create(adapter: StackAdapter): Promise<Stack>;
-    get ownerEntityId(): string;
-    get timezone(): string;
+    static create(adapter: StackAdapter, opts?: StackOptions): Promise<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.
+     */
+    private ensureOwnerEntity;
+    get ownerEntityId(): EntityId;
+    get timezone(): string | undefined;
     get features(): StackFeatures;
     /**
-     * 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.
      *
-     * 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).
+     * `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: string | null): ScopedStack;
+    asEntity(entityId: EntityId | null, opts?: ScopedStackOptions): ScopedStack;
     /**
-     * Define and persist a new Type. Computes the schemaHash automatically.
-     * Should be called at app startup before creating any records of this type.
+     * Scope to an authenticated session — what StackTokenStore.lookupToken()
+     * returns. Equivalent to asEntity(principalId, { onBehalfOf: subjectId }),
+     * and what a server should reach for at its request boundary.
+     *
+     * Both identities are DIDs, so passing them positionally leaves nothing
+     * to catch a swap, and a swapped pair is undetectable in the undelegated
+     * case where they are equal — it would surface only once delegation is in
+     * use, as authority no longer fenced by the app's grants and every write
+     * attributed to the app rather than the person. Taking the pair whole
+     * removes the order to get wrong. See
+     * docs/spec/access-control.md § Delegation: principal and subject.
+     */
+    forSession(session: TokenSession): ScopedStack;
+    /**
+     * 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.
      */
     defineType(id: TypeId, name: string, schema: TypeSchema, opts?: DefineTypeOptions): Promise<StackType>;
     getType(id: TypeId): Promise<StackType | null>;
+    /** Refreshes typeCache wholesale — the explicit way to see a rename made by another writer. */
     listTypes(): Promise<StackType[]>;
     /**
      * Check whether a record's type is compatible with a required schema.
@@ -113,12 +360,10 @@ export declare class Stack implements StackClient {
      */
     typeIsCompatible(typeId: TypeId, requiredSchema: TypeSchema): Promise<boolean>;
     /**
-     * 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: Migration): void;
     /**
@@ -132,99 +377,245 @@ export declare class Stack implements StackClient {
      */
     private latestTypeId;
     /**
-     * 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.
      */
     migrateAll(baseTypeId: string): Promise<{
         migrated: number;
     }>;
     /**
      * 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.
      */
     create<T extends Record<string, unknown> = Record<string, unknown>>(typeId: TypeId, content: T, opts?: CreateRecordOptions): Promise<StackRecord & {
         content: T;
     }>;
     /**
-     * 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.
+     */
+    private presentAtLatest;
+    /**
+     * Get a record by ID, exactly as stored — no implicit migration. Pass
+     * { presentAt: 'latest' } to migrate in memory; only migrateAll()
+     * commits migrations to disk.
      */
     get(id: string, opts?: GetRecordOptions): Promise<StackRecord | null>;
     /**
-     * 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.
      */
-    update(id: string, content: Record<string, unknown | null>): Promise<StackRecord>;
+    update(id: string, content: Record<string, unknown | null>, opts?: IfVersionOptions): Promise<StackRecord>;
     /**
-     * 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.
      */
-    associate(id: string, association: Association): Promise<void>;
+    associate(id: string, association: Association, opts?: IfVersionOptions): Promise<void>;
     /**
-     * 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.
      */
-    dissociate(id: string, association: Association): Promise<void>;
+    dissociate(id: string, association: Association, opts?: IfVersionOptions): Promise<void>;
     /**
-     * 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.
      */
-    setPermissions(id: string, permissions: Permission[]): Promise<void>;
+    setPermissions(id: string, permissions: Permission[], opts?: IfVersionOptions): Promise<void>;
     /**
-     * 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.
      */
     delete(id: string, opts?: DeleteRecordOptions): Promise<void>;
     /**
-     * Query records. See StackQuery for filter, sort, and pagination options.
+     * 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().
+     */
+    undelete(id: string, opts?: IfVersionOptions): Promise<StackRecord>;
+    /**
+     * 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.
      */
     query(query?: StackQuery): Promise<QueryResult>;
+    /**
+     * 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.
+     */
+    private resolveBaseIdFilter;
     getVersions(id: string): Promise<RecordVersion[]>;
     getVersion(id: string, version: number): Promise<RecordVersion | null>;
     /**
-     * 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.
      */
-    restoreVersion(id: string, version: number): Promise<StackRecord>;
+    restoreVersion(id: string, version: number, opts?: IfVersionOptions): Promise<StackRecord>;
     /**
-     * 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.
      */
-    putAttachmentBytes(data: Uint8Array): Promise<string>;
+    commitMigration(id: string, toTypeId: TypeId, content: Record<string, unknown>, opts?: IfVersionOptions): Promise<StackRecord>;
     /**
-     * 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.
+     */
+    private commitMigrationChecked;
+    /** Uniqueness for every unique binding field a newly created card claims. */
+    private checkBindingsOnCreate;
+    /**
+     * 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.
+     */
+    private checkBindingsOnUpdate;
+    /**
+     * 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.
      */
-    putAttachment(data: Uint8Array, mimeType: string, filename?: string): Promise<string>;
+    private checkBindingsOnMigrate;
+    /**
+     * 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.
+     */
+    private checkBindingUnique;
+    /**
+     * 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.
+     */
+    private checkBindingImmutable;
+    /**
+     * 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.
+     *
+     * 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.
+     */
+    private checkAttachmentMimeTypeOnCreate;
+    /**
+     * 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.
+     */
+    private checkAttachmentImmutableFields;
+    /**
+     * 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.
+     */
+    private checkAttachmentImmutableOnMigrate;
+    /**
+     * `_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.
+     */
+    private checkConfigEntityIdUnchanged;
+    /**
+     * 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.
+     */
+    putAttachment(data: Uint8Array, mimeType: string, filename?: string, appId?: AppId): Promise<StackRecord & {
+        content: AttachmentContent;
+    }>;
     getAttachment(fileId: string): Promise<Uint8Array>;
     /**
      * Delete an attachment's bytes and its _attachment@1 metadata record(s).
@@ -233,107 +624,409 @@ export declare class Stack implements StackClient {
      */
     deleteAttachment(fileId: string): Promise<void>;
     /**
-     * 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.
+     * 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.
+     */
+    private deleteUnreferencedAttachmentRecordsFallback;
+    /**
+     * 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.
+     */
+    collectAttachmentGarbage(opts?: CollectAttachmentGarbageOptions): Promise<CollectAttachmentGarbageResult>;
+    /**
+     * 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.
      */
     flush(): Promise<void>;
     /**
-     * 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.
+     * 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.
      */
     close(): Promise<void>;
     /**
-     * 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.
+     * 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(): void;
+    /**
+     * 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 _grant@1 type is defined automatically on first use.
+     * The grantee lives in content.granteeEntityId,
+     * not record.entityId. See docs/spec/access-control.md § Type-level
+     * grants.
      */
-    grant(entityId: string | null, grants: Array<{
+    grant(entityId: EntityId | null, grants: Array<{
         actions: GrantAction[];
         typeId: TypeId;
     }>): Promise<StackRecord[]>;
+    /**
+     * 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.
+     */
+    listGrants(entityId?: EntityId | null): Promise<StackRecord[]>;
+    /**
+     * 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.
+     */
+    revoke(entityId: EntityId | null, grants: Array<{
+        actions: GrantAction[];
+        typeId: TypeId;
+    }>): Promise<void>;
+    /**
+     * 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.
+     */
+    private checkGrantsValid;
     private seedSystemTypes;
-    private saveVersion;
+    /**
+     * 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.
+     */
+    private checkIfVersion;
+    /**
+     * 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.
+     */
+    private buildVersionSnapshot;
 }
 /**
- * A permission-enforcing view of a Stack for a single requester. Obtained
- * via `stack.asEntity(entityId)` — see there for when to use it.
+ * 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 declare class ScopedStack implements StackClient {
     private readonly stack;
-    private readonly requesterEntityId;
-    constructor(stack: Stack, requesterEntityId: string | null);
+    private readonly principalEntityId;
+    private readonly subjectEntityId;
+    private readonly idTimestampSkewMs;
+    private readonly adapter;
+    constructor(stack: Stack, principalEntityId: EntityId | null, subjectEntityId: EntityId | null, idTimestampSkewMs: number | null, adapter: StackAdapter);
     get features(): StackFeatures;
     private resolveRecord;
+    /** Whether a delegated app is acting for someone other than itself. */
+    private get delegated();
+    /**
+     * 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.
+     */
+    private get ownerActingAlone();
     private checkRead;
     private checkWrite;
     /**
-     * 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.
      */
     private hasGrant;
+    /**
+     * 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.
+     */
+    private principalAllows;
+    /**
+     * 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.
+     */
+    private subjectAllows;
     private canRead;
     private checkCreateGrant;
-    /** Fetch a record the requester can update (via permissions or an update grant), or throw. */
+    /**
+     * `_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.
+     */
+    private isGroupManager;
+    /** Whether one identity, on its own, manages `record` — see isGroupManager(). */
+    private managesGroup;
+    /**
+     * 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.
+     */
     private requireUpdatable;
-    /** 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.
+     */
     private requireDeletable;
     /**
-     * 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.
+     */
+    private canReadReferent;
+    /**
+     * 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.
+     */
+    private hasReadableReference;
+    /**
+     * 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.
+     */
+    private canAccessFile;
+    /** Names of the type's top-level file-ref fields — the content-reference half of attachmentFileId matching. */
+    private fileRefFieldNames;
+    /**
+     * 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).
+     */
+    private requireFileRefAccess;
+    /**
+     * 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.
+     */
+    private requireAssociationAccess;
+    /**
+     * 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.
      */
     create<T extends Record<string, unknown> = Record<string, unknown>>(typeId: TypeId, content: T, opts?: CreateRecordOptions): Promise<StackRecord & {
         content: T;
     }>;
+    /**
+     * 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.
+     */
+    private mayGrantAccess;
+    /**
+     * 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.
+     */
+    private mayReshare;
     get(id: string, opts?: GetRecordOptions): Promise<StackRecord | null>;
     /**
-     * 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).
+     * 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.
+     */
+    query(query?: StackQuery): Promise<QueryResult>;
+    update(id: string, content: Record<string, unknown | null>, opts?: IfVersionOptions): Promise<StackRecord>;
+    /**
+     * 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.
      *
-     * `total` is always null — see the QueryResult.total doc comment.
+     * 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.
      *
-     * Grant records are pre-fetched once before the pagination loop so read
-     * grants don't trigger a separate _grant@1 query per record.
+     * `_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.
+     */
+    private requireOwnerForAppIdentity;
+    /**
+     * 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.
+     */
+    private requireAppIdMatchesPrincipal;
+    /**
+     * 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.
+     */
+    private requireOwnerForOwnerDid;
+    /**
+     * 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.
+     */
+    private requireOwnerForGrantRecord;
+    associate(id: string, association: Association, opts?: IfVersionOptions): Promise<void>;
+    dissociate(id: string, association: Association, opts?: IfVersionOptions): Promise<void>;
+    setPermissions(id: string, permissions: Permission[], opts?: IfVersionOptions): Promise<void>;
+    /**
+     * 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.
      */
-    query(query?: StackQuery): Promise<QueryResult>;
-    update(id: string, content: Record<string, unknown | null>): Promise<StackRecord>;
-    associate(id: string, association: Association): Promise<void>;
-    dissociate(id: string, association: Association): Promise<void>;
-    setPermissions(id: string, permissions: Permission[]): Promise<void>;
     delete(id: string, opts?: DeleteRecordOptions): Promise<void>;
+    /**
+     * 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().
+     */
+    undelete(id: string, opts?: IfVersionOptions): Promise<StackRecord>;
+    /**
+     * 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.
+     */
     getVersions(id: string): Promise<RecordVersion[]>;
+    /** See getVersions() — same mutate-surface gate, same permissions stripping. */
     getVersion(id: string, version: number): Promise<RecordVersion | null>;
-    restoreVersion(id: string, version: number): Promise<StackRecord>;
     /**
-     * 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.
+     * 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.
+     */
+    restoreVersion(id: string, version: number, opts?: IfVersionOptions): Promise<StackRecord>;
+    /**
+     * 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.
      */
-    putAttachment(data: Uint8Array, mimeType: string, filename?: string): Promise<string>;
+    commitMigration(id: string, toTypeId: TypeId, content: Record<string, unknown>, opts?: IfVersionOptions): Promise<StackRecord>;
     /**
-     * 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.
+     * 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.
+     */
+    putAttachment(data: Uint8Array, mimeType: string, filename?: string, appId?: AppId): Promise<StackRecord & {
+        content: AttachmentContent;
+    }>;
+    /**
+     * 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).
      */
     getAttachment(fileId: string): Promise<Uint8Array>;
     /**
@@ -341,5 +1034,10 @@ export declare class ScopedStack implements StackClient {
      * Delegates to Stack.deleteAttachment(), which enforces the "not referenced" check.
      */
     deleteAttachment(fileId: string): Promise<void>;
+    /**
+     * Sweep for unreferenced attachment bytes and delete them. Only the stack
+     * owner may run this. Delegates to Stack.collectAttachmentGarbage().
+     */
+    collectAttachmentGarbage(opts?: CollectAttachmentGarbageOptions): Promise<CollectAttachmentGarbageResult>;
 }
 //# sourceMappingURL=stack.d.ts.map