@timqi/pier 0.1.0 → 0.1.1

package/dist/web/session-state.js

@@ -1,42 +1,12 @@
 // What the workbench decided about a session, and nothing a transcript already
-// knows. A finished turn nobody has looked at (`unread`), and the rail's
-// working set: the rank of a row kept on top (`sort`).
-//
-// The working set replaced pinning and dragging. Ordering the rail by activity
-// made it jump — a scheduled task, a subagent, anyone's Slack message moved the
-// row somebody was about to click — and ordering it by hand asked for the
-// arranging. So: a session enters the set at the front when a human speaks to
-// it and it is not in the set already, and members never move relative to each
-// other until one is pushed out of the last slot. A three-week-old session is
-// back on top the moment it is used; the four you switch between hold still.
-//
-// Remembered rather than derived on purpose: "the last time a human spoke" is
-// there in the transcript and still jumps, because it reorders on every
-// message. Only an order nothing recomputes can hold still.
-//
-// It used to mirror the summary too — cwd, title, created_at, last_active —
-// because listing sessions meant parsing every transcript on disk (~237ms) and
-// the rail could not pay that on every read. agent/listing.ts made a listing
-// cheap, so the mirror bought nothing and cost two stores kept in step: a
-// backfill gate, a repair pass on every full listing, a touch at the end of
-// every turn, a title write on the first prompt, a second write on rename.
-// Deriving beats syncing; all of it is gone.
-//
-// `cwd` and `project_sort` stayed as columns nothing reads: they keyed the
-// per-directory order the rail no longer has (migration 19).
-//
-// The rank does not bring that back: it is written only when a session outside
-// the set is spoken to, not once per turn.
-//
-// One row per session rather than two JSON files: the unread flag is written at
-// the end of every turn, and rewriting a whole file on each of those writes
-// loses the entire set when the process dies mid-write — a truncated file reads
-// back as "nothing on top", which is indistinguishable from a fresh install.
+// knows: a finished turn nobody looked at (`unread`), and the rail's working
+// set (`sort`). A session enters the set at the front when a human speaks to it
+// and it is not already in; members never move relative to each other until one
+// is pushed out. Remembered, not derived: any order recomputed from activity
+// jumps on every message. `cwd` and `project_sort` are columns nothing reads.
 import { pierDb, transact } from "../db.js";
