@haverstack/core 0.37.0 → 0.39.0

package/dist/types.d.ts

@@ -13,12 +13,15 @@
 export type RecordId = string;
 /** Namespaced, versioned type identifier e.g. "com.example.myapp/note@2" */
 export type TypeId = string;
-/** Opaque file identifier returned by putAttachment */
+/** A type family: a TypeId without its version, e.g. "com.example.myapp/note" */
+export type BaseId = string;
+/** Opaque file identifier returned by putBlob() */
 export type FileId = string;
 /**
  * Reverse-DNS identifier for the software that wrote a Record, e.g.
  * "com.example.myapp" — not a RecordId. Self-reported and never a
- * permission input; `StackRecord.principalId` is the verified counterpart.
+ * permission input; `StackRecord.createdBy.principalId` is the verified
+ * counterpart.
  * See docs/spec/identity.md § App.
  */
 export type AppId = string;
@@ -29,6 +32,17 @@ export type AppId = string;
  * See docs/spec/identity.md.
  */
 export type EntityId = string;
+/**
+ * Who did something, and through which principal. `subjectId` is who the
+ * act is attributed to; `principalId` is who authenticated, present only
+ * when it differs — a delegated app acting for its user. `Stack` stores
+ * a `principalId` equal to `subjectId` as absent, so the two spellings of
+ * "acted as itself" never diverge. See docs/spec/data-model.md § Actor.
+ */
+export type Actor = {
+    subjectId: EntityId;
+    principalId?: EntityId;
+};
 export type TagAssociation = {
     kind: 'tag';
     label: string;
@@ -36,7 +50,7 @@ export type TagAssociation = {
 /**
  * `attachmentRecordId` names the `_attachment` record whose upload
  * established this reference — annotation, not identity, since `fileId`
- * alone is what GC, the `attachmentFileId` filter and file access ask
+ * alone is what GC, the `referencesFileId` filter and file access ask
  * about. See docs/spec/attachments.md § Naming the upload a reference came from.
  */
 export type AttachmentAssociation = {
@@ -51,7 +65,7 @@ export type AttachmentAssociation = {
  * stack. See docs/spec/data-model.md § Associations.
  */
 export type RecordTarget = {
-    scope: 'record';
+    kind: 'record';
     recordId: RecordId;
     stackUrl?: string;
 };
@@ -61,7 +75,7 @@ export type RecordTarget = {
  * See docs/spec/identity.md § Group.
  */
 export type EntityTarget = {
-    scope: 'entity';
+    kind: 'entity';
     entityId: EntityId;
 };
 /**
@@ -71,7 +85,7 @@ export type EntityTarget = {
  * See docs/spec/data-model.md § Relationship targets.
  */
 export type ExternalTarget = {
-    scope: 'external';
+    kind: 'external';
     ns: string;
     id: string;
 };
@@ -87,25 +101,28 @@ export type RelationshipAssociation = {
  * granting and revoking are a plain add and remove and the element's
  * identity carries its whole meaning. Its grantee shape is its own rather
  * than a `RelationshipTarget`: a target names no role and has no group
- * scope. See docs/spec/access-control.md § Record-level permissions.
+ * arm. See docs/spec/access-control.md § Record-level permissions.
  */
 export type PermissionAssociation = {
     kind: 'permission';
     label: 'read' | 'write';
-    grantee: PermissionGrantee;
+    grantee: Grantee;
 };
+/** An entity's standing within a `_group` Record's roster. `admin` implies `member` for ACL purposes. */
+export type GroupRole = 'member' | 'admin';
 /**
- * Who a permission reaches. `role` is required — `member` is the wider
- * set, `admin` the narrower, matching the roster labels where admin
- * implies member. See docs/spec/identity.md § Group.
+ * The grantee arms both permission layers share, spelled identically so a
+ * value built for one is valid for the other. `role` is required — `member`
+ * is the wider set, `admin` the narrower, matching the roster labels where
+ * admin implies member. See docs/spec/access-control.md § Who a grant reaches.
  */
-export type PermissionGrantee = {
-    scope: 'entity';
+export type Grantee = {
+    kind: 'entity';
     entityId: EntityId;
 } | {
-    scope: 'group';
+    kind: 'group';
     groupId: RecordId;
-    role: 'member' | 'admin';
+    role: GroupRole;
 };
 /**
  * Reach to the world, spelled affirmatively: it names no grantee and
@@ -166,46 +183,43 @@ export type AssociationChange = {
  * record, so they stay their own verbs rather than folding in here.
  * See docs/spec/data-model.md § Mutations.
  */
-export type RecordChanges = {
+export type RecordChangeSet = {
     contentPatch?: Record<string, unknown | null>;
-    parentId?: string | null;
+    parentId?: RecordId | null;
     permissions?: AuthorityAssociation[];
     associations?: DataAssociation[];
     unlisted?: boolean;
 };
 /** The keys of a change set, for presence checks that must not miss one. */
-export declare const RECORD_CHANGE_KEYS: readonly ["contentPatch", "parentId", "permissions", "associations", "unlisted"];
+export declare const RECORD_CHANGE_SET_KEYS: readonly ["contentPatch", "parentId", "permissions", "associations", "unlisted"];
 export type StackRecord = {
     id: RecordId;
     typeId: TypeId;
     createdAt: Date;
     updatedAt: Date;
     content: Record<string, unknown>;
+    /**
+     * Ordinal of the snapshot history, not a count of changes: associations,
+     * permissions, parent and listing moves leave it alone. See
+     * docs/spec/versioning.md § Version history.
+     */
     version: number;
     parentId?: RecordId;
-    entityId?: EntityId;
     appId?: AppId;
     /**
-     * The authenticated principal behind the write, when it isn't the author
-     * itself — a delegated app's own DID. Absent means the writer
-     * authenticated as the author, so `appId` is an unverifiable self-report;
-     * present means `appId` can be checked against the `_app` record naming
-     * this DID. See docs/spec/identity.md § App.
-     */
-    principalId?: EntityId;
-    /**
-     * The subject that performed the mutation this version records — unlike
-     * `entityId`, it moves with every write. Absent means an unscoped `Stack`
-     * wrote it, which names no requester.
+     * The record's author, stamped once by the create. A `principalId` here
+     * is what lets `appId` be checked against the `_app` record naming that
+     * DID; without one, `appId` is an unverifiable self-report.
      * See docs/spec/data-model.md § Authorship and attribution.
      */
-    updatedBy?: EntityId;
+    createdBy?: Actor;
     /**
-     * The authenticated principal behind that mutation, when it isn't the
-     * subject — `principalId` is the same fact about the create.
+     * Who performed the mutation this version records — unlike `createdBy`,
+     * it moves with every write. Absent means an unscoped `Stack` wrote it,
+     * which names no requester.
      * See docs/spec/data-model.md § Authorship and attribution.
      */
-    updatedVia?: EntityId;
+    updatedBy?: Actor;
     deletedAt?: Date;
     /**
      * Present when the record is withheld from enumeration — absent from
@@ -232,15 +246,13 @@ export type RecordVersion = {
     content: Record<string, unknown>;
     updatedAt: Date;
     /**
-     * The record's author, carried through from `record.entityId` — not the
-     * entity that performed the change this version records.
+     * The record's author, carried through from `record.createdBy` — not the
+     * actor of the change this version records.
      * See docs/spec/versioning.md § Version history.
      */
-    entityId?: EntityId;
+    createdBy?: Actor;
     /** Who performed the mutation that produced this version. */
-    updatedBy?: EntityId;
-    /** The principal behind that mutation, when it isn't `updatedBy`. */
-    updatedVia?: EntityId;
+    updatedBy?: Actor;
 };
 export type ScalarFieldKind = 'string' | 'number' | 'boolean' | 'date' | 'text' | 'record-ref' | 'file-ref';
 export type ScalarFieldDef = {
@@ -294,7 +306,7 @@ export type TypeSchema = {
 };
 export type StackType = {
     id: TypeId;
-    baseId: string;
+    baseId: BaseId;
     version: number;
     name: string;
     schema: TypeSchema;
@@ -311,7 +323,7 @@ export type StackType = {
 export type EntityContent = {
     /**
      * The identity this profile is about. e.g. "did:key:z6Mk...". A binding,
-     * not a value — a Record's `entityId` resolves through it to the name
+     * not a value — an Actor's `subjectId` resolves through it to the name
      * this card carries, so it is unique per stack and immutable once set.
      * See docs/spec/identity.md § DID bindings.
      */
@@ -341,7 +353,7 @@ export type AppContent = {
     version?: string;
     /**
      * The DID this app authenticates with, when it holds a key of its own.
-     * Lets an attribution UI resolve a record's `principalId` to this card,
+     * Lets an attribution UI resolve an Actor's `principalId` to this card,
      * and a server check a self-reported `appId` against the principal that
      * wrote it. Absent for apps that ride their user's identity. Unique per
      * stack and immutable once set, like `appId` above — see
@@ -366,7 +378,7 @@ export type GroupContent = {
 /**
  * Actions that can be granted via a _grant record. The array is the source
  * of truth — GrantAction is derived from it so runtime validation (see
- * Stack.grant()) can't drift from the type.
+ * Stack.grantType()) can't drift from the type.
  */
 export declare const GRANT_ACTIONS: readonly ["create", "read-own", "read-any", "update-own", "update-any", "delete-own", "delete-any"];
 export type GrantAction = (typeof GRANT_ACTIONS)[number];
@@ -385,16 +397,18 @@ export type GrantAction = (typeof GRANT_ACTIONS)[number];
  * principal half of a delegated request.
  * See docs/spec/access-control.md § Type-level grants.
  */
-export type GrantGrantee = {
-    kind: 'entity';
-    entityId: EntityId;
-} | {
-    kind: 'group';
-    groupId: RecordId;
-    role: 'member' | 'admin';
-} | {
+export type GrantGrantee = Grantee | {
     kind: 'authenticated';
 };
+/**
+ * What `Stack.grantType()` and `Stack.revokeType()` take beside the type they act
+ * on — the type-level counterpart of the `AuthorityAssociation`
+ * `grantAccess()` takes beside a record id.
+ */
+export type TypeGrant = {
+    actions: GrantAction[];
+    grantee: GrantGrantee;
+};
 /** Content for _grant records */
 export type GrantContent = {
     /** Which record type the grant applies to. */
@@ -404,6 +418,13 @@ export type GrantContent = {
     /** Who the grant reaches. Required — see GrantGrantee. */
     grantee: GrantGrantee;
 };
+/** The metadata an upload's `_attachment@1` record carries beside its bytes. */
+export type PutAttachmentOptions = {
+    mimeType: string;
+    filename?: string;
+    /** Attribution for the metadata record, as create()'s `appId`. */
+    appId?: AppId;
+};
 /** Content for _attachment records — one per upload, tracks file metadata. */
 export type AttachmentContent = {
     /** Content-addressed file identifier (SHA-256 hex). */
@@ -447,21 +468,21 @@ export declare const SYSTEM_TYPES: {
  * matches its whole namespace.
  */
 export type RelationshipTargetPattern = {
-    scope: 'record';
+    kind: 'record';
     recordId: RecordId;
     stackUrl?: string;
 } | {
-    scope: 'entity';
+    kind: 'entity';
     entityId: EntityId;
 } | {
-    scope: 'external';
+    kind: 'external';
     ns: string;
     id?: string;
 };
 /**
  * A relationship query names a label, a target, or both — never neither.
  * "Carries any relationship at all" is deliberately not expressible, in
- * line with `tags` and `hasAttachment`, which likewise have no match-any
+ * line with `tags` and `attachment`, which likewise have no match-any
  * form. See docs/spec/data-model.md § Filter.
  */
 export type RelatedToFilter = {
@@ -471,6 +492,18 @@ export type RelatedToFilter = {
     label?: string;
     target: RelationshipTargetPattern;
 };
+/**
+ * An attachment query names a label, a file, or both — never neither —
+ * and both halves together match one association. See
+ * docs/spec/data-model.md § Filter.
+ */
+export type AttachmentFilter = {
+    label: string;
+    fileId?: FileId;
+} | {
+    label?: string;
+    fileId: FileId;
+};
 export type DateRange = {
     before?: Date;
     after?: Date;
@@ -484,15 +517,19 @@ export type RecordFilter = {
      * it works regardless of which versions happen to exist. Combined with
      * typeId (if both given) as an intersection.
      */
-    baseId?: string | string[];
+    baseId?: BaseId | BaseId[];
     parentId?: RecordId | null;
     appId?: AppId | AppId[];
-    entityId?: EntityId | EntityId[];
-    principalId?: EntityId | EntityId[];
+    /** Matches the record's author — never the latest actor, which isn't filterable. */
+    createdBy?: {
+        subjectId?: EntityId | EntityId[];
+        principalId?: EntityId | EntityId[];
+    };
     createdAt?: DateRange;
     updatedAt?: DateRange;
     tags?: string[];
-    hasAttachment?: string;
+    /** Records carrying a matching attachment association. See docs/spec/data-model.md § Filter. */
+    attachment?: AttachmentFilter;
     /**
      * Records carrying a matching relationship association. Either half may
      * be given alone and each is a pattern: a bare `label` matches every
@@ -501,13 +538,18 @@ export type RecordFilter = {
      * only local targets. See docs/spec/data-model.md § Filter.
      */
     relatedTo?: RelatedToFilter;
-    attachmentFileId?: FileId;
+    /**
+     * Records that reference this file, through an attachment association
+     * or a top-level `file-ref` content field — the question GC and
+     * `deleteAttachment()` ask. See docs/spec/attachments.md § Deleting attachments.
+     */
+    referencesFileId?: FileId;
     /**
      * Exact match on content fields, keyed by a dot-separated path
      * (`'emails.value'`). An array anywhere along the path is matched
      * element-wise, so the motivating question — which contact holds this
      * email address — is one filter. A multi-segment key needs the
-     * `filter.content: 'path'` capability. POST /query only.
+     * `filter.content: 'path'` capability. POST /records/query only.
      * See docs/spec/data-model.md § Filter.
      */
     content?: Record<string, unknown>;
@@ -516,7 +558,7 @@ export type RecordFilter = {
      * since a filter value matches what is there rather than whether
      * anything is. Element-wise like `content`, so a path holds a value
      * when at least one non-null value is reachable at it. Needs the
-     * filter.contentPresent capability. POST /query only.
+     * filter.contentPresent capability. POST /records/query only.
      * See docs/spec/data-model.md § Filter.
      */
     contentPresent?: string[];
@@ -600,19 +642,19 @@ export type ContentFilterReach =
 /** Multi-segment paths too (`'emails.value'`). */
  | 'path';
 /**
- * What an adapter honors, grouped by the query surface each entry gates:
+ * What a Stack — and the adapter under it — honors, grouped by the query surface each entry gates:
  * every flag under `filter`/`sort` is named for the query key it answers
  * for, so the capability a query needs is derivable from the query rather
  * than memorized. `limits` sits apart because a byte ceiling is not a
  * feature to gate on but a number to pre-check against.
  * See docs/spec/adapters.md § Adapter capabilities.
  */
-export type AdapterCapabilities = {
+export type StackCapabilities = {
     filter: {
         /**
          * Required `'path'` for local/in-process adapters; a wire adapter may
          * report a shallower rung, driven by the server's discovery response.
-         * Stack.query() throws StackQueryError rather than silently widening.
+         * Stack.query() throws StackBadRequestError rather than silently widening.
          */
         content: ContentFilterReach;
         /**
@@ -666,24 +708,23 @@ export type AdapterCapabilities = {
         contentBytes: number | null;
     };
 };
-/** What a Stack can do, as seen by app and plugin code. */
-export type StackFeatures = AdapterCapabilities;
 /**
  * A capability a query can be refused for, as its path into
- * AdapterCapabilities — the same name the spec and a discovery response
+ * StackCapabilities — the same name the spec and a discovery response
  * use, so an error says which key to look at. `limits` never appears: a
  * ceiling is not something a query can lack.
  */
 export type MissingCapability = 'filter.content' | 'filter.contentPresent' | 'filter.search' | 'sort.fields' | 'sort.contentField';
 /**
  * Opt-in optimistic-concurrency precondition, accepted by every mutation
- * that bumps a record's version. On mismatch the adapter throws
- * StackVersionConflictError without applying anything. The check is atomic
- * inside the adapter's write, never a read-then-write. See
- * docs/spec/versioning.md § Optimistic concurrency (`ifVersion`).
+ * that bumps a record's version. On mismatch the mutation throws
+ * StackVersionConflictError and changes nothing; omit to keep
+ * last-writer-wins. An adapter checks it atomically inside its write, never
+ * as a read-then-write. See docs/spec/versioning.md § Optimistic
+ * concurrency (`ifVersion`).
  */
-export type ExpectedVersionOptions = {
-    expectedVersion?: number;
+export type IfVersionOptions = {
+    ifVersion?: number;
 };
 /**
  * Accepted by every mutating StackRecordAdapter method. The adapter
@@ -713,8 +754,7 @@ export type BumpVersionOptions = {
  * See docs/spec/data-model.md § Authorship and attribution.
  */
 export type ActorOptions = {
-    updatedBy?: EntityId;
-    updatedVia?: EntityId;
+    actor?: Actor;
 };
 /**
  * The part of a change that the record cannot report once the write has
@@ -780,24 +820,24 @@ export type JournalOptions = {
 /** Window into a record's journal. Omitting both reads the whole log, oldest first. */
 export type JournalQuery = {
     /** Entries after this seq, exclusive. */
-    sinceSeq?: number;
+    afterSeq?: number;
     limit?: number;
 };
 /**
  * The coarse branch every subscriber makes, closed at four values. A
  * handler covering exactly these is complete, not merely adequate:
- * `changed` is an upsert signal carrying seven distinct verbs.
+ * `changed` is an upsert signal carrying nine distinct verbs.
  * See docs/spec/events.md § The event shape.
  */
 export type ChangeKind = 'created' | 'changed' | 'deleted' | 'purged';
 /**
  * The precise verb behind a ChangeKind, for consumers that distinguish a
- * reshare from an edit. `associate`, `dissociate`, `reparent`, `unlist`
- * and `list` carry the record's version/updatedAt exactly as they stood
- * before the call; every other entry bumps. See docs/spec/versioning.md
- * § Version history.
+ * reshare from an edit. Each is named after the call that produced it; see
+ * docs/spec/events.md § The event shape for the three that aren't a method
+ * name. `associate`, `dissociate`, `reshare`, `reparent`, `unlist` and
+ * `list` don't bump; see docs/spec/versioning.md § Version history.
  */
-export type ChangeOp = 'create' | 'patch' | 'associate' | 'dissociate' | 'permissions' | 'migrate' | 'restore' | 'delete' | 'undelete' | 'hard-delete'
+export type ChangeOp = 'create' | 'patch' | 'associate' | 'dissociate' | 'reshare' | 'migrate' | 'restore' | 'delete' | 'undelete' | 'purge'
 /**
  * Emitted even though the record's post-change state (`unlistedAt` now
  * set) would otherwise be excluded by the same filter it announces —
@@ -821,11 +861,7 @@ export type ChangeOp = 'create' | 'patch' | 'associate' | 'dissociate' | 'permis
  * `Stack`: absence is a fact of its own and never stands in for the
  * author. See docs/spec/events.md § Attribution.
  */
-export type ChangeActor = {
-    /** The subject the change is attributed to. */
-    entityId: EntityId;
-    /** The principal behind it, when a delegated app acted for the subject. */
-    principalId?: EntityId;
+export type ChangeActor = Actor & {
     /** Self-reported at create, never a trust input. See AppId. */
     appId?: AppId;
 };
@@ -851,14 +887,14 @@ export type RecordChange = {
     typeId: TypeId;
     /**
      * The version this change produced; on `purged`, the version destroyed.
-     * Unchanged from the record's prior version on `associate`/`dissociate`,
-     * which don't bump.
+     * Unchanged from the record's prior version on every op that doesn't
+     * bump — see ChangeOp.
      */
     version: number;
     /**
      * As persisted by this change; on `purged`, when the delete ran.
-     * Unchanged from the record's prior `updatedAt` on `associate`/
-     * `dissociate`, which don't touch it.
+     * Unchanged from the record's prior `updatedAt` on every op that
+     * doesn't bump.
      */
     updatedAt: Date;
     parentId?: RecordId;
@@ -869,14 +905,14 @@ export type RecordChange = {
      * `attachmentRecordId`. Present whenever `ops` includes `associate`, on
      * the same "as of this change" convention as every other field here.
      */
-    associationsAdded?: Association[];
+    associationsAdded?: DataAssociation[];
     /**
      * Associations no longer present, identity only — kind and label, plus
      * `fileId` for an attachment — present whenever `ops` includes
      * `dissociate`. An attachment's `attachmentRecordId` is never repeated
      * here, the same way a `purged` frame never carries what it destroyed.
      */
-    associationsRemoved?: Association[];
+    associationsRemoved?: DataAssociation[];
     /**
      * The record as of this change — present only when asked for and
      * available, never on `purged`. Shared with every other subscriber on
@@ -888,19 +924,16 @@ export type RecordChange = {
      * stack's own writes included — so a consumer holding a cursor keeps
      * the last one that was present rather than the last change's.
      */
-    seq?: string;
+    cursor?: string;
 };
 /**
  * Applied by the emitter, exactly: a filtered subscription never receives
  * an event outside its filter, so filtering again is redundant rather than
- * defensive.
+ * defensive. Every key means what it means on `RecordFilter`, so one value
+ * can drive both `query()` and `subscribe()`. See docs/spec/events.md
+ * § Subscribing.
  */
-export type ChangeFilter = {
-    /** Matched by baseId, as grants are, so a version bump orphans nothing. */
-    typeId?: TypeId | TypeId[];
-    parentId?: RecordId | null;
-    /** The record's author. Not the actor — see ChangeActor. */
-    entityId?: EntityId;
+export type ChangeFilter = Pick<RecordFilter, 'typeId' | 'baseId' | 'parentId' | 'createdBy'> & {
     kinds?: ChangeKind[];
 };
 /** Ends a subscription. Safe to call more than once. */
@@ -918,16 +951,16 @@ export type SubscribeOptions = {
      */
     includeUnlisted?: boolean;
     /**
-     * Resume from this cursor rather than the present — the last `seq` that
-     * was present on a delivered `RecordChange`. A relaying stack delivers
+     * Resume from this cursor rather than the present — the last `cursor`
+     * that was present on a delivered `RecordChange`. A relaying stack delivers
      * its own local writes through the same handler and those carry none, so
-     * a consumer that stores every change's `seq` unconditionally erases its
+     * a consumer that stores every change's `cursor` unconditionally erases its
      * own cursor on its next write.
      *
      * Forwarded to the adapter as `SubscribeChangesOptions.since`, so it
      * only means something where a relay exists: a stack with none has no
      * third-party writes to have missed, and therefore no cursor it could
-     * ever have minted. Passing `since` there throws `StackQueryError`
+     * ever have minted. Passing `since` there throws `StackBadRequestError`
      * rather than silently starting from the present, which would let the
      * caller believe it resumed when it did not. A cursor outside the
      * framable charset is refused the same way, so a malformed one reports
@@ -973,7 +1006,7 @@ export type SubscribeChangesOptions = {
  * associations, versioning, type definitions, and stack identity.
  */
 export interface StackRecordAdapter {
-    readonly capabilities: AdapterCapabilities;
+    readonly capabilities: StackCapabilities;
     /** DID of the stack owner. Set during adapter initialization. */
     readonly ownerEntityId: EntityId;
     /**
@@ -1013,19 +1046,19 @@ export interface StackRecordAdapter {
      * See docs/spec/data-model.md § Mutations and docs/spec/versioning.md
      * § Version history.
      */
-    mutateRecord(id: RecordId, changes: RecordChanges, opts?: ExpectedVersionOptions & SnapshotOptions & BumpVersionOptions & ActorOptions & JournalOptions): Promise<StackRecord>;
+    mutateRecord(id: RecordId, changes: RecordChangeSet, opts?: IfVersionOptions & SnapshotOptions & BumpVersionOptions & ActorOptions & JournalOptions): Promise<StackRecord>;
     /**
      * Returns the record this call acted on: as it now stands after a soft
-     * delete, and as it stood immediately before destruction after a hard
-     * one — captured inside the same write, so nothing can observe or alter
+     * delete, and as it stood immediately before destruction after a
+     * purge — captured inside the same write, so nothing can observe or alter
      * it in between. Null when there was no record to delete, which is the
      * only case that mutates nothing.
      */
     deleteRecord(id: RecordId, opts?: {
-        hard?: boolean;
-    } & ExpectedVersionOptions & SnapshotOptions & ActorOptions & JournalOptions): Promise<StackRecord | null>;
+        purge?: boolean;
+    } & IfVersionOptions & SnapshotOptions & ActorOptions & JournalOptions): Promise<StackRecord | null>;
     /** Reverse a soft delete. Returns the record as it now stands. */
-    undeleteRecord(id: RecordId, opts?: ExpectedVersionOptions & SnapshotOptions & ActorOptions & JournalOptions): Promise<StackRecord>;
+    undeleteRecord(id: RecordId, opts?: IfVersionOptions & SnapshotOptions & ActorOptions & JournalOptions): Promise<StackRecord>;
     queryRecords(query: StackQuery): Promise<QueryResult>;
     /**
      * Add an association. Never bumps `version`/`updatedAt` and never
@@ -1058,20 +1091,20 @@ export interface StackRecordAdapter {
      * Bumps version internally; throws StackNotFoundError if the version
      * doesn't exist.
      */
-    restoreVersion(id: RecordId, version: number, opts?: ExpectedVersionOptions & SnapshotOptions & ActorOptions & JournalOptions): Promise<StackRecord>;
+    restoreVersion(id: RecordId, version: number, opts?: IfVersionOptions & SnapshotOptions & ActorOptions & JournalOptions): Promise<StackRecord>;
     /**
      * Commit a migration: write new content under a new typeId in one step.
      * This is the only way a record's typeId changes after creation — used by
      * Stack.commitMigration() and Stack.migrateAll(); Stack.mutate() never
      * changes typeId as a side effect. Bumps version internally.
      */
-    commitMigration(id: RecordId, toTypeId: TypeId, content: Record<string, unknown>, opts?: ExpectedVersionOptions & SnapshotOptions & ActorOptions & JournalOptions): Promise<StackRecord>;
+    commitMigration(id: RecordId, toTypeId: TypeId, content: Record<string, unknown>, opts?: IfVersionOptions & SnapshotOptions & ActorOptions & JournalOptions): Promise<StackRecord>;
     saveType(type: StackType): Promise<void>;
     getType(id: TypeId): Promise<StackType | null>;
     listTypes(): Promise<StackType[]>;
     /**
-     * Atomically verify fileId is unreferenced, then hard-delete its
-     * metadata records in the same adapter call, returning their ids.
+     * Atomically verify fileId is unreferenced, then purge its
+     * metadata records in the same adapter call, returning the deleted records.
      * Throws StackConflictError if still referenced. Optional —
      * Stack.deleteAttachment() has a non-atomic fallback. See
      * docs/spec/attachments.md § Deleting attachments.
@@ -1088,12 +1121,12 @@ export interface StackRecordAdapter {
      * storage, so locally there is no third party whose writes could have
      * been missed. See docs/spec/events.md § Where events come from.
      */
-    subscribeChanges?(opts: SubscribeChangesOptions, handler: (change: RecordChange) => void): Promise<() => void>;
+    subscribeChanges?(opts: SubscribeChangesOptions, handler: (change: RecordChange) => void): Promise<Unsubscribe>;
     flush?(): Promise<void>;
     close?(): Promise<void>;
 }
-/** One stored blob, as reported by StackBlobAdapter.listFiles(). */
-export type BlobFileInfo = {
+/** One stored blob, as reported by StackBlobAdapter.listBlobs(). */
+export type BlobInfo = {
     fileId: FileId;
     size: number;
     /** When the blob was written. Used to apply a GC grace period to fresh, not-yet-associated uploads. */
@@ -1104,22 +1137,22 @@ export type BlobFileInfo = {
  * attachment metadata lives on _attachment@1 records in the record adapter.
  */
 export interface StackBlobAdapter {
-    putAttachment(data: Uint8Array): Promise<FileId>;
-    getAttachment(fileId: FileId): Promise<Uint8Array>;
-    deleteAttachment(fileId: FileId): Promise<void>;
+    putBlob(data: Uint8Array): Promise<FileId>;
+    getBlob(fileId: FileId): Promise<Uint8Array>;
+    deleteBlob(fileId: FileId): Promise<void>;
     /**
      * Enumerate every blob currently in storage. Optional — without it,
      * garbage collection can't find bare-bytes orphans (bytes with no
      * metadata record at all). See docs/spec/attachments.md § Garbage
      * collection.
      */
-    listFiles?(): Promise<BlobFileInfo[]>;
+    listBlobs?(): Promise<BlobInfo[]>;
     flush?(): Promise<void>;
     close?(): Promise<void>;
 }
 /**
  * A complete adapter: record storage and blob storage combined.
- * Pass this to Stack.create(). Build one with combineAdapters() when you
+ * Pass this to Stack.open(). Build one with combineAdapters() when you
  * want different backends for records and blobs (e.g. SQLite + S3).
  */
 export type StackAdapter = StackRecordAdapter & StackBlobAdapter & {
@@ -1130,22 +1163,16 @@ export type StackAdapter = StackRecordAdapter & StackBlobAdapter & {
      * synthesized by combineAdapters(). A security boundary, not an
      * efficiency shortcut — see docs/spec/adapters.md § Interface split.
      */
-    putAttachmentWithMetadata?(data: Uint8Array, mimeType: string, filename?: string, appId?: AppId): Promise<StackRecord>;
+    putAttachmentWithMetadata?(data: Uint8Array, opts: PutAttachmentOptions): Promise<StackRecord>;
 };
 /**
- * The two identities a token establishes. Both are always populated: on an
- * undelegated token they are the same DID, and spelling that out is what
- * keeps the mapping onto asEntity() mechanical.
- *
- *     stack.asEntity(session.principalId, { onBehalfOf: session.subjectId })
- *
- * See docs/spec/access-control.md § Delegation: principal and subject.
+ * The two identities a token establishes — an Actor whose `principalId` is
+ * always populated, equal to `subjectId` on an undelegated token, so a
+ * server reading one never has to default it. Passes to `Stack.asActor()`
+ * as is. See docs/spec/access-control.md § Delegation: principal and subject.
  */
-export type TokenSession = {
-    /** Who authenticated — the DID that proved key possession. Governs authority. */
+export type TokenSession = Actor & {
     principalId: EntityId;
-    /** Who the principal acts for. Governs attribution. Equal to principalId unless delegated. */
-    subjectId: EntityId;
 };
 export type TokenInfo = TokenSession & {
     id: string;
@@ -1160,14 +1187,13 @@ export type TokenInfo = TokenSession & {
  * handshake. Tokens SHOULD be stored outside the portable stack file.
  * See docs/spec/wire-format.md § Authentication.
  *
- * `onBehalfOf` is the delegation binding, and no handshake can establish
- * it — proving key possession proves the principal and nothing about whom
- * it may act for. It is asserted by the owner out of band, which is safe
+ * The actor's `subjectId`, where it differs from `principalId`, is the
+ * delegation binding, and no handshake can establish it — proving key
+ * possession proves the principal and nothing about whom it may act for. It is asserted by the owner out of band, which is safe
  * because effective authority is the intersection of both parties' grants.
  */
 export interface StackTokenStore {
-    createToken(principalId: EntityId, opts?: {
-        onBehalfOf?: EntityId;
+    createToken(actor: Actor, opts?: {
         label?: string;
         expiresAt?: Date;
     }): Promise<{