@haverstack/core 0.28.0 → 0.30.0

package/dist/stack.d.ts

@@ -13,19 +13,9 @@
  *
  * Apps should never talk to a StackAdapter directly.
  */
-import type { SchemaDriftViolation } from './schema.js';
-import { ChangeEmitter } from './changes.js';
-import type { ValidationError } from './validate.js';
-import type { StackRecord, StackType, TypeSchema, TypeId, StackAdapter, StackQuery, QuerySort, RecordFilter, QueryResult, Association, RelationshipTarget, Permission, Migration, RecordVersion, StackFeatures, GrantAction, AttachmentContent, FileId, EntityId, AppId, RecordId, TokenSession, ActorOptions, RecordChange, SubscribeOptions, Unsubscribe } from './types.js';
-/**
- * Who a grant() / revoke() / listGrants() call targets: a specific entity
- * (DID), a `_group` Record's roster (by ID), or `null` for the default
- * grant / default-only listing. See docs/spec/access-control.md § Type-level
- * grants.
- */
-export type GrantTarget = EntityId | {
-    groupId: RecordId;
-} | null;
+import type { StackRecord, StackType, TypeSchema, TypeId, StackAdapter, StackQuery, QueryResult, Association, Permission, Migration, RecordVersion, StackFeatures, GrantAction, AttachmentContent, FileId, EntityId, AppId, TokenSession, ActorOptions, RecordChange, RecordChanges, SubscribeOptions, Unsubscribe } from './types.js';
+import type { GrantTarget } from './grants.js';
+import { ScopedStack } from './scoped-stack.js';
 export type CreateRecordOptions = {
     /**
      * Client-minted record ID. Must be 12 lowercase Crockford base-32
@@ -49,7 +39,7 @@ export type CreateRecordOptions = {
     /**
      * Create the record already unlisted, so the create event itself is
      * withheld from the feed — there is no window where the record exists
-     * and is listed before setUnlisted() catches up. See
+     * and is listed before a mutation catches up. See
      * docs/spec/unlisted.md.
      */
     unlisted?: boolean;
@@ -151,204 +141,6 @@ export type DeleteRecordOptions = IfVersionOptions & {
 export type DefineTypeOptions = {
     migratesFrom?: TypeId;
 };
-/**
- * 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 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 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 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 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, a malformed TypeId, search text the engine
- * cannot parse, or a typeId no definition exists for). Distinct from
- * StackValidationError, which means the request was well-formed but content
- * failed schema validation.
- *
- * Naming something absent belongs here rather than under `not_found`: a
- * request whose *type* is undefined never addressed a record, so answering
- * 404 would say a record was missing when none was asked for.
- */
-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, 'filter'>): void;
-/**
- * Split a content filter key into path segments. Write-time validation
- * keeps stored field names free of the path metacharacters, but a filter
- * arrives from a request body and has made no such promise, so the same
- * rule is enforced here. See docs/spec/data-model.md § Content field names.
- */
-export declare function parseContentFilterKey(key: string): string[];
-/**
- * Reject a sort whose field or direction is outside the closed set the
- * types promise. `QuerySort` is typed `'asc' | 'desc'`, but a type is not a
- * runtime guard: a server mapping `?direction=` onto a query, or a
- * delegated app calling query(), supplies a raw string. A SQLite record
- * adapter interpolates the direction straight into `ORDER BY`, so an
- * unvalidated value there is a SQL-injection sink reachable from every
- * untrusted caller. Validating in the invariant layer — the same reason
- * emission and _config protection live here — means no adapter can forget
- * it. See docs/spec/data-model.md § Sorting and pagination.
- */
-export declare function assertValidSort(sort: QuerySort | undefined): void;
-/**
- * Fail loud rather than silently reorder: an adapter that can't honor the
- * requested sort would otherwise answer in some other order, which a
- * caller paging a bounded window has no way to notice. The companion to
- * assertQueryCapabilities(), split from it because a sort is not a filter
- * — see docs/spec/data-model.md § Capability-gated filters.
- */
-export declare function assertSortCapability(sort: QuerySort | undefined, capabilities: Pick<StackFeatures, 'sort'>): void;
-/**
- * Reject a relationship filter that names neither a label nor a target,
- * or whose target is malformed. `RelatedToFilter` promises one half is
- * always present; without the runtime check a filter decoded from a
- * request could arrive empty and match every record carrying any
- * relationship. See docs/spec/data-model.md § Filter.
- */
-export declare function assertValidRelatedTo(relatedTo: RecordFilter['relatedTo']): void;
-/**
- * Thrown when an attachment upload exceeds the adapter's declared
- * `limits.attachmentBytes` 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);
-}
-/**
- * Thrown when a scoped view is asked to observe a stack whose adapter
- * relays a remote feed. Outside the StackError taxonomy for the same
- * reason StackClosedError is: it reports a topology the caller assembled,
- * not a state a request can be in.
- *
- * A relayed frame is scoped by the authority that opened the feed, and a
- * narrower scope cannot re-derive that decision — a purge leaves no record
- * to check `canRead` against. Delivering anyway would break the promise
- * that a subscriber never sees what it may not read; delivering only local
- * writes would silently drop every change made elsewhere, which is the
- * failure that looks fine in testing. So it refuses.
- * See docs/spec/events.md § Permission scoping.
- */
-export declare class StackRelayScopeError 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
@@ -371,18 +163,20 @@ export interface StackClient {
     getEntityByDid(did: EntityId): Promise<StackRecord | null>;
     /** getEntityByDid() for the one DID every stack reserves: its own owner. */
     getOwnerEntity(): Promise<StackRecord | null>;
-    update(id: string, content: Record<string, unknown | null>, opts?: IfVersionOptions): Promise<StackRecord>;
+    /**
+     * Apply a change set: any combination of content patch, `parentId`,
+     * `permissions`, `associations` and `unlisted`, in one atomic write
+     * producing one version. Keys are read for presence, so `unlisted: false`
+     * and `parentId: null` are changes; a change set naming no key at all is
+     * a StackQueryError. Under ScopedStack each key carries its own gate and
+     * one refused key refuses the call.
+     * See docs/spec/data-model.md § Mutations.
+     */
+    mutate(id: string, changes: RecordChanges, opts?: IfVersionOptions): Promise<StackRecord>;
+    /** mutate() with `contentPatch` alone — the common case, named for it. */
+    patchContent(id: string, patch: Record<string, unknown | null>, opts?: IfVersionOptions): Promise<StackRecord>;
     associate(id: string, association: Association, opts?: IfVersionOptions): Promise<StackRecord>;
     dissociate(id: string, association: Association, opts?: IfVersionOptions): Promise<StackRecord>;
-    setPermissions(id: string, permissions: Permission[], opts?: IfVersionOptions): Promise<StackRecord>;
-    setUnlisted(id: string, unlisted: boolean, opts?: IfVersionOptions): Promise<StackRecord>;
-    /**
-     * Move a record into another container, or to the root with `null`.
-     * The only native field a write-holder may change after creation; it
-     * decides enumeration, never access. See docs/spec/data-model.md
-     * § Reparenting.
-     */
-    setParent(id: string, parentId: string | null, opts?: IfVersionOptions): Promise<StackRecord>;
     delete(id: string, opts?: DeleteRecordOptions): Promise<void>;
     undelete(id: string, opts?: IfVersionOptions): Promise<StackRecord>;
     getVersions(id: string): Promise<RecordVersion[]>;
@@ -434,7 +228,7 @@ export declare class Stack implements StackClient {
     /**
      * Announce a mutation that has already been persisted. Called after the
      * adapter write resolves and before the mutating method settles, so
-     * `await stack.update(...)` guarantees subscribers have been notified —
+     * `await stack.mutate(...)` guarantees subscribers have been notified —
      * and nothing about work they deferred. A handler cannot fail the write:
      * there is nothing left to fail. See docs/spec/events.md § Handlers.
      */
@@ -563,16 +357,62 @@ export declare class Stack implements StackClient {
      */
     get(id: string, opts?: GetRecordOptions): Promise<StackRecord | null>;
     /**
-     * Update a record's content via JSON Merge Patch: omitted fields are
-     * kept, null removes a field. Validates the merged result against the
-     * record's *current* stored type and never changes typeId (see
-     * docs/spec/data-model.md § Type migrations); snapshots the prior state
-     * to version history. Associations and permissions have their own methods.
+     * Apply a change set — content patch, `parentId`, `permissions`,
+     * `associations`, `unlisted`, in any combination — as one atomic write
+     * producing one version and one snapshot. Keys are read for presence, so
+     * `unlisted: false` and `parentId: null` are changes.
+     *
+     * Every key present is checked against the record as it stands, and a
+     * change set already satisfied in all of them writes nothing and returns
+     * the record unchanged. The ops the change event carries are derived
+     * from that same comparison, so naming an aspect without moving it is
+     * never reported as moving it.
+     *
+     * Content is validated against the record's *current* stored type and
+     * `typeId` never changes (see docs/spec/data-model.md § Type
+     * migrations). See docs/spec/data-model.md § Mutations.
+     */
+    mutate(id: string, changes: RecordChanges, opts?: IfVersionOptions & ActorOptions): Promise<StackRecord>;
+    /**
+     * mutate() with `contentPatch` alone. The common case by a wide margin,
+     * and named for what it does rather than for a symmetry with create()
+     * that a patch does not have.
+     */
+    patchContent(id: string, patch: Record<string, unknown | null>, opts?: IfVersionOptions & ActorOptions): Promise<StackRecord>;
+    /**
+     * Every check a change set owes before anything is written, in one pass:
+     * one refused key refuses the call, so none of them may run after a
+     * partial write. Returns the merged content when the set carries a
+     * content patch, since the caller needs it to decide whether content
+     * actually moved.
+     *
+     * Parent existence and acyclicity are asked only when the destination
+     * differs from where the record already sits — a move to where it
+     * already is names no new edge, and would otherwise cost a read apiece.
      */
-    update(id: string, content: Record<string, unknown | null>, opts?: IfVersionOptions & ActorOptions): Promise<StackRecord>;
+    private validateChangeSet;
+    /**
+     * Refuse a write that would leave a `_group` Record with no `admin` on
+     * its roster. Asked of the roster the write would *produce* — the one
+     * place a change-set check reads the post-state rather than the
+     * pre-state, because the rule is about what is left behind rather than
+     * what the caller named.
+     *
+     * That framing is the whole of the self-removal question: an `admin`
+     * removing themselves passes while another remains and is refused when
+     * they are the last, and neither case needs to know whose entry went.
+     *
+     * Lives here rather than in `ScopedStack` deliberately. Who may write a
+     * `_group` is a permission question and belongs to the gate up there;
+     * this is an integrity constraint on the Record, so it binds every
+     * requester — the stack owner included, who would otherwise be the hole
+     * that stops anything downstream relying on the invariant.
+     * See docs/spec/identity.md § Group.
+     */
+    private assertGroupAdminRemains;
     /**
      * Add an association to a record. Snapshots the record's prior state and
-     * bumps version, same as update() — associations are covered by the same
+     * bumps version, same as patchContent() — associations are covered by the same
      * versioning rule as content.
      * If the association already exists (same kind, label, and payload), this
      * is a no-op. Returns the record as it now stands — unchanged on a no-op.
@@ -585,43 +425,21 @@ export declare class Stack implements StackClient {
      */
     dissociate(id: string, association: Association, opts?: IfVersionOptions & ActorOptions): Promise<StackRecord>;
     /**
-     * Replace all permissions on a record. Snapshots and bumps version, same
-     * as associate(). Pass an empty array to make the record private (the
-     * default). No-op if the new set is deep-equal to the current one. Returns
-     * the record as it now stands — unchanged on a no-op.
-     */
-    setPermissions(id: string, permissions: Permission[], opts?: IfVersionOptions & ActorOptions): Promise<StackRecord>;
-    /**
-     * Withhold a record from enumeration, or restore it. Orthogonal to
-     * setPermissions(): it says nothing about who may read the record, only
-     * whether `query()` and the change feed enumerate it by default. No-op if
-     * already in the requested state. Returns the record as it now stands —
-     * unchanged on a no-op. See docs/spec/access-control.md §
-     * Unlisted records.
-     *
-     * The op passed to emitChange() carries the transition direction —
-     * `unlist` (kind `deleted`, so subscribers already holding the record are
-     * told to drop it) or `list` (kind `changed`, an upsert like `undelete`,
-     * for the record's publish moment).
-     */
-    setUnlisted(id: string, unlisted: boolean, opts?: IfVersionOptions & ActorOptions): Promise<StackRecord>;
-    /**
-     * Move a record into another container, or to the root with `null`.
-     * Snapshots and bumps version, same as setUnlisted(). No-op if the
-     * record is already there. Returns the record as it now stands —
-     * unchanged on a no-op.
+     * The checks a *caller-named* destination owes, before the cycle walk:
+     * `parentId` is a real, well-formed record id. Format first, so a
+     * malformed one is a 400 naming the problem rather than a read that
+     * cannot match. Existence closes the gap between the owner path and a
+     * non-owner's, where canReadReferent() already refuses a parent that
+     * isn't there.
      *
-     * `parentId` is the one native field a write-holder may move after
-     * creation, and it confers nothing: containment is not an
-     * access-control edge, so a move changes which queries and feeds
-     * enumerate a record and nothing about who may read it. See
-     * docs/spec/data-model.md § Reparenting.
+     * restoreVersion() deliberately does not call this — see its own comment.
+     * See docs/spec/data-model.md § Reparenting.
      */
-    setParent(id: string, parentId: string | null, opts?: IfVersionOptions & ActorOptions): Promise<StackRecord>;
+    private assertParentExists;
     /**
      * Refuse an edge that would make a record its own ancestor — asked at
-     * every site that adds one: setParent(), a restore putting a container
-     * back, and a create naming both its own id and a parent. Nothing
+     * every site that adds one: a change set naming `parentId`, a restore
+     * putting a container back, and a create naming both its own id and a parent. Nothing
      * downstream (a generator deriving a page path, a folder view) is
      * written to survive a cycle.
      *
@@ -639,18 +457,6 @@ export declare class Stack implements StackClient {
      * the same posture applied here.
      * See docs/spec/data-model.md § Reparenting.
      */
-    /**
-     * The checks a *caller-named* destination owes, before the cycle walk:
-     * `parentId` is a real, well-formed record id. Format first, so a
-     * malformed one is a 400 naming the problem rather than a read that
-     * cannot match. Existence closes the gap between the owner path and a
-     * non-owner's, where canReadReferent() already refuses a parent that
-     * isn't there.
-     *
-     * restoreVersion() deliberately does not call this — see its own comment.
-     * See docs/spec/data-model.md § Reparenting.
-     */
-    private assertParentExists;
     private assertNoParentCycle;
     /**
      * Soft-delete a record (default) or hard-delete it permanently, removing
@@ -695,12 +501,12 @@ export declare class Stack implements StackClient {
     /**
      * Commit a per-record migration: replace `content` and `typeId` together
      * in one step, validated against `toTypeId`'s schema exactly as
-     * create()/update() validate against a type's schema. The single-record
+     * create()/mutate() validate against a type's schema. The single-record
      * counterpart to migrateAll() — content here is supplied by the caller
      * (computed client-side by the type's owning app, per
      * docs/spec/wire-format.md § Migration commit) rather than a registered
      * Migration function. Snapshots the prior state to version history, same
-     * as update()/restoreVersion(), and takes the same optional `ifVersion`
+     * as mutate()/restoreVersion(), and takes the same optional `ifVersion`
      * precondition every version-bumping mutation takes — checked atomically
      * at the adapter, not here (see docs/spec/versioning.md § Optimistic
      * concurrency).
@@ -710,7 +516,7 @@ export declare class Stack implements StackClient {
      * record as it stands, so it owes both sets of integrity checks — the
      * binding rules, the attachment rules, and `_config`'s. Missing either
      * half would make migrate a second, unguarded write path to the same
-     * state create()/update() refuse to reach.
+     * state create()/mutate() refuse to reach.
      */
     commitMigration(id: string, toTypeId: TypeId, content: Record<string, unknown>, opts?: IfVersionOptions & ActorOptions): Promise<StackRecord>;
     /**
@@ -734,7 +540,7 @@ export declare class Stack implements StackClient {
     /**
      * Immutability for every binding field a patch touches, then uniqueness
      * for the subset that carries it. Fields absent from the patch carry no
-     * new claim — update() is a merge, so an untouched binding is the one the
+     * new claim — a content patch is a merge, so an untouched binding is the one the
      * card already holds.
      */
     private checkBindingsOnUpdate;
@@ -797,27 +603,21 @@ export declare class Stack implements StackClient {
      */
     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.
+     * filename is the only mutable field on an `_attachment@1` record; fileId,
+     * size and mimeType are immutable, and the correction flow is delete +
+     * re-upload. `violates` decides what counts as touching one, because the
+     * two write shapes disagree: a patch names only what it changes, while a
+     * migration replaces content wholesale and necessarily re-sends all three.
      *
      * 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.
+     * See docs/spec/attachments.md § The `_attachment` record type.
      */
-    private checkAttachmentImmutableOnMigrate;
+    private assertAttachmentImmutable;
     /**
-     * `_config.entityId` defines stack ownership; neither update() nor
+     * `_config.entityId` defines stack ownership; neither patchContent() nor
      * restoreVersion() may change it. A conflict with stack integrity, not a
      * schema violation — hence StackConflictError. See docs/spec.md § The
      * `_config` record.
@@ -876,12 +676,6 @@ export declare class Stack implements StackClient {
      * not a failure. See docs/spec/attachments.md § Garbage collection.
      */
     collectAttachmentGarbage(opts?: CollectAttachmentGarbageOptions & ActorOptions): 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.
-     */
     /**
      * Observe every change made through this Stack. Unscoped, so no
      * permission filter applies — a caller holding a `Stack` already reaches
@@ -910,6 +704,12 @@ export declare class Stack implements StackClient {
      * ScopedStack can refuse a scope it cannot honor; not an app-facing API.
      */
     get relaysChanges(): boolean;
+    /**
+     * 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>;
     /**
      * Flush, then release any resources the adapter holds (connections, file
@@ -979,6 +779,15 @@ export declare class Stack implements StackClient {
      * snapshotting work when the mismatch is already visible.
      */
     private checkIfVersion;
+    /**
+     * The options every version-bumping adapter write carries: the `ifVersion`
+     * precondition, the prior-state snapshot that has to land in the same
+     * atomic write, and who to attribute the change to. Taken together so a
+     * new mutating verb cannot quietly omit one — `updatedVia` most of all,
+     * whose absence reads as an undelegated write.
+     * See docs/spec/versioning.md § Version history.
+     */
+    private writeOptions;
     /**
      * Snapshot of a record's prior state, passed with the mutating adapter
      * call so snapshot and mutation land in one atomic write. `associations`
@@ -989,405 +798,4 @@ export declare class Stack implements StackClient {
      */
     private buildVersionSnapshot;
 }
-/** Structural equality per target arm — what dissociate() matches on. */
-export declare function targetEqual(a: RelationshipTarget, b: RelationshipTarget): boolean;
-export declare class ScopedStack implements StackClient {
-    private readonly stack;
-    private readonly principalEntityId;
-    private readonly subjectEntityId;
-    private readonly idTimestampSkewMs;
-    private readonly adapter;
-    private readonly changes;
-    constructor(stack: Stack, principalEntityId: EntityId | null, subjectEntityId: EntityId | null, idTimestampSkewMs: number | null, adapter: StackAdapter, changes: ChangeEmitter);
-    get features(): StackFeatures;
-    private resolveRecord;
-    /** Whether a delegated app is acting for someone other than itself. */
-    private get delegated();
-    /**
-     * Who this request is, for stamping onto whatever it mutates. Attribution
-     * follows record-level authorship: the subject is the actor, and the
-     * principal is named beside it only when the two differ.
-     * See docs/spec/data-model.md § Authorship and attribution.
-     */
-    private get actor();
-    /**
-     * 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. Shared with the predicate a server applies to a
-     * session, which decides the same tier one step earlier. See
-     * docs/spec/access-control.md § Delegation: principal and subject.
-     */
-    private get ownerActingAlone();
-    private checkRead;
-    private checkWrite;
-    /**
-     * 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.
-     *
-     * Group-targeted grants don't count here either, one step removed: a
-     * roster is editable by any of the group's admins, so authority reaching
-     * a principal through one would let someone other than the owner name an
-     * app to a type. See docs/spec/access-control.md § Type-level grants.
-     */
-    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;
-    /**
-     * How to refuse a record this request addressed by ID. A requester who
-     * can read the record is told it exists and the verb was refused;
-     * everyone else is told what a missing ID is told, so no one learns an ID
-     * is live who could not have learned it by reading. `message` therefore
-     * only ever reaches someone holding the record already.
-     * See docs/spec/access-control.md § Errors and information exposure.
-     */
-    private denialFor;
-    private canRead;
-    private checkCreateGrant;
-    /**
-     * `_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;
-    /**
-     * Refuse a mutation aimed at a soft-deleted Record. Asked only of a
-     * mutating caller, so the history readers borrowing this gate still work,
-     * and only after the authority decision, so "exists but deleted" is never
-     * a probe a stranger can run. See docs/spec/versioning.md § Mutations are
-     * refused, not applied to a tombstone.
-     */
-    private refuseIfDeleted;
-    /**
-     * Fetch a record the subject can reach and the principal holds `delete` on
-     * (via permissions or a delete grant), or throw.
-     */
-    private requireDeletable;
-    /**
-     * 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.
-     * `_attachment@1` records are excluded from matching outright: the
-     * carve-out must be satisfied by some *other* record referencing the
-     * file, never by the requester's own prior metadata record for it —
-     * allowing that would let one successful guess unlock unlimited further
-     * metadata records for the same fileId, reintroducing the circularity
-     * the carve-out's uploader-clause exclusion closes.
-     * 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, and a `relationship` naming a record in this stack
-     * requires read access to it. `tag` is unchecked, and `_group` roster
-     * associations are gated by the stricter isGroupManager() instead.
-     *
-     * The other target arms are ungated because the gate's purpose —
-     * refusing a reference that would convey access to, or confirm the
-     * existence of, an unreadable record — has nothing to bite on: core
-     * never resolves them, so no access flows through one.
-     * 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.
-     * `createdAt`/`updatedAt` are refused to everyone but the owner acting
-     * alone — see the guard below and docs/spec/data-model.md § Record IDs.
-     * See also docs/spec/access-control.md and docs/spec/attachments.md.
-     */
-    create<T extends Record<string, unknown> = Record<string, unknown>>(typeId: TypeId, content: T, opts?: BackdatableCreateRecordOptions): 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;
-    /**
-     * A record this request may read, or null. Never throws
-     * StackPermissionError: an unreadable record answers exactly as a missing
-     * one does, so a caller learns only what it may read.
-     * See docs/spec/access-control.md § Errors and information exposure.
-     */
-    get(id: string, opts?: GetRecordOptions): Promise<StackRecord | null>;
-    /**
-     * Runs through this.query(), so canRead() still applies — this answers a
-     * question the caller asks on its own behalf. includeUnlisted is passed
-     * only when the request is the owner acting alone, per
-     * docs/spec/identity.md § DID bindings.
-     */
-    getEntityByDid(did: EntityId): Promise<StackRecord | null>;
-    getOwnerEntity(): Promise<StackRecord | null>;
-    /**
-     * 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. 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.
-     *
-     * 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.
-     */
-    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<StackRecord>;
-    dissociate(id: string, association: Association, opts?: IfVersionOptions): Promise<StackRecord>;
-    setPermissions(id: string, permissions: Permission[], opts?: IfVersionOptions): Promise<StackRecord>;
-    /**
-     * Withhold a record from enumeration, or restore it — gated exactly like
-     * setPermissions(), since both decide who or what can discover the
-     * record rather than merely read it once found. See
-     * docs/spec/unlisted.md.
-     */
-    setUnlisted(id: string, unlisted: boolean, opts?: IfVersionOptions): Promise<StackRecord>;
-    /**
-     * Move a record into another container, or to the root with `null`.
-     * Gated as an ordinary write on the record, plus read access to the
-     * destination — the same reference gate `create()` applies to a
-     * `parentId`, asked again here so a move cannot reach a container an
-     * authoring call could not have named. Not reshare-gated like
-     * setUnlisted(): containment decides which listings enumerate a record,
-     * never who may read it, so a move discloses it to nobody who could not
-     * already read it. The origin is ungated — knowing it requires reading
-     * the record, which this caller has already had to do. See
-     * docs/spec/access-control.md § Reference-creation gating.
-     */
-    setParent(id: string, parentId: string | null, opts?: IfVersionOptions): Promise<StackRecord>;
-    /**
-     * 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.
-     */
-    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>;
-    /**
-     * 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 — the snapshot's `parentId` among them, gated
-     * exactly as setParent() gates a destination named directly. Only the
-     * owner acting alone is exempt: under delegation the checks resolve
-     * against the subject, which is whose reach the restore would widen.
-     * See docs/spec/versioning.md § Restore semantics.
-     */
-    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.
-     */
-    commitMigration(id: string, toTypeId: TypeId, content: Record<string, unknown>, opts?: IfVersionOptions): Promise<StackRecord>;
-    /**
-     * 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>;
-    /**
-     * Delete an attachment. Only the stack owner may delete attachments.
-     * 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>;
-    /**
-     * Observe the changes this request may read. The predicate is canRead
-     * applied per event — the same one get() and query() answer with, so a
-     * feed can't disagree with them about what this session sees.
-     *
-     * A record the subscriber cannot read produces no event at all, rather
-     * than an empty or redacted one: the existence of a change is itself a
-     * disclosure, the same reasoning that keeps a count of the whole match
-     * off a query result. See docs/spec/events.md § Permission scoping.
-     */
-    subscribe(handler: (change: RecordChange) => void, opts?: SubscribeOptions): Promise<Unsubscribe>;
-    /**
-     * canRead for one event, through the subscription's own cache. Grants
-     * are prefetched once and refilled after an invalidation rather than
-     * re-queried per event, which would be a `_grant` scan for every change
-     * the stack makes.
-     */
-    private canReadCached;
-}
 //# sourceMappingURL=stack.d.ts.map