fix(core): narrow the binding rules to what each one protects

Three rules introduced with the bindings reached past the thing they exist
to stop.

`_app.appId` was unique as well as immutable, which made an app's second
card unwritable. `appId` is required, so a replacement card for the same
software necessarily repeats it — and uniqueness then refused exactly the
card key rotation calls for, and the same app registered from a second
device, with no way out but hard-deleting the first card and orphaning the
`principalId` on everything it wrote. Uniqueness bought nothing there:
nothing resolves a card *by* `appId`, the cross-check reaching it by `did`
and only comparing, so `_app.did` alone already gives that lookup its single
answer. Immutability is what stops a card being moved onto a name it did not
have, and immutability stays. Uniqueness now covers the two `did` fields —
the ones something resolves by — and `UNIQUE_BINDING_FIELDS` names that
subset rather than leaving it implied by the immutability list.

The `_app` and owner-DID fences keyed on a field being *present* in the
patch, not on its value changing. Read-modify-write is the ordinary client
shape, so a write-holder sending a card back with `name` edited was refused
for round-tripping bindings it never touched — which made "`name` and
`version` stay writable" false for any client that patches with a whole
content object, and disagreed with `checkBindingImmutable()` and
`restoreVersion()`, both of which already compare values. Both fences now
ask whether the write would introduce or alter the field.

The uniqueness scan materialised the whole family through `queryAllPages()`
before testing it, so a family past that helper's cap turned every create
and update into a `StackQueryError` rather than a conflict. It now uses
`findFirstMatch()`, the same bounded walk the `appId` cross-check added
beside it, and stops at the first clash.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017JmFgdZKqgqPFGoxMBgjwn

Author: claude

docs/spec/identity.md

