@hraness/sponge 0.2.3 → 0.2.5

package/dist/src/portability/database.js

@@ -62,6 +62,9 @@ export function neutralizeRestoredDatabase(path) {
             db.exec("UPDATE index_jobs SET state='failed',reason='restore-reconciliation-required' WHERE state NOT IN ('succeeded','failed','cancelled')");
             db.prepare("UPDATE index_attempts SET stage='restored-unexecuted',cleanup='settled',finished_at=COALESCE(finished_at,?) WHERE cleanup='pending' OR finished_at IS NULL").run(new Date().toISOString());
         }
+        // A restored copy is a new device of the same library: a fresh device id keeps its HLCs distinct; clock_ms only moves forward.
+        if (inspected.schemaVersion >= 5)
+            db.exec('UPDATE device SET device_id=lower(hex(randomblob(16))) WHERE id=1');
         db.exec('COMMIT; PRAGMA journal_mode=DELETE');
         return { incarnation, heldJobs: Number(held.changes) };
     }

package/dist/src/publish/component.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `<sponge-list src="feed.json" limit="20" verify>`: a dependency-free custom element. It builds DOM from a
+ * fixed tag set with textContent only and links only http(s) URLs. `verify` checks the Ed25519-signed manifest
+ * with WebCrypto first; `verify="KEY"` pins the publisher's key. The source stays ASCII so any charset serves it.
+ */
+export declare const componentSource: string;
+/** A complete static page around the component; it carries the feed title only. */
+export declare function indexHtml(title: string): string;

package/dist/src/publish/component.js

