From 6fb20b3a0ffc66be8ac7622ed22bbcdd1131618f Mon Sep 17 00:00:00 2001
From: Jen Garcia <jen@haverstack.com>
Date: Sun, 20 Sep 2026 07:32:44 -0400
Subject: [PATCH 1/3] =?UTF-8?q?feat:=20adopt=20core=200.37=20=E2=80=94=20p?=
 =?UTF-8?q?ermissions=20as=20associations,=20and=20the=20no-bump=20tier?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Record permissions are associations now, and six operations no longer move
a version. Both reach the command surface, so this is one change rather
than two.

**The ACL is per-element.** `Permission[]` is replaced by two association
kinds — `permission`, whose bit is its label and whose grantee carries a
required role, and `anyone` for world-read spelled affirmatively. `perm`
calls `grantAccess()`/`revokeAccess()` instead of reading the whole list,
editing an entry and writing it back: that read-modify-write dropped
whatever a second admin granted between the read and the write, which is
exactly the case a sharing command has to survive.

The flags follow the model rather than the old shape. `--public` becomes
`--anyone`, which carries read alone, so `--write` beside it is refused
here rather than written and bounced by core. `--group` requires `--role`,
because member and admin name two different sets of people and neither is
a safe default. `perm add --read --write` grants read first and `perm rm`
withdraws write first — the one ordering that satisfies core's rule that
no write lands in a set whose grantee cannot read it; the rule itself is
left to core's message rather than re-derived. `perm ls` is new: the ACL
was otherwise only legible in `show --json`.

`grant`'s target is core's required grantee union — `--default` becomes
`--authenticated`, a DID-holder tier distinct from `--anyone`'s anonymous
reach, and `--group` takes `--role`. `grant ls` accepts the same flags as
a query, widened by the listing-only `--role any`, and `grant rm` reports
a count now that `revoke()` returns what it withdrew.

**Associating, sharing, moving and (un)listing bump nothing.** `tag`,
`link`, `perm` and `attach` stop printing a version that did not move and
compare the record before and after instead, so a repeat says `already
tagged` rather than claiming a write. `commit` reports the version its own
`mutate()` produced; the tag and attachment reconcile that follow cannot
move it. Naming `contentPatch` alongside `parentId` is what keeps a move
under `ifVersion`, which is now pinned from both sides.

Also: `rm --hard` reports the files the purged record referenced, since
destroying the record destroys the only rows naming them, and `attach add`
records an `attachmentRecordId` so a filename resolves to the upload that
reference came from.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .changeset/adopt-core-0-37.md    |  43 +++++
 README.md                        |  11 +-
 docs/design.md                   | 131 ++++++++-----
 package.json                     |  10 +-
 pnpm-lock.yaml                   |  94 ++++-----
 pnpm-workspace.yaml              |  16 +-
 scripts/smoke.mjs                |  14 ++
 src/cli.ts                       | 126 +++++++-----
 src/commands/access.ts           | 320 +++++++++++++++++++------------
 src/commands/associations.ts     |  49 +++--
 src/commands/attach.ts           |  18 +-
 src/commands/edit.ts             |  30 +--
 src/commands/records.ts          |  14 +-
 src/index.ts                     |   9 +-
 tests/access.test.ts             | 180 +++++++++++++----
 tests/associations.test.ts       |  22 ++-
 tests/edit-commit.test.ts        |  38 +++-
 tests/record-format.test.ts      |   4 +-
 tests/server-integration.test.ts |  12 +-
 19 files changed, 775 insertions(+), 366 deletions(-)
 create mode 100644 .changeset/adopt-core-0-37.md

diff --git a/.changeset/adopt-core-0-37.md b/.changeset/adopt-core-0-37.md
new file mode 100644
index 0000000..b50c47b
--- /dev/null
+++ b/.changeset/adopt-core-0-37.md
@@ -0,0 +1,43 @@
+---
+'@haverstack/cli': minor
+---
+
+Adopt core 0.37: record permissions are associations, and six operations no longer bump a version
+
+**`Permission[]` is gone.** A record's ACL is two association kinds over the same table —
+`{ kind: 'permission', label: 'read' | 'write', grantee }` and `{ kind: 'anyone', label:
+'read' }` — with `grantAccess()` / `revokeAccess()` adding and withdrawing exactly one
+element. `hstack perm` follows: it no longer reads the whole list, edits an entry and
+writes the array back, a read-modify-write that silently discarded whatever a second
+admin granted in between.
+
+The flags move with the model. `--public` becomes `--anyone`, which carries `read` alone
+(`--write` beside it is refused rather than written and bounced). `--group` now requires
+`--role member` or `--role admin`, because member and admin are two different elements and
+neither is a safe guess. `perm rm` naming neither `--read` nor `--write` withdraws the
+target's access entirely; naming one withdraws just that one. `perm add --read --write`
+grants read first and `perm rm` withdraws write first, which is the one ordering that
+satisfies core's rule that no write lands in a set whose grantee cannot read it. New:
+`hstack perm ls <id>` prints the whole ACL.
+
+`hstack grant`'s target is core's required `GrantGrantee` union: `--default` becomes
+`--authenticated` (any entity holding a DID — a tier below `--anyone`, which also reaches
+anonymous requesters), and `--group` takes `--role`. `grant ls` accepts the same flags as
+a query, widened by the listing-only `--role any`, and `grant rm` reports how many grants
+it withdrew now that `revoke()` returns them.
+
+**`associate`, `dissociate`, `permissions`, `reparent`, `unlist` and `list` are no-bump**:
+they leave `version` and `updatedAt` exactly where they stand. `tag`, `link`, `perm` and
+`attach` therefore stop printing a version that did not move, and compare the record
+before and after instead — a repeat now says `already tagged` rather than claiming a write
+that did not happen. `hstack commit` reports the version its own `mutate()` produced,
+since the tag and attachment reconcile that follow cannot move it.
+
+Also: `hstack rm --hard` reports the files the purged record referenced (core's
+`delete()` returns them, because destroying the record destroys the only rows naming
+them), and `hstack attach add` records an `attachmentRecordId` so a filename resolves to
+the upload that reference came from.
+
+**Not backwards compatible.** The SQLite schema is create-if-missing with no migrations,
+so a database written before core 0.37 keeps its old tables and fails on the first
+permission write. Existing stacks must be recreated.
diff --git a/README.md b/README.md
index a79b12b..4aab6c8 100644
--- a/README.md
+++ b/README.md
@@ -53,12 +53,19 @@ hstack show <id>                   # render one record
 hstack rm <id>                     # soft-delete; hstack restore <id> to undo
 hstack tag add <id> <label>        # tag a record outside an edit session
 hstack link add <id> --label <l> --to-record <otherId>
-hstack perm add <id> --entity <did> --read
-hstack grant add <typeId> --entity <did> read-any
+hstack perm add <id> --entity <did> --read --write   # or --anyone, or --group <id> --role member
+hstack perm ls <id>                # who reaches this record
+hstack grant add <typeId> --entity <did> read-any    # or --authenticated, or --group + --role
 hstack attach add <id> --label <l> --file <path>
 hstack types define <schema.json>  # register { id, name, schema, migratesFrom? }
 ```
 
+Tagging, linking, attaching, sharing and moving a record are **no-bump** writes in core:
+they leave `version` and `updatedAt` where they stand, so these commands report what the
+record now says rather than a version number that did not move. Record permissions are
+associations — one element per bit per grantee — so `perm add`/`perm rm` write exactly the
+element you name and never restate the rest of the ACL over someone else's change.
+
 Every read command takes `--json` and loops the result cursor to exhaustion (or an
 explicit `--limit`), so it's a client to build on, not just one to sit in front of:
 
diff --git a/docs/design.md b/docs/design.md
index ca34b4d..449dd68 100644
--- a/docs/design.md
+++ b/docs/design.md
@@ -156,7 +156,7 @@ Local files need no identity: an unscoped `Stack` names no requester. `hstack st
 An edit in progress is a **lock plus a working directory**. `hstack new` / `hstack edit`
 materialize a record, open your editor on it, and _exit_. You edit — and save — as
 freely as you like. `hstack commit` validates the working copy and writes it back as one
-`update()`. `hstack discard` throws it away.
+`mutate()`. `hstack discard` throws it away.
 
 ### Why stateful, not a synchronous editor spawn
 
@@ -166,7 +166,7 @@ losing everything if the editor or terminal dies. The stateful model:
 
 - **makes frequent saves free.** The working copy is a plain file. Saving it fifty times
   while drafting produces exactly zero version-history entries; only `hstack commit` calls
-  `Stack.update()`.
+  `Stack.mutate()`.
 - **survives a dead editor.** The working copy is on disk under XDG state; reopen it, or
   `hstack commit` it, whenever.
 - **lets you consult the stack mid-edit.** `hstack show <other-id>` in another terminal
@@ -221,19 +221,37 @@ you wanted it open alongside. The editor is `config.editor`, else `$VISUAL`, els
 `$EDITOR`; with none set, `new`/`edit` just print the file path to open.
 
 **`parentId` moves with the record.** Core's `mutate()` carries a content patch and a
-`parentId` in one fenced, one-version write, so editing the `parentId` line and
-committing moves the record — core checks the destination exists and refuses a cycle,
-surfaced as an ordinary kept-copy failure if either is wrong. A root record's rendered
+`parentId` in one fenced write, so editing the `parentId` line and committing moves the
+record — core checks the destination exists and refuses a cycle, surfaced as an ordinary
+kept-copy failure if either is wrong. A move on its own is a **no-bump** write (below);
+naming `contentPatch` alongside it is what puts the whole call back under `ifVersion`. A root record's rendered
 buffer has no live `parentId` line to edit, so `hstack edit` always leaves a commented
 `# parentId:` hint in its place — otherwise moving a record would be a capability with no
 way to discover it from the file alone. Re-uploading files dropped into the working
 directory is Phase 6.
 
+### What does and does not bump a version
+
+Core (0.33–0.35) settled six operations as **no-bump**: `associate`, `dissociate`,
+`permissions`, `reparent`, `unlist` and `list`. They leave `version` _and_ `updatedAt`
+exactly where they stand, take no snapshot, and are not fenced by `ifVersion` — a
+set-add/remove composes correctly whatever order two writers land in, so there was never
+a race for a precondition to guard. Only a content patch and the whole-record verbs bump.
+
+Two consequences the CLI lives with:
+
+- **`tag` / `link` / `perm` / `attach` report no version.** There is none to report, and
+  printing the unchanged one would read as "this wrote at v4" rather than "v4 is where
+  this record still is". They compare the record before and after instead, so a repeat
+  says `already tagged` rather than claiming a write that did not happen.
+- **`hstack commit` reports the version its own `mutate()` produced**, not a re-read after
+  the tag and attachment reconcile. Those reconcile passes cannot move it.
+
 ### Optimistic concurrency
 
 `hstack edit` records the record's `version` as `baseVersion`. `hstack commit` passes it as
 `ifVersion`. If the record moved on the stack while you were editing — likelier here than
-elsewhere because the window is a whole writing session — `update()` throws
+elsewhere because the window is a whole writing session — `mutate()` throws
 `StackVersionConflictError { expectedVersion, actualVersion }`. The commit fails, the
 working copy is left exactly as it is, and `hstack` prints the conflict plus how to see what
 changed (`hstack show <id> --history`). Resolving it is manual: re-`hstack edit` a fresh copy
@@ -272,7 +290,8 @@ _readonly:
   associations:            # shown for context; edited via `hstack link` / `hstack tag`
     - { kind: relationship, label: blocks, target: { scope: record, recordId: 01h… } }
   permissions:             # shown for context; edited via `hstack perm`
-    - { access: entity, entityId: did:key:z6Mk…, read: true, write: false }
+    - { kind: permission, label: read, grantee: { scope: entity, entityId: did:key:z6Mk… } }
+    - { kind: anyone, label: read }
 ---
 Body text goes here — the schema's one `text` field.
 ```
@@ -362,10 +381,13 @@ hstack tag  add|rm <id> <label>
 hstack link add|rm <id> --label <l> ( --to-record <id> [--stack-url <u>]
                                      | --to-entity <did>
                                      | --to-external <ns> --external-id <id> )
-hstack perm add|rm <id> ( --public | --entity <did> | --group <id> [--role admin] )
+hstack perm add|rm <id> ( --anyone | --entity <did> | --group <id> --role <member|admin> )
                          [--read] [--write]
-hstack grant add|rm <typeId> ( --entity <did> | --group <id> | --default ) <action>...
-hstack grant ls [--type <typeId>]
+hstack perm ls <id>
+hstack grant add|rm <typeId> ( --entity <did> | --group <id> --role <member|admin>
+                              | --authenticated ) <action>...
+hstack grant ls [--type <typeId>] [--entity <did> | --group <id> [--role <r|any>]
+                                   | --authenticated]
 ```
 
 `link` mirrors core's `RelationshipTarget` union exactly — a target names one identifier
@@ -375,23 +397,40 @@ same target flags `link add` did. Typing that union as YAML in a text file is pr
 what a text editor is bad at; a command with validation and, later, tab-completion is
 better even before any picker exists.
 
-**`perm`** edits one entry of the record's whole `Permission[]` and writes the array back
-via `mutate()` (there is no single-permission verb any more — `setPermissions()` was
-folded into `mutate()`). An entry's identity is `public`, `entity:<did>`, or
-`group:<id>:<role|member>` — an admin-only and a general-member grant on the same group
-are different entries. `add` **merges** access bits into an existing entry (`--write`
-after `--read` produces read **and** write, never resets what was already granted);
-`rm` **narrows**: naming `--write` alone clears just that bit, and an entry left with
-neither bit is dropped. `rm` with no `--read`/`--write` (or `--public`) drops the entry
-outright. Core itself enforces `write` requires `read` in the same entry — the CLI does
-not duplicate that check, it lets core's own message teach it.
+**`perm` writes one element at a time.** Record permissions are associations: the ACL is
+two kinds over the same table — `{ kind: 'permission', label: 'read'|'write', grantee }`,
+whose grantee is `{ scope: 'entity', entityId }` or `{ scope: 'group', groupId, role }`,
+plus `{ kind: 'anyone', label: 'read' }` for world-read spelled affirmatively. Core's
+`grantAccess(id, el)` / `revokeAccess(id, el)` add and withdraw exactly one, and `perm`
+calls those rather than the `permissions` change-set key. The key replaces the whole set,
+so between the read it would need and the write, whatever a second admin granted is gone;
+a per-element write is the spelling that survives two people sharing one record at once.
+
+An element's identity is its bit plus its grantee, and `role` is **required** on a group —
+member is the wider set, admin the narrower, and the two are different elements, so
+`--group` without `--role` is refused rather than guessed at. `--anyone` carries `read`
+and nothing else; `--write` beside it is refused rather than written and then bounced by
+core. `perm add --read --write` grants read first and `perm rm` withdraws write first,
+because core's cross-element invariant is that **no write lands in a set whose grantee
+cannot read it** — the CLI does not re-derive that rule, it just does not fight the one
+ordering that satisfies it, and lets core's message teach the rest. `perm rm` naming
+neither bit withdraws the target's access entirely; naming one withdraws just that one.
+`perm ls` prints the whole ACL, which is otherwise only visible in `show --json` and the
+`_readonly` block.
 
 `grant` actions are core's `GrantAction` set — `create`, `read-own`, `read-any`,
-`update-own`, `update-any`, `delete-own`, `delete-any`. Core enforces the dependency
-(a `-any`/`-own` mutate action needs a matching-scope read action in the same grant) and
+`update-own`, `update-any`, `delete-own`, `delete-any`. Its grantee is core's
+`GrantGrantee` union, one required arm: `--entity <did>`, `--group <id> --role <r>`, or
+`--authenticated` (any entity holding a DID — the tier below `--anyone`, which also
+reaches anonymous requesters; the two never share a word). `grant ls` takes the same flags
+as a query, widened by the listing-only `--role any`; an `--entity` listing answers
+_coverage_ (grants naming them, their groups, and every authenticated grant), so it is not
+a preview of what `grant rm` would withdraw. Core enforces the action dependency (a
+`-any`/`-own` mutate action needs a matching-scope read action in the same grant) and
 names the missing one in its own error; the CLI does not re-derive that rule client-side,
-since a copy could disagree with the answer that actually governs the write. Grants are
-`_grant` records under the hood and work through either backend.
+since a copy could disagree with the answer that actually governs the write. `revoke()`
+returns what it withdrew, so `grant rm` reports a count rather than a silent success.
+Grants are `_grant` records under the hood and work through either backend.
 
 ### Attachments — both ways
 
@@ -441,28 +480,28 @@ gives, not to invent a more specific one the server never promised.
 
 ## Command surface
 
-| Command                                                                      | Purpose                                                                            |
-| ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
-| `hstack stack add <name> (--url <u> [--expected-owner <did>] \| --path <p>)` | Create a profile; generate + store a key for a server profile                      |
-| `hstack stack ls` / `hstack stack use <name>` / `hstack stack rm <name>`     | Manage profiles and the default                                                    |
-| `hstack types`                                                               | List registered types (id, name, schemaHash)                                       |
-| `hstack types show <typeId>`                                                 | Print a type's schema                                                              |
-| `hstack types define <schema.json>`                                          | Register a type from `{ id, name, schema, migratesFrom? }`                         |
-| `hstack ls <typeId> \| --base <baseId>`                                      | List records of a type — `--parent <id>`/`--root`, `--tag <l>`…, `--limit N`       |
-| `hstack show <id>`                                                           | Print a record — `--history` for version history                                   |
-| `hstack new <typeId>`                                                        | Scaffold and open a new record — `--parent`, `--id`, `--minimal`, `--body <field>` |
-| `hstack edit <id>`                                                           | Open an existing record — `--all`, `--body <field>`, `-c`/`--commit`               |
-| `hstack status`                                                              | List open edits for the active profile                                             |
-| `hstack commit [<id>]`                                                       | Validate and write back — `--force` to drop the `ifVersion` fence                  |
-| `hstack discard [<id>]`                                                      | Abandon a working copy — `--stale` to sweep stale locks                            |
-| `hstack rm <id>`                                                             | Soft-delete — `--hard` to purge (owner-only on a server)                           |
-| `hstack restore <id>`                                                        | Undelete                                                                           |
-| `hstack versions <id>`                                                       | Version history                                                                    |
-| `hstack tag add\|rm <id> <label>`                                            | Add or remove a tag                                                                |
-| `hstack link add\|rm <id> --label <l> (...)`                                 | Add or remove a relationship (above)                                               |
-| `hstack perm add\|rm <id> (...)`                                             | Grant, merge, narrow, or drop a record permission (above)                          |
-| `hstack grant add\|rm <typeId> (...) <action>...` / `hstack grant ls`        | Type-level grants (above)                                                          |
-| `hstack attach add\|rm <id> --label <l> (...)`                               | Attach or detach a file outside an edit session (above)                            |
+| Command                                                                      | Purpose                                                                                |
+| ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `hstack stack add <name> (--url <u> [--expected-owner <did>] \| --path <p>)` | Create a profile; generate + store a key for a server profile                          |
+| `hstack stack ls` / `hstack stack use <name>` / `hstack stack rm <name>`     | Manage profiles and the default                                                        |
+| `hstack types`                                                               | List registered types (id, name, schemaHash)                                           |
+| `hstack types show <typeId>`                                                 | Print a type's schema                                                                  |
+| `hstack types define <schema.json>`                                          | Register a type from `{ id, name, schema, migratesFrom? }`                             |
+| `hstack ls <typeId> \| --base <baseId>`                                      | List records of a type — `--parent <id>`/`--root`, `--tag <l>`…, `--limit N`           |
+| `hstack show <id>`                                                           | Print a record — `--history` for version history                                       |
+| `hstack new <typeId>`                                                        | Scaffold and open a new record — `--parent`, `--id`, `--minimal`, `--body <field>`     |
+| `hstack edit <id>`                                                           | Open an existing record — `--all`, `--body <field>`, `-c`/`--commit`                   |
+| `hstack status`                                                              | List open edits for the active profile                                                 |
+| `hstack commit [<id>]`                                                       | Validate and write back — `--force` to drop the `ifVersion` fence                      |
+| `hstack discard [<id>]`                                                      | Abandon a working copy — `--stale` to sweep stale locks                                |
+| `hstack rm <id>`                                                             | Soft-delete — `--hard` to purge (owner-only on a server), reporting what it referenced |
+| `hstack restore <id>`                                                        | Undelete                                                                               |
+| `hstack versions <id>`                                                       | Version history                                                                        |
+| `hstack tag add\|rm <id> <label>`                                            | Add or remove a tag                                                                    |
+| `hstack link add\|rm <id> --label <l> (...)`                                 | Add or remove a relationship (above)                                                   |
+| `hstack perm add\|rm <id> (...)` / `hstack perm ls <id>`                     | Grant or withdraw one element of a record's ACL; list the whole of it (above)          |
+| `hstack grant add\|rm <typeId> (...) <action>...` / `hstack grant ls`        | Type-level grants (above)                                                              |
+| `hstack attach add\|rm <id> --label <l> (...)`                               | Attach or detach a file outside an edit session (above)                                |
 
 Every read command takes `--json`. Every listing command **loops the cursor to
 exhaustion** or honours an explicit `--limit` — `cursor === null` is the only
