@haverstack/adapter-conformance 0.11.0 → 0.13.0

package/dist/record.js

@@ -21,8 +21,9 @@
  */
 import { describe, test, expect, beforeEach, afterEach } from 'vitest';
 import { SYSTEM_TYPES } from '@haverstack/core';
+import { ElementSetMovedError, inReach, resolveQuery } from '@haverstack/core/adapter';
 import { expectStackErrorCode } from './errors.js';
-import { CONFORMANCE_TYPE_ID, conformanceType, makeRecord, uniqueId } from './helpers.js';
+import { CONFORMANCE_TYPE_ID, conformanceType, makeRecord, snapshotOf, uniqueId, } from './helpers.js';
 export function runRecordAdapterConformance(options) {
     const { name, open, close, capabilities } = options;
     describe(`record adapter conformance: ${name}`, () => {
@@ -42,37 +43,48 @@ export function runRecordAdapterConformance(options) {
             opened = false;
             await close?.(adapter);
         });
+        /**
+         * Patch `record` `count` times, each patch snapshotting the version it
+         * replaces, as Stack does: versions 1 through `count` end up stored.
+         */
+        const patchWithSnapshots = async (record, count) => {
+            let current = record;
+            for (let i = 0; i < count; i++) {
+                current = await adapter.patchContent(current.id, { title: `v${current.version + 1}` }, { snapshot: snapshotOf(current) });
+            }
+            return current;
+        };
         // -----------------------------------------------------------------
         // Capabilities
         // -----------------------------------------------------------------
         describe('capabilities', () => {
             test('declares a well-formed StackCapabilities object', () => {
                 expect(['none', 'field', 'path']).toContain(capabilities.filter.content);
-                expect(typeof capabilities.filter.contentPresent).toBe('boolean');
-                expect(typeof capabilities.filter.search).toBe('boolean');
-                expect(Array.isArray(capabilities.sort.fields)).toBe(true);
-                expect(typeof capabilities.sort.contentField).toBe('boolean');
-                for (const cap of [
+                for (const flag of [
+                    capabilities.filter.contentPresent,
                     capabilities.filter.contentByType,
+                    capabilities.filter.search,
+                    capabilities.sort.contentField,
                     capabilities.sort.contentFieldByType,
                 ]) {
-                    expect(Number.isInteger(cap) && cap >= 0).toBe(true);
-                }
-            });
-            test('the per-Type caps are 0 whenever filter.content is "none"', () => {
-                // Both travel in the body of the endpoint a reach of "none" omits.
-                if (capabilities.filter.content === 'none') {
-                    expect(capabilities.filter.contentByType).toBe(0);
-                    expect(capabilities.sort.contentFieldByType).toBe(0);
+                    expect(typeof flag).toBe('boolean');
                 }
+                expect(Array.isArray(capabilities.sort.fields)).toBe(true);
             });
-            test('filter.contentPresent is false whenever filter.content is "none"', () => {
-                // contentPresent asks whether a value is there at all — meaningless
-                // to promise from an adapter that reaches no content to look at.
+            // Each travels only in the POST /records/query body, which a reach of
+            // "none" does not serve.
+            test('what needs the query body is false whenever filter.content is "none"', () => {
                 if (capabilities.filter.content === 'none') {
                     expect(capabilities.filter.contentPresent).toBe(false);
+                    expect(capabilities.filter.contentByType).toBe(false);
+                    expect(capabilities.sort.contentFieldByType).toBe(false);
                 }
             });
+            // A query naming no sort reads `createdAt`, newest first, so every
+            // adapter already orders by it.
+            test('sort.fields includes createdAt', () => {
+                expect(capabilities.sort.fields).toContain('createdAt');
+            });
         });
         // -----------------------------------------------------------------
         // Types
@@ -122,44 +134,79 @@ export function runRecordAdapterConformance(options) {
                 await expectStackErrorCode(adapter.createRecord(makeRecord({ id: record.id })), 'conflict');
                 expect((await adapter.getRecord(record.id))?.content).toEqual(record.content);
             });
-            test('mutateRecord merges the content patch at the top level and bumps version', async () => {
+            test('patchContent merges the patch at the top level and bumps version', async () => {
                 const record = makeRecord({ content: { title: 'Before', priority: 1 } });
                 await adapter.createRecord(record);
-                const updated = await adapter.mutateRecord(record.id, {
-                    contentPatch: { title: 'After' },
-                });
+                const updated = await adapter.patchContent(record.id, { title: 'After' });
                 expect(updated.content).toEqual({ title: 'After', priority: 1 });
                 expect(updated.version).toBe(record.version + 1);
             });
-            // A change set naming only aspects the journal keeps in full arrives
-            // with `bumpsVersion: false`. The columns still land; `version`,
-            // `updatedAt` and the actor stamps do not move.
+            // The aspects the journal keeps in full never bump: the column lands,
+            // and `version`, `updatedAt` and the actor stamps do not move.
             // See docs/spec/versioning.md § Version history.
-            test('a no-bump mutateRecord writes parentId and unlisted without moving version', async () => {
+            test('setParent and setUnlisted write their column without moving version', async () => {
                 const parent = makeRecord();
                 await adapter.createRecord(parent);
                 const record = makeRecord({ content: { title: 'Hello' } });
                 await adapter.createRecord(record);
-                const moved = await adapter.mutateRecord(record.id, { parentId: parent.id }, { bumpsVersion: false });
+                const moved = await adapter.setParent(record.id, parent.id);
                 expect(moved.parentId).toBe(parent.id);
                 expect(moved.version).toBe(record.version);
                 expect(moved.updatedAt).toEqual(record.updatedAt);
-                const unlisted = await adapter.mutateRecord(record.id, { unlisted: true }, { bumpsVersion: false });
+                const unlisted = await adapter.setUnlisted(record.id, true);
                 expect(unlisted.unlistedAt).toBeInstanceOf(Date);
                 expect(unlisted.version).toBe(record.version);
                 expect(unlisted.parentId).toBe(parent.id);
-                const listed = await adapter.mutateRecord(record.id, { unlisted: false }, { bumpsVersion: false });
+                const listed = await adapter.setUnlisted(record.id, false);
                 expect(listed.unlistedAt).toBeUndefined();
                 expect(listed.version).toBe(record.version);
+                const rooted = await adapter.setParent(record.id, null);
+                expect(rooted.parentId).toBeUndefined();
             });
-            test('a no-bump mutateRecord takes no snapshot', async () => {
+            test('a write that does not bump takes no snapshot', async () => {
                 const parent = makeRecord();
                 await adapter.createRecord(parent);
                 const record = makeRecord();
                 await adapter.createRecord(record);
-                await adapter.mutateRecord(record.id, { parentId: parent.id }, { bumpsVersion: false });
+                await adapter.setParent(record.id, parent.id);
+                await adapter.setUnlisted(record.id, true);
+                await adapter.setAssociations(record.id, [{ kind: 'tag', label: 'x' }]);
+                await adapter.setAccess(record.id, [{ kind: 'anyone', label: 'read' }]);
                 expect(await adapter.getVersions(record.id)).toEqual([]);
             });
+            // Every write checks its precondition inside its own write, whether
+            // or not it bumps. See docs/spec/versioning.md § Optimistic concurrency.
+            test('every write refuses a stale ifVersion and changes nothing', async () => {
+                const parent = makeRecord();
+                await adapter.createRecord(parent);
+                const record = makeRecord({ content: { title: 'v1' } });
+                await adapter.createRecord(record);
+                const stale = { ifVersion: record.version + 1 };
+                const tag = { kind: 'tag', label: 'x' };
+                const anyone = { kind: 'anyone', label: 'read' };
+                for (const write of [
+                    () => adapter.patchContent(record.id, { title: 'v2' }, stale),
+                    () => adapter.setParent(record.id, parent.id, stale),
+                    () => adapter.setUnlisted(record.id, true, stale),
+                    () => adapter.editAssociations(record.id, [{ op: 'add', association: tag }], stale),
+                    () => adapter.setAssociations(record.id, [tag], stale),
+                    () => adapter.editAccess(record.id, [{ op: 'add', association: anyone }], stale),
+                    () => adapter.setAccess(record.id, [anyone], stale),
+                ]) {
+                    await expectStackErrorCode(write(), 'version_conflict');
+                }
+                const after = await adapter.getRecord(record.id);
+                expect(after.content).toEqual({ title: 'v1' });
+                expect(after.parentId).toBeUndefined();
+                expect(after.unlistedAt).toBeUndefined();
+                expect(after.associations ?? []).toEqual([]);
+                expect(after.permissions ?? []).toEqual([]);
+                const current = { ifVersion: record.version };
+                expect((await adapter.setParent(record.id, parent.id, current)).parentId).toBe(parent.id);
+                expect((await adapter.setAccess(record.id, [anyone], current)).permissions).toEqual([
+                    anyone,
+                ]);
+            });
             test('soft deleteRecord sets deletedAt; undeleteRecord clears it', async () => {
                 const record = makeRecord();
                 await adapter.createRecord(record);
@@ -171,27 +218,13 @@ export function runRecordAdapterConformance(options) {
             test('getVersions returns snapshots newest first', async () => {
                 const record = makeRecord();
                 await adapter.createRecord(record);
-                for (const version of [1, 2, 3]) {
-                    await adapter.saveVersion(record.id, {
-                        version,
-                        typeId: record.typeId,
-                        content: record.content,
-                        updatedAt: record.updatedAt,
-                    });
-                }
+                await patchWithSnapshots(record, 3);
                 expect((await adapter.getVersions(record.id)).map((v) => v.version)).toEqual([3, 2, 1]);
             });
             test('getVersions pages walk every version exactly once, newest first', async () => {
                 const record = makeRecord();
                 await adapter.createRecord(record);
-                for (const version of [1, 2, 3, 4, 5]) {
-                    await adapter.saveVersion(record.id, {
-                        version,
-                        typeId: record.typeId,
-                        content: record.content,
-                        updatedAt: record.updatedAt,
-                    });
-                }
+                await patchWithSnapshots(record, 5);
                 const seen = [];
                 let beforeVersion;
                 for (;;) {
@@ -207,14 +240,7 @@ export function runRecordAdapterConformance(options) {
             test('getVersions beforeVersion is exclusive and limit bounds the result', async () => {
                 const record = makeRecord();
                 await adapter.createRecord(record);
-                for (const version of [1, 2, 3]) {
-                    await adapter.saveVersion(record.id, {
-                        version,
-                        typeId: record.typeId,
-                        content: record.content,
-                        updatedAt: record.updatedAt,
-                    });
-                }
+                await patchWithSnapshots(record, 3);
                 const versionsOf = async (query) => (await adapter.getVersions(record.id, query)).map((v) => v.version);
                 expect(await versionsOf({ beforeVersion: 3 })).toEqual([2, 1]);
                 expect(await versionsOf({ beforeVersion: 1 })).toEqual([]);
@@ -225,12 +251,7 @@ export function runRecordAdapterConformance(options) {
             test('purging deleteRecord removes the record and its version history', async () => {
                 const record = makeRecord();
                 await adapter.createRecord(record);
-                await adapter.saveVersion(record.id, {
-                    version: record.version,
-                    typeId: record.typeId,
-                    content: record.content,
-                    updatedAt: record.updatedAt,
-                });
+                await patchWithSnapshots(record, 1);
                 await adapter.deleteRecord(record.id, { purge: true });
                 expect(await adapter.getRecord(record.id)).toBeNull();
                 expect(await adapter.getVersions(record.id)).toEqual([]);
@@ -245,7 +266,7 @@ export function runRecordAdapterConformance(options) {
                 // initialization, outside this interface — nothing here writes it.
                 // The invariant holds either way: if the adapter under test has one,
                 // a generic query must still never surface it.
-                const { records } = await adapter.queryRecords({});
+                const { records } = await adapter.queryRecords(resolveQuery({}));
                 expect(records.some((r) => r.id === SYSTEM_TYPES.CONFIG)).toBe(false);
             });
         });
@@ -254,15 +275,28 @@ export function runRecordAdapterConformance(options) {
         // -----------------------------------------------------------------
         describe('associations', () => {
             const tag = (label) => ({ kind: 'tag', label });
+            // A tag filter is conjunctive, and its length is the caller's — far
+            // past any statement's parameter cap (100 on Durable Object SQLite).
+            test('a tag filter matches the records carrying every tag named, however many', async () => {
+                const labels = Array.from({ length: 120 }, (_, i) => `tag-${i}`);
+                const all = makeRecord({ associations: labels.map((label) => ({ kind: 'tag', label })) });
+                const allButOne = makeRecord({
+                    associations: labels.slice(1).map((label) => ({ kind: 'tag', label })),
+                });
+                await adapter.createRecord(all);
+                await adapter.createRecord(allButOne);
+                const result = await adapter.queryRecords(resolveQuery({ filter: { tags: [...labels, labels[0]] } }));
+                expect(result.records.map((r) => r.id)).toEqual([all.id]);
+            });
             test('an add puts a tag on the record and a remove takes it off; neither bumps version', async () => {
                 const record = makeRecord();
                 await adapter.createRecord(record);
-                const tagged = await adapter.amendAssociations(record.id, [
+                const tagged = await adapter.editAssociations(record.id, [
                     { op: 'add', association: { kind: 'tag', label: 'important' } },
                 ]);
                 expect(tagged.associations).toContainEqual({ kind: 'tag', label: 'important' });
                 expect(tagged.version).toBe(record.version);
-                const untagged = await adapter.amendAssociations(record.id, [
+                const untagged = await adapter.editAssociations(record.id, [
                     {
                         op: 'remove',
                         association: {
@@ -280,24 +314,23 @@ export function runRecordAdapterConformance(options) {
             test('an add is idempotent — a duplicate does not create a second entry', async () => {
                 const record = makeRecord();
                 await adapter.createRecord(record);
-                await adapter.amendAssociations(record.id, [
+                await adapter.editAssociations(record.id, [
                     { op: 'add', association: { kind: 'tag', label: 'dup' } },
                 ]);
-                const twice = await adapter.amendAssociations(record.id, [
+                const twice = await adapter.editAssociations(record.id, [
                     { op: 'add', association: { kind: 'tag', label: 'dup' } },
                 ]);
                 expect(twice.associations?.filter((a) => a.kind === 'tag' && a.label === 'dup')).toHaveLength(1);
             });
-            test('an amend on a nonexistent record reports not_found rather than creating an orphan', async () => {
-                await expectStackErrorCode(adapter.amendAssociations(uniqueId('missing'), [
+            test('an edit on a nonexistent record reports not_found rather than creating an orphan', async () => {
+                await expectStackErrorCode(adapter.editAssociations(uniqueId('missing'), [
                     { op: 'add', association: { kind: 'tag', label: 'x' } },
                 ]), 'not_found');
             });
-            // Authority and data share one stored set, projected into two
-            // fields by kind. Every adapter partitions it for itself, so the
-            // agreement is worth pinning here rather than once per adapter.
+            // Data associations and permissions are two aspects, stored apart:
+            // a write to one never reads or moves the other.
             // See docs/spec/access-control.md § Record-level permissions.
-            test('authority kinds travel the same call and project onto permissions', async () => {
+            test('permissions are their own aspect, edited and replaced apart from associations', async () => {
                 const record = makeRecord();
                 await adapter.createRecord(record);
                 const grant = {
@@ -305,20 +338,21 @@ export function runRecordAdapterConformance(options) {
                     label: 'read',
                     grantee: { kind: 'entity', entityId: 'did:key:z6MkConformance' },
                 };
-                await adapter.amendAssociations(record.id, [
-                    { op: 'add', association: { kind: 'tag', label: 'draft' } },
-                ]);
-                const granted = await adapter.amendAssociations(record.id, [
-                    { op: 'add', association: grant },
-                ]);
+                // A grantee and a relationship target naming the same entity are
+                // two different facts.
+                const related = {
+                    kind: 'relationship',
+                    label: 'read',
+                    target: { kind: 'entity', entityId: 'did:key:z6MkConformance' },
+                };
+                await adapter.editAssociations(record.id, [{ op: 'add', association: related }]);
+                const granted = await adapter.editAccess(record.id, [{ op: 'add', association: grant }]);
                 expect(granted.permissions).toEqual([grant]);
-                expect(granted.associations).toEqual([{ kind: 'tag', label: 'draft' }]);
+                expect(granted.associations).toEqual([related]);
                 expect(granted.version).toBe(record.version);
-                const revoked = await adapter.amendAssociations(record.id, [
-                    { op: 'remove', association: grant },
-                ]);
+                const revoked = await adapter.editAccess(record.id, [{ op: 'remove', association: grant }]);
                 expect(revoked.permissions ?? []).toEqual([]);
-                expect(revoked.associations).toEqual([{ kind: 'tag', label: 'draft' }]);
+                expect(revoked.associations).toEqual([related]);
             });
             test('a group grantee keeps its role — member and admin are two entries', async () => {
                 const record = makeRecord();
@@ -331,18 +365,16 @@ export function runRecordAdapterConformance(options) {
                 });
                 const member = forRole('member');
                 const admin = forRole('admin');
-                await adapter.amendAssociations(record.id, [{ op: 'add', association: member }]);
-                const both = await adapter.amendAssociations(record.id, [
-                    { op: 'add', association: admin },
-                ]);
+                await adapter.editAccess(record.id, [{ op: 'add', association: member }]);
+                const both = await adapter.editAccess(record.id, [{ op: 'add', association: admin }]);
                 expect(both.permissions).toEqual(expect.arrayContaining([member, admin]));
                 expect(both.permissions).toHaveLength(2);
             });
             test('a list of adds and removes lands as one write that bumps no version', async () => {
                 const record = makeRecord();
                 await adapter.createRecord(record, { journal: { ops: ['create'], kind: 'created' } });
-                await adapter.amendAssociations(record.id, [{ op: 'add', association: tag('old') }]);
-                const amended = await adapter.amendAssociations(record.id, [
+                await adapter.editAssociations(record.id, [{ op: 'add', association: tag('old') }]);
+                const amended = await adapter.editAssociations(record.id, [
                     { op: 'remove', association: tag('old') },
                     { op: 'add', association: tag('new') },
                     { op: 'add', association: tag('extra') },
@@ -353,64 +385,144 @@ export function runRecordAdapterConformance(options) {
                 expect(amended.updatedAt).toEqual(record.updatedAt);
                 expect(await adapter.getJournal(record.id)).toHaveLength(2);
             });
-            test('edits naming one identity collapse, last wins', async () => {
+            // The compare-and-swap Stack retries on: the set its rules were asked
+            // of must be the set the write lands on. Order is not part of a set.
+            // See docs/spec/adapters.md § Editing associations.
+            test('an element write refuses an expectSet the stored set no longer matches, and changes nothing', async () => {
                 const record = makeRecord();
                 await adapter.createRecord(record);
-                const fileId = 'c'.repeat(64);
-                const first = {
-                    kind: 'attachment',
-                    label: 'cover',
-                    fileId,
-                    attachmentRecordId: 'one',
-                };
-                const second = { ...first, attachmentRecordId: 'two' };
-                const amended = await adapter.amendAssociations(record.id, [
-                    { op: 'add', association: first },
-                    { op: 'add', association: second },
-                ]);
-                expect(amended.associations).toEqual([second]);
+                const anyone = { kind: 'anyone', label: 'read' };
+                await adapter.setAssociations(record.id, [tag('a'), tag('b')]);
+                await adapter.setAccess(record.id, [anyone]);
+                const journal = { ops: ['associate'], kind: 'changed' };
+                const staleTags = { expectSet: [tag('a')], journal };
+                const stalePermissions = { expectSet: [], journal };
+                for (const write of [
+                    () => adapter.editAssociations(record.id, [{ op: 'add', association: tag('c') }], staleTags),
+                    () => adapter.setAssociations(record.id, [tag('c')], staleTags),
+                    () => adapter.editAccess(record.id, [{ op: 'remove', association: anyone }], stalePermissions),
+                    () => adapter.setAccess(record.id, [], stalePermissions),
+                ]) {
+                    await expect(write()).rejects.toBeInstanceOf(ElementSetMovedError);
+                }
+                const after = await adapter.getRecord(record.id);
+                expect(after.associations).toEqual(expect.arrayContaining([tag('a'), tag('b')]));
+                expect(after.associations).toHaveLength(2);
+                expect(after.permissions).toEqual([anyone]);
+                expect(await adapter.getJournal(record.id)).toHaveLength(0);
+                const held = await adapter.editAssociations(record.id, [{ op: 'add', association: tag('c') }], { expectSet: [tag('b'), tag('a')] });
+                expect(held.associations).toHaveLength(3);
+                const cleared = await adapter.setAccess(record.id, [], { expectSet: [anyone] });
+                expect(cleared.permissions ?? []).toEqual([]);
             });
-            test('a list mixing authority and data elements is refused and applies nothing', async () => {
+            // Asked before ifVersion: the stale version here would otherwise
+            // answer 412 for a record whose state is the reason for refusing.
+            // See docs/spec/adapters.md § Interface split.
+            test('an aspect write refuses a soft-deleted record, and changes nothing', async () => {
+                const parent = makeRecord();
                 const record = makeRecord();
+                await adapter.createRecord(parent);
                 await adapter.createRecord(record);
-                const grant = { kind: 'anyone', label: 'read' };
-                await expectStackErrorCode(adapter.amendAssociations(record.id, [
-                    { op: 'add', association: tag('mixed') },
-                    { op: 'add', association: grant },
-                ]), 'bad_request');
-                const after = await adapter.getRecord(record.id);
-                expect(after.associations ?? []).toEqual([]);
-                expect(after.permissions ?? []).toEqual([]);
+                await adapter.deleteRecord(record.id);
+                const before = await adapter.getRecord(record.id);
+                const journalBefore = await adapter.getJournal(record.id);
+                const anyone = { kind: 'anyone', label: 'read' };
+                const journal = { ops: ['associate'], kind: 'changed' };
+                const opts = { ifVersion: record.version, journal };
+                for (const write of [
+                    () => adapter.setParent(record.id, parent.id, opts),
+                    () => adapter.setUnlisted(record.id, true, opts),
+                    () => adapter.editAssociations(record.id, [{ op: 'add', association: tag('a') }], opts),
+                    () => adapter.setAssociations(record.id, [tag('a')], opts),
+                    () => adapter.editAccess(record.id, [{ op: 'add', association: anyone }], opts),
+                    () => adapter.setAccess(record.id, [anyone], opts),
+                ]) {
+                    await expectStackErrorCode(write(), 'conflict');
+                }
+                expect(await adapter.getRecord(record.id)).toEqual(before);
+                expect(await adapter.getJournal(record.id)).toEqual(journalBefore);
+            });
+            // Stack's expectSet is what getRecord() answered, so a set read back
+            // must match itself in every shape an element can take.
+            test('a set read back through getRecord matches itself as expectSet', async () => {
+                const record = makeRecord();
+                await adapter.createRecord(record);
+                const associations = [
+                    tag('t'),
+                    { kind: 'attachment', label: 'cover', fileId: 'a'.repeat(64) },
+                    {
+                        kind: 'attachment',
+                        label: 'cover',
+                        fileId: 'b'.repeat(64),
+                        attachmentRecordId: uniqueId('att'),
+                    },
+                    { kind: 'relationship', label: 'cites', target: { kind: 'record', recordId: 'r1' } },
+                    {
+                        kind: 'relationship',
+                        label: 'cites',
+                        target: { kind: 'record', recordId: 'r1', stackUrl: 'https://example.com' },
+                    },
+                    {
+                        kind: 'relationship',
+                        label: 'about',
+                        target: { kind: 'entity', entityId: 'did:key:z6MkConformance' },
+                    },
+                    {
+                        kind: 'relationship',
+                        label: 'link',
+                        target: { kind: 'external', ns: 'isbn', id: '1' },
+                    },
+                ];
+                const permissions = [
+                    { kind: 'anyone', label: 'read' },
+                    {
+                        kind: 'permission',
+                        label: 'read',
+                        grantee: { kind: 'entity', entityId: 'did:key:z6MkConformance' },
+                    },
+                    {
+                        kind: 'permission',
+                        label: 'write',
+                        grantee: { kind: 'group', groupId: uniqueId('grp'), role: 'admin' },
+                    },
+                ];
+                await adapter.setAssociations(record.id, associations);
+                await adapter.setAccess(record.id, permissions);
+                const read = (await adapter.getRecord(record.id));
+                const tagged = await adapter.editAssociations(record.id, [{ op: 'add', association: tag('u') }], { expectSet: read.associations ?? [] });
+                expect(tagged.associations).toHaveLength(associations.length + 1);
+                const shared = await adapter.setAccess(record.id, permissions.slice(1), {
+                    expectSet: read.permissions ?? [],
+                });
+                expect(shared.permissions).toHaveLength(permissions.length - 1);
             });
-            test('each change-set key replaces only its own half of the set', async () => {
+            test('each set verb replaces only its own aspect', async () => {
                 const record = makeRecord();
                 await adapter.createRecord(record);
                 const anyone = { kind: 'anyone', label: 'read' };
-                await adapter.amendAssociations(record.id, [
+                await adapter.editAssociations(record.id, [
                     { op: 'add', association: { kind: 'tag', label: 'draft' } },
                 ]);
-                await adapter.amendAssociations(record.id, [{ op: 'add', association: anyone }]);
-                const retagged = await adapter.mutateRecord(record.id, { associations: [{ kind: 'tag', label: 'reviewed' }] }, { bumpsVersion: false });
+                await adapter.editAccess(record.id, [{ op: 'add', association: anyone }]);
+                const retagged = await adapter.setAssociations(record.id, [
+                    { kind: 'tag', label: 'reviewed' },
+                ]);
                 expect(retagged.associations).toEqual([{ kind: 'tag', label: 'reviewed' }]);
                 expect(retagged.permissions).toEqual([anyone]);
-                const cleared = await adapter.mutateRecord(record.id, { permissions: [] }, { bumpsVersion: false });
+                const cleared = await adapter.setAccess(record.id, []);
                 expect(cleared.associations).toEqual([{ kind: 'tag', label: 'reviewed' }]);
                 expect(cleared.permissions ?? []).toEqual([]);
+                expect(cleared.version).toBe(record.version);
             });
         });
         // -----------------------------------------------------------------
         // Versions — snapshots and restore
         // -----------------------------------------------------------------
         describe('versions', () => {
-            test('saveVersion and getVersion roundtrip', async () => {
+            test("a patch's snapshot reads back through getVersion", async () => {
                 const record = makeRecord();
                 await adapter.createRecord(record);
-                await adapter.saveVersion(record.id, {
-                    version: record.version,
-                    typeId: record.typeId,
-                    content: record.content,
-                    updatedAt: record.updatedAt,
-                });
+                await patchWithSnapshots(record, 1);
                 const version = await adapter.getVersion(record.id, record.version);
                 expect(version?.content).toEqual(record.content);
             });
@@ -419,15 +531,9 @@ export function runRecordAdapterConformance(options) {
                 await adapter.createRecord(parent);
                 const record = makeRecord({ content: { title: 'v1' } });
                 await adapter.createRecord(record);
-                await adapter.saveVersion(record.id, {
-                    version: record.version,
-                    typeId: record.typeId,
-                    content: record.content,
-                    updatedAt: record.updatedAt,
-                });
-                await adapter.mutateRecord(record.id, { contentPatch: { title: 'v2' } });
-                await adapter.mutateRecord(record.id, { parentId: parent.id }, { bumpsVersion: false });
-                await adapter.amendAssociations(record.id, [
+                await adapter.patchContent(record.id, { title: 'v2' }, { snapshot: snapshotOf(record) });
+                await adapter.setParent(record.id, parent.id);
+                await adapter.editAssociations(record.id, [
                     { op: 'add', association: { kind: 'tag', label: 'keep-me' } },
                 ]);
                 const restored = await adapter.restoreVersion(record.id, record.version);
@@ -443,6 +549,134 @@ export function runRecordAdapterConformance(options) {
             });
         });
         // -----------------------------------------------------------------
+        // Importing a record — optional, so each test asks whether the adapter
+        // has importRecord() at all. See docs/spec/portability.md § Writing
+        // history.
+        // -----------------------------------------------------------------
+        describe('importing a record', () => {
+            const AUTHOR = { subjectId: 'did:key:conformance-author' };
+            const EDITOR = { subjectId: 'did:key:conformance-editor', principalId: 'did:key:app' };
+            const at = (day) => new Date(Date.UTC(2024, 0, day));
+            const pinned = { kind: 'tag', label: 'pinned' };
+            /** A record with a past: two versions, four journal entries, every optional field set. */
+            const withPast = (parentId) => {
+                const record = makeRecord({
+                    content: { title: 'v2' },
+                    createdAt: at(1),
+                    updatedAt: at(2),
+                    version: 2,
+                    parentId,
+                    appId: 'org.haverstack.conformance',
+                    createdBy: AUTHOR,
+                    updatedBy: EDITOR,
+                    unlistedAt: at(3),
+                    associations: [pinned],
+                    permissions: [{ kind: 'anyone', label: 'read' }],
+                });
+                const versions = [
+                    {
+                        version: 1,
+                        typeId: record.typeId,
+                        content: { title: 'v1' },
+                        updatedAt: at(1),
+                        createdBy: AUTHOR,
+                        updatedBy: AUTHOR,
+                    },
+                ];
+                const journal = [
+                    {
+                        seq: 1,
+                        at: at(1),
+                        kind: 'created',
+                        ops: ['create'],
+                        version: 1,
+                        typeId: record.typeId,
+                        actor: AUTHOR,
+                    },
+                    {
+                        seq: 2,
+                        at: at(2),
+                        kind: 'changed',
+                        ops: ['patch'],
+                        version: 2,
+                        typeId: record.typeId,
+                        actor: EDITOR,
+                    },
+                    {
+                        seq: 3,
+                        at: at(3),
+                        kind: 'changed',
+                        ops: ['reparent'],
+                        version: 2,
+                        typeId: record.typeId,
+                        parentId,
+                        previousParentId: null,
+                        actor: EDITOR,
+                    },
+                    {
+                        seq: 4,
+                        at: at(3),
+                        kind: 'changed',
+                        ops: ['associate', 'unlist'],
+                        version: 2,
+                        typeId: record.typeId,
+                        parentId,
+                        associations: [{ op: 'add', association: pinned }],
+                    },
+                ];
+                return { record, versions, journal };
+            };
+            test('writes the record, its versions and its journal exactly as recorded', async () => {
+                if (!adapter.importRecord)
+                    return;
+                const parent = makeRecord();
+                await adapter.createRecord(parent);
+                const { record, versions, journal } = withPast(parent.id);
+                expect(await adapter.importRecord(record, { versions, journal })).toEqual(record);
+                expect(await adapter.getRecord(record.id)).toEqual(record);
+                expect(await adapter.getVersions(record.id)).toEqual(versions);
+                expect(await adapter.getJournal(record.id)).toEqual(journal);
+            });
+            test('appends no journal entry of its own', async () => {
+                if (!adapter.importRecord)
+                    return;
+                const record = makeRecord();
+                await adapter.importRecord(record, { versions: [], journal: [] });
+                expect(await adapter.getJournal(record.id)).toEqual([]);
+            });
+            test('refuses an id that already exists', async () => {
+                if (!adapter.importRecord)
+                    return;
+                const record = makeRecord();
+                await adapter.createRecord(record);
+                await expectStackErrorCode(adapter.importRecord(record, { versions: [], journal: [] }), 'conflict');
+            });
+            test('an imported record answers queries as a created one does', async () => {
+                if (!adapter.importRecord)
+                    return;
+                const record = makeRecord({ content: { title: 'imported' }, associations: [pinned] });
+                await adapter.importRecord(record, { versions: [], journal: [] });
+                const byTag = await adapter.queryRecords(resolveQuery({ filter: { tags: ['pinned'] } }));
+                expect(byTag.records.map((r) => r.id)).toEqual([record.id]);
+                if (capabilities.filter.content !== 'none') {
+                    const byContent = await adapter.queryRecords(resolveQuery({ filter: { content: { title: 'imported' } } }));
+                    expect(byContent.records.map((r) => r.id)).toEqual([record.id]);
+                }
+            });
+            test('a write after an import continues its history', async () => {
+                if (!adapter.importRecord)
+                    return;
+                const parent = makeRecord();
+                await adapter.createRecord(parent);
+                const { record, versions, journal } = withPast(parent.id);
+                await adapter.importRecord(record, { versions, journal });
+                const patched = await adapter.patchContent(record.id, { title: 'v3' }, { snapshot: snapshotOf(record), journal: { ops: ['patch'], kind: 'changed' } });
+                expect(patched.version).toBe(3);
+                expect((await adapter.getVersions(record.id)).map((v) => v.version)).toEqual([2, 1]);
+                expect((await adapter.getJournal(record.id)).map((e) => e.seq)).toEqual([1, 2, 3, 4, 5]);
+            });
+        });
+        // -----------------------------------------------------------------
         // Change journal — the second durable tier
         // -----------------------------------------------------------------
         describe('change journal', () => {
@@ -465,7 +699,7 @@ export function runRecordAdapterConformance(options) {
                 await adapter.createRecord(record, {
                     journal: { ops: ['create'], kind: 'created' },
                 });
-                await adapter.mutateRecord(record.id, { contentPatch: { title: 'v2' } }, { bumpsVersion: true, journal: { ops: ['patch'], kind: 'changed' } });
+                await adapter.patchContent(record.id, { title: 'v2' }, { journal: { ops: ['patch'], kind: 'changed' } });
                 const log = await adapter.getJournal(record.id);
                 expect(log).toHaveLength(2);
                 // version, typeId and parentId are the adapter's to stamp: Stack
@@ -480,8 +714,8 @@ export function runRecordAdapterConformance(options) {
                 const second = makeRecord();
                 await adapter.createRecord(first, { journal: { ops: ['create'], kind: 'created' } });
                 await adapter.createRecord(second, { journal: { ops: ['create'], kind: 'created' } });
-                await adapter.amendAssociations(first.id, [{ op: 'add', association: { kind: 'tag', label: 'a' } }], { journal: { ops: ['associate'], kind: 'changed' } });
-                await adapter.amendAssociations(first.id, [{ op: 'add', association: { kind: 'tag', label: 'b' } }], { journal: { ops: ['associate'], kind: 'changed' } });
+                await adapter.editAssociations(first.id, [{ op: 'add', association: { kind: 'tag', label: 'a' } }], { journal: { ops: ['associate'], kind: 'changed' } });
+                await adapter.editAssociations(first.id, [{ op: 'add', association: { kind: 'tag', label: 'b' } }], { journal: { ops: ['associate'], kind: 'changed' } });
                 expect((await adapter.getJournal(first.id)).map((e) => e.seq)).toEqual([1, 2, 3]);
                 // Per record, so a busy neighbour never advances this one's log.
                 expect((await adapter.getJournal(second.id)).map((e) => e.seq)).toEqual([1]);
@@ -489,14 +723,14 @@ export function runRecordAdapterConformance(options) {
             test('an association change journals a version that stands still', async () => {
                 const record = makeRecord();
                 await adapter.createRecord(record);
-                await adapter.amendAssociations(record.id, [{ op: 'add', association: { kind: 'tag', label: 'starred' } }], {
+                await adapter.editAssociations(record.id, [{ op: 'add', association: { kind: 'tag', label: 'starred' } }], {
                     journal: {
                         ops: ['associate'],
                         kind: 'changed',
                         associations: [{ op: 'add', association: { kind: 'tag', label: 'starred' } }],
                     },
                 });
-                await adapter.amendAssociations(record.id, [{ op: 'remove', association: { kind: 'tag', label: 'starred' } }], {
+                await adapter.editAssociations(record.id, [{ op: 'remove', association: { kind: 'tag', label: 'starred' } }], {
                     journal: {
                         ops: ['dissociate'],
                         kind: 'changed',
@@ -530,7 +764,7 @@ export function runRecordAdapterConformance(options) {
                     fileId: 'a'.repeat(64),
                     attachmentRecordId: uniqueId('new'),
                 };
-                await adapter.amendAssociations(record.id, [{ op: 'add', association: association }], {
+                await adapter.editAssociations(record.id, [{ op: 'add', association: association }], {
                     journal: {
                         ops: ['associate'],
                         kind: 'changed',
@@ -552,8 +786,8 @@ export function runRecordAdapterConformance(options) {
                     fileId: 'b'.repeat(64),
                     attachmentRecordId: uniqueId('upload'),
                 };
-                await adapter.amendAssociations(record.id, [{ op: 'add', association: previous }]);
-                await adapter.amendAssociations(record.id, [
+                await adapter.editAssociations(record.id, [{ op: 'add', association: previous }]);
+                await adapter.editAssociations(record.id, [
                     {
                         op: 'remove',
                         association: { kind: 'attachment', label: 'cover', fileId: 'b'.repeat(64) },
@@ -568,25 +802,6 @@ export function runRecordAdapterConformance(options) {
                 const [entry] = await adapter.getJournal(record.id);
                 expect(entry.associations).toEqual([{ op: 'remove', association: previous }]);
             });
-            test('an association list is keyed by identity, last wins', async () => {
-                // Association identity is the association table's primary key, so a
-                // list naming one identity twice is a state no store can hold.
-                // An adapter that kept both would let a record reach one a SQL
-                // adapter cannot represent.
-                const record = makeRecord();
-                await adapter.createRecord(record);
-                const fileId = 'c'.repeat(64);
-                const winner = uniqueId('second');
-                const updated = await adapter.mutateRecord(record.id, {
-                    associations: [
-                        { kind: 'attachment', label: 'cover', fileId, attachmentRecordId: uniqueId('first') },
-                        { kind: 'attachment', label: 'cover', fileId, attachmentRecordId: winner },
-                    ],
-                }, { bumpsVersion: false });
-                expect(updated.associations).toEqual([
-                    { kind: 'attachment', label: 'cover', fileId, attachmentRecordId: winner },
-                ]);
-            });
             test('previousParentId tells "did not move" apart from "moved off the root"', async () => {
                 // The one field on any entry where null is a value rather than an
                 // input spelling. Collapsing both to absent loses which happened —
@@ -596,8 +811,7 @@ export function runRecordAdapterConformance(options) {
                 await adapter.createRecord(parent);
                 const record = makeRecord();
                 await adapter.createRecord(record, { journal: { ops: ['create'], kind: 'created' } });
-                await adapter.mutateRecord(record.id, { parentId: parent.id }, {
-                    bumpsVersion: false,
+                await adapter.setParent(record.id, parent.id, {
                     journal: { ops: ['reparent'], kind: 'changed', previousParentId: null },
                 });
                 const log = await adapter.getJournal(record.id);
@@ -609,7 +823,7 @@ export function runRecordAdapterConformance(options) {
                 const record = makeRecord();
                 await adapter.createRecord(record, { journal: { ops: ['create'], kind: 'created' } });
                 for (const label of ['a', 'b', 'c']) {
-                    await adapter.amendAssociations(record.id, [{ op: 'add', association: { kind: 'tag', label } }], { journal: { ops: ['associate'], kind: 'changed' } });
+                    await adapter.editAssociations(record.id, [{ op: 'add', association: { kind: 'tag', label } }], { journal: { ops: ['associate'], kind: 'changed' } });
                 }
                 expect(await adapter.getJournal(record.id)).toHaveLength(4);
                 expect((await adapter.getJournal(record.id, { afterSeq: 2 })).map((e) => e.seq)).toEqual([
@@ -623,7 +837,7 @@ export function runRecordAdapterConformance(options) {
             });
             test('a failed mutation leaves no entry behind', async () => {
                 const missing = uniqueId('missing');
-                await expectStackErrorCode(adapter.mutateRecord(missing, { contentPatch: { title: 'x' } }, { bumpsVersion: true, journal: { ops: ['patch'], kind: 'changed' } }), 'not_found');
+                await expectStackErrorCode(adapter.patchContent(missing, { title: 'x' }, { journal: { ops: ['patch'], kind: 'changed' } }), 'not_found');
                 // The record was never created, so its log is refused rather than
                 // read — what matters is that the entry did not land somewhere.
                 await expectStackErrorCode(adapter.getJournal(missing), 'not_found');
@@ -676,7 +890,7 @@ export function runRecordAdapterConformance(options) {
                 const seen = new Set();
                 let cursor;
                 do {
-                    const page = await adapter.queryRecords({ limit: 2, cursor: cursor ?? undefined });
+                    const page = await adapter.queryRecords(resolveQuery({ limit: 2, cursor: cursor ?? undefined }));
                     expect(page.records.length).toBeLessThanOrEqual(2);
                     for (const r of page.records)
                         seen.add(r.id);
@@ -685,22 +899,275 @@ export function runRecordAdapterConformance(options) {
                 for (const id of ids)
                     expect(seen.has(id)).toBe(true);
             });
+            // A cursor names the last record its page held, so the next page
+            // starts after that record wherever it now falls in the order.
+            test('a page resumes after its cursor whatever was inserted ahead of it', async () => {
+                for (let i = 0; i < 5; i++) {
+                    await adapter.createRecord(makeRecord({ createdAt: new Date(1_000 + i) }));
+                }
+                const sort = { field: 'createdAt', direction: 'asc' };
+                const first = await adapter.queryRecords(resolveQuery({ limit: 2, sort }));
+                await adapter.createRecord(makeRecord({ createdAt: new Date(1) }));
+                const second = await adapter.queryRecords(resolveQuery({ limit: 2, cursor: first.cursor, sort }));
+                const all = (await adapter.queryRecords(resolveQuery({ limit: 100, sort }))).records.map((r) => r.id);
+                const after = all.indexOf(first.records[1].id);
+                expect(second.records.map((r) => r.id)).toEqual(all.slice(after + 1, after + 3));
+            });
             test('a malformed cursor is refused rather than misread', async () => {
-                await expectStackErrorCode(adapter.queryRecords({ cursor: 'not-a-real-cursor' }), 'bad_request');
+                await expectStackErrorCode(adapter.queryRecords(resolveQuery({ cursor: 'not-a-real-cursor' })), 'bad_request');
             });
             test('a cursor minted under one sort field is refused when replayed under a different one', async () => {
                 await adapter.createRecord(makeRecord());
                 await adapter.createRecord(makeRecord());
-                const minted = await adapter.queryRecords({
+                const minted = await adapter.queryRecords(resolveQuery({
                     limit: 1,
                     sort: { field: 'createdAt', direction: 'asc' },
-                });
+                }));
                 expect(minted.cursor).not.toBeNull();
-                await expectStackErrorCode(adapter.queryRecords({
+                await expectStackErrorCode(adapter.queryRecords(resolveQuery({
                     limit: 1,
                     cursor: minted.cursor,
                     sort: { field: 'updatedAt', direction: 'asc' },
-                }), 'bad_request');
+                })), 'bad_request');
+            });
+        });
+        // -----------------------------------------------------------------
+        // Querying within a reach — optional, so each test asks whether the
+        // adapter has queryReadable() at all. The reference reading is core's
+        // inReach(); see docs/spec/access-control.md § Reach.
+        // -----------------------------------------------------------------
+        describe('querying within a reach', () => {
+            const NOTE = 'org.haverstack.conformance/note';
+            const OTHER = 'org.haverstack.conformance/other';
+            const OTHER_TYPE_ID = `${OTHER}@1`;
+            const ALICE = 'did:key:conformance-alice';
+            const BOB = 'did:key:conformance-bob';
+            const anyone = { kind: 'anyone', label: 'read' };
+            const toAlice = {
+                kind: 'permission',
+                label: 'read',
+                grantee: { kind: 'entity', entityId: ALICE },
+            };
+            const toMembers = {
+                kind: 'permission',
+                label: 'read',
+                grantee: { kind: 'group', groupId: 'conformance-group', role: 'member' },
+            };
+            const toAdmins = {
+                kind: 'permission',
+                label: 'read',
+                grantee: { kind: 'group', groupId: 'conformance-group', role: 'admin' },
+            };
+            /** One record per route into a reach, and one beside each that misses it. */
+            const populate = async () => {
+                const records = [
+                    makeRecord(),
+                    makeRecord({ typeId: OTHER_TYPE_ID }),
+                    makeRecord({ createdBy: { subjectId: ALICE } }),
+                    makeRecord({ typeId: OTHER_TYPE_ID, createdBy: { subjectId: ALICE } }),
+                    makeRecord({ createdBy: { subjectId: BOB, principalId: ALICE } }),
+                    makeRecord({ permissions: [anyone] }),
+                    makeRecord({ typeId: OTHER_TYPE_ID, permissions: [anyone] }),
+                    // A family's other versions are in reach with it; one sharing its
+                    // prefix is not.
+                    makeRecord({ typeId: `${NOTE}@2` }),
+                    makeRecord({ typeId: `${NOTE}@2`, createdBy: { subjectId: ALICE } }),
+                    makeRecord({ typeId: `${NOTE}s@1`, createdBy: { subjectId: ALICE } }),
+                    makeRecord({ permissions: [toAlice] }),
+                    makeRecord({ permissions: [{ ...toAlice, label: 'write' }] }),
+                    makeRecord({ permissions: [toMembers] }),
+                    makeRecord({ permissions: [toAdmins] }),
+                    makeRecord({ permissions: [toAlice, toMembers] }),
+                    makeRecord({ permissions: [toAlice, { ...toAlice, label: 'write' }] }),
+                    makeRecord({ permissions: [anyone, { ...toAlice, label: 'write' }] }),
+                    makeRecord({ permissions: [toMembers, toAdmins] }),
+                ];
+                for (const record of records)
+                    await adapter.createRecord(record);
+                return records;
+            };
+            // Far past any statement's parameter cap — 100 on Durable Object SQLite.
+            const manyFamilies = Array.from({ length: 150 }, (_, i) => `org.haverstack.conformance/t${i}`);
+            const manyGroups = Array.from({ length: 60 }, (_, i) => `conformance-group-${i}`);
+            const reaches = [
+                ['nothing constrained', {}],
+                ['every Record of a family', { within: { baseIds: [OTHER], permissions: [] } }],
+                [
+                    'the Records one subject authored in a family',
+                    {
+                        within: {
+                            baseIds: [],
+                            authored: { subjectId: ALICE, baseIds: [NOTE] },
+                            permissions: [],
+                        },
+                    },
+                ],
+                ['Records carrying `anyone`', { within: { baseIds: [], permissions: [[anyone]] } }],
+                [
+                    'Records carrying a read naming an entity',
+                    { within: { baseIds: [], permissions: [[toAlice]] } },
+                ],
+                [
+                    'Records carrying a read naming a group at one role',
+                    { within: { baseIds: [], permissions: [[toAdmins]] } },
+                ],
+                [
+                    'every arm at once',
+                    {
+                        within: {
+                            baseIds: [OTHER],
+                            authored: { subjectId: ALICE, baseIds: [NOTE] },
+                            permissions: [[anyone], [toMembers]],
+                        },
+                    },
+                ],
+                ['a fence alone', { fence: [OTHER] }],
+                [
+                    'arms inside a fence',
+                    {
+                        fence: [NOTE],
+                        within: {
+                            baseIds: [OTHER],
+                            authored: { subjectId: ALICE, baseIds: [NOTE, OTHER] },
+                            permissions: [[anyone]],
+                        },
+                    },
+                ],
+                ['an empty fence', { fence: [], within: { baseIds: [NOTE], permissions: [[anyone]] } }],
+                ['no arm at all', { within: { baseIds: [], permissions: [] } }],
+                [
+                    'Records carrying every element of a set',
+                    { within: { baseIds: [], permissions: [[toAlice, { ...toAlice, label: 'write' }]] } },
+                ],
+                [
+                    'Records carrying one whole set of several',
+                    {
+                        within: {
+                            baseIds: [],
+                            permissions: [
+                                [{ ...toAlice, label: 'write' }, anyone],
+                                [toMembers, toAdmins],
+                            ],
+                        },
+                    },
+                ],
+                ['an empty set, which no Record carries', { within: { baseIds: [], permissions: [[]] } }],
+                [
+                    'a reach of any size',
+                    {
+                        fence: [NOTE, ...manyFamilies],
+                        within: {
+                            baseIds: manyFamilies,
+                            authored: { subjectId: ALICE, baseIds: [NOTE, ...manyFamilies] },
+                            permissions: [
+                                ...manyGroups.flatMap((groupId) => [
+                                    [{ ...toMembers, grantee: { ...toMembers.grantee, groupId } }],
+                                    [
+                                        {
+                                            ...toAdmins,
+                                            label: 'write',
+                                            grantee: { ...toAdmins.grantee, groupId },
+                                        },
+                                        anyone,
+                                    ],
+                                ]),
+                                [toAlice],
+                            ],
+                        },
+                    },
+                ],
+            ];
+            test.each(reaches)('returns exactly the Records in reach: %s', async (_name, reach) => {
+                if (!adapter.queryReadable)
+                    return;
+                const records = await populate();
+                const result = await adapter.queryReadable(resolveQuery({ limit: 100 }), reach);
+                const expected = records.filter((r) => inReach(r, reach)).map((r) => r.id);
+                expect(result.records.map((r) => r.id).sort()).toEqual(expected.sort());
+                expect(result.cursor).toBeNull();
+            });
+            test("a reach narrows the query's own filter rather than widening it", async () => {
+                if (!adapter.queryReadable)
+                    return;
+                const pinned = { kind: 'tag', label: 'pinned' };
+                const tagged = makeRecord({ permissions: [anyone], associations: [pinned] });
+                await adapter.createRecord(tagged);
+                await adapter.createRecord(makeRecord({ permissions: [anyone] }));
+                await adapter.createRecord(makeRecord({ associations: [pinned] }));
+                const result = await adapter.queryReadable(resolveQuery({ filter: { tags: ['pinned'] } }), {
+                    within: { baseIds: [], permissions: [[anyone]] },
+                });
+                expect(result.records.map((r) => r.id)).toEqual([tagged.id]);
+            });
+            // Paging is decided among the Records in reach alone: every page is
+            // full, and no cursor comes back once they are exhausted, however
+            // many Records outside the reach remain.
+            const pagesWithin = async (sort) => {
+                if (!adapter.queryReadable)
+                    return;
+                const reach = { within: { baseIds: [], permissions: [[anyone]] } };
+                const inside = [];
+                for (let i = 0; i < 9; i++) {
+                    const visible = i % 3 === 1;
+                    const record = makeRecord({
+                        content: { title: `t${i}`, priority: i },
+                        ...(visible && { permissions: [anyone] }),
+                    });
+                    await adapter.createRecord(record);
+                    if (visible)
+                        inside.push(record.id);
+                }
+                const seen = [];
+                let cursor;
+                do {
+                    const page = await adapter.queryReadable(resolveQuery({ limit: 1, cursor, sort }), reach);
+                    expect(page.records).toHaveLength(1);
+                    seen.push(page.records[0].id);
+                    cursor = page.cursor ?? undefined;
+                } while (cursor);
+                expect(seen.sort()).toEqual(inside.sort());
+            };
+            test('pages through the Records in reach alone, by a native field', () => pagesWithin({ field: 'createdAt', direction: 'asc' }));
+            if (capabilities.sort.contentField) {
+                test('pages through the Records in reach alone, by a content field', async () => {
+                    await adapter.saveType(conformanceType());
+                    await pagesWithin({ contentField: 'priority', direction: 'desc' });
+                });
+            }
+        });
+        // -----------------------------------------------------------------
+        // Type families
+        // -----------------------------------------------------------------
+        describe('filter.baseId', () => {
+            const NOTE = 'org.haverstack.conformance/note';
+            const ids = async (filter) => (await adapter.queryRecords(resolveQuery({ filter }))).records.map((r) => r.id).sort();
+            /** One record per TypeId, keyed by it. */
+            const seed = async (typeIds) => {
+                const seeded = {};
+                for (const typeId of typeIds) {
+                    const record = makeRecord({ typeId });
+                    await adapter.createRecord(record);
+                    seeded[typeId] = record.id;
+                }
+                return seeded;
+            };
+            test('matches every version of the family and nothing that only shares its prefix', async () => {
+                const r = await seed([`${NOTE}@1`, `${NOTE}@2`, `${NOTE}s@1`, `${NOTE}-x@1`, `${NOTE}@10`]);
+                expect(await ids({ baseId: NOTE })).toEqual([r[`${NOTE}@1`], r[`${NOTE}@2`], r[`${NOTE}@10`]].sort());
+            });
+            test('matches any of several families', async () => {
+                const r = await seed([`${NOTE}@1`, `${NOTE}s@1`, 'org.haverstack.conformance/other@1']);
+                expect(await ids({ baseId: [NOTE, `${NOTE}s`] })).toEqual([r[`${NOTE}@1`], r[`${NOTE}s@1`]].sort());
+            });
+            test('intersects with filter.typeId', async () => {
+                const r = await seed([`${NOTE}@1`, `${NOTE}@2`, `${NOTE}s@1`]);
+                expect(await ids({ baseId: NOTE, typeId: [`${NOTE}@2`, `${NOTE}s@1`] })).toEqual([
+                    r[`${NOTE}@2`],
+                ]);
+            });
+            test('an unknown family matches nothing', async () => {
+                await seed([`${NOTE}@1`]);
+                expect(await ids({ baseId: 'org.haverstack.conformance/none' })).toEqual([]);
             });
         });
         // -----------------------------------------------------------------
@@ -713,7 +1180,7 @@ export function runRecordAdapterConformance(options) {
                     const decoy = makeRecord({ content: { title: 'b', priority: 2 } });
                     await adapter.createRecord(match);
                     await adapter.createRecord(decoy);
-                    const result = await adapter.queryRecords({ filter: { content: { priority: 1 } } });
+                    const result = await adapter.queryRecords(resolveQuery({ filter: { content: { priority: 1 } } }));
                     // The positive assertion first: `not.toContain` and `every` are
                     // both vacuously true on an empty result, so without this an
                     // adapter that declares filter.content and returns nothing at
@@ -729,7 +1196,7 @@ export function runRecordAdapterConformance(options) {
                     await adapter.createRecord(absent);
                     await adapter.createRecord(explicitNull);
                     await adapter.createRecord(present);
-                    const result = await adapter.queryRecords({ filter: { content: { priority: null } } });
+                    const result = await adapter.queryRecords(resolveQuery({ filter: { content: { priority: null } } }));
                     const ids = result.records.map((r) => r.id).sort();
                     expect(ids).toEqual([absent.id, explicitNull.id].sort());
                     expect(ids).not.toContain(present.id);
@@ -739,7 +1206,7 @@ export function runRecordAdapterConformance(options) {
                     const nested = makeRecord({ content: { title: 'y', priority: { high: true } } });
                     await adapter.createRecord(scalarMatch);
                     await adapter.createRecord(nested);
-                    const result = await adapter.queryRecords({ filter: { content: { priority: 1 } } });
+                    const result = await adapter.queryRecords(resolveQuery({ filter: { content: { priority: 1 } } }));
                     expect(result.records.map((r) => r.id)).toContain(scalarMatch.id);
                     expect(result.records.map((r) => r.id)).not.toContain(nested.id);
                 });
@@ -751,10 +1218,43 @@ export function runRecordAdapterConformance(options) {
                         await adapter.createRecord(present);
                         await adapter.createRecord(absent);
                         await adapter.createRecord(nullValue);
-                        const result = await adapter.queryRecords({ filter: { contentPresent: ['priority'] } });
+                        const result = await adapter.queryRecords(resolveQuery({ filter: { contentPresent: ['priority'] } }));
                         expect(result.records.map((r) => r.id)).toEqual([present.id]);
                     });
                 }
+                // A value matches as `===` compares it: its JSON type as well as
+                // its value. See docs/spec/data-model.md § Filter.
+                test('a content filter value matches its own JSON type only', async () => {
+                    const bool = makeRecord({ content: { title: 'b', flag: true } });
+                    const num = makeRecord({ content: { title: 'n', flag: 1 } });
+                    const text = makeRecord({ content: { title: 't', flag: '1' } });
+                    for (const record of [bool, num, text])
+                        await adapter.createRecord(record);
+                    for (const [value, record] of [
+                        [true, bool],
+                        [1, num],
+                        ['1', text],
+                    ]) {
+                        const result = await adapter.queryRecords(resolveQuery({ filter: { content: { flag: value } } }));
+                        expect(result.records.map((r) => r.id)).toEqual([record.id]);
+                    }
+                });
+                if (capabilities.filter.contentPresent && capabilities.filter.content === 'path') {
+                    // Both are element-wise, so a path reaching a null and a value
+                    // satisfies each. See docs/spec/data-model.md § Filter.
+                    test('a multi-valued path satisfies both contentPresent and a null filter', async () => {
+                        const mixed = makeRecord({
+                            content: { title: 'x', tags: [null, 'a'], emails: [{ value: null }, { value: 1 }] },
+                        });
+                        await adapter.createRecord(mixed);
+                        for (const path of ['tags', 'emails.value']) {
+                            const present = await adapter.queryRecords(resolveQuery({ filter: { contentPresent: [path] } }));
+                            expect(present.records.map((r) => r.id)).toEqual([mixed.id]);
+                            const nulls = await adapter.queryRecords(resolveQuery({ filter: { content: { [path]: null } } }));
+                            expect(nulls.records.map((r) => r.id)).toEqual([mixed.id]);
+                        }
+                    });
+                }
                 if (capabilities.filter.content === 'path') {
                     test('an array is spread element-wise when filtering a nested path', async () => {
                         const match = makeRecord({
@@ -765,9 +1265,9 @@ export function runRecordAdapterConformance(options) {
                         });
                         await adapter.createRecord(match);
                         await adapter.createRecord(noMatch);
-                        const result = await adapter.queryRecords({
+                        const result = await adapter.queryRecords(resolveQuery({
                             filter: { content: { 'emails.value': 'a@b.c' } },
-                        });
+                        }));
                         expect(result.records.map((r) => r.id)).toEqual([match.id]);
                     });
                     test('a nested path filter reaches a property inside a plain (non-array) object', async () => {
@@ -775,16 +1275,16 @@ export function runRecordAdapterConformance(options) {
                         const noMatch = makeRecord({ content: { title: 'y', address: { city: 'Lyon' } } });
                         await adapter.createRecord(match);
                         await adapter.createRecord(noMatch);
-                        const result = await adapter.queryRecords({
+                        const result = await adapter.queryRecords(resolveQuery({
                             filter: { content: { 'address.city': 'Berlin' } },
-                        });
+                        }));
                         expect(result.records.map((r) => r.id)).toEqual([match.id]);
                     });
                     test('a filter path descending through a scalar matches nothing, rather than throwing', async () => {
                         await adapter.createRecord(makeRecord({ content: { title: 'x', priority: 1 } }));
-                        const result = await adapter.queryRecords({
+                        const result = await adapter.queryRecords(resolveQuery({
                             filter: { content: { 'priority.nested': 'anything' } },
-                        });
+                        }));
                         expect(result.records).toEqual([]);
                     });
                 }
@@ -793,7 +1293,7 @@ export function runRecordAdapterConformance(options) {
         // -----------------------------------------------------------------
         // Content by type — capability-gated on filter.contentByType
         // -----------------------------------------------------------------
-        if (capabilities.filter.contentByType >= 2) {
+        if (capabilities.filter.contentByType) {
             describe('content by type', () => {
                 const OTHER = 'org.haverstack.conformance/other@1';
                 const THIRD = 'org.haverstack.conformance/third@1';
@@ -807,14 +1307,14 @@ export function runRecordAdapterConformance(options) {
                     ];
                     for (const record of [note, other, ...decoys])
                         await adapter.createRecord(record);
-                    const result = await adapter.queryRecords({
+                    const result = await adapter.queryRecords(resolveQuery({
                         filter: {
                             contentByType: {
                                 [CONFORMANCE_TYPE_ID]: { content: { title: 'a' } },
                                 [OTHER]: { content: { heading: 'a' } },
                             },
                         },
-                    });
+                    }));
                     expect(result.records.map((r) => r.id).sort()).toEqual([note.id, other.id].sort());
                 });
                 test('an arm naming nothing matches every record of its type', async () => {
@@ -822,11 +1322,11 @@ export function runRecordAdapterConformance(options) {
                     const decoy = makeRecord({ typeId: THIRD });
                     for (const record of [...notes, decoy])
                         await adapter.createRecord(record);
-                    const result = await adapter.queryRecords({
+                    const result = await adapter.queryRecords(resolveQuery({
                         filter: {
                             contentByType: { [CONFORMANCE_TYPE_ID]: {}, [OTHER]: { content: { a: 1 } } },
                         },
-                    });
+                    }));
                     expect(result.records.map((r) => r.id).sort()).toEqual(notes.map((r) => r.id).sort());
                 });
                 test('intersects with every other key of the filter', async () => {
@@ -835,12 +1335,12 @@ export function runRecordAdapterConformance(options) {
                     const child = makeRecord({ content: { title: 'a' }, parentId: parent.id });
                     await adapter.createRecord(kept);
                     await adapter.createRecord(child);
-                    const result = await adapter.queryRecords({
+                    const result = await adapter.queryRecords(resolveQuery({
                         filter: {
                             parentId: parent.id,
                             contentByType: { [CONFORMANCE_TYPE_ID]: { content: { title: 'a' } }, [OTHER]: {} },
                         },
-                    });
+                    }));
                     expect(result.records.map((r) => r.id)).toEqual([child.id]);
                 });
                 if (capabilities.filter.contentPresent) {
@@ -850,14 +1350,14 @@ export function runRecordAdapterConformance(options) {
                         const other = makeRecord({ typeId: OTHER, content: { priority: 1 } });
                         for (const record of [present, absent, other])
                             await adapter.createRecord(record);
-                        const result = await adapter.queryRecords({
+                        const result = await adapter.queryRecords(resolveQuery({
                             filter: {
                                 contentByType: {
                                     [CONFORMANCE_TYPE_ID]: { contentPresent: ['priority'] },
                                     [OTHER]: { contentPresent: ['missing'] },
                                 },
                             },
-                        });
+                        }));
                         expect(result.records.map((r) => r.id)).toEqual([present.id]);
                     });
                 }
@@ -866,7 +1366,7 @@ export function runRecordAdapterConformance(options) {
         // -----------------------------------------------------------------
         // Sort by content field per type — gated on sort.contentFieldByType
         // -----------------------------------------------------------------
-        if (capabilities.sort.contentFieldByType >= 3) {
+        if (capabilities.sort.contentFieldByType) {
             describe('sort by content field per type', () => {
                 const OTHER = 'org.haverstack.conformance/other@1';
                 const THIRD = 'org.haverstack.conformance/third@1';
@@ -899,9 +1399,9 @@ export function runRecordAdapterConformance(options) {
                 const titles = (records) => records.map((r) => r.content.title);
                 test.each(['asc', 'desc'])('orders each type by its own field or constant, %s, holding no value last', async (direction) => {
                     await seed();
-                    const result = await adapter.queryRecords({
+                    const result = await adapter.queryRecords(resolveQuery({
                         sort: { contentFieldByType: BY_TYPE, direction },
-                    });
+                    }));
                     const ordered = ['a', 'b', 'c', 'd', 'e'];
                     expect(titles(result.records)).toEqual([
                         ...(direction === 'asc' ? ordered : ordered.reverse()),
@@ -914,11 +1414,11 @@ export function runRecordAdapterConformance(options) {
                     const seen = [];
                     let cursor;
                     do {
-                        const page = await adapter.queryRecords({
+                        const page = await adapter.queryRecords(resolveQuery({
                             limit: 1,
                             cursor: cursor ?? undefined,
                             sort: { contentFieldByType: BY_TYPE, direction: 'asc' },
-                        });
+                        }));
                         seen.push(...titles(page.records));
                         cursor = page.cursor;
                     } while (cursor);
@@ -927,15 +1427,15 @@ export function runRecordAdapterConformance(options) {
                 if (capabilities.sort.contentField) {
                     test('a cursor minted under one field is refused under a map', async () => {
                         await seed();
-                        const minted = await adapter.queryRecords({
+                        const minted = await adapter.queryRecords(resolveQuery({
                             limit: 1,
                             sort: { contentField: 'priority', direction: 'asc' },
-                        });
-                        await expectStackErrorCode(adapter.queryRecords({
+                        }));
+                        await expectStackErrorCode(adapter.queryRecords(resolveQuery({
                             limit: 1,
                             cursor: minted.cursor,
                             sort: { contentFieldByType: BY_TYPE, direction: 'asc' },
-                        }), 'bad_request');
+                        })), 'bad_request');
                     });
                 }
             });
@@ -948,7 +1448,7 @@ export function runRecordAdapterConformance(options) {
                 const a = await adapter.createRecord(makeRecord());
                 await new Promise((r) => setTimeout(r, 5));
                 const b = await adapter.createRecord(makeRecord());
-                const result = await adapter.queryRecords({ sort: { field: 'createdAt', direction } });
+                const result = await adapter.queryRecords(resolveQuery({ sort: { field: 'createdAt', direction } }));
                 const ids = result.records.map((r) => r.id);
                 expect(ids).toEqual(direction === 'asc' ? [a.id, b.id] : [b.id, a.id]);
             });
@@ -959,9 +1459,9 @@ export function runRecordAdapterConformance(options) {
                     await adapter.saveType(conformanceType());
                     await adapter.createRecord(makeRecord({ content: { title: 'x', priority: 1 } }));
                     await adapter.createRecord(makeRecord({ content: { title: 'y', priority: 2 } }));
-                    const result = await adapter.queryRecords({
+                    const result = await adapter.queryRecords(resolveQuery({
                         sort: { contentField: 'priority', direction },
-                    });
+                    }));
                     const priorities = result.records.map((r) => r.content.priority);
                     expect(priorities).toEqual(direction === 'asc' ? [1, 2] : [2, 1]);
                 });
@@ -973,9 +1473,9 @@ export function runRecordAdapterConformance(options) {
                     await adapter.createRecord(makeRecord({ content: { title: 'x', priority: 3 } }));
                     await adapter.createRecord(makeRecord({ content: { title: 'y', priority: 1 } }));
                     await adapter.createRecord(makeRecord({ content: { title: 'z', priority: 2 } }));
-                    const result = await adapter.queryRecords({
+                    const result = await adapter.queryRecords(resolveQuery({
                         sort: { contentField: 'priority', direction: 'asc' },
-                    });
+                    }));
                     expect(result.records.map((r) => r.content.priority)).toEqual([
                         1, 2, 3,
                     ]);
@@ -990,9 +1490,9 @@ export function runRecordAdapterConformance(options) {
                     for (const status of ['want', 'finished', 'reading']) {
                         await adapter.createRecord(makeRecord({ content: { title: status, status } }));
                     }
-                    const result = await adapter.queryRecords({
+                    const result = await adapter.queryRecords(resolveQuery({
                         sort: { contentField: 'status', direction: 'asc' },
-                    });
+                    }));
                     expect(result.records.map((r) => r.content.status)).toEqual([
                         'finished',
                         'reading',
@@ -1011,7 +1511,7 @@ export function runRecordAdapterConformance(options) {
                     const noMatch = makeRecord({ content: { title: 'something unrelated' } });
                     await adapter.createRecord(match);
                     await adapter.createRecord(noMatch);
-                    const result = await adapter.queryRecords({ filter: { search: 'brown' } });
+                    const result = await adapter.queryRecords(resolveQuery({ filter: { search: 'brown' } }));
                     expect(result.records.map((r) => r.id)).toContain(match.id);
                     expect(result.records.map((r) => r.id)).not.toContain(noMatch.id);
                 });
@@ -1022,17 +1522,17 @@ export function runRecordAdapterConformance(options) {
                 test('a content patch is reflected in search — the old content is no longer searchable', async () => {
                     const record = makeRecord({ content: { title: 'original wording' } });
                     await adapter.createRecord(record);
-                    await adapter.mutateRecord(record.id, { contentPatch: { title: 'updated wording' } });
-                    const stale = await adapter.queryRecords({ filter: { search: 'original' } });
+                    await adapter.patchContent(record.id, { title: 'updated wording' });
+                    const stale = await adapter.queryRecords(resolveQuery({ filter: { search: 'original' } }));
                     expect(stale.records.map((r) => r.id)).not.toContain(record.id);
-                    const fresh = await adapter.queryRecords({ filter: { search: 'updated' } });
+                    const fresh = await adapter.queryRecords(resolveQuery({ filter: { search: 'updated' } }));
                     expect(fresh.records.map((r) => r.id)).toContain(record.id);
                 });
                 test('a purged record is no longer found by search', async () => {
                     const record = makeRecord({ content: { title: 'ephemeral content' } });
                     await adapter.createRecord(record);
                     await adapter.deleteRecord(record.id, { purge: true });
-                    const result = await adapter.queryRecords({ filter: { search: 'ephemeral' } });
+                    const result = await adapter.queryRecords(resolveQuery({ filter: { search: 'ephemeral' } }));
                     expect(result.records.map((r) => r.id)).not.toContain(record.id);
                 });
             });