AI guidance: co-located conformance pattern + one-command data-ai install

[krisnye]

Description

Two related bodies of work on the @adobe/data-ai AI guidance and the samples that exercise it.

1. Co-located, type-first conformance pattern. Reworks the feature-architecture rules and skills so a data/state transform file exports exactly its function and its cases (typed Conformance<typeof fn> / Derivation<typeof fn>), eliminating per-transform .cases.ts + .test.ts clutter in favor of a single per-layer aggregator test that auto-discovers via import.meta.glob.

• Injected services as named args (keyed by service-name-minus--service), with deterministic doubles that publish their exact responses, and strongly-typed effects (positive + negative compile-time checks).
• Matcher-aware matches() honoring vitest asymmetric matchers (anyNumber/anyString) so the pure spec and the ECS satisfy the same case despite ECS-minted ids.
• Four conformance runners (spec / transaction / action / computed), each with a barrel-driven coverage guard; computed conformance builds from the ComputedDatabase layer.
• Folders organize by kind of type (data/ values, services/ service types incl. impls, ui/ presentation); ui/ isolation is strict and inviolable.
• Assembled-db alias aligned to MainService; actions read current state from the store, never a cached computed.
• All samples converted to the pattern (todo reference impl, tictactoe, solid-dashboard, react-pixie, p2p, space-rock).

2. One-command, managed data-ai install. install now both copies the bundle and wires the consumer repo to self-update — idempotently pinning the exact dev-dependency, adding the repo's own postinstall, and gitignoring the managed folders. Skips the wiring gracefully with --global or when there's no package.json, and prints a lockfile-sync reminder only when it actually (re)pins the dep. README rewritten to the single-command flow.

Related PRs

None.

[krisnye]

anyNumber doesn't seem to demonstrate the vite any number pattern we use.

[krisnye]

Fixed in 602c42f. The example now imports anyNumber with an inline // vitest expect.any(Number), and the matchers bullet shows the actual source so the pattern is explicit:

// matchers.ts
import { expect } from "vitest";
export const anyNumber = expect.any(Number);
export const anyString = expect.any(String);

Also noted matches() honors any vitest asymmetric matcher (expect.stringContaining, …), not just these two.

[krisnye]

Why can't we import state derivations in cases where they have good/equivalent performance? I believe the tic tac toe sample had good samples of delegating observables concisely to the pure computed functions.

I definitely agree that we should always prioritize maximum performance in the ECS, both here and in state transitions, but in cases where it doesn't matter (small N, resource computeds etc, reusing seems like it is fine)

Please review and verify my thinking on this.

Summary: ECS is about performance anywhere that performance can matter, but it is fine to reuse tested data functions where appropriate.

[krisnye]

Verified — your thinking is correct, and I relaxed the rule in 602c42f.

I checked my own stated rationale and it was wrong for derivations. The rule justified the ban with "cases construct service test-doubles at load" — but that's true only of transform cases. A state/ derivation is (state) => value, takes no services, so its co-located cases are inert { input, value } data with no doubles, and they tree-shake out of the app build exactly like matchers.ts does. So module hygiene was never the real reason.

The real constraint is the one you named: performance. A derivation takes the whole State, so reusing it forces the computed to observe the full-state projection and re-run on any field change. That's fine for small-N / resource / scalar computeds (the tictactoe case — though note those actually delegate to data/board-state helpers, which read only what they need), and wasteful on a hot per-entity / large-N path, where you hand-wire minimal resource/index reads instead.

New guidance: prefer the data/<type> helper (both the computed and the state/ derivation call it, so they agree by construction); may import a pure state/ derivation where perf is adequate; hand-wire minimal reads where it matters. Reuse freely where it doesn't matter, optimize where it does. The one remaining hazard is a cases literal touching the public.js barrel at load — already forbidden in state.md.

[krisnye]

So, we are writing a custom expect matches for each feature? Is there no common or more reusable pattern that we could use? Let's think about this and examine several examples to see if anything common shakes out of this.

It seems that there should be standard patterns for converting state to ecs and comparing.

[krisnye]

Resolved — this is gone. The matcher-aware compare is now Match.matches/Match.assert in @adobe/data/testing (framework-agnostic, honors asymmetric matchers, float tolerance, and per-collection ordered/multiset via the unordered option). No feature writes expect-state-matches.ts anymore; space-rock just passes match: { unordered: new Set(["bullets","asteroids"]) } to the runners.

[krisnye]

args: undefined

still needs to be provided? Seems like would be nice to be omittable only when there are no args.

[krisnye]

Fixed. The shared Conformance.Case<State, Args> makes args optional exactly when the transform takes none — … & ([Args] extends [void] ? { args?: undefined } : { args: Args }) — so a no-arg case omits args entirely, and a real-arg case still requires it. fire-bullet cases now drop args.

[krisnye]

This seems like a LOT of type machinery to replicate in every conformance case. We should find a common location to define these, perhaps in adobe-data types. Approve the type names/location with me before implementing.

