@opetope/lint 0.12.0 → 0.12.2

package/CHANGELOG.md

@@ -1,5 +1,269 @@
 # @opetope/lint
 
+## 0.12.2
+
+### Patch Changes
+
+- 2d1ecfc: Two axes of a Resource state, not one word (D462)
+
+  `ResourceState` carries two independent fields, `failure` and `pending`, and each is declared on every member of the
+  union — `?: never` where the member cannot hold one. Both are therefore read on the whole state in one step, without
+  narrowing by `kind` first:
+
+  ```ts
+  const refused = state.failure !== undefined;
+  const working = state.kind === 'loading' || state.pending !== undefined;
+  ```
+
+  `ResourceActivity` is gone, `ResourceChannelFailure` is now `ResourceFailure` with an optional `channel`, and
+  `failed` carries `failure` instead of a top-level `error`.
+
+  **Why.** One frequent question — «did something fail?» — was asked in three shapes: `failed.error`,
+  `loading.failure`, and `ready.activity.kind === 'failed'`. «Is something in flight?» was asked in two. Both are one
+  read each now.
+
+  **What changes in behaviour.** The priority within an axis is unchanged: at an equal kind the connection outranks
+  the refresh. The priority _between_ the axes is gone — a failed channel no longer hides a working one, so a `ready`
+  record publishes a dead connection and a running refresh together. That is more information, not less, and it is the
+  difference between «the live stream is gone, what is shown will not update» and «a manual reload is running over a
+  live stream».
+
+  `pending` is observable structure, so **every transition of the work axis now publishes a record**. It did not
+  before: one projected word hid that axis on a dataless `loading`, which carried no `activity` at all, and under any
+  failure, because `failed` outranked `pending`. Measured on a live Resource with both channels, a connection opening
+  over a dataless Resource goes from 1 record to 2; a `refresh()` over a healthy `ready` from 5 to 6; and a
+  `refresh()` over a `ready` that already carries a dead connection from 5 to 7, because its settling used to cost no
+  record at all. Up to two extra publications over the life of one materialization, and they reach the subscribers of
+  a `ready` Resource and not only a dataless one. Each carries the fact the axes were split for.
+
+  **Migration.**
+
+  | Was                                           | Is now                                            |
+  | --------------------------------------------- | ------------------------------------------------- |
+  | `state.error` on `failed`                     | `state.failure.error`                             |
+  | `state.failure.channel` on `loading`          | unchanged, and now on every kind                  |
+  | `state.activity.kind === 'failed'`            | `state.failure !== undefined`                     |
+  | `state.activity.kind === 'pending'`           | `state.pending !== undefined`                     |
+  | `state.activity.operation`                    | `state.failure?.channel` or `state.pending`       |
+  | `state.activity.error`                        | `state.failure?.error`                            |
+  | `ResourceChannelFailure` from `@opetope/core` | `ResourceFailure`                                 |
+  | `ResourceActivity` from `@opetope/core`       | nothing: read `state.failure` and `state.pending` |
+
+  `failure.channel` is absent only on a `failed` record whose every configured channel died, where no single channel
+  is the answer. `opetope/no-retired-vocabulary` reports `ResourceActivity` at both entries that ever spelled it, and
+  reports `state.activity` wherever it is read rather than only inside a `kind === 'loading'` narrowing; the rename to
+  `ResourceFailure` is printed by the compiler itself.
+
+  The inspection protocol is unchanged: `opetope.runtime-activity/4` stays `/4`, and the facts now read the published
+  record instead of a second copy of the channel phases.
+
+## 0.12.1
+
+### Patch Changes
+
+- 8aa4d85: **Four positions of a call name a command's input, and the member that says so is an intersection (D455).** The
+  `input` of `ModelCommandContext<Input>` and of `FeatureCommandContext<Within, Input>` was
+  `Input extends void ? {instruction} : Input`, which is not provably `Input` while `Input` is unresolved: a generic
+  helper could read the member and could not hand it to anything asking for exactly its own type parameter
+  (`TS2345: Argument of type 'T extends void ? {…} : T' is not assignable to parameter of type 'T'`, and a constraint
+  on `T` did not cure it). It is `Input & (Input extends void ? {instruction} : unknown)` now. An intersection is
+  assignable to each of its members, so the hand-off resolves; the second branch is `unknown`, which intersects away,
+  so a named input reads exactly as before and a call that named none is refused on the read exactly as before. No
+  public name is added or removed — 59 types and 37 values before and after — and every emitted JavaScript file is
+  byte-identical apart from the lint rule's message, so no size budget moves. The type slices move
+  11 736 → 11 756, 87 612 → 87 710 and 160 090 → 160 268 instantiations against ceilings of 12 200, 99 062 and
+  181 237, which stay where they were.
+
+  - **The instruction the refusal prints names four positions in order of cost, and says why there is no fifth.**
+    D444 wrote that the annotation of the destructured context was the one place an input could be named. It is the
+    most expensive of four. `Input` is inferred from every position of the call except the body: the result type of a
+    model factory names the input of every command in the literal it returns; an option whose callback is annotated
+    (`dedupe`, `memoize`, `concurrency: { by }`) names it where a call was writing an option anyway; a constant
+    annotated `Command<Input, Output>` names it and keeps `Output` checked; and the annotation of the context is what
+    is left. `command<Deposit>(…)` is not a position — one explicit type argument pins `Output` to its default, and
+    the body that answers a value is refused for answering one. A feature has the last two only: `own.command`
+    answers a ref carrying the feature's id, which no public name annotates.
+  - **The authoring documents now teach the cheap positions instead of the expensive one.** The spec, the cookbook,
+    the authoring guide, the primitives reference, the wave migration and the lint rule and its README were all
+    teaching the context annotation as the one route; the compiled examples that sit inside a factory with a result
+    type name nothing now, and the ones bound to a constant annotate the constant. The examples that keep the context
+    annotation say in a comment why it is the route left there.
+  - **Both directions are held by type tests.** A generic helper handing `context.input` to something asking for
+    exactly its parameter compiles, bare and constrained; a pair of identically shaped generic factories, one writing
+    a typed option and one not, both compile, which is what says the intersection is the cure and not the option; and
+    a call whose only option names nothing is refused on the read, with each assertion naming the diagnostic it
+    expects — `TS2339` at a member read, `TS2345` at a hand-off, `TS2322` at the pinned `Output`.
+
+- 8aec982: **A command's one waiting place is written as the record that names it: `concurrency: { pending: 'latest' }`
+  (D459).** The scalar `concurrency: 'latest'` named the input that wins and never named what it wins — «the latest»
+  reads as a place in a queue, as the body already running and as a cached answer, and only the first was true. The
+  shared form of the same fact never had that gap: `{ lane, pending: 'latest' }` says the place out loud, with the
+  `pending` an event and a live Resource already write for their own one waiting place. One fact was being written in
+  two vocabularies, and the shorter one left out the part that mattered. The word is removed rather than kept beside
+  the record, which makes this a breaking change to the authoring surface of a model command, of a model selection
+  and of a feature command.
+
+  - **Migrate by writing the place.** `concurrency: 'latest'` becomes `concurrency: { pending: 'latest' }` in
+    `ctx.command`, `ctx.select` and `own.command`. `concurrency: { lane, pending: 'latest' }` is unchanged: the lane
+    is the one parameter this record takes, and it is optional now instead of required. Nothing else about the option
+    moves — the same record, the same siblings, the same `dedupe` prohibition beside it.
+  - **No law moved with the spelling.** While call 1 runs, calls 2 and 3 take one waiting place: the body of 2 never
+    starts, its wait ends as `CommandError('cancelled', 'Command <id> replaced a waiting input.')`, and 3 runs when 1
+    finishes. A newer request never reaches the call in flight. The regression that holds this reads `signal.aborted`
+    inside the running body — after both newer requests were admitted and before the body returns — rather than
+    counting abort events, because the abort that follows a call's own end belongs to its cleanup and says nothing
+    about the policy. It was proved by substitution: with the kernel changed to cancel whatever is in flight, the
+    test fails on that line.
+  - **The retired word is answered with its replacement, not with a list of everything else.** The runtime throws
+    `Model command concurrency latest is now a record: write { pending: 'latest' }, or { lane, pending: 'latest' }.`
+    — and `Model select`, `Feature command` the same. Two neighbouring messages move with it: the choice sentence
+    loses the word — `concurrency must be queue, parallel, a lane of this surface or a record.` — and the record's own
+    refusal now says the lane is optional. A record that names `lane` and hands it `undefined` is still refused, by
+    the type under `exactOptionalPropertyTypes` and by the runtime, which reads the shape of the record by its keys.
+  - **The compiler names the replacement too, because the literal stays in the union.** The options record of a
+    command gained a third member — the retired word beside a key an author cannot write — so a refusal arrives as a
+    missing property carrying the instruction. Without it the union held no string at all, every word written there
+    widened to `string`, and one sentence answered a typo and a retired word alike. What the two now print, the same
+    on a model and on a feature: `{ concurrency: 'quee' }` is a `TS2820` that names the word and suggests `'queue'`,
+    which is better than it was before this change, and `{ concurrency: 'latest' }` is a `TS2345` whose elaboration
+    carries «`concurrency: "latest"` is now a record: write `{ pending: "latest" }`, or `{ lane, pending: "latest" }`».
+    A selection is the one surface where the compiler names the word written and not its replacement — its options
+    record is not a union — and there the runtime and the lint rule carry it.
+  - **`opetope/no-retired-vocabulary` reports it.** `concurrency: 'latest'` is a retired _value_ of a live key, the
+    shape `overflow: 'reject'` already had, so the rule now reads the values of a command's options record as well as
+    its keys and reports on the word that was written. A project that pins the rule's output by its own fixtures gains
+    one row.
+  - **What the gates read.** Instantiations are unchanged — 11 756, 87 710 and 160 268 against ceilings of 12 200,
+    99 062 and 181 237 — because a scalar became a record that already existed. The tightest size row, the headless
+    session consumer of `@opetope/devtools`, stays at 6.95 kB of 7.1 kB. The two runtime rows carry the new branch and
+    its message: the application graph consumer moves 48.56 → 48.66 kB of 49 kB and the public feature consumer
+    39.88 → 39.92 kB of 41 kB, measured by rebuilding the validator both ways. No budget moves.
+
+- be0613e: **The cell is the only place that says what a write is (D457).** `ModelStateWriter.update` was
+  `update<Value>(state: OwnedState<Value>, update: (previous: NoInfer<Value>) => Value)`, and a type parameter in the
+  result of a callback is an inference site: `Value` was not fixed while the body was checked, so the object literal
+  the updater returned had no contextual type and its fields widened — and the widened candidate then passed the
+  state, because `OwnedState` is covariant. `update(sessions, previous => ({ ...previous, kind: 'loading' }))` into a
+  cell whose `kind` is `'idle' | 'loading'` was therefore refused with a type nobody wrote,
+  `(previous: NoInfer<Sessions>) => { items: readonly string[]; kind: string }`, and the remedies were the author's:
+  `as const`, an annotated updater result, or a cell widened to `string`. The signature is
+  `update: NoInfer<(previous: Value) => Value>` now, so the state is the only inference site and the updater is
+  checked against the cell. No public name is added or removed — 59 types and 37 values before and after — and every
+  emitted JavaScript file is byte-identical, so no size budget moves; the three type slices write no state at all and
+  stand at 11 756, 87 710 and 160 268 instantiations against ceilings of 12 200, 99 062 and 181 237. Measured on 1 200
+  identical writes that compile under both signatures, the change costs 2 instantiations and 2 types.
+
+  - **Breaking: three writes that used to compile are refused now, all for the same reason.** A value wider than the
+    cell (`update(sessions, () => wider)` where `wider.kind` is `string`); a member of a discriminated union that
+    leaves out a field that member declares (`update(phase, () => ({ kind: 'loading' }))` where that member also
+    declares `since`); and a word outside a union of literals (`update(mode, () => 'stopped')` into
+    `OwnedState<'off' | 'on'>`). Each was accepted because the widened inference and the covariance of `OwnedState`
+    met, and each reached the cell through an updater that takes no parameter — the one shape whose inference
+    resolved before the body was checked. Each is a `TS2769` where it is written now. Recompiled with the previous
+    signature, the four new type tests report 15 refusals of correct writes and 12 asserted refusals that do not
+    fire.
+  - **An updater written at the call needs no `as const`, no annotated result and no widened field.** A literal it
+    returns keeps its type through a spread, in a nested record and in a member of a union; a mutable array and a
+    tuple in a cell keep their own mutability, which is why the `const` type parameter that also fixes the literals
+    was rejected. The value form of `update` is untouched, and so is the rule that a function in that position is the
+    updater. Diagnostics improve with the fix: the compiler prints `kind: "done"` instead of `kind: string`.
+  - **Two limits of that promise, both measured.** An updater hoisted into a constant widens at its own declaration,
+    where there is no contextual type at all, so it still needs an annotated result — before and after this change.
+    And the updater half performs no excess-property check, because TypeScript does not apply one to a literal
+    returned from a contextually typed function: a stray key written inside the updater now compiles, where it used
+    to be caught in passing by the false refusal whenever the literal also had something to widen. The value half
+    still catches it and names the key.
+  - **`StateCommit.update` and the reactive calculations are unchanged, and the type tests say why.** A commit's
+    `Value` is already one cell, and so is a pipe's, so neither `commit.update` nor `fold` has a callback result to
+    infer from. `derive`, `computed`, `fromMaybe`, `fromExternal` and the `project` of a collection do put a type
+    parameter in the result of a callback, and none of them has this defect: a widened result has nowhere to go
+    there, because no covariant container stands in the call for a supertype to pass through — the assignment of the
+    result refuses it. The `apply.change` of a live Resource is the one public callback left where the same widening
+    is live; it belongs to a separate change.
+  - **One workaround is gone.** The `@opetope/lint` README declared its example state with `kind: string` and a
+    comment saying the widening was a defect of the writer's own signature; the field is `'idle' | 'loading'` again
+    and the comment is gone. Spec §2.38 is the new compile-checked example, and it asserts all three closed holes.
+
+- 4e65393: **The published archive of every package loses `README.ru.md`, and `@opetope/runtime` loses the Russian pages of
+  its `docs/` as well (D456).** The Russian half of the documentation is removed: nineteen `*.ru.md` files,
+  **2 027 997 bytes**, which is 39.0 % of what `ci:docs` counts as a document and 35.1 % of every `*.md` in the tree.
+  Documentation is written once, in English, from here on. No public name, no `exports` entry and no subpath moves —
+  a `.ru.md` was never a resolvable specifier, only a file read by its path — and no line of shipped JavaScript
+  changes, which is why this is a patch. The composition of what is published does change, and this is the line that
+  says so.
+
+  - **What goes.** `CONTRIBUTING.ru.md`, `README.ru.md`, the README of the minimal React example, the nine guides of
+    `docs/` — agent guide, cookbook, devtools, how-it-works, primitives, releases, both migration guides and the
+    spec — and the `README.ru.md` of all seven packages. `docs/decisions.md` stays Russian and keeps no pair, as it
+    never had one. The nine copies under `packages/runtime/docs/` are generated by packaging and leave on their own.
+  - **The rule that required a pair is cancelled, with its gate.** `CLAUDE.md` said «README and user guides have
+    English/Russian pairs, updated together» with four exceptions; it now says a document is written once, in
+    English, and gets no second copy. `ci:docs` no longer looks for a `*.ru.md` beside a document and no longer
+    compares the heading skeleton of a pair, and its report reads «links and example section order passed».
+  - **One gate is lost outright, and nothing replaces it.** The fixture generator held every English example against
+    its Russian twin as the same program — syntax without comments and without JSX text — which is how D441 caught a
+    real drift in a spec §2 block, a string literal that differed in one copy. The defect class that stops being
+    caught is a silent edit to a detail of an example that still compiles: a string literal, a number, the order of
+    two arguments of the same type. `ci:type` accepts any literal of the right type, `ci:docs` reads section order
+    and links rather than values, `ci:asserted-refusals` holds pragmas, and the generator's own `--check` compares a
+    fixture with the very document it was lifted from, so one `fixtures:generate` makes any such edit the new
+    baseline. The twin was the only place in this repository where one program was written twice and the two
+    writings were compared. It also never knew which copy was right — in the one case it fired, the wrong copy was
+    the Russian one — and it protected above all the copy that nothing compiled.
+  - **Where the archive change is written down, so it cannot drift from its gate.** The composition of an archive is
+    stated in six places and all six are rewritten: the `files` of the seven manifests; the required-file list and
+    the archive-member allowlist of the pack archive check; the fixture of that check's own unit test; the
+    allowlists of the two real pack smoke tests; and what packaging demands of each package before it packs. The
+    requirement that `@opetope/runtime` ship `docs/spec.ru.md` is gone; `docs/spec.md` is required exactly as before.
+  - **The numbers the gates print.** `ci:docs` reads 28 documents instead of 46 — nineteen leave and this changeset
+    is itself a document — with 4 pending changesets instead of 3 and 424 decision identifiers instead of 423. Its
+    feature examples halve, 64 to 32: that gate lints every fenced example that declares a feature, and it was
+    linting both copies of each one. Packaging prepares 10 documents instead of 19, and the merge-marker scan reads
+    1101 text files instead of 1117 — seventeen of the nineteen removed files live under a scanned root, and this
+    changeset is one file back. The document examples do not move at all: 38 spec §2 blocks and 132 blocks of 11
+    other documents, 2 fragments, 14 asserted refusals, exactly as before, because only the English block was ever
+    lifted into a fixture.
+
+- e12b0b6: **An event takes its handler second: `event(source, run, subscribe, options?)` (D458).** The natural declaration was
+  refused although its payload was already annotated — `emit` typed as
+  `(payload: EventPayloadNotNamed | undefined) => boolean`, and `run` as taking the marker. The cause is the order of
+  the arguments and nothing else. TypeScript types a call's arguments in order and leaves a context-sensitive callback
+  out of the first inference pass; in the second it walks them left to right, and resolves the type parameters a
+  callback's own type refers to before giving that callback a contextual type. `subscribe` stood second and its one
+  unannotated parameter is a context carrying `Payload`, so `Payload` answered its default on the way past, before the
+  annotation on `run` was ever read. With `run` second, its unannotated parameter is a run context, which carries no
+  payload at all, so nothing about it resolves `Payload` and one annotation is the whole naming site. This is a
+  breaking change to the authoring surface of both a model and a feature.
+
+  - **Migrate by swapping the two callbacks.** `ctx.event(source, subscribe, run, options?)` becomes
+    `ctx.event(source, run, subscribe, options?)`, and `own.event` of a feature the same. Nothing else about the node
+    moves: the same four arguments, the same options record, the same `request`, the same delivery policies. A call
+    left in the old order does not compile silently — each callback is checked against the other's signature.
+  - **One annotation on `run` is now the whole naming site, whatever it does with its context.** The condition the
+    previous decision recorded — that a run annotating its payload and destructuring its context names nothing — was
+    true only while `subscribe` stood first. It is gone, and so is the shape it forced: the polling recipe of the
+    cookbook and the spec no longer annotate a context they only destructure. The marker's instruction narrowed with
+    it, from «annotate every parameter of `run`, the payload first — a `run` that leaves its context unannotated names
+    nothing — or annotate a `delivery.by` parameter» to «annotate the first parameter of `run`, or annotate a
+    `delivery.by` parameter», and the diagnostics gate holds those words.
+  - **The node now reads like every other one.** `effect`, `scope.while` and `scope.switch` all take the working
+    callback straight after the source; the event was the one node with a second callback wedged between them. The
+    rule the spec states for the whole vocabulary — the source first, the work next, modifiers last — is true here
+    without an exception now.
+  - **No single-signature cure exists, and that was measured rather than assumed.** On TypeScript 7.0.2, 6.0.2 and
+    6.0.3: carrying the payload through a separate inferred parameter as `Parameters<Run>[0]` answers `never`;
+    `NoInfer` on `emit` and `NoInfer` over the whole `subscribe` type both fail, because a reference to the parameter
+    is still a reference; a separate `Emitted extends Payload` fails; and a conditional `emit` that widens to
+    `unknown` or `any` stops the complaint at `emit` and poisons the inference instead. While `subscribe` stands
+    before `run` and mentions the payload, the order is the only lever there is.
+  - **`@opetope/lint` moves with it.** The ingress of an event is the third argument now, so
+    `opetope/no-subscribe-outside-models` reads it there; a project that pins the rule's behaviour by its own fixtures
+    updates them the same way an application updates its calls.
+  - **What the gates read.** Instantiations are unchanged — 11 756, 87 710 and 160 268 against ceilings of 12 200,
+    99 062 and 181 237 — because a reorder adds no type. The tightest size row, the headless session consumer of
+    `@opetope/devtools`, stays at 6.95 kB of 7.1 kB: the only emitted JavaScript that changes is one `TypeError`
+    message, `Model event run and subscribe must be functions.`, and the argument index the lint rule carries.
+
 ## 0.12.0
 
 ### Minor Changes