@startsimpli/ui 0.4.111 → 0.4.113

package/src/components/collection/__tests__/scoped-client.test.ts

@@ -0,0 +1,243 @@
+/**
+ * `withScope` — the one seam (bd startsim-nq39j, epic startsim-ux39t).
+ *
+ * These pin the four things the bead asked to be TESTED rather than inspected:
+ * a list read carries the active scope, a blank one never reaches the wire, a
+ * request with no type never carries a scope at all, and a write cannot move a
+ * row between scopes.
+ *
+ * WHY THE ASSERTIONS LOOK AT THE ABSENCE OF A KEY. `?scope=` (blank) and
+ * `?scope=all` are both 400s server-side, and the blank one is the dangerous
+ * one — `normalize_container("")` returns `/`, so an implementation that sends
+ * an empty parameter is asking for EVERY scoped row while believing it asked
+ * for none (bd startsim-mj609). `toHaveProperty` is therefore the right
+ * assertion and `toBe('')` is not.
+ */
+import { resolveScope, scopeFilters, scopeKey, withScope, SCOPE_FILTER } from '../scoped-client';
+import type { CollectionClient, EntityRecord, EntityTypeDef, ListEntitiesOptions, Paginated } from '../types';
+
+function page<T>(results: T[]): Paginated<T> {
+  return { count: results.length, next: null, previous: null, results };
+}
+
+function record(over: Partial<EntityRecord> = {}): EntityRecord {
+  return {
+    id: 1,
+    entityType: 'topic',
+    externalId: null,
+    name: 'A topic',
+    data: {},
+    createdAt: '2026-08-27T00:00:00Z',
+    ...over,
+  };
+}
+
+function stub() {
+  const listTypes = jest.fn(async () => page<EntityTypeDef>([]));
+  const listAllEntities = jest.fn(async (_type: string, _options?: ListEntitiesOptions) => [record()]);
+  const updateEntity = jest.fn(async () => record());
+  const client: CollectionClient = { listTypes, listAllEntities, updateEntity };
+  return { client, listTypes, listAllEntities, updateEntity };
+}
+
+/** The filters bag as it was actually handed down, whatever the call shape. */
+function filtersOf(mock: jest.Mock, call = 0): Record<string, string> {
+  const options = mock.mock.calls[call]?.[1] as ListEntitiesOptions | undefined;
+  return options?.filters ?? {};
+}
+
+// --------------------------------------------------------------------------
+// resolveScope / scopeFilters — the wire spelling of "everything"
+// --------------------------------------------------------------------------
+
+describe('resolveScope — every spelling of "no bound" is one value', () => {
+  it.each([
+    ['null', null],
+    ['undefined', undefined],
+    ['empty', ''],
+    ['whitespace', '   '],
+    // The BROWSER URL's reserved word. A caller can reach the raw parameter
+    // without going through useScopeParam — a server component reading
+    // searchParams, a test, an app keeping the scope elsewhere — so `all` has to
+    // mean the same thing here as it does there.
+    ['the reserved word "all"', 'all'],
+  ])('resolves %s to null', (_label, input) => {
+    expect(resolveScope(input as string | null | undefined)).toBeNull();
+  });
+
+  it('keeps a real path, trimmed, verbatim', () => {
+    expect(resolveScope('  /clients/acme  ')).toBe('/clients/acme');
+  });
+
+  it('passes a malformed path THROUGH rather than dropping it', () => {
+    // The server refuses a value with no leading separator, and that refusal is
+    // the right answer: dropping it would silently widen to the whole corpus
+    // under a filter the reader believes is active.
+    expect(resolveScope('clients/acme')).toBe('clients/acme');
+  });
+});
+
+describe('scopeFilters — a blank scope is never on the wire', () => {
+  it.each([[null], [undefined], [''], ['   '], ['all']])(
+    'emits NO scope key at all for %p',
+    (input) => {
+      const filters = scopeFilters(input as string | null | undefined);
+      expect(filters).not.toHaveProperty(SCOPE_FILTER);
+      expect(Object.keys(filters)).toHaveLength(0);
+    },
+  );
+
+  it('emits the path when there is one', () => {
+    expect(scopeFilters('/clients/acme')).toEqual({ scope: '/clients/acme' });
+  });
+});
+
+// --------------------------------------------------------------------------
+// list reads
+// --------------------------------------------------------------------------
+
+describe('withScope — with a scope active, every list request carries it', () => {
+  it('puts the scope in the FILTERS bag, which the app puts in the URL string', async () => {
+    const { client, listAllEntities } = stub();
+    await withScope(client, '/clients/acme').listAllEntities('topic');
+    expect(filtersOf(listAllEntities)).toEqual({ scope: '/clients/acme' });
+  });
+
+  it('carries it on every type a workspace reads, not just the first', async () => {
+    const { client, listAllEntities } = stub();
+    const scoped = withScope(client, '/clients/acme');
+    await scoped.listAllEntities('topic');
+    await scoped.listAllEntities('draft');
+    expect(filtersOf(listAllEntities, 0)).toEqual({ scope: '/clients/acme' });
+    expect(filtersOf(listAllEntities, 1)).toEqual({ scope: '/clients/acme' });
+  });
+
+  it('keeps the caller’s own filters alongside it', async () => {
+    const { client, listAllEntities } = stub();
+    await withScope(client, '/clients/acme').listAllEntities('draft', {
+      filters: { 'attr.published_at__gte': '2026-08-10' },
+    });
+    expect(filtersOf(listAllEntities)).toEqual({
+      scope: '/clients/acme',
+      'attr.published_at__gte': '2026-08-10',
+    });
+  });
+
+  it('does not overrule a caller that sent its own scope', async () => {
+    const { client, listAllEntities } = stub();
+    await withScope(client, '/clients/acme').listAllEntities('draft', {
+      filters: { scope: '/clients/globex' },
+    });
+    expect(filtersOf(listAllEntities).scope).toBe('/clients/globex');
+  });
+
+  it('sends no scope key when nothing is in scope', async () => {
+    const { client, listAllEntities } = stub();
+    await withScope(client, null).listAllEntities('topic', { filters: { page_size: '200' } });
+    expect(filtersOf(listAllEntities)).not.toHaveProperty('scope');
+    expect(filtersOf(listAllEntities)).toEqual({ page_size: '200' });
+  });
+
+  it('calls an unscoped read exactly the way an unwrapped client is called', async () => {
+    // A client that only ever took `(type)` must see what it always saw, so
+    // wrapping an existing app in `withScope` is not a behaviour change.
+    const { client, listAllEntities } = stub();
+    await withScope(client, null).listAllEntities('topic');
+    expect(listAllEntities).toHaveBeenCalledWith('topic');
+    expect(listAllEntities.mock.calls[0]).toHaveLength(1);
+  });
+});
+
+describe('withScope — a request with no type never carries a scope', () => {
+  it('hands listTypes on with NO arguments', async () => {
+    // `?scope=` REQUIRES `?type=` — a 400 without it (bd startsim-mj609),
+    // because the parameter resolves through ONE type's declaration and the
+    // schema read spans every type.
+    const { client, listTypes } = stub();
+    await withScope(client, '/clients/acme').listTypes();
+    expect(listTypes).toHaveBeenCalledWith();
+    expect(listTypes.mock.calls[0]).toHaveLength(0);
+  });
+
+  it.each([[''], ['   ']])('adds no scope to a list read whose type is %p', async (type) => {
+    const { client, listAllEntities } = stub();
+    await withScope(client, '/clients/acme').listAllEntities(type);
+    expect(filtersOf(listAllEntities)).not.toHaveProperty('scope');
+  });
+});
+
+describe('withScope — the shared corpus opts out', () => {
+  it('leaves a `scoped: false` read unbounded', async () => {
+    // One source registry, one news_item corpus (epic startsim-ux39t decision
+    // 2). Narrowing a lookup of a shared type either 400s or silently loses
+    // every row outside the bound.
+    const { client, listAllEntities } = stub();
+    await withScope(client, '/clients/acme').listAllEntities('source', { scoped: false });
+    expect(filtersOf(listAllEntities)).not.toHaveProperty('scope');
+  });
+
+  it('scopes by DEFAULT, so forgetting narrows rather than widens', async () => {
+    const { client, listAllEntities } = stub();
+    await withScope(client, '/clients/acme').listAllEntities('source', {});
+    expect(filtersOf(listAllEntities)).toEqual({ scope: '/clients/acme' });
+  });
+});
+
+// --------------------------------------------------------------------------
+// writes
+// --------------------------------------------------------------------------
+
+describe('withScope — a write cannot cross scopes', () => {
+  it('hands the payload on BYTE-FOR-BYTE', async () => {
+    const { client, updateEntity } = stub();
+    const input = { data: { status: 'ready', path: '/clients/globex' } };
+    await withScope(client, '/clients/acme').updateEntity(7, input);
+    expect(updateEntity).toHaveBeenCalledWith(7, input);
+  });
+
+  it('never rewrites a row’s own scope to the active one', async () => {
+    // Patching a row while /clients/acme is selected must NOT move it out of
+    // /clients/globex. Changing a row's scope is an explicit act.
+    const { client, updateEntity } = stub();
+    await withScope(client, '/clients/acme').updateEntity(7, {
+      data: { path: '/clients/globex' },
+    });
+    const [, input] = updateEntity.mock.calls[0] as [unknown, { data: Record<string, unknown> }];
+    expect(input.data.path).toBe('/clients/globex');
+  });
+
+  it('never STAMPS a scope onto a write that carried none', async () => {
+    // The bead's "writes stamp it" belongs to CREATE, on the upsert path. There
+    // is no create on this interface, and stamping an UPDATE is exactly the
+    // cross-scope move the same bead forbids.
+    const { client, updateEntity } = stub();
+    await withScope(client, '/clients/acme').updateEntity(7, { data: { status: 'ready' } });
+    const [, input] = updateEntity.mock.calls[0] as [unknown, { data: Record<string, unknown> }];
+    expect(input.data).toEqual({ status: 'ready' });
+    expect(input).not.toHaveProperty('scope');
+  });
+});
+
+// --------------------------------------------------------------------------
+// the cache key
+// --------------------------------------------------------------------------
+
+describe('scopeKey — a cached read is only valid for its own scope', () => {
+  it('is the path for a bound client', () => {
+    expect(scopeKey(withScope(stub().client, '/clients/acme'))).toBe('/clients/acme');
+  });
+
+  it('is "all" for an unbounded one', () => {
+    expect(scopeKey(withScope(stub().client, null))).toBe('all');
+  });
+
+  it('is "all" for a plain, never-wrapped client, so an existing cache does not split', () => {
+    expect(scopeKey(stub().client)).toBe('all');
+    expect(scopeKey(undefined)).toBe('all');
+  });
+
+  it('differs between two scopes — the whole point of putting it in a key', () => {
+    const { client } = stub();
+    expect(scopeKey(withScope(client, '/a'))).not.toBe(scopeKey(withScope(client, '/b')));
+  });
+});