-/** How many rows the rail keeps on top. The handful anybody actually switches
- *  between, and small enough that every member is somewhere a hand can see: a
- *  set as deep as the page (20) would count a row nobody has scrolled to as
- *  "already up there" and never bring it back. */
+/** Small enough that every member is where a hand can see it: a set as deep as
+ *  the page would count a row nobody scrolled to as "already up there". */
 export const WORKING_SET = 5;
 export class SessionStateStore {
     #db;
@@ -51,14 +21,10 @@ export class SessionStateStore {
         this.#db.prepare(`INSERT INTO session_state(session_id, unread) VALUES (?, ?)
        ON CONFLICT(session_id) DO UPDATE SET unread = excluded.unread`).run(sessionId, unread ? 1 : 0);
     }
-    /** A human spoke to this session. Already in the working set → nothing moves
-     *  and nothing is written; otherwise it takes the front slot and whatever
-     *  sat in the last one falls out. Answers whether the order changed, so the
-     *  caller broadcasts a re-list only when there is something to see. */
+    /** Already in the working set: nothing moves. Answers whether the order
+     *  changed, so the caller re-lists only when there is something to see. */
     promote(sessionId) {
-        // `session_id` breaks a tie the migration can leave behind: several pinned
-        // rows nobody ever dragged share rank -1 until the first promotion
-        // renumbers them.
+        // `session_id` breaks a tie migration 20 can leave behind (several rows at -1).
         const ranked = this.#db.prepare("SELECT session_id AS id FROM session_state WHERE sort IS NOT NULL ORDER BY sort, session_id").all().map((r) => r.id);
         if (ranked.includes(sessionId))
             return false;
@@ -67,8 +33,7 @@ export class SessionStateStore {
         const rank = this.#db.prepare(`INSERT INTO session_state(session_id, sort) VALUES (?, ?)
        ON CONFLICT(session_id) DO UPDATE SET sort = excluded.sort`);
         const drop = this.#db.prepare("UPDATE session_state SET sort = NULL WHERE session_id = ?");
-        // Every rank rewritten rather than the new one prepended: the places are
-        // 0..n and a half-renumbered set is an order nobody would recognize.
+        // Every rank rewritten: a half-renumbered set is an order nobody would recognize.
         transact(this.#db, () => {
             kept.forEach((id, i) => rank.run(id, i));
             for (const id of evicted)
@@ -76,16 +41,11 @@ export class SessionStateStore {
         });
         return true;
     }
-    /** Drop a session's organization row entirely — rank and unread. For
-     *  ghosts: Pi persists a session only once its first assistant reply lands,
-     *  so a created-and-never-messaged one cannot be resumed, and its remembered
-     *  row would otherwise sit in the rail 404ing forever — holding a slot in the
-     *  working set while it does. */
+    /** For ghosts: a created-and-never-messaged session cannot be resumed, and
+     *  its row would otherwise hold a working-set slot while 404ing forever. */
     forget(sessionId) {
         this.#db.prepare("DELETE FROM session_state WHERE session_id = ?").run(sessionId);
     }
-    /** What this store knows about the sessions it knows anything about, for a
-     *  caller holding the listing. */
     flags() {
         const rows = this.#db.prepare(`SELECT session_id AS id, unread, sort
        FROM session_state WHERE unread = 1 OR sort IS NOT NULL`).all();

package/dist/web/types.js

@@ -1,5 +1,3 @@
-// The shapes web's HTTP answers carry beyond the stores they come from — the
-// area's own wire vocabulary, and the one file in web/ the browser may import
-// type-only (docs/architecture.md, same rule as tasks/types.ts). Nothing here
-// runs: no imports, no values, so a page pays nothing for reading it.
+// The area's own wire vocabulary, and the one file in web/ the browser may
+// import type-only (docs/architecture.md). No imports, no values.
 export {};

package/dist/web/webpush.js

@@ -1,19 +1,13 @@
-// The Web Push wire format, and only that: RFC 8291 message encryption
-// (ECDH P-256 → HKDF → one aes128gcm record) and RFC 8292 VAPID
-// authorization. Who is notified, and why, is push.ts.
-//
-// Written on node:crypto instead of pulled in: the whole format is one ECDH,
-// two HKDFs, one AES-GCM record and a JWT, and every step of it has a
-// published test vector (webpush.test.ts runs the RFC's). A dependency here
-// would be new transitive code inside the process that holds the operator's
-// provider keys, buying ~120 lines (principle 8).
+// The Web Push wire format: RFC 8291 message encryption (ECDH P-256 → HKDF →
+// one aes128gcm record) and RFC 8292 VAPID. On node:crypto rather than a
+// dependency: every step has a published test vector, and a dependency here is
+// transitive code inside the process holding the provider keys (principle 8).
 import { createCipheriv, createECDH, createPrivateKey, hkdfSync, randomBytes, sign } from "node:crypto";
 /** RFC 8291 §4: one record, and a push service need not accept more than 4096
  *  octets of body. Header (86) + padding (1) + GCM tag (16) leaves this. */
 export const MAX_PUSH_PLAINTEXT = 3993;
 const RECORD_SIZE = 4096;
-/** VAPID token lifetime. Apple refuses anything past 24h; half a day is well
- *  inside every push service's limit and still outlives a slow retry. */
+/** Apple refuses anything past 24h. */
 const TOKEN_TTL_S = 12 * 60 * 60;
 const REQUEST_TIMEOUT_MS = 10_000;
 const b64 = (b) => Buffer.from(b instanceof ArrayBuffer ? new Uint8Array(b) : b).toString("base64url");
@@ -29,13 +23,8 @@ export function generateVapidKeys() {
         privateKey: b64(pad32(ecdh.getPrivateKey())),
     };
 }
-/**
- * Encrypt one push message for `target` (RFC 8291 §3.4, RFC 8188 header).
- *
- * `salt` and `serverKey` are injectable for exactly one reason: the RFC's
- * worked example is the only way to prove this implementation is right, and it
- * fixes both. Nothing else may pass them — a reused salt is a broken cipher.
- */
+/** RFC 8291 §3.4, RFC 8188 header. `salt` and `serverKey` are injectable only
+ *  for the RFC's worked example; a reused salt is a broken cipher. */
 export function encryptPush(plaintext, target, { salt = randomBytes(16), serverKey } = {}) {
     const body = Buffer.from(plaintext);
     if (body.length > MAX_PUSH_PLAINTEXT) {
@@ -68,9 +57,7 @@ export function encryptPush(plaintext, target, { salt = randomBytes(16), serverK
     header.writeUInt8(asPublic.length, 20);
     return Buffer.concat([header, asPublic, sealed]);
 }
-/** The `Authorization` a push service checks before it accepts anything: a
- *  short-lived ES256 JWT bound to the service's own origin, plus the public
- *  key the subscription was created with (RFC 8292 §3). */
+/** RFC 8292 §3: an ES256 JWT bound to the service's origin, plus the public key. */
 export function vapidAuthorization(endpoint, keys, subject, now = Date.now()) {
     const token = [
         b64(Buffer.from(JSON.stringify({ typ: "JWT", alg: "ES256" }))),
@@ -95,8 +82,7 @@ export function vapidAuthorization(endpoint, keys, subject, now = Date.now()) {
     const signature = sign("sha256", Buffer.from(token), { key, dsaEncoding: "ieee-p1363" });
     return `vapid t=${token}.${b64(signature)}, k=${keys.publicKey}`;
 }
-/** POST one encrypted message. Never throws: every outcome is a result the
- *  caller can log or act on. */
+/** Never throws: every outcome is a result the caller can log or act on. */
 export async function sendPush(target, payload, keys, subject, ttlSeconds = 4 * 60 * 60, fetchImpl = fetch) {
     let body;
     try {
@@ -120,8 +106,7 @@ export async function sendPush(target, payload, keys, subject, ttlSeconds = 4 *
         });
         if (res.ok)
             return { status: res.status };
-        // The service's own sentence is the only thing that explains a 400 from
-        // Apple or a 403 from FCM; without it the operator sees a bare number.
+        // The service's own sentence is the only thing that explains a 400 from Apple.
         const said = (await res.text().catch(() => "")).slice(0, 200);
         return { status: res.status, error: said || res.statusText };
     }