@@ -0,0 +1,114 @@
+/**
+ * `<sponge-list src="feed.json" limit="20" verify>`: a dependency-free custom element. It builds DOM from a
+ * fixed tag set with textContent only and links only http(s) URLs. `verify` checks the Ed25519-signed manifest
+ * with WebCrypto first; `verify="KEY"` pins the publisher's key. The source stays ASCII so any charset serves it.
+ */
+export const componentSource = String.raw `/* sponge-list: renders a Sponge reading-list feed. */
+(() => {
+  'use strict';
+  const web = u => { if (typeof u !== 'string') return null; try { const x = new URL(u); return x.protocol === 'https:' || x.protocol === 'http:' ? x.href : null; } catch (e) { return null; } };
+  const str = v => typeof v === 'string' && v.length > 0;
+  const obj = v => v && typeof v === 'object' && !Array.isArray(v) ? v : {};
+  const list = v => Array.isArray(v) ? v : [];
+  /** Feed JSON to a plain node tree: { t: tag, p: part, a: attributes, x: text, c: children }. */
+  function view(feed, limit) {
+    const items = list(obj(feed).items).filter(i => str(obj(i).title)).slice(0, limit);
+    return { t: 'ol', p: 'list', c: items.map(i => {
+      const s = obj(i._sponge), d = obj(s.digest), href = web(i.url), day = str(i.date_published) ? i.date_published.slice(0, 10) : null;
+      const meta = [str(s.site) ? { t: 'span', p: 'site', x: s.site } : null, day ? { t: 'time', p: 'date', a: { datetime: day }, x: day } : null].filter(Boolean);
+      const ideas = list(d.ideas).filter(x => str(obj(x).claim)).map(x => {
+        const more = [str(x.detail) ? { t: 'p', p: 'detail', x: x.detail } : null, ...list(x.quotes).filter(str).map(q => ({ t: 'blockquote', p: 'quote', x: q }))].filter(Boolean);
+        return { t: 'li', p: 'idea', c: [more.length ? { t: 'details', p: 'idea-body', c: [{ t: 'summary', p: 'claim', x: x.claim }, ...more] } : { t: 'span', p: 'claim', x: x.claim }] };
+      });
+      return { t: 'li', p: 'item', c: [href ? { t: 'a', p: 'title', a: { href }, x: i.title } : { t: 'span', p: 'title', x: i.title }, ...(meta.length ? [{ t: 'div', p: 'meta', c: meta }] : []), ...(str(d.lead) ? [{ t: 'p', p: 'lead', x: d.lead }] : []), ...(ideas.length ? [{ t: 'ul', p: 'ideas', c: ideas }] : [])] };
+    }) };
+  }
+  const tags = new Set(['ol', 'ul', 'li', 'a', 'span', 'div', 'time', 'p', 'details', 'summary', 'blockquote']);
+  /** Only known tags and attributes; text goes through textContent, never markup. */
+  function build(doc, n) {
+    if (!tags.has(n.t)) throw new Error('tag');
+    const e = doc.createElement(n.t), a = obj(n.a);
+    e.setAttribute('part', n.p);
+    if (n.t === 'a') { const h = web(a.href); if (!h) throw new Error('href'); e.setAttribute('href', h); e.setAttribute('rel', 'noopener noreferrer'); }
+    if (n.t === 'time' && str(a.datetime)) e.setAttribute('datetime', a.datetime);
+    if (n.x !== undefined) e.textContent = String(n.x); else for (const c of list(n.c)) e.appendChild(build(doc, c));
+    return e;
+  }
+  const bytes64 = s => { const v = String(s).trim().replace(/-/g, '+').replace(/_/g, '/'), b = atob(v + '='.repeat((4 - v.length % 4) % 4)); return Uint8Array.from(b, c => c.charCodeAt(0)); };
+  const hex = b => Array.from(new Uint8Array(b), x => x.toString(16).padStart(2, '0')).join('');
+  /** True only when the signature over the exact manifest bytes holds and the feed's bytes match its entry. */
+  async function verify(subtle, manifestBytes, signature, feedBytes, feedPath, pinned) {
+    try { return await check(subtle, manifestBytes, signature, feedBytes, feedPath, pinned); } catch (e) { return false; }
+  }
+  async function check(subtle, manifestBytes, signature, feedBytes, feedPath, pinned) {
+    const m = obj(JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(manifestBytes)));
+    if (m.algorithm !== 'Ed25519' || !str(m.publicKey) || (pinned && pinned !== m.publicKey)) return false;
+    const key = await subtle.importKey('raw', bytes64(m.publicKey), { name: 'Ed25519' }, false, ['verify']);
+    if (!await subtle.verify({ name: 'Ed25519' }, key, bytes64(signature), manifestBytes)) return false;
+    const entry = list(m.files).find(f => obj(f).path === feedPath);
+    return !!entry && entry.bytes === feedBytes.byteLength && entry.sha256 === hex(await subtle.digest('SHA-256', feedBytes));
+  }
+  const css = ':host{display:block;font:var(--sponge-font,inherit);color:var(--sponge-color,inherit)}' +
+    'ol{list-style:none;margin:0;padding:0;display:grid;gap:var(--sponge-gap,1.25em)}ul{margin:.4em 0 0;padding-left:1.1em}' +
+    '[part~=title]{font-weight:600;color:var(--sponge-link,inherit)}[part~=meta]{color:var(--sponge-muted,#666);font-size:.875em}' +
+    '[part~=meta]>*+*::before{content:" ' + String.fromCharCode(183) + ' "}[part~=lead]{margin:.4em 0}summary{cursor:pointer}[part~=detail]{margin:.3em 0}' +
+    'blockquote{margin:.3em 0;padding-left:.75em;border-left:2px solid var(--sponge-rule,#ccc);color:var(--sponge-muted,#666)}';
+  const Base = typeof HTMLElement === 'undefined' ? class {} : HTMLElement;
+  class SpongeList extends Base {
+    static get observedAttributes() { return ['src', 'limit', 'verify', 'manifest']; }
+    connectedCallback() { this.schedule(); }
+    attributeChangedCallback() { this.schedule(); }
+    /** Upgrading reports each attribute, then the connection; load once for all of them. */
+    schedule() { if (this.pending) return; this.pending = true; queueMicrotask(() => { this.pending = false; if (this.isConnected) this.load(); }); }
+    async load() {
+      const run = this.run = (this.run || 0) + 1, root = this.shadowRoot || this.attachShadow({ mode: 'open' });
+      const fail = reason => { if (run !== this.run) return; root.replaceChildren(); this.dispatchEvent(new CustomEvent('error', { detail: { reason } })); };
+      try {
+        const get = async u => { const r = await fetch(u, { credentials: 'omit' }); if (!r.ok) throw new Error('fetch'); return new Uint8Array(await r.arrayBuffer()); };
+        const src = new URL(this.getAttribute('src') || 'feed.json', document.baseURI), n = Number(this.getAttribute('limit') || 20), limit = Number.isInteger(n) && n > 0 ? Math.min(n, 1000) : 20;
+        const body = await get(src), feed = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(body));
+        if (this.hasAttribute('verify')) {
+          const at = this.getAttribute('manifest') || (str(obj(obj(feed)._sponge).manifest) ? feed._sponge.manifest : 'index.json'), manifest = new URL(at, src), dir = new URL('.', manifest).href;
+          if (src.search || src.hash || !src.href.startsWith(dir)) return fail('verify');
+          const [m, sig] = await Promise.all([get(manifest), get(new URL(manifest.pathname + '.sig', manifest))]);
+          if (!await verify(crypto.subtle, m, new TextDecoder().decode(sig), body, src.href.slice(dir.length), this.getAttribute('verify') || null)) return fail('verify');
+        }
+        if (run !== this.run) return;
+        const style = document.createElement('style');
+        style.textContent = css;
+        root.replaceChildren(style, build(document, view(feed, limit)));
+      } catch (e) { fail(e && e.message === 'fetch' ? 'fetch' : 'invalid'); }
+    }
+  }
+  SpongeList.view = view; SpongeList.build = build; SpongeList.verify = verify; SpongeList.safeHref = web;
+  if (typeof customElements !== 'undefined' && !customElements.get('sponge-list')) customElements.define('sponge-list', SpongeList);
+})();
+`;
+const html = (s) => s.replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
+/** A complete static page around the component; it carries the feed title only. */
+export function indexHtml(title) {
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${html(title)}</title>
+<link rel="alternate" type="application/feed+json" href="feed.json">
+<link rel="alternate" type="application/atom+xml" href="feed.xml">
+<style>
+:root{color-scheme:light dark;--sponge-muted:#6b6b6b}
+@media (prefers-color-scheme:dark){:root{--sponge-muted:#a0a0a0;--sponge-rule:#444}}
+body{margin:0 auto;max-width:42rem;padding:2rem 1rem;font:16px/1.5 system-ui,sans-serif}
+h1{font-size:1.5rem}footer{margin-top:3rem;font-size:.875rem;color:var(--sponge-muted)}
+</style>
+</head>
+<body>
+<h1>${html(title)}</h1>
+<sponge-list src="feed.json" limit="100" verify></sponge-list>
+<noscript><p><a href="feed.json">JSON Feed</a> · <a href="feed.xml">Atom</a></p></noscript>
+<footer><a href="feed.xml">Atom</a> · <a href="feed.json">JSON Feed</a> · <a href="identity.json">Signing key</a></footer>
+<script src="sponge-list.js" defer></script>
+</body>
+</html>
+`;
+}

package/dist/src/publish/feed.d.ts

@@ -0,0 +1,24 @@
+import type { PublicEntry } from '../store/foundation.js';
+/** feed.json and feed.xml carry the newest entries; every entry also lives in its month's shard. */
+export declare const feedLimit = 100;
+export declare const manifestPath = "index.json", signaturePath = "index.json.sig";
+export interface PublicIdentity {
+    algorithm: 'Ed25519';
+    publicKey: string;
+    created: string;
+}
+export interface SiteOptions {
+    title: string;
+    baseUrl?: string;
+}
+/** Sorted keys, no whitespace, undefined fields dropped: equal values always give equal bytes. */
+export declare function canonical(value: unknown): string;
+/** An https origin and path, with no credentials, query or fragment, ending in `/`. */
+export declare function baseUrl(value: string): string;
+/** XML 1.0 text and attribute escaping; characters XML cannot carry become U+FFFD. */
+export declare function xml(value: string): string;
+/**
+ * Every file of the static site, keyed by path, from the projection alone. Pure and deterministic:
+ * no clock, no randomness, sorted keys. The manifest lists each file's sha256 and is signed once.
+ */
+export declare function buildSite(entries: PublicEntry[], identity: PublicIdentity, options: SiteOptions, sign: (bytes: Uint8Array) => Uint8Array): Map<string, Buffer>;

package/dist/src/publish/feed.js

@@ -0,0 +1,77 @@
+import { createHash } from 'node:crypto';
+import { StoreError } from '../store/types.js';
+import { componentSource, indexHtml } from './component.js';
+/** feed.json and feed.xml carry the newest entries; every entry also lives in its month's shard. */
+export const feedLimit = 100;
+export const manifestPath = 'index.json', signaturePath = 'index.json.sig';
+const about = 'https://github.com/hraness/sponge/blob/main/docs/decisions/publish-feed.md';
+const fail = (code = 'integrity') => { throw new StoreError(code); };
+/** Sorted keys, no whitespace, undefined fields dropped: equal values always give equal bytes. */
+export function canonical(value) {
+    if (Array.isArray(value))
+        return '[' + value.map(canonical).join(',') + ']';
+    if (value && typeof value === 'object')
+        return '{' + Object.keys(value).sort().filter(k => value[k] !== undefined).map(k => JSON.stringify(k) + ':' + canonical(value[k])).join(',') + '}';
+    if (typeof value === 'number' && !Number.isSafeInteger(value) || !['string', 'number', 'boolean'].includes(typeof value) && value !== null)
+        fail();
+    return JSON.stringify(value);
+}
+/** An https origin and path, with no credentials, query or fragment, ending in `/`. */
+export function baseUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch { /* rejected below */ }
+    if (!url || url.protocol !== 'https:' || url.username || url.password || /[?#]/.test(value) || value.length > 2048)
+        fail('invalid-input');
+    return url.href.endsWith('/') ? url.href : url.href + '/';
+}
+const web = (uri) => /^https?:\/\//.test(uri);
+const xmlInvalid = /[^\t\n\r -퟿-�\u{10000}-\u{10ffff}]/gu;
+const xmlEntities = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&apos;' };
+/** XML 1.0 text and attribute escaping; characters XML cannot carry become U+FFFD. */
+export function xml(value) { return value.replace(xmlInvalid, '�').replace(/[&<>"']/g, c => xmlEntities[c]); }
+const date = (e) => /^\d{4}-\d{2}-\d{2}$/.test(e.listedOn) ? e.listedOn + 'T00:00:00Z' : fail();
+const summaryText = (e) => [e.digest?.lead, ...(e.digest?.ideas ?? []).map(i => '- ' + i.claim)].filter(Boolean).join('\n') || e.title;
+function item(e) {
+    return { id: e.uri, url: web(e.uri) ? e.uri : undefined, title: e.title, content_text: summaryText(e), summary: e.digest?.lead, date_published: date(e), authors: e.authors ? [{ name: e.authors }] : undefined,
+        _sponge: { uri: e.uri, aliases: e.aliases, kind: e.kind, site: e.site, published: e.published, digest: e.digest } };
+}
+function atom(entries, identity, options) {
+    const base = options.baseUrl, updated = entries.length ? date(entries.reduce((a, b) => b.listedOn > a.listedOn ? b : a)) : identity.created + 'T00:00:00Z';
+    const lines = ['<?xml version="1.0" encoding="utf-8"?>', '<feed xmlns="http://www.w3.org/2005/Atom">', `<id>tag:sponge.computer,2026:feed/${xml(identity.publicKey)}</id>`, `<title>${xml(options.title)}</title>`, `<updated>${updated}</updated>`, `<author><name>${xml(options.title)}</name></author>`, '<generator>Sponge</generator>',
+        ...(base ? [`<link rel="self" type="application/atom+xml" href="${xml(base + 'feed.xml')}"/>`, `<link rel="alternate" type="text/html" href="${xml(base)}"/>`] : [])];
+    for (const e of entries)
+        lines.push('<entry>', `<id>${xml(e.uri)}</id>`, `<title>${xml(e.title)}</title>`, ...(web(e.uri) ? [`<link rel="alternate" href="${xml(e.uri)}"/>`] : []), `<updated>${date(e)}</updated>`, ...(e.authors ? [`<author><name>${xml(e.authors)}</name></author>`] : []), ...(e.digest?.lead ? [`<summary>${xml(e.digest.lead)}</summary>`] : []), `<content type="text">${xml(summaryText(e))}</content>`, '</entry>');
+    return lines.concat('</feed>', '').join('\n');
+}
+/**
+ * Every file of the static site, keyed by path, from the projection alone. Pure and deterministic:
+ * no clock, no randomness, sorted keys. The manifest lists each file's sha256 and is signed once.
+ */
+export function buildSite(entries, identity, options, sign) {
+    if (identity.algorithm !== 'Ed25519' || !/^[A-Za-z0-9_-]{43}$/.test(identity.publicKey) || !/^\d{4}-\d{2}-\d{2}$/.test(identity.created))
+        fail();
+    const base = options.baseUrl, link = (from, to) => base ? base + to : from.includes('/') && to.startsWith(from.slice(0, from.lastIndexOf('/') + 1)) ? to.slice(from.lastIndexOf('/') + 1) : to;
+    const months = new Map();
+    for (const e of entries) {
+        const month = date(e).slice(0, 7);
+        months.set(month, [...months.get(month) ?? [], e]);
+    }
+    const order = [...months.keys()].sort().reverse(), shard = (month) => `items/${month}.json`;
+    const signed = { about, schemaVersion: 1, algorithm: identity.algorithm, publicKey: identity.publicKey };
+    const feed = (path, list, next, extra) => Buffer.from(canonical({ version: 'https://jsonfeed.org/version/1.1', title: options.title, home_page_url: base, feed_url: base && base + path, next_url: next && link(path, next), items: list.map(item), _sponge: { ...signed, manifest: link(path, manifestPath), ...extra } }) + '\n');
+    const files = new Map(), head = entries.slice(0, feedLimit), omitted = entries[feedLimit];
+    files.set('feed.json', feed('feed.json', head, omitted && shard(date(omitted).slice(0, 7)), { total: entries.length, shards: order.map(m => ({ month: m, url: link('feed.json', shard(m)), items: months.get(m).length })) }));
+    order.forEach((m, i) => files.set(shard(m), feed(shard(m), months.get(m), order[i + 1] && shard(order[i + 1]), { month: m })));
+    files.set('feed.xml', Buffer.from(atom(head, identity, options)));
+    files.set('identity.json', Buffer.from(canonical({ schemaVersion: 1, algorithm: identity.algorithm, publicKey: identity.publicKey, created: identity.created }) + '\n'));
+    files.set('sponge-list.js', Buffer.from(componentSource));
+    files.set('index.html', Buffer.from(indexHtml(options.title)));
+    const listed = [...files.keys()].sort().map(path => ({ path, bytes: files.get(path).length, sha256: createHash('sha256').update(files.get(path)).digest('hex') }));
+    const manifest = Buffer.from(canonical({ ...signed, files: listed }) + '\n');
+    files.set(manifestPath, manifest);
+    files.set(signaturePath, Buffer.from(Buffer.from(sign(manifest)).toString('base64url') + '\n'));
+    return new Map([...files.entries()].sort(([a], [b]) => a < b ? -1 : 1));
+}

package/dist/src/publish/identity.d.ts

@@ -0,0 +1,6 @@
+import type { PublicIdentity } from './feed.js';
+export interface Identity extends PublicIdentity {
+    sign(bytes: Uint8Array): Buffer;
+}
+/** The publishing key never leaves the library: `keys/publish-ed25519.json`, mode 0600 inside a 0700 directory. */
+export declare function publishIdentity(root: string): Identity;

package/dist/src/publish/identity.js

@@ -0,0 +1,68 @@
+import { chmodSync, closeSync, constants, fstatSync, fsyncSync, linkSync, openSync, readFileSync, unlinkSync } from 'node:fs';
+import { createPrivateKey, createPublicKey, generateKeyPairSync, randomUUID, sign } from 'node:crypto';
+import { join } from 'node:path';
+import { pathExists, regularFile, safeDirectory, syncDirectory } from '../store/files.js';
+import { StoreError } from '../store/types.js';
+import { writeAll } from '../portability/files.js';
+const fail = () => { throw new StoreError('integrity'); };
+const b64 = (v, n) => typeof v === 'string' && new RegExp(`^[A-Za-z0-9_-]{${n}}$`).test(v) ? v : fail();
+/** The publishing key never leaves the library: `keys/publish-ed25519.json`, mode 0600 inside a 0700 directory. */
+export function publishIdentity(root) {
+    const dir = safeDirectory(join(root, 'keys'), true);
+    chmodSync(dir, 0o700);
+    const path = join(dir, 'publish-ed25519.json');
+    if (!pathExists(path))
+        create(dir, path);
+    return load(path);
+}
+/** Write a temporary file, then hard-link it into place, so a concurrent first publish keeps one key. */
+function create(dir, path) {
+    const jwk = generateKeyPairSync('ed25519').privateKey.export({ format: 'jwk' });
+    const body = JSON.stringify({ schemaVersion: 1, algorithm: 'Ed25519', created: new Date().toISOString().slice(0, 10), privateKey: { kty: jwk.kty, crv: jwk.crv, x: jwk.x, d: jwk.d } }) + '\n';
+    const temp = join(dir, randomUUID() + '.tmp'), fd = openSync(temp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    try {
+        writeAll(fd, Buffer.from(body));
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    try {
+        linkSync(temp, path);
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST') {
+            unlinkSync(temp);
+            throw error;
+        }
+    }
+    unlinkSync(temp);
+    syncDirectory(dir);
+}
+function load(path) {
+    regularFile(path);
+    const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    let raw;
+    try {
+        const stat = fstatSync(fd);
+        if (!stat.isFile() || (stat.mode & 0o777) !== 0o600 || stat.size > 4096 || stat.uid !== process.getuid?.())
+            fail();
+        raw = readFileSync(fd, 'utf8');
+    }
+    finally {
+        closeSync(fd);
+    }
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        fail();
+    }
+    if (!value || value.schemaVersion !== 1 || value.algorithm !== 'Ed25519' || typeof value.created !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(value.created) || value.privateKey?.kty !== 'OKP' || value.privateKey?.crv !== 'Ed25519')
+        fail();
+    const x = b64(value.privateKey.x, 43), key = createPrivateKey({ key: { kty: 'OKP', crv: 'Ed25519', x, d: b64(value.privateKey.d, 43) }, format: 'jwk' });
+    if (createPublicKey(key).export({ format: 'jwk' }).x !== x)
+        fail();
+    return { algorithm: 'Ed25519', created: value.created, publicKey: x, sign: bytes => sign(null, bytes, key) };
+}

package/dist/src/publish/index.d.ts

@@ -0,0 +1,34 @@
+import type { PublicEntry } from '../store/foundation.js';
+export { buildSite, canonical, xml, feedLimit } from './feed.js';
+export declare const publishMarker = ".sponge-publish", markerBody = "sponge-publish-v1\n";
+export interface PublishOptions {
+    output: string;
+    title?: string;
+    baseUrl?: string;
+    minAgeDays?: number;
+    now?: Date;
+}
+export interface PublishSource {
+    root: string;
+    publicProjection(): {
+        entries: PublicEntry[];
+        skipped: {
+            itemId: string;
+            reason: string;
+        }[];
+    };
+}
+/** Drop entries listed fewer than `days` days ago, so listing dates do not reveal what is read right now. */
+export declare function minAge(entries: PublicEntry[], days?: number, now?: Date): PublicEntry[];
+/**
+ * Write the signed static site for the public projection. The site is built in a temporary sibling and renamed
+ * into place; an existing directory is replaced only when it is a previous publish output with no foreign files.
+ */
+export declare function publishSite(source: PublishSource, options: PublishOptions): {
+    output: string;
+    entries: number;
+    held: number;
+    skipped: number;
+    files: number;
+    publicKey: string;
+};

package/dist/src/publish/index.js

@@ -0,0 +1,137 @@
+import { closeSync, constants, fsyncSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, rmSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { basename, dirname, isAbsolute, join, parse, relative, resolve, sep } from 'node:path';
+import { digest, pathExists, regularFile, safeDirectory, syncDirectory, verifyFile } from '../store/files.js';
+import { StoreError } from '../store/types.js';
+import { writeAll } from '../portability/files.js';
+import { baseUrl, buildSite, manifestPath, signaturePath } from './feed.js';
+import { publishIdentity } from './identity.js';
+export { buildSite, canonical, xml, feedLimit } from './feed.js';
+export const publishMarker = '.sponge-publish', markerBody = 'sponge-publish-v1\n';
+const fail = (code = 'invalid-input') => { throw new StoreError(code); };
+/** Drop entries listed fewer than `days` days ago, so listing dates do not reveal what is read right now. */
+export function minAge(entries, days = 0, now = new Date()) {
+    if (!Number.isSafeInteger(days) || days < 0 || days > 3650)
+        fail();
+    if (!days)
+        return entries;
+    const cutoff = new Date(now.getTime() - days * 86_400_000).toISOString().slice(0, 10);
+    return entries.filter(e => e.listedOn <= cutoff);
+}
+/** Files a previous publish wrote, or a refusal: an unmarked directory or unlisted files are not ours to replace. */
+function previousOutput(target, stat) {
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        fail('integrity');
+    const marker = join(target, publishMarker);
+    if (!pathExists(marker))
+        fail();
+    regularFile(marker);
+    verifyFile(marker, digest(markerBody), Buffer.byteLength(markerBody));
+    let listed;
+    try {
+        const manifest = join(target, manifestPath);
+        regularFile(manifest);
+        listed = new Set(JSON.parse(readFileSync(manifest, 'utf8')).files.map(f => f.path));
+    }
+    catch {
+        return fail();
+    }
+    for (const path of [manifestPath, signaturePath, publishMarker])
+        listed.add(path);
+    const walk = (dir) => { for (const name of readdirSync(dir)) {
+        const path = join(dir, name), s = lstatSync(path), rel = relative(target, path).split(sep).join('/');
+        if (s.isSymbolicLink())
+            fail('integrity');
+        if (s.isDirectory())
+            walk(path);
+        else if (!s.isFile() || !listed.has(rel))
+            fail();
+    } };
+    walk(target);
+}
+function writeTree(root, files) {
+    mkdirSync(root, { mode: 0o755 });
+    const dirs = new Set([root]);
+    for (const [path, bytes] of [...files, [publishMarker, Buffer.from(markerBody)]]) {
+        const target = join(root, ...path.split('/')), dir = dirname(target);
+        if (!dirs.has(dir)) {
+            mkdirSync(dir, { mode: 0o755 });
+            dirs.add(dir);
+        }
+        const fd = openSync(target, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o644);
+        try {
+            writeAll(fd, bytes);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    for (const dir of [...dirs].reverse())
+        syncDirectory(dir);
+}
+/**
+ * Write the signed static site for the public projection. The site is built in a temporary sibling and renamed
+ * into place; an existing directory is replaced only when it is a previous publish output with no foreign files.
+ */
+export function publishSite(source, options) {
+    const output = options.output;
+    if (!isAbsolute(output) || resolve(output) !== output || output === parse(output).root)
+        fail();
+    let parent;
+    try {
+        parent = safeDirectory(dirname(output));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            fail();
+        throw error;
+    }
+    const target = join(parent, basename(output)), library = safeDirectory(source.root), inside = relative(library, target);
+    if (!inside || !inside.startsWith('..') && !isAbsolute(inside) || !relative(target, library).startsWith('..'))
+        fail();
+    const title = options.title ?? 'Reading list';
+    if (!title.trim() || title.length > 200 || /[\u0000-\u001f\u007f]/.test(title))
+        fail();
+    const base = options.baseUrl === undefined ? undefined : baseUrl(options.baseUrl);
+    let previous;
+    try {
+        previous = lstatSync(target);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    if (previous)
+        previousOutput(target, previous);
+    const projection = source.publicProjection(), entries = minAge(projection.entries, options.minAgeDays, options.now), identity = publishIdentity(library);
+    const files = buildSite(entries, identity, { title, ...(base ? { baseUrl: base } : {}) }, bytes => identity.sign(bytes));
+    const id = randomUUID(), temp = join(parent, `.${basename(target)}.${id}.tmp`);
+    try {
+        writeTree(temp, files);
+    }
+    catch (error) {
+        rmSync(temp, { recursive: true, force: true });
+        throw error;
+    }
+    if (previous) {
+        const old = join(parent, `.${basename(target)}.${id}.old`);
+        renameSync(target, old);
+        try {
+            renameSync(temp, target);
+        }
+        catch (error) {
+            renameSync(old, target);
+            rmSync(temp, { recursive: true, force: true });
+            throw error;
+        }
+        const moved = lstatSync(old);
+        if (moved.dev !== previous.dev || moved.ino !== previous.ino)
+            fail('integrity');
+        rmSync(old, { recursive: true });
+    }
+    else
+        renameSync(temp, target);
+    syncDirectory(parent);
+    return { output: target, entries: entries.length, held: projection.entries.length - entries.length, skipped: projection.skipped.length, files: files.size, publicKey: identity.publicKey };
+}

package/dist/src/publish/projection.d.ts

@@ -0,0 +1,29 @@
+import type { DatabaseSync } from 'node:sqlite';
+/** One public list entry. Metadata only: no captured text, paths, account realms or local fingerprints. */
+export interface PublicEntry {
+    uri: string;
+    aliases: string[];
+    kind: string;
+    title: string;
+    authors?: string;
+    published?: string;
+    site?: string;
+    listedOn: string;
+    digest?: {
+        lead?: string;
+        ideas: {
+            claim: string;
+            detail: string;
+            kind?: string;
+            quotes: string[];
+        }[];
+    };
+}
+/** What `sponge publish` would publish now, newest first. Items without a resolvable URI are listed as skipped. */
+export declare function publicProjection(db: DatabaseSync): {
+    entries: PublicEntry[];
+    skipped: {
+        itemId: string;
+        reason: string;
+    }[];
+};

package/dist/src/publish/projection.js

@@ -0,0 +1,43 @@
+import { itemUris, visibility } from '../identity/visibility.js';
+import { acceptedDigest, currentDigest } from '../digest/store.js';
+import { currentEditorial, publicEditorial } from '../digest/editorial.js';
+/** The first selected (or unmarked) claim among `fields`; string lists are joined. */
+function selectedClaim(db, revisionId, fields) {
+    for (const field of fields) {
+        const r = db.prepare('SELECT value_json FROM metadata_claims WHERE revision_id=? AND field=? AND selected IS NOT 0 ORDER BY selected IS NOT 1,rowid LIMIT 1').get(revisionId, field);
+        const raw = r ? JSON.parse(String(r.value_json)) : undefined, v = Array.isArray(raw) && raw.every(x => typeof x === 'string') ? raw.join(', ') : raw;
+        if (typeof v === 'string' && v.trim() && v.length <= 1024)
+            return v.trim();
+    }
+    return undefined;
+}
+/**
+ * The public digest: the accepted fields of the current Digest v1, else the public subset of an accepted editorial
+ * note (lead, claims, verbatim quotes within the v1 budget). Never both, and never the note's other content.
+ */
+function publicDigest(db, id) { const d = currentDigest(db, id); if (d)
+    return acceptedDigest(d); const e = currentEditorial(db, id); return e && publicEditorial(db, e); }
+/** What `sponge publish` would publish now, newest first. Items without a resolvable URI are listed as skipped. */
+export function publicProjection(db) {
+    const entries = [], skipped = [];
+    for (const item of db.prepare('SELECT id,kind,title,current_revision,created_at FROM items WHERE deleted_at IS NULL ORDER BY created_at DESC,id').all()) {
+        const id = String(item.id);
+        if (visibility(db, id).effective !== 'public')
+            continue;
+        if (!item.current_revision) {
+            skipped.push({ itemId: id, reason: 'not-captured' });
+            continue;
+        }
+        const uris = itemUris(db, id).filter(u => u.resolvable), primary = uris.find(u => u.role === 'primary') ?? uris[0];
+        if (!primary) {
+            skipped.push({ itemId: id, reason: 'no-public-uri' });
+            continue;
+        }
+        const revision = String(item.current_revision), authors = selectedClaim(db, revision, ['authors', 'author']), published = selectedClaim(db, revision, ['publishedAt', 'published']), accepted = publicDigest(db, id);
+        let site;
+        if (/^https?:/.test(primary.uri))
+            site = new URL(primary.uri).hostname.replace(/^www\./, '');
+        entries.push({ uri: primary.uri, aliases: uris.filter(u => u !== primary).map(u => u.uri), kind: String(item.kind), title: String(item.title), ...(authors ? { authors } : {}), ...(published ? { published } : {}), ...(site ? { site } : {}), listedOn: String(item.created_at).slice(0, 10), ...(accepted ? { digest: accepted } : {}) });
+    }
+    return { entries, skipped };
+}

package/dist/src/search/hybrid.js

@@ -1,6 +1,6 @@
 import { chunkDocument } from '../indexing/index.js';
+import { lexicalSearch } from './lexical.js';
 import { pinSearchGeneration, vectorSearch } from './vector.js';
-function lexical(db, query, limit) { const literal = '"' + query.replaceAll('"', '""') + '"'; return db.prepare('SELECT i.id AS itemId,i.title,i.current_revision AS revisionId FROM readable_fts f JOIN items i ON i.id=f.item_id WHERE readable_fts MATCH ? AND i.deleted_at IS NULL AND i.current_revision=f.revision_id ORDER BY rank,i.id LIMIT ?').all(literal, limit); }
 /** Reciprocal rank fusion after per-channel item collapsing; chunks cannot amplify rank. */
 export function fuse(lexicalHits, semanticHits, limit) {
     const hits = new Map();
@@ -106,7 +106,7 @@ export async function hybridSearch(db, query, options = {}) {
                 warnings.push('semantic-unavailable');
             }
         }
-        const result = { hits: fuse(lexical(db, query, Math.min(500, limit * 5)), semantic, limit), warnings, generation: pin };
+        const result = { hits: fuse(lexicalSearch(db, query, Math.min(500, limit * 5)), semantic, limit), warnings, generation: pin };
         projectAnchors(db, result.hits);
         db.exec('COMMIT');
         return result;

package/dist/src/search/lexical.d.ts

@@ -0,0 +1,11 @@
+import type { DatabaseSync } from 'node:sqlite';
+export interface LexicalHit {
+    itemId: string;
+    revisionId: string;
+    title: string;
+}
+/** Contentless FTS rows are keyed by readable_fts_rows.id; items.rowid is not VACUUM-stable. Callers own the transaction. */
+export declare function indexReadable(db: DatabaseSync, itemId: string, revisionId: string, title: string, markdown: string): void;
+export declare function unindexReadable(db: DatabaseSync, itemId: string): void;
+/** Literal phrase, bm25 rank then item id; excludes tombstones and superseded revisions. */
+export declare function lexicalSearch(db: DatabaseSync, query: string, limit: number): LexicalHit[];

package/dist/src/search/lexical.js

@@ -0,0 +1,6 @@
+/** Contentless FTS rows are keyed by readable_fts_rows.id; items.rowid is not VACUUM-stable. Callers own the transaction. */
+export function indexReadable(db, itemId, revisionId, title, markdown) { unindexReadable(db, itemId); const row = db.prepare('INSERT INTO readable_fts_rows(item_id,revision_id) VALUES(?,?) RETURNING id').get(itemId, revisionId); db.prepare('INSERT INTO readable_fts(rowid,title,markdown) VALUES(?,?,?)').run(row.id, title, markdown); }
+export function unindexReadable(db, itemId) { const row = db.prepare('DELETE FROM readable_fts_rows WHERE item_id=? RETURNING id').get(itemId); if (row)
+    db.prepare('DELETE FROM readable_fts WHERE rowid=?').run(row.id); }
+/** Literal phrase, bm25 rank then item id; excludes tombstones and superseded revisions. */
+export function lexicalSearch(db, query, limit) { const literal = '"' + query.replaceAll('"', '""') + '"'; return db.prepare('SELECT i.id AS itemId,i.title,i.current_revision AS revisionId FROM readable_fts f JOIN readable_fts_rows m ON m.id=f.rowid JOIN items i ON i.id=m.item_id WHERE readable_fts MATCH ? AND i.deleted_at IS NULL AND i.current_revision=m.revision_id ORDER BY rank,i.id LIMIT ?').all(literal, limit); }

package/dist/src/search/query.d.ts

@@ -1,12 +1,16 @@
 import type { LibraryStore } from '../store/index.js';
 import { embedBatch, type EmbeddingRuntime } from '../inference/embedding/index.js';
 import type { QueryEmbedder } from './hybrid.js';
-/** Queries mutate coordination journals only, never library content or job tables. */
-export declare function createQueryEmbedder(store: LibraryStore, runtime: EmbeddingRuntime, options?: {
+type EmbedOptions = {
     embed?: typeof embedBatch;
     onReady?: (context: {
         attemptId: string;
         ownerDirectory: string;
         scratchRoot: string;
     }) => Promise<void>;
-}): QueryEmbedder;
+};
+/** Queries mutate coordination journals only, never library content or job tables. */
+export declare function createQueryEmbedder(store: LibraryStore, runtime: EmbeddingRuntime, options?: EmbedOptions): QueryEmbedder;
+/** Unit 768-dimension document vectors for short texts, 16 per helper run; text is clipped to the helper's byte budget on a character boundary. */
+export declare function createTextEmbedder(store: LibraryStore, runtime: EmbeddingRuntime, options?: EmbedOptions): (texts: string[], signal: AbortSignal) => Promise<number[][]>;
+export {};