p3 application
Overview
Path-routing coverage: this doc owns apps/p3/**. Route any review that changes the private p3 package, its p3 command, API exports, built-in plugins, kit, release/build scripts, benches, p3 docs, or p3 tests here.
apps/p3 is the private @earendil-works/p3 package: a local Pi server, the p3 CLI that starts and controls it, the plugin API exposed to p3 plugins, the built-in sessions plugin, and the release tooling that packages all of that. apps/…/package.json marks it private, exposes p3 as dist/p3.js, and exports only ./v1, ./v1/server, and ./v1/worker for plugins. The README documents the user-facing model: a Pi is a data directory, defaulting to ~/.pi/p3; named Pis live under ~/.pi/p3/pis/<name>; each Pi has its own sessions, sign-ins, cookie, config, port, and logs.
The command entry is apps/…/bin.ts. It imports apps/…/minimum-node.ts first so too-old Node versions fail before any other module loads, parses p3 [command] [--pi | --dir] [--port], maps Pi choices through apps/…/pi.ts, then either runs the foreground server (p3 server) through startP3 or delegates background/status/stop/list behavior to apps/…/commands.ts. Background starts spawn apps/…/supervisor.ts, which holds a supervisor lock, starts the server child, restarts it after post-listen crashes with backoff, and writes to <dataDir>/…/server.log. commands.ts never trusts server.json or supervisor.json alone: it combines the lock/record logic in apps/…/running.ts with HTTP identity proof via apps/…/ask.ts and apps/…/identity.ts before sending owner-token requests such as owner-link renewal or stop.
The server entry is apps/…/server.ts, which calls apps/…/start-server.ts. startServer opens and private-izes the data directory, takes the server lock, writes a starting record, opens pi.json, the cookie secret, the SQLite server store, the Chord host, HTTP component, plugin loader, and session workers, then loads p3 core facets plus built-in plugins. Once HTTP listens and the owner token file exists, it writes the running record with the run id, Pi id, port, version, and start time. State on disk is laid out by apps/…/layout.ts: pi.json, server/store.sqlite, server/cookie-secret, owner-token, server.json, supervisor.json, cache/worker, cache/node, workers/<kind>/<encoded address>, and logs. apps/…/config.ts persists the Pi id and first chosen port; apps/…/secrets.ts generates token material, hashes sign-in secrets, and writes secret/config/record files by private temp-file rename.
Authentication and ownership are kit facets. apps/…/sign-ins.ts stores sign-ins in the server store with only token hashes, authenticates bearer tokens before signed cookies, rolls browser cookies, and closes open Chord links when a sign-in ends. apps/…/owner.ts creates a single-use 10-minute owner link at /_p3/owner#<token>, consumes it through a public POST that issues an owner browser sign-in, and maintains the owner-token file as a device sign-in for same-machine clients and the CLI. apps/…/stop.ts serves owner-only POST /_p3/stop; the CLI prefers this HTTP stop and only signals identified or otherwise safe fallback targets.
The worker entry is apps/…/worker.ts, which calls apps/…/worker.ts. Server-side worker management lives in apps/…/session-workers.ts: Chord's workers component forks one process per Session address, builds a worker base into cache/worker, uses cache/node as the Node compile cache, authorizes only owner/server principals in apps/…/session-route.ts, and admits a worker only if the sessions plugin says that session exists. A worker creates its own SQLite store under workers/session/<encoded key>/store.sqlite, connects back to the server as a trusted worker principal, loads worker facets, and serves WorkerInfo. Worker process flags are centralized in apps/…/install.ts along with source-vs-release entry paths and the built-in plugins root.
The public plugin API is intentionally narrow. apps/…/app.ts declares p3's package name, API versions/modules, host kinds, and principals. apps/…/index.ts re-exports Chord's root surface, p3's defineFacet, Server, Session, P3Principal, and browser-safe kit helpers forward and contribute. apps/…/server.ts exports server-only items (Http, AppInfo, and the SessionRoute local contract), and apps/…/worker.ts exports WorkerInfo. Plugins should import these API modules rather than Chord directly; apps/…/build-release.ts compiles the API modules and declarations separately from the process bundles so third-party plugins can type-check against an installed p3.
The built-in sessions plugin under apps/p3/plugins/sessions is currently the main domain plugin. Its shared contract in contract.ts defines sessions, lists, worker facts, and owner-visible worker objects. server.ts owns a sessions.rows table and serves owner operations, paged active/archive lists, worker SessionFacts, and the base-code SessionRoute existence contract. worker.ts serves SessionWorker by forwarding the server-provided SessionFacts from the session worker back to the owner. This plugin is loaded from the package's plugins/ root in both source and release layouts.
Release and validation live inside the same package. apps/…/build-release.ts builds separate esbuild bundles for the command/server (main.js), worker, supervisor, and minimum-node check, writes the warning-filtering launcher dist/p3.js, checks dependency versions and bundle externals, keeps worker/supervisor bundles lean, and invokes tsc for API JavaScript/declarations. apps/…/release-local.ts builds p3 plus workspace dependency tarballs, installs them into an isolated directory outside the repo, links the command, and can run release tests and apps/…/slice-1.ts. Tests cover the kit, commands, topology, release packaging, third-party API use, and end-to-end server/worker persistence; apps/…/topology.ts provides an in-process Chord topology with reloadable sessions plugin, while apps/…/launched.ts drives real source or release processes.
Coupling
- If apps/…/app.ts,
apps/p3/src/api/v1/*, or apps/…/package.json exports change, also verify apps/…/build-release.ts and apps/…/release.test.ts: the release expects exactly those API entry points, shipped source files, declaration maps, and plugin-facing runtime imports. - If apps/…/install.ts changes entry paths, source flags, worker V8 flags, or plugin-root resolution, also check apps/…/server.ts, apps/…/commands.ts, apps/…/build-release.ts, apps/…/install.test.ts, and release tests. Source and release layouts both depend on this file rather than rebuilding paths independently.
- If the data-directory layout in apps/…/layout.ts changes, update apps/…/start-server.ts, apps/…/session-workers.ts, apps/…/commands.ts, apps/…/ask.ts, apps/…/client.ts, apps/…/launched.ts, and apps/…/slice-1.ts; these files know paths such as
owner-token,cache/worker, logs, and worker stores. - If the running-record or identity proof shape changes in apps/…/running.ts or apps/…/identity.ts, also update apps/…/ask.ts, apps/…/commands.ts, and apps/…/supervisor.ts. The CLI's safety depends on proving a record over the same connection before sending owner credentials or signals.
- If apps/…/server.ts changes
SessionRoute, also update apps/…/session-route.ts and apps/…/server.ts: base code owns the route contract but the sessions plugin serves it, and session worker admission depends on both sides matching. - If session contracts or table rows change in apps/…/contract.ts, contract.server.ts, or server.ts, verify apps/…/worker.ts, apps/…/end-to-end.ts, apps/…/topology.ts, and apps/…/slice-1.ts; lists, worker admission, worker-visible facts, and benchmark filling all share the same session row shape.
- If apps/…/build-release.ts changes shipped files, bundle externals, or process bundle boundaries, verify apps/…/package.json
files/exports, apps/…/release-local.ts, and apps/…/release.test.ts. The installed release tests assert that no workspace sources leak into the install and that worker/supervisor bundles do not drag server-only code.
Risks
- apps/…/secrets.ts writes secrets with create-vs-replace semantics under the assumption that create callers hold the server lock. Recent history includes
fix(p3): write secret files by rename, never a hard link (Android forbids hard links), so changing this path can break first start or expose/lose cookie and owner-token material on platforms that reject hard links. - apps/…/running.ts, apps/…/ask.ts, and apps/…/commands.ts guard against stale records, PID reuse, and hostile local listeners. apps/…/commands.test.ts documents a prior review finding where unknown process starts could have led
stopto signal the wrong process; weakening identity/proof checks can send owner tokens or SIGTERM to the wrong local process. - apps/…/install.ts and apps/…/build-release.ts are memory-sensitive for session workers. Recent commits tuned worker V8 flags and bundle separation; if worker flags are dropped or the worker bundle starts importing server-side HTTP/plugin-build code, every session worker may pay significant memory/startup overhead, which apps/…/release.test.ts and apps/…/slice-1.ts are designed to catch.
- apps/…/bin.ts must import apps/…/minimum-node.ts before modules that require newer Node builtins or flags. If that ordering or the release launcher in apps/…/build-release.ts changes, old Node versions may fail during module linking instead of printing the clear minimum-Node error.