cursedbelt 2.7.0 → 3.0.0

package/src/react/data/wireEnvelope.spec.ts

@@ -1,264 +0,0 @@
-/**
- * The envelope contract (01 §6).
- *
- * The test that matters is the FIRST one, and it is the audit's own scenario
- * verbatim: rename `items` to `rows` in a mixin and — before this landed —
- * both `tsc`s, `lint`, the `requiredFeature` parity gate, the `engineResources`
- * CDC-channel parity gate (both of which compare route STRINGS and channel
- * STRINGS, never body shapes) and the browser gate were all green, while the
- * list rendered empty in production. Nothing in this repository could see it.
- */
-import { describe, expect, it } from 'bun:test';
-import { ASSET_ITEMS, ASSET_ITEM, ASSET_SOURCES, ENGINE_RESOURCES, KNOWLEDGE_BOARD_CARDS } from './engineResources';
-import { DEGRADED_ROW_SAMPLE, readWirePolicy, setWireErrorSink, setWirePolicy, WireShapeError } from './wireEnvelope';
-
-describe('the response envelope is checked, not assumed', () => {
-  it('REFUSES a listing whose envelope key was renamed — the `items` → `rows` bug', () => {
-    // Exactly what a mixin returning `{ success: true, rows: [...] }` produces.
-    expect(() => ASSET_ITEMS.read({ success: true, rows: [{ id: 'a', kind: 'photo' }] }, ASSET_ITEMS.id)).toThrow(WireShapeError);
-    // …and the error NAMES the resource and the key, so the fix is one grep.
-    try {
-      ASSET_ITEMS.read({ success: true, rows: [] }, ASSET_ITEMS.id);
-    } catch (error) {
-      expect((error as WireShapeError).message).toContain('asset.items');
-      expect((error as WireShapeError).message).toContain('`items`');
-      // The received shape too — "it was an object with these keys" is what
-      // turns a report into a diagnosis.
-      expect((error as WireShapeError).message).toContain('rows');
-    }
-  });
-
-  it('reads a well-formed page, cursor and all', () => {
-    const page = ASSET_ITEMS.read({ success: true, items: [{ id: 'a', kind: 'photo' }], cursor: 'c1' }, ASSET_ITEMS.id);
-    expect(page.items).toHaveLength(1);
-    expect(page.nextCursor).toBe('c1');
-  });
-
-  it('omits nextCursor rather than carrying a non-string one', () => {
-    // A route that echoed a numeric or object cursor would otherwise be passed
-    // straight into the next request's query string as "[object Object]".
-    const page = ASSET_ITEMS.read({ success: true, items: [], cursor: 42 }, ASSET_ITEMS.id);
-    expect(page.nextCursor).toBeUndefined();
-  });
-
-  it('REFUSES a keyed listing whose key is absent, and one whose key is not an array', () => {
-    expect(() => ASSET_SOURCES.read({ success: true }, ASSET_SOURCES.id)).toThrow(/`sources`/);
-    expect(() => ASSET_SOURCES.read({ success: true, sources: { a: 1 } }, ASSET_SOURCES.id)).toThrow(/`sources`/);
-  });
-
-  it('an ABSENT entity is data, not a shape error — but a non-envelope is', () => {
-    // A detail route legitimately answers "no such row" for a deleted item or a
-    // stale link. That must render the empty state, never throw.
-    expect(ASSET_ITEM.read({ success: true }, ASSET_ITEM.id).items).toEqual([]);
-    expect(ASSET_ITEM.read({ success: true, item: { id: 'a', kind: 'photo' } }, ASSET_ITEM.id).items).toHaveLength(1);
-    // A body that is not an object at all means the response was not this
-    // resource's envelope.
-    expect(() => ASSET_ITEM.read('not an envelope', ASSET_ITEM.id)).toThrow(WireShapeError);
-    expect(() => ASSET_ITEM.read(null, ASSET_ITEM.id)).toThrow(WireShapeError);
-  });
-
-  it('DEGRADES rather than throwing in a production bundle, and reports where a human looks', () => {
-    // 01 §6.2: "parse in dev/test, report + degrade in production, so a schema
-    // bug degrades rather than blanks the surface." A wrong list is bad; an app
-    // that throws on every render is worse.
-    expect(readWirePolicy()).toBe('throw'); // this suite runs under NODE_ENV=test
-
-    const reported: Error[] = [];
-    setWireErrorSink((error) => reported.push(error));
-    setWirePolicy('degrade');
-    try {
-      // The REAL production branch — not a catch around the throw. A probe that
-      // asserts against its own fixture proves nothing (`§D`), so the policy is
-      // a settable seam precisely so this line can execute the shipped path.
-      const page = ASSET_ITEMS.read({ success: true, rows: [{ id: 'a', kind: 'photo' }] }, ASSET_ITEMS.id);
-      expect(page.items).toEqual([]);
-    } finally {
-      setWirePolicy(null);
-      setWireErrorSink(null);
-    }
-
-    expect(reported).toHaveLength(1);
-    expect(reported[0]).toBeInstanceOf(WireShapeError);
-    expect((reported[0] as WireShapeError).detail).toMatchObject({ resource: 'asset.items', key: 'items' });
-    // …and the policy really did go back, or every test after this one would be
-    // silently running in degrade mode.
-    expect(readWirePolicy()).toBe('throw');
-  });
-
-  /**
-   * Every descriptor in the catalog must be reachable through a checked reader.
-   * The catalog is the thing that rots — a resource added with a hand-rolled
-   * `read: (body) => ({ items: (body as any).x })` would reintroduce exactly the
-   * silent-empty-page behavior this closes, and nothing else would notice.
-   */
-  it('EVERY catalog resource refuses a body missing its own envelope', () => {
-    const survivors: string[] = [];
-    for (const resource of ENGINE_RESOURCES) {
-      // `{}` carries no key any reader can want. An entity reader legitimately
-      // returns an empty page for it (an absent row is data), so the assertion
-      // is "throws OR returns nothing" — never "returns rows from nowhere".
-      let threw = false;
-      let rows = 0;
-      try {
-        rows = resource.read({ success: true, __unexpected: [1, 2, 3] }, resource.id).items.length;
-      } catch {
-        threw = true;
-      }
-      if (!threw && rows !== 0) survivors.push(resource.id);
-    }
-    expect(survivors).toEqual([]);
-  });
-
-  it('the catalog ids are unique — the cache key is built from them', () => {
-    const ids = ENGINE_RESOURCES.map((r) => r.id);
-    expect(new Set(ids).size).toBe(ids.length);
-  });
-
-  it('an UNKNOWN environment degrades — the fail-safe direction, which the obvious spelling gets backwards', () => {
-
-    // A browser bundle has no `process` unless the builder defines one, so
-    // "unknown" is the COMMON case in the shipped artifact. `env !== 'production'`
-    // would therefore default the SHIPPED app to throwing. `buildEngineClient`
-    // now defines NODE_ENV, but the library must not depend on every consumer
-    // remembering to.
-    const holder = globalThis as { process?: { env?: Record<string, string | undefined> } };
-    const saved = holder.process;
-    try {
-      holder.process = undefined;
-      setWirePolicy(null); // re-derive with no environment at all
-      expect(readWirePolicy()).toBe('degrade');
-
-      holder.process = { env: { NODE_ENV: 'production' } };
-      setWirePolicy(null);
-      expect(readWirePolicy()).toBe('degrade');
-
-      holder.process = { env: { NODE_ENV: 'development' } };
-      setWirePolicy(null);
-      expect(readWirePolicy()).toBe('throw');
-    } finally {
-      holder.process = saved;
-      setWirePolicy(null);
-    }
-    expect(readWirePolicy()).toBe('throw');
-  });
-});
-
-/**
- * The ROW half (frontier item 16). The envelope tests above prove the container
- * is the one this resource expects; these prove the things INSIDE it are.
- *
- * The failure being closed is not exotic. A `LEFT JOIN` that found nothing, a
- * repository mapping a NULL column, a service returning a partial projection and
- * a route hand-building a body all produce the same artifact: a row that is
- * missing a field the view interface promises unconditionally. `tsc` sees none
- * of them, because the client's `request<T>` is an assertion rather than a
- * measurement.
- */
-describe('rows are checked against what their view PROMISES (item 16)', () => {
-  it('REFUSES a row missing a field the view declares unconditional', () => {
-    // `MediaItemView.kind` is required — the gallery branches on it to pick a
-    // renderer, so a row without one renders nothing and reports nothing.
-    expect(() => ASSET_ITEMS.read({ success: true, items: [{ id: 'a' }] }, ASSET_ITEMS.id)).toThrow(WireShapeError);
-    try {
-      ASSET_ITEMS.read({ success: true, items: [{ id: 'a' }] }, ASSET_ITEMS.id);
-    } catch (error) {
-      const message = (error as WireShapeError).message;
-      // Resource, row index, field, expected kind, what arrived — everything
-      // needed to find the handler without opening a debugger.
-      expect(message).toContain('asset.items');
-      expect(message).toContain('row 0');
-      expect(message).toContain('`kind`');
-      expect(message).toContain('string');
-      expect((error as WireShapeError).detail).toMatchObject({ resource: 'asset.items', key: 'kind' });
-    }
-  });
-
-  it('REFUSES a field of the wrong TYPE, not merely an absent one', () => {
-    // The shape a repository produces when a numeric column is read into a
-    // string field, or a JSON column arrives unparsed.
-    expect(() => ASSET_ITEMS.read({ success: true, items: [{ id: 7, kind: 'photo' }] }, ASSET_ITEMS.id)).toThrow(/`id`/);
-    expect(() => KNOWLEDGE_BOARD_CARDS.read({ success: true, cards: [{ id: 'c', columnId: 'x', title: 't', labels: 'a,b', position: 1 }] }, KNOWLEDGE_BOARD_CARDS.id)).toThrow(
-      /`labels`/,
-    );
-  });
-
-  it('accepts a row carrying every required field, with optional ones absent', () => {
-    // The other half of the assertion: a checker that refused valid rows would
-    // be a new outage created in the name of preventing one. `title`,
-    // `streamUrl`, `hlsUrl` and `private` are all optional on `MediaItemView`.
-    const page = ASSET_ITEMS.read({ success: true, items: [{ id: 'a', kind: 'video' }] }, ASSET_ITEMS.id);
-    expect(page.items).toHaveLength(1);
-  });
-
-  it('REFUSES a non-object row — an array of strings where records were expected', () => {
-    expect(() => ASSET_ITEMS.read({ success: true, items: ['a'] }, ASSET_ITEMS.id)).toThrow(/row 0 is not an object/);
-  });
-
-  it('checks the ENTITY read too — a detail route can lie the same way a listing can', () => {
-    expect(() => ASSET_ITEM.read({ success: true, item: { id: 'a' } }, ASSET_ITEM.id)).toThrow(/`kind`/);
-    // …and an ABSENT entity is still data, not a shape error: there is no row to
-    // check, so nothing is refused.
-    expect(ASSET_ITEM.read({ success: true }, ASSET_ITEM.id).items).toEqual([]);
-  });
-
-  it('DEGRADES on a bad row, and RETURNS IT — the customer sees what they saw before, and somebody knows', () => {
-    const reported: Error[] = [];
-    setWireErrorSink((error) => reported.push(error));
-    setWirePolicy('degrade');
-    try {
-      const page = ASSET_ITEMS.read({ success: true, items: [{ id: 'a' }, { id: 'b' }] }, ASSET_ITEMS.id);
-      // NOT dropped. Dropping the bad rows would be a silent, data-losing "fix"
-      // of exactly the kind this module exists to stop — and a half-empty list
-      // is harder to diagnose than a wrong one.
-      expect(page.items).toHaveLength(2);
-    } finally {
-      setWirePolicy(null);
-      setWireErrorSink(null);
-    }
-    // ONE report, not two: in production the check is O(1) per page, because a
-    // wire-shape defect is systemic — every row came from one query through one
-    // mapper, so the first row answers the question the thousandth would.
-    expect(reported).toHaveLength(1);
-    expect(DEGRADED_ROW_SAMPLE).toBe(1);
-  });
-
-  it('walks the WHOLE page in dev/test, where a heterogeneous page is worth catching', () => {
-    // A union listing whose second source maps differently (asset's catalogue
-    // ∪ vault union is exactly that shape) is invisible to a first-row check.
-    expect(() =>
-      ASSET_ITEMS.read({ success: true, items: [{ id: 'a', kind: 'photo' }, { id: 'b' }] }, ASSET_ITEMS.id),
-    ).toThrow(/row 1/);
-  });
-
-  /**
-   * The parity property, and the one that keeps this from rotting: a resource
-   * added later with no spec would be a listing nothing checks, and only a human
-   * re-reading 41 declarations would notice. It is asserted HERE as well as in
-   * `engineResources.spec.ts` because the two ask different questions — that one
-   * asks whether the catalog is complete, this one whether the reader uses it.
-   */
-  it('EVERY catalog resource actually CHECKS its rows', () => {
-    const unchecked: string[] = [];
-    for (const resource of ENGINE_RESOURCES) {
-      const keys = Object.keys(resource.rowSpec as Record<string, unknown>);
-      expect(keys.length, `${resource.id} declares an empty row spec`).toBeGreaterThan(0);
-      // A row of `null`s carries every key and satisfies no kind, so every spec
-      // must refuse it. If a reader ignored its spec, this row would sail
-      // through — which is precisely the regression being pinned.
-      const row = Object.fromEntries(keys.map((key) => [key, null]));
-      const envelope = resource.envelope;
-      const body =
-        envelope.kind === 'paged'
-          ? { success: true, items: [row] }
-          : { success: true, [envelope.key]: envelope.kind === 'entity' ? row : [row] };
-      let refused = false;
-      try {
-        resource.read(body, resource.id);
-      } catch {
-        refused = true;
-      }
-      if (!refused) unchecked.push(resource.id);
-    }
-    expect(unchecked).toEqual([]);
-  });
-});

