@haverstack/core 0.36.0 → 0.38.0

package/dist/stack.d.ts

@@ -9,13 +9,20 @@
  *  - Content validation on write
  *  - Migration registry and explicit, owner-driven migrateAll()
  *  - Version snapshotting on update
- *  - Soft and hard delete
+ *  - Soft delete and purge
  *
  * Apps should never talk to a StackAdapter directly.
  */
-import type { StackRecord, StackType, TypeSchema, TypeId, StackAdapter, StackQuery, QueryResult, AuthorityAssociation, DataAssociation, Migration, RecordVersion, StackFeatures, GrantAction, AttachmentContent, FileId, EntityId, AppId, TokenSession, ActorOptions, RecordChange, RecordChanges, SubscribeOptions, Unsubscribe, JournalQuery, RecordJournalEntry } from './types.js';
-import type { GrantQuery, GrantTarget } from './grants.js';
+import type { StackRecord, StackType, TypeSchema, TypeId, BaseId, StackAdapter, StackQuery, QueryResult, AuthorityAssociation, DataAssociation, Migration, RecordVersion, StackCapabilities, IfVersionOptions, GrantContent, TypeGrant, PutAttachmentOptions, AttachmentContent, FileId, EntityId, AppId, RecordId, Actor, ActorOptions, RecordChange, RecordChangeSet, SubscribeOptions, Unsubscribe, JournalQuery, RecordJournalEntry } from './types.js';
+import type { GrantQuery } from './grants.js';
 import { ScopedStack } from './scoped-stack.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
@@ -23,17 +30,16 @@ export type CreateRecordOptions = {
      * library generate one. See Stack.create() and ScopedStack.create()
      * for the validation each applies.
      */
-    id?: string;
-    parentId?: string;
-    entityId?: EntityId;
-    /** Reverse-DNS identifier of the writing software — see AppId. */
-    appId?: AppId;
+    id?: RecordId;
+    parentId?: RecordId;
     /**
-     * The authenticated principal, when it isn't the author. ScopedStack sets
-     * this from its own principal; callers of plain Stack supply it only when
-     * reconstructing a delegated write. See StackRecord.principalId.
+     * The author. ScopedStack sets this from its own identities; callers of
+     * plain Stack supply it only when reconstructing an attributed write.
+     * See StackRecord.createdBy.
      */
-    principalId?: EntityId;
+    createdBy?: Actor;
+    /** Reverse-DNS identifier of the writing software — see AppId. */
+    appId?: AppId;
     permissions?: AuthorityAssociation[];
     associations?: DataAssociation[];
     /**
@@ -69,14 +75,6 @@ export type BackdatableCreateRecordOptions = CreateRecordOptions & {
      */
     updatedAt?: Date;
 };
