Slice 7b
Reload

A plugin is a directory. Its name is its package.json name; its code is one file per host kind it runs on, a facet; everything else is ordinary TypeScript the facets import. This is p2's layout today (apps/p2/plugins/*), plus the package.json that loader D needs (p2's plugin-loading.md §8; p2's built-in plugins have none yet and are named by their directory).

plugins/notes/
  package.json        name = the plugin's name; peerDependencies = host packages; dependencies = bundled npm deps
  contract.ts         the plugin's object types and registries (shared by its facets and by other plugins)
  server.ts           facet for the server     (default export: defineFacet(...))
  worker.ts           facet for session workers
  web.tsx             facet for browser tabs
  tui.ts              facet for the TUI
  store.ts            plain modules the facets import
  NoteList.tsx
  notes.css
  assets/
    template.md       files the plugin ships (read at runtime, or offered for download)
    icon.svg
  skills/notes/SKILL.md   optional resources (p2 §4.4)

{
  "name": "@pi/notes",
  "version": "1.4.0",
  "type": "module",
  "peerDependencies": {
    "@earendil-works/chord": "^2",
    "@earendil-works/pi-durable": "^1",
    "react": "^19"
  },
  "dependencies": {
    "marked": "16.4.1"
  }
}

• name identifies the plugin everywhere: its facets, its registry contributions, diagnostics, reloads.
• peerDependencies are host packages: the running app supplies them, one instance per process (one Chord, one React; instanceof ChordError and React hooks only work that way). The bundler never copies them.
• dependencies are the plugin's own npm packages (marked): installed into the plugin's node_modules with --ignore-scripts and bundled into every facet that imports them. Decided (owner, 2026-10-29): bundled by default; on Node a plugin may keep named packages external by an explicit list, "chord": { "external": ["better-sqlite3"] }. Server and worker facets then load them from the plugin's node_modules with createRequire, as pi 1.0 loads extension dependencies, native addons included; they stay in Node's module cache until the process ends, so a new version takes effect after a restart. A browser or TUI facet that imports one fails to build.
• No tsconfig.json is needed. The bundler strips types and does not type-check; JSX is compiled with the automatic React runtime, a fixed setting of the loader. A plugin may keep a tsconfig.json for its editor and for tsc --noEmit (the SDK ships one to extend); the loader ignores it.

A facet only declares (chapter III of the model): it serves object types, serves or contributes to registries, and returns nothing.

// plugins/notes/contract.ts
import { defineRegistry, local, remote, str, obj, arr, method } from "@earendil-works/chord/next";
import { Session } from "@app/core";                        // the app's host kinds, a host package
export const NoteStore = local("notes.store", { version: 1, params: {}, members: { /* … */ } });
export const Notes = remote("notes", {
  version: 2,
  params: { session: str() },
  hostAddress: ({ session }) => Session({ id: session }),
  variants: { editor: { state: { list: arr(obj({ id: str(), text: str() })) }, methods: { add: method(obj({ text: str() })) } } },
});

// plugins/notes/worker.ts
import { defineFacet } from "@app/core";                    // bound to the app's principal type
import { NoteStore, Notes } from "./contract.ts";
import { serveStore } from "./store.ts";
export default defineFacet((host) => {
  host.serve(NoteStore, serveStore);
  host.serve(Notes, ({ session }, principal, self) => { /* … */ });
});

// plugins/notes/web.tsx
import { defineFacet } from "@app/core";
import { NoteList } from "./NoteList.tsx";                  // a React component, bundled
import "./notes.css";                                       // bundled into the facet's stylesheet
export default defineFacet((host, self) => {
  self.contribute(Panels, { notes: NoteList });             // the app's UI registry
});

Each facet is built on its own, as one script. The bundler starts at the facet file and follows its imports:

The built script is a function of its host packages. That is the whole trick of loader D: there is no module map, no second copy of Chord, and an old version is garbage-collected once nothing holds its closures.