package/src/components/collection/__tests__/scoped-workspace.test.tsx

@@ -0,0 +1,179 @@
+/**
+ * The seam AS THE REVIEW SURFACE SEES IT (bd startsim-nq39j).
+ *
+ * `scoped-client.test.ts` pins the decorator in isolation. This pins the thing
+ * the decorator exists for: a workspace handed a scoped client asks the server
+ * for that scope, SHOWS that scope, and stops showing it the moment the scope
+ * changes.
+ *
+ * THE SECOND TEST HERE IS THE ONE THAT MATTERS, and it is a defect this bead
+ * introduced and had to fix. react-query keys the two list reads
+ * `['entities','topic','all']` — a key with no scope in it. Wrap the client and
+ * the REQUEST carries the new scope while the CACHE serves the old scope's rows:
+ * the "every list request carries it" acceptance criterion goes green while the
+ * board shows another client's work. A scope in the key is the fix and this is
+ * what stops it being tidied away.
+ */
+import * as React from 'react';
+import { render, screen, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+
+import { TopicReviewWorkspace } from '../TopicReviewWorkspace';
+import { withScope } from '../scoped-client';
+import type {
+  CollectionClient,
+  EntityRecord,
+  EntityTypeDef,
+  ListEntitiesOptions,
+  Paginated,
+} from '../types';
+
+const TOPIC_TYPE: EntityTypeDef = { id: 1, key: 'topic', label: 'Topic', attributes: [] };
+
+function page<T>(results: T[]): Paginated<T> {
+  return { count: results.length, next: null, previous: null, results };
+}
+
+function topic(id: number, title: string, path: string): EntityRecord {
+  return {
+    id,
+    entityType: 'topic',
+    externalId: null,
+    name: title,
+    data: { title, status: 'suggested', path },
+    createdAt: '2026-08-27T00:00:00Z',
+  };
+}
+
+/** Rows per scope, so "which scope did the board actually render" is answerable. */
+const BY_SCOPE: Record<string, EntityRecord[]> = {
+  '/clients/acme': [topic(1, 'Acme desalination', '/clients/acme')],
+  '/clients/globex': [topic(2, 'Globex logistics', '/clients/globex')],
+};
+
+function stub(overrides: Partial<CollectionClient> = {}) {
+  const listTypes = jest.fn(async () => page([TOPIC_TYPE]));
+  const listAllEntities = jest.fn(async (type: string, options?: ListEntitiesOptions) => {
+    if (type !== 'topic') return [];
+    const scope = options?.filters?.scope;
+    return scope ? (BY_SCOPE[scope] ?? []) : Object.values(BY_SCOPE).flat();
+  });
+  const updateEntity = jest.fn(async () => topic(1, 'Acme desalination', '/clients/acme'));
+  const client: CollectionClient = { listTypes, listAllEntities, updateEntity, ...overrides };
+  return { client, listTypes, listAllEntities, updateEntity };
+}
+
+function Harness({ client }: { client: CollectionClient }) {
+  // ONE QueryClient across re-renders — otherwise a fresh cache per render would
+  // hide exactly the staleness the scope-change test is looking for.
+  const [qc] = React.useState(
+    () => new QueryClient({ defaultOptions: { queries: { retry: false } } }),
+  );
+  return (
+    <QueryClientProvider client={qc}>
+      <TopicReviewWorkspace client={client} />
+    </QueryClientProvider>
+  );
+}
+
+/** Every `topic` list read the client saw, as its scope filter (or `none`). */
+function topicScopes(mock: jest.Mock): string[] {
+  return mock.mock.calls
+    .filter((call) => call[0] === 'topic')
+    .map((call) => (call[1] as ListEntitiesOptions | undefined)?.filters?.scope ?? 'none');
+}
+
+describe('a scoped client scopes the whole review surface', () => {
+  it('asks the server for the active scope, and renders what came back', async () => {
+    const { client, listAllEntities } = stub();
+    render(<Harness client={withScope(client, '/clients/acme')} />);
+
+    expect(await screen.findByText('Acme desalination')).toBeTruthy();
+    expect(topicScopes(listAllEntities)).toEqual(['/clients/acme']);
+    // NO CLIENT-SIDE FILTERING: the board shows exactly the rows the request
+    // returned, so the other scope's row was never fetched to be hidden.
+    expect(screen.queryByText('Globex logistics')).toBeNull();
+  });
+
+  it('REFETCHES when the scope changes, instead of serving the previous scope’s rows', async () => {
+    const { client, listAllEntities } = stub();
+    const { rerender } = render(<Harness client={withScope(client, '/clients/acme')} />);
+    expect(await screen.findByText('Acme desalination')).toBeTruthy();
+
+    rerender(<Harness client={withScope(client, '/clients/globex')} />);
+
+    expect(await screen.findByText('Globex logistics')).toBeTruthy();
+    await waitFor(() => expect(screen.queryByText('Acme desalination')).toBeNull());
+    expect(topicScopes(listAllEntities)).toEqual(['/clients/acme', '/clients/globex']);
+  });
+
+  it('reads the SHARED source registry unscoped, and reads it once for both scopes', async () => {
+    // One source registry across scopes (epic startsim-ux39t decision 2). It is
+    // also keyed without the scope, so switching client does not refetch it.
+    const { client, listAllEntities } = stub();
+    const { rerender } = render(<Harness client={withScope(client, '/clients/acme')} />);
+    expect(await screen.findByText('Acme desalination')).toBeTruthy();
+    rerender(<Harness client={withScope(client, '/clients/globex')} />);
+    expect(await screen.findByText('Globex logistics')).toBeTruthy();
+
+    const sourceCalls = listAllEntities.mock.calls.filter((call) => call[0] === 'source');
+    expect(sourceCalls).toHaveLength(1);
+    expect((sourceCalls[0][1] as ListEntitiesOptions).filters).not.toHaveProperty('scope');
+  });
+
+  it('never puts a scope on the schema read', async () => {
+    const { client, listTypes } = stub();
+    render(<Harness client={withScope(client, '/clients/acme')} />);
+    expect(await screen.findByText('Acme desalination')).toBeTruthy();
+    // `?scope=` without `?type=` is a 400 (bd startsim-mj609).
+    expect(listTypes).toHaveBeenCalledWith();
+  });
+});
+
+describe('an update preserves the row’s scope', () => {
+  it('PATCHes the row’s own path back, not the active one', async () => {
+    // The row lives in /clients/globex; the board is bounded to /clients/acme
+    // (a staff view that reached it, a stale cache, a hand-edited URL). Rating
+    // it must not MOVE it. PATCH replaces the whole blob, so the path has to be
+    // in the payload — with the row's value, never the client's.
+    const { client, updateEntity } = stub();
+    const scoped = withScope(client, '/clients/acme');
+    const stray = topic(9, 'Stray topic', '/clients/globex');
+    jest
+      .spyOn(client, 'listAllEntities')
+      .mockImplementation(async (type: string) => (type === 'topic' ? [stray] : []));
+
+    render(<Harness client={scoped} />);
+    expect(await screen.findByText('Stray topic')).toBeTruthy();
+
+    await userEvent.click(screen.getByRole('button', { name: /Good/ }));
+
+    await waitFor(() => expect(updateEntity).toHaveBeenCalled());
+    const [id, input] = updateEntity.mock.calls[0] as [
+      number,
+      { data: Record<string, unknown> },
+    ];
+    expect(id).toBe(9);
+    expect(input.data.path).toBe('/clients/globex');
+    expect(input.data.teamVerdict).toBe('good');
+  });
+});
+
+describe('a refused scope is reported, not rendered as an empty board', () => {
+  it('shows the server’s refusal instead of “Nothing to review right now.”', async () => {
+    // `?scope=` on a type declaring no scope path is a 400 (bd startsim-mj609).
+    // Swallowed, it renders as "this client has no topics" — a confident wrong
+    // answer of the same family as silently widening.
+    const { client } = stub();
+    jest.spyOn(client, 'listAllEntities').mockImplementation(async (type: string) => {
+      if (type === 'topic') throw new Error("type 'topic' declares no scope path");
+      return [];
+    });
+
+    render(<Harness client={withScope(client, '/clients/acme')} />);
+
+    expect(await screen.findByText(/declares no scope path/)).toBeTruthy();
+    expect(screen.queryByText('Nothing to review right now.')).toBeNull();
+  });
+});

package/src/components/collection/index.ts

@@ -28,7 +28,28 @@ export {
   type VerdictOption,
   type VerdictTone,
 } from './review';
-export type { CollectionClient, EntityRecord, EntityTypeDef, AttributeDef, Paginated, DataType } from './types';
+export type {
+  CollectionClient,
+  EntityRecord,
+  EntityTypeDef,
+  AttributeDef,
+  Paginated,
+  DataType,
+  EntityFilters,
+  ListEntitiesOptions,
+} from './types';
+// The scope seam (bd startsim-nq39j): wrap the injected client once and every
+// review surface in this package is scoped, because every one of them is
+// client-injected. `useScopedCollectionClient` in '@startsimpli/ui/scope' binds
+// it to the URL for a Next host.
+export {
+  withScope,
+  scopeFilters,
+  resolveScope,
+  scopeKey,
+  SCOPE_FILTER,
+  type ScopedCollectionClient,
+} from './scoped-client';
 export { readData, toCamelKey } from './data';
 export {
   parseSources,

package/src/components/collection/review.ts

@@ -186,6 +186,24 @@ export interface ReviewConfig {
    * unchanged, so nothing that does not pass this renders differently.
    */
   decisionLabels?: Record<string, string>;
+  /**
+   * Decision keys after which the drawer STAYS on the record instead of
+   * auto-advancing to the next one. Default: none (every decision behaves
+   * exactly as it does today).
+   *
+   * WHY THIS EXISTS (bd startsim-t1t1k). Auto-advance is right for pure triage
+   * — decide, move on — but wrong for a decision that UNLOCKS a next action on
+   * the same record. On OGMC, approving a topic is precisely what makes
+   * "Generate drafts" legal for it; advancing scrolled the newly-legal control
+   * off the screen, and the reviewer's workaround was to close the drawer,
+   * reload, filter to Ready, find the topic again and approve it a second time.
+   * Six steps, and the second approve wrote nothing — what the reload bought
+   * was a fresh record.
+   *
+   * Only the consumer knows whether one of its decisions has a follow-on, so
+   * this is theirs to declare. Rejecting has none, so it keeps advancing.
+   */
+  holdAfter?: string[];
 }
 
 export interface ResolvedReview {
@@ -203,6 +221,7 @@ export interface ResolvedReview {
   sourceAttrs: string[];
   omitNeedsWork: boolean;
   decisionLabels: Record<string, string>;
+  holdAfter: string[];
 }
 
 const DEFAULT_SOURCE_ATTRS = ['source_1', 'source_2', 'source_3', 'sources'];
@@ -235,6 +254,7 @@ export function resolveReviewConfig(
     sourceAttrs: (config.sourceAttrs ?? DEFAULT_SOURCE_ATTRS).filter((a) => declared.has(a)),
     omitNeedsWork: config.omitNeedsWork ?? false,
     decisionLabels: config.decisionLabels ?? {},
+    holdAfter: config.holdAfter ?? [],
   };
 }
 
@@ -284,10 +304,15 @@ export interface ReviewDecision {
  * A decision only appears when its status target resolves (or, for Needs work,
  * when there's an entry stage or an edit verdict) — so a two-state or non-workflow
  * enum simply shows fewer buttons instead of guessing.
+ *
+ * `holdAfter` overrides the advance flag per decision key (bd startsim-t1t1k) —
+ * it changes only whether the queue moves on, never what a decision writes.
  */
 export function reviewDecisions(r: ResolvedReview): ReviewDecision[] {
   const verdictOf = (tone: VerdictTone): string | null =>
     r.verdicts.find((v) => v.tone === tone)?.value ?? null;
+  const held = new Set(r.holdAfter ?? []);
+  const advances = (key: string) => !held.has(key);
   const entry = r.statusChoices[0] ?? null;
   const out: ReviewDecision[] = [];
 
@@ -298,7 +323,7 @@ export function reviewDecisions(r: ResolvedReview): ReviewDecision[] {
       status: r.transitions.approve,
       verdict: verdictOf('good'),
       tone: 'good',
-      advance: true,
+      advance: advances('approve'),
       shortcut: 'a',
       promptNote: false,
     });
@@ -325,7 +350,7 @@ export function reviewDecisions(r: ResolvedReview): ReviewDecision[] {
       status: r.transitions.reject,
       verdict: verdictOf('bad'),
       tone: 'bad',
-      advance: true,
+      advance: advances('reject'),
       shortcut: 'x',
       promptNote: false,
     });

package/src/components/collection/scoped-client.ts

@@ -0,0 +1,155 @@
+/**
+ * THE ONE SEAM (bd startsim-nq39j, epic startsim-ux39t).
+ *
+ * `withScope(client, scope)` returns a `CollectionClient` whose LIST reads carry
+ * the active scope and whose WRITES cannot cross one. Because every review
+ * surface in this package is client-injected — the app wrapper is ~10 LOC and
+ * hands in its authed tenant API — wrapping that one object scopes the whole
+ * surface at once. Nothing else in `collection/` knows what a scope is, and
+ * nothing else should learn: a second place that narrows is a second place that
+ * can forget to.
+ *
+ * THE WIRE SPELLING OF "EVERYTHING" IS SILENCE, and this is the decision the
+ * bead asked to be taken deliberately. The BROWSER URL spells it `?scope=all`
+ * (`SCOPE_ALL`), because there a missing parameter has to stay distinguishable
+ * from an asserted one — see `../scope/useScopeParam`. The WIRE cannot borrow
+ * that spelling and must not borrow the empty one either:
+ *
+ *   • `?scope=all` is a 400 — every stored path begins with the separator, so a
+ *     value that does not is refused as a value that could only match nothing.
+ *   • `?scope=` (blank) is ALSO a 400, and it is the dangerous one:
+ *     `normalize_container("")` returns `/`, so the obvious implementation reads
+ *     an empty parameter as EVERY scoped row (bd startsim-mj609).
+ *
+ * So "no scope" OMITS THE KEY. That is not merely the safe encoding, it is the
+ * only correct one: an omitted parameter returns unscoped rows too, which today
+ * is every row, while `?scope=/` would return only rows that carry a path.
+ *
+ * A PATH IS PASSED THROUGH VERBATIM, INCLUDING A BAD ONE. A value that is not
+ * `all` and not blank goes on the wire as the caller wrote it, even without a
+ * leading separator, because the server refuses that and a refusal is a better
+ * answer than a client that quietly drops a narrowing it did not understand.
+ *
+ * REFERENTIALLY STABLE OR NOT AT ALL. The returned client is the query key's
+ * input and react-query's identity for the injected API; building a new one on
+ * every render is the same mistake as building a new `ScopeClient` on every
+ * render (see `../scope/types.ts`). Memoize it on the scope, or use
+ * `useScopedCollectionClient` from `@startsimpli/ui/scope`, which does.
+ */
+import type { CollectionClient, EntityFilters, ListEntitiesOptions } from './types';
+
+/**
+ * The query parameter the tenant recognises. It is a plain lowercase word, so
+ * unlike `attr.x__gte` it survives a camel/snake rewrite unharmed — but it still
+ * travels the {@link EntityFilters} path, because one narrowing mechanism is the
+ * whole point of `EntityFilters` existing.
+ */
+export const SCOPE_FILTER = 'scope';
+
+/**
+ * The URL's reserved word for "no bound at all". Recognised here as well as in
+ * `useScopeParam` because a caller can reach a raw `?scope=` value without going
+ * through the hook — a server component reading `searchParams`, a test, an app
+ * that keeps the scope somewhere else — and `all` must mean the same thing to
+ * every one of them.
+ */
+const SCOPE_ALL_VALUE = 'all';
+
+/**
+ * A `CollectionClient` that knows what it is bounded to.
+ *
+ * `scope` is exposed for ONE reason and it is not decoration: a cached read is
+ * only valid for the scope it was made under, so a consumer's react-query key
+ * has to name it. {@link scopeKey} is that read.
+ */
+export interface ScopedCollectionClient extends CollectionClient {
+  /** The active path, or `null` for no bound. */
+  readonly scope: string | null;
+}
+
+/**
+ * Resolve any spelling of a scope to the one the wire uses: a path, or `null`.
+ *
+ * `null`, `undefined`, empty, whitespace and the reserved `all` all resolve to
+ * `null` — "no bound" — and `null` is spelled on the wire by sending nothing.
+ */
+export function resolveScope(scope: string | null | undefined): string | null {
+  if (typeof scope !== 'string') return null;
+  const trimmed = scope.trim();
+  if (!trimmed || trimmed === SCOPE_ALL_VALUE) return null;
+  return trimmed;
+}
+
+/**
+ * The filters a scope contributes to a list read — `{}` when there is no bound.
+ *
+ * IT RETURNS AN ABSENT KEY, NOT AN EMPTY ONE. `{ scope: '' }` is a 400 that
+ * would be read as "the root" by an unlucky implementation; the only encoding of
+ * "everything" this package will ever put on the wire is no key at all.
+ */
+export function scopeFilters(scope: string | null | undefined): EntityFilters {
+  const resolved = resolveScope(scope);
+  return resolved === null ? {} : { [SCOPE_FILTER]: resolved };
+}
+
+/**
+ * The cache-key fragment for a client's bound. `'all'` for no bound, so an
+ * UNWRAPPED client (a plain `CollectionClient`, which has no `scope` at all)
+ * keys identically to an explicitly unbounded one and an existing consumer's
+ * cache does not split in two for no reason.
+ */
+export function scopeKey(client: Pick<ScopedCollectionClient, 'scope'> | CollectionClient | null | undefined): string {
+  const scope = (client as ScopedCollectionClient | null | undefined)?.scope;
+  return resolveScope(scope) ?? SCOPE_ALL_VALUE;
+}
+
+/**
+ * Bind a `CollectionClient` to a scope.
+ *
+ * LIST reads gain `?scope=<path>`; WRITES are handed on BYTE-FOR-BYTE. A write
+ * that carried the active scope would be able to MOVE a row: patch a row while
+ * `/clients/acme` is selected and it would silently leave `/clients/globex`.
+ * Changing a row's scope is an explicit act with its own affordance, never a
+ * side effect of editing it somewhere. (The bead's phrase "writes stamp it"
+ * belongs to CREATE, on the scope-aware upsert path — there is no create on this
+ * interface, so there is nothing here to stamp.)
+ */
+export function withScope(
+  client: CollectionClient,
+  scope: string | null | undefined,
+): ScopedCollectionClient {
+  const resolved = resolveScope(scope);
+
+  return {
+    scope: resolved,
+
+    // Passed on with NO arguments at all. The schema read carries no `?type=`,
+    // and `?scope=` without `?type=` is a 400 (bd startsim-mj609) — so this is
+    // not an omission to tidy up later, it is the refusal being respected.
+    listTypes: () => client.listTypes(),
+
+    listAllEntities: (type: string, options?: ListEntitiesOptions) => {
+      // A type-less list read cannot carry a scope for the same reason
+      // `listTypes` cannot: the parameter resolves through ONE type's
+      // declaration. A blank type is already a bad request; adding a scope to it
+      // would turn a legible 400 into a confusing one.
+      const scopable = typeof type === 'string' && type.trim() !== '';
+      const applies = scopable && options?.scoped !== false;
+      const extra = applies ? scopeFilters(resolved) : {};
+      // Merged UNDER the caller's own filters, not over them: a consumer that
+      // deliberately sent its own `scope` (a fixture, a one-off drill-down)
+      // means it, and the decorator does not overrule it.
+      const filters: EntityFilters = { ...extra, ...(options?.filters ?? {}) };
+      const next: ListEntitiesOptions = { ...options, filters };
+      // No filters and no options in means no options through — an
+      // implementation that only ever took `(type)` sees exactly what it did
+      // before, so wrapping an old client is not a behaviour change.
+      if (Object.keys(filters).length === 0 && options === undefined) {
+        return client.listAllEntities(type);
+      }
+      return client.listAllEntities(type, next);
+    },
+
+    updateEntity: (id, input) => client.updateEntity(id, input),
+  };
+}