diff --git a/package.json b/package.json
index c8374fe..9c30372 100644
--- a/package.json
+++ b/package.json
@@ -48,9 +48,9 @@
     "release": "pnpm run build && changeset publish"
   },
   "dependencies": {
-    "@haverstack/adapter-api": "^0.31.0",
-    "@haverstack/adapter-local": "^0.31.0",
-    "@haverstack/core": "^0.32.0",
+    "@haverstack/adapter-api": "^0.36.0",
+    "@haverstack/adapter-local": "^0.36.0",
+    "@haverstack/core": "^0.37.0",
     "commander": "^15.0.0",
     "smol-toml": "^1.8.0",
     "yaml": "^2.9.0"
@@ -59,8 +59,8 @@
     "@changesets/changelog-github": "^1.0.1",
     "@changesets/cli": "^3.0.2",
     "@eslint/js": "^10.0.1",
-    "@haverstack/commons": "^0.26.0",
-    "@haverstack/server": "^0.9.1",
+    "@haverstack/commons": "^0.31.0",
+    "@haverstack/server": "^0.10.3",
     "@types/node": "^22.0.0",
     "eslint": "^10.2.1",
     "eslint-config-prettier": "^10.1.8",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 3b05df5..a3998f6 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -9,14 +9,14 @@ importers:
   .:
     dependencies:
       '@haverstack/adapter-api':
-        specifier: ^0.31.0
-        version: 0.31.0
+        specifier: ^0.36.0
+        version: 0.36.0
       '@haverstack/adapter-local':
-        specifier: ^0.31.0
-        version: 0.31.0
+        specifier: ^0.36.0
+        version: 0.36.0
       '@haverstack/core':
-        specifier: ^0.32.0
-        version: 0.32.0
+        specifier: ^0.37.0
+        version: 0.37.0
       commander:
         specifier: ^15.0.0
         version: 15.0.0
@@ -37,11 +37,11 @@ importers:
         specifier: ^10.0.1
         version: 10.0.1(eslint@10.10.0)
       '@haverstack/commons':
-        specifier: ^0.26.0
-        version: 0.26.0
+        specifier: ^0.31.0
+        version: 0.31.0
       '@haverstack/server':
-        specifier: ^0.9.1
-        version: 0.9.1
+        specifier: ^0.10.3
+        version: 0.10.3
       '@types/node':
         specifier: ^22.0.0
         version: 22.20.1
@@ -188,32 +188,32 @@ packages:
     resolution: {integrity: sha512-IkO+/KEUvwbVpiURZg+P7zF74z5Jxe0UgJxVni+RtoHQ6IZieXaO02kmadomap/q+l6bc/jdPGGqTjhuZnuz1Q==}
     engines: {node: ^20.19.0 || ^22.13.0 || >=24}
 
-  '@haverstack/adapter-api@0.31.0':
-    resolution: {integrity: sha512-f/2+7vWkirs+tHVpFZD3V73S/KChLvT/zxNujt/QEe6yNWhbfOCuVbFzw9GaGNo6eObbk5SdBZTlopMCQwiRng==}
+  '@haverstack/adapter-api@0.36.0':
+    resolution: {integrity: sha512-/lnUEi5dnyUXAcNnFJgx9NLZHXZCxNXLmx4arplYUbyg367PhlNzxmXJgMYtvMnrO0iQMpf8Y8czwW3lutQ1rg==}
 
-  '@haverstack/adapter-local@0.31.0':
-    resolution: {integrity: sha512-RwUadZDm9jRc++DPni8TPsLnYGI/7gY1kdn9b2kXoStkFb8IPnlFp6ZBApnKGUCVkqsoXqvX6ET6dOX2Lnn6kA==}
+  '@haverstack/adapter-local@0.36.0':
+    resolution: {integrity: sha512-i5srwErYEYNzF/50teht6XaPSOj54Skn/9x5kfO+Q3kHb9IB3alJEangOmMSMu9vqU/i4ifnurYEgJwB6xsV5Q==}
     engines: {node: '>=22.5.0'}
 
-  '@haverstack/blob-adapter-disk@0.30.0':
-    resolution: {integrity: sha512-uvPKY5GImj7RNslw/HESWXd4KvhVIKuJ6ZIIi7kXKGemoWuFDxBo0cuvJxo3Qvwfr9pElgb1lQfyXfRp0I4syQ==}
+  '@haverstack/blob-adapter-disk@0.35.0':
+    resolution: {integrity: sha512-JWLGq0i8bBHjP3bF0qI6yVySZPuS6Vj8td9nPLi80z24s42FYFkYnylcXDHzbLFGYfD9tXyGeJjt5BIN1yBZbw==}
 
-  '@haverstack/commons@0.26.0':
-    resolution: {integrity: sha512-BFOmiMDzV9NhOuSK4fZv47/ooBw+kDR9ME9sZoA2sdXD4pbt3Uek3kJE0JVtDkmLm7ZyK2frNg9lJp/+kGrAcg==}
+  '@haverstack/commons@0.31.0':
+    resolution: {integrity: sha512-OhKy1IzXtZ9r6tFVwZ3fQb2Q+SbwBUu08FliU5BhwJXku/cFwVNBaOnZcrx1TQiOJ0i04ftz+WXq+BIDGblYxQ==}
 
-  '@haverstack/core@0.32.0':
-    resolution: {integrity: sha512-IPd3I9vJg3334MO+QLynGN+hULT0GG3Fv5aqvilFajJp3T4pyL1jfAQuYCD4I3ZuVZMMdsIjvQjFVB3F9v+xMg==}
+  '@haverstack/core@0.37.0':
+    resolution: {integrity: sha512-tEFL/mVpVeOsQt0BDdtEJu8PQgy5DVoScCqEKID+DrAkvcspjcXrhUsGsCe87tWHbrYUWAMH8zW0UCSNw/ET0Q==}
 
-  '@haverstack/record-adapter-sqlite@0.24.0':
-    resolution: {integrity: sha512-8to2k+i9ydCp/O0+SdEB5Pz6YbD6sG5NRo7pXySU4tIuG/+9iiWQ4fHL0Ig0ErYcpvIA/LjM9vMTthzJqFiPow==}
+  '@haverstack/record-adapter-sqlite@0.29.0':
+    resolution: {integrity: sha512-r62aMZRZpW+B3bkQuZ0neJtNezHYgoBMR6s/kQnpoulJUMKViG6Lvs8bfW/MoVacZI1tWSDwtc8UsqAV6sblCA==}
     engines: {node: '>=22.5.0'}
 
-  '@haverstack/server@0.9.1':
-    resolution: {integrity: sha512-oId7EPhV412FxdKz9ni0VIoGsSfTZM/BhEU+a2Lbe2v3auYHEwrKtCzMBJCVyjL4Am8Iqu6nCktiO/NLvg409A==}
+  '@haverstack/server@0.10.3':
+    resolution: {integrity: sha512-Hdd/UE7MQohBnzufcY8eDwLDZ0G2jiKxZzsB9+yI9RlFzMEQPFOxIp9US146ymnHPNEm8uUMoyzQI7sGR+GvFw==}
     engines: {node: '>=22.9'}
 
-  '@haverstack/wire-types@0.31.0':
-    resolution: {integrity: sha512-XoTsIfP3u72h7VMF9fq5KQi9qOvYKm3yIONdf6eNcFAnLjTk+fzylGFOISUXlUctLFWuay3xXMEHN1IWGavB5g==}
+  '@haverstack/wire-types@0.36.0':
+    resolution: {integrity: sha512-alZbtPvyCtIrdJztDHlwUqhZu3Lns38EB6x31hBo8Ns/q2aQXTMcewlgLbLT0KdqJDZkpBJDnfTKTTHJ/aoENQ==}
 
   '@hono/node-server@2.1.1':
     resolution: {integrity: sha512-ELuehkj5VCBdgEw9zs+ivkKwyzzUCSQuE96YmiPvn1ECBoZCczbFXJLeEGMTYjphP6gydh4pHMqEYPVMYUVgQg==}
@@ -1336,45 +1336,45 @@ snapshots:
       '@eslint/core': 1.2.1
       levn: 0.4.1
 
-  '@haverstack/adapter-api@0.31.0':
+  '@haverstack/adapter-api@0.36.0':
     dependencies:
-      '@haverstack/core': 0.32.0
-      '@haverstack/wire-types': 0.31.0
+      '@haverstack/core': 0.37.0
+      '@haverstack/wire-types': 0.36.0
 
-  '@haverstack/adapter-local@0.31.0':
+  '@haverstack/adapter-local@0.36.0':
     dependencies:
-      '@haverstack/blob-adapter-disk': 0.30.0
-      '@haverstack/core': 0.32.0
-      '@haverstack/record-adapter-sqlite': 0.24.0
+      '@haverstack/blob-adapter-disk': 0.35.0
+      '@haverstack/core': 0.37.0
+      '@haverstack/record-adapter-sqlite': 0.29.0
 
-  '@haverstack/blob-adapter-disk@0.30.0':
+  '@haverstack/blob-adapter-disk@0.35.0':
     dependencies:
-      '@haverstack/core': 0.32.0
+      '@haverstack/core': 0.37.0
 
-  '@haverstack/commons@0.26.0':
+  '@haverstack/commons@0.31.0':
     dependencies:
-      '@haverstack/core': 0.32.0
+      '@haverstack/core': 0.37.0
 
-  '@haverstack/core@0.32.0': {}
+  '@haverstack/core@0.37.0': {}
 
-  '@haverstack/record-adapter-sqlite@0.24.0':
+  '@haverstack/record-adapter-sqlite@0.29.0':
     dependencies:
-      '@haverstack/core': 0.32.0
+      '@haverstack/core': 0.37.0
 
-  '@haverstack/server@0.9.1':
+  '@haverstack/server@0.10.3':
     dependencies:
-      '@haverstack/adapter-local': 0.31.0
-      '@haverstack/commons': 0.26.0
-      '@haverstack/core': 0.32.0
-      '@haverstack/wire-types': 0.31.0
+      '@haverstack/adapter-local': 0.36.0
+      '@haverstack/commons': 0.31.0
+      '@haverstack/core': 0.37.0
+      '@haverstack/wire-types': 0.36.0
       '@hono/node-server': 2.1.1(hono@4.13.7)
       hono: 4.13.7
       pino: 10.3.1
       pino-pretty: 13.1.3
 
-  '@haverstack/wire-types@0.31.0':
+  '@haverstack/wire-types@0.36.0':
     dependencies:
-      '@haverstack/core': 0.32.0
+      '@haverstack/core': 0.37.0
 
   '@hono/node-server@2.1.1(hono@4.13.7)':
     dependencies:
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 56c7a49..2c8abbc 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -3,11 +3,11 @@ allowBuilds:
 # @haverstack/* publish frequently enough to land inside a minimumReleaseAge
 # supply-chain policy window; excluded so a fresh release still installs.
 minimumReleaseAgeExclude:
-  - '@haverstack/adapter-api@0.30.0 || 0.31.0'
-  - '@haverstack/adapter-local@0.30.0 || 0.31.0'
-  - '@haverstack/blob-adapter-disk@0.29.0 || 0.30.0'
-  - '@haverstack/commons@0.25.0 || 0.26.0'
-  - '@haverstack/core@0.31.0 || 0.32.0'
-  - '@haverstack/record-adapter-sqlite@0.23.0 || 0.24.0'
-  - '@haverstack/wire-types@0.30.0 || 0.31.0'
-  - '@haverstack/server@0.9.0 || 0.9.1'
+  - '@haverstack/adapter-api@0.36.0'
+  - '@haverstack/adapter-local@0.36.0'
+  - '@haverstack/blob-adapter-disk@0.35.0'
+  - '@haverstack/commons@0.31.0'
+  - '@haverstack/core@0.37.0'
+  - '@haverstack/record-adapter-sqlite@0.29.0'
+  - '@haverstack/wire-types@0.36.0'
+  - '@haverstack/server@0.10.3'
diff --git a/scripts/smoke.mjs b/scripts/smoke.mjs
index 169fca1..59d8334 100644
--- a/scripts/smoke.mjs
+++ b/scripts/smoke.mjs
@@ -77,6 +77,20 @@ async function main() {
     '`tag add` associated the tag',
   );
 
+  run('perm', 'add', id, '--anyone');
+  const shared = JSON.parse(run('show', id, '--json'));
+  check(
+    (shared.permissions ?? []).some((p) => p.kind === 'anyone' && p.label === 'read'),
+    '`perm add --anyone` wrote an `anyone` element',
+  );
+  check(shared.version === tagged.version, 'tagging and sharing are no-bump writes');
+  check(run('perm', 'ls', id).includes('anyone'), '`perm ls` shows who reaches it');
+  run('perm', 'rm', id, '--anyone');
+  check(
+    (JSON.parse(run('show', id, '--json')).permissions ?? []).length === 0,
+    '`perm rm --anyone` withdrew it',
+  );
+
   run('rm', id);
   const afterRm = JSON.parse(run('ls', TYPE_ID, '--json'));
   check(afterRm.length === 0, '`rm` excludes the record from a default listing');
diff --git a/src/cli.ts b/src/cli.ts
index 00b90c0..2d55cce 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -40,7 +40,14 @@ import {
 } from './edit/editor.js';
 import { stackAdd, stackList, stackRemove, stackUse } from './commands/stack.js';
 import { tagAdd, tagRemove, linkAdd, linkRemove } from './commands/associations.js';
-import { permAdd, permRemove, grantAdd, grantRemove, grantList } from './commands/access.js';
+import {
+  permAdd,
+  permList,
+  permRemove,
+  grantAdd,
+  grantRemove,
+  grantList,
+} from './commands/access.js';
 import { attachAdd, attachRemove } from './commands/attach.js';
 
 const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')) as {
@@ -481,35 +488,38 @@ linkOptions(link.command('rm <id>'))
     }
   });
 
-const perm = program.command('perm').description('Add or remove a record permission');
+const perm = program
+  .command('perm')
+  .description('Add, remove, or list record permissions (read/write, per grantee)');
 
 function permOptions(cmd: Command) {
   return cmd
-    .option('--public', 'anyone may access it')
-    .option('--entity <did>', 'grant this identity access')
-    .option('--group <id>', 'grant this group access')
-    .option('--role <role>', 'restrict a --group entry to admins ("admin")')
-    .option('--read', 'grant read access')
-    .option('--write', 'grant write access');
+    .option('--anyone', 'reach the world, anonymous requesters included (read only)')
+    .option('--entity <did>', 'this identity')
+    .option('--group <id>', 'this group, at --role')
+    .option('--role <role>', 'which half of a --group: "member" (wider) or "admin"', permRole)
+    .option('--read', 'the read bit')
+    .option('--write', 'the write bit (core refuses a writer who cannot read)');
 }
 
 type PermCliOptions = {
-  public?: boolean;
+  anyone?: boolean;
   entity?: string;
   group?: string;
-  role?: string;
+  role?: 'member' | 'admin';
   read?: boolean;
   write?: boolean;
 };
 
+function permRole(value: string): 'member' | 'admin' {
+  if (value !== 'member' && value !== 'admin') {
+    throw new InvalidArgumentError('--role must be "member" or "admin"');
+  }
+  return value;
+}
+
 function permTarget(opts: PermCliOptions) {
-  if (opts.role && opts.role !== 'admin') throw new InvalidArgumentError('--role must be "admin"');
-  return {
-    public: opts.public,
-    entity: opts.entity,
-    group: opts.group,
-    role: opts.role as 'admin' | undefined,
-  };
+  return { anyone: opts.anyone, entity: opts.entity, group: opts.group, role: opts.role };
 }
 
 permOptions(perm.command('add <id>'))
@@ -526,7 +536,7 @@ permOptions(perm.command('add <id>'))
   });
 
 permOptions(perm.command('rm <id>'))
-  .description('Remove or narrow record-level access')
+  .description('Withdraw record-level access — no --read/--write withdraws all of it')
   .action(async function (this: Command, id: string, opts: PermCliOptions) {
     const opened = await open(this);
     try {
@@ -544,30 +554,66 @@ permOptions(perm.command('rm <id>'))
     }
   });
 
+perm
+  .command('ls <id>')
+  .description('List who reaches a record')
+  .option('--json', 'output raw JSON')
+  .action(async function (this: Command, id: string, opts: { json?: boolean }) {
+    const opened = await open(this);
+    try {
+      out(await permList(opened.stack, id, Boolean(opts.json)));
+    } finally {
+      await opened.close();
+    }
+  });
+
 const grant = program.command('grant').description('Add, remove, or list type-level grants');
 