// what the bundler emits for plugins/notes/worker.ts (simplified)
(function (require, __files) {
  const { defineFacet } = require("@app/core");             // the host's instance
  const { local, remote, str } = require("@earendil-works/chord/next");
  const { marked } = /* marked's code, inlined */;
  /* contract.ts, store.ts, inlined */
  return defineFacet((host) => { /* … */ });
})

// the loader (proposed @earendil-works/chord/next/loader), Node side
import { buildFacet, evaluateFacet } from "@earendil-works/chord/next/loader";

const HOST_PACKAGES = {                                     // the app's base bundle exports these
  "@earendil-works/chord/next": chordNext, "@earendil-works/pi-durable": durable,
  "@app/core": core, react, "react/jsx-runtime": jsxRuntime,
};
const script = await buildFacet({ plugin: "/data/plugins/notes", facet: "worker.ts", hostPackages: Object.keys(HOST_PACKAGES), platform: "node" });
const facet = evaluateFacet(script, { hostPackages: HOST_PACKAGES, require: createRequire(import.meta.url), dir: "/data/plugins/notes" });
await host.reload([{ name: "@pi/notes", facet }], ctx);    // or host.load the first time

• buildFacet is esbuild with: the facet as entry, the host packages and node:* external, format: "cjs" wrapped as the function above, minified, an onResolve that refuses anything outside the plugin, its node_modules, a contract of another plugin or a host package. It returns the script, its content hash and esbuild's metafile (the dev loop knows which files a facet used).
• evaluateFacet runs the script with vm.Script and a stable filename per (facet, hash) on Node, or as a classic <script> in the browser (the page fetches the script and its stylesheet by hash, which caches forever).
• Imports a plugin cannot use: dynamic import() (resolved at build, or not at all), top-level await (a facet is a synchronous declaration), require of anything but builtins.

A plugin has files that are not code. They fall into three cases.

1. Imported by a web facet. CSS, images, wasm. The bundler emits them as content-hashed files next to the facet's script, and the import evaluates to their URL. The app serves the bundle's files under one path; p2 does exactly this today for the terminal's wasm (plugins/terminals/Terminal.tsx: import ghosttyWasm from "../../vendor/ghostty/ghostty-vt.wasm?url", served under /__p2_web/).

import iconUrl from "./assets/icon.svg?url";
export const NoteIcon = () => <img src={iconUrl} alt="" />;

