@opetope/runtime 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# @opetope/runtime
+
+## 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,345 @@
+# `@opetope/runtime`
+
+The runtime with no renderer binding: the feature declaration, the opening of its instance, the lowering of
+attachments and a lifetime graph checked in advance. [The specification](./docs/spec.md) §3 sets the vocabulary of the package; everything not named
+here lives on `@opetope/runtime/internal`.
+
+## Installation
+
+```sh
+npm install @opetope/core @opetope/runtime
+```
+
+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 module
+
+```ts
+import { defineFeature, defineHostContract, openFeature } from '@opetope/runtime';
+
+type Clock = { tick(): PromiseLike<void> | void };
+declare const clockService: Clock;
+
+const clockContract = defineHostContract<Clock>('example.clock.service');
+
+const clockFeature = defineFeature({
+  id: 'example.clock',
+  imports: { service: clockContract },
+  own: ({ attach, call, imports }) => {
+    const clock = attach(imports.service, {
+      open: ({ source, timers }) => timers.interval(1_000, () => source.tick()),
+    });
+    const tick = call({ within: clock, run: (_input: void, { source }) => source.tick() });
+
+    return { clock, tick };
+  },
+  exports: ({ own }) => ({ tick: own.tick }),
+});
+
+const instance = openFeature(clockFeature, {
+  imports: { service: clockService },
+  reporter: error => void error,
+});
+const ready = await instance.ready;
+await instance.close();
+```
+
+`attach` derives the id from the `clock` key and takes the value from an import, so the
+lifecycle is always bound to what the host or another feature gave. The disposer from `timers.interval`
+is closed together with the instance.
+`timers.delay`/`timers.interval` physically cancel a callback that has not started yet and pass the signal of the
+current attachment generation. Cancelling asynchronous work that has already started is cooperative. An interval does
+not wait for the Promise of the previous callback and therefore allows overlap; backpressure and execution policy
+belong to `effect`/`CallLane`, not to the timer.
+A cleanup failure is best-effort `report` by default; the retryable `quarantine` is enabled explicitly only for
+resources that must have a physical release.
+
+The data sugar lives in that same `own` section and is lowered into ordinary attachments:
+
+- `effect({ from, when?, run, onDispose? })` takes an imported `Readable`, runs for the
+  initial snapshot and then latest-wins; the signal, the per-run timers and the returned disposer belong to that
+  exact run;
+- `event(from, subscribe, { run })` gives the `subscribe` context a non-replayed `emit`, serialises the handler and
+  limits the queue to one pending payload; a failure and an overflow go to the application reporter.
+  Retirement aborts the handler, drops the pending payload and drains work already started before the source is released;
+- `resource(from, target, { key, load, retry?, retention? })` watches a
+  `Readable<T | null | undefined>` returned by the target selector:
+  `null` or `undefined` closes the materialization, and a change of `key(target)` fences the old load and opens a new
+  instance. `refresh` keeps stale data only for the same key, `invalidate` clears it, and
+  `retry` repeats a failure that can be repeated, inside the current instance;
+- `stream(from, target, { backpressure, connect, consume?, key, retention? })` applies
+  backpressure before publication and `consume`, fences the emitter of the old generation and physically closes the
+  source before the imported value is released.
+
+`model` gives that same `own` section owned data instead of one more attachment:
+
+- `model(Declaration, create)` needs no dependencies. `model(Declaration, { platform: imports.platform,
+lookup: requires.lookup }, create)` supplies a readonly map of resolved dependencies when the instance opens.
+  Use the map even for one dependency. The factory declares its own dependency interface; it receives ready
+  values, not the feature context or declaration refs. Authentic imports and call refs of the current feature are
+  accepted; optional imports keep their `Readable<Lookup<…>>` projection. Raw services, port declarations, foreign
+  refs and another model ref are rejected (D169).
+
+`ModelContext` is not generic and gives a model its own kernel (D73): `state` creates an `OwnedState`, `update(state, value)`
+is the single writer and accepts only that, `call`, `calls`, `lane`, `effect`, `event`, `resource`, `stream`,
+`scope`, `timers` and `cleanup` open the nodes of the model when the instance opens and close them in its drain; `calls(deps, keys, { lane })`
+is the same selection of methods as `own.calls`, only the source is the ready dependencies of the model (D143); `from` in `resource`/`stream`/`event` is a
+ready dependency value, not an import ref,
+`signal` is aborted on retire, and a write after retire goes to the reporter as a
+`FeatureError` with the code `retired` instead of being thrown at the caller. Owned state lives only in a model: `own`
+has no `state` method, because there would be nobody to write into such state — `ctx.update` accepts only what
+its own context created (D139). The refs of `model()` take no part in the lowering IR: they cannot be exported as a call and
+cannot be used in `within`. A contribution component reads the models of its feature through `useModel` inside the
+contribution mount, which binds them automatically. A single field goes outward through
+`exports: ({ own }) => ({ x: own.model.field })`. A model call can also provide a port:
+`port(SubmitPort, { from: own.order, select: order => order.submit })`. The selector runs once on the materialized
+model before publication; the selected authentic `Call` is fenced by the provider's lifetime even if it passes
+through a dependency call. The direct `port(SubmitPort, own.submit)` form remains for a declared call ref (D169).
+
+`target` is a selector `(source) => Readable<T | null | undefined>` in both feature and model APIs.
+TypeScript infers the payload of the returned `Readable`, whose shape is checked before opening; a scalar
+snapshot or property-name string is not accepted. `null` and `undefined` close the materialization.
+`retention` is optional in both APIs; `scoped({ capacity })` uses LRU eviction with no additional option.
+
+Both APIs publish one atomic snapshot `idle | opening | ready | refreshing | error` with the
+`key`, the generation, the attempt, the stale data and the failure. `subscribe` only observes and activates no
+work; demand is set by a separate `retain()` lease. Retention by default merges the StrictMode
+release/reacquire into one microtask and aborts unfinished work after the last lease. An explicit
+`scoped({ capacity })` holds the materialization until retirement and bounds the sticky
+cache. The UI of a feature gets an instance-bound facade through `bindFeatureResource(instance, own.x)`,
+and the React `useResource` holds one lease per mounted consumer.
+
+There are exactly two policies, and both have a production pilot: `scoped({ capacity })` for retention and
+`latest()` for stream backpressure. The former `drop`, `sample` and `queue` are removed together with their branches:
+they could not be named from the author vocabulary, so they measured only themselves (D160).
+
+## Calls and lanes
+
+`call(options)` declares a command; `invoke(target, input)` executes one. In a feature or model `run`, use
+`run: (input, { invoke }) => invoke(target, input)` or `context.invoke(target, input)`. Trusted attachment steps
+use the same name on their execution `context`. There is no execution `call` alias (D243).
+
+`call({ within, run })` creates an instance call with a private FIFO lane by default. Several
+calls can be serialised by one `lane({ within })`; a lane cannot be moved to another attachment.
+A nested `context.invoke(localRef, input)` on the same lane runs without a self-deadlock, while cycles across
+several lanes and a recursive single flight end with a diagnostic error.
+
+`policy: 'parallel'` is always explicit. `singleFlight: fn` merges only equal keys:
+cancelling one caller does not cancel the others, and the departure of the last one aborts the physical run. A successful
+`once: true | fn` lives exactly one instance; a failure is not cached. `policy: 'latest'` replaces an input still
+waiting at the end of the lane, preserving a running body and the order across other Calls (D185). Retirement first
+fences the settlement and releases the lane, then
+waits for the physical drain before the attachment is cleaned up.
+
+`calls(imports.host, keys)` selects host methods; `calls(imports.feature, keys)` selects exported calls from a
+hard feature import with the same inferred inputs and outputs. For an optional feature import it creates calls
+that resolve the current provider at invocation and fail with `unavailable` while it is missing (D187). The import
+itself remains a lookup; `fromOptional` from Core selects its data with an explicit missing value.
+
+Host methods selected by `calls` may take no parameters, one input, or an input followed by `AbortSignal`;
+optional input/signal are supported. No parameters means `Call<void, Awaited<Output>>`. Methods keep their receiver and
+receive `(input, signal)` uniformly; the runtime never reads `Function.length` or guesses where a client expects
+options. For `client.load(input, { signal })`, provide the ordinary adapter
+`load: (input: Input, signal: AbortSignal) => client.load(input, { signal })`. A lone parameter named `signal`
+is an input; inject cancellation into a signal-only method explicitly in `call({ run })` (D244).
+
+A command's body receives its own execution signal and a nested `invoke` inherits cancellation and the lane stack.
+`Resource.load` and `Stream.connect`/`consume` receive the current target execution's signal: changing that target,
+refreshing or releasing the resource can abort work while the model stays alive. `ModelContext.signal` belongs to
+the entire model. Logical cancellation does not stop a method that ignores its signal or undo its writes; physical
+drain waits for admitted work. Plain setters and methods without I/O need no dummy `_signal` (D244).
+
+`instance.close()` fences synchronously and returns one shared completion promise. A failed cleanup may produce a
+`FeatureError` with `code: 'quarantined'` and an optional `retryCleanup` capability. Check that capability before
+calling it; ordinary errors have no retry function. `Resource.retry()` and feature-demand retry remain separate
+operations. The internal lifecycle name and cancellation code `retired` stay unchanged (D168).
+
+## Lazy feature bodies
+
+A lightweight header declares topology through `id`, `when`, `imports`, `requires` and `provides` metadata, plus
+`body: () => import('./feature.body')`. Its body uses `defineFeature.body(header, { own, exports, provides })`;
+`FeatureBody<Exports>` names the loader result without a circular dependency, and `FeatureBodyOf<Header>` types
+the body input from the header's imports, requirements and exports. `defineFeature.preload(header)` fetches code without opening an instance (D186, D207, D208).
+
+Eager and lazy `openFeature` validate and snapshot options, imports and requirements immediately. A loader throw
+rejects `ready` or `preload`. Each definition shares its code load, while each instance has its own lifetime:
+closing before code arrives rejects that instance's readiness as `retired` and completes without waiting for the
+shared load. Other instances and preloads still use it; late success cannot reopen the closed instance and failed
+loads may be retried. Once materialization starts, close drains the work already owned, including a reentrant
+close from a model factory; synchronous fencing, a shared close promise and quarantine recovery match eager
+instances (D211).
+
+## Dynamic scopes
+
+`scope.while`, `scope.switch` and `scope.keyed` drive a child generation from an imported
+`Readable`; the `open(value, { signal, timers })` callback returns a disposer or `void`. They compile the
+child into the same lifetime IR as an ordinary `attach`, and the controller only translates changes of the
+source into an opening and a retire of the scope that already exists.
+
+```ts
+own: ({ imports, scope }) => ({
+  authorized: scope.while({
+    from: imports.authorized,
+    open: (_authorized, { signal }) => connection.open(signal),
+  }),
+  selected: scope.switch({
+    from: imports.selected,
+    key: item => item.id,
+    open: (item, { signal }) => repository.open(item.id, signal),
+  }),
+  rows: scope.keyed({
+    from: imports.rows,
+    key: row => row.id,
+    open: (row, { signal }) => cache.retain(row.id, signal),
+  }),
+}),
+```
+
+`while` without `when` uses truthiness. `switch` treats `null`/`undefined` as the closed state,
+closes the old generation before the new one and on `A → B → C` opens only the current `C`; an equal
+explicit `key` keeps the current generation. `keyed` holds an independent child generation per
+unique `string | number` key. A repeated key rejects the whole new snapshot before any change to the children that are
+already active. Retire fences the children synchronously and waits for their physical drain.
+
+The `provides` section declares both ports and contributions: `port` binds a call ref to a `Port`, while `slot`, `pipe` and
+`register` declare a contribution by the kind of its target:
+
+```ts
+import { definePipe } from '@opetope/core';
+import { defineFeature } from '@opetope/runtime';
+
+const titlePipe = definePipe<string>({ id: 'example.title' });
+const titleFeature = defineFeature({
+  id: 'example.title-contributor',
+  provides: ({ pipe }) => ({
+    suffix: pipe(titlePipe, { fold: title => `${title} · ready` }, { priority: 20 }),
+  }),
+});
+```
+
+The outer factory is synchronous and runs at `defineFeature`, so the target/id/priority are available
+to the application compiler before an instance opens. The second argument of `pipe(...)` is a `{ fold }` descriptor:
+the runtime binds it to the concrete instance after the critical barrier and calls the handler only on a fold (D223).
+`slot` and `register` take either a value factory with a concrete `FeatureOpenContext`, which also runs only after
+that barrier, or a ready contribution value. An exact plain record must
+return every receipt exactly once; the id of an entry is derived as `featureId.key`. The whole batch goes through
+preflight and is published atomically. The start of retirement removes the entries synchronously before the async cleanup, including
+a reentrant retirement from a target listener; a failed opening or an error in the value factory leaves no partially
+published contributions.
+
+The feature API is declared by the `exports: ({ own }) => ({ … })` section: the contract is created from the feature
+definition under the id `<feature>.exports`, and a consumer imports the definition itself — `imports: { provider: providerFeature }`.
+Assigned missing/extra keys and incompatible `Call` signatures are rejected at compile time. Host-only values
+use `defineHostContract<T>()`. `context.invoke`
+accepts a local call of the same feature or a target from the imports of the current instance; a foreign local ref and a
+target captured outside the declared imports are rejected by the runtime fence.
+
+`onDemand(hostContract)` records a deferred connection in the import declaration for the compiled topology. The host
+value keeps the same contract-derived type, and `attach(imports.x)` is lowered into the same lifecycle IR as
+`attach(imports.x, { open: () => undefined })`; the wrapper accepts only one direct authentic host contract, allows no
+re-wrapping and does not wrap a feature edge.
+
+`optional(x)` in `imports` and `optional(port)` in `requires` are a weak edge: a consumer may outlive its
+provider, so the value arrives as a `Readable<Lookup<…>>` projection, and a call to a weak port with no live provider
+settles as a `CallError` with the code `unavailable`. This is an error, not a cancellation: `isCancellation` is false for it, and
+`useCommand` returns the `failed` outcome with that error in `lastError` (D138).
+
+## Word map
+
+One page of the package vocabulary: RFC §3 sets the names, the README explains what each one is for.
+
+| Word                                                                                                                                              | What for                                                          |
+| ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| `defineFeature`, `Feature`, `FeatureBody`, `FeatureBodyOf`                                                                                        | the feature declaration; only `id` is required                    |
+| sections `imports`, `requires`, `own`, `exports`, `provides`, `when`                                                                              | what I am given, what I need, what I own and when I live          |
+| `defineHostContract`, `HostContract`, `onDemand`                                                                                                  | the boundary with the host and a deferred connection              |
+| `optional` (its projection uses `Lookup` from `@opetope/core`)                                                                                    | a weak edge: a projection instead of a value                      |
+| `attach`, `calls`, `call`, `lane`, `effect`, `event`, `model`, `resource`, `stream`, `scope.while`, `scope.switch`, `scope.keyed`                 | the methods of `own`: what a feature owns                         |
+| `port`, `slot`, `pipe`, `register`                                                                                                                | the methods of `provides`: what a feature offers extension points |
+| `openFeature`, `FeatureInstance`                                                                                                                  | one opening of a feature: `ready`, `close`                        |
+| `scoped`, `latest`, `ScopedRetention`, `LatestBackpressure`, `Resource`, `ResourceSnapshot`                                                       | retention policies and the snapshot of a resource                 |
+| `defineApplication`, `Application`, `defineCondition`, `Condition`, `bind`, `openApplication`, `ApplicationExecution`, `ApplicationImportBinding` | the static topology, the conditions and the shared lifetime       |
+| `ErrorReporter`, `CleanupFailurePolicy`                                                                                                           | where a failure goes and what to do with a failed cleanup         |
+| `FeatureError` with the codes `not-ready`, `quarantined`, `cleanup-failed`, `retired`; `ApplicationError` with the code `closed`                  | one class per subject, the state in the `code` field              |
+
+`defineModule`, `instantiateModule` and the whole `Module*`, `Call*`, `Attachment*` family live only in
+`@opetope/runtime/internal`: this is the ABI for framework implementation and host integration, not the vocabulary of a feature author.
+
+`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.
+
+An eager `defineFeature` is lowered into an immutable reusable `defineModule`; a lazy header defers implementation
+lowering to `defineFeature.body`. `openFeature` creates an
+isolated generation with an exact map of scopes, synchronous UI preparation, rollback, single-flight
+retirement and quarantine retry. The advanced `defineModule`/`instantiateModule` stay available for
+framework lowering, but are not the typical feature-authoring path.
+`instance.ready` and `close()` are a throwing convenience facade with typed errors.
+Detailed outcome unions are not wrapped in `.orThrow()`: they stay on the advanced path
+`instantiateModule` → `scope.open`/`retirement.drain`, so that no second lifecycle API appears.
+
+Consumer size scenarios are built from `size/**`, and the limits in `package.json` serve as coarse regression guards
+with headroom, not as ratchets to the current byte. The preserve-modules inventory is deliberately not summed per
+file: such a count grows from an architectural split without any growth of the consumer bundle. Validate the host's
+initial and asynchronous chunks against its own budgets, and measure startup and retained heap on the application
+workload. Package size checks alone do not establish application performance.
+
+Static scope/attachment/call refs are available through `definition.own`; the raw target, the compiler IR
+and the lifetime controller are not published. The exact value of a scope generation is passed into `open`, `close` and an
+attachment-bound `call`, so one definition safely creates several instances with no shared
+closure state.
+
+The first `scope.open` seals the assembly. Module retirement synchronously fences the registered
+renderer participants and every active scope, after which `drain` returns a single typed outcome.
+`retry` walks only the quarantined frontier; workspace retirement handles stay idempotent.
+The normal cancellation of a generation is represented by a `FeatureError` with the code `retired`; framework adapters use
+`isCancellation`, while ordinary UI gets a `CommandOutcome` from `useCommand`. Call cancellation is the codes
+`cancelled` and `closed`; `unavailable` and `publication-rejected` reach the product as an error.
+An attachment callback must not call `drain`/`retry` of its own scope generation:
+a synchronous self-wait is rejected before cleanup starts. A self-wait after an `await` of its own stays a
+violation of the callback contract — without an async context token it cannot be told apart from a legitimate external
+join, so the runtime keeps the single flight for external callers.
+`call` infers the input, the output and the scope value from the callback and `within`; where necessary an author
+annotates the `input` parameter. The partial form `call<Input, Output>(...)` is deliberately not an API: after an
+explicit prefix TypeScript will not infer the hidden owner value without `any`.
+
+The owner generation controller, the low-level compiler, lifetime binding, call target resolution and
+retire receipts stay on `@opetope/runtime/internal`, not in the author vocabulary. The dependency direction is
+one-way: the runtime uses `@opetope/core/internal`, and the core never imports the runtime.
+
+The lowering layer gives immutable templates and independent instances: it computes the critical barrier, starts
+deferred attachments only after the owner commits, keeps causal failures observable and returns
+stable attachment identities in the outcomes of a failed opening and drain.
+
+The attachments of one scope form a single wave, not a graph: there is no order between them either on opening or on
+closing (D163). Critical attachments start before the owner commits, deferred ones after `ready`. Retire
+first fences the whole live set, then drains it entirely; a failed attachment lands in the quarantine
+frontier in the canonical order of slots, the rest are closed, and `retry` repeats exactly the failed ones.
+
+A rolled-back quarantined opening recovers only through the private `retry` of the owner. A successful
+recovery removes the dead child from the live set; the raw `retry` of the core is part of neither the lowering nor the
+author vocabulary. A replacement child counts as proof that the old one is closed only after a settled `ready`
+from the core.
+
+While an instance is opening, its generation is not yet the current call authority: the lowering commits it
+only after a successful critical barrier, and retire invalidates the generation before the parent and the children are notified.
+The parent signal and the attachment signal form a single execution fence for steps and calls, while closing and cleanup hold
+a separate release authority.
+
+Opaque call receipts are returned under canonical runtime keys and compiled into frozen
+bindings with no behaviour. A call can be bound only to a critical attachment; the physical target becomes current
+only after the whole critical barrier of the owner commits and is fenced by retire before the children are cleaned up. The runtime mints
+one direct target per binding and instance, and one transaction owns the publication of contributions into React.
+
+The runtime has no temporary author entry: call target resolution, renderer participant registration and
+the owner controllers stay an internal ABI on `@opetope/runtime/internal`.
+
+## Compatibility contract
+
+The runtime publishes ESM for Chrome 82+, Firefox 110+, Safari/iOS 15+, Android 82+ and Node 20.19+.
+The required globals and the compatibility implementations belong to `@opetope/core`; the runtime installs no polyfills.
+The raw dist passes the same syntax-target gate and the same HTTP import smoke test as the core.