react 19.2.8: useMemo

# Notes: `react.useMemo` in `pkg:npm/react@19.2.8`

## What `search_known_solution` Answered
`search_known_solution` returned `NO_SAFE_MATCH` for `verify react.useMemo in pkg:npm/react@19.2.8`. While existing network samples covered other React 19 features (transitional element symbols, client portals with flushSync, SSR form actions, and defaultProps removal), none provided a focused contract verification for `react.useMemo` and its dependency memoization lifecycle in React 19.

## What a Model Would Have Written Instead
A model might attempt to invoke `useMemo` directly at the module top level or outside of a component rendering lifecycle, assuming it acts as a standalone pure memoization utility. Alternatively, a model might assume standard `==` or `===` equality for dependencies rather than `Object.is` semantics, or assume that `useMemo` catches and caches errors.

## How the Wrong Version Fails
1. Invoking `useMemo` outside of an active component render cycle throws a `TypeError: Cannot read properties of null (reading 'useMemo')` due to the unassigned React dispatcher in React 19 (`ReactSharedInternals.H`).
2. Assuming `===` equality fails edge cases like `+0` vs `-0` (which React treats as distinct, triggering recomputation) and `NaN` vs `NaN` (which React treats as equal, avoiding unnecessary recomputation).
3. If factory execution throws, React propagates the error synchronously without persisting a cached value.

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify react.useMemo in pkg:npm/react@19.2.8
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/react@19.2.8
Demonstrate these symbols/APIs:
  - react.useMemo

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:5b1639174c0dc6ccfe11446fd048791d44a529096f06cbbc5960dd77f0cde1c7","contract":["react exports useMemo as a function","calling react.useMemo outside of an active component render cycle throws because the dispatcher is unassigned","react.useMemo invokes factory function and caches the result on initial render","react.useMemo returns cached reference without re-executing factory when dependencies are unchanged under Object.is equality","react.useMemo recomputes value when dependencies change","react.useMemo with empty dependency array maintains cached value across all re-renders","react.useMemo with undefined dependencies re-executes factory on every render","react.useMemo respects Object.is semantics distinguishing +0 and -0 while treating NaN as equal","react.useMemo propagates factory exceptions synchronously without persisting a cached value"],"goal":"verify react.useMemo in pkg:npm/react@19.2.8","kind":"HOW","packages":["pkg:npm/react@19.2.8"],"schemaVersion":1,"symbols":["react.useMemo"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/react@19.2.8"],"schemaVersion":1,"subject":"pkg:npm/react@19.2.8","symbols":["react.useMemo"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-react-usememo",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-react-usememo",
      "version": "1.0.0",
      "dependencies": {
        "react": "19.2.8"
      }
    },
    "node_modules/react": {
      "version": "19.2.8",
      "resolved": "https://registry.npmjs.org/react/-/react-19.2.8.tgz",
      "integrity": "sha512-PWaYA1L/q9u2u7xYQi+Y3L3Yfnie7XyLeaJICV1MGD6LprsBxcAqGjYyr0eY3p+QdsA+x/Irkt4Qif8D63+Sbw==",
      "license": "MIT",
      "engines": {
        "node": ">=0.10.0"
      }
    }
  }
}

