@earendil-works/chord 1.4.0 → 1.5.1

package/docs/plugin-authoring.md

@@ -0,0 +1,276 @@
+# Writing a Chord plugin
+
+For agents and people writing plugins for an app built on Chord v2. Self-contained: everything a plugin author needs
+is here. In the examples the app is "Acme", its API package `@acme/app`; replace it with your app's (its docs name the
+package and the versions it provides).
+
+## What a plugin is
+
+A plugin is a feature of a running app: it serves objects (state plus methods) and contributes to the app's
+registries (routes, panels, tools). The app loads it on its hosts (the server, its workers, browser pages, terminal
+clients), reloads it when it is edited, and leaves it out alone when it is broken. Plugins talk to each other only
+through object contracts and registries.
+
+## Layout
+
+A **directory plugin**, in one of the app's plugin roots:
+
+```text
+plugins/stats/
+  package.json          { "name": "@bob/stats", "dependencies": { ... } }      required; the name is the plugin's
+  server.ts             the server facet           one file per host kind the app has, each optional:
+  worker.ts             the worker facet           <kind>.ts, .tsx, .js or .mjs; default export: a facet
+  web.tsx               the web (page) facet
+  tui.ts                the terminal client facet
+  contract.ts           contracts every kind may import (data only)
+  contract.web.tsx      contracts and tokens for web facets only (`contract.<kind>.ts(x)` per kind)
+  *.ts, *.css, assets/  plain files of the plugin
+```
+
+- `package.json`: `name` (an npm package name, scoped or not) is the plugin's name; `dependencies` are bundled into
+  its scripts; `"chord": { "external": ["better-sqlite3"] }` keeps named packages external in Node facets (native
+  addons).
+- A **package of several plugins** (a repository holding them) lists their folders in its own `package.json`:
+  `"chord": { "plugins": ["./notes", "plugins/*", "!plugins/draft"] }` (paths, globs and `!` exclusions; `.` is the
+  package itself; a listed folder inside another listed one is refused). Without the field, the package is one plugin
+  when its top has facet files, else **every** subfolder with a `package.json` is a plugin: a repository with nested
+  packages that are no plugins (a helper library, examples, fixtures) must list its plugins in `chord.plugins`.
+- A plugin with no facet file holds contracts others import.
+- A **single-file plugin** is a file at a root's top named `<name>.<kind>.ts` (or `.tsx`, `.js`, `.mjs`):
+  `hello.server.ts` and `hello.web.tsx` are the plugin `hello` with two facets. No `package.json`, so no
+  dependencies; it imports only the app's API and defines its contracts inline. When it needs more, make it the
+  directory `hello/` with a `package.json` named `hello`: the app treats it as the same plugin.
+
+## A facet
+
+```ts
+// plugins/stats/worker.ts
+import { defineFacet, int, local, str } from "@acme/app/v3";
+import { Indexers } from "@acme/app/v3/worker";
+import { Notes } from "../notes/contract.ts";
+
+const Stats = local("bob.stats", { version: 1, params: { project: str() }, members: { words: int() } });
+
+export default defineFacet((host, self) => {
+	self.contribute(Indexers, { name: "word count" });                 // a registry entry while the plugin is loaded
+	host.serve(Stats, ({ project }, self) => {                          // a factory, run per object
+		const notes = self.get(Notes, { project });                      // a dependency: Stats waits until Notes is live
+		return { words: self.derive([notes.text], ([text]) => text.split(/\s+/).filter(Boolean).length) };
+	});
+});
+```
+
+A facet only declares (`host.serve`, `self.contribute`, `host.references`), synchronously. Everything at runtime
+happens in objects: state in documents and tables, standing behaviour in a `local` object with empty params (it lives
+as long as the host). Names are prefixed by the plugin (`bob.stats`).
+
+## Tables shown live
+
+A table has no watch. To show its rows live, the object owning it declares a live query with a limit:
+
+```ts
+host.serve(Store, (_params, self) => {                 // a local type with empty params: it may have tables
+	const items = self.table(Items);
+	const newest = self.query(items, query(Items).orderBy((i) => i.id, "desc"), 50);
+	return { items: newest, add: async (row, ctx) => self.tx(async (tx) => tx.put(items, row), ctx) };
+});
+```
+
+- Chord runs it before the object goes live and again in each commit of the object that writes the table; watchers get
+  only what changed. A commit writing no such table runs nothing.
+- Only the object's own tables, the query fixed for the object's attempt (decide it from params), the limit required
+  (`invalid/args` without one).
+- One query per writing commit, at most `limit` rows (for 100 rows about 60 µs more per commit, 80 µs when watched;
+  `benchmarks.md`): there may be dragons for a table written hundreds of times a second. Keep a document for those.
+- Never read a table in `self.open` to fill a window: a live query reruns by itself after every commit and at a
+  reload's restart; a read in `self.open` is a one-time snapshot.
+
+## What a plugin may import
+
+| Import | Resolves to |
+| --- | --- |
+| its own files (`./label.ts`, `./icon.svg?url` in web facets) | inlined into its script |
+| the app's API, a version in the path: `@acme/app/v3`, its kind's module `@acme/app/v3/worker` | the app's own instance (a host package), never copied |
+| another plugin of the same root (one repository): `../notes/contract.ts` | inlined (a copy, frozen at this build) |
+| a package in `dependencies`: `@bob/notes`, `@bob/notes/web` | inlined from `node_modules` at the installed version, through the package's `exports` |
+| a plugin inside a dependency on a whole repository of several: `@bob/plugins/notes/contract.ts` | inlined, as any package file |
+| a `chord.external` package, a Node builtin (Node facets) | loaded when the script runs |
+| `pluginFile` from `@earendil-works/chord/plugins` | the absolute path of a file of this plugin |
+
+Refused at build, each with the file, line and rule:
+
+- `@acme/app/v1` when the app does not list v1 ("@acme/app/v1 is not available: this app provides v3, v2");
+  another kind's module (`@acme/app/v3/web` from a worker facet); two API versions in one facet.
+- Chord itself (`@earendil-works/chord`): the app's API re-exports what plugins may use.
+- A relative path leaving the plugin's root (base code, another root); a file of a directory that is no plugin.
+- A file copied from another plugin importing anything but the API and its own plugin's files.
+- A per-kind file (`contract.web.tsx`, `contract.Web.ts` alike) or another kind's facet file (`web.tsx`) reached from
+  a facet of another kind, directly or through other files (the error names the chain). Files inside npm packages are
+  checked only when the package is plugin code (its `package.json`, or one above it in the package, has a `chord`
+  field); ordinary libraries name files as they like (`pdf.worker.mjs`).
+- A package file whose real path is outside the plugin's own `node_modules` (a `file:` dependency linked elsewhere, a
+  package importing `../src`).
+- A copied file importing a Node builtin or a package.
+- A package not in `dependencies`; `import.meta`, `__dirname`, `__filename`, a literal `import("x")`, top-level
+  `await` (read files through `pluginFile`).
+- In a single-file plugin, anything but host packages.
+
+Contract files mention native things (React components, functions) only through `import type`; at runtime they import
+only the API and the plugin's own data-only files.
+
+## An app's API is a package
+
+The app's API is a workspace package of the app's repository: a `package.json` named `@acme/app` with an `exports`
+entry per module, listed in the repository root's `workspaces`, so `npm install` links it into `node_modules`:
+
+```json
+{
+	"name": "@acme/app",
+	"private": true,
+	"type": "module",
+	"exports": {
+		"./v3": "./src/api/v3/index.ts",
+		"./v3/web": "./src/api/v3/web.ts",
+		"./v3/worker": "./src/api/v3/worker.ts"
+	}
+}
+```
+
+Plugins, tests and tools resolve it alike: a facet imports `@acme/app/v3`, and so do the app's base code, a test, and
+a plugin's `contract.ts` that a test or a script imports. In a plugin's build it stays a host package (left out of the
+script, the process's own instance passed in when the script is evaluated).
+
+## Errors
+
+Throw Chord's own errors where Chord's built-in checks would, from the API (it re-exports them):
+`invalid("args", "a note needs a title")` for arguments a method refuses (`"params"` for params a factory refuses),
+`forbidden("viewers only")` for a principal a factory or method refuses. The caller gets the same
+`{ code: "invalid", reason: "args" }` or `{ code: "forbidden" }` across every link. For codes of the plugin's own throw
+`new PluginError(code, message, details)`. Only the code, reason, message and JSON details cross a link, never a stack
+or a cause.
+
+## Contracts and versions
+
+A plugin carries the contract it was written against. Plugins changing together (one root, one repository) import
+each other's contract files by relative path. A plugin from another repository takes the contracts as a dependency
+pinned to a version: an npm version, or a git ref (`"@bob/notes": "github:bob/notes#<commit>"`, `"git+https://...#v2"`).
+The app's own contracts for third parties come with its API (`@acme/app/v3` exports `Notes`). When a contract
+changes shape, bump its `version`; the provider serves older consumers through `accepts`, else they wait "contract
+mismatch" (visible, never wrong data).
+
+## Reloads
+
+A reload of the plugin restarts each of its live objects. The calls running at that moment, and every call they make
+with their `ctx`, finish on the old code; new calls wait for the new code; documents and tables stay. Two rules keep
+that working: a root opened inside a method takes the method's `ctx` (`host.root(fn, withoutAbortSignal(ctx))`), so its
+calls count as the method's; and work longer than a few seconds is a job, since a call still running at
+`reloadDrainTimeout` (5 s) is cut `released`.
+
+## How the app builds it
+
+The server builds each facet with one esbuild call from source: TypeScript and TSX (JSX with the automatic React
+runtime), JS, JSON, CSS (web facets: one stylesheet per facet), assets and WASM by URL (`import url from "./x.svg?url"`).
+No type check, no build hooks, no `dist` needed; generated files are committed. The script is evaluated in each
+process of its kind with that process's API modules. A failed build or evaluation leaves the plugin out (at startup)
+or keeps its old code (at a reload), reported with the error.
+
+## Styles, themes and state across reloads (web and terminal facets)
+
+- A web facet's CSS is served with its script and swapped when the plugin reloads. Scope it with a **CSS module**: a
+  file named `*.module.css` has its class names made unique to the plugin and the file, and its import is the mapping
+  (`import styles from "./notes.module.css"; <div className={styles.card}>`). Plain CSS files still work; their class
+  names should then start with the plugin's name.
+- Read the app's look from its CSS variables (`var(--accent)`, `var(--bg)`, `var(--fg)`, `var(--muted)`, `var(--error)`,
+  `var(--warning)`, `var(--success)`, and the app's own roles), never fixed colours: the active theme sets them.
+- In a terminal facet, ask the app's theme lookup for a role (`theme.fg("accent", "Notes")`); never write raw colours.
+- A reload of the plugin remounts its components (each is a new function): their `useState` starts over. Keep what
+  must survive an update (a half-typed message, a scroll position) in page state, kept by the page's host under a key
+  prefixed with the plugin's name: `usePageState("stats.draft", "")` instead of `useState("")` (from the app's web
+  API); in a terminal facet `scope.pageState("stats.draft", "")` on the `TuiScope` it was given. Any value, never sent
+  anywhere, gone with the page.
+- A theme is data: contribute a `Theme` (`{ id, name, mode, colors, web?, tui? }`) to the kit's `Themes` registry,
+  from a web facet and a terminal facet to reach both. Users pick one dark and one light theme.
+
+## Messages
+
+Text people read is written once, in code, and rendered in each viewer's language (design §23, "Messages and
+languages"). From the app's API:
+
+```ts
+// plugins/stats/messages.ts: imported by every facet that renders, and by the worker when it builds messages as data
+export const messages = defineMessages("bob.stats", {
+	en: { title: "Stats", words: (n: number) => (n === 1 ? "1 word" : `${formatNumber(n)} words`), done: (by: string) => `${by} finished` },
+	de: { title: "Statistik", words: (n) => (n === 1 ? "1 Wort" : `${formatNumber(n)} Wörter`), done: (by) => `${by} ist fertig` },
+});
+```
+
+- The namespace is the plugin's name; keys are names (`title`), never English text; the English catalog comes first and
+  annotates its functions' parameters, the others take them from it. A missing key, an unknown one or a wrong argument
+  is a type error. Plurals and word order are functions; dates, times and numbers go through `formatTime` and
+  `formatNumber` inside them (they follow the language being rendered).
+- Every facet that renders contributes the plugin's own catalogs: `self.contribute(Translations, messages.translations)`
+  (registries are per host; the host learns the languages offered from them).
+- Render in the host's language: `const { t } = useMessages(messages)` in a component, `const t =
+  scope.messages(messages)` in a terminal facet. The plain `messages(key, ...)` has no language of its own (outside a
+  render: the first catalog); never use it in UI code.
+- Objects never store sentences: a member typed `union([MessageSchema, nul()])` holds `messages.message("done", by)`
+  (keys whose arguments are strings, numbers, booleans or `null`; a date as an ISO string), and each client renders it
+  with `t.render(message)`, which shows the key of a message it does not know.
+- A translation is a plugin: its catalogs typed `MessagesOf<typeof messages>` (a type-only import of the other plugin's
+  `messages.ts`), partial allowed, in one shared file contributed as a list from each facet that renders:
+  `self.contribute(Translations, [{ namespace: "bob.stats", locale: "fr", messages: statsFr }])`; `override: true`
+  replaces the plugin's own catalog of that locale.
+- Never translated: the model's prompts and answers, log lines, error codes.
+
+## Installing
+
+- `plugins.installPlugin({ git: "https://github.com/bob/stats.git", ref: "v1.2.0" }, root, ctx)`: a shallow clone of
+  the branch, tag or commit into `<root>/stats`; its plugins are the folders its `chord.plugins` lists, else by
+  convention. `{ npm: "@bob/stats", version: "1.2.0" }`: the package extracted into `<root>/@bob/stats`. Then their
+  dependencies are installed (`npm install --omit=dev --ignore-scripts`; no lifecycle scripts run). Refused: a plugin
+  name the app has already, an existing directory, a ref or name starting with `-`.
+- Removing is deleting the directory. To update, install another ref (a new directory) or delete and install again.
+
+## Testing a plugin alone
+
+```ts
+import { testPlugin } from "@earendil-works/chord/plugins";
+import * as apiV3 from "@acme/app/v3";
+import * as apiV3Worker from "@acme/app/v3/worker";
+
+const Notes = apiV3.local("acme.notes", { version: 1, params: { project: apiV3.str() }, members: { text: apiV3.str() } });
+const Stats = apiV3.local("bob.stats", { version: 1, params: { project: apiV3.str() }, members: { words: apiV3.int() } });
+const notesStub = apiV3.defineFacet((host) => host.serve(Notes, () => ({ text: apiV3.constant("a b c") })));
+
+const t = await testPlugin("./plugins/stats", {
+	kind: "worker",
+	kinds: ["server", "worker", "web"],                                  // the app's kinds (by default: those its files name)
+	api: { name: "@acme/app", versions: ["v3"] },
+	modules: { "@acme/app/v3": apiV3, "@acme/app/v3/worker": apiV3Worker },   // the real API modules
+	stubs: [{ name: "@acme/notes", facet: notesStub }],                   // facets serving what it uses
+	principal: { kind: "worker", project: "p1" },                          // the host's principal (optional)
+}, ctx);
+const stats = await t.host.get(Stats, { project: "p1" }, ctx);           // stats.words.value: 3
+t.contributions(apiV3Worker.Indexers);   // its entries in a registry nobody serves (the helper collects them)
+t.unserved();                            // contracts its requests wait for: stub these
+await t.root(async (ctx) => ..., ctx, { principal: { kind: "user", id: "u1" } });
+await t.close(ctx);
+```
+
+The plugin is built as production builds it and loaded on an in-memory host (a `:memory:` store). Stubs are ordinary
+facets with fake data. A test imports the API by its package name and the plugin's own contracts from its
+`contract.ts` (the build bundles its own copy; contracts are data: the same name, version and schema bind); contracts
+of plugins it has no files of, it declares again, as `Notes` above.
+
+## Checklist
+
+1. `package.json` with a valid name (or a single file `<name>.<kind>.ts`).
+2. One facet file per kind it runs on; each default-exports `defineFacet(...)`.
+3. Imports: the app's API at one version, own files, same-root contract files by relative path, other repositories'
+   by package name pinned in `dependencies`.
+4. Contracts prefixed with the plugin's name; a version bump for every change of shape.
+5. Live rows of a table through `self.query(table, q, limit)`, never a read in `self.open`.
+6. Files of one kind named `*.<kind>.ts(x)`.
+7. A test with `testPlugin` and stubs for every name `t.unserved()` lists.
+8. Texts people read in `messages.ts` (`defineMessages`), its catalogs contributed from each facet that renders, state
+   holding messages as data.

package/docs/plugin-model/book.md

@@ -0,0 +1,186 @@
+---
+title: The Plugin Model: what a plugin is, what it may import, and how versions meet
+cover: The Plugin / Model
+kicker: A design proposal · Chord v2 · 2026-10-31
+subtitle: Plugins, base code, versioned APIs and contracts, in one place, as discussed with the owner on 2026-10-31
+stats:
+  - 4 | kinds of import a plugin may write
+  - 1 | integer per API version, in the import path
+  - 0 | package.json fields Chord reads besides name and dependencies
+  - 0 | type checks in the build
+note: |
+  A proposal written by the redesign session after a day of discussion with the owner. It collects what was decided
+  and what is proposed into one model. Decided points cite their decision in `decisions.md`; proposed ones are marked.
+  Nothing here is built yet beyond slices 7c and 10.
+colophon: The Plugin Model · proposal · 2026-10-31
+---
+
+# Before we begin {.preface}
+
+An app built on Chord is mostly plugins. Its own features are plugins, users add plugins, and agents write plugins
+while the app runs. A plugin uses the app (where things live, who calls, how to declare objects), uses other plugins
+(their objects and extension points), and uses npm packages. Each of those can change on its own schedule: the app
+gets a new version, a plugin it depends on changes its contract, a package publishes a fix.
+
+The questions the owner kept asking were all versions of one: when a plugin is written against one state of the world
+and runs against another, what does it get, and who notices a mismatch? This model answers it with one rule for each
+kind of import, and versions that sit where the dependency is written: in the code.
+
+## Eight things to know
+
+:::findings
+1. **A plugin is a directory, or a single file.** A directory has a `package.json` (its name, its npm dependencies)
+   and one file per host kind; a single file `hello.worker.ts` is a plugin named `hello` with no dependencies.
+2. **Base code is internal unless it is an API.** The app exposes only versioned API modules to plugins; everything
+   else is unreachable.
+3. **API versions are in the import path.** `import { Session } from "@acme/app/v3"`: the plugin says what it was
+   written for where it imports it; an unavailable version is a build error.
+4. **APIs are split by host kind.** A shared module holds what every host may use (contracts, registry tokens, host
+   kinds); `/v3/web` and `/v3/tui` hold UI pieces; a worker never loads React.
+5. **Contracts carry their own versions.** A plugin carries the contract version it was written for; the provider
+   binds it if it accepts that version, else the plugin waits with a clear reason.
+6. **A plugin imports four things:** its own files, host packages, its npm dependencies, and the app's own plugins by
+   relative path. Nothing else.
+7. **Settings are arguments, extensions are registries.** What the app decides at startup is passed to its components;
+   what plugins add is contributed.
+8. **No type checking in the build.** Types come from where imports come from; editors and agents check, the build
+   only builds.
+:::
+
+## Words used throughout
+
+**Base code** is the app's own program; its **API** is the part plugins may import, published as **API modules**,
+one per version and host kind. A **host package** is a module the running process provides to every plugin (Chord,
+the app's API modules). A **contract** is an object type's declaration; a **registry token** an extension point's.
+A **facet** is a plugin's declarations for one host kind.
+
+# What a Plugin Is {#plugin lede="A directory or a single file, named once, with one file per host kind."}
+
+```text
+plugins/notes/                     a directory plugin
+  package.json                     { "name": "@acme/notes", "dependencies": { "slugify": "1.6.6" } }
+  contract.ts                      the object types and registry tokens it offers
+  worker.ts  server.ts  web.tsx    one facet per host kind it needs
+plugins/hello.worker.ts            a single-file plugin "hello" with one worker facet
+plugins/hello.web.tsx              the same plugin's web facet
+```
+
+A directory plugin's name is its `package.json` name; Chord reads only `name` and `dependencies` from it. A
+single-file plugin's name is its file's base name; it has no dependencies and imports only host packages. When a
+single file needs a package or a second file, it becomes a directory. Two roots with the same name: the first root
+wins, the other is reported (slice 7c).
+
+# Base Code: Internal and External {#base lede="What the app keeps to itself, what it exposes, and how exposure is versioned."}
+
+The app's base code is everything that starts the process: settings, startup, core objects' implementations, the
+session index, migrations. Plugins must not depend on any of it, or every refactoring of the app would break them.
+So the app draws a line and exposes only its **API**:
+
+```text
+src/api/v3/index.ts       shared: host kinds, the principal type, defineFacet per kind, core contracts, registry tokens
+src/api/v3/web.ts         web only: shared UI pieces (a Sheet, theme variables), React-typed registry tokens
+src/api/v3/tui.ts         TUI only: its UI pieces
+src/…                     internal: everything else
+```
+
+Each API module is a host package of the kinds that may use it: `@acme/app/v3` for every kind, `@acme/app/v3/web` for
+the web kind only. A worker plugin importing `@acme/app/v3/web` is a build error, and a worker process never loads
+React. The shared module stays free of runtime imports of UI libraries: a registry token that needs a React type names
+it with `import type`, which the build erases.
+
+:::note | Proposed
+The split of the external API into a shared module and per-kind modules answers the owner's worry about "web, TUI,
+worker, server things all in the same index.ts". Proposed, not yet decided.
+:::
+
+# Versions in the Import Path {#versions lede="A plugin says what it was written for where it imports it."}
+
+The app's API changes over time: a host kind is renamed, a principal variant changes. A plugin written for an older
+API must not silently get the new one. So every API module has a version in its path, and the app lists which versions
+it still provides:
+
+```ts
+// plugins/stats/worker.ts
+import { defineFacet, Session, Panels } from "@acme/app/v3";
+import { remote, str } from "@earendil-works/chord/v2";
+```
+
+- The app provides `/v3`, its current API. If version 2 plugins still work unchanged against it, `/v2` is listed too,
+  pointing to the same module. An app that needs a compatibility layer makes `/v2` a thin module over `/v3`.
+- An import of a version the app no longer lists is a build error: "@acme/app/v1 is not available: this app provides
+  v3, v2". The plugin keeps its old code, and the message tells an agent exactly what to change.
+- Nothing to fill in elsewhere: no `package.json` field, no npm ranges. Skeletons and examples import the current
+  version, so an agent copies it without thinking.
+- Chord's own surface is versioned the same way (`@earendil-works/chord/v2`).
+
+Decided: "the API version must be declared by the plugin in code" (owner, 2026-10-31); the import path is how.
+
+# Contracts and Registries {#contracts lede="Finer versions inside the API, and what crosses between plugins."}
+
+Contracts and registry tokens keep their own versions inside the API, because they evolve independently of the API as
+a whole:
+
+- **An object type**: the consumer carries the contract version it was written for; the provider binds it at that
+  version if it accepts it (`accepts` maps arguments forward and results and state back), otherwise the consumer waits
+  "contract mismatch: v1, served v3". Shapes are fingerprinted, so a changed shape without a version bump is caught.
+- **A registry token**: a name, a version and TypeScript types for what is contributed and read. Values are in-process
+  things (functions, components), which cannot be fingerprinted: bumping the version when they change is the defining
+  plugin's rule, and its `accepts` adapts older contributions.
+- **Host kinds on registries** (proposed): a token names the kinds that serve it (`hosts: ["web"]`), typed, so a worker
+  facet contributing to a web registry is a type error and a load error, not a silent no-op.
+
+A contract file imports only host packages at runtime (Chord, the app's API); native types it mentions are type-only.
+
+# What a Plugin May Import {#imports lede="Four kinds of import, each with one rule."}
+
+| Import | Resolved to | Versioned by |
+| --- | --- | --- |
+| its own files (`./store.ts`) | copied into its script | the plugin itself |
+| host packages (`@acme/app/v3`, `@earendil-works/chord/v2`, `react`) | the running process's instance, shared | the path's version; the app lists what it provides |
+| npm packages in its `dependencies` (`slugify`, a third party's contracts package) | its own `node_modules`, bundled | the installed version |
+| the app's own plugins (`../notes/contract.ts`), in the same root | copied into its script | the same revision: one repository |
+
+A third-party plugin that wants the app's plugins' contracts gets them through the app's API (core contracts) or the
+app's published package, as an npm dependency at the version it was written for, never from the running plugin's
+files. Anything else (a path into base code, an unlisted version, a package not in its dependencies) is a build error.
+
+# Settings and Extensions {#settings lede="How the app configures its components without letting plugins override it."}
+
+Decided ("Settings are arguments, extensions are registries"): what the app decides at startup is an argument to the
+component's facet, which base code constructs, and plugins cannot change it:
+
+```ts
+const http = createHttp(server, { listen: { port: 8788 }, links: { path: "/chord", maxPayload: MiB }, closeTimeout: 10_000, onError }, ctx);
+```
+
+What plugins add while the app runs is a registry: routes, authenticators, tools, panels. A component may offer both
+for one thing: the session index takes its indexer as an argument, and may also follow a registry of indexers if
+plugins should supply them.
+
+# Building and Evaluating {#build lede="Unchanged from slices 7c and 10: one build on the server, evaluation everywhere."}
+
+Only the server builds, because only the server has the sources. `createPlugins` builds every kind and needs only
+names: per kind its platform and its host package names. Each process evaluates the scripts of its kind with its own
+module objects (the server's at `plugins.load`, a worker's in `workerMain`, a page's in its base bundle), so a plugin
+shares that process's Chord and API. Base-code facets are passed beside the plugins; they are not plugins, because
+they close over the process's own values and never reload.
+
+# Types and Tests {#tools lede="Where types come from, and how a plugin is tested alone."}
+
+Types come from where imports come from: relative files and npm packages resolve natively in TypeScript; the app's API
+modules ship `.d.ts` per version in the app's package. There is no type checking in the build (the owner: seconds per
+build is too slow); editors check as an author types, and an agent may run `tsc` as a tool.
+
+Testing a plugin alone (proposed): `testPlugin(dir, { kind, stubs })` builds the plugin like production, loads it on an
+in-memory host with the kind's real host packages, and loads stub facets that serve the contracts it depends on. A stub
+is an ordinary facet; there is no mocking framework.
+
+# Open Questions {.epilogue lede="What is proposed here and still to decide."}
+
+1. The external API split by host kind (`/v3`, `/v3/web`, `/v3/tui`).
+2. Host kinds on registry tokens, typed and checked at load.
+3. Single-file plugins (`hello.worker.ts`, named by the file).
+4. Contracts of the app's plugins for third parties: through the API modules only, or also the app's npm package.
+5. `testPlugin` with stub facets.
+6. Reversing "Plugins import each other by name" (2026-10-31, morning) in favour of relative paths within the app
+   and npm dependencies across it.