@haverstack/core 0.41.0 → 0.43.0

package/README.md

@@ -46,40 +46,44 @@ const adapter = await LocalAdapter.open({
 // safe to keep passing on every open, it's a no-op once the record exists.
 const stack = await Stack.open(adapter, { ownerProfile: { name: 'Jane Smith' } });
 
-// Define a type. The handle carries the id and schema, and the compiler
+// Define a type. The handle carries the id, name and schema, and the compiler
 // derives the content type from it — no separate interface to keep in step.
-const Note = typeHandle('com.example.myapp/note@1', {
-  text: { kind: 'text', required: true },
-  title: { kind: 'string' },
+const Note = typeHandle({
+  id: 'com.example.myapp/note@1',
+  name: 'Note',
+  schema: {
+    text: { kind: 'text', required: true },
+    title: { kind: 'string' },
+  },
 });
-await stack.defineType({ ...Note, name: 'Note' });
+await stack.defineType(Note);
+
+// Typed access to the Note family
+const notes = stack.collection(Note);
 
 // Create a record
-const note = await stack.create(Note, {
+const note = await notes.create({
   text: 'Hello, Haverstack!',
   title: 'My first note',
 });
 
 // Update its content (partial merge — only changed fields needed)
-await stack.patchContent(Note, note.id, { title: 'Updated title' });
+await notes.patchContent(note.id, { title: 'Updated title' });
 
 // Read it back, typed: `content.text` is a string
-const same = await stack.get(Note, note.id);
+const same = await notes.get(note.id);
 
 // Tag it
-await stack.associate(note.id, [{ kind: 'tag', label: 'favourite' }]);
+await notes.editAssociations(note.id, [
+  { op: 'add', association: { kind: 'tag', label: 'favourite' } },
+]);
 
-// Or change several things at once — one version, one atomic write
-await stack.mutate(note.id, {
-  contentPatch: { title: 'Final title' },
-  permissions: [{ kind: 'anyone', label: 'read' }],
-  unlisted: false,
-});
+// Share it with everyone — each aspect of a record has its own verb
+await notes.setAccess(note.id, [{ kind: 'anyone', label: 'read' }]);
 
-// Query. With no filter, query() returns every record you can read, from every
-// app and system types included, so filter by typeId, baseId or appId to get your own.
-const notes = await stack.query({
-  filter: { typeId: 'com.example.myapp/note@1', tags: ['favourite'] },
+// Query the family. stack.query() reads across every type you can see instead.
+const { records: favourites } = await notes.query({
+  filter: { tags: ['favourite'] },
   sort: { field: 'createdAt', direction: 'desc' },
 });
 
@@ -92,60 +96,117 @@ await stack.close();
 An app has two layers, because the stack draws a line between them:
 
 - **A data layer that takes a `StackClient`** — the record API `Stack` and `ScopedStack` both implement. The same code then runs embedded as the owner, or behind a server as a requester who reaches only what they were granted.
-- **An install function that takes a `Stack`**, run by the owner. Defining types, `migrateAll()` and `grantType()` change the whole stack rather than one record, so they live on `Stack` alone and are absent from `StackClient`. Over the wire, `POST /types` and `POST /records/:id/migrate` are served to the owner acting alone.
+- **An install that the owner approves.** Defining types, `migrateAll()` and `grantType()` change the whole stack rather than one record, so they live on `Stack` alone and are absent from `StackClient`.
 
-`registerMigration()` belongs to neither. Its registry lives in memory on each `Stack` instance, so it runs at **every startup**, right after `Stack.open()` — an install function that registers migrations and runs once leaves every later start without them.
+Migrations belong to neither. They are passed to `Stack.open()` on **every startup**, so the chain is complete before the first read.
 
 ```ts
-import { Stack, typeHandle, type StackClient } from '@haverstack/core';
+import { Stack, map, migration, typeHandle } from '@haverstack/core';
+import type { AppManifest, Collection, ContentOf, StackClient } from '@haverstack/core';
 
-const NoteV1 = typeHandle('com.example.myapp/note@1', {
-  text: { kind: 'text', required: true },
+export const Shelf = typeHandle({
+  id: 'com.example.reading/shelf@1',
+  name: 'Shelf',
+  schema: { name: { kind: 'string', required: true } },
 });
-export const Note = typeHandle('com.example.myapp/note@2', {
-  text: { kind: 'text', required: true },
-  pinned: { kind: 'boolean', required: true },
+const BookV1 = typeHandle({
+  id: 'com.example.reading/book@1',
+  name: 'Book',
+  schema: {
+    title: { kind: 'string', required: true },
+    status: { kind: 'enum', values: ['reading', 'done'], required: true },
+  },
 });
+export const Book = typeHandle({
+  id: 'com.example.reading/book@2',
+  name: 'Book',
+  migratesFrom: BookV1,
+  schema: {
+    title: { kind: 'string', required: true },
+    status: { kind: 'enum', values: ['reading', 'finished'], required: true },
+    shelfId: { kind: 'record-ref' },
+  },
+});
+export const Review = typeHandle({
+  id: 'com.example.reading/review@1',
+  name: 'Review',
+  schema: {
+    bookId: { kind: 'record-ref', required: true },
+    rating: { kind: 'number', required: true },
+    text: { kind: 'text' },
+  },
+});
+
+export interface ShelfContent extends ContentOf<typeof Shelf.schema> {}
+export interface BookContent extends ContentOf<typeof Book.schema> {}
+export interface ReviewContent extends ContentOf<typeof Review.schema> {}
+
+// Startup: pass to every Stack.open(). Each step is checked against both
+// handles' schemas when migration() runs.
+export const migrations = [migration(BookV1, Book, [map('status', { done: 'finished' })])];
 
-// Data layer: whoever the stack lets in.
-export class Notes {
-  constructor(private readonly client: StackClient) {}
-  add(text: string) {
-    return this.client.create(Note, { text, pinned: false });
+// Data layer: one collection per type, and typed records from every verb.
+export class Library {
+  readonly shelves: Collection<ShelfContent>;
+  readonly books: Collection<BookContent>;
+  readonly reviews: Collection<ReviewContent>;
+
+  constructor(client: StackClient) {
+    this.shelves = client.collection(Shelf);
+    this.books = client.collection(Book);
+    this.reviews = client.collection(Review);
   }
-  pin(id: string) {
-    return this.client.patchContent(Note, id, { pinned: true });
+
+  addBook(title: string, shelfId: string) {
+    return this.books.create({ title, status: 'reading', shelfId });
   }
-  list() {
-    return this.client.query(Note);
+
+  finish(id: string) {
+    return this.books.patchContent(id, { status: 'finished' });
   }
-}
 
-// Startup: every open, every Stack instance.
-export function registerNoteMigrations(stack: Stack) {
-  stack.registerMigration({
-    from: NoteV1.id,
-    to: Note.id,
-    migrate: (content) => ({ ...content, pinned: false }),
-  });
-}
+  review(bookId: string, rating: number, text?: string) {
+    return this.reviews.create({ bookId, rating, ...(text && { text }) });
+  }
 
-// Install: the owner, once per stack and again after a schema change.
-// defineType() is a no-op for a schema already stored, so re-running is safe.
-export async function installNotes(stack: Stack, appDid?: string) {
-  await stack.defineType({ ...NoteV1, name: 'Note' });
-  await stack.defineType({ ...Note, name: 'Note', migratesFrom: NoteV1.id });
-  await stack.migrateAll(Note.baseId);
-  if (appDid) {
-    await stack.grantType(Note.baseId, {
-      actions: ['create', 'read-own', 'update-own', 'delete-own'],
-      grantee: { kind: 'entity', entityId: appDid },
+  // Records at @1 come back migrated to @2. One written by a newer release
+  // of the app can't be migrated down, so it is reported, not thrown.
+  async onShelf(shelfId: string) {
+    const page = await this.books.query({
+      filter: { content: { shelfId } },
+      sort: { contentField: 'title' },
     });
+    if (page.misfits.length > 0) {
+      console.warn(`${page.misfits.length} books need a newer version of this app`);
+    }
+    return page.records;
   }
 }
+
+// Install, when the owner runs the app. defineType() is a no-op for a
+// schema already stored, so re-running after an upgrade is safe.
+export async function install(stack: Stack) {
+  for (const handle of [Shelf, BookV1, Book, Review]) await stack.defineType(handle);
+  await stack.migrateAll(Book.baseId);
+}
+
+// Install, when the owner doesn't: the same handles, as a request.
+export const manifest: AppManifest = {
+  appId: 'com.example.reading',
+  name: 'Reading',
+  types: [Shelf, BookV1, Book, Review],
+  requests: [Shelf, Book, Review].map((handle) => ({
+    baseId: handle.baseId,
+    actions: ['create', 'read-own', 'update-own', 'delete-own'],
+  })),
+};
 ```
 
-The owner's own app calls `registerNoteMigrations(stack)` and `installNotes(stack)`, then `new Notes(stack)`. A server hands each requester `new Notes(stack.asActor(session))`. An app that isn't the owner has no way to install its own types yet; the owner runs its install function for it.
+**When the owner runs the app**, it opens with `Stack.open(adapter, { migrations })`, calls `install(stack)`, then `new Library(stack)`. A server hands each requester `new Library(stack.asActor(session))`.
+
+**When the app runs elsewhere** — holding its own key and reaching the stack through `APIAdapter` — it can't define types, so it asks: `adapter.requestInstall(manifest)` resolves to `pending` until the owner approves. The owner reviews `stack.planInstall(manifest, { did })` and applies it with `stack.installApp(plan)`, which defines the types, registers the app's key and grants it the requests. The app still opens with its `migrations`, then builds `new Library(stack)` over its own connection. See [App installs](https://github.com/haverstack/core/blob/main/docs/spec/apps.md).
+
+**Name content with an interface**, as above. `ContentOf` flattens its result, so a `type` alias shows the expanded object in editor hovers, while an interface keeps its name. typescript-eslint's recommended `no-empty-object-type` rule rejects an empty interface; its `allowInterfaces: 'with-single-extends'` option admits this one.
 
 ## Core concepts
 
@@ -186,24 +247,23 @@ Tags, attachments, and relationships are unified under a single model:
 
 ### Migrations
 
-Types can evolve over time. Register migration functions between adjacent versions and the library composes them into chains automatically:
+Types can evolve over time. A new version names the one it migrates from, and `migration()` builds the step between two handles from declared steps — `rename`, `map`, `add`, `drop` and `derive` — checked against both schemas when it runs. Pass every step to `Stack.open()`; the library composes adjacent steps into chains:
 
 ```ts
-await stack.defineType({
+const NoteV2 = typeHandle({
   id: 'com.example.myapp/note@2',
   name: 'Note',
+  migratesFrom: NoteV1,
   schema: { text: { kind: 'text', required: true }, title: { kind: 'string' } },
-  migratesFrom: 'com.example.myapp/note@1',
 });
 
-stack.registerMigration({
-  from: 'com.example.myapp/note@1',
-  to: 'com.example.myapp/note@2',
-  migrate: (content) => ({ ...content, title: '' }),
+const stack = await Stack.open(adapter, {
+  migrations: [migration(NoteV1, NoteV2, [add('title', '')])],
 });
+await stack.defineType(NoteV2);
 ```
 
-Records stay at the version they were written at: `get()` and `query()` return them as stored, `presentAt: 'latest'` migrates them in memory for one read, and `stack.migrateAll()` commits a family to disk. Register migrations at every startup — see [Writing an app](#writing-an-app).
+Records stay at the version they were written at: `get()` and `query()` return them as stored, `presentAt: 'latest'` migrates them in memory for one read, and `stack.migrateAll()` commits a family to disk. Because the steps are declared rather than a function, a collection carries a content filter or sort across the versions they translate to — a filter on `title` reaches records still at `@1`. Pass migrations at every startup — see [Writing an app](#writing-an-app).
 
 ## License
 

package/dist/access.d.ts

@@ -1,78 +1,74 @@
 /**
  * Stack — Permission Resolution
  * -------------------------------------------------------
- * Implements the Permissions model from the spec: a pure predicate over a
- * Record's `permissions` field, with no dependency on a transport layer or
- * storage backend. Used by ScopedStack (see scoped-stack.ts) to enforce
- * access control; exported standalone for callers that want the raw
- * predicate.
+ * The record-level permission rules, with no dependency on a transport
+ * layer or storage backend: how a grantee reaches an entity, the
+ * write-implies-read invariant, and the `_group` roster rules both layers
+ * resolve against, plus the owner-acting-alone tier. What a requester may
+ * do is a reach per verb, which scoped-stack/authority.ts builds from these.
  *
  * A permission set is read as data throughout, never as the type: it can
  * arrive from an import or a foreign server, where no compiler has seen
  * it. Every tier is affirmative, so an element read past its own kind —
  * or carrying no kind at all — confers nothing.
  */
-import type { Association, AuthorityAssociation, DataAssociation, EntityId, GroupRole, RecordId, StackRecord } from './types.js';
+import type { AuthorityAssociation, DataAssociation, EntityId, GroupRole, Grantee, RecordId, StackRecord } from './types/index.js';
 import type { ValidationError } from './validate.js';
-export type AccessMode = 'read' | 'write';
+/** Resolves a Record by ID, for walks that need no full adapter. */
+export type RecordResolver = (id: RecordId) => Promise<StackRecord | null>;
 /**
- * Resolves a Record by ID. Used to walk a `_group` Record's associations for
- * membership checks without requiring a full StackAdapter.
+ * The roles one entity holds on live `_group` rosters, keyed by group id,
+ * loaded on first use and at most once per operation, so no resolved role
+ * outlives the operation that read it — removal from a group must never go
+ * stale. See loadRosterRoles().
  */
-export type RecordResolver = (id: RecordId) => Promise<StackRecord | null>;
+export type RosterRoles = () => Promise<ReadonlyMap<RecordId, GroupRole>>;
 /**
- * Whether an entity has read or write access to a Record.
- *
- * The entity here is the **subject** — record-level permissions are written
- * about who data is for, never about the software that carried the request.
- * A delegated app's own authority is a separate question, asked of the
- * principal. See docs/spec/access-control.md § Record-level permissions and
- * § Delegation: principal and subject.
+ * The elements beside which a `write` naming `grantee` carries its bit: its
+ * own `read`, or an `anyone`, which reaches the grantee already. The one
+ * statement of write-implies-read — validation and every reach ask it.
+ * See docs/spec/access-control.md § Write implies read.
  */
-export declare function checkAccess(record: StackRecord, subjectEntityId: EntityId | null, ownerEntityId: EntityId | null, mode: AccessMode, resolveRecord: RecordResolver): Promise<boolean>;
+export declare function readCompanions(grantee: Grantee): AuthorityAssociation[];
 /**
- * Rejects a permission set where some grantee holds `write` with no `read`
- * beside it — the shape checkAccess() refuses to honor. A cross-element
+ * Whether a grantee reaches `entityId`, for both layers alike. Read as data,
+ * so an arm the write would refuse confers nothing; `member` is the wider
+ * role. See docs/spec/access-control.md § Refused at the write, and again at evaluation.
+ */
+export declare function granteeReaches(grantee: unknown, entityId: EntityId, opts: {
+    roles: RosterRoles;
+    allowGroup?: boolean;
+}): Promise<boolean>;
+/**
+ * Rejects a permission set where some `write` stands without a
+ * readCompanions() element, which no reach would honor. A cross-element
  * invariant, so it is asked of the set the write would *produce*, the same
  * way hasGroupAdmin() reads its post-state below.
  * See docs/spec/access-control.md § Write implies read.
  */
 export declare function validatePermissions(permissions: AuthorityAssociation[] | undefined, path?: string): ValidationError[];
+/** Whether a held role meets a grantee's: an admin is also a member. */
+export declare function roleSatisfies(held: GroupRole | null, required: GroupRole): boolean;
 /**
- * Whether a Record is a roster anything may resolve against, on two counts.
- * The family check: without it an app modelling its own `member` links
- * would turn every record it points a permission at into an ACL. The
- * tombstone check: deleting a Group is how a Group is withdrawn. Shared
- * with the grant path, so the two layers cannot disagree about which Groups
- * still reach anyone. See docs/spec/identity.md § Group.
+ * Whether a Record is a `_group`, in any of its type versions — the family
+ * whose roster rules apply.
  */
-export declare function carriesRoster(record: StackRecord): boolean;
+export declare function isGroupRecord(record: StackRecord): boolean;
 /**
- * An entity's role within a `_group` Record's roster. `admin`
- * short-circuits, so a matching admin association wins regardless of order.
- *
- * Reads associations alone and cannot tell whose they are: callers pass
- * carriesRoster() first, or an app's own `member` relationships become a
- * roster.
+ * An entity's role on a `_group` roster; a matching `admin` wins regardless
+ * of order. Reads associations alone and cannot tell whose they are, so
+ * callers ask it of a live `_group` only — see loadRosterRoles().
  */
 export declare function groupRoleFromAssociations(associations: DataAssociation[] | undefined, entityId: EntityId): GroupRole | null;
 /**
- * Whether a roster carries at least one `admin` — the invariant every write
- * to a `_group` Record must leave standing. Asked of the roster a write
- * would *produce*, never the one it started from: that is what lets an
- * admin remove themselves while another remains, and refuses the same
- * removal when they are the last, without either case naming who is going.
- * Reads associations alone, on the same terms as
- * groupRoleFromAssociations() above.
+ * Whether a roster carries at least one `admin` — the invariant every
+ * `_group` write must leave standing. Asked of the roster the write would
+ * *produce*, which lets an admin leave while another remains and refuses
+ * the last. Reads associations alone, like groupRoleFromAssociations().
  */
 export declare function hasGroupAdmin(associations: DataAssociation[] | undefined): boolean;
-/**
- * Whether one association is an `admin` roster entry. The `entity` target is
- * what makes it one — a `record` target carrying the same label confers
- * nothing, so it must not count toward the invariant either.
- * See docs/spec/data-model.md § Relationship targets.
- */
-export declare function isGroupAdminAssociation(association: Association): boolean;
+/** Bootstraps a `_group` record's first admin at create time. */
+export declare function stampGroupAdmin(associations: DataAssociation[] | undefined, creator: EntityId): DataAssociation[];
 /**
  * Whether a request is the stack owner acting alone — the tier behind every
  * unconditional owner authority. Being the owner is never sufficient on its

package/dist/access.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"access.d.ts","sourceRoot":"","sources":["../src/access.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EACV,WAAW,EACX,oBAAoB,EACpB,eAAe,EACf,QAAQ,EACR,SAAS,EAET,QAAQ,EACR,WAAW,EACZ,MAAM,YAAY,CAAC;AAGpB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC;AAE1C;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,EAAE,EAAE,QAAQ,KAAK,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;AAE3E;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,WAAW,EACnB,eAAe,EAAE,QAAQ,GAAG,IAAI,EAChC,aAAa,EAAE,QAAQ,GAAG,IAAI,EAC9B,IAAI,EAAE,UAAU,EAChB,aAAa,EAAE,cAAc,GAC5B,OAAO,CAAC,OAAO,CAAC,CAyBlB;AAyCD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,oBAAoB,EAAE,GAAG,SAAS,EAC/C,IAAI,SAAgB,GACnB,eAAe,EAAE,CAanB;AAaD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAE1D;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CACvC,YAAY,EAAE,eAAe,EAAE,GAAG,SAAS,EAC3C,QAAQ,EAAE,QAAQ,GACjB,SAAS,GAAG,IAAI,CASlB;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,YAAY,EAAE,eAAe,EAAE,GAAG,SAAS,GAAG,OAAO,CAElF;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAMzE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE;IAAE,SAAS,EAAE,QAAQ,GAAG,IAAI,CAAC;IAAC,WAAW,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAA;CAAE,EACpE,aAAa,EAAE,QAAQ,GACtB,OAAO,CAGT"}
+{"version":3,"file":"access.d.ts","sourceRoot":"","sources":["../src/access.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAEV,oBAAoB,EACpB,eAAe,EACf,QAAQ,EAER,SAAS,EACT,OAAO,EACP,QAAQ,EAER,WAAW,EACZ,MAAM,kBAAkB,CAAC;AAG1B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD,oEAAoE;AACpE,MAAM,MAAM,cAAc,GAAG,CAAC,EAAE,EAAE,QAAQ,KAAK,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;AAE3E;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,CAAC,WAAW,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC;AAE1E;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,oBAAoB,EAAE,CAKvE;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE;IAAE,KAAK,EAAE,WAAW,CAAC;IAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAAE,GACjD,OAAO,CAAC,OAAO,CAAC,CAelB;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,oBAAoB,EAAE,GAAG,SAAS,EAC/C,IAAI,SAAgB,GACnB,eAAe,EAAE,CAcnB;AAED,wEAAwE;AACxE,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,EAAE,QAAQ,EAAE,SAAS,GAAG,OAAO,CAElF;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAE1D;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,YAAY,EAAE,eAAe,EAAE,GAAG,SAAS,EAC3C,QAAQ,EAAE,QAAQ,GACjB,SAAS,GAAG,IAAI,CASlB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,YAAY,EAAE,eAAe,EAAE,GAAG,SAAS,GAAG,OAAO,CAElF;AAkBD,iEAAiE;AACjE,wBAAgB,eAAe,CAC7B,YAAY,EAAE,eAAe,EAAE,GAAG,SAAS,EAC3C,OAAO,EAAE,QAAQ,GAChB,eAAe,EAAE,CAUnB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE;IAAE,SAAS,EAAE,QAAQ,GAAG,IAAI,CAAC;IAAC,WAAW,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAA;CAAE,EACpE,aAAa,EAAE,QAAQ,GACtB,OAAO,CAGT"}

package/dist/access.js

@@ -1,137 +1,94 @@
 /**
  * Stack — Permission Resolution
  * -------------------------------------------------------
- * Implements the Permissions model from the spec: a pure predicate over a
- * Record's `permissions` field, with no dependency on a transport layer or
- * storage backend. Used by ScopedStack (see scoped-stack.ts) to enforce
- * access control; exported standalone for callers that want the raw
- * predicate.
+ * The record-level permission rules, with no dependency on a transport
+ * layer or storage backend: how a grantee reaches an entity, the
+ * write-implies-read invariant, and the `_group` roster rules both layers
+ * resolve against, plus the owner-acting-alone tier. What a requester may
+ * do is a reach per verb, which scoped-stack/authority.ts builds from these.
  *
  * A permission set is read as data throughout, never as the type: it can
  * arrive from an import or a foreign server, where no compiler has seen
  * it. Every tier is affirmative, so an element read past its own kind —
  * or carrying no kind at all — confers nothing.
  */
-import { SYSTEM_TYPES } from './types.js';
-import { granteeEqual } from './record-changes.js';
+import { SYSTEM_TYPES } from './types/index.js';
+import { associationKey } from './associations/identity.js';
 import { baseIdOf } from './schema.js';
 /**
- * Whether an entity has read or write access to a Record.
- *
- * The entity here is the **subject** — record-level permissions are written
- * about who data is for, never about the software that carried the request.
- * A delegated app's own authority is a separate question, asked of the
- * principal. See docs/spec/access-control.md § Record-level permissions and
- * § Delegation: principal and subject.
- */
-export async function checkAccess(record, subjectEntityId, ownerEntityId, mode, resolveRecord) {
-    if (subjectEntityId && subjectEntityId === ownerEntityId)
-        return true;
-    const perms = record.permissions;
-    // No permissions = private.
-    if (!perms || perms.length === 0)
-        return false;
-    for (const p of perms) {
-        if (p?.kind === 'anyone') {
-            if (mode === 'read' && isWorldRead(p))
-                return true;
-            continue;
-        }
-        if (p?.kind !== 'permission' || !p.grantee)
-            continue;
-        if (p.label !== mode)
-            continue;
-        // The write bit is inert without read alongside it: the mutate surface
-        // hands back the record it wrote and opens its whole history, so a
-        // write element standing alone would withhold nothing. Refused at the
-        // write by validatePermissions() and again here.
-        // See docs/spec/access-control.md § Write implies read.
-        if (mode === 'write' && !holdsRead(perms, p.grantee))
-            continue;
-        if (await granteeCovers(p.grantee, subjectEntityId, resolveRecord))
-            return true;
-    }
-    return false;
-}
-/**
- * Whether the set conveys read to this grantee — a `read` of its own, or
- * an `anyone` that already reaches everyone. Demanding a second, redundant
- * `read` beside the write would refuse a set that withholds nothing;
- * revoking the `anyone` is what the invariant catches instead.
+ * The elements beside which a `write` naming `grantee` carries its bit: its
+ * own `read`, or an `anyone`, which reaches the grantee already. The one
+ * statement of write-implies-read — validation and every reach ask it.
  * See docs/spec/access-control.md § Write implies read.
  */
-function holdsRead(permissions, grantee) {
-    return permissions.some((p) => p?.kind === 'anyone'
-        ? isWorldRead(p)
-        : p?.kind === 'permission' && p.label === 'read' && granteeEqual(p.grantee, grantee));
+export function readCompanions(grantee) {
+    return [
+        { kind: 'permission', label: 'read', grantee },
+        { kind: 'anyone', label: 'read' },
+    ];
 }
 /**
- * Whether an `anyone` element reaches the world. `read` is the only bit it
- * can carry, so one labelled otherwise names no reach — refused at the
- * write by validateAssociation() and read as nothing here.
+ * Whether a grantee reaches `entityId`, for both layers alike. Read as data,
+ * so an arm the write would refuse confers nothing; `member` is the wider
+ * role. See docs/spec/access-control.md § Refused at the write, and again at evaluation.
  */
-function isWorldRead(association) {
-    return association.label === 'read';
-}
-/**
- * Whether a grantee reaches this subject. `role: 'member'` is the wider
- * set — an admin satisfies it — and `role: 'admin'` the narrower.
- */
-async function granteeCovers(grantee, subjectEntityId, resolveRecord) {
-    if (!subjectEntityId)
+export async function granteeReaches(grantee, entityId, opts) {
+    if (!grantee || typeof grantee !== 'object')
         return false;
-    if (grantee.kind === 'entity')
-        return grantee.entityId === subjectEntityId;
-    const role = await resolveGroupRole(grantee.groupId, subjectEntityId, resolveRecord);
-    return grantee.role === 'admin' ? role === 'admin' : role !== null;
+    const g = grantee;
+    switch (g.kind) {
+        case 'entity':
+            return !!g.entityId && g.entityId === entityId;
+        case 'group': {
+            if (opts.allowGroup === false || !g.groupId)
+                return false;
+            if (g.role !== 'member' && g.role !== 'admin')
+                return false;
+            const held = (await opts.roles()).get(g.groupId) ?? null;
+            return roleSatisfies(held, g.role);
+        }
+        default:
+            return false;
+    }
 }
 /**
- * Rejects a permission set where some grantee holds `write` with no `read`
- * beside it — the shape checkAccess() refuses to honor. A cross-element
+ * Rejects a permission set where some `write` stands without a
+ * readCompanions() element, which no reach would honor. A cross-element
  * invariant, so it is asked of the set the write would *produce*, the same
  * way hasGroupAdmin() reads its post-state below.
  * See docs/spec/access-control.md § Write implies read.
  */
 export function validatePermissions(permissions, path = 'permissions') {
     const list = permissions ?? [];
+    const held = new Set(list.map(associationKey));
     const errors = [];
     list.forEach((p, i) => {
         if (p?.kind !== 'permission' || p.label !== 'write')
             return;
-        if (holdsRead(list, p.grantee))
+        if (readCompanions(p.grantee).some((c) => held.has(associationKey(c))))
             return;
         errors.push({
             path: `${path}[${i}]`,
-            message: 'write requires read: a write-holder reaches the record and its history through the mutate surface, so a `write` element with no `read` for the same grantee withholds nothing. Grant `read` and `write` together: grantAccess(id, [read, write])',
+            message: 'write requires read: a write-holder reaches the record and its history through the mutate surface, so a `write` element with no `read` for the same grantee withholds nothing. Grant `read` and `write` together in one editAccess() or setAccess() call',
         });
     });
     return errors;
 }
-/** Resolve a role from the `_group` Record a permission's `groupId` names. */
-async function resolveGroupRole(groupRecordId, entityId, resolveRecord) {
-    const group = await resolveRecord(groupRecordId);
-    if (!group || !carriesRoster(group))
-        return null;
-    return groupRoleFromAssociations(group.associations, entityId);
+/** Whether a held role meets a grantee's: an admin is also a member. */
+export function roleSatisfies(held, required) {
+    return required === 'admin' ? held === 'admin' : held !== null;
 }
 /**
- * Whether a Record is a roster anything may resolve against, on two counts.
- * The family check: without it an app modelling its own `member` links
- * would turn every record it points a permission at into an ACL. The
- * tombstone check: deleting a Group is how a Group is withdrawn. Shared
- * with the grant path, so the two layers cannot disagree about which Groups
- * still reach anyone. See docs/spec/identity.md § Group.
+ * Whether a Record is a `_group`, in any of its type versions — the family
+ * whose roster rules apply.
  */
-export function carriesRoster(record) {
-    return baseIdOf(record.typeId) === SYSTEM_TYPES.GROUP && !record.deletedAt;
+export function isGroupRecord(record) {
+    return baseIdOf(record.typeId) === SYSTEM_TYPES.GROUP;
 }
 /**
- * An entity's role within a `_group` Record's roster. `admin`
- * short-circuits, so a matching admin association wins regardless of order.
- *
- * Reads associations alone and cannot tell whose they are: callers pass
- * carriesRoster() first, or an app's own `member` relationships become a
- * roster.
+ * An entity's role on a `_group` roster; a matching `admin` wins regardless
+ * of order. Reads associations alone and cannot tell whose they are, so
+ * callers ask it of a live `_group` only — see loadRosterRoles().
  */
 export function groupRoleFromAssociations(associations, entityId) {
     let role = null;
@@ -146,13 +103,10 @@ export function groupRoleFromAssociations(associations, entityId) {
     return role;
 }
 /**
- * Whether a roster carries at least one `admin` — the invariant every write
- * to a `_group` Record must leave standing. Asked of the roster a write
- * would *produce*, never the one it started from: that is what lets an
- * admin remove themselves while another remains, and refuses the same
- * removal when they are the last, without either case naming who is going.
- * Reads associations alone, on the same terms as
- * groupRoleFromAssociations() above.
+ * Whether a roster carries at least one `admin` — the invariant every
+ * `_group` write must leave standing. Asked of the roster the write would
+ * *produce*, which lets an admin leave while another remains and refuses
+ * the last. Reads associations alone, like groupRoleFromAssociations().
  */
 export function hasGroupAdmin(associations) {
     return (associations ?? []).some(isGroupAdminAssociation);
@@ -163,11 +117,22 @@ export function hasGroupAdmin(associations) {
  * nothing, so it must not count toward the invariant either.
  * See docs/spec/data-model.md § Relationship targets.
  */
-export function isGroupAdminAssociation(association) {
+function isGroupAdminAssociation(association) {
     return (association.kind === 'relationship' &&
         association.label === 'admin' &&
         association.target.kind === 'entity');
 }
+/** Bootstraps a `_group` record's first admin at create time. */
+export function stampGroupAdmin(associations, creator) {
+    const list = associations ?? [];
+    const alreadyAdmin = list.some((a) => isGroupAdminAssociation(a) && a.target.entityId === creator);
+    if (alreadyAdmin)
+        return list;
+    return [
+        ...list,
+        { kind: 'relationship', label: 'admin', target: { kind: 'entity', entityId: creator } },
+    ];
+}
 /**
  * Whether a request is the stack owner acting alone — the tier behind every
  * unconditional owner authority. Being the owner is never sufficient on its