@opetope/core 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# @opetope/core
+
+## 0.1.0
+
+Initial release. See the package README for the supported API and usage.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aleksei Berezin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,250 @@
+# `@opetope/core`
+
+The renderer-neutral core: `Readable` and its derivatives, keyed collections, declarations of models, ports and
+extension points, calls with a lifetime. [The specification](https://www.npmjs.com/package/@opetope/runtime) §3 sets the package vocabulary;
+the runtime implementation uses the lower-level primitives on `@opetope/core/internal`.
+
+## Installation
+
+```sh
+npm install @opetope/core
+```
+
+Use matching Opetope versions. For release candidates, append `@next` to every `@opetope/*` package in the command.
+The API is ESM-only; Node 20.19+ is required. Development check commands below apply to a contributor checkout.
+
+The normative EN/RU guides are shipped in `@opetope/runtime`: after installing it, open
+`node_modules/@opetope/runtime/docs/spec.md` or `spec.ru.md`; recipes are in `cookbook.md` and `cookbook.ru.md`.
+No GitHub access is needed to read those installed guides.
+
+## Hello data boundary
+
+```ts
+import { defineModel } from '@opetope/core';
+import type { Readable } from '@opetope/core';
+import { createState } from '@opetope/core/internal';
+
+type Counter = Readonly<{ value: number }>;
+const counter = createState<Counter>({ value: 0 });
+const CounterModel = defineModel<{ readonly counter: Readable<Counter> }>('example.counter.model');
+
+let latest = counter.getSnapshot();
+const unsubscribe = counter.subscribe(() => {
+  latest = counter.getSnapshot();
+});
+counter.update(current => ({ value: current.value + 1 }));
+void latest;
+unsubscribe();
+counter.close();
+```
+
+`createState` lives on `@opetope/core/internal` (D142): an author gets owned state from `ctx.state` of their own
+model, while the direct constructor is what host adapters and tests need. That is why the examples import it from the
+internal entry.
+
+`Model` holds the type of a boundary, but owns no state and is not a service locator. A feature creates the
+implementation of a model through `model()` in its own `own` section, passing a `ModelContext`: a non-generic context
+with `state`, `update`, `signal`, `call`, `calls`, `lane`, `effect`, `event`, `resource`, `stream`, `scope`, `timers`
+and `cleanup`. `calls(deps, ['setAmount', 'submit'], { lane })` takes methods shaped as `() => Output`,
+`(input) => Output` or `(input, signal: AbortSignal) => Output`
+from the dependencies and returns one `Call` per key, the way `own.calls` does for a feature (D143, D244). Optional
+input and signal parameters are supported; no parameters means `void` input. A second parameter must be exactly
+`AbortSignal` or `AbortSignal | undefined`; options objects or more parameters need an explicit adapter. `state`
+returns `OwnedState<Value>`, and only that is accepted by `update`; the remaining members create nodes that live
+exactly as long as the generation of the model, while `cleanup(disposer)` puts its own cleanup into the same drain, in
+reverse order of registration. A model declares its dependencies with its own interface; about the feature, the
+imports and the ports it knows nothing.
+
+Each model context records ownership of its states privately: `OwnedState` gives the static write contract,
+and `update` also checks the creating context at runtime. The fence closes all owned states synchronously and
+prevents new calls, resources, streams, effects, events, scopes and state from being created afterwards.
+User work already admitted is physically drained before its source is released; logical cancellation of a caller
+does not replace that drain. A failed model factory drains its partial kernel (D170).
+
+A retryable quarantined `FeatureError` may expose `retryCleanup`; other errors have no retry capability.
+Guard the optional function before invoking it. `retired` remains the cancellation code (D168).
+
+## Derived data
+
+```ts
+import { collection, computed, derive, selectByKey } from '@opetope/core';
+import { createState } from '@opetope/core/internal';
+
+type Session = Readonly<{ id: string; title: string }>;
+const sessionList = createState<readonly Session[]>([]);
+const selectedSessionId = createState('active');
+const isVisible = createState(true);
+const sessions = collection({ from: sessionList, key: session => session.id });
+const selected = selectByKey(sessions, selectedSessionId);
+const title = derive({ from: selected, select: result => (result.kind === 'found' ? result.value.title : '') });
+const visibleTitle = computed({ read: get => (get(isVisible) ? get(title) : '') });
+```
+
+`derive({ from, select })` is the main explicit primitive; a tuple `from` is computed by a single formula.
+`computed({ read })` is the advanced autotracked variant with dynamic dependencies. Both use one
+scheduler: a source update stabilises the chain/diamond before notification, `Object.is` or an explicit `equals`
+stops an unchanged branch, and a formula error is rethrown on read and can recover
+after invalidation.
+
+`externalReadable` performs a subscribe-before-reread handshake, shares one source subscription between
+observers and releases it after a microtask of waiting. `collection` builds stable `list`/`byId`, and
+`selectByKey` notifies only the key that changed and drops an unused selector from the cache.
+
+`close()` on a `State` is a change, not silence: dependent nodes get one notification, after which their
+`getSnapshot` throws a `ReadableError` with the code `closed`, and from then on they stay quiet. An unsubscribed
+derived node gets the same rejection on its next read, because it reads a closed source (D146).
+
+## Contributions
+
+`ContributionTarget` is an authentic extension point with no string locator and no global registry.
+The runtime publishes and withdraws the entries that belong to one instance as an atomic batch; a consumer reads an
+ordered `entries` snapshot. The order is static: `priority` first, then the full contribution `id`.
+
+```ts
+import { defineRegistry, definePipe } from '@opetope/core';
+
+const counter = definePipe<number>({ id: 'inbox.entry-counter' });
+const pages = defineRegistry<string, { readonly title: string }>({ id: 'layout.pages' });
+
+counter.fold(0, undefined);
+pages.select('dashboard').getSnapshot();
+```
+
+In its first version a Pipe is an ordered-many fold only: zero handlers return the seed, and the first exception
+interrupts the fold. The query form and dynamic ordering are not part of the API. A keyed registry distinguishes a
+missing value from a found one through the same `Lookup` as `selectByKey`.
+
+## Calls and lanes
+
+`CallInvocation<Output>` is an authentic frozen native `Promise<Output>`, so it keeps ordinary `await`, `.then()` and
+Promise assimilation. The additional `callId`/`parentCallId`, `cancel()`, `getSnapshot()` and `subscribe()` separate
+the logical outcome of the caller (`settlement`) from the physical state of the body (`execution`). Cancellation
+settles immediately through a `CallError` with the code `cancelled`; a body that is still exiting on its `AbortSignal`
+stays visible as `draining`.
+
+A feature author never sees this layer: they write `own.call`/`own.calls` or `ctx.call`/`ctx.calls`, while the
+executor and the lane live on `@opetope/core/internal` for runtime implementation and host integration.
+
+These factory methods declare commands. Inside a command body, `run: (input, { invoke }) => invoke(target, input)`
+executes an existing command and inherits cancellation and the lane stack. The execution context exposes only
+`invoke`, with no former `call` alias; `ModelContext.call(options)` remains the declaration method (D243).
+
+Use the command's `run` signal for its execution, not `ModelContext.signal`, which lasts for the whole model.
+Resource loads and Stream connections/consumption likewise receive the signal of their current target execution.
+`calls` preserves the source receiver and always supplies `(input, signal)`, even when a method needs neither.
+Methods without I/O need no dummy signal parameter. Work that ignores cancellation can outlive the caller's logical
+outcome; physical drain still waits for it. Map an external client's options explicitly, for example
+`load: (input: Input, signal: AbortSignal) => client.load(input, { signal })` (D244).
+
+```ts
+import { createCallExecutor, defineCallLane } from '@opetope/core/internal';
+
+const writes = defineCallLane({ id: 'accounts.write.lane' });
+const refresh = createCallExecutor<{ accountId: string }, void>({
+  id: 'accounts.refresh.call',
+  scheduling: { lane: writes, policy: 'queue' },
+  cache: { key: input => input.accountId, policy: 'once' },
+  singleFlight: { key: input => input.accountId },
+});
+
+const invocation = refresh.start({ accountId: 'primary' }, ({ signal }) => loadAccount(signal));
+invocation.cancel();
+```
+
+Without `scheduling` every executor gets a private FIFO lane. A shared `CallLane` sets explicit serialisation between
+executors; `{ policy: 'parallel' }` disables the lane explicitly. The `{ policy: 'once' }` cache keeps only a
+successful result inside one instance — an author writes it as `once: true` or `once: input => key` — while
+`singleFlight` merges concurrent execution but leaves every waiter its own `CallInvocation`. An author may declare
+`policy: 'latest'` on a Call (D185): it replaces an input still waiting at the end of the lane, never the running
+body or a waiting input followed by another Call. React consumers keep status; they add no scheduling policy (D203).
+
+## Word map
+
+One page of the package vocabulary: spec §3 sets the names, the README explains what each one is for.
+
+| Word                                                                                  | What for                                                                                   |
+| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `Readable`, `State`, `Collection`, `Lookup`                                           | a value that can be read and subscribed to                                                 |
+| `derive`, `computed`, `fromOptional`, `collection`, `selectByKey`, `externalReadable` | how to get a `Readable`: derived, computed, external                                       |
+| `Equality`                                                                            | when a derived value counts as unchanged                                                   |
+| `Resource`, `ResourceSnapshot`, `ScopedRetention`, `LatestBackpressure`               | the resource and policy types; the `scoped` and `latest` values live in `@opetope/runtime` |
+| `defineModel`, `Model`, `ModelOf`, `ModelContext`, `OwnedState`                       | the model declaration, its shape, its context and its owned state                          |
+| `Call`                                                                                | a call with a lifetime: the unit of model behaviour                                        |
+| `definePort`, `Port`, `PortRef`                                                       | a port: one feature declares it, another requires it                                       |
+| `definePipe`, `Pipe`, `defineRegistry`, `Registry`                                    | extension points: a stream of values and a keyed set                                       |
+| `declarationId`, `DeclarationId`                                                      | validation of a declaration id                                                             |
+| `CallError` `cancelled`, `closed`                                                     | the call is dropped, cancellation (`isCancellation` on the internal entry)                 |
+| `CallError` `unavailable`, `publication-rejected`                                     | an answer the product shows; there is no cancellation here                                 |
+| `CancellationError`, `FeatureError`, `ReadableError`, `DeclarationError`, `CallError` | one class per subject, the state in the `code` field                                       |
+
+The kernel words `Attachment`, `Executor` and `Authority` live only in `@opetope/core/internal`: they are not on the safe entry (`Call` is an author word of the safe entry; `Blueprint` and `IR` are runtime names). `defineSlot`, `defineSwitchSlot`, `Slot` and
+`SwitchSlotTarget` are declared in `@opetope/react`, not here: a slot is a markup extension point.
+
+`Model` is a typed key for a record of `Readable` and `Call`. It declares the data and commands a consumer can
+access; a model factory creates the implementation within an owned lifetime. UI components consume this contract.
+
+The package stays `private` while the design is under review: the current API is experimental.
+
+## Boundary
+
+- the model and the data of a feature declare `Model`, `Readable` and `Call` — and nothing else;
+- the feature instance is not passed into the arguments of an author: the lifetime is checked by an opaque lease;
+- the internal call controller keeps the state of the last call separately from the total count of unclosed ones;
+- `close()` aborts unclosed calls, releases listeners and callback cells and accepts no late
+  result;
+- `isCancellation(error)` on `@opetope/core/internal` recognises the normal termination of an instance and of a call
+  for runtime adapters; the product reads `CommandOutcome` from `useCommand` and never recognises cancellation by
+  hand (D142). Cancellation is a code, not a class: on `CallError` it is meant only by
+  `cancelled` and `closed`, while `unavailable` and `publication-rejected` reach the product as an error (D138);
+- `FeatureError`, `CallError`, `ReadableError` and `DeclarationError` give one class per subject, and the state is
+  read from `code`: `retired`, `not-ready`, `quarantined`, `cleanup-failed` for a feature, `cancelled`, `closed`,
+  `unavailable`, `publication-rejected` for a call, `closed` for a `Readable`, `invalid-id` for a declaration;
+- React, view frames, module lowering and compatibility knowledge are outside the package.
+
+An author writes a declaration id as `<feature>.<entity>.<kind>`. The grammar still accepts the `/` and `:`
+separators for the sake of future namespaces, but the application does not use them.
+
+## Attachment readiness
+
+This whole section is about the internal entry used by the runtime implementation. A feature author writes
+`own.attach`.
+
+`AttachmentReadinessRef` is a read-only projection of readiness. The controller that creates it and
+`bindCallTargetToAttachment` live on `@opetope/core/internal`: this is a narrow lowering ABI, not a service locator
+and not a security boundary. The source of authority is never handed outward.
+
+The binding mints a separate authentic target with an exact provenance by object identity. Minting the same
+`(target, attachment)` pair again returns the same identity, and the call itself takes the authority out of the
+target. That is why a feature and the UI never assemble a "target plus lifetime" pair by hand and cannot accidentally
+take the target of one instance and the readiness of another.
+
+On top of that seam `createAttachmentLifecycleController` holds the `closed | opening | ready | closing |
+failed-close` state machine: the last intent wins, cleanup is adopted in advance, rollback runs in reverse order on a
+quiesced node, a retry touches only the handles that failed, and a quarantine does not open the next generation.
+Lowering `own.attach` into that state machine and minting the bound targets is the runtime's job, so an author writes
+neither `request` nor a retry by hand.
+
+The feature runtime checks `assertRetirable(expectedKey)` before a mutation and calls `retireExpected(expectedKey)`
+directly on it. Both checks look at the real current or pending key, not at an external copy.
+The plain `retire()` is kept, but the coordinator always uses the exact variant.
+
+Every cleanup must be safe on a partial opening, idempotent and repeatable. The strict waiting
+policy deliberately does not open a new generation on top of an opening or closing that never finishes: deadlines and
+drain supervision belong to the application. Opetope raises the fence at once and publishes diagnostics, but does not
+declare a physical resource closed on an artificial timeout.
+
+`createState`, `externalReadable`, `derive`, `computed`, `collection` and `selectByKey` work through one
+data scheduler. Two independent external adapters do not become one transaction without a shared host boundary; one
+source update and all of its derivatives stabilise atomically.
+
+## Compatibility contract
+
+The published ESM is built for Chrome 82+, Firefox 110+, Safari/iOS 15+ and Android 82+; the Node entry requires
+Node 20.19+. The package installs no global polyfills: the host must provide `Promise`, `Map`/`Set`, weak collections,
+`AbortController`/`AbortSignal`, `EventTarget`, `queueMicrotask` and `Reflect`. What the lower bound does not have —
+`AbortSignal.reason`, `throwIfAborted`, `AbortSignal.any`, the cancellation reason, `AggregateError` and
+`Error.cause` — goes only through the package's own compatibility implementation.
+
+A deterministic syntax-target gate checks the raw ESM, and a separate smoke test of an HTTP import checks current
+Chromium, Firefox and WebKit. This is not a claim that historical browser builds run in the repository: exact
+certification of the lower bound requires an external farm.

package/README.ru.md

@@ -0,0 +1,246 @@
+# `@opetope/core`
+
+Renderer-neutral ядро: `Readable` и его производные, keyed collections, объявления моделей, портов и точек
+расширения, вызовы с временем жизни. Словарь пакета задаёт §3 [спецификации](https://www.npmjs.com/package/@opetope/runtime);
+реализация рантайма использует низкоуровневые примитивы из `@opetope/core/internal`.
+
+## Установка
+
+```sh
+npm install @opetope/core
+```
+
+Используйте согласованные версии Opetope. Для release candidate добавьте `@next` каждому пакету `@opetope/*` в команде.
+API поставляется только в ESM; требуется Node 20.19+. Команды разработки ниже относятся к contributor checkout.
+
+Нормативные руководства EN/RU поставляются в `@opetope/runtime`: после его установки откройте
+`node_modules/@opetope/runtime/docs/spec.md` или `spec.ru.md`; рецепты находятся в `cookbook.md` и `cookbook.ru.md`.
+Для чтения установленных руководств доступ к GitHub не нужен.
+
+## Hello data boundary
+
+```ts
+import { defineModel } from '@opetope/core';
+import type { Readable } from '@opetope/core';
+import { createState } from '@opetope/core/internal';
+
+type Counter = Readonly<{ value: number }>;
+const counter = createState<Counter>({ value: 0 });
+const CounterModel = defineModel<{ readonly counter: Readable<Counter> }>('example.counter.model');
+
+let latest = counter.getSnapshot();
+const unsubscribe = counter.subscribe(() => {
+  latest = counter.getSnapshot();
+});
+counter.update(current => ({ value: current.value + 1 }));
+void latest;
+unsubscribe();
+counter.close();
+```
+
+`createState` живёт на `@opetope/core/internal` (D142): автор получает владеемое состояние из `ctx.state` своей
+модели, а прямой конструктор нужен адаптерам хоста и тестам. В примерах он поэтому импортируется с internal-входа.
+
+`Model` хранит тип границы, но не владеет состоянием и не является service locator. Реализацию модели
+создаёт фича через `model()` в своей секции `own`, передавая `ModelContext`: не generic контекст со `state`,
+`update`, `signal`, `call`, `calls`, `lane`, `effect`, `event`, `resource`, `stream`, `scope`, `timers` и `cleanup`.
+`calls(deps, ['setAmount', 'submit'], { lane })` берёт из зависимостей методы форм `() => Output`, `(input) => Output`
+или `(input, signal: AbortSignal) => Output` и
+отдаёт по одному `Call` на ключ, как `own.calls` у фичи (D143, D244). Поддерживаются необязательные input и signal;
+отсутствие параметров означает input `void`. Второй параметр должен быть точно `AbortSignal` или
+`AbortSignal | undefined`; options-объекты и дополнительные параметры требуют явного адаптера. `state`
+возвращает `OwnedState<Value>`, и только его принимает `update`; остальные члены создают узлы, которые живут ровно
+столько, сколько generation модели, а `cleanup(disposer)` кладёт свою уборку в тот же drain, в обратном порядке
+регистрации. Свои зависимости модель объявляет собственным интерфейсом, о фиче,
+импортах и портах она не знает.
+
+Каждый контекст модели хранит принадлежность состояния приватно: `OwnedState` задаёт статический контракт
+записи, а `update` дополнительно проверяет создавший контекст во время исполнения. Фенс синхронно закрывает всё
+владеемое состояние и запрещает затем создавать вызовы, ресурсы, стримы, эффекты, события, scope-ы и state.
+Уже допущенная пользовательская работа физически дренируется до освобождения источника; логическая отмена
+вызывающего не заменяет этот дренаж. Отказ фабрики модели дренирует частичный kernel (D170).
+
+Повторяемый карантинный `FeatureError` может предоставить `retryCleanup`; у других ошибок capability повтора нет.
+Проверяйте необязательную функцию перед вызовом. `retired` остаётся кодом отмены (D168).
+
+## Derived data
+
+```ts
+import { collection, computed, derive, selectByKey } from '@opetope/core';
+import { createState } from '@opetope/core/internal';
+
+type Session = Readonly<{ id: string; title: string }>;
+const sessionList = createState<readonly Session[]>([]);
+const selectedSessionId = createState('active');
+const isVisible = createState(true);
+const sessions = collection({ from: sessionList, key: session => session.id });
+const selected = selectByKey(sessions, selectedSessionId);
+const title = derive({ from: selected, select: result => (result.kind === 'found' ? result.value.title : '') });
+const visibleTitle = computed({ read: get => (get(isVisible) ? get(title) : '') });
+```
+
+`derive({ from, select })` — основной явный primitive; tuple `from` вычисляется одной формулой.
+`computed({ read })` — advanced autotracked-вариант с dynamic dependencies. Оба используют один
+scheduler: source update стабилизирует chain/diamond до notification, `Object.is` или явный `equals`
+останавливает неизменившуюся ветку, formula error повторно выбрасывается при чтении и может
+восстановиться после invalidation.
+
+`externalReadable` делает subscribe-before-reread handshake, разделяет одну source subscription между
+наблюдателями и освобождает её после микрозадачи ожидания. `collection` строит стабильные `list`/`byId`, а
+`selectByKey` уведомляет только изменившийся ключ и удаляет неиспользуемый selector из cache.
+
+`close()` у `State` это изменение, а не тишина: зависимые узлы получают одно уведомление, после него их
+`getSnapshot` бросает `ReadableError` с кодом `closed`, и дальше они молчат. Неподписанный производный узел
+получает тот же отказ на следующем чтении, потому что читает закрытый источник (D146).
+
+## Contributions
+
+`ContributionTarget` — authentic extension point без строкового locator-а и глобального registry.
+Runtime публикует и отзывает принадлежащие одного экземпляра записи атомарным batch-ем; consumer читает
+упорядоченный `entries` snapshot. Порядок статический: сначала `priority`, затем полный contribution `id`.
+
+```ts
+import { defineRegistry, definePipe } from '@opetope/core';
+
+const counter = definePipe<number>({ id: 'inbox.entry-counter' });
+const pages = defineRegistry<string, { readonly title: string }>({ id: 'layout.pages' });
+
+counter.fold(0, undefined);
+pages.select('dashboard').getSnapshot();
+```
+
+Pipe в первой версии — только ordered-many fold: ноль handlers возвращает seed, первый exception прерывает
+fold. Query-форма и динамический порядок не входят в API. Keyed registry различает missing и найденное значение
+через тот же `Lookup`, что и `selectByKey`.
+
+## Calls and lanes
+
+`CallInvocation<Output>` — authentic frozen native `Promise<Output>`, поэтому сохраняет обычные `await`, `.then()` и
+Promise assimilation. Дополнительные `callId`/`parentCallId`, `cancel()`, `getSnapshot()` и `subscribe()` разделяют
+логический outcome caller-а (`settlement`) и физическое состояние body (`execution`). Отмена немедленно завершает
+settlement через `CallError` с кодом `cancelled`; body, который ещё выходит по `AbortSignal`, остаётся видимым как `draining`.
+
+Автор фичи этого слоя не видит: он пишет `own.call`/`own.calls` или `ctx.call`/`ctx.calls`, а исполнитель и lane
+живут на `@opetope/core/internal` для реализации рантайма и интеграции с хостом.
+
+Эти методы фабрики объявляют команды. В теле команды `run: (input, { invoke }) => invoke(target, input)` исполняет
+существующую команду и наследует отмену и стек lane. В контексте исполнения есть только `invoke`, без прежнего
+алиаса `call`; `ModelContext.call(options)` остаётся методом объявления (D243).
+
+Для исполнения команды используйте сигнал её `run`, а не `ModelContext.signal`, который живёт со всей моделью.
+Загрузка Resource, соединение и consume Stream также получают сигнал текущего исполнения target.
+`calls` сохраняет receiver источника и всегда передаёт `(input, signal)`, даже если методу они не нужны.
+Методам без I/O не нужен фиктивный signal. Работа, игнорирующая отмену, может продолжаться после логического
+исхода вызывающего; физический drain всё ещё ждёт её. Options внешнего клиента преобразуйте явно, например
+`load: (input: Input, signal: AbortSignal) => client.load(input, { signal })` (D244).
+
+```ts
+import { createCallExecutor, defineCallLane } from '@opetope/core/internal';
+
+const writes = defineCallLane({ id: 'accounts.write.lane' });
+const refresh = createCallExecutor<{ accountId: string }, void>({
+  id: 'accounts.refresh.call',
+  scheduling: { lane: writes, policy: 'queue' },
+  cache: { key: input => input.accountId, policy: 'once' },
+  singleFlight: { key: input => input.accountId },
+});
+
+const invocation = refresh.start({ accountId: 'primary' }, ({ signal }) => loadAccount(signal));
+invocation.cancel();
+```
+
+Без `scheduling` каждый исполнитель получает приватную FIFO lane. Общая `CallLane` задаёт явную сериализацию между
+исполнителями; `{ policy: 'parallel' }` явно отключает lane. Кэш `{ policy: 'once' }` хранит только успешный
+результат внутри одного экземпляра — автор пишет его как `once: true` или `once: input => key`, — а `singleFlight`
+объединяет одновременное исполнение, но оставляет каждому ожидающему отдельный `CallInvocation`. Автор может задать
+`policy: 'latest'` у Call (D185): заменяется вход, ещё ожидающий в конце lane, но не исполняющееся тело и не вход, за
+которым уже стоит другой Call. React-потребители ведут статус и не добавляют политику исполнения (D203).
+
+## Карта слов
+
+Одна страница словаря пакета: spec §3 задаёт имена, README объясняет, зачем каждое.
+
+| Слово                                                                                 | Зачем                                                                       |
+| ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| `Readable`, `State`, `Collection`, `Lookup`                                           | значение, которое можно прочитать и на которое можно подписаться            |
+| `derive`, `computed`, `fromOptional`, `collection`, `selectByKey`, `externalReadable` | как получить `Readable`: производное, вычисленное, внешнее                  |
+| `Equality`                                                                            | когда производное значение считается прежним                                |
+| `Resource`, `ResourceSnapshot`, `ScopedRetention`, `LatestBackpressure`               | типы ресурса и его политик; сами `scoped` и `latest` — в `@opetope/runtime` |
+| `defineModel`, `Model`, `ModelOf`, `ModelContext`, `OwnedState`                       | объявление модели, её форма, контекст и владеемый state                     |
+| `Call`                                                                                | вызов с lifetime: единица поведения модели                                  |
+| `definePort`, `Port`, `PortRef`                                                       | порт: одна фича объявляет его, другая требует                               |
+| `definePipe`, `Pipe`, `defineRegistry`, `Registry`                                    | точки расширения: поток значений и набор по ключу                           |
+| `declarationId`, `DeclarationId`                                                      | проверка id объявления                                                      |
+| `CallError` `cancelled`, `closed`                                                     | вызов брошен, отмена (`isCancellation` на internal-входе)                   |
+| `CallError` `unavailable`, `publication-rejected`                                     | ответ, который показывает продукт; отмены здесь нет                         |
+| `CancellationError`, `FeatureError`, `ReadableError`, `DeclarationError`, `CallError` | один класс на субъект, состояние в поле `code`                              |
+
+Kernel-слова `Attachment`, `Executor` и `Authority` живут только в `@opetope/core/internal`: на безопасном входе их нет (`Call` — авторское слово безопасного входа, `Blueprint` и `IR` — имена рантайма). `defineSlot`, `defineSwitchSlot`, `Slot` и
+`SwitchSlotTarget` объявлены в `@opetope/react`, а не здесь: слот это точка расширения разметки.
+
+`Model` — типизированный ключ записи из `Readable` и `Call`. Он объявляет доступные потребителю данные и команды;
+фабрика модели создаёт реализацию в пределах принадлежащего ей времени жизни. UI-компоненты используют этот контракт.
+
+Пакет остаётся `private`, пока продолжается проработка дизайна: текущее API экспериментальное.
+
+## Граница
+
+- модель и данные фичи объявляют `Model`, `Readable` и `Call` — и больше ничего;
+- экземпляр фичи не передаётся в аргументы автора: время жизни проверяется непрозрачным lease-ом;
+- внутренний контроллер вызова держит состояние последнего вызова отдельно от общего счёта незакрытых;
+- `close()` abort-ит незакрытые вызовы, освобождает слушателей и ячейки колбэков и не принимает поздний
+  результат;
+- `isCancellation(error)` на `@opetope/core/internal` распознаёт штатное завершение экземпляра и вызова для
+  адаптеров рантайма; продукт читает `CommandOutcome` из `useCommand` и руками отмену не распознаёт (D142). Отмена это код, а не класс: у `CallError` её означают только
+  `cancelled` и `closed`, а `unavailable` и `publication-rejected` продукт показывает как ошибку (D138);
+- `FeatureError`, `CallError`, `ReadableError` и `DeclarationError` дают один класс на субъект, а состояние
+  читается из `code`: `retired`, `not-ready`, `quarantined`, `cleanup-failed` у фичи, `cancelled`, `closed`,
+  `unavailable`, `publication-rejected` у вызова, `closed` у `Readable`, `invalid-id` у объявления;
+- React, view frames, module lowering и compatibility knowledge находятся вне пакета.
+
+Id объявления автор пишет как `<feature>.<entity>.<kind>`. Разделители `/` и `:` грамматика пока принимает
+ради будущих пространств имён, но в приложении они не используются.
+
+## Attachment readiness
+
+Весь этот раздел про internal-вход, который использует реализация рантайма. Автор фичи пишет `own.attach`.
+
+`AttachmentReadinessRef` это read-only проекция готовности. Контроллер, который её создаёт, и
+`bindCallTargetToAttachment` живут на `@opetope/core/internal`: это узкий ABI понижения, а не локатор сервисов и не
+граница безопасности. Источник авторитета наружу не выдаётся.
+
+Привязка чеканит отдельный подлинный target с точным происхождением по идентичности объекта. Повторная чеканка той
+же пары `(target, вложение)` возвращает ту же идентичность, а вызов сам достаёт авторитет из target. Поэтому фича и
+UI не собирают пару «target плюс время жизни» руками и не могут случайно взять target одного экземпляра, а
+готовность другого.
+
+`createAttachmentLifecycleController` поверх этого шва держит автомат `closed | opening | ready | closing |
+failed-close`: последнее намерение выигрывает, уборка усыновляется заранее, откат идёт в обратном порядке на
+затихшем узле, повтор трогает только отказавшие ручки, а карантин не открывает следующее поколение. Понижение
+`own.attach` в этот автомат и чеканку связанных targets делает рантайм, поэтому автор не пишет ни `request`, ни
+повтор руками.
+
+Рантайм фичи проверяет `assertRetirable(expectedKey)` перед мутацией и вызывает `retireExpected(expectedKey)`
+непосредственно на ней. Обе проверки смотрят на настоящий текущий или ожидающий ключ, а не на внешнюю копию.
+Обычный `retire()` сохранён, но координатор всегда пользуется точным вариантом.
+
+Каждая уборка обязана быть безопасной при частичном открытии, идемпотентной и повторяемой. Политика строгого
+ожидания намеренно не открывает новое поколение поверх незавершающегося открытия или закрытия: дедлайны и надзор за
+дренажом принадлежат приложению. Opetope сразу ставит фенс и публикует диагностику, но не объявляет физический
+ресурс закрытым по искусственному таймауту.
+
+`createState`, `externalReadable`, `derive`, `computed`, `collection` и `selectByKey` работают через один
+планировщик данных. Два независимых внешних адаптера не становятся одной транзакцией без общей границы хоста; одно
+обновление источника и все его производные стабилизируются атомарно.
+
+## Compatibility contract
+
+Опубликованный ESM собирается для Chrome 82+, Firefox 110+, Safari/iOS 15+ и Android 82+; вход для Node требует
+Node 20.19+. Пакет не ставит глобальные полифилы: хост обязан дать `Promise`, `Map`/`Set`, слабые коллекции,
+`AbortController`/`AbortSignal`, `EventTarget`, `queueMicrotask` и `Reflect`. То, чего на нижней границе нет —
+`AbortSignal.reason`, `throwIfAborted`, `AbortSignal.any`, причина отмены, `AggregateError` и `Error.cause`, —
+проходит только через собственную реализацию совместимости пакета.
+
+Сырой ESM проверяет детерминированный гейт синтаксической цели, а текущие Chromium, Firefox и WebKit — отдельный
+smoke на импорт по HTTP. Это не заявление, что в репозитории запускаются исторические сборки браузеров: точная
+сертификация нижней границы требует внешней фермы.

package/dist/abort-compat.d.ts

@@ -0,0 +1,10 @@
+interface CombinedAbortSignal {
+    readonly dispose: () => void;
+    readonly signal: AbortSignal;
+}
+declare function abortWithReason(controller: AbortController, reason: unknown): void;
+declare function compatibleAbortReason(signal: AbortSignal): unknown;
+declare function throwIfSignalAborted(signal: AbortSignal): void;
+declare function combineAbortSignals(signals: readonly AbortSignal[]): CombinedAbortSignal;
+export { abortWithReason, combineAbortSignals, compatibleAbortReason, throwIfSignalAborted };
+export type { CombinedAbortSignal };

package/dist/abort-compat.js

@@ -0,0 +1,2 @@
+const i=new WeakMap;function c(){if(typeof DOMException=="function")return new DOMException("This operation was aborted.","AbortError");const e=new Error("This operation was aborted.");return e.name="AbortError",e}function b(e,r){e.signal.aborted||(r!==void 0&&i.set(e.signal,r),e.abort(r))}function s(e){return i.has(e)?{found:!0,value:i.get(e)}:"reason"in e?{found:!0,value:e.reason}:{found:!1,value:void 0}}function d(e){return s(e).value}function l(e){if(!e.aborted)return;const r=s(e);throw r.found?r.value:c()}function p(e){const r=new AbortController,o=new Map;let a=!0;const u=()=>{if(a){a=!1;for(const[n,t]of o)n.removeEventListener("abort",t);o.clear()}},f=n=>{if(!a)return;const t=s(n);u(),b(r,t.found?t.value:c())};for(const n of e){if(o.has(n))continue;if(n.aborted){f(n);break}const t=()=>f(n);o.set(n,t),n.addEventListener("abort",t,{once:!0})}return Object.freeze({dispose:u,signal:r.signal})}export{b as abortWithReason,p as combineAbortSignals,d as compatibleAbortReason,l as throwIfSignalAborted};
+//# sourceMappingURL=abort-compat.js.map

package/dist/abort-compat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort-compat.js","sources":["../src/abort-compat.ts"],"sourcesContent":["const abortReasons = new WeakMap<AbortSignal, unknown>();\n\ninterface CombinedAbortSignal {\n  readonly dispose: () => void;\n  readonly signal: AbortSignal;\n}\n\ntype AbortReasonRead = { readonly found: boolean; readonly value: unknown };\n\nfunction defaultAbortReason(): unknown {\n  if (typeof DOMException === 'function') return new DOMException('This operation was aborted.', 'AbortError');\n\n  const error = new Error('This operation was aborted.');\n  error.name = 'AbortError';\n\n  return error;\n}\n\nfunction abortWithReason(controller: AbortController, reason: unknown): void {\n  if (controller.signal.aborted) return;\n\n  if (reason !== undefined) abortReasons.set(controller.signal, reason);\n\n  // Older browsers may ignore the argument, so the sidecar remains the canonical fallback. Modern\n  // consumers must still observe the exact reason through the native signal.reason API.\n  controller.abort(reason);\n}\n\nfunction readAbortReason(signal: AbortSignal): AbortReasonRead {\n  if (abortReasons.has(signal)) return { found: true, value: abortReasons.get(signal) };\n\n  if ('reason' in signal) return { found: true, value: signal.reason };\n\n  return { found: false, value: undefined };\n}\n\nfunction compatibleAbortReason(signal: AbortSignal): unknown {\n  return readAbortReason(signal).value;\n}\n\nfunction throwIfSignalAborted(signal: AbortSignal): void {\n  if (!signal.aborted) return;\n\n  const reason = readAbortReason(signal);\n\n  throw reason.found ? reason.value : defaultAbortReason();\n}\n\nfunction combineAbortSignals(signals: readonly AbortSignal[]): CombinedAbortSignal {\n  const controller = new AbortController();\n  const listeners = new Map<AbortSignal, () => void>();\n  let active = true;\n\n  const dispose = (): void => {\n    if (!active) return;\n\n    active = false;\n\n    for (const [signal, listener] of listeners) signal.removeEventListener('abort', listener);\n\n    listeners.clear();\n  };\n  const abortFrom = (source: AbortSignal): void => {\n    if (!active) return;\n\n    const reason = readAbortReason(source);\n    dispose();\n    abortWithReason(controller, reason.found ? reason.value : defaultAbortReason());\n  };\n\n  for (const signal of signals) {\n    if (listeners.has(signal)) continue;\n\n    if (signal.aborted) {\n      abortFrom(signal);\n      break;\n    }\n\n    const listener = (): void => abortFrom(signal);\n    listeners.set(signal, listener);\n    signal.addEventListener('abort', listener, { once: true });\n  }\n\n  return Object.freeze({ dispose, signal: controller.signal });\n}\n\nexport { abortWithReason, combineAbortSignals, compatibleAbortReason, throwIfSignalAborted };\nexport type { CombinedAbortSignal };\n"],"names":["abortReasons","defaultAbortReason","error","abortWithReason","controller","reason","readAbortReason","signal","compatibleAbortReason","throwIfSignalAborted","combineAbortSignals","signals","listeners","active","dispose","listener","abortFrom","source"],"mappings":"AAAA,MAAMA,EAAe,IAAI,QASzB,SAASC,GAAkB,CACzB,GAAI,OAAO,cAAiB,WAAY,OAAO,IAAI,aAAa,8BAA+B,YAAY,EAE3G,MAAMC,EAAQ,IAAI,MAAM,6BAA6B,EACrD,OAAAA,EAAM,KAAO,aAENA,CACT,CAEA,SAASC,EAAgBC,EAA6BC,EAAe,CAC/DD,EAAW,OAAO,UAElBC,IAAW,QAAWL,EAAa,IAAII,EAAW,OAAQC,CAAM,EAIpED,EAAW,MAAMC,CAAM,EACzB,CAEA,SAASC,EAAgBC,EAAmB,CAC1C,OAAIP,EAAa,IAAIO,CAAM,EAAU,CAAE,MAAO,GAAM,MAAOP,EAAa,IAAIO,CAAM,CAAC,EAE/E,WAAYA,EAAe,CAAE,MAAO,GAAM,MAAOA,EAAO,MAAM,EAE3D,CAAE,MAAO,GAAO,MAAO,MAAS,CACzC,CAEA,SAASC,EAAsBD,EAAmB,CAChD,OAAOD,EAAgBC,CAAM,EAAE,KACjC,CAEA,SAASE,EAAqBF,EAAmB,CAC/C,GAAI,CAACA,EAAO,QAAS,OAErB,MAAMF,EAASC,EAAgBC,CAAM,EAErC,MAAMF,EAAO,MAAQA,EAAO,MAAQJ,EAAkB,CACxD,CAEA,SAASS,EAAoBC,EAA+B,CAC1D,MAAMP,EAAa,IAAI,gBACjBQ,EAAY,IAAI,IACtB,IAAIC,EAAS,GAEb,MAAMC,EAAU,IAAW,CACzB,GAAKD,EAEL,CAAAA,EAAS,GAET,SAAW,CAACN,EAAQQ,CAAQ,IAAKH,EAAWL,EAAO,oBAAoB,QAASQ,CAAQ,EAExFH,EAAU,MAAK,EACjB,EACMI,EAAaC,GAA6B,CAC9C,GAAI,CAACJ,EAAQ,OAEb,MAAMR,EAASC,EAAgBW,CAAM,EACrCH,EAAO,EACPX,EAAgBC,EAAYC,EAAO,MAAQA,EAAO,MAAQJ,GAAoB,CAChF,EAEA,UAAWM,KAAUI,EAAS,CAC5B,GAAIC,EAAU,IAAIL,CAAM,EAAG,SAE3B,GAAIA,EAAO,QAAS,CAClBS,EAAUT,CAAM,EAChB,KACF,CAEA,MAAMQ,EAAW,IAAYC,EAAUT,CAAM,EAC7CK,EAAU,IAAIL,EAAQQ,CAAQ,EAC9BR,EAAO,iBAAiB,QAASQ,EAAU,CAAE,KAAM,GAAM,CAC3D,CAEA,OAAO,OAAO,OAAO,CAAE,QAAAD,EAAS,OAAQV,EAAW,OAAQ,CAC7D"}

package/dist/adapter-method.d.ts

@@ -0,0 +1,27 @@
+import type { ExactType, IsAny } from './type-helpers.js';
+/**
+ * Plain dependency methods accept no arguments, one input, or input plus an optional lifetime signal. Both
+ * `ctx.calls` and `own.calls` share this inference (D143); invocation always passes input and signal without
+ * inspecting function arity. A method that ignores its signal still belongs to the owner's lifetime.
+ */
+type AdapterMethodParameters<Arguments extends readonly unknown[]> = Arguments['length'] extends 0 | 1 | 2 ? 2 extends Arguments['length'] ? IsAny<Arguments[0]> extends true ? never : IsAny<Arguments[1]> extends true ? never : ExactType<Exclude<Arguments[1], undefined>, AbortSignal> extends true ? {
+    readonly input: Arguments[0];
+} : never : 1 extends Arguments['length'] ? IsAny<Arguments[0]> extends true ? never : {
+    readonly input: Arguments[0];
+} : {
+    readonly input: void;
+} : never;
+type AdapterMethodSignature<Method> = IsAny<Method> extends true ? never : Method extends (...arguments_: infer Arguments) => infer Result ? IsAny<Awaited<Result>> extends true ? never : AdapterMethodParameters<Arguments> & {
+    readonly output: Awaited<Result>;
+} : never;
+/** Every key of the source whose method matches the call shape; anything else is not selectable. */
+type AdapterMethodKey<Value> = {
+    readonly [Key in keyof Value]-?: Key extends string ? AdapterMethodSignature<Value[Key]> extends never ? never : Key : never;
+}[keyof Value];
+type TupleHasDuplicate<Keys extends readonly PropertyKey[], Seen extends PropertyKey = never> = Keys extends readonly [
+    infer Head extends PropertyKey,
+    ...infer Tail extends readonly PropertyKey[]
+] ? Head extends Seen ? true : TupleHasDuplicate<Tail, Head | Seen> : false;
+/** One key may be selected once: a repeated key would mint two calls under one name. */
+type UniqueExposeKeys<Keys extends readonly PropertyKey[]> = TupleHasDuplicate<Keys> extends true ? never : unknown;
+export type { AdapterMethodKey, AdapterMethodSignature, UniqueExposeKeys };

package/dist/attachment-lifecycle-cleanup.d.ts

@@ -0,0 +1,3 @@
+import type { AttachmentAttempt, AttachmentCleanupOutcome } from './attachment-lifecycle-contract.js';
+declare function runAttachmentCleanup<Key extends object>(ownerId: string, attempt: AttachmentAttempt<Key>): Promise<AttachmentCleanupOutcome>;
+export { runAttachmentCleanup };

package/dist/attachment-lifecycle-cleanup.js

@@ -0,0 +1,2 @@
+import{throwIfSignalAborted as d}from"./abort-compat.js";import{makeCleanupOutcome as f}from"./attachment-lifecycle-helpers.js";import{settleGuardedResult as p}from"./call-target-result.js";async function g(i,n){const t=new AbortController,s=Object.freeze({signal:t.signal}),a=[],c=[];let l=0;for(let r=n.cleanups.length-1;r>=0;r-=1){const e=n.cleanups[r];if(e===void 0)continue;const u=e.cleanup;if(u!==void 0){l+=1;try{const o=u(s);await p(o,{assertCurrent:()=>d(t.signal),signal:t.signal}),e.cleanup=void 0}catch(o){a.push(Object.freeze({error:o,id:e.id,ordinal:l})),c.push(e)}}}return n.cleanups=c.reverse(),f(i,a)}export{g as runAttachmentCleanup};
+//# sourceMappingURL=attachment-lifecycle-cleanup.js.map

package/dist/attachment-lifecycle-cleanup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachment-lifecycle-cleanup.js","sources":["../src/attachment-lifecycle-cleanup.ts"],"sourcesContent":["import { throwIfSignalAborted } from './abort-compat';\nimport type {\n  AttachmentAttempt,\n  AttachmentCleanupFailure,\n  AttachmentCleanupOutcome,\n  OwnedCleanup,\n} from './attachment-lifecycle-contract';\nimport { makeCleanupOutcome } from './attachment-lifecycle-helpers';\nimport { settleGuardedResult } from './call-target';\n\nasync function runAttachmentCleanup<Key extends object>(\n  ownerId: string,\n  attempt: AttachmentAttempt<Key>,\n): Promise<AttachmentCleanupOutcome> {\n  const cleanupAbort = new AbortController();\n  const context = Object.freeze({ signal: cleanupAbort.signal });\n  const failures: AttachmentCleanupFailure[] = [];\n  const retainedInInvocationOrder: OwnedCleanup[] = [];\n  let ordinal = 0;\n\n  for (let index = attempt.cleanups.length - 1; index >= 0; index -= 1) {\n    const ownedCleanup = attempt.cleanups[index];\n\n    if (ownedCleanup === undefined) continue;\n\n    const cleanup = ownedCleanup.cleanup;\n\n    if (cleanup === undefined) continue;\n\n    ordinal += 1;\n\n    try {\n      const result = cleanup(context);\n\n      await settleGuardedResult(result, {\n        assertCurrent: () => throwIfSignalAborted(cleanupAbort.signal),\n        signal: cleanupAbort.signal,\n      });\n      ownedCleanup.cleanup = undefined;\n    } catch (error) {\n      failures.push(Object.freeze({ error, id: ownedCleanup.id, ordinal }));\n      retainedInInvocationOrder.push(ownedCleanup);\n    }\n  }\n\n  attempt.cleanups = retainedInInvocationOrder.reverse();\n\n  return makeCleanupOutcome(ownerId, failures);\n}\n\nexport { runAttachmentCleanup };\n"],"names":["runAttachmentCleanup","ownerId","attempt","cleanupAbort","context","failures","retainedInInvocationOrder","ordinal","index","ownedCleanup","cleanup","result","settleGuardedResult","throwIfSignalAborted","error","makeCleanupOutcome"],"mappings":"8LAUA,eAAeA,EACbC,EACAC,EAA+B,CAE/B,MAAMC,EAAe,IAAI,gBACnBC,EAAU,OAAO,OAAO,CAAE,OAAQD,EAAa,OAAQ,EACvDE,EAAuC,CAAA,EACvCC,EAA4C,CAAA,EAClD,IAAIC,EAAU,EAEd,QAASC,EAAQN,EAAQ,SAAS,OAAS,EAAGM,GAAS,EAAGA,GAAS,EAAG,CACpE,MAAMC,EAAeP,EAAQ,SAASM,CAAK,EAE3C,GAAIC,IAAiB,OAAW,SAEhC,MAAMC,EAAUD,EAAa,QAE7B,GAAIC,IAAY,OAEhB,CAAAH,GAAW,EAEX,GAAI,CACF,MAAMI,EAASD,EAAQN,CAAO,EAE9B,MAAMQ,EAAoBD,EAAQ,CAChC,cAAe,IAAME,EAAqBV,EAAa,MAAM,EAC7D,OAAQA,EAAa,MACtB,CAAA,EACDM,EAAa,QAAU,MACzB,OAASK,EAAO,CACdT,EAAS,KAAK,OAAO,OAAO,CAAE,MAAAS,EAAO,GAAIL,EAAa,GAAI,QAAAF,CAAO,CAAE,CAAC,EACpED,EAA0B,KAAKG,CAAY,CAC7C,EACF,CAEA,OAAAP,EAAQ,SAAWI,EAA0B,QAAO,EAE7CS,EAAmBd,EAASI,CAAQ,CAC7C"}