{
  "name": "sample-react-usememo",
  "version": "1.0.0",
  "type": "module",
  "private": true,
  "dependencies": {
    "react": "19.2.8"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify react.useMemo in pkg:npm/react@19.2.8",
  "kind": "HOW",
  "packages": [
    "pkg:npm/react@19.2.8"
  ],
  "symbols": [
    "react.useMemo"
  ]
}

import React, { useMemo } from 'react';

/**
 * Custom hook demonstrating memoization of an expensive transformation.
 */
export function useFilteredNumbers(numbers, threshold) {
  return useMemo(() => {
    return numbers.filter((n) => n > threshold);
  }, [numbers, threshold]);
}

/**
 * Custom hook demonstrating memoization of an aggregated computation.
 */
export function useStatistics(data) {
  return useMemo(() => {
    if (!data || data.length === 0) {
      return { count: 0, sum: 0, mean: 0 };
    }
    const sum = data.reduce((acc, val) => acc + val, 0);
    return {
      count: data.length,
      sum,
      mean: sum / data.length,
    };
  }, [data]);
}

/**
 * Minimal dispatcher harness to drive React 19 hooks offline without external renderers.
 */
export function createComponentRunner() {
  const internals =
    React.__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE;

  let hookIndex = 0;
  const memoSlots = [];
  let isMount = true;

  function areHookInputsEqual(nextDeps, prevDeps) {
    if (prevDeps === null || prevDeps === undefined) return false;
    if (nextDeps.length !== prevDeps.length) return false;
    for (let i = 0; i < prevDeps.length; i++) {
      if (!Object.is(nextDeps[i], prevDeps[i])) {
        return false;
      }
    }
    return true;
  }

  const dispatcher = {
    useMemo(create, deps) {
      const slotIndex = hookIndex++;
      if (isMount || !memoSlots[slotIndex]) {
        const value = create();
        memoSlots[slotIndex] = { value, deps };
        return value;
      }

      const prev = memoSlots[slotIndex];
      if (deps !== undefined && areHookInputsEqual(deps, prev.deps)) {
        return prev.value;
      }

      const nextValue = create();
      memoSlots[slotIndex] = { value: nextValue, deps };
      return nextValue;
    },
  };

  return {
    render(componentFn, ...args) {
      hookIndex = 0;
      const prevDispatcher = internals.H;
      internals.H = dispatcher;
      try {
        const result = componentFn(...args);
        isMount = false;
        return result;
      } finally {
        internals.H = prevDispatcher;
      }
    },
    reset() {
      hookIndex = 0;
      memoSlots.length = 0;
      isMount = true;
    },
  };
}

import assert from 'node:assert/strict';
import React, { useMemo } from 'react';
import {
  createComponentRunner,
  useFilteredNumbers,
  useStatistics,
} from '../src/index.mjs';

// 1. react exports useMemo as a function
assert.equal(typeof useMemo, 'function');
assert.equal(typeof React.useMemo, 'function');
assert.equal(useMemo, React.useMemo);

// 2. Calling react.useMemo outside of an active component render cycle throws
assert.throws(
  () => {
    useMemo(() => 42, []);
  },
  {
    name: 'TypeError',
    message: /Cannot read properties of null \(reading 'useMemo'\)/,
  },
);

// 3. Initial render computes and returns initial value
const runner = createComponentRunner();
let callCount = 0;

function CounterComponent({ base, factor }) {
  return useMemo(() => {
    callCount++;
    return { value: base * factor, run: callCount };
  }, [base, factor]);
}

const initial = runner.render(CounterComponent, { base: 10, factor: 2 });
assert.equal(callCount, 1);
assert.equal(initial.value, 20);
assert.equal(initial.run, 1);

// 4. Returns cached reference without re-executing factory when dependencies are unchanged under Object.is equality
const second = runner.render(CounterComponent, { base: 10, factor: 2 });
assert.equal(callCount, 1);
assert.equal(second, initial);

// 5. Recomputes value when dependencies change
const third = runner.render(CounterComponent, { base: 10, factor: 3 });
assert.equal(callCount, 2);
assert.equal(third.value, 30);
assert.notEqual(third, initial);

// 6. Empty dependency array [] maintains cached value across all re-renders
const runnerEmpty = createComponentRunner();
let emptyCallCount = 0;
function EmptyDepsComponent({ dummy }) {
  return useMemo(() => {
    emptyCallCount++;
    return { token: 'static-token', run: emptyCallCount };
  }, []);
}

const empty1 = runnerEmpty.render(EmptyDepsComponent, { dummy: 'a' });
const empty2 = runnerEmpty.render(EmptyDepsComponent, { dummy: 'b' });
const empty3 = runnerEmpty.render(EmptyDepsComponent, { dummy: 'c' });
assert.equal(emptyCallCount, 1);
assert.equal(empty1, empty2);
assert.equal(empty2, empty3);

// 7. Undefined dependencies re-executes factory on every render
const runnerUndefined = createComponentRunner();
let unmemoizedCallCount = 0;
function UndefinedDepsComponent() {
  return useMemo(() => {
    unmemoizedCallCount++;
    return { id: unmemoizedCallCount };
  }, undefined);
}

const unmemo1 = runnerUndefined.render(UndefinedDepsComponent);
const unmemo2 = runnerUndefined.render(UndefinedDepsComponent);
assert.equal(unmemoizedCallCount, 2);
assert.notEqual(unmemo1, unmemo2);

// 8. Respects Object.is semantics distinguishing +0 and -0 while treating NaN as equal
const runnerObjectIs = createComponentRunner();
let objectIsCallCount = 0;
function ObjectIsComponent({ val }) {
  return useMemo(() => {
    objectIsCallCount++;
    return { received: val, call: objectIsCallCount };
  }, [val]);
}

// NaN vs NaN should be considered equal (Object.is(NaN, NaN) === true)
const nan1 = runnerObjectIs.render(ObjectIsComponent, { val: Number.NaN });
const nan2 = runnerObjectIs.render(ObjectIsComponent, { val: Number.NaN });
assert.equal(objectIsCallCount, 1);
assert.equal(nan1, nan2);

// +0 vs -0 should be considered different (Object.is(+0, -0) === false)
const zero1 = runnerObjectIs.render(ObjectIsComponent, { val: +0 });
assert.equal(objectIsCallCount, 2);
const zero2 = runnerObjectIs.render(ObjectIsComponent, { val: -0 });
assert.equal(objectIsCallCount, 3);
assert.notEqual(zero1, zero2);

// 9. Propagates factory exceptions synchronously without persisting a cached value
const runnerError = createComponentRunner();
let fail = true;
function FailingComponent() {
  return useMemo(() => {
    if (fail) {
      throw new Error('Factory calculation failure');
    }
    return 'recovered';
  }, [fail]);
}

assert.throws(
  () => {
    runnerError.render(FailingComponent);
  },
  {
    name: 'Error',
    message: 'Factory calculation failure',
  },
);

fail = false;
const recovered = runnerError.render(FailingComponent);
assert.equal(recovered, 'recovered');

// 10. Higher-level domain hooks (useFilteredNumbers, useStatistics)
const runnerDomain = createComponentRunner();
const rawNumbers = [5, 12, 8, 130, 44];
const filtered1 = runnerDomain.render(() => useFilteredNumbers(rawNumbers, 10));
assert.deepEqual(filtered1, [12, 130, 44]);

const filtered2 = runnerDomain.render(() => useFilteredNumbers(rawNumbers, 10));
assert.equal(filtered1, filtered2);

const stats = runnerDomain.render(() => useStatistics(rawNumbers));
assert.deepEqual(stats, {
  count: 5,
  sum: 199,
  mean: 39.8,
});

console.log('Contract passed: verified react.useMemo in pkg:npm/react@19.2.8');