@@ -91,22 +91,28 @@ Linking the two is the owner's job, not the library's: an `_app` Record with a `
 
 That second rule is what makes "only the owner writes cards" true, rather than nearly true. Type-level grants are refused, but record-level `write` on an individual card is shareable like on any other Record, so a write-holder is a real writer of that card — free to correct its `name` or `version`, and refused the two fields a trust decision reads.
 
-Both fields are also **bindings** in the sense defined next, which is where uniqueness and immutability come from.
+**The rule reads values, not keys.** A write that carries `did` or `appId` unchanged is not setting it, so it is not refused: a client that reads a card, edits its `name` and sends the whole content object back is exercising exactly the reach the previous paragraph describes, and `update()` being a merge is a calling convention rather than a permission boundary. Only a write that would introduce or alter one of the two fields needs the owner. The same reading applies to the [reserved owner DID](#did-bindings) below — the refusal is on _claiming_ it — and `restoreVersion()` compares the snapshot against the Record's present content for the same reason.
+
+Both fields are also **bindings** in the sense defined next, which is where immutability — and, for `did`, uniqueness — comes from.
 
 ## DID bindings
 
 Two system types carry fields that are **lookup keys rather than display values**: something resolves _through_ them to reach a name the owner chose.
 
-| Field         | What resolves through it                        |
-| ------------- | ----------------------------------------------- |
-| `_entity.did` | a Record's `entityId` → who authored it         |
-| `_app.did`    | a Record's `principalId` → which app wrote it   |
-| `_app.appId`  | a verified principal → the `appId` it may claim |
+| Field         | What resolves through it                        | Unique |
+| ------------- | ----------------------------------------------- | ------ |
+| `_entity.did` | a Record's `entityId` → who authored it         | yes    |
+| `_app.did`    | a Record's `principalId` → which app wrote it   | yes    |
+| `_app.appId`  | a verified principal → the `appId` it may claim | no     |
+
+A binding is not a value a card happens to hold; it is what makes the card _about_ something. Two rules follow:
+
+- **Immutable once set** — every field in the table. Adopting a value is a one-way step a card carrying none can still take, but a card that holds one never moves off it: `update()` and `restoreVersion()` both refuse to change or clear a binding with `StackValidationError`. This is the rule that stops an existing card being _moved_ onto a value — repointed at another key, or relabelled to claim another app's `appId` — which is impersonation by a quieter route than minting a card.
+- **Unique within a stack** — the two `did` fields, the ones a lookup resolves _by_. A second card claiming a value already in use is refused with `StackConflictError`, on create and on update. A soft-deleted card keeps its claim: a deleted card is `undelete()`-able, so releasing the value on delete would let a new card take it and the old one come back beside it. Without uniqueness, "the Record whose `did` matches" has no single answer — and ambiguity is all an impersonating card needs.
 
-A binding is not a value a card happens to hold; it is what makes the card _about_ something. Two rules follow, and they apply to every field in that table:
+**`_app.appId` is immutable but not unique**, and the asymmetry is load-bearing. Nothing resolves a card _by_ `appId`: the cross-check finds the card by `content.did` and only compares `appId` to what the principal claimed, so `_app.did` being unique already gives that lookup its single answer. Uniqueness on `appId` would add no disambiguation and would forbid a state the stack has to be able to reach — two cards naming the same software under different keys. `appId` is required, so a card for an app's new key necessarily repeats it, and without the exemption the replacement card that [key rotation](#deferred-key-rotation) calls for could not be written at all, nor the same app registered on a second device. Both cards are the owner's own to write, `_app` being ungrantable; what stays refused is moving an _existing_ card onto an `appId` it did not have.
 
-- **Unique within a stack.** A second card claiming a value already in use is refused with `StackConflictError`, on create and on update. A soft-deleted card keeps its claim: a deleted card is `undelete()`-able, so releasing the value on delete would let a new card take it and the old one come back beside it. Without uniqueness, "the Record whose `did` matches" has no single answer — and ambiguity is all an impersonating card needs.
-- **Immutable once set.** Uniqueness stops a second card claiming a value; only immutability stops an existing card being _moved_ onto one, which reaches the same impersonation by another route. `update()` and `restoreVersion()` both refuse to change or clear a binding with `StackValidationError`. Adopting a value is a one-way step a card carrying none can still take. A subject whose key changes gets a new card, matching this document's deferral of [key rotation](#deferred-key-rotation) — a new key is a new identity, not the same one relabelled.
+A subject whose key changes therefore gets a new card, matching this document's deferral of [key rotation](#deferred-key-rotation) — a new key is a new identity, not the same one relabelled. Records written under the old key keep pointing at the old card, which is what makes their attribution still resolvable.
 
 **`_entity` stays grantable; `_app` does not.** Naming people is ordinary app work — a contacts app creates and relabels cards — so `_entity` cards are reachable by grant and only the two binding rules fence them. Naming software is a trust decision about who may speak as what, so `_app` adds the owner-only rule above. The asymmetry is deliberate: both registries resolve a name, but only one of them is deciding whether to believe a claim.
 
@@ -175,4 +181,4 @@ Token issuance (see [Wire format § Authentication](./wire-format.md#authenticat
 
 ## Deferred: key rotation
 
-With pure `did:key`, identity _is_ the key: lose it and you're a new identity. For individuals and small groups who know each other, that's a recoverable social event ("new key, it's me" over a trusted channel; contacts update their `_entity` cards), not a protocol failure. Rotation — a signed chain of "key A hands off to key B" records, hosted by the stack itself — is a native fit for a future RFC, but nothing here blocks it: a rotated identity is either a new DID _documented by_ that log, or a method upgrade (`did:key` → stack-hosted method) for those who opt in. Multi-device works without rotation in the meantime: the identity key bootstraps a session per device via challenge–response; devices hold revocable tokens, never the key.
+With pure `did:key`, identity _is_ the key: lose it and you're a new identity. For individuals and small groups who know each other, that's a recoverable social event ("new key, it's me" over a trusted channel; contacts card the new key), not a protocol failure. Carding it is a new `_entity` record rather than an edit to the old one — [`did` is immutable once set](#did-bindings), which is the same rule that lets an app's replacement card carry the `appId` its predecessor already claimed. Rotation — a signed chain of "key A hands off to key B" records, hosted by the stack itself — is a native fit for a future RFC, but nothing here blocks it: a rotated identity is either a new DID _documented by_ that log, or a method upgrade (`did:key` → stack-hosted method) for those who opt in. Multi-device works without rotation in the meantime: the identity key bootstraps a session per device via challenge–response; devices hold revocable tokens, never the key.

packages/core/src/stack.ts

@@ -84,17 +84,40 @@ const UNGRANTABLE_SYSTEM_TYPES: ReadonlySet<string> = new Set([
 
 /**
  * Content fields that are lookup keys rather than display values: a card
- * claims one, and something later resolves through it. Each is unique per
- * stack and immutable once set. See docs/spec/identity.md § DID bindings.
+ * claims one, and something later resolves through it. Every one of them is
+ * immutable once set. See docs/spec/identity.md § DID bindings.
  */
 const BINDING_FIELDS: ReadonlyMap<string, readonly ('did' | 'appId')[]> = new Map([
   [SYSTEM_TYPES.APP, ['did', 'appId'] as const],
   [SYSTEM_TYPES.ENTITY, ['did'] as const],
 ]);
 
+/**
+ * The subset that is additionally unique per stack: the fields something
+ * resolves *by*. A Record's `principalId` finds its card by `_app.did` and
+ * its `entityId` by `_entity.did`, so a second card claiming either leaves
+ * that lookup without a single answer — and ambiguity is all an
+ * impersonating card needs.
+ *
+ * `_app.appId` is deliberately absent. Nothing resolves a card by it — the
+ * cross-check reaches the card by `did` and only compares `appId` — so
+ * uniqueness would buy no disambiguation, while forbidding the second card
+ * key rotation is supposed to produce: `appId` is required, so a
+ * replacement card for the same software necessarily repeats it. Moving one
+ * card onto another's `appId` is what immutability already refuses.
+ * See docs/spec/identity.md § DID bindings.
+ */
+const UNIQUE_BINDING_FIELDS: ReadonlyMap<string, readonly ('did' | 'appId')[]> = new Map([
+  [SYSTEM_TYPES.APP, ['did'] as const],
+  [SYSTEM_TYPES.ENTITY, ['did'] as const],
+]);
+
 const bindingFieldsOf = (family: string): readonly ('did' | 'appId')[] =>
   BINDING_FIELDS.get(family) ?? [];
 
+const uniqueBindingFieldsOf = (family: string): readonly ('did' | 'appId')[] =>
+  UNIQUE_BINDING_FIELDS.get(family) ?? [];
+
 export type CreateRecordOptions = {
   /**
    * Client-minted record ID. Must be 12 lowercase Crockford base-32
@@ -1297,21 +1320,22 @@ export class Stack implements StackClient {
     });
   }
 
-  /** Uniqueness for every binding field a newly created card claims. */
+  /** Uniqueness for every unique binding field a newly created card claims. */
   private async checkBindingsOnCreate(
     typeId: TypeId,
     content: Record<string, unknown>,
   ): Promise<void> {
     const family = baseIdOf(typeId);
-    for (const field of bindingFieldsOf(family)) {
+    for (const field of uniqueBindingFieldsOf(family)) {
       await this.checkBindingUnique(family, field, content[field]);
     }
   }
 
   /**
-   * Immutability then uniqueness for every binding field a patch touches.
-   * Fields absent from the patch carry no new claim — update() is a merge,
-   * so an untouched binding is the one the card already holds.
+   * Immutability for every binding field a patch touches, then uniqueness
+   * for the subset that carries it. Fields absent from the patch carry no
+   * new claim — update() is a merge, so an untouched binding is the one the
+   * card already holds.
    */
   private async checkBindingsOnUpdate(
     typeId: TypeId,
@@ -1321,21 +1345,27 @@ export class Stack implements StackClient {
     merged: Record<string, unknown>,
   ): Promise<void> {
     const family = baseIdOf(typeId);
+    const unique = uniqueBindingFieldsOf(family);
     for (const field of bindingFieldsOf(family)) {
       if (!(field in patch)) continue;
       this.checkBindingImmutable(family, field, existing[field], merged[field]);
-      await this.checkBindingUnique(family, field, merged[field], id);
+      if (unique.includes(field)) {
+        await this.checkBindingUnique(family, field, merged[field], id);
+      }
     }
   }
 
   /**
-   * A card's binding field is what a lookup resolves through — a record's
-   * `principalId` through `_app.did`, its `entityId` through `_entity.did`,
-   * a claimed `appId` through `_app.appId`. Two cards claiming one value
-   * would make that lookup ambiguous, and ambiguity is all an impersonating
-   * card needs. Enforced here rather than by schema, since uniqueness is a
-   * property of the set, not of the value. Called by the paths that can
-   * introduce a binding: create and update.
+   * A unique binding field is what a lookup resolves *by* — a record's
+   * `principalId` by `_app.did`, its `entityId` by `_entity.did`. Two cards
+   * claiming one value would leave that lookup without a single answer, and
+   * ambiguity is all an impersonating card needs. Enforced here rather than
+   * by schema, since uniqueness is a property of the set, not of the value.
+   * Called by the paths that can introduce a binding: create and update.
+   *
+   * Short-circuits on the first clash rather than materialising the family,
+   * so a stack whose `_entity` family is larger than a single scan settles
+   * the common case — the value is already taken — without walking the rest.
    *
    * Read-then-write, so two creates racing on one value can both pass.
    * Closing that properly means a unique index over a JSON field, which
@@ -1351,14 +1381,15 @@ export class Stack implements StackClient {
   ): Promise<void> {
     if (typeof value !== 'string' || value === '') return;
 
-    const results = await queryAllPages((q) => this.query(q), {
-      filter: {
-        baseId: family,
-        includeDeleted: true,
-        ...(this.features.contentFieldQuery && { content: { [field]: value } }),
+    const clash = await findFirstMatch(
+      (q) => this.query(q),
+      {
+        filter: {
+          baseId: family,
+          includeDeleted: true,
+          ...(this.features.contentFieldQuery && { content: { [field]: value } }),
+        },
       },
-    });
-    const clash = results.some(
       (r) => r.id !== excludeId && (r.content as Record<string, unknown>)[field] === value,
     );
     if (clash) {
@@ -2483,8 +2514,20 @@ export class ScopedStack implements StackClient {
     opts: IfVersionOptions = {},
   ): Promise<StackRecord> {
     const record = await this.requireUpdatable(id);
-    this.requireOwnerForAppIdentity(record.typeId, (field) => field in content);
-    if ('did' in content) this.requireOwnerForOwnerDid(record.typeId, content.did);
+    // Value-wise, not presence-wise: a client that reads a card, edits its
+    // `name` and sends the whole content object back is not setting the
+    // binding it round-trips, and `name` is writable by record-level
+    // permission. Same predicate restoreVersion() applies to a snapshot.
+    this.requireOwnerForAppIdentity(
+      record.typeId,
+      (field) =>
+        field in content && content[field] !== (record.content as Record<string, unknown>)[field],
+    );
+    // Likewise value-wise: re-sending the DID a card already holds claims
+    // nothing, and immutability refuses changing it regardless.
+    if ('did' in content && content.did !== (record.content as Record<string, unknown>).did) {
+      this.requireOwnerForOwnerDid(record.typeId, content.did);
+    }
     await this.requireFileRefAccess(record.typeId, content);
     return this.stack.update(id, content, opts);
   }

packages/core/tests/scoped-stack.test.ts

@@ -2344,6 +2344,32 @@ describe('ScopedStack — _app bindings', () => {
     const updated = await stack.asEntity(MEMBER).update(shared.id, { version: '2.0.0' });
     expect((updated.content as { did?: string }).did).toBe(APP_DID);
   });
+
+  // The fence reads values, not keys. Read-modify-write is the ordinary
+  // client shape, and a card sent back with its bindings untouched is
+  // exercising the display-field reach the test above pins — a presence
+  // check would make that reach unreachable for any client that round-trips
+  // the whole content object.
+  test('a write-holder may round-trip unchanged bindings in a full-content update', async () => {
+    const shared = await stack.create('_app@1', {
+      appId: 'com.example.notes',
+      name: 'My Notes App',
+      did: APP_DID,
+    });
+    await stack.setPermissions(shared.id, [
+      { access: 'entity', entityId: MEMBER, read: true, write: true },
+    ]);
+
+    const scoped = stack.asEntity(MEMBER);
+    const current = await scoped.get(shared.id);
+    const updated = await scoped.update(shared.id, { ...current!.content, name: 'Renamed' });
+
+    expect(updated.content).toMatchObject({
+      appId: 'com.example.notes',
+      name: 'Renamed',
+      did: APP_DID,
+    });
+  });
 });
 
 // The owner-only rule covers both halves of the attribution lookup: a
@@ -2443,6 +2469,21 @@ describe('ScopedStack — _entity bindings hold under a grant', () => {
         .create('_entity@1', { did: OWNER, name: 'Owner, per the app' }),
     ).rejects.toThrow(StackPermissionError);
   });
+
+  // The reservation is on *claiming* the DID. Re-sending the value a card
+  // already holds claims nothing, and immutability refuses changing it — so
+  // refusing the round-trip would only stop a grantee relabelling the card,
+  // which is the reach a grant on _entity exists to give.
+  test('a grantee may relabel the owner card while round-tripping its DID', async () => {
+    const ownerCard = await stack.asEntity(OWNER).create('_entity@1', { did: OWNER, name: 'Me' });
+    await stack.grant(MEMBER, [{ typeId: '_entity@1', actions: ['read-any', 'update-any'] }]);
+
+    const scoped = stack.asEntity(MEMBER);
+    const current = await scoped.get(ownerCard.id);
+    const updated = await scoped.update(ownerCard.id, { ...current!.content, name: 'The Owner' });
+
+    expect(updated.content).toMatchObject({ did: OWNER, name: 'The Owner' });
+  });
 });
 
 describe('ScopedStack — _grant records are owner-write-only', () => {

packages/core/tests/stack.test.ts

@@ -2994,10 +2994,31 @@ describe('_app.did bindings', () => {
 describe('_app.appId bindings', () => {
   const APP_DID = 'did:key:z6MkNotesApp';
 
-  test('rejects a second card claiming an appId already in use', async () => {
-    await stack.create('_app@1', { appId: 'com.example.notes', name: 'My Notes App' });
+  // appId is immutable but not unique: nothing resolves a card by it, and
+  // requiring it while forbidding a second card holding it would make the
+  // replacement card key rotation calls for unwritable.
+  test('a second card may claim the same appId under a different did', async () => {
+    await stack.create('_app@1', {
+      appId: 'com.example.notes',
+      name: 'My Notes App',
+      did: APP_DID,
+    });
+    const rotated = await stack.create('_app@1', {
+      appId: 'com.example.notes',
+      name: 'My Notes App',
+      did: 'did:key:z6MkNotesAppRotated',
+    });
+    expect((rotated.content as { appId: string }).appId).toBe('com.example.notes');
+  });
+
+  test('the did on those cards is still unique', async () => {
+    await stack.create('_app@1', {
+      appId: 'com.example.notes',
+      name: 'My Notes App',
+      did: APP_DID,
+    });
     await expect(
-      stack.create('_app@1', { appId: 'com.example.notes', name: 'Impostor' }),
+      stack.create('_app@1', { appId: 'com.example.other', name: 'Impostor', did: APP_DID }),
     ).rejects.toThrow(StackConflictError);
   });
 
@@ -3068,6 +3089,23 @@ describe('_entity.did bindings', () => {
     const restored = await stack.restoreVersion(alice.id, 1);
     expect((restored.content as { did: string }).did).toBe(ALICE);
   });
+
+  // Without contentFieldQuery the check cursor-walks the family and stops at
+  // the first clash, so a colliding card past page one must still be found —
+  // short-circuiting is what keeps the walk bounded, not a narrower scan.
+  test('finds a clash past page one on an adapter without contentFieldQuery', async () => {
+    const incapable = await Stack.create(
+      new IncapableMemoryAdapter({ ownerEntityId: 'owner-123', timezone: 'UTC' }),
+    );
+    for (let i = 0; i < 60; i++) {
+      await incapable.create('_entity@1', { did: `did:key:filler${i}`, name: `Filler ${i}` });
+    }
+    await incapable.create('_entity@1', { did: ALICE, name: 'Alice' });
+
+    await expect(
+      incapable.create('_entity@1', { did: ALICE, name: 'Alice (impostor)' }),
+    ).rejects.toThrow(StackConflictError);
+  });
 });
 
 // grant() refuses these families, but a _grant record is an ordinary Record