[krisnye]

This applies to almost all the types in this file.

[krisnye]

Done — extracted into a shared @adobe/data/testing module (approved names/location up-thread), and migrated all six samples to it. Two namespaces:

• Conformance — the case types (Case/Cases/DerivationCase/DerivationCases/Effects/ServiceCall), effect recording, generic id resolution, and the four runner drivers (runSpec/runTransactions/runActions/runComputeds).
• Match — framework-agnostic matches/assert, anyNumber/anyString, and a ref(label) id-correspondence matcher (options: unordered, tolerance).

This file — all ~112 lines of it — collapses to a ~10-line alias that binds State once:

import type { Conformance as ConformanceApi } from "@adobe/data/testing";
import type { State } from "./state.js";
export type Conformance<F extends (...a: never[]) => unknown> = ConformanceApi.Cases<State, F>;
export type Derivation<F extends (...a: never[]) => unknown> = ConformanceApi.DerivationCases<F>;

Transform/derivation files are unchanged (cases: Conformance<typeof fn>). expect-state-matches.ts, record-effects.ts, matchers.ts, and expect-conforms.ts are deleted from every feature — ~180 lines of per-feature infra gone, replaced by the alias + the genuinely feature-specific projection (from-state/to-state/to-data). vitest is an optional peer dep. Shipped in commits 7b8261a → aaeba48; @adobe/data 2935 tests green, all samples green on Node 24.

[krisnye]

Resolved — moved into shared @adobe/data/testing (Conformance + Match namespaces); this per-feature file is now a ~10-line alias / deleted. See the summary on the type-machinery thread above.

[krisnye]

This also seems that it would be worth sharing from somewhere else.

[krisnye]

Resolved — moved into shared @adobe/data/testing (Conformance + Match namespaces); this per-feature file is now a ~10-line alias / deleted. See the summary on the type-machinery thread above.

[krisnye]

Ya, this is all way too much code to have to author for each feature.

[krisnye]

Resolved — moved into shared @adobe/data/testing (Conformance + Match namespaces); this per-feature file is now a ~10-line alias / deleted. See the summary on the type-machinery thread above.

[krisnye]

This export does not adhere to our single export rules. It would be preferable if conformance tests just injected their own values.

[krisnye]

Fixed. create-fake.ts is now a single export (createFake); the published schedule is folded inline as its default, and it is dropped from public.ts. Per your preference, conformance cases now inject their own values — OpponentService.createFake([4]) — and assert against what they passed, so nothing reads a shared published constant. Applied to all five service doubles; features/services/index.md updated to this convention.

[krisnye]

are these type checks necessary per feature? this isn't covered by our new data testing types?

[krisnye]

Right — moved. The Effects positive/negative type-test now lives once in @adobe/data/testing (conformance/effects.type-test.ts), and every per-feature conformance-case.type-test.ts is deleted. The feature conformance-case.ts is now purely the ~10-line State-binding alias (plus the entity re-export).

[krisnye]

Why does this monolith exist? I thought we had an automated way to locate test cases and execute them?

[krisnye]

Resolved — actions.test.ts is now one Conformance.runActions({ makeDb, store, fromState, toState, transitions: <data/state glob>, actions: <barrel or actions-dir glob> }) call. It discovers actions and pairs each to its same-named transition automatically (like runSpec); no imports-and-conforms(...) list. See the full write-up on the thread below.

[krisnye]

See, this is another monolith. We need a better way rather than writing a monolithic test importer.

Let's think of some way to improve and simplify how we aggregate and run the tests that is not monolithic.

[krisnye]

Done — the runners now auto-pair by name, so there is no importer to maintain. I traced every override to a spec↔ecs vocabulary gap and closed each at the source rather than in the test:

• services → conform the action (reads db.services); the case's service args become recording overrides via makeDb.
• identity → a Conformance.entity(specId) arg marker the runner resolves per side (spec→data-id, ecs→seeded entity); ecs ops take the entity under the transition's arg key.
• arg shape → precise (non-Partial) invocation, so same-shape ops need no reshape.
• granularity/infra → an op with no same-named transition is skipped (infra like setInput, or system-dispatched like collision); coverage is inherent to pairing, so the guards are gone.
• name divergence → a thin same-named op (todo reorderTodo action, space-rock createInitial tx) instead of an adapter.
• output shape → computeds compare identity by default; entity-id lists opt into hydrate.

A whole conformance test file is now just discovery. tictactoe's, in full:

Conformance.runTransactions({
  createStore, fromState, toState,
  transitions: import.meta.glob([".../data/state/*.ts", "!*.test.ts", "!*.type-test.ts"], { eager: true }),
  transactions,   // the facet barrel (or a dir glob)
});

The one irreducible residual is ambient user-scoped context — p2p's per-peer userId — which keeps a single seedContext hook. All six samples migrated (zero per-item adapters), define removed, Node 24 green. Shipped in d09029d → ff76c63.