@kedem/okdb 1.9.2 → 2.0.0

package/public/setup.html

@@ -44,6 +44,9 @@
             --accent2:#16a34a;
         }
         * { box-sizing:border-box; }
+        /* Author rule for .field/.check sets display, which beats the UA [hidden]
+           rule — so make hidden authoritative for everything on this page. */
+        [hidden] { display:none !important; }
         body {
             margin:0;
             min-height:100vh;
@@ -59,13 +62,13 @@
             background: radial-gradient(circle at top, #c8dff5 0%, var(--bg0) 45%, #e8f2ff 100%);
         }
         .shell {
-            width:min(1000px, 100%);
+            width:min(440px, 100%);
             display:flex;
             flex-direction:column;
             gap:0;
         }
         .header {
-            margin-bottom:28px;
+            margin-bottom:24px;
             text-align:center;
         }
         .eyebrow {
@@ -73,13 +76,8 @@
             background:rgba(79,193,255,.12); color:var(--accent); font-size:12px; letter-spacing:.08em; text-transform:uppercase;
             border:1px solid rgba(79,193,255,.18);
         }
-        h1 { font-size:32px; line-height:1.1; margin:14px 0 6px; }
+        h1 { font-size:30px; line-height:1.1; margin:14px 0 6px; }
         .subtitle { color:var(--muted); font-size:15px; margin:0; }
-        .panels {
-            display:grid;
-            grid-template-columns:1fr 1fr;
-            gap:16px;
-        }
         .panel {
             background:rgba(8,16,26,.86);
             border:1px solid rgba(79,193,255,.16);
@@ -111,6 +109,24 @@
             background:linear-gradient(135deg, var(--accent2), #a8f0b4);
             box-shadow:0 10px 30px rgba(126,231,135,.18);
         }
+        /* Secondary, low-emphasis action (e.g. the "Join a cluster" entry point) */
+        .button.ghost {
+            background:transparent; color:var(--muted); border:1px solid rgba(255,255,255,.12);
+            box-shadow:none; font-weight:600; font-size:14px; padding:12px 16px;
+        }
+        .button.ghost:hover { filter:none; color:var(--text); border-color:rgba(79,193,255,.4); }
+        [data-theme='light'] .button.ghost { border-color:var(--line); }
+        .divider {
+            display:flex; align-items:center; gap:12px; color:var(--muted); font-size:12px;
+            text-transform:uppercase; letter-spacing:.08em;
+        }
+        .divider::before, .divider::after { content:''; flex:1; height:1px; background:rgba(255,255,255,.1); }
+        [data-theme='light'] .divider::before, [data-theme='light'] .divider::after { background:var(--line); }
+        .back {
+            align-self:flex-start; background:none; border:none; cursor:pointer; font-family:inherit;
+            color:var(--muted); font-size:13px; padding:0; margin-bottom:10px;
+        }
+        .back:hover { color:var(--text); }
         .error {
             padding:10px 12px; border-radius:10px;
             background:rgba(248,113,113,.12); border:1px solid rgba(248,113,113,.25); color:#fecaca;
@@ -121,11 +137,24 @@
             background:rgba(126,231,135,.1); border:1px solid rgba(126,231,135,.25); color:#a8f0b4;
             font-size:13px;
         }
-        @media (max-width:720px) {
-            .panels { grid-template-columns:1fr; }
-        }
         [data-theme='light'] .panel { background: rgba(255,255,255,.92); border-color: rgba(26,122,184,.2); }
         [data-theme='light'] .field input { background: var(--bg2); border-color: var(--line); }
+
+        /* Segmented credential toggle */
+        .segmented {
+            display:flex; border:1px solid rgba(255,255,255,.1); border-radius:12px; overflow:hidden;
+        }
+        .segmented button {
+            flex:1; background:transparent; color:var(--muted); border:none; cursor:pointer;
+            font-family:inherit; font-size:13px; font-weight:600; padding:10px 8px; transition:color .15s, background .15s;
+        }
+        .segmented button + button { border-left:1px solid rgba(255,255,255,.08); }
+        .segmented button.seg-active { background:#0b1420; color:var(--text); box-shadow:inset 0 0 0 1px rgba(79,193,255,.35); }
+        [data-theme='light'] .segmented { border-color:var(--line); }
+        [data-theme='light'] .segmented button.seg-active { background:var(--bg2); }
+        .check { display:flex; align-items:flex-start; gap:9px; font-size:13px; color:var(--muted); cursor:pointer; line-height:1.45; }
+        .check input { margin-top:2px; cursor:pointer; accent-color:var(--accent2); }
+        .hint { font-size:12px; color:var(--muted); line-height:1.5; margin:0; }
     </style>
 </head>
 <body>
@@ -133,57 +162,89 @@
         <header class="header">
             <div class="eyebrow">OKDB First-Time Setup</div>
             <h1>Welcome to OKDB</h1>
-            <p class="subtitle">This node has no credentials yet. Create an admin token or join an existing cluster.</p>
+            <p class="subtitle">This node has no credentials yet. Create an admin to get started.</p>
         </header>
 
-        <div class="panels">
-            <section class="panel" id="createPanel">
-                <div>
-                    <p class="panel-title">Create first admin token</p>
-                    <p class="panel-desc">Set up credentials for this node. You'll log in with these after setup.</p>
+        <!-- Create admin (default view) -->
+        <section class="panel" id="createView">
+            <div>
+                <p class="panel-title">Create your first admin</p>
+                <p class="panel-desc">Set up credentials for this node. You'll log in with these after setup.</p>
+            </div>
+            <form id="createForm" class="stack">
+                <div class="field">
+                    <label for="createName">Username</label>
+                    <input id="createName" name="name" value="admin" autocomplete="username" placeholder="admin">
                 </div>
-                <form id="createForm" class="stack">
-                    <div class="field">
-                        <label for="createName">Username</label>
-                        <input id="createName" name="name" value="admin" autocomplete="username" placeholder="admin">
-                    </div>
-                    <div class="field">
-                        <label for="createPassword">Password</label>
-                        <input id="createPassword" name="password" type="password" autocomplete="new-password" placeholder="••••••••">
-                    </div>
-                    <div class="field">
-                        <label for="createConfirm">Confirm password</label>
-                        <input id="createConfirm" name="confirm" type="password" autocomplete="new-password" placeholder="••••••••">
-                    </div>
-                    <div class="field">
-                        <label for="createLabel">Label <span style="color:var(--muted)">(optional)</span></label>
-                        <input id="createLabel" name="label" value="Initial admin" placeholder="Initial admin">
-                    </div>
-                    <div id="createError" class="error" hidden></div>
-                    <button type="submit" class="button">Create admin and continue</button>
-                </form>
-            </section>
+                <div class="field">
+                    <label for="createPassword">Password</label>
+                    <input id="createPassword" name="password" type="password" autocomplete="new-password" placeholder="••••••••">
+                </div>
+                <div class="field">
+                    <label for="createConfirm">Confirm password</label>
+                    <input id="createConfirm" name="confirm" type="password" autocomplete="new-password" placeholder="••••••••">
+                </div>
+                <div class="field">
+                    <label for="createLabel">Label <span style="color:var(--muted)">(optional)</span></label>
+                    <input id="createLabel" name="label" value="Initial admin" placeholder="Initial admin">
+                </div>
+                <div id="createError" class="error" hidden></div>
+                <button type="submit" class="button">Create admin and continue</button>
+            </form>
+
+            <div class="divider"><span>or</span></div>
+            <button type="button" id="showJoin" class="button ghost">Join an existing cluster</button>
+        </section>
 
-            <section class="panel" id="joinPanel">
-                <div>
-                    <p class="panel-title">Join an existing cluster</p>
-                    <p class="panel-desc">Connect to a running OKDB node. The cluster admin provides the sync token out-of-band.</p>
+        <!-- Join cluster (revealed on demand) -->
+        <section class="panel" id="joinView" hidden>
+            <div>
+                <button type="button" id="backToCreate" class="back">← Back</button>
+                <p class="panel-title">Join an existing cluster</p>
+                <p class="panel-desc">Connect to a running OKDB node. The credential is used once for the handshake — after that, sync authenticates with Ed25519 keys.</p>
+            </div>
+            <form id="joinForm" class="stack">
+                <div class="field">
+                    <label for="joinAddress">Remote node address</label>
+                    <input id="joinAddress" name="address" placeholder="http://node-a.example.com:8484">
                 </div>
-                <form id="joinForm" class="stack">
-                    <div class="field">
-                        <label for="joinAddress">Remote node address</label>
-                        <input id="joinAddress" name="address" placeholder="https://node-a.example.com:8484">
-                    </div>
-                    <div class="field">
-                        <label for="joinToken">Cluster sync token</label>
-                        <input id="joinToken" name="token" type="password" placeholder="cluster sync token">
+
+                <div class="field">
+                    <label>Authentication</label>
+                    <div class="segmented" id="joinAuthSeg">
+                        <button type="button" data-method="token" class="seg-active">Token</button>
+                        <button type="button" data-method="login">Login</button>
+                        <button type="button" data-method="none">None</button>
                     </div>
-                    <div id="joinError" class="error" hidden></div>
-                    <button type="submit" class="button green">Join cluster</button>
-                </form>
-            </section>
-        </div>
+                </div>
+
+                <div class="field" data-auth="token">
+                    <label for="joinToken">Cluster sync token</label>
+                    <input id="joinToken" name="token" type="password" placeholder="Bearer token from the cluster admin">
+                </div>
+
+                <div class="field" data-auth="login" hidden>
+                    <label for="joinUsername">Username</label>
+                    <input id="joinUsername" name="username" autocomplete="username" placeholder="Username on the remote node">
+                    <label for="joinPassword" style="margin-top:6px;">Password</label>
+                    <input id="joinPassword" name="password" type="password" autocomplete="current-password" placeholder="••••••••">
+                </div>
+
+                <div class="field" data-auth="none" hidden>
+                    <p class="hint">No credential is sent. This only works when the remote node is running in open mode.</p>
+                </div>
+
+                <label class="check">
+                    <input type="checkbox" id="joinDataLink" checked>
+                    <span>Sync data immediately <span style="opacity:.6">— unchecked links topology only</span></span>
+                </label>
+
+                <div id="joinError" class="error" hidden></div>
+                <button type="submit" class="button green">Join cluster</button>
+            </form>
+        </section>
     </main>
+
     <script type="module" src="setup-app.js"></script>
 </body>
 </html>

package/types/index.d.ts

@@ -74,7 +74,12 @@ export declare class OKDB {
     readonly events: EventEmitter;
 
     // ── Subsystems ────────────────────────────────────────────────────────────
-    readonly http: unknown;
+    readonly http: {
+        /** Start the built-in HTTP server (REST API + admin UI). Single-process only —
+         *  a `{ workers }` second argument throws HTTP_CLUSTER_REMOVED (okdb 2.0). */
+        listen(port: number, host?: string): unknown;
+        [key: string]: unknown;
+    };
     readonly auth: OKDBAuth;
     readonly log: unknown;
     readonly bus: unknown;
@@ -100,12 +105,37 @@ export declare class OKDB {
     // ── Lifecycle ─────────────────────────────────────────────────────────────
     open(): Promise<void>;
     close(): Promise<void>;
+    /** Resolved role flags. `engines`/`compaction` are fixed for the instance's
+     *  lifetime; `processors` reflects CURRENT participation (see processors.start/stop). */
+    readonly role: { readonly processors: boolean; readonly engines: boolean; readonly compaction: boolean };
+    /** Composite load signal for this node (cached 250 ms; safe to poll per claim).
+     *  score ≥ 1 ≈ at the documented distress limits — the standard admission policy is
+     *  `() => db.pressure().score < 1`. queuePending is workload context, not in the score. */
+    pressure(): {
+        writerStallMs: number;
+        writerDepth: number;
+        maxDurableLag: number;
+        queuePending: number;
+        loopLagMs: number;
+        score: number;
+    };
+    /** Processing participation control + status.
+     *  start(): begin participating — un-gate lease claiming; the first call also runs
+     *  the per-store view boot that open() skips on a non-participating node.
+     *  stop(): cease participating — finish in-flight quanta, release leases (peers
+     *  fail over), park registrations. Both idempotent; resolve true on state change. */
+    readonly processors: {
+        start(): Promise<boolean>;
+        stop(): Promise<boolean>;
+        status(): { participate: boolean; processors: unknown[] };
+        [key: string]: unknown;
+    };
 
     // ── Environment management ────────────────────────────────────────────────
     readonly default: OKDBEnvironment;
     env(name?: string): OKDBEnvironment;
-    /** Open a registered env on demand (companion to the `envs` constructor
-     *  option). Idempotent; throws ENV_NOT_FOUND for an unregistered name. */
+    /** Open a registered env on demand (envs always open lazily in okdb 2.0).
+     *  Idempotent; throws ENV_NOT_FOUND for an unregistered name. */
     openEnv(name: string): Promise<OKDBEnvironment>;
     createEnvironment(name: string, config?: OKDBEnvironmentConfig): Promise<OKDBEnvironment>;
     removeEnvironment(name: string, options?: { keepSubEnvs?: string[] }): Promise<OKDBRemoveEnvironmentResult>;

package/types/options.d.ts

@@ -18,7 +18,6 @@ export interface OKDBOptions {
     auth?: OKDBAuthOptions;
     sync?: OKDBSyncOptions;
     queue?: OKDBQueueOptions;
-    bus?: boolean | Record<string, unknown>;
     functions?: Record<string, unknown>;
     timeMachine?: OKDBTimeMachineOptions;
     runtimeDeclarations?: boolean;
@@ -28,14 +27,25 @@ export interface OKDBOptions {
      *  Defaults preserve full-role behavior; passive instances serve reads/writes
      *  but skip engines / async processors / compaction scheduling. */
     engines?: boolean;
-    asyncProcessors?: boolean;
-    compaction?: 'active' | 'passive';
-    http?: boolean;
-    /** Which registered envs open() eagerly opens: 'all' (default), 'core'
-     *  (~system/~log/default only), or an array of names (core + listed —
-     *  an unknown listed name makes open() throw). Use openEnv(name) to open
-     *  more on demand. */
-    envs?: 'all' | 'core' | string[];
+    /** okdb 2.0: INITIAL processing participation (claim every unclaimed `single` lease
+     *  and drain derived work — FTS, views, time-machine, embeddings). Default true.
+     *  false = not participating: claim nothing; reads/writes + inline processors still
+     *  run. Participation is dynamic — db.processors.start()/stop() flip it at runtime
+     *  (open with false + start() later = fast startup). Pass false for ephemeral
+     *  short-lived processes. */
+    processors?: boolean;
+    /** okdb 2.0: true = eligible to claim the per-env compaction lease,
+     *  false = passive (explicit env.compact() still works). */
+    compaction?: boolean;
+    /** Process-registry participation. false = invisible non-participant;
+     *  { name } labels this process in the admin's process list. */
+    processes?: boolean | { name?: string; kind?: string; register?: boolean; listenAddr?: string | null };
+    /** Auto-compaction thresholds; { enabled: false } (or OKDB_AUTO_COMPACT=0) disables. */
+    autoCompact?: { enabled?: boolean; [key: string]: unknown };
+    /** HTTP API options (e.g. defaultEnv for routes that omit :env). */
+    api?: { defaultEnv?: string; [key: string]: unknown };
+    /** Admin UI feature; false disables it entirely. */
+    admin?: boolean | Record<string, unknown>;
 }
 
 export interface OKDBAuthOptions {
@@ -90,7 +100,6 @@ export interface OKDBTimeMachineOptions {
 }
 
 export interface OKDBEnvironmentConfig {
-    sync?: boolean;
     durability?: 'strict' | 'balanced' | 'fast' | 'custom';
     lmdb?: Record<string, unknown>;
     compression?: boolean;

package/docs/worker-fleet.md

@@ -1,139 +0,0 @@
-# Workers — background-work placement over the root
-
-The worker population is OKDB's **inter-process placement layer**: a set of
-generic worker processes forked over one LMDB root that claim and execute
-background work — processor drains, queue jobs, function runs, and (FTS)
-snapshot bootstraps. There is no intra-process executor (the thread/process
-pool was removed in the runtime-model rework, P4): whoever holds a claim
-drains it **on its own loop in bounded quanta**, yielding between chunks.
-
-> **See also:** [Processors](processors.md) for the change-subscription **modes**
-> (`single`/`fanout`/`inline`), registration, and bootstrap — the _guarantee_ each
-> processor declares. This doc covers _where_ that work runs (population & placement);
-> processors.md covers _what_ a processor is.
-
-## Quick start
-
-```javascript
-const db = new OKDB('./data');
-await db.open();
-
-// Declare workers desired state. Root-keyed and idempotent: any instance may call
-// it any number of times; one population results.
-db.workers.ensure({ scale: 'auto' }); // default: min 0, backlog-driven
-
-// Tear down: scale:0 persists across restarts.
-await db.workers.destroy();
-```
-
-**Zero-config embedded behavior is unchanged** — no `ensure()` call means the
-instance self-processes exactly as before (end-of-tick async on its own loop,
-leases held uncontended).
-
-## `workers.ensure({scale})`
-
-| `scale` value      | Meaning                                                                                 |
-| ------------------ | --------------------------------------------------------------------------------------- |
-| `'auto'` (default) | Supervisor runs; starts at 0 workers; forks on backlog, retires to 0 when idle          |
-| `{ min, max }`     | Supervisor runs; always keeps at least `min` workers; elastic ceiling `max`             |
-| `0`                | Hard off — no supervisor, no workers (serverless, test runners, PID-limited containers) |
-
-```javascript
-// Auto-scaling (recommended default)
-db.workers.ensure({ scale: 'auto' });
-
-// Fixed floor with elastic ceiling
-db.workers.ensure({ scale: { min: 2, max: 8 } });
-
-// Hard off
-db.workers.ensure({ scale: 0 });
-```
-
-Workers are **homogeneous and anonymous**: every worker handles every job class
-(processing drains, queue definitions, function runs, bootstrap jobs). Any
-worker may claim any work unit — the claim IS the dispatcher.
-
-## Deployment shapes
-
-| shape                   | how                                                                                                                                                                     |
-| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| embedded, self-process  | default — nothing to configure                                                                                                                                          |
-| embedded + workers      | `db.workers.ensure({scale:'auto'})` — instance stops self-claiming when workers are up; resumes when they retire                                                        |
-| embedded + HTTP workers | `db.http.listen(port, { workers: N })` after `open()` — forks okdb's own passive HTTP worker entry (child-entry mode; your app never re-executes; built-in routes only) |
-| CLI server              | HTTP cluster (primary + N HTTP workers) is the `bin/okdb` default; add workers alongside                                                                                |
-
-## How placement works
-
-- **`processing: 'auto'`** (the default) resolves against the workers
-  desired-state:
-    - `scale:0` or no workers → self-process (today's behavior)
-    - `scale:'auto'` at 0 live workers → self-process; forks first worker → stop claiming; population retires to 0 → resume self-claiming
-    - `scale:{min,max}` → stop claiming immediately (workers are starting up)
-      A configured-but-dead population is **re-forked** by any `'auto'` instance
-      (recovery restores separation rather than absorbing the work).
-- Explicit `processing: 'main'` self-processes regardless of workers;
-  `'none'` never processes. The legacy `'threads'`/`'processes'` values warn
-  once and map to `'auto'` (the executor they selected was removed in P4).
-- **Supervisor**: a per-root `OKDBLock` lease elects one forker. The holder
-  forks/retires children to match desired-state, respawns crashes (backoff
-  250 ms→4 s, crash-loop guard 5-in-10 s), and recycles wedged workers (stats
-  heartbeat silent > 3× interval → SIGKILL + respawn). Supervisor death → its
-  children die with it (parent-death watch); any surviving instance acquires the
-  lease and re-forks from durable state.
-- **Shmbuf hard gate**: `workers.ensure({ scale: non-zero })` throws
-  `WORKERS_SHMBUF_REQUIRED` when the shmbuf native binding is missing (the
-  fallback shim is process-local; a multi-process write topology would corrupt
-  HLC/clock ordering). A persisted desired > 0 read by a fallback-mode instance
-  is treated as 0 + a warning.
-
-## Job classes
-
-| class        | mechanism                                                                                                                                                                                                                                                                    |
-| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `processing` | the existing per-(env,type) lease + retry; bus `POKE {env,type}` wakes the holder                                                                                                                                                                                            |
-| `queue`      | the verb is the placement: `queue.process(type, handler)` — in-process consumer; `queue.worker(type, module)` — the SHARED POOL (durable definition, declarative: no workers yet → jobs wait until `workers.ensure()`); `queue.spawn(type, module)` — dedicated forked child |
-| `functions`  | durable request/response rows (`~fn:requests`/`~fn:responses`) + PROC bus fast path (`OKDB_FN_LEGACY_POOL=1` forces the legacy runner pool)                                                                                                                                  |
-| `bootstrap`  | snapshot bootstraps route as one-shot worker jobs (v1: FTS only — durable per-index meta); ineligible/closure bootstraps run owner-local                                                                                                                                     |
-
-## Admission & elasticity
-
-Per worker: `maxLeases` (default 32, `OKDB_WORKERS_MAX_LEASES`), loop-lag gate —
-p99 > 200 ms (`OKDB_WORKERS_LAG_GATE_MS`) for 2 windows → stop claiming (resume
-below half the gate for 2 windows).
-
-The supervisor probes every `OKDB_WORKERS_SUPERVISE_MS` (default 10 s) and
-scales on four backlog signals, **all read from durable state** (never this
-instance's in-memory processor lag, which is self-cancelling on a self-claiming
-supervisor and inflates on a claim-gated one):
-
-- changelog lag — per-type heads vs the persisted `~proc:state` cursors
-  (high `OKDB_WORKERS_LAG_HIGH` default 10 000, low `OKDB_WORKERS_LAG_LOW`
-  default 1 000)
-- queue depth (`OKDB_WORKERS_QUEUE_HIGH` default 100, `_LOW` default 10)
-- function backlog — pending `~fn:requests` rows (`OKDB_WORKERS_FN_HIGH`
-  default 10)
-- pending routed-bootstrap job rows (any pending row counts as backlog)
-
-Scale-up respects `maxWorkers` (for `'auto'`: cores−1 or
-`OKDB_WORKERS_AUTO_MAX`) and holds at +1 until the last-forked worker comes
-online; scale-down floor is `minWorkers` (0 for `'auto'` — the population fully
-retires when idle). Cooldown: `OKDB_WORKERS_SCALE_COOLDOWN_MS` default 5 000 ms.
-
-## Ops
-
-- Workers are registry citizens: `kind:'worker'` rows under their supervisor,
-  with memory/CPU stats **and their processor states** (reported over the
-  stats IPC channel) — the registry's `processorsView()` shows the
-  claim-holder's row as the truth for each 1-of-N key, so the UI says
-  "online on worker pid N", not "paused". Decommission/recommission/kill route
-  through the supervisor's reconcile loop (durable slot records).
-- Status honesty: a `processing:'auto'` instance that released its claims
-  reports `claimGated: true` (rendered as `delegated`, never `paused`) and
-  `heldBy: {pid, hostname}` from the live lease record; a worker-routed
-  bootstrap surfaces `progress: {phase:'bootstrap', placement:'worker',
-state, claimedBy}`.
-- Per-drain deadlines (`drainDeadlineMs`, default 60 s) mark a slow processor
-  errored (lease retained, in-place retry); a truly wedged worker (silent stats)
-  is recycled by the supervisor.
-- Runtime mode switching: `processor.setMode(logicalKey, mode)` /
-  `POST /api/processors/:logicalKey/mode` — see `docs/processors.md`.