package/src/react/data/wireEnvelope.ts

@@ -1,345 +0,0 @@
-/**
- * The RESPONSE ENVELOPE contract — the one place a wire shape is checked
- * (spec 01 §6, incremental step 1).
- *
- * ## What was wrong
- *
- * There is no compile-time contract between a Hono handler's `c.json({...})` and
- * the React hook that reads it. `engineClient.request<T>` ends with
- * `return (body ?? {}) as T` — `T` is a CALLER-SUPPLIED ASSERTION, not a
- * measurement — and every `EngineResource.read` was `(body as Record<string,
- * unknown>)?.[key]` followed by a cast. So renaming `items` to `rows` in a mixin
- * left **both `tsc`s green, `lint` green, the `requiredFeature` and
- * `engineResources` parity gates green** (they compare route strings and channel
- * strings, never body shapes), **the browser gate green** — and the list
- * rendering EMPTY in production.
- *
- * That is not hypothetical; it is this repo's own recurring bug. `ASSET_ITEMS`
- * shipped half-declared for two arcs. `AssetService.remove` had no route for an
- * arc while its docstring described the caller. `MediaCell` rendered a delete
- * control no handler was passed to. Every one is the same missing contract,
- * found by hand each time.
- *
- * ## Both halves are now closed
- *
- * The **envelope** half (landed first): a response whose expected key is absent,
- * or present but not an array, is a LOCATED ERROR instead of an empty page.
- *
- * The **row** half (frontier item 16, this landing): {@link RowSpec} declares,
- * per listing type, every field the view interface promises is ALWAYS there —
- * and {@link checkRows} refuses a row that does not carry them. The two halves
- * catch different failures and neither subsumes the other: the envelope catches
- * a renamed container key, and the row check catches a row that arrives with a
- * field missing or of the wrong type, which is what a `LEFT JOIN` that found
- * nothing, a repository mapping a NULL column, or a service returning a partial
- * projection actually produces.
- *
- * ## Why hand-written and not zod, for BOTH halves
- *
- * zod earns its place on nested, branching shapes that no other artifact
- * describes. Here the shape is already described — by the `*View` interface the
- * service returns — so a zod schema would be a SECOND declaration free to drift
- * from the first. {@link RowSpec} cannot drift: it is a mapped type over the
- * view, so a renamed field fails `tsc` in this package and a new REQUIRED field
- * fails until the spec names it. That is the property zod would not have given
- * us, and it costs no bytes in a bundle that ships to a browser.
- *
- * ## What a spec deliberately does not check
- *
- * Optional fields, nested object shapes, and string FORMATS (an ISO date, a
- * uuid). A row is refused for the things whose absence breaks a render — the
- * fields the interface says are unconditional — and nothing else. A checker that
- * refused a valid row because a date was spelled differently would be a new
- * outage in the name of preventing one.
- *
- * ## Import direction
- *
- * This module imports NOTHING — not from the server tier, not from the config
- * tier. `§D`: "`import type` is erased from the emitted JS, NOT from the module
- * graph the compiler walks", so a type-only reach into `server/mixins/services`
- * would drag the server storage tier into a DOM-typed compile.
- */
-
-/** Where a malformed response goes when we choose to degrade rather than throw. */
-export type WireErrorSink = (error: Error) => void;
-
-let sink: WireErrorSink | null = null;
-
-/**
- * Route malformed-response reports somewhere a human will see them.
- *
- * `EngineDataProvider` installs one on mount — every generated app and the
- * studio mount it, so the sink has a real caller rather than an aspirational
- * docstring. It logs under the stable prefix `CC_WIRE_SHAPE` and deliberately
- * does NOT raise the app-error overlay: that surface is what a CUSTOMER reads,
- * and "the response has no `items` array" is a message for whoever ships the
- * app. Degrading exists so the screen keeps working.
- *
- * Absent ⇒ `console.error`, which is still louder than the empty array this
- * replaces.
- */
-export function setWireErrorSink(next: WireErrorSink | null): void {
-  sink = next;
-}
-
-/**
- * 01 §6.2's policy: **THROW in dev/test, report and DEGRADE in production.**
- *
- * A schema bug must be impossible to miss while building, and must not blank a
- * customer's screen after shipping — a wrong list is bad, an app that throws on
- * every render is worse.
- *
- * It is a mutable module value with a setter rather than a build-time constant,
- * and that is a deliberate trade. A `const` derived from `process.env.NODE_ENV`
- * would let the bundler drop the throw branch — saving one `throw` statement —
- * at the cost of making the DEGRADE branch untestable from a suite that runs
- * under `NODE_ENV=test`. A test that "proves" the production path by catching
- * the throw it is meant to avoid is a probe asserting against its own fixture,
- * which `§D` records as a standing footgun. So the branch is real and reachable.
- */
-export type WirePolicy = 'throw' | 'degrade';
-
-/**
- * `throw` only when the environment says so EXPLICITLY; otherwise `degrade`.
- *
- * The fail-safe direction matters and the obvious spelling (`env !== 'production'`)
- * gets it backwards. A browser bundle has no `process` unless the builder
- * defines one, so an unknown environment is the COMMON case in the shipped
- * artifact — and defaulting that to `throw` would put an exception in front of a
- * customer on the strength of a variable nobody set. Unknown ⇒ report and carry
- * on; a developer's `NODE_ENV` is what turns the loud mode on.
- */
-const defaultPolicy = (): WirePolicy => {
-  try {
-    const env = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env?.NODE_ENV;
-    return env === 'development' || env === 'test' ? 'throw' : 'degrade';
-  } catch {
-    return 'degrade';
-  }
-};
-
-let policy: WirePolicy = defaultPolicy();
-
-export function readWirePolicy(): WirePolicy {
-  return policy;
-}
-
-/** Override the policy. Pass `null` to restore the `NODE_ENV`-derived default. */
-export function setWirePolicy(next: WirePolicy | null): void {
-  policy = next ?? defaultPolicy();
-}
-
-/** Throw or report-and-degrade, per {@link readWirePolicy}. */
-function refuse(error: WireShapeError): void {
-  if (policy === 'throw') throw error;
-  (sink ?? ((e: Error) => console.error(e)))(error);
-}
-
-export class WireShapeError extends Error {
-  constructor(
-    message: string,
-    readonly detail: { readonly resource: string; readonly key: string; readonly received: string },
-  ) {
-    super(message);
-    this.name = 'WireShapeError';
-  }
-}
-
-const describe = (value: unknown): string => {
-  if (value === null) return 'null';
-  if (Array.isArray(value)) return `array(${value.length})`;
-  if (typeof value !== 'object') return typeof value;
-  const keys = Object.keys(value as object);
-  return `object{${keys.slice(0, 8).join(',')}${keys.length > 8 ? ',…' : ''}}`;
-};
-
-/**
- * Refuse a body that does not carry `key` as an array.
- *
- * `fallback` is what production returns after reporting. It is `[]` — the SAME
- * value the old silent path returned — which is the point: the behavior a
- * customer sees is unchanged, and the difference is that somebody now knows.
- */
-export function requireArray<T>(resource: string, key: string, body: unknown): T[] {
-  const container = body as Record<string, unknown> | null | undefined;
-  const rows = container == null ? undefined : container[key];
-  if (Array.isArray(rows)) return rows as T[];
-
-  refuse(
-    new WireShapeError(
-      `${resource}: the response has no \`${key}\` array — the route's envelope and this resource's reader disagree. Received ${describe(body)}.`,
-      { resource, key, received: describe(body) },
-    ),
-  );
-  return [];
-}
-
-/**
- * Refuse a request that omits a query parameter its route REQUIRES.
- *
- * Found while building the both-directions gate: `/api/system/calendar` answers
- * `400 CALENDAR_RANGE_MISSING` without `from`/`to`, the catalog said nothing
- * about it, and the single existing consumer happened to pass them. A second
- * consumer would have got a 400 that no type, no gate and no descriptor
- * predicted — the same class of undeclared coupling this catalog exists to
- * remove, one field over from the ones it already declares.
- *
- * Production still makes the request: it will 400, exactly as it does today, and
- * the report says why. Dev/test throws, because there the omission is a bug
- * being written rather than one already shipped.
- */
-export function requireParams(resource: string, required: readonly string[], params: Readonly<Record<string, unknown>>): void {
-  const missing = required.filter((key) => params[key] === undefined || params[key] === '');
-  if (missing.length === 0) return;
-  refuse(
-    new WireShapeError(
-      `${resource}: this route requires the query parameter(s) \`${missing.join('`, `')}\`, and the caller passed none. Pass them through \`params\` on the hook.`,
-      { resource, key: missing.join(','), received: describe(params) },
-    ),
-  );
-}
-
-/* ------------------------------------------------------------- row shapes */
-
-/**
- * What a field must BE at runtime.
- *
- * `defined` is the escape for a field the view types as a union of kinds
- * (`string | number | boolean` — a list cell's value): the guarantee is then
- * "present and not undefined", which is still the guarantee that matters, and
- * pretending to a precision the interface does not have would be worse than
- * naming the looser one.
- */
-export type FieldKind = 'string' | 'number' | 'boolean' | 'array' | 'object' | 'defined';
-
-/**
- * The kinds a spec may declare for a field of type `V`.
- *
- * This is the whole compile-time half. `RowSpec<T>` is a mapped type over the
- * view interface, so:
- *
- *   * renaming `title` → `label` in the view makes every spec naming `title`
- *     fail `tsc` — the excess-property check;
- *   * adding a REQUIRED field to a view makes every spec for it fail until it is
- *     named — the mapped type demands all required keys;
- *   * declaring `position: 'string'` where the view says `number` fails, because
- *     `KindFor<number>` does not include `'string'`.
- *
- * A zod schema beside the interface would have caught none of the three: it
- * would be a second declaration, free to drift from the first.
- */
-type ExactKind<V> = [V] extends [readonly unknown[]]
-  ? 'array'
-  : [V] extends [string]
-    ? 'string'
-    : [V] extends [number]
-      ? 'number'
-      : [V] extends [boolean]
-        ? 'boolean'
-        : [V] extends [object]
-          ? 'object'
-          : never;
-
-export type KindFor<V> = ExactKind<NonNullable<V>> | 'defined';
-
-type RequiredKeysOf<T> = { [K in keyof T]-?: undefined extends T[K] ? never : K }[keyof T];
-
-/**
- * Every field the view promises unconditionally, and what it must be.
- *
- * OPTIONAL view fields may be named too but need not be: a `title?: string` that
- * is absent is data, not a defect, and a spec that demanded it would refuse rows
- * the product itself calls valid.
- */
-export type RowSpec<T> = { readonly [K in RequiredKeysOf<T>]: KindFor<T[K]> } & {
-  readonly [K in Exclude<keyof T, RequiredKeysOf<T>>]?: KindFor<T[K]>;
-};
-
-/** The erased form {@link checkRows} walks. Every `RowSpec<T>` is assignable. */
-export type RowSpecShape = Readonly<Record<string, FieldKind>>;
-
-const kindOf = (value: unknown): FieldKind => {
-  if (Array.isArray(value)) return 'array';
-  if (value === null) return 'object';
-  const type = typeof value;
-  return type === 'string' || type === 'number' || type === 'boolean' || type === 'object' ? (type as FieldKind) : 'defined';
-};
-
-const matches = (kind: FieldKind, value: unknown): boolean => {
-  if (value === undefined) return false;
-  if (kind === 'defined') return true;
-  if (kind === 'array') return Array.isArray(value);
-  if (kind === 'object') return typeof value === 'object' && value !== null && !Array.isArray(value);
-  return typeof value === kind;
-};
-
-/**
- * How many rows a page is checked at, per {@link readWirePolicy}.
- *
- * A wire-shape defect is SYSTEMIC — every row of a page comes from one query
- * through one mapper — so the first row answers the question the thousandth
- * would. In dev/test we still walk the whole page, because there the cost is
- * nothing and a heterogeneous page (a union listing whose second source maps
- * differently) is exactly the kind of bug worth the walk. In production the
- * check is O(1) per page and cannot become a rendering cost on a long list.
- */
-export const DEGRADED_ROW_SAMPLE = 1;
-
-/**
- * Refuse rows that do not carry what their view interface promises.
- *
- * Returns the rows UNCHANGED — in both policies. Under `throw` the caller never
- * sees the return value, and under `degrade` a wrong-shaped row still renders
- * whatever it can, which is the same thing the customer saw before this existed.
- * Dropping the bad rows would be a silent, data-losing "fix" of the sort this
- * whole module exists to stop.
- */
-export function checkRows<T>(resource: string, spec: RowSpecShape | undefined, rows: T[]): T[] {
-  if (spec === undefined || rows.length === 0) return rows;
-  const limit = policy === 'throw' ? rows.length : Math.min(rows.length, DEGRADED_ROW_SAMPLE);
-  for (let index = 0; index < limit; index += 1) {
-    const row = rows[index];
-    if (row === null || typeof row !== 'object' || Array.isArray(row)) {
-      refuse(
-        new WireShapeError(
-          `${resource}: row ${index} is not an object — the route returned ${describe(row)} where a record was expected.`,
-          { resource, key: `[${index}]`, received: describe(row) },
-        ),
-      );
-      continue;
-    }
-    for (const [key, kind] of Object.entries(spec)) {
-      const value = (row as Record<string, unknown>)[key];
-      if (matches(kind, value)) continue;
-      refuse(
-        new WireShapeError(
-          `${resource}: row ${index} has no valid \`${key}\` — the view declares it as ${kind} and always present, and the route sent ${value === undefined ? 'nothing' : kindOf(value)}. The service's shape and this resource's contract disagree.`,
-          { resource, key, received: value === undefined ? 'undefined' : describe(value) },
-        ),
-      );
-    }
-  }
-  return rows;
-}
-
-/**
- * Read an OPTIONAL single entity under `key`.
- *
- * Deliberately NOT symmetric with {@link requireArray}: a detail route legitimately
- * answers "no such row" — a deleted item, a stale link — and that is data, not a
- * shape error. What IS refused is a body that is not an object at all, because
- * that means the response was not the envelope this resource expects.
- */
-export function readEntity<T>(resource: string, key: string, body: unknown): T[] {
-  if (body === null || typeof body !== 'object') {
-    refuse(
-      new WireShapeError(
-        `${resource}: the response is not an object envelope, so \`${key}\` cannot be read. Received ${describe(body)}.`,
-        { resource, key, received: describe(body) },
-      ),
-    );
-    return [];
-  }
-  const entity = (body as Record<string, unknown>)[key];
-  return entity != null && typeof entity === 'object' ? [entity as T] : [];
-}