2. Read at runtime by a server or worker facet. A template, a wasm module for a native, a script a native runs. A bundled script has no meaningful import.meta.url (today's plugins/terminals/main.ts reads its wasm with new URL("../../vendor/…", import.meta.url)). The loader passes the plugin's directory, and a helper resolves a path inside it, refusing .. out of it:

// plugins/notes/worker.ts
import { pluginFile } from "@earendil-works/chord/next/loader";   // reads the directory the loader passed
const template = await readFile(pluginFile("assets/template.md"), "utf8");

3. Offered for download over HTTP. A plugin contributes a route to the app's HTTP registry; the handler opens the file through the same helper and streams it, with the plugin's own authorization:

// plugins/notes/server.ts
export default defineFacet((host, self) => {
  self.contribute(Http, {
    routes: {
      "GET /notes/template.md": async (request, ctx) => {
        if (ctx.principal.kind !== "owner") return { kind: "error", status: 403 };
        const path = pluginFile("assets/template.md");
        const { size } = await stat(path);
        return { kind: "bytes", name: "template.md", mime: "text/markdown", size, read: (offset, length) => readRange(path, offset, length) };
      },
    },
  });
});

So yes: a plugin can offer its files for download, because the loader tells it where it lives. Each facet sees only its own plugin's directory; nothing gives it another plugin's files.

Chord v2 has no HTTP server today. Design §23 designs one (@earendil-works/chord/next/http) and defers it until "the kernel fixes and a first real proof" are done. p2's HTTP is its own, about 30 lines of helpers plus the server host:

// apps/p2/src/runtime/server.ts (p2 today, Chord v1)
export const Routes = defineRegistry<RouteHandler>("p2.routes", { conflict: "error" });        // "METHOD /path" → handler
export const Upgrades = defineRegistry<UpgradeHandler>("p2.upgrades", { conflict: "error" });   // WebSocket upgrades
export const RequestResolvers = defineRegistry<RequestResolver>("p2.request-resolvers", { conflict: "error" });
type RouteHandler = (request: IncomingMessage, response: ServerResponse, access: RequestAccess, ctx: Ctx) => void | Promise<void>;

Plugins contribute handlers that write to Node's ServerResponse themselves; the files plugin implements ranges, download headers and previews by hand (plugins/files/server.ts).

The designed component (§23) replaces raw responses with descriptions, so every plugin gets ranges (206/416), HEAD, safe download headers, streaming and abort on disconnect from one place:

export const Http = defineRegistry<HttpContribution, Router>("chord.http", { version: 1 });
type HttpContribution = { routes?: Record<string, Route>; wraps?: Wrap[] };
type Route = (req: HttpRequest, ctx: Ctx) => Promise<HttpResponse>;   // ctx.principal: the request's principal
type HttpResponse =
  | { kind: "json"; value: JsonValue } | { kind: "page"; title: string; body: string }
  | { kind: "bytes"; name: string; mime: string; size: number; read(offset: number, length: number): Promise<Uint8Array> }
  | { kind: "redirect"; to: string } | { kind: "error"; status: number };

• Routes compose by keyedEntries: a duplicate pattern is a reported conflict, the first by plugin name wins.
• Wraps (middleware) run in phases the owner defines (observe, headers, transform), by default only around their own plugin's routes.
• Request resolvers (who sent a request: cookie, loopback, relay) are hooks; WebSocket byte channels for terminals are a separate component.

Built with the loader D settings above (each facet alone, host packages and apps/p2/src external, minified), on p2's real plugins:

The plugins are small; the time goes into the host packages and the runtime (85% of a worker's load time, p2 §14.1), which the base bundle loads once per process. A reload of one plugin costs one rebuild (about 11 ms warm) and one evaluation (about 1 ms per facet), then Chord's reload. The memory caveat is V8's compilation cache: every distinct compiled script stays cached, so scripts get a stable name per (facet, hash) and hosts that reload in place run with the cache off (+0.1 MiB instead of +5.6 MiB per 100 reloads, p2's measurement).

p2 has about 10,700 lines of host code in apps/p2/src/hosts and its runtime: the server's HTTP and WebSocket entry, the worker supervisor, plugin discovery, the web and TUI bundles, the web shell, the TUI sandbox and launcher, the reload control. Almost none of it is p2-specific. The proposal: Chord ships it as optional components, each a subpath an app imports only if it wants it, none of them in Chord's kernel.

What it would look like

// server.ts: a whole app with plugins, a web and a TUI surface
import { createHost } from "@earendil-works/chord/next";
import { discoverPlugins, pluginLoader } from "@earendil-works/chord/next/loader";
import { httpServer } from "@earendil-works/chord/next/http";
import { workerRoute } from "@earendil-works/chord/next/workers";
import { webSurface } from "@earendil-works/chord/next/web";
import { tuiSurface } from "@earendil-works/chord/next/tui";
import { devReload } from "@earendil-works/chord/next/dev";
import { Server, Session, core } from "./core.ts";              // the app's base code: host kinds, principals, core facet

const plugins = await discoverPlugins(["./plugins", join(dataDir, "plugins")]);
const loader = pluginLoader({ hostPackages: core.hostPackages });

const server = createHost<P>({ address: Server(), principal: { kind: "server" }, onError });
server.route(Session, workerRoute({ entry: "./worker.ts", idleMs: 300_000, authorize: core.authorize }), ctx);
await server.load([core.serverFacet, ...(await loader.facets(plugins, "server"))], ctx);

const http = httpServer(server, { port: 4321, authenticate: core.authenticate });   // routes from the Http registry
http.surface(webSurface({ loader, plugins, shell: core.webShell }));                  // /: the page, its bundle, its socket
http.surface(tuiSurface({ loader, plugins }));                                        // the TUI launcher's bundle and socket
devReload({ server, loader, plugins, watch: true });                                 // a changed plugin reloads everywhere

// worker.ts
import { workerMain } from "@earendil-works/chord/next/workers";
await workerMain(async ({ address, init, parent }) => {
  const worker = createHost<P>({ address, principal: { kind: "worker", session: init.id }, onError });
  worker.connect(parent, { principal: { kind: "server" }, trusted: true }, ctx);
  await worker.load([core.workerFacet(init), ...(await loader.facets(init.plugins, "worker"))], ctx);
  return worker;
});

// core.ts, the web shell: the app decides the layout; plugins fill registries
export const Panels = defineRegistry<Record<string, ComponentType>, Panel[]>("app.panels", { version: 1 });
export const webShell = ({ host }: ShellProps) => {
  const panels = useRegistry(host, Panels);                     // from chord/next/web: a hook over a registry value
  return <Tabs>{panels.map((p) => <p.component key={p.name} />)}</Tabs>;
};

And a plugin is what chapter I shows: a directory, a package.json, facets that serve types and contribute to the app's registries (Http, Panels, a TUI command list).

The components

Each is ordinary code on top of Chord's public API: nothing in the kernel depends on it, a Durable Object deployment uses none of it, and an app can replace any one (its own HTTP server, its own shell). React is a host package of the web component, pi-tui of the TUI component; an app without them never imports them.

What stays the app's

The principal type and authentication; the host kinds (Server, Session) and what a worker's start message holds; the core facet and core objects (catalog, harness); the web shell's layout and the TUI's look; which registries plugins contribute to beyond Http. That is roughly what p3's base code should be: a few hundred lines, not ten thousand.

Design §21 fixes the shape. Decided.

1. load      the new bundles; an import or syntax error rejects
2. staging   facet setups and every live object's new factory run with a recording `self`
             (declarations only, nothing activated); any throw rejects
3. commit    the host switches to the new code atomically: a publication (7a)
4. after     each object follows its fate (chapter II)

Rollback is all or nothing per host, and only for code errors: an import error, a throwing setup or factory. A failed open, a registry conflict or a failing migrate after the commit are runtime states of single objects, never a reason to roll back. A host is at revision R or R−1, never in between.

Staging runs factories against a recording self because a factory only declares: it returns members and calls self.state, self.get, self.open and so on, and the recording tells Chord what changed (a new dependency, a native added or removed, a member gone) before anything happens.

The commit compares each live object's old and new declarations. Decided (design §21, owner 2026-10-26, the dependency model).

// notes v1                                     // notes v2: pure, swapped in place
host.serve(NoteStore, (_, self) => {           host.serve(NoteStore, (_, self) => {
  const notes = self.state(Notes);               const notes = self.state(Notes);      // same document, v2 migrates it
  return {                                       const count = self.derive([notes], ([n]) => n.list.length);
    notes,                                       return {
    add: (a, ctx) => self.tx(…, ctx),              notes, count,                       // a new exposed member
  };                                               add: (a, ctx) => self.tx(…, ctx),
});                                                rename: (a, ctx) => self.tx(…, ctx), // a new method
                                                 };
                                               });

Rules that come with the fates, all decided:

• R15, old code and migrated documents: an old call that touches a document whose version rose throws once; the document stays intact; the call is not resent.
• Derives have no names: exposed derives are matched by their member name, internal ones are rebuilt.
• Routines hand over per object: the old ones are aborted, the new ones start once the old calls finished, bounded by closeTimeout; calls do not wait for it.
• Instance ids: a restarted object gets a new instance id (an old activation chain must not match it); a swapped one keeps it.
• Broken objects of a reloaded plugin are retried, as ref.retry() does.
• A parked object of a reloaded plugin is replaced by the new factory's attempt in one handover: the new requests bind before the old ones are released (the mechanism 7a removed comes back here).
• In-memory documents migrate on reload through their definition's migrate (6a built the version check).

A reference on another host points at an object whose code may change under it. Decided (design §21, §22 and the dependency model):

A provider accepts older consumers through accepts, written once with the provider, never in the shared contract (Q10):

export const NotesV2 = evolve(NotesV1, (e) => e.state("editor", "notes", arr(NoteV2)).args("add", NoteV2));

host.serve(NotesV2, factory, {
  accepts: {
    1: {
      state: { editor: { notes: (current) => current.map(toV1) } },   // what a v1 tab sees, as a diff per commit
      methods: { add: { args: (old) => toV2(old) } },                 // a v1 tab's call, mapped forward
    },
  },
});

• Old-version calls: checkArgs returns { kind: "method", args, result? } or { kind: "call", args, call }; Chord runs the handler or the provider's replacement and maps the result back (L1 built the check; 7b invokes it).
• Adapted bindings get diffs: Chord keeps the last adapted value per binding and sends diffRevisions, so an old tab never receives a whole state per commit.
• On the wire (7b's half of 7a's model): a failed on a bound hold unbinds it; the provider drops its unsent pending work and keeps the ack slots of messages already sent; a consumer whose own code moves to a new version releases its old hold and makes a new one.
• A consumer reloaded itself gets new requests from its new factory; the handover binds them before it releases the old.

Today host.serve binds every provider with an empty accepts table (host.ts: bindProvider(contract, {})); 7b passes the provider's table. Small and decided in shape (Q10, bindProvider); the option's place is host.serve(Type, factory, { accepts, linger }).

Decided (design §15, owner 2026-10-24 and 2026-10-26):

const ExportJob = defineJob("notes.export", {
  version: 2,
  args: obj({ format: oneOf("md", "html") }),
  result: obj({ path: str() }),
  accepts: { 1: { args: (old) => ({ format: "md" }), result: (old) => ({ path: old.file }) } },
});

• A run started on an older version finishes on its old code across a pure swap; finish and running see its args and result mapped forwards, once per run.
• Without an adapter, or for a run of a newer version (a rollback), the run is blocked { version } until a reload brings matching code; blocked runs are retried on every reload. Nothing is aborted or discarded for a version change.
• A native restart aborts running runs (aborted { reload }) and finish runs on the new code.
• A job the new code no longer declares: its runs are blocked { version } (the same family), kept until a reload declares it again or they are aborted.
• Persisted runs of another version or fingerprint stay blocked with their record as stored, resolved by the reload that brings their version.

Decided (slice 8 §6, design §17): the commit replaces a plugin's contributions and a registry's provider in one batch; staging composes nothing (D1). The record keeps the provider, facet contributions by plugin and object contributions by object apart, so a reload of one plugin replaces exactly its parts (today RegistryRecord.serve refuses a second serve). Older readers across a reload of the provider follow its new accepts[old].value. A reader waits (7a) when the new provider no longer serves its version. retryOn watches are re-declared by the new factory.

Decided (design §21 and the dependency model): a revision is the complete code set; the server installs first, then workers, then clients; installs are serialized per host; a host that starts or reconnects installs the current revision first; a revision carries a code-set digest so an unchanged server restart reinstalls nothing; an install never waits for activations (a reverse-order rollout would deadlock); each host knows only its own install: while it installs, holds that do not fit its running code wait installing, re-evaluated when the install ends; a host whose own install was rejected fails its own requests with the reason.