-export type ScopedStackOptions = {
-    /**
-     * The entity a delegated app acts for. Omit when the principal acts as
-     * itself — the case for an app riding its user's identity, which needs
-     * no delegation. See docs/spec/identity.md § App.
-     */
-    onBehalfOf?: EntityId;
-};
 export type StackOptions = {
     /**
      * Ensures the owner's own `_entity` profile record exists, creating it on
@@ -109,7 +107,8 @@ export type CollectAttachmentGarbageOptions = {
     dryRun?: boolean;
 };
 export type CollectAttachmentGarbageResult = {
-    deleted: string[];
+    /** The files collected — or, on a dry run, the ones that would be. */
+    deletedFileIds: FileId[];
     reclaimedBytes: number;
 };
 export type GetRecordOptions = {
@@ -120,18 +119,9 @@ export type GetRecordOptions = {
      */
     presentAt?: 'stored' | 'latest';
 };
-/**
- * Opt-in optimistic-concurrency precondition, accepted by every mutation
- * that bumps a record's version. On mismatch the mutation throws
- * StackVersionConflictError and changes nothing; omit to keep
- * last-writer-wins. See docs/spec/versioning.md § Optimistic concurrency (`ifVersion`).
- */
-export type IfVersionOptions = {
-    ifVersion?: number;
-};
 export type DeleteRecordOptions = IfVersionOptions & {
     /** If true, permanently remove the record and all its history. Default: false */
-    hard?: boolean;
+    purge?: boolean;
 };
 /**
  * What a delete reports back. Information, not action: a purge never
@@ -149,7 +139,26 @@ export type DeleteResult = {
      */
     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;
+    schema: TypeSchema;
     migratesFrom?: TypeId;
 };
 /**
@@ -158,11 +167,11 @@ export type DefineTypeOptions = {
  * and work equally well with a full Stack or a permission-scoped view.
  */
 export interface StackClient {
-    readonly features: StackFeatures;
+    readonly capabilities: StackCapabilities;
     create<T extends Record<string, unknown> = Record<string, unknown>>(typeId: TypeId, content: T, opts?: CreateRecordOptions): Promise<StackRecord & {
         content: T;
     }>;
-    get(id: string, opts?: GetRecordOptions): Promise<StackRecord | null>;
+    get(id: RecordId, opts?: GetRecordOptions): Promise<StackRecord | null>;
     query(query?: StackQuery): Promise<QueryResult>;
     /**
      * Resolve a DID to its `_entity` card — family-wide and soft-deleted
@@ -180,35 +189,42 @@ export interface StackClient {
      * 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 StackQueryError. Under ScopedStack each key carries its own gate and
+     * 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(id: string, changes: RecordChanges, opts?: IfVersionOptions): Promise<StackRecord>;
+    mutate(id: RecordId, changes: RecordChangeSet, 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>;
+    patchContent(id: RecordId, patch: Record<string, unknown | null>, opts?: IfVersionOptions): Promise<StackRecord>;
     /**
      * Add an association. Never bumps `version`/`updatedAt` and takes no
      * `ifVersion` — a set-add composes regardless of write order.
      * See docs/spec/versioning.md § Version history.
      */
-    associate(id: string, association: DataAssociation): Promise<StackRecord>;
+    associate(id: RecordId, association: DataAssociation): Promise<StackRecord>;
     /** Remove an association. Never bumps `version`/`updatedAt` — see associate(). */
-    dissociate(id: string, association: DataAssociation): Promise<StackRecord>;
+    dissociate(id: RecordId, association: DataAssociation): Promise<StackRecord>;
     /**
      * Extend who reaches a record by one element — the record-level mirror of
-     * the type-level `grant()`, and the amending spelling of the
+     * the type-level `grantType()`, and the amending spelling of the
      * `permissions` key, which replaces the whole set. No-bump, like
      * associate(). See docs/spec/access-control.md § Record-level permissions.
      */
-    grantAccess(id: string, permission: AuthorityAssociation): Promise<StackRecord>;
+    grantAccess(id: RecordId, permission: AuthorityAssociation): Promise<StackRecord>;
     /** Withdraw one element of who reaches a record — see grantAccess(). */
-    revokeAccess(id: string, permission: AuthorityAssociation): Promise<StackRecord>;
-    delete(id: string, opts?: DeleteRecordOptions): Promise<DeleteResult>;
-    undelete(id: string, opts?: IfVersionOptions): Promise<StackRecord>;
-    getVersions(id: string): Promise<RecordVersion[]>;
-    getVersion(id: string, version: number): Promise<RecordVersion | null>;
-    restoreVersion(id: string, version: number, opts?: IfVersionOptions): Promise<StackRecord>;
+    revokeAccess(id: RecordId, permission: AuthorityAssociation): 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): 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.
@@ -218,7 +234,7 @@ export interface StackClient {
      * unconditionally, so an adapter with nothing to read refuses and names
      * why instead. See docs/spec/journal.md § Reading it.
      */
-    getJournal(id: string, query?: JournalQuery): Promise<RecordJournalEntry[]>;
+    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
@@ -227,12 +243,12 @@ export interface StackClient {
      * record's version (see docs/spec/versioning.md § Optimistic
      * concurrency); over the wire that is `If-Match`.
      */
-    commitMigration(id: string, toTypeId: TypeId, content: Record<string, unknown>, opts?: IfVersionOptions): Promise<StackRecord>;
-    getAttachment(fileId: string): Promise<Uint8Array>;
-    putAttachment(data: Uint8Array, mimeType: string, filename?: string, appId?: AppId): Promise<StackRecord & {
+    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: string): Promise<void>;
+    deleteAttachment(fileId: FileId): Promise<void>;
     collectAttachmentGarbage(opts?: CollectAttachmentGarbageOptions): Promise<CollectAttachmentGarbageResult>;
     subscribe(handler: (change: RecordChange) => void, opts?: SubscribeOptions): Promise<Unsubscribe>;
 }
