@haverstack/core 0.40.0 → 0.42.0

package/dist/stack.d.ts

@@ -1,971 +0,0 @@
-/**
- * Stack — Core Stack Class
- * -------------------------------------------------------
- * The Stack class is the primary interface for apps. It sits
- * on top of a StackAdapter and adds:
- *
- *  - ID generation
- *  - Type definition and schema hashing
- *  - Content validation on write
- *  - Migration registry and explicit, owner-driven migrateAll()
- *  - Version snapshotting on update
- *  - Soft delete and purge
- *
- * Apps should never talk to a StackAdapter directly.
- */
-import type { StackRecord, StackType, TypeSchema, TypeId, BaseId, StackAdapter, StackQuery, QueryResult, AssociationEdit, AuthorityAssociation, DataAssociation, Migration, RecordVersion, StackCapabilities, IfVersionOptions, GrantContent, TypeGrant, PutAttachmentOptions, AttachmentContent, FileId, EntityId, AppId, RecordId, Actor, ActorOptions, RecordChange, RecordChangeSet, SubscribeOptions, Unsubscribe, JournalQuery, VersionsQuery, RecordJournalEntry } from './types.js';
-import type { GrantQuery } from './grants.js';
-import { ScopedStack } from './scoped-stack.js';
-import type { ContentOf, PatchOf, ReadonlyTypeSchema, TypedChange, TypedChangeSet, TypedQuery, TypedSubscribeOptions, TypedRecord, TypeHandle } from './type-handle.js';
-/**
- * An Actor in the one form `Stack` stores: a `principalId` equal to the
- * subject is dropped, so "acted as itself" has a single spelling, and an
- * empty id is refused rather than stored as a name for nobody.
- * See docs/spec/data-model.md § Actor.
- */
-export declare function normalizeActor(actor: Actor | undefined): Actor | undefined;
-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?: RecordId;
-    parentId?: RecordId;
-    /**
-     * The author. ScopedStack sets this from its own identities; callers of
-     * plain Stack supply it only when reconstructing an attributed write.
-     * See StackRecord.createdBy.
-     */
-    createdBy?: Actor;
-    /** Reverse-DNS identifier of the writing software — see AppId. */
-    appId?: AppId;
-    permissions?: AuthorityAssociation[];
-    associations?: DataAssociation[];
-    /**
-     * 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 a mutation catches up. See
-     * docs/spec/unlisted.md.
-     */
-    unlisted?: boolean;
-};
-/**
- * CreateRecordOptions extended with createdAt/updatedAt, for backdating a
- * record's clock fields on import. Unscoped Stack.create() accepts them
- * unconditionally; ScopedStack.create() only from the stack owner acting
- * alone, since a grantee or a delegated app could otherwise forge a sort
- * position the same way a raw `id` could.
- * See docs/spec/data-model.md § Record IDs.
- */
-export type BackdatableCreateRecordOptions = CreateRecordOptions & {
-    /**
-     * The record's creation time. When `id` is also supplied, its embedded
-     * timestamp must agree with this within `idTimestampSkewMs` (default 24h;
-     * see StackOptions.idTimestampSkewMs) or the create throws
-     * StackValidationError. Omit `id` to have it derived from this timestamp
-     * instead. Defaults to now.
-     */
-    createdAt?: Date;
-    /**
-     * The record's last-modified time. Defaults to `createdAt` (or now, if
-     * `createdAt` is omitted too) — never to the actual current time — so a
-     * plain import doesn't fabricate a fake edit. Must not precede
-     * `createdAt`.
-     */
-    updatedAt?: Date;
-};
-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 two timestamp-prefix checks: the one
-     * ScopedStack.create() runs on a non-backdated create's client-supplied
-     * `id` against the current time, and the one Stack.create() runs between
-     * an explicit `id` and an explicit `createdAt` when both are supplied —
-     * reached directly when unscoped, or via ScopedStack.create() when the
-     * requester is the owner acting alone. Default: 24 hours; null disables
-     * both. 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 = {
-    /** The files collected — or, on a dry run, the ones that would be. */
-    deletedFileIds: FileId[];
-    reclaimedBytes: number;
-};
-export type GetRecordOptions = {
-    /**
-     * 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';
-    /**
-     * Soft-deleted records are hidden by default, as query() hides them: a
-     * tombstone reads as `null`. Pass true to read it back.
-     * See docs/spec/versioning.md § Deletion.
-     */
-    includeDeleted?: boolean;
-};
-export type DeleteRecordOptions = IfVersionOptions & {
-    /** If true, permanently remove the record and all its history. Default: false */
-    purge?: boolean;
-};
-/**
- * What a delete reports back. Information, not action: a purge never
- * touches the blob store, and nothing here is deleted by having been
- * named. See docs/spec/attachments.md § A purge strands the bytes it
- * referenced.
- */
-export type DeleteResult = {
-    /**
-     * The files the purged record referenced — its attachment associations
-     * and its `file-ref` content fields, deduplicated. The purge removes the
-     * only rows naming them, so this is the caller's one chance to hold the
-     * argument `deleteAttachment()` takes. Empty on a soft delete, which
-     * strands nothing: a tombstone's references stand.
-     */
-    referencedFileIds: FileId[];
-};
-/**
- * What deleteAndReturn() reports back — DeleteResult plus the record itself,
- * captured inside the same atomic operation as the destroy rather than a
- * read beforehand. See Stack.deleteAndReturn().
- */
-export type DeleteAndReturnResult = DeleteResult & {
-    /**
-     * The record as it stood at the moment of deletion: immediately before
-     * destruction for a purge, or the resulting tombstone for a soft
-     * delete. Null only for the purge no-op — there was nothing to
-     * delete, and nothing to report; every other outcome throws instead of
-     * returning null (see Stack.delete()'s own no-op cases).
-     */
-    record: StackRecord | null;
-};
-/** The argument to Stack.defineType(). */
-export type DefineTypeOptions = {
-    id: TypeId;
-    name: string;
-    /** A handle's `schema` is accepted as written, readonly members and all. */
-    schema: ReadonlyTypeSchema;
-    migratesFrom?: TypeId;
-};
-/**
- * The app-facing record API, implemented by both Stack and ScopedStack.
- * Accept this type in plugin or extension code to remain adapter-agnostic
- * and work equally well with a full Stack or a permission-scoped view.
- */
-export interface StackClient {
-    readonly capabilities: StackCapabilities;
-    create<S extends ReadonlyTypeSchema>(handle: TypeHandle<S>, content: ContentOf<S>, opts?: CreateRecordOptions): Promise<TypedRecord<S>>;
-    create<T extends Record<string, unknown> = Record<string, unknown>>(typeId: TypeId, content: T, opts?: CreateRecordOptions): Promise<StackRecord & {
-        content: T;
-    }>;
-    /**
-     * Typed read: the record at `presentAt: 'latest'`, checked to be exactly
-     * the handle's Type with every enum field holding a value the handle
-     * lists, else it throws. Live records only — a tombstone reads as `null`,
-     * and there is no `includeDeleted`.
-     * See docs/spec/data-model.md § Type handles.
-     */
-    get<S extends ReadonlyTypeSchema>(handle: TypeHandle<S>, id: RecordId): Promise<TypedRecord<S> | null>;
-    get(id: RecordId, opts?: GetRecordOptions): Promise<StackRecord | null>;
-    /** Typed read of the handle's whole family — see the typed `get()`. */
-    query<S extends ReadonlyTypeSchema>(handle: TypeHandle<S>, query?: TypedQuery): Promise<{
-        records: TypedRecord<S>[];
-        cursor: string | null;
-    }>;
-    query(query?: StackQuery): Promise<QueryResult>;
-    /**
-     * Resolve a DID to its `_entity` card — family-wide and soft-deleted
-     * inclusive, per docs/spec/identity.md § DID bindings. No caching.
-     *
-     * Under `ScopedStack`, `null` covers missing, unreadable, and (unless the
-     * owner is acting alone) unlisted — never evidence the card is absent.
-     */
-    getEntityByDid(did: EntityId): Promise<StackRecord | null>;
-    /** getEntityByDid() for the one DID every stack reserves: its own owner. */
-    getOwnerEntity(): Promise<StackRecord | null>;
-    /**
-     * Apply a change set: any combination of content patch, `parentId`,
-     * `permissions`, `associations` and `unlisted`, in one atomic write —
-     * producing one version where it names `contentPatch`, and none where it
-     * doesn't. Keys are read for presence, so `unlisted: false`
-     * and `parentId: null` are changes; a change set naming no key at all is
-     * a StackBadRequestError. Under ScopedStack each key carries its own gate and
-     * one refused key refuses the call.
-     * See docs/spec/data-model.md § Mutations.
-     */
-    mutate<S extends ReadonlyTypeSchema>(handle: TypeHandle<S>, id: RecordId, changes: TypedChangeSet<S>, opts?: IfVersionOptions): Promise<TypedRecord<S>>;
-    mutate(id: RecordId, changes: RecordChangeSet, opts?: IfVersionOptions): Promise<StackRecord>;
-    /** mutate() with `contentPatch` alone — the common case, named for it. */
-    patchContent<S extends ReadonlyTypeSchema>(handle: TypeHandle<S>, id: RecordId, patch: PatchOf<S>, opts?: IfVersionOptions): Promise<TypedRecord<S>>;
-    patchContent(id: RecordId, patch: Record<string, unknown | null>, opts?: IfVersionOptions): Promise<StackRecord>;
-    /**
-     * Add associations in one atomic write and one journal entry. Never bumps
-     * `version`/`updatedAt` and takes no `ifVersion` — a set-add composes
-     * regardless of write order. See docs/spec/data-model.md § Mutations and
-     * docs/spec/versioning.md § Version history.
-     */
-    associate(id: RecordId, associations: DataAssociation[]): Promise<StackRecord>;
-    /** Remove associations, matched by identity — see associate(). */
-    dissociate(id: RecordId, associations: DataAssociation[]): Promise<StackRecord>;
-    /**
-     * Apply a list of adds and removes to a record's data associations as one
-     * atomic write — the cover swap. associate() and dissociate() are this with
-     * one half each; `mutate({ associations })` is the only whole-set write.
-     * `repoint` is not a request: an add naming an attachment the record
-     * already holds re-points it. See docs/spec/data-model.md § Mutations.
-     */
-    amendAssociations(id: RecordId, changes: AssociationEdit[]): Promise<StackRecord>;
-    /**
-     * Extend who reaches a record — the record-level mirror of the type-level
-     * `grantType()`, and the amending spelling of the `permissions` key, which
-     * replaces the whole set. `write` never implies `read`: grant both,
-     * `grantAccess(id, [read, write])`. No-bump, like associate().
-     * See docs/spec/access-control.md § Write implies read.
-     */
-    grantAccess(id: RecordId, permissions: AuthorityAssociation[]): Promise<StackRecord>;
-    /** Withdraw elements of who reaches a record — see grantAccess(). */
-    revokeAccess(id: RecordId, permissions: AuthorityAssociation[]): Promise<StackRecord>;
-    /**
-     * amendAssociations() for permissions: adds and removes in one atomic
-     * write, so a downgrade (remove `write`, keep `read`) is one change.
-     * See docs/spec/access-control.md § Record-level permissions.
-     */
-    amendAccess(id: RecordId, changes: AssociationEdit[]): Promise<StackRecord>;
-    delete(id: RecordId, opts?: DeleteRecordOptions): Promise<DeleteResult>;
-    /**
-     * delete(), plus the record it acted on — read and destroyed as one
-     * atomic operation, so a caller that needs the record for its own
-     * response (e.g. a server building a purge's body) never opens a
-     * gap between reading it and destroying it. See Stack.deleteAndReturn().
-     */
-    deleteAndReturn(id: RecordId, opts?: DeleteRecordOptions): Promise<DeleteAndReturnResult>;
-    undelete(id: RecordId, opts?: IfVersionOptions): Promise<StackRecord>;
-    getVersions(id: RecordId, query?: VersionsQuery): Promise<RecordVersion[]>;
-    getVersion(id: RecordId, version: number): Promise<RecordVersion | null>;
-    restoreVersion(id: RecordId, version: number, opts?: IfVersionOptions): Promise<StackRecord>;
-    /**
-     * A record's change journal, oldest first. On the mutate surface, on the
-     * same footing as getVersions() — a plain reader is refused.
-     *
-     * Required of every adapter rather than optional, which is why it sits
-     * here beside the rest: an empty log has to mean "nothing changed"
-     * unconditionally, so an adapter with nothing to read refuses and names
-     * why instead. See docs/spec/journal.md § Reading it.
-     */
-    getJournal(id: RecordId, query?: JournalQuery): Promise<RecordJournalEntry[]>;
-    /**
-     * 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: RecordId, toTypeId: TypeId, content: Record<string, unknown>, opts?: IfVersionOptions): Promise<StackRecord>;
-    getAttachment(fileId: FileId): Promise<Uint8Array>;
-    putAttachment(data: Uint8Array, opts: PutAttachmentOptions): Promise<StackRecord & {
-        content: AttachmentContent;
-    }>;
-    deleteAttachment(fileId: FileId): Promise<void>;
-    collectAttachmentGarbage(opts?: CollectAttachmentGarbageOptions): Promise<CollectAttachmentGarbageResult>;
-    /**
-     * Typed subscription: delivers only changes to records of exactly the
-     * handle's Type, each `record` typed as its content. See
-     * docs/spec/data-model.md § Type handles.
-     */
-    subscribe<S extends ReadonlyTypeSchema>(handle: TypeHandle<S>, handler: (change: TypedChange<S>) => void, opts?: TypedSubscribeOptions): Promise<Unsubscribe>;
-    subscribe(handler: (change: RecordChange) => void, opts?: SubscribeOptions): Promise<Unsubscribe>;
-}
-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;
-    /**
-     * Every change made through this Stack. `ScopedStack` filters this same
-     * stream rather than opening its own, so no scoped view can observe a
-     * change the stack did not emit. See docs/spec/events.md.
-     */
-    private readonly changes;
-    private constructor();
-    /**
-     * Announce a mutation that has already been persisted. Called after the
-     * adapter write resolves and before the mutating method settles, so
-     * `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.
-     */
-    private announce;
-    /**
-     * The actor for a `create` journal entry, read off the record as just
-     * built. Create is the one journaled write that stamps the requester
-     * onto the row itself, so the record in hand is authoritative — and it
-     * carries `appId`, which ActorOptions has no field for.
-     */
-    private static createActor;
-    private getTypeCached;
-    /**
-     * Open a Stack over an adapter. Reads ownerEntityId and timezone from the adapter.
-     */
-    static open(adapter: StackAdapter, opts?: StackOptions): Promise<Stack>;
-    /**
-     * Idempotent bootstrap for StackOptions.ownerProfile. Filters by family
-     * only (content filtering 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;
-    getEntityByDid(did: EntityId): Promise<StackRecord | null>;
-    getOwnerEntity(): Promise<StackRecord | null>;
-    get timezone(): string | undefined;
-    get capabilities(): StackCapabilities;
-    /**
-     * Get a permission-scoped view of this Stack, as if requests came from
-     * the given entity acting as itself (null = anonymous). Plain Stack
-     * methods are unscoped; use asEntity() when one Stack serves multiple,
-     * possibly untrusted, entities. See
-     * docs/spec/access-control.md § Enforcement: Stack.asEntity().
-     */
-    asEntity(entityId: EntityId | null): ScopedStack;
-    /**
-     * Scope to an Actor — a delegated app acting for its user, or a
-     * TokenSession exactly as StackTokenStore.lookupToken() returns it, which
-     * is what a server should reach for at its request boundary. Authority is
-     * the intersection of both parties' grants, while authorship and `-own`
-     * resolve against the subject. Taking the pair whole leaves no order to
-     * swap. See docs/spec/access-control.md § Delegation: principal and subject.
-     */
-    asActor(actor: Actor): ScopedStack;
-    private scope;
-    /**
-     * 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, name, schema: declared, migratesFrom, }: 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.
-     * Useful for duck-typed consumption across types.
-     */
-    typeIsCompatible(typeId: TypeId, requiredSchema: TypeSchema): Promise<boolean>;
-    /**
-     * 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;
-    /**
-     * Find and compose a migration path from one TypeId to another.
-     * Returns null if no path exists.
-     */
-    private resolveMigrationPath;
-    /**
-     * Find the latest registered version of a type family.
-     * Follows the migration chain from the given typeId to the end.
-     */
-    private latestTypeId;
-    /**
-     * 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(baseId: BaseId): 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(). `opts.createdAt`/`updatedAt` let a caller
-     * backdate an imported record's clock fields — unconditionally here;
-     * ScopedStack.create() forwards to this same method, but only reaches
-     * this far with them when the requester is the stack owner acting alone
-     * — see BackdatableCreateRecordOptions and docs/spec/data-model.md §
-     * Record IDs.
-     */
-    create<S extends ReadonlyTypeSchema>(handle: TypeHandle<S>, content: ContentOf<S>, opts?: BackdatableCreateRecordOptions): Promise<TypedRecord<S>>;
-    create<T extends Record<string, unknown> = Record<string, unknown>>(typeId: TypeId, content: T, opts?: BackdatableCreateRecordOptions): Promise<StackRecord & {
-        content: T;
-    }>;
-    /**
-     * 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. A soft-deleted record answers `null` unless
-     * { includeDeleted: true } is passed.
-     */
-    get<S extends ReadonlyTypeSchema>(handle: TypeHandle<S>, id: RecordId): Promise<TypedRecord<S> | null>;
-    get(id: RecordId, opts?: GetRecordOptions): Promise<StackRecord | null>;
-    /**
-     * Apply a change set as one atomic write — see the StackClient
-     * declaration above for what it accepts. Atomicity is what it is for: a
-     * publish is one act, so nothing it names may half-land.
-     *
-     * Every key present is checked against the record as it stands, and a set
-     * already satisfied in all of them writes nothing. Content is validated
-     * against the record's *current* stored type; `typeId` never changes here.
-     * See docs/spec/data-model.md § Mutations.
-     */
-    mutate<S extends ReadonlyTypeSchema>(handle: TypeHandle<S>, id: RecordId, changes: TypedChangeSet<S>, opts?: IfVersionOptions & ActorOptions): Promise<TypedRecord<S>>;
-    mutate(id: RecordId, changes: RecordChangeSet, 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<S extends ReadonlyTypeSchema>(handle: TypeHandle<S>, id: RecordId, patch: PatchOf<S>, opts?: IfVersionOptions & ActorOptions): Promise<TypedRecord<S>>;
-    patchContent(id: RecordId, 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.
-     */
-    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*, which is the
-     * whole of the self-removal question: an admin removing themselves passes
-     * while another remains and is refused when they are the last, without
-     * either case naming who is going.
-     *
-     * An integrity constraint on the Record, not a permission question, so it
-     * lives here rather than in `ScopedStack` and binds every requester — the
-     * stack owner included. See docs/spec/identity.md § Group.
-     */
-    private assertGroupAdminRemains;
-    /**
-     * Add associations to a record — no-bump and no snapshot, per the
-     * StackClient declaration above.
-     *
-     * An association the record already holds, saying the same thing, is a
-     * no-op; one matching an existing association's identity but naming a
-     * different `attachmentRecordId` — or none, which clears the one stored —
-     * re-points it in place rather than adding a second reference to the same
-     * file. What a re-point overwrote is kept only by the journal, on that
-     * entry's `repoint`. See docs/spec/journal.md § The entry.
-     */
-    associate(id: RecordId, associations: DataAssociation[], opts?: ActorOptions): Promise<StackRecord>;
-    /**
-     * Remove associations from a record — see associate(). Matched by kind,
-     * label and payload; an element not found is a no-op. The emitted event
-     * names each association by identity only, since an attachment's
-     * `attachmentRecordId` describes nothing current once it is gone; the
-     * journal is where it survives.
-     */
-    dissociate(id: RecordId, associations: DataAssociation[], opts?: ActorOptions): Promise<StackRecord>;
-    /**
-     * The atomic form of associate() and dissociate(): one list of adds and
-     * removes, one adapter write, one journal entry. The journal records each
-     * element in full — a remove with its annotation, a re-point with what it
-     * overwrote — so the entry is as undoable as a single-element one.
-     * See docs/spec/data-model.md § Mutations.
-     */
-    amendAssociations(id: RecordId, changes: AssociationEdit[], opts?: ActorOptions, surface?: string): Promise<StackRecord>;
-    /**
-     * Extend who reaches a record. The spelling that survives two admins
-     * sharing a record at once: a `permissions` key write replaces the whole
-     * set, so the later of two concurrent ones drops what the earlier
-     * granted. No-bump, like associate(); an element the record already
-     * carries is a no-op. `write` never implies `read` — name both.
-     */
-    grantAccess(id: RecordId, permissions: AuthorityAssociation[], opts?: ActorOptions): Promise<StackRecord>;
-    /**
-     * Withdraw elements of who reaches a record — see grantAccess() for why
-     * this is a verb rather than a key write. An element the record does not
-     * carry is a no-op. Returns the record as it now stands.
-     */
-    revokeAccess(id: RecordId, permissions: AuthorityAssociation[], opts?: ActorOptions): Promise<StackRecord>;
-    /**
-     * The atomic form of grantAccess() and revokeAccess(). The
-     * write-implies-read invariant is asked once, of the set the whole list
-     * produces. See docs/spec/access-control.md § Write implies read.
-     */
-    amendAccess(id: RecordId, changes: AssociationEdit[], opts?: ActorOptions, surface?: string): Promise<StackRecord>;
-    /**
-     * Hold a permission set to the cross-element invariant — see
-     * validatePermissions() in access.ts for why it reads the post-state.
-     */
-    private assertPermissionSet;
-    /**
-     * A soft-deleted record has no current state to edit, so the verbs that
-     * edit one refuse it; undelete() and commitMigration() do not call this.
-     * Asked after the record is found and, under ScopedStack, after the
-     * authority decision. See docs/spec/versioning.md § Mutations are refused,
-     * not applied to a tombstone.
-     */
-    private refuseIfDeleted;
-    /** The record, or the not-found refusal every mutating verb owes. */
-    private requireRecord;
-    /**
-     * 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;
-    /**
-     * Refuse an edge that would make a record its own ancestor — asked at
-     * every site that adds one. Nothing downstream (a generator deriving a
-     * page path, a folder view) is written to survive a cycle.
-     *
-     * Walks with the unscoped adapter: a walk that skipped the links a
-     * requester cannot read would let a cycle be assembled through them and
-     * break the invariant for every reader.
-     *
-     * Read-then-write, so two moves racing on opposite ends of one chain can
-     * both pass — the same deferral as checkBindingUnique() above, since
-     * closing it would put a graph constraint in the storage contract.
-     * Consumers walking `parentId` should carry a visited set rather than
-     * trust this alone. See docs/spec/data-model.md § Reparenting.
-     */
-    private assertNoParentCycle;
-    /**
-     * Soft-delete a record (default) or purge 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.
-     *
-     * A purge reports the files the record referenced. It deletes none of
-     * them — byte lifetime is not the purged record's to decide — but it
-     * destroys the only rows naming them, so a caller who means to erase the
-     * bytes too has nowhere else to read the argument from afterwards. See
-     * docs/spec/attachments.md § A purge strands the bytes it referenced.
-     *
-     * deleteAndReturn() is this plus the record itself; reach for that
-     * instead when the caller needs the record too — building a response
-     * body from a separate read beforehand is exactly the race and the extra
-     * round trip it exists to remove.
-     */
-    delete(id: RecordId, opts?: DeleteRecordOptions & ActorOptions): Promise<DeleteResult>;
-    /**
-     * delete(), reporting the record it acted on alongside the files it
-     * stranded: as it stood immediately before destruction for a
-     * purge, or as the resulting tombstone for a soft delete. Both are
-     * captured inside the same write that destroys or tombstones the record,
-     * never a read beforehand — a read-then-delete would leave a window
-     * where a concurrent write can land, get destroyed or overwritten by
-     * this call, and never appear in the record this returns.
-     */
-    deleteAndReturn(id: RecordId, opts?: DeleteRecordOptions & ActorOptions): Promise<DeleteAndReturnResult>;
-    /**
-     * The files a record references, by the same definition
-     * deleteAttachment() and the garbage sweep use: attachment associations
-     * and top-level `file-ref` content fields. An `_attachment` record's own
-     * `fileId` is a plain string by design and is not one, which is why
-     * purging a metadata record reports nothing — see initSystemTypes().
-     */
-    private referencedFileIds;
-    /**
-     * Reverse a soft delete. Idempotent — undeleting a record that isn't
-     * deleted returns it unchanged. Purged records are gone, so this
-     * throws StackNotFoundError for them just like any other missing record.
-     * Snapshots and bumps version, same as delete().
-     */
-    undelete(id: RecordId, opts?: IfVersionOptions & ActorOptions): 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<S extends ReadonlyTypeSchema>(handle: TypeHandle<S>, query?: TypedQuery): Promise<{
-        records: TypedRecord<S>[];
-        cursor: string | null;
-    }>;
-    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: RecordId, query?: VersionsQuery): Promise<RecordVersion[]>;
-    /**
-     * A record's change journal, oldest first — what moved, who moved it, and
-     * the association deltas nothing else retains. `ScopedStack` applies the
-     * mutate-surface gate; this layer is unscoped and trusted by definition.
-     *
-     * A record that isn't there is StackNotFoundError, a purged one included:
-     * a destroyed log and an empty one are not the same answer.
-     * See docs/spec/journal.md § Reading it.
-     */
-    getJournal(id: RecordId, query?: JournalQuery): Promise<RecordJournalEntry[]>;
-    getVersion(id: RecordId, version: number): Promise<RecordVersion | null>;
-    /**
-     * Restore a record to a previous version by creating a new version —
-     * never rewrites history. The snapshot is validated against its own
-     * stored typeId, and puts back `content` and `typeId` alone: a snapshot
-     * carries nothing else. See docs/spec/versioning.md § Restore semantics.
-     */
-    restoreVersion(id: RecordId, version: number, opts?: IfVersionOptions & ActorOptions): Promise<StackRecord>;
-    /**
-     * Commit a per-record migration — the single-record counterpart to
-     * migrateAll(), with `content` supplied by the caller rather than by a
-     * registered Migration function. See docs/spec/wire-format.md § Migration
-     * commit.
-     *
-     * 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. Missing
-     * either half would make migrate a second, unguarded write path to a
-     * state create()/mutate() refuse to reach.
-     */
-    commitMigration(id: RecordId, toTypeId: TypeId, content: Record<string, unknown>, opts?: IfVersionOptions & ActorOptions): Promise<StackRecord>;
-    /**
-     * 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 — a content patch 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, so every
-     * binding field either keeps its value, moves to a new one, or is shed by
-     * omission — and immutability refuses the last two. Asked across the
-     * union of both 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, excluding the
-     * record itself. See docs/spec/identity.md § DID bindings.
-     */
-    private checkBindingsOnMigrate;
-    /**
-     * A unique binding field is what a lookup resolves *by* — an Actor's
-     * `principalId` by `_app.did`, its `subjectId` 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.
-     *
-     * Read-then-write, so two creates racing on one value can both pass:
-     * closing that means a unique index over a JSON field, which is a
-     * decision about where uniqueness lives rather than 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. 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*:
-     * getAttachmentRecords() returns the candidates in the same total order
-     * a server serving Content-Type applies, so both sides name the same
-     * winner however many records exist.
-     */
-    private checkAttachmentMimeTypeOnCreate;
-    /**
-     * An attachment association's `attachmentRecordId` names an `_attachment`
-     * record for the same `fileId` — checked here so a reference can't be
-     * annotated with an unrelated record's filename.
-     *
-     * Best-effort, like the mimeType check above: the named record can be
-     * deleted afterwards, so every reader of the field falls back rather than
-     * trusting it. `stored` is what the record already holds, asked so a
-     * change set restating an association is never refused for a pointer the
-     * record has carried since before the named record was deleted.
-     * See docs/spec/attachments.md § Naming the upload a reference came from.
-     */
-    private checkAttachmentAssociationPointers;
-    /**
-     * 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 assertAttachmentImmutable;
-    /**
-     * `_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.
-     */
-    private checkConfigEntityIdUnchanged;
-    /**
-     * Store bytes and create an _attachment@1 metadata record (owner-
-     * attributed, no createdBy), 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, opts: PutAttachmentOptions): Promise<StackRecord & {
-        content: AttachmentContent;
-    }>;
-    getAttachment(fileId: FileId): Promise<Uint8Array>;
-    /**
-     * Every `_attachment` record describing `fileId`, earliest-recorded
-     * first — so `records[0]` is the one that establishes the file's
-     * mimeType, and firstRecordedAttachment() is only needed by a caller
-     * narrowing the set further. See docs/spec/attachments.md § Finding a
-     * `fileId`'s metadata records.
-     *
-     * On `Stack` and not `StackClient`: the lookup answers a presentation
-     * question about an access decision already made, so a scoped version
-     * would impose a second, different permission check rather than a
-     * narrower correct answer.
-     */
-    getAttachmentRecords(fileId: FileId): Promise<(StackRecord & {
-        content: AttachmentContent;
-    })[]>;
-    /**
-     * The `_attachment` family as concrete typeIds. Resolved here rather
-     * than in the adapter, which has no baseId concept of its own — see
-     * resolveBaseIdFilter().
-     */
-    private attachmentTypeIds;
-    /**
-     * Delete an attachment's bytes and every _attachment metadata record for
-     * it, family-wide. Throws StackConflictError if any record in the stack
-     * still references the file, StackNotFoundError if neither metadata
-     * records nor bytes exist.
-     */
-    deleteAttachment(fileId: FileId, opts?: ActorOptions): Promise<void>;
-    /**
-     * 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 & ActorOptions): Promise<CollectAttachmentGarbageResult>;
-    /**
-     * Observe every change made through this Stack. Unscoped, so no
-     * permission filter applies — a caller holding a `Stack` already reaches
-     * every record by other means; `ScopedStack.subscribe()` is the filtered
-     * view. See docs/spec/events.md.
-     *
-     * Async so that a remote stack can resolve once its feed is live, which
-     * makes subscribe-then-query the gap-free startup order everywhere. A
-     * local stack is live immediately.
-     */
-    subscribe<S extends ReadonlyTypeSchema>(handle: TypeHandle<S>, handler: (change: TypedChange<S>) => void, opts?: TypedSubscribeOptions): Promise<Unsubscribe>;
-    subscribe(handler: (change: RecordChange) => void, opts?: SubscribeOptions): Promise<Unsubscribe>;
-    /**
-     * Ask the adapter to relay changes that originated elsewhere. Absent on
-     * every local adapter, where one process owns the storage and there is
-     * no third party whose writes could have been missed.
-     *
-     * The subscription's own filter goes to the relay rather than being
-     * applied on the way back: the emitter at the far end holds the record,
-     * so it can answer `createdBy` and `parentId`, which the envelope
-     * deliberately does not carry. That is also why a relay is opened per
-     * subscription rather than shared.
-     */
-    private openRelay;
-    /** Whether changes reach this stack from elsewhere. */
-    private get relaysChanges();
-    /**
-     * 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
-     * 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>;
-    /** Throws once close() has run. */
-    private assertOpen;
-    /**
-     * Create a _grant record authorizing `grantee` to take `actions` on
-     * records of `typeId`: `{ kind: 'entity' }` for one DID, `{ kind: 'group' }`
-     * for a `_group` Record's roster at a role, `{ kind: 'authenticated' }` for
-     * any authenticated entity. The type-level mirror of grantAccess() —
-     * subject first, grantee inside the element.
-     *
-     * 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.
-     *
-     * `baseId` names the whole family and is refused when it carries an
-     * `@version` suffix. See docs/spec/access-control.md § Type-level grants.
-     */
-    grantType(baseId: BaseId, grant: TypeGrant): Promise<StackRecord & {
-        content: GrantContent;
-    }>;
-    /**
-     * List _grant records. Omit `query` for all grants;
-     * `{ kind: 'authenticated' }` for only default grants;
-     * `{ kind: 'group' }` for grants naming that exact group and role, or
-     * `role: 'any'` for every grant naming the group;
-     * `{ kind: 'entity' }` for the grants that currently apply to that entity
-     * (ones naming them, ones naming a group they belong to at a role they
-     * hold, plus every default grant) — the same resolution hasGrant() uses.
-     *
-     * Every arm but `entity` answers identity — what `grantType()` would have
-     * written with the same argument. The `entity` arm answers coverage, so
-     * its result is not a preview of what `revokeType()` would withdraw.
-     * See docs/spec/access-control.md § Type-level grants.
-     */
-    listTypeGrants(query?: GrantQuery): Promise<(StackRecord & {
-        content: GrantContent;
-    })[]>;
-    /**
-     * The inverse of grantType(): soft-deletes the _grant records on
-     * `baseId`'s family matching `grant`, at the same granularity
-     * grantType() writes — the grantee is matched whole, role included, and
-     * the actions exactly. A soft delete like any other — the owner can
-     * undelete a revocation.
-     *
-     * Returns the grants it withdrew, as they stood: an array, where
-     * revokeAccess() returns one Record, because one target can match several
-     * _grant records. An empty result is not an error — re-running a
-     * revocation has to stay safe. See
-     * docs/spec/access-control.md § Listing and revoking.
-     */
-    revokeType(baseId: BaseId, grant: TypeGrant): Promise<(StackRecord & {
-        content: GrantContent;
-    })[]>;
-    /**
-     * Actions must be known GrantAction values; the target is held to the
-     * same rule every `_grant` write meets — see validateGrantBaseId().
-     */
-    private checkGrantValid;
-    private seedSystemTypes;
-    /**
-     * 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;
-    /**
-     * 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 — the actor's `principalId`
-     * 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. Carries what
-     * only a snapshot preserves: `content` and the `typeId` it is read
-     * under. Containment, listing and associations — the authority ones
-     * among them — are all kept by the journal instead, so no version ever
-     * snapshots them and there is nothing for a restore to roll them back
-     * to. See docs/spec/versioning.md § Version history.
-     */
-    private buildVersionSnapshot;
-}
-//# sourceMappingURL=stack.d.ts.map