-function grantOptions(cmd: Command) {
+function grantRole(allowAny: boolean) {
+  return (value: string): 'member' | 'admin' | 'any' => {
+    const allowed = allowAny ? ['"member"', '"admin"', '"any"'] : ['"member"', '"admin"'];
+    if (!allowed.includes(`"${value}"`)) {
+      const named = `${allowed.slice(0, -1).join(', ')} or ${allowed.at(-1)}`;
+      throw new InvalidArgumentError(`--role must be ${named}`);
+    }
+    return value as 'member' | 'admin' | 'any';
+  };
+}
+
+function grantOptions(cmd: Command, allowAny = false) {
   return cmd
-    .option('--entity <did>', 'grant this identity')
-    .option('--group <id>', 'grant this group')
-    .option('--default', 'grant any authenticated entity');
+    .option('--entity <did>', 'this identity')
+    .option('--group <id>', 'this group, at --role')
+    .option(
+      '--role <role>',
+      allowAny
+        ? 'which half of a --group: "member", "admin", or "any" (default)'
+        : 'which half of a --group: "member" (wider) or "admin"',
+      grantRole(allowAny),
+    )
+    .option('--authenticated', 'any entity holding a DID');
 }
 
-type GrantCliOptions = { entity?: string; group?: string; default?: boolean };
+type GrantCliOptions = {
+  entity?: string;
+  group?: string;
+  role?: 'member' | 'admin' | 'any';
+  authenticated?: boolean;
+};
+
+const grantTarget = (opts: GrantCliOptions) => ({
+  entity: opts.entity,
+  group: opts.group,
+  role: opts.role,
+  authenticated: opts.authenticated,
+});
 
 grantOptions(grant.command('add <typeId> <actions...>'))
   .description('Grant create/read/update/delete on a type family')
   .action(async function (this: Command, typeId: string, actions: string[], opts: GrantCliOptions) {
     const opened = await open(this);
     try {
-      out(
-        await grantAdd(
-          opened.stack,
-          typeId,
-          { entity: opts.entity, group: opts.group, isDefault: opts.default },
-          actions as GrantAction[],
-        ),
-      );
+      out(await grantAdd(opened.stack, typeId, grantTarget(opts), actions as GrantAction[]));
     } finally {
       await opened.close();
     }
@@ -578,27 +624,19 @@ grantOptions(grant.command('rm <typeId> <actions...>'))
   .action(async function (this: Command, typeId: string, actions: string[], opts: GrantCliOptions) {
     const opened = await open(this);
     try {
-      out(
-        await grantRemove(
-          opened.stack,
-          typeId,
-          { entity: opts.entity, group: opts.group, isDefault: opts.default },
-          actions as GrantAction[],
-        ),
-      );
+      out(await grantRemove(opened.stack, typeId, grantTarget(opts), actions as GrantAction[]));
     } finally {
       await opened.close();
     }
   });
 
-grant
-  .command('ls')
-  .description('List grants')
+grantOptions(grant.command('ls'), true)
+  .description('List grants — narrow by --type and/or a grantee')
   .option('--type <typeId>', 'only this type')
-  .action(async function (this: Command, opts: { type?: string }) {
+  .action(async function (this: Command, opts: GrantCliOptions & { type?: string }) {
     const opened = await open(this);
     try {
-      out(await grantList(opened.stack, opts.type));
+      out(await grantList(opened.stack, opts.type, grantTarget(opts)));
     } finally {
       await opened.close();
     }
diff --git a/src/commands/access.ts b/src/commands/access.ts
index f2e624e..f4334ed 100644
--- a/src/commands/access.ts
+++ b/src/commands/access.ts
@@ -1,51 +1,86 @@
 /**
- * `hstack perm | grant` — who may read or write a record, and who may
- * create/read/update/delete a whole type family. `mutate()` replaced
- * `setPermissions()`; a permission entry has no per-field verb of its own,
- * so `perm` reads the record's current `Permission[]`, edits the one entry
- * it names, and writes the whole array back. `grant`/`revoke`/`listGrants`
- * already operate at that granularity. See docs/design.md § Associations.
+ * `hstack perm | grant` — who may read or write one record, and who may
+ * create/read/update/delete a whole type family.
+ *
+ * Record permissions are associations: one element per bit per grantee,
+ * added and withdrawn one at a time by `grantAccess()`/`revokeAccess()`.
+ * Both verbs are no-bump, and neither restates the rest of the ACL, so two
+ * people sharing one record cannot overwrite each other.
+ * See docs/design.md § Associations.
  */
 
-import type { EntityId, GrantAction, Permission, RecordId, Stack } from '@haverstack/core';
+import type {
+  AuthorityAssociation,
+  GrantAction,
+  PermissionGrantee,
+  RecordId,
+  Stack,
+  StackRecord,
+} from '@haverstack/core';
 import { shortDid } from '../config.js';
 
-// Core's own shape for stack.grant()/revoke()/listGrants(), not exported
-// from its root: an entity, a group, or null for a default (public) grant.
-type GrantTarget = EntityId | { groupId: RecordId } | null;
-
 // ---------------------------------------------------------------- perm
 
 export type PermTargetOptions = {
-  public?: boolean;
+  anyone?: boolean;
   entity?: string;
   group?: string;
-  role?: 'admin';
+  role?: 'member' | 'admin';
 };
 
-type PermKey = string;
+/** `anyone` has no grantee at all, which is what makes it its own arm. */
+type PermTarget = { scope: 'anyone' } | PermissionGrantee;
+
+type Bits = { read: boolean; write: boolean };
+
+function resolvePermTarget(opts: PermTargetOptions): PermTarget {
+  const picked = ['anyone', 'entity', 'group'].filter((k) => opts[k as keyof PermTargetOptions]);
+  if (picked.length !== 1) throw new Error('Pass exactly one of --anyone, --entity, or --group.');
+  if (opts.anyone) return { scope: 'anyone' };
+  if (opts.entity) return { scope: 'entity', entityId: opts.entity };
+  if (!opts.role) {
+    throw new Error('--group needs --role member or --role admin — a permission names one role.');
+  }
+  return { scope: 'group', groupId: opts.group!, role: opts.role };
+}
+
+/** The element a target + bit names, or null where the pair names none. */
+function elementFor(target: PermTarget, label: 'read' | 'write'): AuthorityAssociation | null {
+  if (target.scope === 'anyone') return label === 'read' ? { kind: 'anyone', label: 'read' } : null;
+  return { kind: 'permission', label, grantee: target };
+}
+
+function granteeMatches(a: PermissionGrantee, b: PermissionGrantee): boolean {
+  if (a.scope !== b.scope) return false;
+  if (a.scope === 'entity' && b.scope === 'entity') return a.entityId === b.entityId;
+  if (a.scope === 'group' && b.scope === 'group') {
+    return a.groupId === b.groupId && a.role === b.role;
+  }
+  return false;
+}
 
-function keyOf(p: Permission): PermKey {
-  if (p.access === 'public') return 'public';
-  if (p.access === 'entity') return `entity:${p.entityId}`;
-  return `group:${p.groupId}:${p.role ?? 'member'}`;
+function bitsOf(permissions: AuthorityAssociation[] | undefined, target: PermTarget): Bits {
+  const held = (label: 'read' | 'write') =>
+    (permissions ?? []).some((p) =>
+      target.scope === 'anyone'
+        ? p.kind === 'anyone' && label === 'read'
+        : p.kind === 'permission' && p.label === label && granteeMatches(p.grantee, target),
+    );
+  return { read: held('read'), write: held('write') };
 }
 
-function targetKey(opts: PermTargetOptions): PermKey {
-  const picked = ['public', 'entity', 'group'].filter((k) => opts[k as keyof PermTargetOptions]);
-  if (picked.length !== 1) throw new Error('Pass exactly one of --public, --entity, or --group.');
-  if (opts.public) return 'public';
-  if (opts.entity) return `entity:${opts.entity}`;
-  return `group:${opts.group}:${opts.role ?? 'member'}`;
+function describePermTarget(target: PermTarget): string {
+  if (target.scope === 'anyone') return 'anyone';
+  if (target.scope === 'entity') return shortDid(target.entityId);
+  return `group:${target.groupId}:${target.role}`;
 }
 
-function describePerm(p: Permission): string {
-  if (p.access === 'public') return 'public';
-  if (p.access === 'entity') return shortDid(p.entityId);
-  return `group:${p.groupId}${p.role ? `:${p.role}` : ''}`;
+function describeBits(bits: Bits): string {
+  const named = [bits.read && 'read', bits.write && 'write'].filter(Boolean);
+  return named.length > 0 ? named.join('+') : 'nothing';
 }
 
-async function requireRecord(stack: Stack, id: string) {
+async function requireRecord(stack: Stack, id: string): Promise<StackRecord> {
   const record = await stack.get(id);
   if (!record) throw new Error(`No record "${id}".`);
   return record;
@@ -54,111 +89,148 @@ async function requireRecord(stack: Stack, id: string) {
 export async function permAdd(
   stack: Stack,
   id: string,
-  target: PermTargetOptions,
+  targetOpts: PermTargetOptions,
   read: boolean,
   write: boolean,
 ): Promise<string> {
-  if (!target.public && !read && !write) {
-    throw new Error('Nothing to grant — pass --read and/or --write.');
-  }
-  const record = await requireRecord(stack, id);
-  const key = targetKey(target);
-  const perms = [...(record.permissions ?? [])];
-  const i = perms.findIndex((p) => keyOf(p) === key);
-
-  if (target.public) {
-    if (i === -1) perms.push({ access: 'public' });
-  } else if (target.entity) {
-    const prior = i === -1 ? undefined : (perms[i] as Extract<Permission, { access: 'entity' }>);
-    const entry: Permission = {
-      access: 'entity',
-      entityId: target.entity,
-      read: read || Boolean(prior?.read),
-      write: write || Boolean(prior?.write),
-    };
-    if (i === -1) perms.push(entry);
-    else perms[i] = entry;
-  } else {
-    const prior = i === -1 ? undefined : (perms[i] as Extract<Permission, { access: 'group' }>);
-    const entry: Permission = {
-      access: 'group',
-      groupId: target.group!,
-      ...(target.role && { role: target.role }),
-      read: read || Boolean(prior?.read),
-      write: write || Boolean(prior?.write),
-    };
-    if (i === -1) perms.push(entry);
-    else perms[i] = entry;
+  const target = resolvePermTarget(targetOpts);
+  if (target.scope === 'anyone' && write) {
+    throw new Error('--anyone carries read only. Name a --entity or --group to grant write.');
   }
+  // `anyone` has exactly one bit, so naming it is naming the whole element.
+  if (target.scope === 'anyone') read = true;
+  if (!read && !write) throw new Error('Nothing to grant — pass --read and/or --write.');
+
+  const before = bitsOf((await requireRecord(stack, id)).permissions, target);
 
-  const updated = await stack.mutate(id, { permissions: perms });
-  const entry = updated.permissions!.find((p) => keyOf(p) === key)!;
-  return `${id}: ${describePerm(entry)} can ${accessSummary(entry)} (v${updated.version}).`;
+  // Read first: core refuses a set in which a writer cannot read, so the
+  // two halves of `--read --write` only go in one order.
+  let record: StackRecord | undefined;
+  if (read) record = await stack.grantAccess(id, elementFor(target, 'read')!);
+  if (write) record = await stack.grantAccess(id, elementFor(target, 'write')!);
+
+  const after = bitsOf(record!.permissions, target);
+  const who = describePermTarget(target);
+  return before.read === after.read && before.write === after.write
+    ? `${id}: ${who} could already ${describeBits(after)} — nothing to do.`
+    : `${id}: ${who} can now ${describeBits(after)}.`;
 }
 
 export async function permRemove(
   stack: Stack,
   id: string,
-  target: PermTargetOptions,
+  targetOpts: PermTargetOptions,
   read: boolean,
   write: boolean,
 ): Promise<string> {
-  const record = await requireRecord(stack, id);
-  const key = targetKey(target);
-  const perms = [...(record.permissions ?? [])];
-  const i = perms.findIndex((p) => keyOf(p) === key);
-  if (i === -1)
-    return `${id}: no permission entry for ${describeTargetOpts(target)} — nothing to remove.`;
-
-  // Public and an entry with neither bit surviving are dropped outright;
-  // --read/--write on their own narrow the entry instead of deleting it.
-  if (target.public || !(read || write)) {
-    perms.splice(i, 1);
-  } else {
-    const cur = perms[i] as Extract<Permission, { access: 'entity' | 'group' }>;
-    const nextRead = read ? false : cur.read;
-    const nextWrite = write ? false : cur.write;
-    if (!nextRead && !nextWrite) perms.splice(i, 1);
-    else perms[i] = { ...cur, read: nextRead, write: nextWrite };
+  const target = resolvePermTarget(targetOpts);
+  // Naming no bit withdraws the target's access entirely.
+  if (!read && !write) {
+    read = true;
+    write = target.scope !== 'anyone';
+  }
+  if (target.scope === 'anyone' && write) {
+    throw new Error('--anyone carries read only — there is no write bit to remove.');
   }
 
-  const updated = await stack.mutate(id, { permissions: perms });
-  const remaining = updated.permissions?.find((p) => keyOf(p) === key);
-  return remaining
-    ? `${id}: ${describePerm(remaining)} can now only ${accessSummary(remaining)} (v${updated.version}).`
-    : `${id}: removed the ${describeTargetOpts(target)} entry (v${updated.version}).`;
-}
+  const before = bitsOf((await requireRecord(stack, id)).permissions, target);
+
+  // Write first, the inverse of grant's order, for the same invariant.
+  let record: StackRecord | undefined;
+  if (write) record = await stack.revokeAccess(id, elementFor(target, 'write')!);
+  if (read) record = await stack.revokeAccess(id, elementFor(target, 'read')!);
 
-function accessSummary(p: Permission): string {
-  if (p.access === 'public') return 'read';
-  const bits = [p.read && 'read', p.write && 'write'].filter(Boolean);
-  return bits.length ? bits.join('+') : 'nothing (consider removing it)';
+  const after = bitsOf(record!.permissions, target);
+  const who = describePermTarget(target);
+  if (before.read === after.read && before.write === after.write) {
+    return `${id}: ${who} had no ${describeBits({ read, write })} to remove — nothing to do.`;
+  }
+  return after.read || after.write
+    ? `${id}: ${who} can now only ${describeBits(after)}.`
+    : `${id}: ${who} no longer reaches it.`;
 }
 
-function describeTargetOpts(target: PermTargetOptions): string {
-  if (target.public) return 'public';
-  if (target.entity) return shortDid(target.entity);
-  return `group:${target.group}${target.role ? `:${target.role}` : ''}`;
+/**
+ * Who reaches a record. The stored form is one element per bit, which is
+ * what `--json` and `_readonly` show; this collapses the two bits a
+ * grantee may hold onto one line, since "who reaches this" is the question
+ * being asked.
+ */
+export async function permList(stack: Stack, id: string, json: boolean): Promise<string> {
+  const record = await requireRecord(stack, id);
+  const permissions = record.permissions ?? [];
+  if (json) return JSON.stringify(permissions, null, 2);
+  if (permissions.length === 0) return `${id} is private — only the stack owner reaches it.`;
+
+  const byGrantee = new Map<string, Bits>();
+  for (const p of permissions) {
+    const who = p.kind === 'anyone' ? 'anyone' : describePermTarget(p.grantee);
+    const bits = byGrantee.get(who) ?? { read: false, write: false };
+    bits[p.label] = true;
+    byGrantee.set(who, bits);
+  }
+
+  const whoW = Math.max('GRANTEE'.length, ...[...byGrantee.keys()].map((w) => w.length));
+  return [
+    `${'GRANTEE'.padEnd(whoW)}  ACCESS`,
+    ...[...byGrantee].map(([who, bits]) => `${who.padEnd(whoW)}  ${describeBits(bits)}`),
+  ].join('\n');
 }
 
 // ---------------------------------------------------------------- grant
 
-export type GrantTargetOptions = { entity?: string; group?: string; isDefault?: boolean };
+/**
+ * Core's `GrantGrantee` union as flags. `role: 'any'` is listing-only —
+ * `grant`/`revoke` name one role, since a grant to a group's admins is not
+ * the grant to its members.
+ */
+export type GrantTargetOptions = {
+  entity?: string;
+  group?: string;
+  role?: 'member' | 'admin' | 'any';
+  authenticated?: boolean;
+};
+
+type GrantGrantee =
+  | { kind: 'entity'; entityId: string }
+  | { kind: 'group'; groupId: RecordId; role: 'member' | 'admin' }
+  | { kind: 'authenticated' };
+
+type GrantQuery =
+  | { kind: 'entity'; entityId: string }
+  | { kind: 'group'; groupId: RecordId; role: 'member' | 'admin' | 'any' }
+  | { kind: 'authenticated' };
 
-function resolveGrantTarget(opts: GrantTargetOptions): GrantTarget {
-  const picked = ['entity', 'group', 'isDefault'].filter(
+function resolveGrantTarget(opts: GrantTargetOptions): GrantGrantee {
+  const query = resolveGrantQuery(opts, false);
+  if (!query) throw new Error('Pass exactly one of --entity, --group, or --authenticated.');
+  return query as GrantGrantee;
+}
+
+/** The same union, widened for a listing: `--group` alone means any role. */
+function resolveGrantQuery(opts: GrantTargetOptions, allowAny: boolean): GrantQuery | undefined {
+  const picked = ['entity', 'group', 'authenticated'].filter(
     (k) => opts[k as keyof GrantTargetOptions],
   );
-  if (picked.length !== 1) throw new Error('Pass exactly one of --entity, --group, or --default.');
-  if (opts.entity) return opts.entity;
-  if (opts.group) return { groupId: opts.group };
-  return null;
+  if (picked.length === 0) return undefined;
+  if (picked.length > 1) throw new Error('Pass at most one of --entity, --group, --authenticated.');
+  if (opts.entity) return { kind: 'entity', entityId: opts.entity };
+  if (opts.authenticated) return { kind: 'authenticated' };
+  if (opts.role === 'any' && !allowAny) {
+    throw new Error('--role any is for `grant ls` — a grant names member or admin.');
+  }
+  const role = opts.role ?? (allowAny ? 'any' : undefined);
+  if (!role) {
+    throw new Error('--group needs --role member or --role admin — a grant names one role.');
+  }
+  return { kind: 'group', groupId: opts.group!, role };
 }
 
-function describeGrantTarget(target: GrantTarget): string {
-  if (target === null) return '(default — any authenticated entity)';
-  if (typeof target === 'string') return shortDid(target);
-  return `group:${target.groupId}`;
+function describeGrantee(grantee: GrantQuery | undefined): string {
+  if (!grantee) return '—';
+  if (grantee.kind === 'entity') return shortDid(grantee.entityId);
+  if (grantee.kind === 'group') return `group:${grantee.groupId}:${grantee.role}`;
+  return 'authenticated';
 }
 
 export async function grantAdd(
@@ -169,7 +241,7 @@ export async function grantAdd(
 ): Promise<string> {
   const target = resolveGrantTarget(targetOpts);
   await stack.grant(target, [{ typeId, actions }]);
-  return `Granted ${describeGrantTarget(target)} [${actions.join(', ')}] on ${typeId}.`;
+  return `Granted ${describeGrantee(target)} [${actions.join(', ')}] on ${typeId}.`;
 }
 
 export async function grantRemove(
@@ -179,37 +251,33 @@ export async function grantRemove(
   actions: GrantAction[],
 ): Promise<string> {
   const target = resolveGrantTarget(targetOpts);
-  await stack.revoke(target, [{ typeId, actions }]);
-  return `Revoked ${describeGrantTarget(target)} [${actions.join(', ')}] on ${typeId}.`;
+  const withdrawn = await stack.revoke(target, [{ typeId, actions }]);
+  return withdrawn.length === 0
+    ? `No grant matched ${describeGrantee(target)} [${actions.join(', ')}] on ${typeId} — nothing to revoke.`
+    : `Revoked ${withdrawn.length} grant(s): ${describeGrantee(target)} [${actions.join(', ')}] on ${typeId}.`;
 }
 
-export async function grantList(stack: Stack, typeId?: string): Promise<string> {
-  const all = await stack.listGrants();
+export async function grantList(
+  stack: Stack,
+  typeId?: string,
+  targetOpts: GrantTargetOptions = {},
+): Promise<string> {
+  const query = resolveGrantQuery(targetOpts, true);
+  const all = await stack.listGrants(query);
   const rows = (
     typeId ? all.filter((r) => (r.content as { typeId: string }).typeId === typeId) : all
-  ).map(
-    (r) =>
-      r.content as {
-        typeId: string;
-        actions: GrantAction[];
-        granteeEntityId?: string;
-        granteeGroupId?: string;
-      },
-  );
+  ).map((r) => r.content as { typeId: string; actions: GrantAction[]; grantee?: GrantQuery });
 
   if (rows.length === 0) return 'No grants.';
 
-  const target = (g: (typeof rows)[number]): GrantTarget =>
-    g.granteeEntityId ?? (g.granteeGroupId ? { groupId: g.granteeGroupId } : null);
-
   const typeW = Math.max(4, ...rows.map((g) => g.typeId.length));
   const granteeW = Math.max(
     'GRANTEE'.length,
-    ...rows.map((g) => describeGrantTarget(target(g)).length),
+    ...rows.map((g) => describeGrantee(g.grantee).length),
   );
   const lines = rows.map(
     (g) =>
-      `${g.typeId.padEnd(typeW)}  ${describeGrantTarget(target(g)).padEnd(granteeW)}  ${g.actions.join(', ')}`,
+      `${g.typeId.padEnd(typeW)}  ${describeGrantee(g.grantee).padEnd(granteeW)}  ${g.actions.join(', ')}`,
   );
   return [`${'TYPE'.padEnd(typeW)}  ${'GRANTEE'.padEnd(granteeW)}  ACTIONS`, ...lines].join('\n');
 }
diff --git a/src/commands/associations.ts b/src/commands/associations.ts
index 328a51d..e04ba06 100644
--- a/src/commands/associations.ts
+++ b/src/commands/associations.ts
@@ -4,26 +4,43 @@
  * target union into a text file is exactly what a text editor is bad at;
  * this is the porcelain half of docs/design.md § Associations — a hybrid
  * split (`tags:` in front matter covers the common case day to day).
+ *
+ * These are **no-bump** writes (core 0.33): they leave `version` and
+ * `updatedAt` where they stand, so there is no version to report back and
+ * a repeat is a silent no-op — hence the before/after comparison that
+ * distinguishes "done" from "already so".
  */
 
-import type { RelationshipTarget, Stack } from '@haverstack/core';
+import type { Association, RelationshipTarget, Stack, StackRecord } from '@haverstack/core';
 
-async function requireRecord(stack: Stack, id: string) {
+async function requireRecord(stack: Stack, id: string): Promise<StackRecord> {
   const record = await stack.get(id);
   if (!record) throw new Error(`No record "${id}".`);
   return record;
 }
 
+/** How many associations the record carries — enough to tell a no-op apart. */
+function count(record: StackRecord): number {
+  return (record.associations ?? []).length;
+}
+
+function has(associations: Association[] | undefined, label: string): boolean {
+  return (associations ?? []).some((a) => a.kind === 'tag' && a.label === label);
+}
+
 export async function tagAdd(stack: Stack, id: string, label: string): Promise<string> {
-  await requireRecord(stack, id);
-  const updated = await stack.associate(id, { kind: 'tag', label });
-  return `${id} is tagged "${label}" (v${updated.version}).`;
+  const before = await requireRecord(stack, id);
+  if (has(before.associations, label)) return `${id} is already tagged "${label}".`;
+  await stack.associate(id, { kind: 'tag', label });
+  return `${id} is tagged "${label}".`;
 }
 
 export async function tagRemove(stack: Stack, id: string, label: string): Promise<string> {
-  await requireRecord(stack, id);
-  const updated = await stack.dissociate(id, { kind: 'tag', label });
-  return `${id} is no longer tagged "${label}" (v${updated.version}).`;
+  const before = await requireRecord(stack, id);
+  if (!has(before.associations, label))
+    return `${id} is not tagged "${label}" — nothing to remove.`;
+  await stack.dissociate(id, { kind: 'tag', label });
+  return `${id} is no longer tagged "${label}".`;
 }
 
 export type LinkTargetOptions = {
@@ -73,10 +90,11 @@ export async function linkAdd(
   label: string,
   targetOpts: LinkTargetOptions,
 ): Promise<string> {
-  await requireRecord(stack, id);
+  const before = await requireRecord(stack, id);
   const target = buildRelationshipTarget(targetOpts);
-  const updated = await stack.associate(id, { kind: 'relationship', label, target });
-  return `${id} --${label}--> ${describeTarget(target)} (v${updated.version}).`;
+  const after = await stack.associate(id, { kind: 'relationship', label, target });
+  const arrow = `${id} --${label}--> ${describeTarget(target)}`;
+  return count(after) === count(before) ? `${arrow} — already linked.` : `${arrow}.`;
 }
 
 export async function linkRemove(
@@ -85,8 +103,11 @@ export async function linkRemove(
   label: string,
   targetOpts: LinkTargetOptions,
 ): Promise<string> {
-  await requireRecord(stack, id);
+  const before = await requireRecord(stack, id);
   const target = buildRelationshipTarget(targetOpts);
-  const updated = await stack.dissociate(id, { kind: 'relationship', label, target });
-  return `Removed ${id} --${label}--> ${describeTarget(target)} (v${updated.version}).`;
+  const after = await stack.dissociate(id, { kind: 'relationship', label, target });
+  const arrow = `${id} --${label}--> ${describeTarget(target)}`;
+  return count(after) === count(before)
+    ? `No such link: ${arrow} — nothing to remove.`
+    : `Removed ${arrow}.`;
 }
diff --git a/src/commands/attach.ts b/src/commands/attach.ts
index 4330111..92e2a31 100644
--- a/src/commands/attach.ts
+++ b/src/commands/attach.ts
@@ -3,6 +3,7 @@
  * label other than `embed`. The common case (files dropped in the working
  * directory during `hstack edit`) is handled by commit's own reconcile;
  * see src/edit/attachments.ts and docs/design.md § Attachments — both ways.
+ * Associating is a no-bump write, so neither verb reports a version.
  */
 
 import { readFile } from 'node:fs/promises';
@@ -34,12 +35,16 @@ export async function attachAdd(
   const name = basename(filePath);
   const mimeType = inferContentTypeFromFilename(name) ?? 'application/octet-stream';
   const attachment = await stack.putAttachment(bytes, mimeType, name);
-  const updated = await stack.associate(id, {
+  // `attachmentRecordId` names the upload this particular reference came
+  // from, so a filename lookup resolves to it rather than to whichever
+  // other record happened to upload the same bytes.
+  await stack.associate(id, {
     kind: 'attachment',
     label,
     fileId: attachment.content.fileId,
+    attachmentRecordId: attachment.id,
   });
-  return `${id}: attached "${name}" (${attachment.content.fileId.slice(0, 12)}…) as "${label}" (v${updated.version}).`;
+  return `${id}: attached "${name}" (${attachment.content.fileId.slice(0, 12)}…) as "${label}".`;
 }
 
 export async function attachRemove(
@@ -48,7 +53,10 @@ export async function attachRemove(
   label: string,
   fileId: string,
 ): Promise<string> {
-  await requireRecord(stack, id);
-  const updated = await stack.dissociate(id, { kind: 'attachment', label, fileId });
-  return `${id}: detached "${label}" (${fileId.slice(0, 12)}…) (v${updated.version}).`;
+  const before = await requireRecord(stack, id);
+  const after = await stack.dissociate(id, { kind: 'attachment', label, fileId });
+  if ((after.associations ?? []).length === (before.associations ?? []).length) {
+    return `${id}: no "${label}" attachment for ${fileId.slice(0, 12)}… — nothing to detach.`;
+  }
+  return `${id}: detached "${label}" (${fileId.slice(0, 12)}…).`;
 }
diff --git a/src/commands/edit.ts b/src/commands/edit.ts
index 1953aa7..c749075 100644
--- a/src/commands/edit.ts
+++ b/src/commands/edit.ts
@@ -149,20 +149,21 @@ export async function commitEdit(
 
   try {
     if (data.mode === 'new') {
-      let record = await stack.create(data.typeId, parsed.content, {
+      const record = await stack.create(data.typeId, parsed.content, {
         id: parsed.id ?? data.recordId,
         parentId: parsed.parentId ?? undefined,
       });
-      // Tag and attachment associates each bump the version, so the report
-      // below needs whatever the record actually ended on, not create()'s.
-      for (const label of parsed.tags)
-        record = await stack.associate(record.id, { kind: 'tag', label });
+      // Tags and attachments are no-bump writes, so create()'s version is
+      // the one the record ends on — nothing to re-read for.
+      for (const label of parsed.tags) await stack.associate(record.id, { kind: 'tag', label });
       const warnings = await reconcileAttachments(stack, record.id, dir);
-      const final = (await stack.get(record.id)) ?? record;
       await releaseEdit(dir);
       return {
         ok: true,
-        message: withWarnings(`Created ${final.id} (${data.typeId}), v${final.version}.`, warnings),
+        message: withWarnings(
+          `Created ${record.id} (${data.typeId}), v${record.version}.`,
+          warnings,
+        ),
       };
     }
 
@@ -170,23 +171,22 @@ export async function commitEdit(
     if (!record) return { ok: false, message: `Record "${data.recordId}" no longer exists.` };
 
     const patch = buildPatch(record.content, parsed.content);
-    // mutate() carries content and parentId in one fenced, one-version
-    // write; core checks the destination exists and refuses a cycle. Tag
-    // and attachment reconcile run after (associations are set-merged, not
-    // fenced), so a final re-read reports the version the record actually
-    // ended on.
-    await stack.mutate(
+    // One fenced write carrying both aspects: core checks the destination
+    // exists and refuses a cycle. A move is no-bump on its own, but naming
+    // `contentPatch` alongside it restores `ifVersion` over the whole call.
+    const written = await stack.mutate(
       data.recordId,
       { contentPatch: patch, parentId: parsed.parentId },
       { ifVersion: opts.force ? undefined : data.baseVersion },
     );
+    // Tags and attachments reconcile afterwards and bump nothing, so the
+    // version this write produced is the one the record ends on.
     await reconcileTags(stack, record, parsed.tags);
     const warnings = await reconcileAttachments(stack, data.recordId, dir);
     await releaseEdit(dir);
-    const final = await stack.get(data.recordId);
     return {
       ok: true,
-      message: withWarnings(`Committed ${data.recordId}, v${final?.version ?? '?'}.`, warnings),
+      message: withWarnings(`Committed ${data.recordId}, v${written.version}.`, warnings),
     };
   } catch (err) {
     // Match on the stable `code` rather than `instanceof`: a linked dev
diff --git a/src/commands/records.ts b/src/commands/records.ts
index c9791b8..20c80bf 100644
--- a/src/commands/records.ts
+++ b/src/commands/records.ts
@@ -89,8 +89,18 @@ export async function removeRecord(stack: Stack, id: string, hard: boolean): Pro
   const record = await stack.get(id);
   if (!record) throw new Error(`No record "${id}".`);
   if (hard) {
-    await stack.delete(id, { hard: true });
-    return `Purged ${id}. This cannot be undone.`;
+    // A purge destroys the only rows naming the files the record
+    // referenced, so core reports them rather than deleting bytes on its
+    // own — GC can no longer see they were ever referenced.
+    const { referencedFileIds } = await stack.delete(id, { hard: true });
+    const purged = `Purged ${id}. This cannot be undone.`;
+    return referencedFileIds.length === 0
+      ? purged
+      : [
+          purged,
+          `It referenced ${referencedFileIds.length} file(s); their bytes are still stored:`,
+          ...referencedFileIds.map((f) => `  ${f}`),
+        ].join('\n');
   }
   if (record.deletedAt)
     return `${id} is already deleted. \`hstack restore ${id}\` to bring it back.`;
diff --git a/src/index.ts b/src/index.ts
index 4d70947..5815619 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -30,7 +30,14 @@ export {
   buildRelationshipTarget,
 } from './commands/associations.js';
 export type { LinkTargetOptions } from './commands/associations.js';
-export { permAdd, permRemove, grantAdd, grantRemove, grantList } from './commands/access.js';
+export {
+  permAdd,
+  permList,
+  permRemove,
+  grantAdd,
+  grantRemove,
+  grantList,
+} from './commands/access.js';
 export type { PermTargetOptions, GrantTargetOptions } from './commands/access.js';
 export { attachAdd, attachRemove } from './commands/attach.js';
 
diff --git a/tests/access.test.ts b/tests/access.test.ts
index 9789680..38feb13 100644
--- a/tests/access.test.ts
+++ b/tests/access.test.ts
@@ -1,11 +1,20 @@
 import { beforeEach, describe, expect, it } from 'vitest';
 import { Stack } from '@haverstack/core';
 import { MemoryAdapter } from '@haverstack/core/testing';
-import { grantAdd, grantList, grantRemove, permAdd, permRemove } from '../src/commands/access.js';
+import {
+  grantAdd,
+  grantList,
+  grantRemove,
+  permAdd,
+  permList,
+  permRemove,
+} from '../src/commands/access.js';
 
 let stack: Stack;
 let id: string;
 
+const perms = async () => (await stack.get(id))?.permissions ?? [];
+
 beforeEach(async () => {
   stack = await Stack.create(new MemoryAdapter({ ownerEntityId: 'did:key:zOwner' }));
   await stack.defineType('com.example/note@1', 'Note', { title: { kind: 'string' } });
@@ -13,69 +22,133 @@ beforeEach(async () => {
 });
 
 describe('permAdd', () => {
-  it('adds a public entry, idempotently', async () => {
-    await permAdd(stack, id, { public: true }, false, false);
-    await permAdd(stack, id, { public: true }, false, false);
-    expect((await stack.get(id))?.permissions).toEqual([{ access: 'public' }]);
+  it('adds an `anyone` element, idempotently', async () => {
+    await permAdd(stack, id, { anyone: true }, false, false);
+    const second = await permAdd(stack, id, { anyone: true }, false, false);
+    expect(await perms()).toEqual([{ kind: 'anyone', label: 'read' }]);
+    expect(second).toMatch(/nothing to do/);
   });
 
-  it('requires --read or --write for a non-public target', async () => {
+  it('refuses a write bit on --anyone, which carries read alone', async () => {
+    await expect(permAdd(stack, id, { anyone: true }, false, true)).rejects.toThrow(
+      /--anyone carries read only/,
+    );
+  });
+
+  it('requires --read or --write for a grantee target', async () => {
     await expect(permAdd(stack, id, { entity: 'did:key:z1' }, false, false)).rejects.toThrow(
       /Nothing to grant/,
     );
   });
 
-  it('merges access bits into an existing entity entry rather than resetting it', async () => {
+  it('adds one element per bit, and adding the second keeps the first', async () => {
     await permAdd(stack, id, { entity: 'did:key:z1' }, true, false);
     await permAdd(stack, id, { entity: 'did:key:z1' }, false, true);
-    expect((await stack.get(id))?.permissions).toEqual([
-      { access: 'entity', entityId: 'did:key:z1', read: true, write: true },
+    expect(await perms()).toEqual([
+      { kind: 'permission', label: 'read', grantee: { scope: 'entity', entityId: 'did:key:z1' } },
+      { kind: 'permission', label: 'write', grantee: { scope: 'entity', entityId: 'did:key:z1' } },
     ]);
   });
 
-  it('keys a group entry on groupId + role, so admin and member are distinct entries', async () => {
-    // `write` requires `read` in the same entry (core: write reaches the
-    // record and its history, so write-without-read withholds nothing).
-    await permAdd(stack, id, { group: 'g1' }, true, false);
+  it('keys a group grantee on groupId + role, so member and admin are distinct', async () => {
+    await permAdd(stack, id, { group: 'g1', role: 'member' }, true, false);
     await permAdd(stack, id, { group: 'g1', role: 'admin' }, true, true);
-    expect((await stack.get(id))?.permissions).toEqual([
-      { access: 'group', groupId: 'g1', read: true, write: false },
-      { access: 'group', groupId: 'g1', role: 'admin', read: true, write: true },
+    expect(await perms()).toEqual([
+      {
+        kind: 'permission',
+        label: 'read',
+        grantee: { scope: 'group', groupId: 'g1', role: 'member' },
+      },
+      {
+        kind: 'permission',
+        label: 'read',
+        grantee: { scope: 'group', groupId: 'g1', role: 'admin' },
+      },
+      {
+        kind: 'permission',
+        label: 'write',
+        grantee: { scope: 'group', groupId: 'g1', role: 'admin' },
+      },
     ]);
   });
 
-  it('surfaces core’s own write-requires-read rule for a fresh entry', async () => {
+  it('requires --role alongside --group — a permission names one role', async () => {
+    await expect(permAdd(stack, id, { group: 'g1' }, true, false)).rejects.toThrow(
+      /--group needs --role/,
+    );
+  });
+
+  it('grants read before write, so --read --write together is accepted', async () => {
+    await permAdd(stack, id, { entity: 'did:key:z1' }, true, true);
+    expect((await perms()).map((p) => p.label)).toEqual(['read', 'write']);
+  });
+
+  it('surfaces core’s own write-requires-read rule for a bare write', async () => {
     await expect(permAdd(stack, id, { entity: 'did:key:z1' }, false, true)).rejects.toThrow(
-      /write requires read/,
+      /write requires read|cannot read/i,
     );
   });
 
-  it('requires exactly one of --public / --entity / --group', async () => {
+  it('is a no-bump write — version and updatedAt stay put', async () => {
+    const before = (await stack.get(id))!;
+    await permAdd(stack, id, { anyone: true }, false, false);
+    const after = (await stack.get(id))!;
+    expect(after.version).toBe(before.version);
+    expect(after.updatedAt.getTime()).toBe(before.updatedAt.getTime());
+  });
+
+  it('requires exactly one of --anyone / --entity / --group', async () => {
     await expect(permAdd(stack, id, {}, true, false)).rejects.toThrow(/exactly one/);
   });
 });
 
 describe('permRemove', () => {
-  it('drops the public entry outright', async () => {
-    await permAdd(stack, id, { public: true }, false, false);
-    const msg = await permRemove(stack, id, { public: true }, false, false);
-    expect(msg).toMatch(/removed the public entry/);
-    expect((await stack.get(id))?.permissions ?? []).toEqual([]);
+  it('drops the `anyone` element', async () => {
+    await permAdd(stack, id, { anyone: true }, false, false);
+    const msg = await permRemove(stack, id, { anyone: true }, false, false);
+    expect(msg).toMatch(/no longer reaches it/);
+    expect(await perms()).toEqual([]);
   });
 
-  it('narrows an entity entry when only one bit is named, dropping it once both are gone', async () => {
+  it('withdraws one named bit, leaving the other standing', async () => {
     await permAdd(stack, id, { entity: 'did:key:z1' }, true, true);
     await permRemove(stack, id, { entity: 'did:key:z1' }, false, true);
-    expect((await stack.get(id))?.permissions).toEqual([
-      { access: 'entity', entityId: 'did:key:z1', read: true, write: false },
+    expect(await perms()).toEqual([
+      { kind: 'permission', label: 'read', grantee: { scope: 'entity', entityId: 'did:key:z1' } },
     ]);
-    await permRemove(stack, id, { entity: 'did:key:z1' }, true, false);
-    expect((await stack.get(id))?.permissions ?? []).toEqual([]);
+  });
+
+  it('withdraws every bit when neither is named, write first', async () => {
+    await permAdd(stack, id, { entity: 'did:key:z1' }, true, true);
+    await permRemove(stack, id, { entity: 'did:key:z1' }, false, false);
+    expect(await perms()).toEqual([]);
+  });
+
+  it('surfaces core’s refusal to leave a writer unable to read', async () => {
+    await permAdd(stack, id, { entity: 'did:key:z1' }, true, true);
+    await expect(permRemove(stack, id, { entity: 'did:key:z1' }, true, false)).rejects.toThrow(
+      /read|write/i,
+    );
   });
 
   it('is a no-op message when there is nothing to remove', async () => {
     const msg = await permRemove(stack, id, { entity: 'did:key:zNobody' }, false, false);
-    expect(msg).toMatch(/nothing to remove/);
+    expect(msg).toMatch(/nothing to do/);
+  });
+});
+
+describe('permList', () => {
+  it('says so when a record is private', async () => {
+    expect(await permList(stack, id, false)).toMatch(/private/);
+  });
+
+  it('lists a grantee per line, and round-trips as JSON', async () => {
+    await permAdd(stack, id, { entity: 'did:key:z1' }, true, true);
+    await permAdd(stack, id, { anyone: true }, false, false);
+    const listing = await permList(stack, id, false);
+    expect(listing).toMatch(/GRANTEE\s+ACCESS/);
+    expect(listing).toMatch(/anyone\s+read/);
+    expect(JSON.parse(await permList(stack, id, true))).toHaveLength(3);
   });
 });
 
@@ -87,10 +160,33 @@ describe('grantAdd / grantRemove / grantList', () => {
     expect(listing).toMatch(/create, read-own/);
   });
 
-  it('supports a default (public) grant', async () => {
-    await grantAdd(stack, 'com.example/note@1', { isDefault: true }, ['create']);
-    const listing = await grantList(stack);
-    expect(listing).toMatch(/default/);
+  it('supports an authenticated (default) grant', async () => {
+    await grantAdd(stack, 'com.example/note@1', { authenticated: true }, ['create']);
+    expect(await grantList(stack)).toMatch(/authenticated/);
+  });
+
+  it('names one role on a group grant, and keeps member and admin apart', async () => {
+    await grantAdd(stack, 'com.example/note@1', { group: 'g1', role: 'member' }, ['create']);
+    await grantAdd(stack, 'com.example/note@1', { group: 'g1', role: 'admin' }, ['read-any']);
+    expect(await grantList(stack, undefined, { group: 'g1', role: 'admin' })).toMatch(
+      /group:g1:admin\s+read-any/,
+    );
+    // `--role any` is the listing-only widening.
+    expect(
+      (await grantList(stack, undefined, { group: 'g1', role: 'any' })).split('\n'),
+    ).toHaveLength(3);
+  });
+
+  it('requires --role alongside --group when granting', async () => {
+    await expect(
+      grantAdd(stack, 'com.example/note@1', { group: 'g1' }, ['create']),
+    ).rejects.toThrow(/--group needs --role/);
+  });
+
+  it('refuses the listing-only --role any on a grant', async () => {
+    await expect(
+      grantAdd(stack, 'com.example/note@1', { group: 'g1', role: 'any' }, ['create']),
+    ).rejects.toThrow(/--role any is for/);
   });
 
   it('filters listGrants by typeId', async () => {
@@ -102,19 +198,29 @@ describe('grantAdd / grantRemove / grantList', () => {
     expect(listing).not.toContain('com.example/note@1');
   });
 
-  it('revokes what it granted', async () => {
+  it('revokes what it granted, and reports how many it withdrew', async () => {
     await grantAdd(stack, 'com.example/note@1', { entity: 'did:key:zApp' }, ['create']);
-    await grantRemove(stack, 'com.example/note@1', { entity: 'did:key:zApp' }, ['create']);
+    const msg = await grantRemove(stack, 'com.example/note@1', { entity: 'did:key:zApp' }, [
+      'create',
+    ]);
+    expect(msg).toMatch(/Revoked 1 grant/);
     expect(await grantList(stack)).toBe('No grants.');
   });
 
+  it('says so when a revoke matches nothing', async () => {
+    const msg = await grantRemove(stack, 'com.example/note@1', { entity: 'did:key:zNobody' }, [
+      'create',
+    ]);
+    expect(msg).toMatch(/nothing to revoke/);
+  });
+
   it('surfaces core’s own dependency error for a mutate action with no read companion', async () => {
     await expect(
       grantAdd(stack, 'com.example/note@1', { entity: 'did:key:zApp' }, ['update-any']),
     ).rejects.toThrow(/requires "read-any"/);
   });
 
-  it('requires exactly one of --entity / --group / --default', async () => {
+  it('requires exactly one of --entity / --group / --authenticated', async () => {
     await expect(grantAdd(stack, 'com.example/note@1', {}, ['create'])).rejects.toThrow(
       /exactly one/,
     );
diff --git a/tests/associations.test.ts b/tests/associations.test.ts
index 127f5f1..6e9fcdd 100644
--- a/tests/associations.test.ts
+++ b/tests/associations.test.ts
@@ -22,17 +22,28 @@ beforeEach(async () => {
 });
 
 describe('tagAdd / tagRemove', () => {
-  it('adds and removes a tag, reporting the resulting version', async () => {
+  it('adds and removes a tag without moving the version', async () => {
+    const before = (await stack.get(id))!;
     const added = await tagAdd(stack, id, 'starred');
-    expect(added).toBe(`${id} is tagged "starred" (v2).`);
+    expect(added).toBe(`${id} is tagged "starred".`);
     const record = await stack.get(id);
     expect(record?.associations).toEqual([{ kind: 'tag', label: 'starred' }]);
+    // Associating is a no-bump write: version and updatedAt stay put.
+    expect(record?.version).toBe(before.version);
+    expect(record?.updatedAt.getTime()).toBe(before.updatedAt.getTime());
 
     const removed = await tagRemove(stack, id, 'starred');
-    expect(removed).toBe(`${id} is no longer tagged "starred" (v3).`);
+    expect(removed).toBe(`${id} is no longer tagged "starred".`);
     expect((await stack.get(id))?.associations ?? []).toEqual([]);
   });
 
+  it('reports a repeat as the no-op it is', async () => {
+    await tagAdd(stack, id, 'starred');
+    expect(await tagAdd(stack, id, 'starred')).toMatch(/already tagged/);
+    await tagRemove(stack, id, 'starred');
+    expect(await tagRemove(stack, id, 'starred')).toMatch(/nothing to remove/);
+  });
+
   it('errors on a missing record', async () => {
     await expect(tagAdd(stack, 'ghost', 'x')).rejects.toThrow(/No record "ghost"/);
   });
@@ -73,13 +84,16 @@ describe('buildRelationshipTarget', () => {
 describe('linkAdd / linkRemove', () => {
   it('associates and dissociates a relationship to another record', async () => {
     const msg = await linkAdd(stack, id, 'see-also', { toRecord: otherId });
-    expect(msg).toBe(`${id} --see-also--> ${otherId} (v2).`);
+    expect(msg).toBe(`${id} --see-also--> ${otherId}.`);
     expect((await stack.get(id))?.associations).toEqual([
       { kind: 'relationship', label: 'see-also', target: { scope: 'record', recordId: otherId } },
     ]);
 
     await linkRemove(stack, id, 'see-also', { toRecord: otherId });
     expect((await stack.get(id))?.associations ?? []).toEqual([]);
+    expect(await linkRemove(stack, id, 'see-also', { toRecord: otherId })).toMatch(
+      /nothing to remove/,
+    );
   });
 
   it('dissociate only removes the exact target named', async () => {
diff --git a/tests/edit-commit.test.ts b/tests/edit-commit.test.ts
index 44d975c..ba2bdba 100644
--- a/tests/edit-commit.test.ts
+++ b/tests/edit-commit.test.ts
@@ -134,9 +134,37 @@ describe('edit -> commit', () => {
         `type: com.example/note@1\nparentId: ${parent.id}`,
       ),
     );
+    const before = (await stack.get(id))!;
     const outcome = await commitEdit(stack, LABEL, id, {});
     expect(outcome.ok).toBe(true);
-    expect((await stack.get(id))?.parentId).toBe(parent.id);
+    const after = (await stack.get(id))!;
+    expect(after.parentId).toBe(parent.id);
+    // A move on its own is no-bump, so the commit reports the version the
+    // record was already at rather than inventing one.
+    expect(after.version).toBe(before.version);
+    expect(outcome.message).toContain(`v${before.version}`);
+  });
+
+  it('still fences a move under ifVersion when the same commit patches content', async () => {
+    await stack.defineType('com.example/folder@1', 'Folder', {
+      name: { kind: 'string', required: true },
+    });
+    const parent = await stack.create('com.example/folder@1', { name: 'p2' });
+    const started = await editRecord(stack, LABEL, id);
+    await writeEditFile(
+      started.dir,
+      (await readEditFile(started.dir))
+        .replace('type: com.example/note@1', `type: com.example/note@1\nparentId: ${parent.id}`)
+        .replace(/title: .*/, 'title: Moved and renamed'),
+    );
+    // Someone else writes while the edit is open — naming `contentPatch`
+    // alongside `parentId` is what keeps the precondition live.
+    await stack.mutate(id, { contentPatch: { title: 'Elsewhere' } });
+
+    const outcome = await commitEdit(stack, LABEL, id, {});
+    expect(outcome.ok).toBe(false);
+    expect(outcome.message).toMatch(/Conflict:/);
+    expect((await stack.get(id))?.parentId).toBeUndefined();
   });
 
   it('surfaces a nonexistent parentId as a kept-copy failure, not a crash', async () => {
@@ -208,10 +236,10 @@ describe('working-directory attachments', () => {
     expect(outcome.ok).toBe(true);
     const record = await stack.get(started.recordId);
     expect(record?.associations).toHaveLength(1);
-    // create() lands at v1; the embed associate is a second write the
-    // reported version must reflect, not create()'s own v1.
-    expect(outcome.message).toContain(`v${record?.version}`);
-    expect(record?.version).toBeGreaterThan(1);
+    // The embed associate is a no-bump write, so the record stays at
+    // create()'s v1 and that is what the commit reports.
+    expect(record?.version).toBe(1);
+    expect(outcome.message).toContain('v1');
   });
 
   it('a file dropped during a later edit is embedded, and removing it dissociates', async () => {
diff --git a/tests/record-format.test.ts b/tests/record-format.test.ts
index 3f49434..1595d98 100644
--- a/tests/record-format.test.ts
+++ b/tests/record-format.test.ts
@@ -86,14 +86,14 @@ describe('renderRecord', () => {
         { kind: 'tag', label: 'work' },
         { kind: 'relationship', label: 'blocks', target: { scope: 'record', recordId: 'zzz' } },
       ],
-      permissions: [{ access: 'public' }],
+      permissions: [{ kind: 'anyone', label: 'read' }],
     };
     const fm = frontMatter(renderRecord(record, noteType));
     expect(fm.tags).toEqual(['starred', 'work']);
     const ro = fm._readonly as Record<string, unknown>;
     expect(ro.version).toBe(3);
     expect(ro.associations).toHaveLength(1);
-    expect(ro.permissions).toEqual([{ access: 'public' }]);
+    expect(ro.permissions).toEqual([{ kind: 'anyone', label: 'read' }]);
   });
 
   it('marks a soft-deleted record in _readonly', () => {
diff --git a/tests/server-integration.test.ts b/tests/server-integration.test.ts
index 655ba85..ad976dc 100644
--- a/tests/server-integration.test.ts
+++ b/tests/server-integration.test.ts
@@ -77,7 +77,9 @@ describe('server-path integration', () => {
       title: 'orig',
       text: 'owner-authored',
     });
-    await server.ctx.stack.grant(null, [{ typeId: TYPE_ID, actions: ['read-any'] }]);
+    await server.ctx.stack.grant({ kind: 'authenticated' }, [
+      { typeId: TYPE_ID, actions: ['read-any'] },
+    ]);
 
     const opened = await openAsGrantee();
     try {
@@ -100,7 +102,9 @@ describe('server-path integration', () => {
 
   it('denies includeUnlisted to a grantee, over the real wire', async () => {
     await server.ctx.stack.create(TYPE_ID, { text: 'irrelevant' }, { unlisted: true });
-    await server.ctx.stack.grant(null, [{ typeId: TYPE_ID, actions: ['read-any'] }]);
+    await server.ctx.stack.grant({ kind: 'authenticated' }, [
+      { typeId: TYPE_ID, actions: ['read-any'] },
+    ]);
 
     const opened = await openAsGrantee();
     try {
@@ -114,7 +118,9 @@ describe('server-path integration', () => {
 
   it('reports a version conflict when the record moves under an in-progress edit', async () => {
     const record = await server.ctx.stack.create(TYPE_ID, { title: 'orig', text: 'v1' });
-    await server.ctx.stack.grant(null, [{ typeId: TYPE_ID, actions: ['read-any', 'update-any'] }]);
+    await server.ctx.stack.grant({ kind: 'authenticated' }, [
+      { typeId: TYPE_ID, actions: ['read-any', 'update-any'] },
+    ]);
 
     const opened = await openAsGrantee();
     try {

From b5e514e178874c597f6930451e740d3351ad1dbe Mon Sep 17 00:00:00 2001
From: Jen Garcia <jen@haverstack.com>
Date: Wed, 23 Sep 2026 17:26:40 -0400
Subject: [PATCH 2/3] feat: name every association target the same way, with
 one --to
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`link`, `perm` and `grant` each spelled the other end differently — ten
flags between them, three sets of "exactly one of" rules, and three shapes
for what is, to the person typing, one idea. They now share `--to
<target>`, parsed once in src/target.ts and narrowed per command.

    anyone                     the world, anonymous included   (perm)
    authenticated              any entity holding a DID        (grant)
    did:key:z6Mk…              an identity                     (all three)
    group:<id>/<member|admin>  a roster at one role            (perm, grant)
    record:<id>[@<stackUrl>]   a record, here or elsewhere     (link)
    external:<ns>/<id>         something outside any stack     (link)

The vocabulary is the CLI's own and deliberately wider than any single
core union. Core keeps three apart on purpose — a RelationshipTarget names
no role, a PermissionGrantee has no record scope, and `anyone` is a kind
rather than a grantee, so no dropped field can produce world-read. That
split is right for the data model and wrong for a person, who is naming
Alice either way. So one grammar parses and each command narrows to the
arms it accepts, refusing the rest by name. The narrowing is where core's
distinctions are enforced; the grammar is where the convenience lives.

Three rules keep it honest. Exactly one shape is inferred — a leading
`did:` is an entity, because a DID is the one identifier every command
takes and `entity:did:key:…` reads badly on the most frequent call;
everything else names its scheme and an unknown one is an error, not a
fallback. `external:` nests its namespace rather than sharing the
top-level slot, since `ns` is open and user-chosen and letting it compete
with `group:`/`record:` would reserve words out of a namespace this CLI
does not own. And formatTarget() is parseTarget()'s inverse, so `perm ls`
and `grant ls` print targets unelided in the grammar their own commands
accept — a listing row is a command argument, which the smoke test pins by
feeding one back in.

`grant ls --role any` becomes `--to group:<id>/any`, which also moves the
listing widening and the world-read tier into structurally different slots
instead of leaving them one letter apart.

The single seam is the point: the deferred `--pick` selector resolves a
filter to an id and substitutes it into the invoking command, and against
three flag shapes that would have been three substitution paths.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013wPYq2Dp59HnoYsnzYbuYP
---
 .changeset/one-target-grammar.md |  48 +++++++
 README.md                        |  23 +++-
 docs/design.md                   |  92 +++++++++----
 scripts/smoke.mjs                |  26 +++-
 src/cli.ts                       | 154 +++++----------------
 src/commands/access.ts           | 197 ++++++++++-----------------
 src/commands/associations.ts     |  59 ++------
 src/index.ts                     |  19 +--
 src/target.ts                    | 225 +++++++++++++++++++++++++++++++
 tests/access.test.ts             | 117 ++++++++--------
 tests/associations.test.ts       |  94 ++++++-------
 tests/lifecycle.test.ts          |   2 +-
 tests/target.test.ts             | 123 +++++++++++++++++
 13 files changed, 728 insertions(+), 451 deletions(-)
 create mode 100644 .changeset/one-target-grammar.md
 create mode 100644 src/target.ts
 create mode 100644 tests/target.test.ts

diff --git a/.changeset/one-target-grammar.md b/.changeset/one-target-grammar.md
new file mode 100644
index 0000000..c0bdc12
--- /dev/null
+++ b/.changeset/one-target-grammar.md
@@ -0,0 +1,48 @@
+---
+'@haverstack/cli': minor
+---
+
+Name every association target the same way: one `--to`, parsed once, narrowed per command
+
+`link`, `perm` and `grant` each had their own way of spelling the other end — ten flags
+between them (`--to-record`, `--stack-url`, `--to-entity`, `--to-external`,
+`--external-id`, `--anyone`, `--entity`, `--group`, `--role`, `--authenticated`), three
+sets of "exactly one of" rules, and three shapes for what is, to the person typing, one
+idea. They now share `--to <target>`:
+
+```
+anyone                     the world, anonymous requesters included   (perm)
+authenticated              any entity holding a DID                   (grant)
+did:key:z6Mk…              an identity                                (all three)
+group:<id>/<member|admin>  a group's roster at one role               (perm, grant)
+record:<id>[@<stackUrl>]   a record, here or in another stack         (link)
+external:<ns>/<id>         something outside any stack                (link)
+```
+
+The vocabulary is the CLI's own and deliberately wider than any single core union. Core
+keeps three apart on purpose — a `RelationshipTarget` names no role, a
+`PermissionGrantee` has no record scope, and `anyone` is a kind rather than a grantee —
+and that split is right for the data model and wrong for a person, who is naming Alice
+either way. So one grammar parses, and each command narrows to the arms it accepts,
+refusing the rest by name. The narrowing is where core's distinctions are enforced.
+
+Exactly one shape is inferred: a leading `did:` is an entity, because a DID is the one
+identifier every command takes and `entity:did:key:…` reads badly on the most frequent
+call. Everything else names its scheme, and an unknown one is an error rather than a
+fallback. `external:` nests its namespace rather than sharing the top-level scheme slot,
+since `ns` is open and user-chosen — letting it compete with `group:`/`record:` would
+reserve words out of a namespace the CLI does not own.
+
+`formatTarget()` is `parseTarget()`'s inverse, so `perm ls` and `grant ls` now print
+targets unelided in the grammar their own commands accept: a listing row is a command
+argument. `grant ls --role any` becomes `--to group:<id>/any`, which also puts the
+listing widening and the world-read tier in structurally different slots instead of one
+letter apart.
+
+The single seam is the point. The deferred `--pick` selector resolves a filter to an id
+and substitutes it into the invoking command; against three flag shapes that would have
+been three substitution paths.
+
+`parseTarget`, `formatTarget` and the three narrowing functions are exported for anyone
+embedding the CLI. `buildRelationshipTarget` and the `PermTargetOptions` /
+`GrantTargetOptions` / `LinkTargetOptions` types are gone — the target is a string now.
diff --git a/README.md b/README.md
index 4aab6c8..d0f59c0 100644
--- a/README.md
+++ b/README.md
@@ -52,14 +52,31 @@ hstack ls <typeId>                 # list records of a type
 hstack show <id>                   # render one record
 hstack rm <id>                     # soft-delete; hstack restore <id> to undo
 hstack tag add <id> <label>        # tag a record outside an edit session
-hstack link add <id> --label <l> --to-record <otherId>
-hstack perm add <id> --entity <did> --read --write   # or --anyone, or --group <id> --role member
+hstack link add <id> --label <l> --to record:<otherId>
+hstack perm add <id> --to <did> --read --write
 hstack perm ls <id>                # who reaches this record
-hstack grant add <typeId> --entity <did> read-any    # or --authenticated, or --group + --role
+hstack grant add <typeId> --to <did> read-any
 hstack attach add <id> --label <l> --file <path>
 hstack types define <schema.json>  # register { id, name, schema, migratesFrom? }
 ```
 
+### Naming a target
+
+`link`, `perm` and `grant` all say who or what they mean with one `--to`:
+
+```
+anyone                     the world, anonymous requesters included   (perm)
+authenticated              any entity holding a DID                   (grant)
+did:key:z6Mk…              an identity                                (all three)
+group:<id>/<member|admin>  a group's roster at one role               (perm, grant)
+record:<id>[@<stackUrl>]   a record, here or in another stack         (link)
+external:<ns>/<id>         something outside any stack                (link)
+```
+
+One grammar, parsed in one place, narrowed per command — a target the command cannot name
+is refused by name rather than quietly misread. `perm ls` and `grant ls` print targets in
+the same grammar, unelided, so a listing row pastes straight back into a command.
+
 Tagging, linking, attaching, sharing and moving a record are **no-bump** writes in core:
 they leave `version` and `updatedAt` where they stand, so these commands report what the
 record now says rather than a version number that did not move. Record permissions are
diff --git a/docs/design.md b/docs/design.md
index 449dd68..cb5e724 100644
--- a/docs/design.md
+++ b/docs/design.md
@@ -377,25 +377,61 @@ subcommands are verb-first (`tag add <id> <label>`, not `tag <id> add <label>`)
 consistent with `stack add`/`types show` rather than the earlier sketch:
 
 ```
-hstack tag  add|rm <id> <label>
-hstack link add|rm <id> --label <l> ( --to-record <id> [--stack-url <u>]
-                                     | --to-entity <did>
-                                     | --to-external <ns> --external-id <id> )
-hstack perm add|rm <id> ( --anyone | --entity <did> | --group <id> --role <member|admin> )
-                         [--read] [--write]
-hstack perm ls <id>
-hstack grant add|rm <typeId> ( --entity <did> | --group <id> --role <member|admin>
-                              | --authenticated ) <action>...
-hstack grant ls [--type <typeId>] [--entity <did> | --group <id> [--role <r|any>]
-                                   | --authenticated]
+hstack tag   add|rm <id> <label>
+hstack link  add|rm <id> --label <l> --to <target>
+hstack perm  add|rm <id> --to <target> [--read] [--write]
+hstack perm  ls <id>
+hstack grant add|rm <typeId> --to <target> <action>...
+hstack grant ls [--type <typeId>] [--to <target>]
 ```
 
-`link` mirrors core's `RelationshipTarget` union exactly — a target names one identifier
-space (`record` / `entity` / `external`) one way, and an absent `--stack-url` means _this
-stack_, never a wildcard. `dissociate()` matches a target exactly, so `link rm` takes the
-same target flags `link add` did. Typing that union as YAML in a text file is precisely
-what a text editor is bad at; a command with validation and, later, tab-completion is
-better even before any picker exists.
+Typing a discriminated union as YAML in a text file is precisely what a text editor is
+bad at; a command with validation and, later, tab-completion is better even before any
+picker exists. All three name their other end the same way — see **Naming a target**
+below.
+
+### Naming a target
+
+`link`, `perm` and `grant` all take **`--to <target>`**, one grammar parsed in one place
+(`src/target.ts`) and narrowed per command:
+
+| `--to` value             | Resolves to                                             | Accepted by           |
+| ------------------------ | ------------------------------------------------------- | --------------------- |
+| `anyone`                 | `{ kind: 'anyone', label: 'read' }`                     | `perm`                |
+| `authenticated`          | `{ kind: 'authenticated' }`                             | `grant`               |
+| `did:key:z6Mk…`          | the entity arm — sugar for `entity:`                    | `perm` `grant` `link` |
+| `entity:<did>`           | the entity arm                                          | `perm` `grant` `link` |
+| `group:<id>/<role>`      | the group arm; `member`, `admin`, or `any` when listing | `perm` `grant`        |
+| `record:<id>`            | `{ scope: 'record', recordId }`                         | `link`                |
+| `record:<id>@<stackUrl>` | …in another stack                                       | `link`                |
+| `external:<ns>/<id>`     | `{ scope: 'external', ns, id }`                         | `link`                |
+
+**This vocabulary is the CLI's own, and deliberately wider than any single core union.**
+Core keeps three apart on purpose — a `RelationshipTarget` names no role, a
+`PermissionGrantee` has no record scope, and `anyone` is a kind rather than a grantee,
+so no dropped field can produce world-read. That split is right for the data model and
+wrong for a person, who is naming Alice either way. So the CLI parses one grammar and
+each command narrows to the arms it accepts, refusing the rest by name
+(`record:01hx… is not something `perm` can name`). The narrowing is where core's
+distinctions are enforced; the grammar is where the human convenience lives. Anything
+that blurs the two — a `perm` that quietly accepted a record target, say — is a bug.
+
+Three rules keep the grammar honest:
+
+- **Exactly one shape is inferred**: a leading `did:` is an entity. A DID is the one
+  identifier every command takes, and `entity:did:key:…` reads badly on the most frequent
+  call. Everything else names its scheme, and an unknown one is an error rather than a
+  guess — core's `ExternalTarget` carries an explicit `ns` for the same reason.
+- **`external:` nests its namespace** rather than sharing the top-level scheme slot.
+  `ns` is open and user-chosen, so letting it compete with `group:`/`record:` would
+  reserve words out of a namespace the CLI does not own.
+- **`formatTarget()` is `parseTarget()`'s inverse**, so `perm ls` and `grant ls` print
+  targets unelided in the same grammar their commands accept. A listing row is a command
+  argument; copy-paste works, and the smoke test pins it.
+
+The single seam is the point. `--pick` (below, deferred) resolves a partial filter to an
+id and substitutes it into the invoking command — against three flag shapes that would be
+three substitution paths and three sets of rules about which flag it may fill.
 
 **`perm` writes one element at a time.** Record permissions are associations: the ACL is
 two kinds over the same table — `{ kind: 'permission', label: 'read'|'write', grantee }`,
@@ -406,9 +442,9 @@ calls those rather than the `permissions` change-set key. The key replaces the w
 so between the read it would need and the write, whatever a second admin granted is gone;
 a per-element write is the spelling that survives two people sharing one record at once.
 
-An element's identity is its bit plus its grantee, and `role` is **required** on a group —
+An element's identity is its bit plus its grantee, and a role is **required** on a group —
 member is the wider set, admin the narrower, and the two are different elements, so
-`--group` without `--role` is refused rather than guessed at. `--anyone` carries `read`
+`group:<id>` with no role is a parse error rather than a guess. `anyone` carries `read`
 and nothing else; `--write` beside it is refused rather than written and then bounced by
 core. `perm add --read --write` grants read first and `perm rm` withdraws write first,
 because core's cross-element invariant is that **no write lands in a set whose grantee
@@ -419,13 +455,12 @@ neither bit withdraws the target's access entirely; naming one withdraws just th
 `_readonly` block.
 
 `grant` actions are core's `GrantAction` set — `create`, `read-own`, `read-any`,
-`update-own`, `update-any`, `delete-own`, `delete-any`. Its grantee is core's
-`GrantGrantee` union, one required arm: `--entity <did>`, `--group <id> --role <r>`, or
-`--authenticated` (any entity holding a DID — the tier below `--anyone`, which also
-reaches anonymous requesters; the two never share a word). `grant ls` takes the same flags
-as a query, widened by the listing-only `--role any`; an `--entity` listing answers
-_coverage_ (grants naming them, their groups, and every authenticated grant), so it is not
-a preview of what `grant rm` would withdraw. Core enforces the action dependency (a
+`update-own`, `update-any`, `delete-own`, `delete-any`. Its `--to` is `authenticated`
+(any entity holding a DID — the tier below `anyone`, which also reaches anonymous
+requesters; the two never share a word), a DID, or a group at a role. `grant ls` takes
+the same `--to` as a query, widened by the listing-only `group:<id>/any`; a DID listing
+answers _coverage_ (grants naming them, their groups, and every authenticated grant), so
+it is not a preview of what `grant rm` would withdraw. Core enforces the action dependency (a
 `-any`/`-own` mutate action needs a matching-scope read action in the same grant) and
 names the missing one in its own error; the CLI does not re-derive that rule client-side,
 since a copy could disagree with the answer that actually governs the write. `revoke()`
@@ -536,8 +571,9 @@ owning app.
 
 - **`--pick` for association targets.** A short fuzzy-selector (backed by `stack.query()`)
   that resolves a partial filter to an id and substitutes it into the invoking `link` /
-  `perm` / `grant` command. Additive — it doesn't change the flag path — and the natural
-  place to grow toward a fuller interactive mode if flags prove clunky. Not a v1 blocker;
+  `perm` / `grant` command's `--to`. Additive — it fills one slot with a string the
+  grammar already accepts — and the natural place to grow toward a fuller interactive
+  mode if flags prove clunky. Not a v1 blocker;
   revisit once it's clear which commands get used with unfamiliar ids often enough.
 - **Watch / live status.** The CLI reads and writes on demand; a `hstack watch` over
   `stack.subscribe` (server only — `LocalAdapter` has no `subscribeChanges`) is possible
diff --git a/scripts/smoke.mjs b/scripts/smoke.mjs
index 59d8334..7257da3 100644
--- a/scripts/smoke.mjs
+++ b/scripts/smoke.mjs
@@ -77,19 +77,35 @@ async function main() {
     '`tag add` associated the tag',
   );
 
-  run('perm', 'add', id, '--anyone');
+  run('perm', 'add', id, '--to', 'anyone');
   const shared = JSON.parse(run('show', id, '--json'));
   check(
     (shared.permissions ?? []).some((p) => p.kind === 'anyone' && p.label === 'read'),
-    '`perm add --anyone` wrote an `anyone` element',
+    '`perm add --to anyone` wrote an `anyone` element',
   );
   check(shared.version === tagged.version, 'tagging and sharing are no-bump writes');
-  check(run('perm', 'ls', id).includes('anyone'), '`perm ls` shows who reaches it');
-  run('perm', 'rm', id, '--anyone');
+
+  // The listing prints targets in --to's own grammar, so a row is a command.
+  const permRow = run('perm', 'ls', id)
+    .trim()
+    .split('\n')
+    .at(-1)
+    .split(/\s{2,}/)[0];
+  check(permRow === 'anyone', `\`perm ls\` prints the target as --to takes it (${permRow})`);
+  run('perm', 'rm', id, '--to', permRow);
   check(
     (JSON.parse(run('show', id, '--json')).permissions ?? []).length === 0,
-    '`perm rm --anyone` withdrew it',
+    '`perm ls` output feeds straight back into `perm rm`',
+  );
+
+  run('link', 'add', id, '--label', 'mirrors', '--to', 'external:atproto/at://x/y');
+  check(
+    (JSON.parse(run('show', id, '--json')).associations ?? []).some(
+      (a) => a.kind === 'relationship' && a.target?.ns === 'atproto' && a.target?.id === 'at://x/y',
+    ),
+    '`link add --to external:<ns>/<id>` splits on the first slash only',
   );
+  run('link', 'rm', id, '--label', 'mirrors', '--to', 'external:atproto/at://x/y');
 
   run('rm', id);
   const afterRm = JSON.parse(run('ls', TYPE_ID, '--json'));
diff --git a/src/cli.ts b/src/cli.ts
index 2d55cce..ebd6e12 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -54,6 +54,11 @@ const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url),
   version: string;
 };
 
+/** Shown in --to's help, per command, so the accepted arms are on screen. */
+const TARGET_HINT = '<did> | record:<id>[@<stackUrl>] | external:<ns>/<id>';
+const PERM_TARGETS = 'anyone | <did> | group:<id>/<member|admin>';
+const GRANT_TARGETS = 'authenticated | <did> | group:<id>/<member|admin>';
+
 const program = new Command();
 
 program
@@ -434,55 +439,26 @@ const link = program.command('link').description('Add or remove a relationship a
 function linkOptions(cmd: Command) {
   return cmd
     .requiredOption('--label <label>', 'the relationship label')
-    .option('--to-record <id>', 'target a record in this stack (or another, with --stack-url)')
-    .option('--stack-url <url>', 'the target record lives in this other stack')
-    .option('--to-entity <did>', 'target an identity')
-    .option('--to-external <ns>', 'target something outside any stack, in this namespace')
-    .option('--external-id <id>', 'the identifier within --to-external’s namespace');
+    .requiredOption('--to <target>', `what to link to (${TARGET_HINT})`);
 }
 
-type LinkCliOptions = {
-  label: string;
-  toRecord?: string;
-  stackUrl?: string;
-  toEntity?: string;
-  toExternal?: string;
-  externalId?: string;
-};
-
 linkOptions(link.command('add <id>'))
   .description('Link a record to a target')
-  .action(async function (this: Command, id: string, opts: LinkCliOptions) {
+  .action(async function (this: Command, id: string, opts: { label: string; to: string }) {
     const opened = await open(this);
     try {
-      out(
-        await linkAdd(opened.stack, id, opts.label, {
-          toRecord: opts.toRecord,
-          stackUrl: opts.stackUrl,
-          toEntity: opts.toEntity,
-          toExternalNs: opts.toExternal,
-          externalId: opts.externalId,
-        }),
-      );
+      out(await linkAdd(opened.stack, id, opts.label, opts.to));
     } finally {
       await opened.close();
     }
   });
 
 linkOptions(link.command('rm <id>'))
-  .description('Remove a link (same target flags as when it was added)')
-  .action(async function (this: Command, id: string, opts: LinkCliOptions) {
+  .description('Remove a link (the same --to it was added with)')
+  .action(async function (this: Command, id: string, opts: { label: string; to: string }) {
     const opened = await open(this);
     try {
-      out(
-        await linkRemove(opened.stack, id, opts.label, {
-          toRecord: opts.toRecord,
-          stackUrl: opts.stackUrl,
-          toEntity: opts.toEntity,
-          toExternalNs: opts.toExternal,
-          externalId: opts.externalId,
-        }),
-      );
+      out(await linkRemove(opened.stack, id, opts.label, opts.to));
     } finally {
       await opened.close();
     }
@@ -490,46 +466,23 @@ linkOptions(link.command('rm <id>'))
 
 const perm = program
   .command('perm')
-  .description('Add, remove, or list record permissions (read/write, per grantee)');
+  .description('Add, remove, or list record permissions (read/write, per target)');
 
 function permOptions(cmd: Command) {
   return cmd
-    .option('--anyone', 'reach the world, anonymous requesters included (read only)')
-    .option('--entity <did>', 'this identity')
-    .option('--group <id>', 'this group, at --role')
-    .option('--role <role>', 'which half of a --group: "member" (wider) or "admin"', permRole)
+    .requiredOption('--to <target>', `who reaches it (${PERM_TARGETS})`)
     .option('--read', 'the read bit')
     .option('--write', 'the write bit (core refuses a writer who cannot read)');
 }
 
-type PermCliOptions = {
-  anyone?: boolean;
-  entity?: string;
-  group?: string;
-  role?: 'member' | 'admin';
-  read?: boolean;
-  write?: boolean;
-};
-
-function permRole(value: string): 'member' | 'admin' {
-  if (value !== 'member' && value !== 'admin') {
-    throw new InvalidArgumentError('--role must be "member" or "admin"');
-  }
-  return value;
-}
-
-function permTarget(opts: PermCliOptions) {
-  return { anyone: opts.anyone, entity: opts.entity, group: opts.group, role: opts.role };
-}
+type PermCliOptions = { to: string; read?: boolean; write?: boolean };
 
 permOptions(perm.command('add <id>'))
   .description('Grant record-level access')
   .action(async function (this: Command, id: string, opts: PermCliOptions) {
     const opened = await open(this);
     try {
-      out(
-        await permAdd(opened.stack, id, permTarget(opts), Boolean(opts.read), Boolean(opts.write)),
-      );
+      out(await permAdd(opened.stack, id, opts.to, Boolean(opts.read), Boolean(opts.write)));
     } finally {
       await opened.close();
     }
@@ -540,15 +493,7 @@ permOptions(perm.command('rm <id>'))
   .action(async function (this: Command, id: string, opts: PermCliOptions) {
     const opened = await open(this);
     try {
-      out(
-        await permRemove(
-          opened.stack,
-          id,
-          permTarget(opts),
-          Boolean(opts.read),
-          Boolean(opts.write),
-        ),
-      );
+      out(await permRemove(opened.stack, id, opts.to, Boolean(opts.read), Boolean(opts.write)));
     } finally {
       await opened.close();
     }
@@ -556,7 +501,7 @@ permOptions(perm.command('rm <id>'))
 
 perm
   .command('ls <id>')
-  .description('List who reaches a record')
+  .description('List who reaches a record, in --to’s own grammar')
   .option('--json', 'output raw JSON')
   .action(async function (this: Command, id: string, opts: { json?: boolean }) {
     const opened = await open(this);
@@ -569,74 +514,41 @@ perm
 
 const grant = program.command('grant').description('Add, remove, or list type-level grants');
 
-function grantRole(allowAny: boolean) {
-  return (value: string): 'member' | 'admin' | 'any' => {
-    const allowed = allowAny ? ['"member"', '"admin"', '"any"'] : ['"member"', '"admin"'];
-    if (!allowed.includes(`"${value}"`)) {
-      const named = `${allowed.slice(0, -1).join(', ')} or ${allowed.at(-1)}`;
-      throw new InvalidArgumentError(`--role must be ${named}`);
-    }
-    return value as 'member' | 'admin' | 'any';
-  };
-}
-
-function grantOptions(cmd: Command, allowAny = false) {
-  return cmd
-    .option('--entity <did>', 'this identity')
-    .option('--group <id>', 'this group, at --role')
-    .option(
-      '--role <role>',
-      allowAny
-        ? 'which half of a --group: "member", "admin", or "any" (default)'
-        : 'which half of a --group: "member" (wider) or "admin"',
-      grantRole(allowAny),
-    )
-    .option('--authenticated', 'any entity holding a DID');
-}
-
-type GrantCliOptions = {
-  entity?: string;
-  group?: string;
-  role?: 'member' | 'admin' | 'any';
-  authenticated?: boolean;
-};
-
-const grantTarget = (opts: GrantCliOptions) => ({
-  entity: opts.entity,
-  group: opts.group,
-  role: opts.role,
-  authenticated: opts.authenticated,
-});
-
-grantOptions(grant.command('add <typeId> <actions...>'))
+grant
+  .command('add <typeId> <actions...>')
   .description('Grant create/read/update/delete on a type family')
-  .action(async function (this: Command, typeId: string, actions: string[], opts: GrantCliOptions) {
+  .requiredOption('--to <target>', `who to grant (${GRANT_TARGETS})`)
+  .action(async function (this: Command, typeId: string, actions: string[], opts: { to: string }) {
     const opened = await open(this);
     try {
-      out(await grantAdd(opened.stack, typeId, grantTarget(opts), actions as GrantAction[]));
+      out(await grantAdd(opened.stack, typeId, opts.to, actions as GrantAction[]));
     } finally {
       await opened.close();
     }
   });
 
-grantOptions(grant.command('rm <typeId> <actions...>'))
+grant
+  .command('rm <typeId> <actions...>')
   .description('Revoke actions granted on a type family')
-  .action(async function (this: Command, typeId: string, actions: string[], opts: GrantCliOptions) {
+  .requiredOption('--to <target>', `whose grant to withdraw (${GRANT_TARGETS})`)
+  .action(async function (this: Command, typeId: string, actions: string[], opts: { to: string }) {
     const opened = await open(this);
     try {
-      out(await grantRemove(opened.stack, typeId, grantTarget(opts), actions as GrantAction[]));
+      out(await grantRemove(opened.stack, typeId, opts.to, actions as GrantAction[]));
     } finally {
       await opened.close();
     }
   });
 
-grantOptions(grant.command('ls'), true)
-  .description('List grants — narrow by --type and/or a grantee')
+grant
+  .command('ls')
+  .description('List grants — narrow by --type and/or --to')
   .option('--type <typeId>', 'only this type')
-  .action(async function (this: Command, opts: GrantCliOptions & { type?: string }) {
+  .option('--to <target>', `only this target (group:<id>/any widens over roles)`)
+  .action(async function (this: Command, opts: { type?: string; to?: string }) {
     const opened = await open(this);
     try {
-      out(await grantList(opened.stack, opts.type, grantTarget(opts)));
+      out(await grantList(opened.stack, opts.type, opts.to));
     } finally {
       await opened.close();
     }
diff --git a/src/commands/access.ts b/src/commands/access.ts
index f4334ed..5485594 100644
--- a/src/commands/access.ts
+++ b/src/commands/access.ts
@@ -5,74 +5,56 @@
  * Record permissions are associations: one element per bit per grantee,
  * added and withdrawn one at a time by `grantAccess()`/`revokeAccess()`.
  * Both verbs are no-bump, and neither restates the rest of the ACL, so two
- * people sharing one record cannot overwrite each other.
+ * people sharing one record cannot overwrite each other. Both commands
+ * name their target with `--to` (src/target.ts).
  * See docs/design.md § Associations.
  */
 
-import type {
-  AuthorityAssociation,
-  GrantAction,
-  PermissionGrantee,
-  RecordId,
-  Stack,
-  StackRecord,
-} from '@haverstack/core';
-import { shortDid } from '../config.js';
+import type { AuthorityAssociation, GrantAction, Stack, StackRecord } from '@haverstack/core';
+import {
+  formatTarget,
+  grantQueryOf,
+  grantTargetOf,
+  parseTarget,
+  permissionTargetOf,
+  targetOfPermission,
+  type GrantQuery,
+  type GrantTarget,
+  type PermissionTarget,
+  type Target,
+} from '../target.js';
 
 // ---------------------------------------------------------------- perm
 
-export type PermTargetOptions = {
-  anyone?: boolean;
-  entity?: string;
-  group?: string;
-  role?: 'member' | 'admin';
-};
-
-/** `anyone` has no grantee at all, which is what makes it its own arm. */
-type PermTarget = { scope: 'anyone' } | PermissionGrantee;
-
 type Bits = { read: boolean; write: boolean };
 
-function resolvePermTarget(opts: PermTargetOptions): PermTarget {
-  const picked = ['anyone', 'entity', 'group'].filter((k) => opts[k as keyof PermTargetOptions]);
-  if (picked.length !== 1) throw new Error('Pass exactly one of --anyone, --entity, or --group.');
-  if (opts.anyone) return { scope: 'anyone' };
-  if (opts.entity) return { scope: 'entity', entityId: opts.entity };
-  if (!opts.role) {
-    throw new Error('--group needs --role member or --role admin — a permission names one role.');
-  }
-  return { scope: 'group', groupId: opts.group!, role: opts.role };
-}
-
 /** The element a target + bit names, or null where the pair names none. */
-function elementFor(target: PermTarget, label: 'read' | 'write'): AuthorityAssociation | null {
+function elementFor(
+  target: PermissionTarget,
+  label: 'read' | 'write',
+): AuthorityAssociation | null {
   if (target.scope === 'anyone') return label === 'read' ? { kind: 'anyone', label: 'read' } : null;
   return { kind: 'permission', label, grantee: target };
 }
 
-function granteeMatches(a: PermissionGrantee, b: PermissionGrantee): boolean {
+function sameGrantee(a: PermissionTarget, b: PermissionTarget): boolean {
   if (a.scope !== b.scope) return false;
   if (a.scope === 'entity' && b.scope === 'entity') return a.entityId === b.entityId;
   if (a.scope === 'group' && b.scope === 'group') {
     return a.groupId === b.groupId && a.role === b.role;
   }
-  return false;
+  return a.scope === 'anyone';
 }
 
-function bitsOf(permissions: AuthorityAssociation[] | undefined, target: PermTarget): Bits {
-  const held = (label: 'read' | 'write') =>
-    (permissions ?? []).some((p) =>
-      target.scope === 'anyone'
-        ? p.kind === 'anyone' && label === 'read'
-        : p.kind === 'permission' && p.label === label && granteeMatches(p.grantee, target),
-    );
-  return { read: held('read'), write: held('write') };
+/** An ACL element as the target it names, so both halves compare as one. */
+function granteeOf(p: AuthorityAssociation): PermissionTarget {
+  return p.kind === 'anyone' ? { scope: 'anyone' } : p.grantee;
 }
 
-function describePermTarget(target: PermTarget): string {
-  if (target.scope === 'anyone') return 'anyone';
-  if (target.scope === 'entity') return shortDid(target.entityId);
-  return `group:${target.groupId}:${target.role}`;
+function bitsOf(permissions: AuthorityAssociation[] | undefined, target: PermissionTarget): Bits {
+  const held = (label: 'read' | 'write') =>
+    (permissions ?? []).some((p) => p.label === label && sameGrantee(granteeOf(p), target));
+  return { read: held('read'), write: held('write') };
 }
 
 function describeBits(bits: Bits): string {
@@ -89,13 +71,14 @@ async function requireRecord(stack: Stack, id: string): Promise<StackRecord> {
 export async function permAdd(
   stack: Stack,
   id: string,
-  targetOpts: PermTargetOptions,
+  to: string,
   read: boolean,
   write: boolean,
 ): Promise<string> {
-  const target = resolvePermTarget(targetOpts);
+  const parsed = parseTarget(to);
+  const target = permissionTargetOf(parsed);
   if (target.scope === 'anyone' && write) {
-    throw new Error('--anyone carries read only. Name a --entity or --group to grant write.');
+    throw new Error('`anyone` carries read only. Name a DID or a group to grant write.');
   }
   // `anyone` has exactly one bit, so naming it is naming the whole element.
   if (target.scope === 'anyone') read = true;
@@ -110,7 +93,7 @@ export async function permAdd(
   if (write) record = await stack.grantAccess(id, elementFor(target, 'write')!);
 
   const after = bitsOf(record!.permissions, target);
-  const who = describePermTarget(target);
+  const who = formatTarget(parsed);
   return before.read === after.read && before.write === after.write
     ? `${id}: ${who} could already ${describeBits(after)} — nothing to do.`
     : `${id}: ${who} can now ${describeBits(after)}.`;
@@ -119,18 +102,19 @@ export async function permAdd(
 export async function permRemove(
   stack: Stack,
   id: string,
-  targetOpts: PermTargetOptions,
+  to: string,
   read: boolean,
   write: boolean,
 ): Promise<string> {
-  const target = resolvePermTarget(targetOpts);
+  const parsed = parseTarget(to);
+  const target = permissionTargetOf(parsed);
   // Naming no bit withdraws the target's access entirely.
   if (!read && !write) {
     read = true;
     write = target.scope !== 'anyone';
   }
   if (target.scope === 'anyone' && write) {
-    throw new Error('--anyone carries read only — there is no write bit to remove.');
+    throw new Error('`anyone` carries read only — there is no write bit to remove.');
   }
 
   const before = bitsOf((await requireRecord(stack, id)).permissions, target);
@@ -141,7 +125,7 @@ export async function permRemove(
   if (read) record = await stack.revokeAccess(id, elementFor(target, 'read')!);
 
   const after = bitsOf(record!.permissions, target);
-  const who = describePermTarget(target);
+  const who = formatTarget(parsed);
   if (before.read === after.read && before.write === after.write) {
     return `${id}: ${who} had no ${describeBits({ read, write })} to remove — nothing to do.`;
   }
@@ -153,8 +137,8 @@ export async function permRemove(
 /**
  * Who reaches a record. The stored form is one element per bit, which is
  * what `--json` and `_readonly` show; this collapses the two bits a
- * grantee may hold onto one line, since "who reaches this" is the question
- * being asked.
+ * grantee may hold onto one line. Targets print in `--to`'s own grammar,
+ * unelided, so a row can be pasted straight back into a command.
  */
 export async function permList(stack: Stack, id: string, json: boolean): Promise<string> {
   const record = await requireRecord(stack, id);
@@ -162,84 +146,43 @@ export async function permList(stack: Stack, id: string, json: boolean): Promise
   if (json) return JSON.stringify(permissions, null, 2);
   if (permissions.length === 0) return `${id} is private — only the stack owner reaches it.`;
 
-  const byGrantee = new Map<string, Bits>();
+  const byTarget = new Map<string, Bits>();
   for (const p of permissions) {
-    const who = p.kind === 'anyone' ? 'anyone' : describePermTarget(p.grantee);
-    const bits = byGrantee.get(who) ?? { read: false, write: false };
+    const who = formatTarget(targetOfPermission(granteeOf(p)));
+    const bits = byTarget.get(who) ?? { read: false, write: false };
     bits[p.label] = true;
-    byGrantee.set(who, bits);
+    byTarget.set(who, bits);
   }
 
-  const whoW = Math.max('GRANTEE'.length, ...[...byGrantee.keys()].map((w) => w.length));
+  const whoW = Math.max('TARGET'.length, ...[...byTarget.keys()].map((w) => w.length));
   return [
-    `${'GRANTEE'.padEnd(whoW)}  ACCESS`,
-    ...[...byGrantee].map(([who, bits]) => `${who.padEnd(whoW)}  ${describeBits(bits)}`),
+    `${'TARGET'.padEnd(whoW)}  ACCESS`,
+    ...[...byTarget].map(([who, bits]) => `${who.padEnd(whoW)}  ${describeBits(bits)}`),
   ].join('\n');
 }
 
 // ---------------------------------------------------------------- grant
 
-/**
- * Core's `GrantGrantee` union as flags. `role: 'any'` is listing-only —
- * `grant`/`revoke` name one role, since a grant to a group's admins is not
- * the grant to its members.
- */
-export type GrantTargetOptions = {
-  entity?: string;
-  group?: string;
-  role?: 'member' | 'admin' | 'any';
-  authenticated?: boolean;
-};
-
-type GrantGrantee =
-  | { kind: 'entity'; entityId: string }
-  | { kind: 'group'; groupId: RecordId; role: 'member' | 'admin' }
-  | { kind: 'authenticated' };
-
-type GrantQuery =
-  | { kind: 'entity'; entityId: string }
-  | { kind: 'group'; groupId: RecordId; role: 'member' | 'admin' | 'any' }
-  | { kind: 'authenticated' };
-
-function resolveGrantTarget(opts: GrantTargetOptions): GrantGrantee {
-  const query = resolveGrantQuery(opts, false);
-  if (!query) throw new Error('Pass exactly one of --entity, --group, or --authenticated.');
-  return query as GrantGrantee;
-}
-
-/** The same union, widened for a listing: `--group` alone means any role. */
-function resolveGrantQuery(opts: GrantTargetOptions, allowAny: boolean): GrantQuery | undefined {
-  const picked = ['entity', 'group', 'authenticated'].filter(
-    (k) => opts[k as keyof GrantTargetOptions],
-  );
-  if (picked.length === 0) return undefined;
-  if (picked.length > 1) throw new Error('Pass at most one of --entity, --group, --authenticated.');
-  if (opts.entity) return { kind: 'entity', entityId: opts.entity };
-  if (opts.authenticated) return { kind: 'authenticated' };
-  if (opts.role === 'any' && !allowAny) {
-    throw new Error('--role any is for `grant ls` — a grant names member or admin.');
-  }
-  const role = opts.role ?? (allowAny ? 'any' : undefined);
-  if (!role) {
-    throw new Error('--group needs --role member or --role admin — a grant names one role.');
-  }
-  return { kind: 'group', groupId: opts.group!, role };
-}
+const grantTargetFrom = (to: string): GrantTarget => grantTargetOf(parseTarget(to));
 
+/** A stored grant's grantee as a `--to` string, for a listing's output. */
 function describeGrantee(grantee: GrantQuery | undefined): string {
   if (!grantee) return '—';
-  if (grantee.kind === 'entity') return shortDid(grantee.entityId);
-  if (grantee.kind === 'group') return `group:${grantee.groupId}:${grantee.role}`;
+  if (grantee.kind === 'entity')
+    return formatTarget({ kind: 'entity', entityId: grantee.entityId });
+  if (grantee.kind === 'group') {
+    return formatTarget({ kind: 'group', groupId: grantee.groupId, role: grantee.role });
+  }
   return 'authenticated';
 }
 
 export async function grantAdd(
   stack: Stack,
   typeId: string,
-  targetOpts: GrantTargetOptions,
+  to: string,
   actions: GrantAction[],
 ): Promise<string> {
-  const target = resolveGrantTarget(targetOpts);
+  const target = grantTargetFrom(to);
   await stack.grant(target, [{ typeId, actions }]);
   return `Granted ${describeGrantee(target)} [${actions.join(', ')}] on ${typeId}.`;
 }
@@ -247,22 +190,19 @@ export async function grantAdd(
 export async function grantRemove(
   stack: Stack,
   typeId: string,
-  targetOpts: GrantTargetOptions,
+  to: string,
   actions: GrantAction[],
 ): Promise<string> {
-  const target = resolveGrantTarget(targetOpts);
+  const target = grantTargetFrom(to);
   const withdrawn = await stack.revoke(target, [{ typeId, actions }]);
+  const what = `${describeGrantee(target)} [${actions.join(', ')}] on ${typeId}`;
   return withdrawn.length === 0
-    ? `No grant matched ${describeGrantee(target)} [${actions.join(', ')}] on ${typeId} — nothing to revoke.`
-    : `Revoked ${withdrawn.length} grant(s): ${describeGrantee(target)} [${actions.join(', ')}] on ${typeId}.`;
+    ? `No grant matched ${what} — nothing to revoke.`
+    : `Revoked ${withdrawn.length} grant(s): ${what}.`;
 }
 
-export async function grantList(
-  stack: Stack,
-  typeId?: string,
-  targetOpts: GrantTargetOptions = {},
-): Promise<string> {
-  const query = resolveGrantQuery(targetOpts, true);
+export async function grantList(stack: Stack, typeId?: string, to?: string): Promise<string> {
+  const query = to === undefined ? undefined : grantQueryOf(parseTarget(to));
   const all = await stack.listGrants(query);
   const rows = (
     typeId ? all.filter((r) => (r.content as { typeId: string }).typeId === typeId) : all
@@ -271,13 +211,12 @@ export async function grantList(
   if (rows.length === 0) return 'No grants.';
 
   const typeW = Math.max(4, ...rows.map((g) => g.typeId.length));
-  const granteeW = Math.max(
-    'GRANTEE'.length,
-    ...rows.map((g) => describeGrantee(g.grantee).length),
-  );
+  const targetW = Math.max('TARGET'.length, ...rows.map((g) => describeGrantee(g.grantee).length));
   const lines = rows.map(
     (g) =>
-      `${g.typeId.padEnd(typeW)}  ${describeGrantee(g.grantee).padEnd(granteeW)}  ${g.actions.join(', ')}`,
+      `${g.typeId.padEnd(typeW)}  ${describeGrantee(g.grantee).padEnd(targetW)}  ${g.actions.join(', ')}`,
   );
-  return [`${'TYPE'.padEnd(typeW)}  ${'GRANTEE'.padEnd(granteeW)}  ACTIONS`, ...lines].join('\n');
+  return [`${'TYPE'.padEnd(typeW)}  ${'TARGET'.padEnd(targetW)}  ACTIONS`, ...lines].join('\n');
 }
+
+export type { Target };
diff --git a/src/commands/associations.ts b/src/commands/associations.ts
index e04ba06..8e84c99 100644
--- a/src/commands/associations.ts
+++ b/src/commands/associations.ts
@@ -4,6 +4,7 @@
  * target union into a text file is exactly what a text editor is bad at;
  * this is the porcelain half of docs/design.md § Associations — a hybrid
  * split (`tags:` in front matter covers the common case day to day).
+ * `link` names its target with `--to` (src/target.ts).
  *
  * These are **no-bump** writes (core 0.33): they leave `version` and
  * `updatedAt` where they stand, so there is no version to report back and
@@ -11,7 +12,8 @@
  * distinguishes "done" from "already so".
  */
 
-import type { Association, RelationshipTarget, Stack, StackRecord } from '@haverstack/core';
+import type { Association, Stack, StackRecord } from '@haverstack/core';
+import { formatTarget, parseTarget, relationshipTargetOf } from '../target.js';
 
 async function requireRecord(stack: Stack, id: string): Promise<StackRecord> {
   const record = await stack.get(id);
@@ -43,57 +45,17 @@ export async function tagRemove(stack: Stack, id: string, label: string): Promis
   return `${id} is no longer tagged "${label}".`;
 }
 
-export type LinkTargetOptions = {
-  toRecord?: string;
-  stackUrl?: string;
-  toEntity?: string;
-  toExternalNs?: string;
-  externalId?: string;
-};
-
-/** Core's `RelationshipTarget` union, built from exactly one target flag group. */
-export function buildRelationshipTarget(opts: LinkTargetOptions): RelationshipTarget {
-  const picked = ['toRecord', 'toEntity', 'toExternalNs'].filter(
-    (k) => opts[k as keyof LinkTargetOptions] !== undefined,
-  );
-  if (picked.length !== 1) {
-    throw new Error('Pass exactly one of --to-record, --to-entity, or --to-external <ns>.');
-  }
-
-  if (opts.toRecord !== undefined) {
-    return {
-      scope: 'record',
-      recordId: opts.toRecord,
-      ...(opts.stackUrl && { stackUrl: opts.stackUrl }),
-    };
-  }
-  if (opts.toEntity !== undefined) {
-    return { scope: 'entity', entityId: opts.toEntity };
-  }
-  if (!opts.externalId) {
-    throw new Error('--to-external needs --external-id <id> alongside it.');
-  }
-  return { scope: 'external', ns: opts.toExternalNs!, id: opts.externalId };
-}
-
-function describeTarget(target: RelationshipTarget): string {
-  if (target.scope === 'record') {
-    return target.stackUrl ? `${target.recordId} @ ${target.stackUrl}` : target.recordId;
-  }
-  if (target.scope === 'entity') return target.entityId;
-  return `${target.ns}:${target.id}`;
-}
-
 export async function linkAdd(
   stack: Stack,
   id: string,
   label: string,
-  targetOpts: LinkTargetOptions,
+  to: string,
 ): Promise<string> {
+  const parsed = parseTarget(to);
   const before = await requireRecord(stack, id);
-  const target = buildRelationshipTarget(targetOpts);
+  const target = relationshipTargetOf(parsed);
   const after = await stack.associate(id, { kind: 'relationship', label, target });
-  const arrow = `${id} --${label}--> ${describeTarget(target)}`;
+  const arrow = `${id} --${label}--> ${formatTarget(parsed)}`;
   return count(after) === count(before) ? `${arrow} — already linked.` : `${arrow}.`;
 }
 
@@ -101,12 +63,13 @@ export async function linkRemove(
   stack: Stack,
   id: string,
   label: string,
-  targetOpts: LinkTargetOptions,
+  to: string,
 ): Promise<string> {
+  const parsed = parseTarget(to);
   const before = await requireRecord(stack, id);
-  const target = buildRelationshipTarget(targetOpts);
+  const target = relationshipTargetOf(parsed);
   const after = await stack.dissociate(id, { kind: 'relationship', label, target });
-  const arrow = `${id} --${label}--> ${describeTarget(target)}`;
+  const arrow = `${id} --${label}--> ${formatTarget(parsed)}`;
   return count(after) === count(before)
     ? `No such link: ${arrow} — nothing to remove.`
     : `Removed ${arrow}.`;
diff --git a/src/index.ts b/src/index.ts
index 5815619..95c2902 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -22,14 +22,18 @@ export {
 export type { ListOptions, ShowOptions } from './commands/records.js';
 export { stackAdd, stackList, stackUse, stackRemove } from './commands/stack.js';
 
+export { tagAdd, tagRemove, linkAdd, linkRemove } from './commands/associations.js';
 export {
-  tagAdd,
-  tagRemove,
-  linkAdd,
-  linkRemove,
-  buildRelationshipTarget,
-} from './commands/associations.js';
-export type { LinkTargetOptions } from './commands/associations.js';
+  parseTarget,
+  formatTarget,
+  permissionTargetOf,
+  grantTargetOf,
+  grantQueryOf,
+  relationshipTargetOf,
+  targetOfPermission,
+  targetOfRelationship,
+} from './target.js';
+export type { Target, TargetRole, PermissionTarget, GrantTarget, GrantQuery } from './target.js';
 export {
   permAdd,
   permList,
@@ -38,7 +42,6 @@ export {
   grantRemove,
   grantList,
 } from './commands/access.js';
-export type { PermTargetOptions, GrantTargetOptions } from './commands/access.js';
 export { attachAdd, attachRemove } from './commands/attach.js';
 
 export { newRecord, editRecord, editStatus, commitEdit, discardEdit } from './commands/edit.js';
diff --git a/src/target.ts b/src/target.ts
new file mode 100644
index 0000000..c487675
--- /dev/null
+++ b/src/target.ts
@@ -0,0 +1,225 @@
+/**
+ * `--to` — the one way this CLI names the other end of an association.
+ *
+ * Core keeps three unions apart on purpose: a `RelationshipTarget` names
+ * no role, a `PermissionGrantee` has no record scope, and `anyone` is a
+ * kind of its own rather than a grantee. This vocabulary is deliberately
+ * wider than any one of them and is narrowed per command, so a person
+ * naming Alice writes the same thing wherever they are and `--pick` has
+ * one seam to substitute into.
+ * See docs/design.md § Naming a target.
+ */
+
+import type { EntityId, RecordId, RelationshipTarget } from '@haverstack/core';
+
+/** `any` is listing-only — `grant ls` widens on it; nothing writes it. */
+export type TargetRole = 'member' | 'admin' | 'any';
+
+export type Target =
+  | { kind: 'anyone' }
+  | { kind: 'authenticated' }
+  | { kind: 'entity'; entityId: EntityId }
+  | { kind: 'group'; groupId: RecordId; role: TargetRole }
+  | { kind: 'record'; recordId: RecordId; stackUrl?: string }
+  | { kind: 'external'; ns: string; id: string };
+
+/** What a permission names: `anyone` carries no grantee, the rest do. */
+export type PermissionTarget =
+  | { scope: 'anyone' }
+  | { scope: 'entity'; entityId: EntityId }
+  | { scope: 'group'; groupId: RecordId; role: 'member' | 'admin' };
+
+/** What `grant()`/`revoke()` write — one role, never the listing widening. */
+export type GrantTarget =
+  | { kind: 'entity'; entityId: EntityId }
+  | { kind: 'group'; groupId: RecordId; role: 'member' | 'admin' }
+  | { kind: 'authenticated' };
+
+/** What `listGrants()` accepts — the same union, widened by `role: 'any'`. */
+export type GrantQuery =
+  | { kind: 'entity'; entityId: EntityId }
+  | { kind: 'group'; groupId: RecordId; role: TargetRole }
+  | { kind: 'authenticated' };
+
+const GRAMMAR =
+  'anyone | authenticated | <did> | entity:<did> | group:<id>/<member|admin> | ' +
+  'record:<id>[@<stackUrl>] | external:<ns>/<id>';
+
+function reject(problem: string): never {
+  throw new Error(`${problem}\n  --to takes one of: ${GRAMMAR}`);
+}
+
+/**
+ * A `--to` value as its tagged form. Exactly one shape is inferred rather
+ * than spelled — a leading `did:` is an entity — because a DID is the one
+ * identifier common to every command and `entity:did:key:…` reads badly on
+ * the most frequent call. Everything else names its scheme, so an unknown
+ * one is an error rather than a guess.
+ */
+export function parseTarget(value: string): Target {
+  const raw = value.trim();
+  if (!raw) reject('A target cannot be empty.');
+  if (raw === 'anyone') return { kind: 'anyone' };
+  if (raw === 'authenticated') return { kind: 'authenticated' };
+  if (raw.startsWith('did:')) return entityTarget(raw);
+
+  const colon = raw.indexOf(':');
+  if (colon === -1) reject(`"${raw}" names no scheme.`);
+  const rest = raw.slice(colon + 1);
+
+  switch (raw.slice(0, colon)) {
+    case 'entity':
+      return entityTarget(rest);
+    case 'group':
+      return groupTarget(rest);
+    case 'record':
+      return recordTarget(rest);
+    case 'external':
+      return externalTarget(rest);
+    default:
+      reject(`"${raw.slice(0, colon)}" is not a target scheme.`);
+  }
+}
+
+function entityTarget(did: string): Target {
+  if (!did) reject('An entity target needs a DID.');
+  return { kind: 'entity', entityId: did };
+}
+
+function groupTarget(rest: string): Target {
+  const slash = rest.indexOf('/');
+  if (slash === -1) {
+    reject(`"group:${rest}" names no role — member and admin are two different sets of people.`);
+  }
+  const groupId = rest.slice(0, slash);
+  const role = rest.slice(slash + 1);
+  if (!groupId) reject('A group target needs a record id.');
+  if (role !== 'member' && role !== 'admin' && role !== 'any') {
+    reject(`"${role}" is not a role. Use member, admin, or (when listing) any.`);
+  }
+  return { kind: 'group', groupId, role };
+}
+
+function recordTarget(rest: string): Target {
+  // A record id is Crockford-32, so the first `@` is the separator and a
+  // userinfo `@` inside the URL that follows cannot be mistaken for it.
+  const at = rest.indexOf('@');
+  const recordId = at === -1 ? rest : rest.slice(0, at);
+  const stackUrl = at === -1 ? undefined : rest.slice(at + 1);
+  if (!recordId) reject('A record target needs a record id.');
+  if (at !== -1 && !stackUrl) reject('A record target naming another stack needs its URL.');
+  return { kind: 'record', recordId, ...(stackUrl && { stackUrl }) };
+}
+
+function externalTarget(rest: string): Target {
+  const slash = rest.indexOf('/');
+  if (slash === -1) reject(`"external:${rest}" names a namespace but no identifier within it.`);
+  const ns = rest.slice(0, slash);
+  const id = rest.slice(slash + 1);
+  if (!ns) reject('An external target needs a namespace.');
+  if (!id) reject(`An external target needs an identifier within "${ns}".`);
+  return { kind: 'external', ns, id };
+}
+
+/** The inverse of parseTarget — so a listing's output is a command's input. */
+export function formatTarget(target: Target): string {
+  switch (target.kind) {
+    case 'anyone':
+      return 'anyone';
+    case 'authenticated':
+      return 'authenticated';
+    case 'entity':
+      return target.entityId;
+    case 'group':
+      return `group:${target.groupId}/${target.role}`;
+    case 'record':
+      return target.stackUrl
+        ? `record:${target.recordId}@${target.stackUrl}`
+        : `record:${target.recordId}`;
+    case 'external':
+      return `external:${target.ns}/${target.id}`;
+  }
+}
+
+// ------------------------------------------------- narrowing, per command
+
+function wrongArm(target: Target, verb: string, accepts: string): never {
+  throw new Error(
+    `${formatTarget(target)} is not something \`${verb}\` can name.\n  ${verb} accepts: ${accepts}`,
+  );
+}
+
+export function permissionTargetOf(target: Target): PermissionTarget {
+  switch (target.kind) {
+    case 'anyone':
+      return { scope: 'anyone' };
+    case 'entity':
+      return { scope: 'entity', entityId: target.entityId };
+    case 'group':
+      if (target.role === 'any') {
+        throw new Error('`any` is a listing role — a permission names member or admin.');
+      }
+      return { scope: 'group', groupId: target.groupId, role: target.role };
+    default:
+      wrongArm(target, 'perm', 'anyone | <did> | group:<id>/<member|admin>');
+  }
+}
+
+export function grantTargetOf(target: Target): GrantTarget {
+  const query = grantQueryOf(target);
+  if (query.kind === 'group' && query.role === 'any') {
+    throw new Error('`any` is for `grant ls` — a grant names member or admin.');
+  }
+  return query as GrantTarget;
+}
+
+/** The listing form, which admits the role `grant`/`revoke` refuse. */
+export function grantQueryOf(target: Target): GrantQuery {
+  switch (target.kind) {
+    case 'authenticated':
+      return { kind: 'authenticated' };
+    case 'entity':
+      return { kind: 'entity', entityId: target.entityId };
+    case 'group':
+      return { kind: 'group', groupId: target.groupId, role: target.role };
+    default:
+      wrongArm(target, 'grant', 'authenticated | <did> | group:<id>/<member|admin>');
+  }
+}
+
+export function relationshipTargetOf(target: Target): RelationshipTarget {
+  switch (target.kind) {
+    case 'record':
+      return {
+        scope: 'record',
+        recordId: target.recordId,
+        ...(target.stackUrl && { stackUrl: target.stackUrl }),
+      };
+    case 'entity':
+      return { scope: 'entity', entityId: target.entityId };
+    case 'external':
+      return { scope: 'external', ns: target.ns, id: target.id };
+    default:
+      wrongArm(target, 'link', '<did> | record:<id>[@<stackUrl>] | external:<ns>/<id>');
+  }
+}
+
+// ------------------------------------------------- back from core's shapes
+
+export function targetOfRelationship(target: RelationshipTarget): Target {
+  if (target.scope === 'record') {
+    return {
+      kind: 'record',
+      recordId: target.recordId,
+      ...(target.stackUrl && { stackUrl: target.stackUrl }),
+    };
+  }
+  if (target.scope === 'entity') return { kind: 'entity', entityId: target.entityId };
+  return { kind: 'external', ns: target.ns, id: target.id };
+}
+
+export function targetOfPermission(grantee: PermissionTarget): Target {
+  if (grantee.scope === 'anyone') return { kind: 'anyone' };
+  if (grantee.scope === 'entity') return { kind: 'entity', entityId: grantee.entityId };
+  return { kind: 'group', groupId: grantee.groupId, role: grantee.role };
+}
diff --git a/tests/access.test.ts b/tests/access.test.ts
index 38feb13..33b27e3 100644
--- a/tests/access.test.ts
+++ b/tests/access.test.ts
@@ -23,27 +23,27 @@ beforeEach(async () => {
 
 describe('permAdd', () => {
   it('adds an `anyone` element, idempotently', async () => {
-    await permAdd(stack, id, { anyone: true }, false, false);
-    const second = await permAdd(stack, id, { anyone: true }, false, false);
+    await permAdd(stack, id, 'anyone', false, false);
+    const second = await permAdd(stack, id, 'anyone', false, false);
     expect(await perms()).toEqual([{ kind: 'anyone', label: 'read' }]);
     expect(second).toMatch(/nothing to do/);
   });
 
   it('refuses a write bit on --anyone, which carries read alone', async () => {
-    await expect(permAdd(stack, id, { anyone: true }, false, true)).rejects.toThrow(
-      /--anyone carries read only/,
+    await expect(permAdd(stack, id, 'anyone', false, true)).rejects.toThrow(
+      /`anyone` carries read only/,
     );
   });
 
   it('requires --read or --write for a grantee target', async () => {
-    await expect(permAdd(stack, id, { entity: 'did:key:z1' }, false, false)).rejects.toThrow(
+    await expect(permAdd(stack, id, 'did:key:z1', false, false)).rejects.toThrow(
       /Nothing to grant/,
     );
   });
 
   it('adds one element per bit, and adding the second keeps the first', async () => {
-    await permAdd(stack, id, { entity: 'did:key:z1' }, true, false);
-    await permAdd(stack, id, { entity: 'did:key:z1' }, false, true);
+    await permAdd(stack, id, 'did:key:z1', true, false);
+    await permAdd(stack, id, 'did:key:z1', false, true);
     expect(await perms()).toEqual([
       { kind: 'permission', label: 'read', grantee: { scope: 'entity', entityId: 'did:key:z1' } },
       { kind: 'permission', label: 'write', grantee: { scope: 'entity', entityId: 'did:key:z1' } },
@@ -51,8 +51,8 @@ describe('permAdd', () => {
   });
 
   it('keys a group grantee on groupId + role, so member and admin are distinct', async () => {
-    await permAdd(stack, id, { group: 'g1', role: 'member' }, true, false);
-    await permAdd(stack, id, { group: 'g1', role: 'admin' }, true, true);
+    await permAdd(stack, id, 'group:g1/member', true, false);
+    await permAdd(stack, id, 'group:g1/admin', true, true);
     expect(await perms()).toEqual([
       {
         kind: 'permission',
@@ -72,67 +72,66 @@ describe('permAdd', () => {
     ]);
   });
 
-  it('requires --role alongside --group — a permission names one role', async () => {
-    await expect(permAdd(stack, id, { group: 'g1' }, true, false)).rejects.toThrow(
-      /--group needs --role/,
-    );
+  it('requires a role alongside a group — a permission names one role', async () => {
+    await expect(permAdd(stack, id, 'group:g1', true, false)).rejects.toThrow(/names no role/);
   });
 
   it('grants read before write, so --read --write together is accepted', async () => {
-    await permAdd(stack, id, { entity: 'did:key:z1' }, true, true);
+    await permAdd(stack, id, 'did:key:z1', true, true);
     expect((await perms()).map((p) => p.label)).toEqual(['read', 'write']);
   });
 
   it('surfaces core’s own write-requires-read rule for a bare write', async () => {
-    await expect(permAdd(stack, id, { entity: 'did:key:z1' }, false, true)).rejects.toThrow(
+    await expect(permAdd(stack, id, 'did:key:z1', false, true)).rejects.toThrow(
       /write requires read|cannot read/i,
     );
   });
 
   it('is a no-bump write — version and updatedAt stay put', async () => {
     const before = (await stack.get(id))!;
-    await permAdd(stack, id, { anyone: true }, false, false);
+    await permAdd(stack, id, 'anyone', false, false);
     const after = (await stack.get(id))!;
     expect(after.version).toBe(before.version);
     expect(after.updatedAt.getTime()).toBe(before.updatedAt.getTime());
   });
 
-  it('requires exactly one of --anyone / --entity / --group', async () => {
-    await expect(permAdd(stack, id, {}, true, false)).rejects.toThrow(/exactly one/);
+  it('refuses a target `perm` cannot name, and an empty one', async () => {
+    await expect(permAdd(stack, id, 'record:01hx', true, false)).rejects.toThrow(
+      /not something `perm` can name/,
+    );
+    await expect(permAdd(stack, id, '', true, false)).rejects.toThrow(/cannot be empty/);
   });
 });
 
 describe('permRemove', () => {
   it('drops the `anyone` element', async () => {
-    await permAdd(stack, id, { anyone: true }, false, false);
-    const msg = await permRemove(stack, id, { anyone: true }, false, false);
+    await permAdd(stack, id, 'anyone', false, false);
+    const msg = await permRemove(stack, id, 'anyone', false, false);
     expect(msg).toMatch(/no longer reaches it/);
     expect(await perms()).toEqual([]);
   });
 
   it('withdraws one named bit, leaving the other standing', async () => {
-    await permAdd(stack, id, { entity: 'did:key:z1' }, true, true);
-    await permRemove(stack, id, { entity: 'did:key:z1' }, false, true);
+    await permAdd(stack, id, 'did:key:z1', true, true);
+    await permRemove(stack, id, 'did:key:z1', false, true);
     expect(await perms()).toEqual([
       { kind: 'permission', label: 'read', grantee: { scope: 'entity', entityId: 'did:key:z1' } },
     ]);
   });
 
   it('withdraws every bit when neither is named, write first', async () => {
-    await permAdd(stack, id, { entity: 'did:key:z1' }, true, true);
-    await permRemove(stack, id, { entity: 'did:key:z1' }, false, false);
+    await permAdd(stack, id, 'did:key:z1', true, true);
+    await permRemove(stack, id, 'did:key:z1', false, false);
     expect(await perms()).toEqual([]);
   });
 
   it('surfaces core’s refusal to leave a writer unable to read', async () => {
-    await permAdd(stack, id, { entity: 'did:key:z1' }, true, true);
-    await expect(permRemove(stack, id, { entity: 'did:key:z1' }, true, false)).rejects.toThrow(
-      /read|write/i,
-    );
+    await permAdd(stack, id, 'did:key:z1', true, true);
+    await expect(permRemove(stack, id, 'did:key:z1', true, false)).rejects.toThrow(/read|write/i);
   });
 
   it('is a no-op message when there is nothing to remove', async () => {
-    const msg = await permRemove(stack, id, { entity: 'did:key:zNobody' }, false, false);
+    const msg = await permRemove(stack, id, 'did:key:zNobody', false, false);
     expect(msg).toMatch(/nothing to do/);
   });
 });
@@ -143,10 +142,10 @@ describe('permList', () => {
   });
 
   it('lists a grantee per line, and round-trips as JSON', async () => {
-    await permAdd(stack, id, { entity: 'did:key:z1' }, true, true);
-    await permAdd(stack, id, { anyone: true }, false, false);
+    await permAdd(stack, id, 'did:key:z1', true, true);
+    await permAdd(stack, id, 'anyone', false, false);
     const listing = await permList(stack, id, false);
-    expect(listing).toMatch(/GRANTEE\s+ACCESS/);
+    expect(listing).toMatch(/TARGET\s+ACCESS/);
     expect(listing).toMatch(/anyone\s+read/);
     expect(JSON.parse(await permList(stack, id, true))).toHaveLength(3);
   });
@@ -154,75 +153,69 @@ describe('permList', () => {
 
 describe('grantAdd / grantRemove / grantList', () => {
   it('grants and lists a create+read-own bundle for an entity', async () => {
-    await grantAdd(stack, 'com.example/note@1', { entity: 'did:key:zApp' }, ['create', 'read-own']);
+    await grantAdd(stack, 'com.example/note@1', 'did:key:zApp', ['create', 'read-own']);
     const listing = await grantList(stack);
     expect(listing).toMatch(/com\.example\/note@1/);
     expect(listing).toMatch(/create, read-own/);
   });
 
   it('supports an authenticated (default) grant', async () => {
-    await grantAdd(stack, 'com.example/note@1', { authenticated: true }, ['create']);
+    await grantAdd(stack, 'com.example/note@1', 'authenticated', ['create']);
     expect(await grantList(stack)).toMatch(/authenticated/);
   });
 
   it('names one role on a group grant, and keeps member and admin apart', async () => {
-    await grantAdd(stack, 'com.example/note@1', { group: 'g1', role: 'member' }, ['create']);
-    await grantAdd(stack, 'com.example/note@1', { group: 'g1', role: 'admin' }, ['read-any']);
-    expect(await grantList(stack, undefined, { group: 'g1', role: 'admin' })).toMatch(
-      /group:g1:admin\s+read-any/,
+    await grantAdd(stack, 'com.example/note@1', 'group:g1/member', ['create']);
+    await grantAdd(stack, 'com.example/note@1', 'group:g1/admin', ['read-any']);
+    expect(await grantList(stack, undefined, 'group:g1/admin')).toMatch(
+      /group:g1\/admin\s+read-any/,
     );
     // `--role any` is the listing-only widening.
-    expect(
-      (await grantList(stack, undefined, { group: 'g1', role: 'any' })).split('\n'),
-    ).toHaveLength(3);
+    expect((await grantList(stack, undefined, 'group:g1/any')).split('\n')).toHaveLength(3);
   });
 
-  it('requires --role alongside --group when granting', async () => {
-    await expect(
-      grantAdd(stack, 'com.example/note@1', { group: 'g1' }, ['create']),
-    ).rejects.toThrow(/--group needs --role/);
+  it('requires a role alongside a group when granting', async () => {
+    await expect(grantAdd(stack, 'com.example/note@1', 'group:g1', ['create'])).rejects.toThrow(
+      /names no role/,
+    );
   });
 
-  it('refuses the listing-only --role any on a grant', async () => {
-    await expect(
-      grantAdd(stack, 'com.example/note@1', { group: 'g1', role: 'any' }, ['create']),
-    ).rejects.toThrow(/--role any is for/);
+  it('refuses the listing-only `any` role on a grant', async () => {
+    await expect(grantAdd(stack, 'com.example/note@1', 'group:g1/any', ['create'])).rejects.toThrow(
+      /`any` is for `grant ls`/,
+    );
   });
 
   it('filters listGrants by typeId', async () => {
-    await grantAdd(stack, 'com.example/note@1', { entity: 'did:key:zApp' }, ['create']);
+    await grantAdd(stack, 'com.example/note@1', 'did:key:zApp', ['create']);
     await stack.defineType('com.example/task@1', 'Task', { title: { kind: 'string' } });
-    await grantAdd(stack, 'com.example/task@1', { entity: 'did:key:zApp' }, ['create']);
+    await grantAdd(stack, 'com.example/task@1', 'did:key:zApp', ['create']);
     const listing = await grantList(stack, 'com.example/task@1');
     expect(listing).toContain('com.example/task@1');
     expect(listing).not.toContain('com.example/note@1');
   });
 
   it('revokes what it granted, and reports how many it withdrew', async () => {
-    await grantAdd(stack, 'com.example/note@1', { entity: 'did:key:zApp' }, ['create']);
-    const msg = await grantRemove(stack, 'com.example/note@1', { entity: 'did:key:zApp' }, [
-      'create',
-    ]);
+    await grantAdd(stack, 'com.example/note@1', 'did:key:zApp', ['create']);
+    const msg = await grantRemove(stack, 'com.example/note@1', 'did:key:zApp', ['create']);
     expect(msg).toMatch(/Revoked 1 grant/);
     expect(await grantList(stack)).toBe('No grants.');
   });
 
   it('says so when a revoke matches nothing', async () => {
-    const msg = await grantRemove(stack, 'com.example/note@1', { entity: 'did:key:zNobody' }, [
-      'create',
-    ]);
+    const msg = await grantRemove(stack, 'com.example/note@1', 'did:key:zNobody', ['create']);
     expect(msg).toMatch(/nothing to revoke/);
   });
 
   it('surfaces core’s own dependency error for a mutate action with no read companion', async () => {
     await expect(
-      grantAdd(stack, 'com.example/note@1', { entity: 'did:key:zApp' }, ['update-any']),
+      grantAdd(stack, 'com.example/note@1', 'did:key:zApp', ['update-any']),
     ).rejects.toThrow(/requires "read-any"/);
   });
 
-  it('requires exactly one of --entity / --group / --authenticated', async () => {
-    await expect(grantAdd(stack, 'com.example/note@1', {}, ['create'])).rejects.toThrow(
-      /exactly one/,
+  it('refuses a target `grant` cannot name', async () => {
+    await expect(grantAdd(stack, 'com.example/note@1', 'anyone', ['create'])).rejects.toThrow(
+      /not something `grant` can name/,
     );
   });
 });
diff --git a/tests/associations.test.ts b/tests/associations.test.ts
index 6e9fcdd..e3a353e 100644
--- a/tests/associations.test.ts
+++ b/tests/associations.test.ts
@@ -1,13 +1,7 @@
 import { beforeEach, describe, expect, it } from 'vitest';
 import { Stack } from '@haverstack/core';
 import { MemoryAdapter } from '@haverstack/core/testing';
-import {
-  buildRelationshipTarget,
-  linkAdd,
-  linkRemove,
-  tagAdd,
-  tagRemove,
-} from '../src/commands/associations.js';
+import { linkAdd, linkRemove, tagAdd, tagRemove } from '../src/commands/associations.js';
 
 let stack: Stack;
 let id: string;
@@ -49,59 +43,67 @@ describe('tagAdd / tagRemove', () => {
   });
 });
 
-describe('buildRelationshipTarget', () => {
-  it('builds each scope from its own flags', () => {
-    expect(buildRelationshipTarget({ toRecord: 'rid' })).toEqual({
-      scope: 'record',
-      recordId: 'rid',
-    });
-    expect(buildRelationshipTarget({ toRecord: 'rid', stackUrl: 'https://x' })).toEqual({
-      scope: 'record',
-      recordId: 'rid',
-      stackUrl: 'https://x',
-    });
-    expect(buildRelationshipTarget({ toEntity: 'did:key:z1' })).toEqual({
-      scope: 'entity',
-      entityId: 'did:key:z1',
-    });
-    expect(buildRelationshipTarget({ toExternalNs: 'atproto', externalId: 'at://x' })).toEqual({
-      scope: 'external',
-      ns: 'atproto',
-      id: 'at://x',
-    });
-  });
-
-  it('requires exactly one target group', () => {
-    expect(() => buildRelationshipTarget({})).toThrow(/exactly one/);
-    expect(() => buildRelationshipTarget({ toRecord: 'a', toEntity: 'b' })).toThrow(/exactly one/);
-  });
-
-  it('requires --external-id alongside --to-external', () => {
-    expect(() => buildRelationshipTarget({ toExternalNs: 'atproto' })).toThrow(/--external-id/);
-  });
-});
-
 describe('linkAdd / linkRemove', () => {
   it('associates and dissociates a relationship to another record', async () => {
-    const msg = await linkAdd(stack, id, 'see-also', { toRecord: otherId });
-    expect(msg).toBe(`${id} --see-also--> ${otherId}.`);
+    const msg = await linkAdd(stack, id, 'see-also', `record:${otherId}`);
+    expect(msg).toBe(`${id} --see-also--> record:${otherId}.`);
     expect((await stack.get(id))?.associations).toEqual([
       { kind: 'relationship', label: 'see-also', target: { scope: 'record', recordId: otherId } },
     ]);
 
-    await linkRemove(stack, id, 'see-also', { toRecord: otherId });
+    await linkRemove(stack, id, 'see-also', `record:${otherId}`);
     expect((await stack.get(id))?.associations ?? []).toEqual([]);
-    expect(await linkRemove(stack, id, 'see-also', { toRecord: otherId })).toMatch(
+    expect(await linkRemove(stack, id, 'see-also', `record:${otherId}`)).toMatch(
       /nothing to remove/,
     );
   });
 
   it('dissociate only removes the exact target named', async () => {
-    await linkAdd(stack, id, 'ref', { toEntity: 'did:key:zA' });
-    await linkAdd(stack, id, 'ref', { toEntity: 'did:key:zB' });
-    await linkRemove(stack, id, 'ref', { toEntity: 'did:key:zA' });
+    await linkAdd(stack, id, 'ref', 'did:key:zA');
+    await linkAdd(stack, id, 'ref', 'did:key:zB');
+    await linkRemove(stack, id, 'ref', 'did:key:zA');
     const remaining = (await stack.get(id))?.associations ?? [];
     expect(remaining).toHaveLength(1);
     expect(remaining[0]).toMatchObject({ target: { entityId: 'did:key:zB' } });
   });
 });
+
+describe('link target arms', () => {
+  it('links each scope the relationship union carries, through one --to', async () => {
+    await linkAdd(stack, id, 'see-also', `record:${otherId}@https://other.example`);
+    await linkAdd(stack, id, 'author', 'did:key:zAlice');
+    await linkAdd(stack, id, 'mirrors', 'external:atproto/at://did:plc:x/post/3k');
+    expect((await stack.get(id))?.associations).toEqual([
+      {
+        kind: 'relationship',
+        label: 'see-also',
+        target: { scope: 'record', recordId: otherId, stackUrl: 'https://other.example' },
+      },
+      {
+        kind: 'relationship',
+        label: 'author',
+        target: { scope: 'entity', entityId: 'did:key:zAlice' },
+      },
+      {
+        kind: 'relationship',
+        label: 'mirrors',
+        target: { scope: 'external', ns: 'atproto', id: 'at://did:plc:x/post/3k' },
+      },
+    ]);
+  });
+
+  it('refuses a target `link` cannot name', async () => {
+    await expect(linkAdd(stack, id, 'x', 'anyone')).rejects.toThrow(
+      /not something `link` can name/,
+    );
+  });
+
+  it('matches a foreign-stack link exactly — the same --to removes it', async () => {
+    await linkAdd(stack, id, 'see-also', `record:${otherId}@https://other.example`);
+    // A bare record target is a different element, not a looser match.
+    await linkRemove(stack, id, 'see-also', `record:${otherId}`);
+    expect((await stack.get(id))?.associations).toHaveLength(1);
+    await linkRemove(stack, id, 'see-also', `record:${otherId}@https://other.example`);
+    expect((await stack.get(id))?.associations ?? []).toEqual([]);
+  });
+});
diff --git a/tests/lifecycle.test.ts b/tests/lifecycle.test.ts
index 3b08dc5..6d7725a 100644
--- a/tests/lifecycle.test.ts
+++ b/tests/lifecycle.test.ts
@@ -92,7 +92,7 @@ describe.each(backends)('full lifecycle — $name', ({ make }) => {
 
     // link — to a second record, created directly (not the thing under test here)
     const folder = await stack.create(FOLDER_ID, { name: 'Inbox' });
-    const linkMsg = await linkAdd(stack, started.recordId, 'files-in', { toRecord: folder.id });
+    const linkMsg = await linkAdd(stack, started.recordId, 'files-in', `record:${folder.id}`);
     expect(linkMsg).toMatch(/files-in/);
     const linked = (await stack.get(started.recordId))!;
     expect(linked.associations).toContainEqual(
diff --git a/tests/target.test.ts b/tests/target.test.ts
new file mode 100644
index 0000000..cbb074e
--- /dev/null
+++ b/tests/target.test.ts
@@ -0,0 +1,123 @@
+import { describe, expect, it } from 'vitest';
+import {
+  formatTarget,
+  grantQueryOf,
+  grantTargetOf,
+  parseTarget,
+  permissionTargetOf,
+  relationshipTargetOf,
+} from '../src/target.js';
+
+describe('parseTarget', () => {
+  it('reads the two bare tiers', () => {
+    expect(parseTarget('anyone')).toEqual({ kind: 'anyone' });
+    expect(parseTarget('authenticated')).toEqual({ kind: 'authenticated' });
+  });
+
+  it('treats a bare DID as an entity — the one inferred shape', () => {
+    expect(parseTarget('did:key:z6MkAlice')).toEqual({
+      kind: 'entity',
+      entityId: 'did:key:z6MkAlice',
+    });
+    expect(parseTarget('entity:did:key:z6MkAlice')).toEqual(parseTarget('did:key:z6MkAlice'));
+  });
+
+  it('reads a group with its role', () => {
+    expect(parseTarget('group:01hx/admin')).toEqual({
+      kind: 'group',
+      groupId: '01hx',
+      role: 'admin',
+    });
+    expect(parseTarget('group:01hx/any')).toEqual({ kind: 'group', groupId: '01hx', role: 'any' });
+  });
+
+  it('reads a record, with and without another stack', () => {
+    expect(parseTarget('record:01hx')).toEqual({ kind: 'record', recordId: '01hx' });
+    expect(parseTarget('record:01hx@https://other.example')).toEqual({
+      kind: 'record',
+      recordId: '01hx',
+      stackUrl: 'https://other.example',
+    });
+  });
+
+  it('splits an external target on its first slash, so the id may hold more', () => {
+    expect(parseTarget('external:atproto/at://did:plc:x/app.bsky.feed.post/3k')).toEqual({
+      kind: 'external',
+      ns: 'atproto',
+      id: 'at://did:plc:x/app.bsky.feed.post/3k',
+    });
+  });
+
+  it('refuses a scheme it does not know rather than guessing an arm', () => {
+    expect(() => parseTarget('mystery:x')).toThrow(/not a target scheme/);
+    expect(() => parseTarget('01hx3k9m2p7q')).toThrow(/names no scheme/);
+    expect(() => parseTarget('  ')).toThrow(/cannot be empty/);
+  });
+
+  it('names what is missing from a half-written target', () => {
+    expect(() => parseTarget('group:01hx')).toThrow(/names no role/);
+    expect(() => parseTarget('group:01hx/owner')).toThrow(/not a role/);
+    expect(() => parseTarget('group:/admin')).toThrow(/needs a record id/);
+    expect(() => parseTarget('external:atproto')).toThrow(/no identifier within it/);
+    expect(() => parseTarget('entity:')).toThrow(/needs a DID/);
+    expect(() => parseTarget('record:01hx@')).toThrow(/needs its URL/);
+  });
+
+  it('round-trips every arm through formatTarget', () => {
+    for (const s of [
+      'anyone',
+      'authenticated',
+      'did:key:z6MkAlice',
+      'group:01hx/member',
+      'record:01hx',
+      'record:01hx@https://other.example',
+      'external:atproto/at://x',
+    ]) {
+      expect(formatTarget(parseTarget(s))).toBe(s);
+    }
+  });
+});
+
+describe('narrowing per command', () => {
+  it('gives perm the arms it accepts', () => {
+    expect(permissionTargetOf(parseTarget('anyone'))).toEqual({ scope: 'anyone' });
+    expect(permissionTargetOf(parseTarget('group:g/admin'))).toEqual({
+      scope: 'group',
+      groupId: 'g',
+      role: 'admin',
+    });
+    expect(() => permissionTargetOf(parseTarget('record:01hx'))).toThrow(
+      /not something `perm` can name/,
+    );
+    expect(() => permissionTargetOf(parseTarget('authenticated'))).toThrow(/`perm` can name/);
+    expect(() => permissionTargetOf(parseTarget('group:g/any'))).toThrow(/listing role/);
+  });
+
+  it('gives grant the arms it accepts, and keeps `any` to the listing', () => {
+    expect(grantTargetOf(parseTarget('authenticated'))).toEqual({ kind: 'authenticated' });
+    expect(grantQueryOf(parseTarget('group:g/any'))).toEqual({
+      kind: 'group',
+      groupId: 'g',
+      role: 'any',
+    });
+    expect(() => grantTargetOf(parseTarget('group:g/any'))).toThrow(/`any` is for `grant ls`/);
+    expect(() => grantTargetOf(parseTarget('anyone'))).toThrow(/not something `grant` can name/);
+  });
+
+  it('gives link the arms it accepts', () => {
+    expect(relationshipTargetOf(parseTarget('record:01hx@https://x'))).toEqual({
+      scope: 'record',
+      recordId: '01hx',
+      stackUrl: 'https://x',
+    });
+    expect(relationshipTargetOf(parseTarget('external:email/a@b.example'))).toEqual({
+      scope: 'external',
+      ns: 'email',
+      id: 'a@b.example',
+    });
+    expect(() => relationshipTargetOf(parseTarget('anyone'))).toThrow(
+      /not something `link` can name/,
+    );
+    expect(() => relationshipTargetOf(parseTarget('group:g/admin'))).toThrow(/`link` can name/);
+  });
+});

From 0976034f31546201c33af6a837ec355f8e19ceb6 Mon Sep 17 00:00:00 2001
From: Jen Garcia <jen@haverstack.com>
Date: Wed, 23 Sep 2026 18:48:24 -0400
Subject: [PATCH 3/3] feat: refuse a target from the wrong tier by name, and
 narrow at the parse
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two changes to `--to`, both about keeping the shared grammar from blurring
the distinctions core draws.

**Every entry point returns one command's narrow type.**
parsePermissionTarget(), parseGrantTarget(), parseGrantQuery() and
parseLinkTarget() hand back core's own PermissionGrantee, GrantGrantee,
GrantQuery and RelationshipTarget. The wide union is module-private and no
longer exported, so no caller can hold an un-narrowed target and the
per-command table is a type rather than a convention — parseLinkTarget()
cannot return a grantee because RelationshipTarget has nowhere to put one.
One shared parser still backs all four: one grammar to keep correct rather
than four that drift.

**A target from the wrong tier is told what to say instead**, never
converted. `grant --to anyone` is pointed at `authenticated`, `link --to
group:X/member` at `record:X` (a Group is a Record, so the redirect is
exact), and `perm`/`grant --to record:X` at `group:X/<role>`.

The asymmetry between the first two is deliberate and is the one place
this could have gone wrong. `anyone` is the wider tier — it reaches
anonymous requesters where `authenticated` reaches only DID holders — so
`grant` suggesting `authenticated` narrows and is safe to offer, while
`perm --to authenticated` must not be handed `anyone` back as a synonym.
It names it and says which way it moves, leaving the widening a choice
rather than an autocomplete. Offering it as an equivalent would be a quiet
escalation, which is the same failure as converting between the tiers.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013wPYq2Dp59HnoYsnzYbuYP
---
 .changeset/one-target-grammar.md |  19 +++-
 docs/design.md                   |  44 +++++++--
 src/commands/access.ts           |  48 ++++------
 src/commands/associations.ts     |  12 +--
 src/index.ts                     |  19 ++--
 src/target.ts                    | 151 +++++++++++++++++++-----------
 tests/target.test.ts             | 156 +++++++++++++++++--------------
 7 files changed, 267 insertions(+), 182 deletions(-)

diff --git a/.changeset/one-target-grammar.md b/.changeset/one-target-grammar.md
index c0bdc12..96be652 100644
--- a/.changeset/one-target-grammar.md
+++ b/.changeset/one-target-grammar.md
@@ -43,6 +43,19 @@ The single seam is the point. The deferred `--pick` selector resolves a filter t
 and substitutes it into the invoking command; against three flag shapes that would have
 been three substitution paths.
 
-`parseTarget`, `formatTarget` and the three narrowing functions are exported for anyone
-embedding the CLI. `buildRelationshipTarget` and the `PermTargetOptions` /
-`GrantTargetOptions` / `LinkTargetOptions` types are gone — the target is a string now.
+Every entry point hands back one command's own narrow type —
+`parsePermissionTarget()`, `parseGrantTarget()`, `parseGrantQuery()` and
+`parseLinkTarget()`, returning core's `PermissionGrantee`, `GrantGrantee`, `GrantQuery`
+and `RelationshipTarget`. The wide union is module-private and never escapes, so the
+per-command table is enforced by the type system rather than by remembering to call a
+narrowing step. One shared parser still backs all four: one grammar to keep correct
+rather than four that can drift.
+
+A target from the wrong tier is refused and told what to say instead, never converted.
+`grant --to anyone` is pointed at `authenticated`; `link --to group:X/member` at
+`record:X`; `perm`/`grant --to record:X` at `group:X/<role>`. The one asymmetry is
+deliberate: `perm --to authenticated` is _not_ offered `anyone` as a synonym, because
+`anyone` is the wider tier — it names it and says so, leaving the widening a choice.
+
+`buildRelationshipTarget` and the `PermTargetOptions` / `GrantTargetOptions` /
+`LinkTargetOptions` types are gone — the target is a string now.
diff --git a/docs/design.md b/docs/design.md
index cb5e724..f5a1085 100644
--- a/docs/design.md
+++ b/docs/design.md
@@ -407,14 +407,42 @@ below.
 | `external:<ns>/<id>`     | `{ scope: 'external', ns, id }`                         | `link`                |
 
 **This vocabulary is the CLI's own, and deliberately wider than any single core union.**
-Core keeps three apart on purpose — a `RelationshipTarget` names no role, a
-`PermissionGrantee` has no record scope, and `anyone` is a kind rather than a grantee,
-so no dropped field can produce world-read. That split is right for the data model and
-wrong for a person, who is naming Alice either way. So the CLI parses one grammar and
-each command narrows to the arms it accepts, refusing the rest by name
-(`record:01hx… is not something `perm` can name`). The narrowing is where core's
-distinctions are enforced; the grammar is where the human convenience lives. Anything
-that blurs the two — a `perm` that quietly accepted a record target, say — is a bug.
+Core keeps three apart on purpose — [a permission's grantee "is its own shape, not a
+`RelationshipTarget`, which has no role and no group scope"][spec-perm], and `anyone` is
+a kind rather than a grantee so no dropped field can produce world-read. That split is
+right for the data model and wrong for a person, who is naming Alice either way. So the
+CLI parses one grammar and each command narrows to the arms it accepts. The narrowing is
+where core's distinctions are enforced; the grammar is where the human convenience lives.
+
+[spec-perm]: https://github.com/haverstack/core/blob/main/docs/spec/access-control.md#record-level-permissions
+
+Two rules keep the two from blurring:
+
+**Every entry point returns one command's narrow type.** `parsePermissionTarget()`,
+`parseGrantTarget()`, `parseGrantQuery()` and `parseLinkTarget()` are what the commands
+and the package's consumers call; the wide union is module-private and never escapes.
+The table above is therefore a type, not a convention — `parseLinkTarget()` cannot
+return a grantee, because `RelationshipTarget` has nowhere to put one. A single shared
+parser still backs all four, so there is one grammar to keep correct rather than four
+that can drift.
+
+**A target from the wrong tier is refused and told what to say instead**, never
+converted. Mixing the tiers is the mistake with real consequences, so each command names
+the confusion it actually expects:
+
+| Written                              | Refused with                                                                            |
+| ------------------------------------ | --------------------------------------------------------------------------------------- |
+| `grant … --to anyone`                | a grant cannot reach anonymous requesters — did you mean `authenticated`?               |
+| `perm … --to authenticated`          | a record permission has no authenticated tier; `anyone` is the nearest **and is wider** |
+| `link … --to group:X/member`         | to link to the group's record, use `record:X`                                           |
+| `perm`/`grant … --to record:X`       | to name a group, use `group:X/<member\|admin>`                                          |
+| `link … --to anyone`/`authenticated` | an access tier is not something a record can point at                                   |
+
+The asymmetry in the first two rows is deliberate. `anyone` is the **wider** tier — it
+reaches anonymous requesters, `authenticated` reaches only DID holders — so `grant`
+suggesting `authenticated` narrows and is safe to offer, while `perm` may not offer
+`anyone` back as a synonym. It names it and says which way it moves, leaving the
+widening a choice rather than an autocomplete.
 
 Three rules keep the grammar honest:
 
diff --git a/src/commands/access.ts b/src/commands/access.ts
index 5485594..e1edc85 100644
--- a/src/commands/access.ts
+++ b/src/commands/access.ts
@@ -11,17 +11,14 @@
  */
 
 import type { AuthorityAssociation, GrantAction, Stack, StackRecord } from '@haverstack/core';
+import type { GrantQuery } from '@haverstack/core';
 import {
-  formatTarget,
-  grantQueryOf,
-  grantTargetOf,
-  parseTarget,
-  permissionTargetOf,
-  targetOfPermission,
-  type GrantQuery,
-  type GrantTarget,
+  parseGrantQuery,
+  parseGrantTarget,
+  parsePermissionTarget,
+  showGrantTarget,
+  showPermissionTarget,
   type PermissionTarget,
-  type Target,
 } from '../target.js';
 
 // ---------------------------------------------------------------- perm
@@ -75,8 +72,7 @@ export async function permAdd(
   read: boolean,
   write: boolean,
 ): Promise<string> {
-  const parsed = parseTarget(to);
-  const target = permissionTargetOf(parsed);
+  const target = parsePermissionTarget(to);
   if (target.scope === 'anyone' && write) {
     throw new Error('`anyone` carries read only. Name a DID or a group to grant write.');
   }
@@ -93,7 +89,7 @@ export async function permAdd(
   if (write) record = await stack.grantAccess(id, elementFor(target, 'write')!);
 
   const after = bitsOf(record!.permissions, target);
-  const who = formatTarget(parsed);
+  const who = showPermissionTarget(target);
   return before.read === after.read && before.write === after.write
     ? `${id}: ${who} could already ${describeBits(after)} — nothing to do.`
     : `${id}: ${who} can now ${describeBits(after)}.`;
@@ -106,8 +102,7 @@ export async function permRemove(
   read: boolean,
   write: boolean,
 ): Promise<string> {
-  const parsed = parseTarget(to);
-  const target = permissionTargetOf(parsed);
+  const target = parsePermissionTarget(to);
   // Naming no bit withdraws the target's access entirely.
   if (!read && !write) {
     read = true;
@@ -125,7 +120,7 @@ export async function permRemove(
   if (read) record = await stack.revokeAccess(id, elementFor(target, 'read')!);
 
   const after = bitsOf(record!.permissions, target);
-  const who = formatTarget(parsed);
+  const who = showPermissionTarget(target);
   if (before.read === after.read && before.write === after.write) {
     return `${id}: ${who} had no ${describeBits({ read, write })} to remove — nothing to do.`;
   }
@@ -148,7 +143,7 @@ export async function permList(stack: Stack, id: string, json: boolean): Promise
 
   const byTarget = new Map<string, Bits>();
   for (const p of permissions) {
-    const who = formatTarget(targetOfPermission(granteeOf(p)));
+    const who = showPermissionTarget(granteeOf(p));
     const bits = byTarget.get(who) ?? { read: false, write: false };
     bits[p.label] = true;
     byTarget.set(who, bits);
@@ -163,18 +158,9 @@ export async function permList(stack: Stack, id: string, json: boolean): Promise
 
 // ---------------------------------------------------------------- grant
 
-const grantTargetFrom = (to: string): GrantTarget => grantTargetOf(parseTarget(to));
-
 /** A stored grant's grantee as a `--to` string, for a listing's output. */
-function describeGrantee(grantee: GrantQuery | undefined): string {
-  if (!grantee) return '—';
-  if (grantee.kind === 'entity')
-    return formatTarget({ kind: 'entity', entityId: grantee.entityId });
-  if (grantee.kind === 'group') {
-    return formatTarget({ kind: 'group', groupId: grantee.groupId, role: grantee.role });
-  }
-  return 'authenticated';
-}
+const describeGrantee = (grantee: GrantQuery | undefined): string =>
+  grantee ? showGrantTarget(grantee) : '—';
 
 export async function grantAdd(
   stack: Stack,
@@ -182,7 +168,7 @@ export async function grantAdd(
   to: string,
   actions: GrantAction[],
 ): Promise<string> {
-  const target = grantTargetFrom(to);
+  const target = parseGrantTarget(to);
   await stack.grant(target, [{ typeId, actions }]);
   return `Granted ${describeGrantee(target)} [${actions.join(', ')}] on ${typeId}.`;
 }
@@ -193,7 +179,7 @@ export async function grantRemove(
   to: string,
   actions: GrantAction[],
 ): Promise<string> {
-  const target = grantTargetFrom(to);
+  const target = parseGrantTarget(to);
   const withdrawn = await stack.revoke(target, [{ typeId, actions }]);
   const what = `${describeGrantee(target)} [${actions.join(', ')}] on ${typeId}`;
   return withdrawn.length === 0
@@ -202,7 +188,7 @@ export async function grantRemove(
 }
 
 export async function grantList(stack: Stack, typeId?: string, to?: string): Promise<string> {
-  const query = to === undefined ? undefined : grantQueryOf(parseTarget(to));
+  const query = to === undefined ? undefined : parseGrantQuery(to);
   const all = await stack.listGrants(query);
   const rows = (
     typeId ? all.filter((r) => (r.content as { typeId: string }).typeId === typeId) : all
@@ -218,5 +204,3 @@ export async function grantList(stack: Stack, typeId?: string, to?: string): Pro
   );
   return [`${'TYPE'.padEnd(typeW)}  ${'TARGET'.padEnd(targetW)}  ACTIONS`, ...lines].join('\n');
 }
-
-export type { Target };
diff --git a/src/commands/associations.ts b/src/commands/associations.ts
index 8e84c99..1207323 100644
--- a/src/commands/associations.ts
+++ b/src/commands/associations.ts
@@ -13,7 +13,7 @@
  */
 
 import type { Association, Stack, StackRecord } from '@haverstack/core';
-import { formatTarget, parseTarget, relationshipTargetOf } from '../target.js';
+import { parseLinkTarget, showLinkTarget } from '../target.js';
 
 async function requireRecord(stack: Stack, id: string): Promise<StackRecord> {
   const record = await stack.get(id);
@@ -51,11 +51,10 @@ export async function linkAdd(
   label: string,
   to: string,
 ): Promise<string> {
-  const parsed = parseTarget(to);
+  const target = parseLinkTarget(to);
   const before = await requireRecord(stack, id);
-  const target = relationshipTargetOf(parsed);
   const after = await stack.associate(id, { kind: 'relationship', label, target });
-  const arrow = `${id} --${label}--> ${formatTarget(parsed)}`;
+  const arrow = `${id} --${label}--> ${showLinkTarget(target)}`;
   return count(after) === count(before) ? `${arrow} — already linked.` : `${arrow}.`;
 }
 
@@ -65,11 +64,10 @@ export async function linkRemove(
   label: string,
   to: string,
 ): Promise<string> {
-  const parsed = parseTarget(to);
+  const target = parseLinkTarget(to);
   const before = await requireRecord(stack, id);
-  const target = relationshipTargetOf(parsed);
   const after = await stack.dissociate(id, { kind: 'relationship', label, target });
-  const arrow = `${id} --${label}--> ${formatTarget(parsed)}`;
+  const arrow = `${id} --${label}--> ${showLinkTarget(target)}`;
   return count(after) === count(before)
     ? `No such link: ${arrow} — nothing to remove.`
     : `Removed ${arrow}.`;
diff --git a/src/index.ts b/src/index.ts
index 95c2902..dff6353 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -23,17 +23,18 @@ export type { ListOptions, ShowOptions } from './commands/records.js';
 export { stackAdd, stackList, stackUse, stackRemove } from './commands/stack.js';
 
 export { tagAdd, tagRemove, linkAdd, linkRemove } from './commands/associations.js';
+// Each entry point hands back one command's own narrow type — the wide
+// vocabulary is internal, so no caller can hold an un-narrowed target.
 export {
-  parseTarget,
-  formatTarget,
-  permissionTargetOf,
-  grantTargetOf,
-  grantQueryOf,
-  relationshipTargetOf,
-  targetOfPermission,
-  targetOfRelationship,
+  parsePermissionTarget,
+  parseGrantTarget,
+  parseGrantQuery,
+  parseLinkTarget,
+  showPermissionTarget,
+  showGrantTarget,
+  showLinkTarget,
 } from './target.js';
-export type { Target, TargetRole, PermissionTarget, GrantTarget, GrantQuery } from './target.js';
+export type { PermissionTarget, TargetRole } from './target.js';
 export {
   permAdd,
   permList,
diff --git a/src/target.ts b/src/target.ts
index c487675..89af86e 100644
--- a/src/target.ts
+++ b/src/target.ts
@@ -3,19 +3,33 @@
  *
  * Core keeps three unions apart on purpose: a `RelationshipTarget` names
  * no role, a `PermissionGrantee` has no record scope, and `anyone` is a
- * kind of its own rather than a grantee. This vocabulary is deliberately
- * wider than any one of them and is narrowed per command, so a person
- * naming Alice writes the same thing wherever they are and `--pick` has
- * one seam to substitute into.
+ * kind of its own rather than a grantee. This grammar is deliberately
+ * wider than any one of them, so a person naming Alice writes the same
+ * thing wherever they are — and every entry point below hands back one
+ * command's own narrow type, so the wide form never reaches a write.
+ *
+ * Mixing the tiers is the mistake with real consequences, so a target
+ * from the wrong union is refused by name and told what to say instead.
+ * Nothing is ever converted: `anyone` reaches anonymous requesters and
+ * `authenticated` does not, and no message trades one for the other
+ * without saying which way it moves.
  * See docs/design.md § Naming a target.
  */
 
-import type { EntityId, RecordId, RelationshipTarget } from '@haverstack/core';
+import type {
+  EntityId,
+  GrantGrantee,
+  GrantQuery,
+  PermissionGrantee,
+  RecordId,
+  RelationshipTarget,
+} from '@haverstack/core';
 
 /** `any` is listing-only — `grant ls` widens on it; nothing writes it. */
 export type TargetRole = 'member' | 'admin' | 'any';
 
-export type Target =
+/** The whole vocabulary. Internal: every export below narrows it first. */
+type Target =
   | { kind: 'anyone' }
   | { kind: 'authenticated' }
   | { kind: 'entity'; entityId: EntityId }
@@ -23,23 +37,8 @@ export type Target =
   | { kind: 'record'; recordId: RecordId; stackUrl?: string }
   | { kind: 'external'; ns: string; id: string };
 
-/** What a permission names: `anyone` carries no grantee, the rest do. */
-export type PermissionTarget =
-  | { scope: 'anyone' }
-  | { scope: 'entity'; entityId: EntityId }
-  | { scope: 'group'; groupId: RecordId; role: 'member' | 'admin' };
-
-/** What `grant()`/`revoke()` write — one role, never the listing widening. */
-export type GrantTarget =
-  | { kind: 'entity'; entityId: EntityId }
-  | { kind: 'group'; groupId: RecordId; role: 'member' | 'admin' }
-  | { kind: 'authenticated' };
-
-/** What `listGrants()` accepts — the same union, widened by `role: 'any'`. */
-export type GrantQuery =
-  | { kind: 'entity'; entityId: EntityId }
-  | { kind: 'group'; groupId: RecordId; role: TargetRole }
-  | { kind: 'authenticated' };
+/** What `perm` names: `anyone` carries no grantee, so it is its own arm. */
+export type PermissionTarget = { scope: 'anyone' } | PermissionGrantee;
 
 const GRAMMAR =
   'anyone | authenticated | <did> | entity:<did> | group:<id>/<member|admin> | ' +
@@ -52,11 +51,12 @@ function reject(problem: string): never {
 /**
  * A `--to` value as its tagged form. Exactly one shape is inferred rather
  * than spelled — a leading `did:` is an entity — because a DID is the one
- * identifier common to every command and `entity:did:key:…` reads badly on
- * the most frequent call. Everything else names its scheme, so an unknown
- * one is an error rather than a guess.
+ * identifier every command takes and cannot be confused with a Record ID,
+ * which is twelve lowercase Crockford base-32 characters and holds no
+ * colon. Everything else names its scheme, so an unknown one is an error
+ * rather than a guess.
  */
-export function parseTarget(value: string): Target {
+function parseTarget(value: string): Target {
   const raw = value.trim();
   if (!raw) reject('A target cannot be empty.');
   if (raw === 'anyone') return { kind: 'anyone' };
@@ -122,7 +122,7 @@ function externalTarget(rest: string): Target {
 }
 
 /** The inverse of parseTarget — so a listing's output is a command's input. */
-export function formatTarget(target: Target): string {
+function formatTarget(target: Target): string {
   switch (target.kind) {
     case 'anyone':
       return 'anyone';
@@ -141,15 +141,28 @@ export function formatTarget(target: Target): string {
   }
 }
 
-// ------------------------------------------------- narrowing, per command
+// ------------------------------------------------------------- refusals
+
+/** What to say instead, per arm a command cannot take. */
+type Hints = Partial<Record<Target['kind'], string>>;
 
-function wrongArm(target: Target, verb: string, accepts: string): never {
+function refuse(target: Target, verb: string, accepts: string, hints: Hints): never {
+  const hint = hints[target.kind];
   throw new Error(
-    `${formatTarget(target)} is not something \`${verb}\` can name.\n  ${verb} accepts: ${accepts}`,
+    `${formatTarget(target)} is not something \`${verb}\` can name.` +
+      (hint ? `\n  ${hint}` : '') +
+      `\n  ${verb} accepts: ${accepts}`,
   );
 }
 
-export function permissionTargetOf(target: Target): PermissionTarget {
+const PERM_ACCEPTS = 'anyone | <did> | group:<id>/<member|admin>';
+const GRANT_ACCEPTS = 'authenticated | <did> | group:<id>/<member|admin>';
+const LINK_ACCEPTS = '<did> | record:<id>[@<stackUrl>] | external:<ns>/<id>';
+
+// ------------------------------------------------- one narrow type each
+
+export function parsePermissionTarget(value: string): PermissionTarget {
+  const target = parseTarget(value);
   switch (target.kind) {
     case 'anyone':
       return { scope: 'anyone' };
@@ -161,20 +174,30 @@ export function permissionTargetOf(target: Target): PermissionTarget {
       }
       return { scope: 'group', groupId: target.groupId, role: target.role };
     default:
-      wrongArm(target, 'perm', 'anyone | <did> | group:<id>/<member|admin>');
+      refuse(target, 'perm', PERM_ACCEPTS, {
+        // Deliberately not a substitution: `anyone` is the wider tier, and
+        // offering it as a synonym would be a quiet escalation.
+        authenticated:
+          'A record permission has no authenticated tier. `anyone` is the nearest, and it is ' +
+          'wider — it reaches anonymous requesters too, not only DID holders.',
+        record: `To share with a group, name it as a group: group:${target.kind === 'record' ? target.recordId : '<id>'}/<member|admin>.`,
+        external:
+          'A permission names who reaches the record, and something outside the stack holds no DID.',
+      });
   }
 }
 
-export function grantTargetOf(target: Target): GrantTarget {
-  const query = grantQueryOf(target);
+export function parseGrantTarget(value: string): GrantGrantee {
+  const query = parseGrantQuery(value);
   if (query.kind === 'group' && query.role === 'any') {
     throw new Error('`any` is for `grant ls` — a grant names member or admin.');
   }
-  return query as GrantTarget;
+  return query as GrantGrantee;
 }
 
 /** The listing form, which admits the role `grant`/`revoke` refuse. */
-export function grantQueryOf(target: Target): GrantQuery {
+export function parseGrantQuery(value: string): GrantQuery {
+  const target = parseTarget(value);
   switch (target.kind) {
     case 'authenticated':
       return { kind: 'authenticated' };
@@ -183,11 +206,18 @@ export function grantQueryOf(target: Target): GrantQuery {
     case 'group':
       return { kind: 'group', groupId: target.groupId, role: target.role };
     default:
-      wrongArm(target, 'grant', 'authenticated | <did> | group:<id>/<member|admin>');
+      refuse(target, 'grant', GRANT_ACCEPTS, {
+        anyone:
+          'A grant cannot reach anonymous requesters — did you mean `authenticated`, which ' +
+          'reaches any entity holding a DID?',
+        record: `To grant a group, name it as a group: group:${target.kind === 'record' ? target.recordId : '<id>'}/<member|admin>.`,
+        external: 'A grant names who may act, and something outside the stack holds no DID.',
+      });
   }
 }
 
-export function relationshipTargetOf(target: Target): RelationshipTarget {
+export function parseLinkTarget(value: string): RelationshipTarget {
+  const target = parseTarget(value);
   switch (target.kind) {
     case 'record':
       return {
@@ -200,26 +230,43 @@ export function relationshipTargetOf(target: Target): RelationshipTarget {
     case 'external':
       return { scope: 'external', ns: target.ns, id: target.id };
     default:
-      wrongArm(target, 'link', '<did> | record:<id>[@<stackUrl>] | external:<ns>/<id>');
+      refuse(target, 'link', LINK_ACCEPTS, {
+        // A Group *is* a Record, so the redirect is exact rather than advisory.
+        group: `To link to the group's record, use record:${target.kind === 'group' ? target.groupId : '<id>'}.`,
+        anyone: '`anyone` names who may read a record, not something a record can point at.',
+        authenticated:
+          '`authenticated` names who may act on a type, not something a record can point at.',
+      });
   }
 }
 
-// ------------------------------------------------- back from core's shapes
+// --------------------------------------------- rendering a narrow target
 
-export function targetOfRelationship(target: RelationshipTarget): Target {
+export function showPermissionTarget(target: PermissionTarget): string {
+  if (target.scope === 'anyone') return formatTarget({ kind: 'anyone' });
+  if (target.scope === 'entity') {
+    return formatTarget({ kind: 'entity', entityId: target.entityId });
+  }
+  return formatTarget({ kind: 'group', groupId: target.groupId, role: target.role });
+}
+
+export function showGrantTarget(target: GrantQuery): string {
+  if (target.kind === 'group') {
+    return formatTarget({ kind: 'group', groupId: target.groupId, role: target.role });
+  }
+  return formatTarget(target.kind === 'entity' ? target : { kind: 'authenticated' });
+}
+
+export function showLinkTarget(target: RelationshipTarget): string {
   if (target.scope === 'record') {
-    return {
+    return formatTarget({
       kind: 'record',
       recordId: target.recordId,
       ...(target.stackUrl && { stackUrl: target.stackUrl }),
-    };
+    });
   }
-  if (target.scope === 'entity') return { kind: 'entity', entityId: target.entityId };
-  return { kind: 'external', ns: target.ns, id: target.id };
-}
-
-export function targetOfPermission(grantee: PermissionTarget): Target {
-  if (grantee.scope === 'anyone') return { kind: 'anyone' };
-  if (grantee.scope === 'entity') return { kind: 'entity', entityId: grantee.entityId };
-  return { kind: 'group', groupId: grantee.groupId, role: grantee.role };
+  if (target.scope === 'entity') {
+    return formatTarget({ kind: 'entity', entityId: target.entityId });
+  }
+  return formatTarget({ kind: 'external', ns: target.ns, id: target.id });
 }
diff --git a/tests/target.test.ts b/tests/target.test.ts
index cbb074e..720879c 100644
--- a/tests/target.test.ts
+++ b/tests/target.test.ts
@@ -1,123 +1,137 @@
 import { describe, expect, it } from 'vitest';
 import {
-  formatTarget,
-  grantQueryOf,
-  grantTargetOf,
-  parseTarget,
-  permissionTargetOf,
-  relationshipTargetOf,
+  parseGrantQuery,
+  parseGrantTarget,
+  parseLinkTarget,
+  parsePermissionTarget,
+  showGrantTarget,
+  showLinkTarget,
+  showPermissionTarget,
 } from '../src/target.js';
 
-describe('parseTarget', () => {
-  it('reads the two bare tiers', () => {
-    expect(parseTarget('anyone')).toEqual({ kind: 'anyone' });
-    expect(parseTarget('authenticated')).toEqual({ kind: 'authenticated' });
-  });
-
+describe('the shared grammar', () => {
   it('treats a bare DID as an entity — the one inferred shape', () => {
-    expect(parseTarget('did:key:z6MkAlice')).toEqual({
-      kind: 'entity',
+    expect(parsePermissionTarget('did:key:z6MkAlice')).toEqual({
+      scope: 'entity',
       entityId: 'did:key:z6MkAlice',
     });
-    expect(parseTarget('entity:did:key:z6MkAlice')).toEqual(parseTarget('did:key:z6MkAlice'));
-  });
-
-  it('reads a group with its role', () => {
-    expect(parseTarget('group:01hx/admin')).toEqual({
-      kind: 'group',
-      groupId: '01hx',
-      role: 'admin',
-    });
-    expect(parseTarget('group:01hx/any')).toEqual({ kind: 'group', groupId: '01hx', role: 'any' });
+    expect(parsePermissionTarget('entity:did:key:z6MkAlice')).toEqual(
+      parsePermissionTarget('did:key:z6MkAlice'),
+    );
   });
 
   it('reads a record, with and without another stack', () => {
-    expect(parseTarget('record:01hx')).toEqual({ kind: 'record', recordId: '01hx' });
-    expect(parseTarget('record:01hx@https://other.example')).toEqual({
-      kind: 'record',
+    expect(parseLinkTarget('record:01hx')).toEqual({ scope: 'record', recordId: '01hx' });
+    expect(parseLinkTarget('record:01hx@https://other.example')).toEqual({
+      scope: 'record',
       recordId: '01hx',
       stackUrl: 'https://other.example',
     });
   });
 
   it('splits an external target on its first slash, so the id may hold more', () => {
-    expect(parseTarget('external:atproto/at://did:plc:x/app.bsky.feed.post/3k')).toEqual({
-      kind: 'external',
+    expect(parseLinkTarget('external:atproto/at://did:plc:x/app.bsky.feed.post/3k')).toEqual({
+      scope: 'external',
       ns: 'atproto',
       id: 'at://did:plc:x/app.bsky.feed.post/3k',
     });
   });
 
   it('refuses a scheme it does not know rather than guessing an arm', () => {
-    expect(() => parseTarget('mystery:x')).toThrow(/not a target scheme/);
-    expect(() => parseTarget('01hx3k9m2p7q')).toThrow(/names no scheme/);
-    expect(() => parseTarget('  ')).toThrow(/cannot be empty/);
+    expect(() => parseLinkTarget('mystery:x')).toThrow(/not a target scheme/);
+    expect(() => parseLinkTarget('01hx3k9m2p7q')).toThrow(/names no scheme/);
+    expect(() => parsePermissionTarget('  ')).toThrow(/cannot be empty/);
   });
 
   it('names what is missing from a half-written target', () => {
-    expect(() => parseTarget('group:01hx')).toThrow(/names no role/);
-    expect(() => parseTarget('group:01hx/owner')).toThrow(/not a role/);
-    expect(() => parseTarget('group:/admin')).toThrow(/needs a record id/);
-    expect(() => parseTarget('external:atproto')).toThrow(/no identifier within it/);
-    expect(() => parseTarget('entity:')).toThrow(/needs a DID/);
-    expect(() => parseTarget('record:01hx@')).toThrow(/needs its URL/);
+    expect(() => parsePermissionTarget('group:01hx')).toThrow(/names no role/);
+    expect(() => parsePermissionTarget('group:01hx/owner')).toThrow(/not a role/);
+    expect(() => parsePermissionTarget('group:/admin')).toThrow(/needs a record id/);
+    expect(() => parseLinkTarget('external:atproto')).toThrow(/no identifier within it/);
+    expect(() => parsePermissionTarget('entity:')).toThrow(/needs a DID/);
+    expect(() => parseLinkTarget('record:01hx@')).toThrow(/needs its URL/);
   });
 
-  it('round-trips every arm through formatTarget', () => {
+  it('round-trips every arm back into the grammar that produced it', () => {
+    for (const s of ['anyone', 'did:key:z6MkAlice', 'group:01hx/member']) {
+      expect(showPermissionTarget(parsePermissionTarget(s))).toBe(s);
+    }
+    for (const s of ['authenticated', 'did:key:z6MkAlice', 'group:01hx/any']) {
+      expect(showGrantTarget(parseGrantQuery(s))).toBe(s);
+    }
     for (const s of [
-      'anyone',
-      'authenticated',
       'did:key:z6MkAlice',
-      'group:01hx/member',
       'record:01hx',
       'record:01hx@https://other.example',
       'external:atproto/at://x',
     ]) {
-      expect(formatTarget(parseTarget(s))).toBe(s);
+      expect(showLinkTarget(parseLinkTarget(s))).toBe(s);
     }
   });
 });
 
-describe('narrowing per command', () => {
-  it('gives perm the arms it accepts', () => {
-    expect(permissionTargetOf(parseTarget('anyone'))).toEqual({ scope: 'anyone' });
-    expect(permissionTargetOf(parseTarget('group:g/admin'))).toEqual({
+describe('each command takes only its own arms', () => {
+  it('gives perm what it accepts', () => {
+    expect(parsePermissionTarget('anyone')).toEqual({ scope: 'anyone' });
+    expect(parsePermissionTarget('group:g/admin')).toEqual({
       scope: 'group',
       groupId: 'g',
       role: 'admin',
     });
-    expect(() => permissionTargetOf(parseTarget('record:01hx'))).toThrow(
-      /not something `perm` can name/,
-    );
-    expect(() => permissionTargetOf(parseTarget('authenticated'))).toThrow(/`perm` can name/);
-    expect(() => permissionTargetOf(parseTarget('group:g/any'))).toThrow(/listing role/);
+    expect(() => parsePermissionTarget('group:g/any')).toThrow(/listing role/);
   });
 
-  it('gives grant the arms it accepts, and keeps `any` to the listing', () => {
-    expect(grantTargetOf(parseTarget('authenticated'))).toEqual({ kind: 'authenticated' });
-    expect(grantQueryOf(parseTarget('group:g/any'))).toEqual({
-      kind: 'group',
-      groupId: 'g',
-      role: 'any',
-    });
-    expect(() => grantTargetOf(parseTarget('group:g/any'))).toThrow(/`any` is for `grant ls`/);
-    expect(() => grantTargetOf(parseTarget('anyone'))).toThrow(/not something `grant` can name/);
+  it('gives grant what it accepts, and keeps `any` to the listing', () => {
+    expect(parseGrantTarget('authenticated')).toEqual({ kind: 'authenticated' });
+    expect(parseGrantQuery('group:g/any')).toEqual({ kind: 'group', groupId: 'g', role: 'any' });
+    expect(() => parseGrantTarget('group:g/any')).toThrow(/`any` is for `grant ls`/);
   });
 
-  it('gives link the arms it accepts', () => {
-    expect(relationshipTargetOf(parseTarget('record:01hx@https://x'))).toEqual({
-      scope: 'record',
-      recordId: '01hx',
-      stackUrl: 'https://x',
-    });
-    expect(relationshipTargetOf(parseTarget('external:email/a@b.example'))).toEqual({
+  it('gives link what it accepts', () => {
+    expect(parseLinkTarget('external:email/a@b.example')).toEqual({
       scope: 'external',
       ns: 'email',
       id: 'a@b.example',
     });
-    expect(() => relationshipTargetOf(parseTarget('anyone'))).toThrow(
-      /not something `link` can name/,
+  });
+});
+
+describe('refusing a target from the wrong tier', () => {
+  it('sends a grant naming the world to the authenticated tier', () => {
+    expect(() => parseGrantTarget('anyone')).toThrow(/not something `grant` can name/);
+    expect(() => parseGrantTarget('anyone')).toThrow(/did you mean `authenticated`/);
+  });
+
+  it('never offers `anyone` to perm as a synonym for `authenticated`', () => {
+    // `anyone` is the wider tier, so naming it must stay a choice.
+    expect(() => parsePermissionTarget('authenticated')).toThrow(/no authenticated tier/);
+    expect(() => parsePermissionTarget('authenticated')).toThrow(
+      /wider — it reaches anonymous requesters too/,
+    );
+    expect(() => parsePermissionTarget('authenticated')).not.toThrow(/did you mean/);
+  });
+
+  it('points a link at the group’s own record, by id', () => {
+    expect(() => parseLinkTarget('group:01hxTEAM/member')).toThrow(/use record:01hxTEAM/);
+  });
+
+  it('points perm and grant at a group when handed that group’s record', () => {
+    expect(() => parsePermissionTarget('record:01hxTEAM')).toThrow(
+      /group:01hxTEAM\/<member\|admin>/,
+    );
+    expect(() => parseGrantTarget('record:01hxTEAM')).toThrow(/group:01hxTEAM\/<member\|admin>/);
+  });
+
+  it('refuses an access tier as something to link to', () => {
+    expect(() => parseLinkTarget('anyone')).toThrow(/not something a record can point at/);
+    expect(() => parseLinkTarget('authenticated')).toThrow(/not something a record can point at/);
+  });
+
+  it('always names what the command does accept', () => {
+    expect(() => parsePermissionTarget('record:01hx')).toThrow(
+      /perm accepts: anyone \| <did> \| group:<id>\/<member\|admin>/,
     );
-    expect(() => relationshipTargetOf(parseTarget('group:g/admin'))).toThrow(/`link` can name/);
+    expect(() => parseGrantQuery('anyone')).toThrow(/grant accepts: authenticated/);
+    expect(() => parseLinkTarget('anyone')).toThrow(/link accepts: <did> \| record:/);
   });
 });