@@ -277,20 +293,11 @@ export declare class Stack implements StackClient {
      * carries `appId`, which ActorOptions has no field for.
      */
     private static createActor;
-    /**
-     * The requester behind a write that stamps nothing on the record itself —
-     * a hard delete, which leaves no record to stamp, and associate()/
-     * dissociate(), which don't bump and so don't touch updatedBy/updatedVia.
-     * Hard delete is owner-acting-alone only, so it never has a principal to
-     * name beside the subject; associate()/dissociate() can run delegated,
-     * so `updatedVia` rides along here when present.
-     */
-    private static actorFrom;
     private getTypeCached;
     /**
-     * Create a Stack instance. Reads ownerEntityId and timezone from the adapter.
+     * Open a Stack over an adapter. Reads ownerEntityId and timezone from the adapter.
      */
-    static create(adapter: StackAdapter, opts?: StackOptions): Promise<Stack>;
+    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`
@@ -306,33 +313,25 @@ export declare class Stack implements StackClient {
     getEntityByDid(did: EntityId): Promise<StackRecord | null>;
     getOwnerEntity(): Promise<StackRecord | null>;
     get timezone(): string | undefined;
-    get features(): StackFeatures;
+    get capabilities(): StackCapabilities;
     /**
      * Get a permission-scoped view of this Stack, as if requests came from
-     * the given principal (null = anonymous). Plain Stack methods are
-     * unscoped; use asEntity() when one Stack serves multiple, possibly
-     * untrusted, entities.
-     *
-     * `onBehalfOf` names the subject a delegated app acts for: authority is
-     * then the intersection of both parties' grants, while authorship and
-     * `-own` resolve against the subject. See
+     * 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, opts?: ScopedStackOptions): ScopedStack;
+    asEntity(entityId: EntityId | null): ScopedStack;
     /**
-     * Scope to an authenticated session — what StackTokenStore.lookupToken()
-     * returns. Equivalent to asEntity(principalId, { onBehalfOf: subjectId }),
-     * and what a server should reach for at its request boundary.
-     *
-     * Both identities are DIDs, so passing them positionally leaves nothing
-     * to catch a swap, and a swapped pair is undetectable in the undelegated
-     * case where they are equal — it would surface only once delegation is in
-     * use, as authority no longer fenced by the app's grants and every write
-     * attributed to the app rather than the person. Taking the pair whole
-     * removes the order to get wrong. See
-     * docs/spec/access-control.md § Delegation: principal and subject.
+     * 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.
      */
-    forSession(session: TokenSession): ScopedStack;
+    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
@@ -340,7 +339,7 @@ export declare class Stack implements StackClient {
      * anything beyond additive evolution throws StackSchemaDriftError. See
      * docs/spec/data-model.md § Schema drift detection.
      */
-    defineType(id: TypeId, name: string, schema: TypeSchema, opts?: DefineTypeOptions): Promise<StackType>;
+    defineType({ id, name, schema, 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[]>;
@@ -372,7 +371,7 @@ export declare class Stack implements StackClient {
      * too, validates each result before writing, and aborts on the first
      * validation failure. See docs/spec/data-model.md § Type migrations.
      */
-    migrateAll(baseTypeId: string): Promise<{
+    migrateAll(baseId: BaseId): Promise<{
         migrated: number;
     }>;
     /**
@@ -402,7 +401,7 @@ export declare class Stack implements StackClient {
      * { presentAt: 'latest' } to migrate in memory; only migrateAll()
      * commits migrations to disk.
      */
-    get(id: string, opts?: GetRecordOptions): Promise<StackRecord | 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
@@ -413,13 +412,13 @@ export declare class Stack implements StackClient {
      * against the record's *current* stored type; `typeId` never changes here.
      * See docs/spec/data-model.md § Mutations.
      */
-    mutate(id: string, changes: RecordChanges, opts?: IfVersionOptions & ActorOptions): Promise<StackRecord>;
+    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(id: string, patch: Record<string, unknown | null>, opts?: IfVersionOptions & ActorOptions): Promise<StackRecord>;
+    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
@@ -455,7 +454,7 @@ export declare class Stack implements StackClient {
      * 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: string, association: DataAssociation, opts?: ActorOptions): Promise<StackRecord>;
+    associate(id: RecordId, association: DataAssociation, opts?: ActorOptions): Promise<StackRecord>;
     /**
      * Remove an association from a record — see associate(). Matched by kind,
      * label and payload; a no-op if not found. The emitted event names the
@@ -463,7 +462,7 @@ export declare class Stack implements StackClient {
      * `attachmentRecordId` describes nothing current once it is gone; the
      * journal is where it survives.
      */
-    dissociate(id: string, association: DataAssociation, opts?: ActorOptions): Promise<StackRecord>;
+    dissociate(id: RecordId, association: DataAssociation, opts?: ActorOptions): Promise<StackRecord>;
     /**
      * Extend who reaches a record by one element. The spelling that survives
      * two admins sharing a record at once: a `permissions` key write replaces
@@ -471,13 +470,13 @@ export declare class Stack implements StackClient {
      * earlier granted. No-bump, like associate(); an element the record
      * already carries is a no-op.
      */
-    grantAccess(id: string, permission: AuthorityAssociation, opts?: ActorOptions): Promise<StackRecord>;
+    grantAccess(id: RecordId, permission: AuthorityAssociation, opts?: ActorOptions): Promise<StackRecord>;
     /**
      * Withdraw one element 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: string, permission: AuthorityAssociation, opts?: ActorOptions): Promise<StackRecord>;
+    revokeAccess(id: RecordId, permission: AuthorityAssociation, opts?: ActorOptions): Promise<StackRecord>;
     /**
      * Hold a permission set to the cross-element invariant — see
      * validatePermissions() in access.ts for why it reads the post-state.
@@ -514,7 +513,7 @@ export declare class Stack implements StackClient {
      */
     private assertNoParentCycle;
     /**
-     * Soft-delete a record (default) or hard-delete it permanently, removing
+     * 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
@@ -525,8 +524,23 @@ export declare class Stack implements StackClient {
      * 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.
      */
-    delete(id: string, opts?: DeleteRecordOptions & ActorOptions): Promise<DeleteResult>;
+    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
@@ -537,11 +551,11 @@ export declare class Stack implements StackClient {
     private referencedFileIds;
     /**
      * Reverse a soft delete. Idempotent — undeleting a record that isn't
-     * deleted returns it unchanged. Hard-deleted records are gone, so this
+     * 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: string, opts?: IfVersionOptions & ActorOptions): Promise<StackRecord>;
+    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
@@ -556,7 +570,7 @@ export declare class Stack implements StackClient {
      * the caller can short-circuit without an adapter round trip.
      */
     private resolveBaseIdFilter;
-    getVersions(id: string): Promise<RecordVersion[]>;
+    getVersions(id: RecordId): Promise<RecordVersion[]>;
     /**
      * A record's change journal, oldest first — what moved, who moved it, and
      * the association deltas nothing else retains. `ScopedStack` applies the
@@ -566,15 +580,15 @@ export declare class Stack implements StackClient {
      * a destroyed log and an empty one are not the same answer.
      * See docs/spec/journal.md § Reading it.
      */
-    getJournal(id: string, query?: JournalQuery): Promise<RecordJournalEntry[]>;
-    getVersion(id: string, version: number): Promise<RecordVersion | null>;
+    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: string, version: number, opts?: IfVersionOptions & ActorOptions): Promise<StackRecord>;
+    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
@@ -587,7 +601,7 @@ export declare class Stack implements StackClient {
      * either half would make migrate a second, unguarded write path to a
      * state create()/mutate() refuse to reach.
      */
-    commitMigration(id: string, toTypeId: TypeId, content: Record<string, unknown>, opts?: IfVersionOptions & ActorOptions): Promise<StackRecord>;
+    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
@@ -625,8 +639,8 @@ export declare class Stack implements StackClient {
      */
     private checkBindingsOnMigrate;
     /**
-     * A unique binding field is what a lookup resolves *by* — a record's
-     * `principalId` by `_app.did`, its `entityId` by `_entity.did`. Two cards
+     * 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.
@@ -697,16 +711,16 @@ export declare class Stack implements StackClient {
     private checkConfigEntityIdUnchanged;
     /**
      * Store bytes and create an _attachment@1 metadata record (owner-
-     * attributed, no entityId), returning that record — `content.fileId`
+     * 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, mimeType: string, filename?: string, appId?: AppId): Promise<StackRecord & {
+    putAttachment(data: Uint8Array, opts: PutAttachmentOptions): Promise<StackRecord & {
         content: AttachmentContent;
     }>;
-    getAttachment(fileId: string): Promise<Uint8Array>;
+    getAttachment(fileId: FileId): Promise<Uint8Array>;
     /**
      * Every `_attachment` record describing `fileId`, earliest-recorded
      * first — so `records[0]` is the one that establishes the file's
@@ -734,7 +748,7 @@ export declare class Stack implements StackClient {
      * still references the file, StackNotFoundError if neither metadata
      * records nor bytes exist.
      */
-    deleteAttachment(fileId: string, opts?: ActorOptions): Promise<void>;
+    deleteAttachment(fileId: FileId, opts?: ActorOptions): Promise<void>;
     /**
      * Non-atomic fallback for adapters that don't implement
      * deleteUnreferencedAttachmentRecords(): a concurrent associate() can
@@ -766,16 +780,13 @@ export declare class Stack implements StackClient {
      *
      * 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 `entityId` and `parentId`, which the envelope
+     * 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. Public only so
-     * ScopedStack can refuse a scope it cannot honor; not an app-facing API.
-     */
-    get relaysChanges(): boolean;
+    /** 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
@@ -790,17 +801,14 @@ export declare class Stack implements StackClient {
      * See docs/spec/adapters.md § Lifecycle.
      */
     close(): Promise<void>;
-    /**
-     * Throws once close() has run. Public only so ScopedStack can gate the
-     * one path it takes to the adapter directly; not an app-facing API.
-     */
-    assertOpen(): void;
-    /**
-     * Create _grant records authorizing entities to act on records of
-     * specific types. The target is the grantee the record carries:
-     * `{ kind: 'entity' }` for one DID, `{ kind: 'group' }` for a `_group`
-     * Record's roster at a role, `{ kind: 'authenticated' }` for any
-     * authenticated entity.
+    /** 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
@@ -810,13 +818,13 @@ export declare class Stack implements StackClient {
      * needs, not the suffix that looks narrowest. See
      * docs/spec/access-control.md § Delegation: principal and subject.
      *
-     * The grantee lives in content.grantee, not record.entityId. See
+     * `typeOrBaseId` is a versioned TypeId (`"baseId@version"`) or a bare
+     * baseId; either names the whole family. See
      * docs/spec/access-control.md § Type-level grants.
      */
-    grant(target: GrantTarget, grants: Array<{
-        actions: GrantAction[];
-        typeId: TypeId;
-    }>): Promise<StackRecord[]>;
+    grantType(typeOrBaseId: TypeId | BaseId, grant: TypeGrant): Promise<StackRecord & {
+        content: GrantContent;
+    }>;
     /**
      * List _grant records. Omit `query` for all grants;
      * `{ kind: 'authenticated' }` for only default grants;
@@ -826,36 +834,36 @@ export declare class Stack implements StackClient {
      * (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 `grant()` would have
+     * 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 `revoke()` would withdraw.
+     * its result is not a preview of what `revokeType()` would withdraw.
      * See docs/spec/access-control.md § Type-level grants.
      */
-    listGrants(query?: GrantQuery): Promise<StackRecord[]>;
+    listTypeGrants(query?: GrantQuery): Promise<(StackRecord & {
+        content: GrantContent;
+    })[]>;
     /**
-     * The inverse of grant(): soft-deletes _grant records matching `target`
-     * and each `{ typeId, actions }` pair, at the same granularity grant()
-     * writes — the grantee is matched whole, role included. A soft delete
-     * like any other — the owner can undelete a revocation.
+     * The inverse of grantType(): soft-deletes the _grant records on
+     * `typeOrBaseId`'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, so a revocation that
-     * matched nothing says so rather than passing in silence. An empty result
-     * is not an error — a grant already withdrawn or never written is the
-     * ordinary case, and re-running a revocation has to stay safe.
-     * See docs/spec/access-control.md § Type-level grants.
-     */
-    revoke(target: GrantTarget, grants: Array<{
-        actions: GrantAction[];
-        typeId: TypeId;
-    }>): Promise<StackRecord[]>;
+     * 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(typeOrBaseId: TypeId | BaseId, grant: TypeGrant): Promise<(StackRecord & {
+        content: GrantContent;
+    })[]>;
     /**
-     * Validates the whole grant batch before any record is created, so a bad
-     * entry fails clean rather than leaving a partial set written. Actions
-     * must be known GrantAction values, typeIds must be well-formed, and the
-     * _grant/_config families are refused — see docs/spec/access-control.md
-     * § Type-level grants.
+     * Actions must be known GrantAction values, typeIds must be well-formed,
+     * and the _grant/_config families are refused — see
+     * docs/spec/access-control.md § Type-level grants.
      */
-    private checkGrantsValid;
+    private checkGrantValid;
     private seedSystemTypes;
     /**
      * Fast-fail for the ifVersion precondition using the already-fetched
@@ -868,8 +876,8 @@ export declare class Stack implements StackClient {
      * 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.
+     * 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;