pi-mono/packages/chord/docs/slice-13.md

Slice 13: the app kit (spec)

Status: approved (owner, 2026-11-01: decisions "The app kit, point 1" to "point 5", then "go ahead, just do all the things"). Builds on slices 10 (http, workers) and 12 (the plugin model). chord/app in src/node/app/: an opinionated layer so an app is its API, its built-in plugins and a start script.

Read in full before writing code: this spec; decisions.md entries of 2026-10-31 and 2026-11-01 (the app kit, the plugin model, "The app kit is opinionated", "Settings are arguments, extensions are registries", "The HTTP component's security baseline"); design.md §3, §4, §10, §21, §23 (all of it, "The app kit" included); slices.md (carry-over "Slice 13"); slice-10.md, slice-12.md; the READMEs of node/http, workers, plugins; p2's src/runtime/server.ts, src/hosts/server.ts, src/hosts/worker.ts, src/runtime/loopback-cookie.ts, src/hosts/principals.ts, plugins/devices/, plugins/sharing/, plugins/files/ for what exists.

1. startApp and startWorker

// start.ts (the app's start script)
const app = await startApp<P>({
	name: "acme",                                   // the default data directory: ~/.acme
	dataDir: process.argv[2],                       // optional; no environment variables
	listen: { host: "127.0.0.1", port: 8788 },
	api: { name: "@acme/app", versions: ["v3"], modules: { "@acme/app/v3": apiV3, "@acme/app/v3/server": apiV3Server } },
	kinds: { server: { platform: "node" }, worker: { platform: "node" }, web: { platform: "browser", packages: { react, "react/jsx-runtime": jsx } } },
	principal: { server: { kind: "server" }, worker: (address) => ({ kind: "worker", key: address.key }) },
	workers: [{
		kind: Project,                              // a host kind the app defines, any params
		entry: "./worker.ts",
		start: (address, ctx) => ({ id: address.params.id }),
		authorize: (principal, address) => mayReach(principal, address),
		idleMs: () => 5 * 60_000,
	}],
	onError: (error) => log(error),
}, ctx);
// app.host, app.http, app.workers, app.plugins, app.applyChanges(ctx), app.exportAddress(address, ctx),
// app.importAddress(archive, address, ctx), app.ownerLink(), app.close(ctx)

// worker.ts
await startWorker<P>({ api, kinds, onError });   // reads the start message, opens the worker's store, loads plugins

• startApp creates the data directory layout (§4), opens the server store, creates the host (address Server(), the server principal), createHttp (settings as arguments), createWorkers per worker kind (kind named after the host kind; the worker's facet kind is worker unless the entry says otherwise), createPlugins with the roots of §5 and the app's API (slice 12), loads the server's plugins with the kit's own facets (§2, §3, §4) as core, and resolves once loaded. close closes in the right order (http, workers, host, store).
• startWorker is workerMain plus: the worker's directory and store under its kind and address, the host with the principal from the start message, connect first, plugins loaded with the kit's worker facets, busy from the app if given.
• The start-data facet: the kit serves AppInfo (data directory, app name, version) on the server and WorkerInfo (address, start data) on workers as core objects plugins get.
• Zero worker kinds: no workers component.

2. Principals and sessions

• The app's principal type P; the kit needs only principal.server and principal.worker(address). The kit adds one variant for its owner: { kind: "owner" } must be assignable to P (a type check).
• Sessions (app/sessions.ts, a kit object on the server, persisted in the server store): issue(principal, { label, kind: "browser" | "device" }, ctx) returns a token; tokens stored hashed; revoke(id); list (watchable: label, kind, created, last used). The kit's authenticator (contributed to Authenticators) reads the session cookie (signed, HttpOnly, SameSite=Strict) or an Authorization: Bearer header, and gives its principal.
• Owner link: at start the kit issues a one-time token (random, single use, valid 10 minutes, replaced at each start) and app.ownerLink() returns http://127.0.0.1:8788/_chord/owner#<token>; the start script prints it. The route GET /_chord/owner serves a page that posts the token (from the fragment, never sent in a URL to logs) to POST /_chord/owner, which consumes it and sets a browser session cookie for the owner. No owner by loopback alone.
• Owner token file: <dataDir>/owner-token (mode 0600, created at first start, a device session of the owner) for command-line clients on the same machine.
• Device pairing (for remote command-line and TUI clients): POST /_chord/pair (public) returns { code, poll }; the owner approves the code in a browser (GET /_chord/pair/<code>, owner only, a confirm page); the client polls and receives a device token. Codes expire after 10 minutes.
• Deny by default (an HTTP component change): a route or socket without a principal is refused (401) before plugin code, unless its contribution marks it public: true (routes: { handler, public: true }; sockets likewise). The /chord links endpoint requires a principal. Foreign requests stay anonymous as before, so they reach only public routes. Slice 10's examples and tests mark their anonymous routes public.

3. Optional kit plugins

Shipped as plugins (in packages/chord/plugins/ or exported facets the app adds to its root; choose one and say why): users (accounts keyed by id, a profile schema the app passes in, self.get(Users, {}) with get, update, list), invite (invite links issuing a session for a principal the owner chooses), ephemeral-login (a public route taking a name, issuing a session for { kind: "user", id: <fresh>, name } that ends with the connection; the app's P must allow it). Each contributes to Authenticators or issues sessions through §2.

4. Storage, files, export

• Layout: <dataDir>/server/store.sqlite, <dataDir>/workers/<kind>/<encoded address key>/store.sqlite plus that worker's files, <dataDir>/plugins/ (the user's root), <dataDir>/logs/, <dataDir>/owner-token.
• Files (a kit facet on workers, and on the server for server-scoped files): Files (local, params {}, one per host) with put({ name, mime, bytes }) for small files, begin/append/finish for large ones (design §23 chunked transfers), read({ id, offset, length }), remove, list (watchable index: id, name, mime, size, created), caps per host (an option). Stored under the host's directory (files/), the index in the store.
• Export / import per address: app.exportAddress(address, ctx) stops the worker (as workers.stop), writes one archive: the store's export archive (slice 6a) plus the worker's directory (files), and returns a readable stream or writes to a path; importAddress(archive, address, ctx) refuses an existing address, unpacks, and the next hold starts the worker. Format: a tar of store.archive and files/, with a small manifest (app name, API version, kit format version).

5. Plugins

• Roots: the app's plugins/ (required, slice 12) and <dataDir>/plugins/. Installs (app.plugins.install(source, ctx), slice 12's installPlugin) go to the user's root.
• app.applyChanges(ctx): build the dirty plugins and roll out (server step, then the workers step); returns the rollout result; app.plugins.state for the app's button. Never applied by itself.

6. Not in slice 13

Web and TUI clients (slice 11, which builds on this kit: startApp gains the web surface there); telemetry (9); project plugins (§26 #14).

7. Tests, examples, docs

• One test file per source file: start and close order; a server without workers; two worker kinds; the owner link (single use, expiry, the fragment), sessions (issue, revoke, list, hashed storage), the token file mode, device pairing, deny by default (a route without principal 401, a public route served, /chord refused anonymous), Files (small and chunked, caps, list, remove), export and import (a worker with documents, tables and files round-trips; importing over an existing address refused), applyChanges, required root failure stopping startApp.
• Examples: 53-app (a small app: start script, API, two plugins, a worker kind, the owner link), 54-app-sessions (pairing a command-line client), 55-app-export (export and import a worker's address).
• src/node/app/README.md; the guide "Hosts and Plugins" gets a closing chapter on the app kit.