@hraness/sponge 0.2.4 → 0.2.5

package/dist/src/models/artifacts.js

@@ -1,6 +1,6 @@
 import { constants } from 'node:fs';
 import { chmod, lstat, mkdir, open, rename, rm, statfs, link, unlink, readdir, realpath } from 'node:fs/promises';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { createHash, randomUUID } from 'node:crypto';
 import { processIdentity, identityAlive } from '../worker/identity.js';
 import { readJournal, writeJournal } from '../worker/journal.js';
@@ -48,11 +48,64 @@ async function syncDirectory(path) { const file = await open(path, constants.O_R
 finally {
     await file.close();
 } }
-async function verifyArtifact(path, artifact) {
+const uid = () => process.getuid?.();
+const packageName = /^[a-f0-9]{64}$/, linkHolder = /^(?:[a-f0-9]{64}|\.(?:model-install|gc)-[-a-f0-9]{36})$/;
+const missing = (error) => error.code === 'ENOENT';
+async function exists(path) { try {
+    await lstat(path);
+    return true;
+}
+catch (error) {
+    if (missing(error))
+        return false;
+    throw error;
+} }
+async function privateDirectory(path) { const stat = await lstat(path); return stat.isDirectory() && !stat.isSymbolicLink() && stat.uid === uid() && (stat.mode & 0o077) === 0; }
+/** A shared artifact inode is trusted only when every one of its links is a top-level file of a private package,
+ * stage or GC directory of this cache: nothing outside the private cache can reach (or later rewrite) it. */
+async function linksAccounted(root, stat) {
+    if (stat.nlink > 64)
+        return false;
+    const holders = (await readdir(root)).filter(name => linkHolder.test(name));
+    if (holders.length > 256)
+        return false;
+    let count = 0;
+    for (const name of holders) {
+        const dir = join(root, name);
+        let entries;
+        try {
+            if (!await privateDirectory(dir))
+                continue;
+            entries = await readdir(dir);
+        }
+        catch (error) {
+            if (missing(error))
+                continue;
+            throw error;
+        }
+        if (entries.length > 4096)
+            return false;
+        for (const entry of entries) {
+            let s;
+            try {
+                s = await lstat(join(dir, entry));
+            }
+            catch (error) {
+                if (missing(error))
+                    continue;
+                throw error;
+            }
+            if (s.isFile() && s.ino === stat.ino && s.dev === stat.dev)
+                count++;
+        }
+    }
+    return count === stat.nlink;
+}
+async function verifyArtifact(path, artifact, root) {
     const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
     try {
         const before = await file.stat();
-        if (!before.isFile() || before.nlink !== 1 || before.size !== artifact.bytes || (before.mode & 0o077) !== 0 || (artifact.executable && (before.mode & 0o100) === 0))
+        if (!before.isFile() || before.nlink < 1 || before.nlink !== 1 && !(root && await linksAccounted(root, before)) || before.size !== artifact.bytes || (before.mode & 0o077) !== 0 || (artifact.executable && (before.mode & 0o100) === 0))
             throw new ModelSetupError('integrity');
         const hash = createHash('sha256'), buffer = Buffer.alloc(65536);
         let bytes = 0;
@@ -66,20 +119,128 @@ async function verifyArtifact(path, artifact) {
             hash.update(buffer.subarray(0, read.bytesRead));
         }
         const after = await file.stat();
-        if (bytes !== artifact.bytes || hash.digest('hex') !== artifact.sha256 || before.mtimeMs !== after.mtimeMs)
+        if (bytes !== artifact.bytes || hash.digest('hex') !== artifact.sha256 || before.mtimeMs !== after.mtimeMs || before.nlink !== after.nlink)
+            throw new ModelSetupError('integrity');
+    }
+    finally {
+        await file.close();
+    }
+}
+/** Write one stream into a fresh staged file while hashing; the caller verifies against the manifest. */
+async function writeStaged(path, artifact, chunks, signal) {
+    const file = await open(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    const hash = createHash('sha256');
+    let bytes = 0;
+    try {
+        for await (const chunk of chunks) {
+            if (signal?.aborted)
+                throw new ModelSetupError('cancelled');
+            bytes += chunk.length;
+            if (bytes > artifact.bytes)
+                throw new ModelSetupError('integrity');
+            hash.update(chunk);
+            let offset = 0;
+            while (offset < chunk.length) {
+                const result = await file.write(chunk, offset, chunk.length - offset);
+                if (!result.bytesWritten)
+                    throw new ModelSetupError('unavailable');
+                offset += result.bytesWritten;
+            }
+        }
+        if (bytes !== artifact.bytes || hash.digest('hex') !== artifact.sha256)
             throw new ModelSetupError('integrity');
+        await file.chmod(artifact.executable ? 0o700 : 0o600);
+        await file.sync();
     }
     finally {
         await file.close();
     }
 }
+/** Same name, size and mode class in another installed package that no setup or recovery currently holds. */
+async function reuseCandidates(root, artifact, exclude) {
+    const result = [];
+    for (const name of (await readdir(root)).filter(n => packageName.test(n) && n !== exclude).sort()) {
+        try {
+            if (await exists(join(root, `.${name}.lock`)) || await exists(join(root, `.${name}.recovery-lock`)) || !await privateDirectory(join(root, name)))
+                continue;
+            const s = await lstat(join(root, name, artifact.name));
+            if (s.isFile() && !s.isSymbolicLink() && s.uid === uid() && s.size === artifact.bytes && (s.mode & 0o077) === 0 && !!artifact.executable === ((s.mode & 0o100) !== 0))
+                result.push(join(root, name, artifact.name));
+        }
+        catch (error) {
+            if (!missing(error))
+                throw error;
+        }
+    }
+    return result;
+}
+/** Upgrade reuse: a package whose fingerprint differs only by release URLs carries byte-identical artifacts. A candidate
+ * is never trusted: it is opened without following links, hard-linked (same inode as the opened file, or undone) or
+ * else copied from that descriptor, and the staged file is re-hashed against THIS manifest. Any doubt downloads. */
+async function reuseArtifact(root, stage, artifact, exclude, signal) {
+    const target = join(stage, artifact.name), mode = artifact.executable ? 0o700 : 0o600;
+    for (const candidate of await reuseCandidates(root, artifact, exclude)) {
+        if (signal?.aborted)
+            throw new ModelSetupError('cancelled');
+        let source;
+        try {
+            source = await open(candidate, constants.O_RDONLY | constants.O_NOFOLLOW);
+        }
+        catch {
+            continue;
+        }
+        try {
+            const s = await source.stat();
+            if (!s.isFile() || s.uid !== uid() || s.size !== artifact.bytes || (s.mode & 0o077) !== 0 || !!artifact.executable !== ((s.mode & 0o100) !== 0))
+                continue;
+            if ((s.mode & 0o777) === mode) {
+                // A link to anything but the opened inode, or bytes failing this manifest, is undone and the candidate skipped.
+                let linked = false;
+                try {
+                    await link(candidate, target);
+                    linked = true;
+                    const staged = await lstat(target);
+                    if (staged.isFile() && !staged.isSymbolicLink() && staged.ino === s.ino && staged.dev === s.dev) {
+                        await verifyArtifact(target, artifact, root);
+                        return 'linked';
+                    }
+                }
+                catch (error) {
+                    if (linked && !(error instanceof ModelSetupError))
+                        throw error;
+                }
+                if (linked) {
+                    await unlink(target);
+                    continue;
+                }
+            }
+            const disk = await statfs(root);
+            if (disk.bavail * disk.bsize < artifact.bytes + 512 * 1024 ** 2)
+                continue;
+            try {
+                await writeStaged(target, artifact, source.createReadStream({ autoClose: false, start: 0 }), signal);
+                await verifyArtifact(target, artifact, root);
+                return 'copied';
+            }
+            catch (error) {
+                await rm(target, { force: true });
+                if (error instanceof ModelSetupError && error.code === 'cancelled')
+                    throw error;
+            }
+        }
+        finally {
+            await source.close();
+        }
+    }
+    return null;
+}
 export async function inspectModelPackage(cacheRoot, manifest) {
     const plan = modelSetupPlan(manifest), root = join(await privateRoot(cacheRoot), plan.fingerprint);
     await privateRoot(root);
     const paths = Object.create(null);
     for (const artifact of manifest.artifacts) {
         const path = join(root, artifact.name);
-        await verifyArtifact(path, artifact);
+        await verifyArtifact(path, artifact, dirname(root));
         paths[artifact.name] = path;
     }
     return paths;
@@ -203,8 +364,13 @@ export async function provisionModelPackage(cacheRoot, manifest, options = {}) {
     }
     let stage;
     try {
+        // Reusable artifacts need no download space; a copy fallback rechecks space for itself.
+        let needed = 512 * 1024 ** 2;
+        for (const artifact of manifest.artifacts)
+            if (!(await reuseCandidates(root, artifact, plan.fingerprint)).length)
+                needed += artifact.bytes;
         const disk = await statfs(root);
-        if (disk.bavail * disk.bsize < plan.requiredFreeBytes)
+        if (disk.bavail * disk.bsize < needed)
             throw new ModelSetupError('limit-exceeded');
         stage = join(root, owner.stage);
         await mkdir(stage, { mode: 0o700 });
@@ -213,6 +379,8 @@ export async function provisionModelPackage(cacheRoot, manifest, options = {}) {
         await syncDirectory(stage);
         await syncDirectory(root);
         for (const artifact of manifest.artifacts) {
+            if (await reuseArtifact(root, stage, artifact, plan.fingerprint, options.signal))
+                continue;
             const signal = options.signal ? AbortSignal.any([options.signal, AbortSignal.timeout(600000)]) : AbortSignal.timeout(600000);
             const response = await (options.fetch ?? fetch)(artifact.url, { signal });
             if (!response.ok || !response.body || (response.url && new URL(response.url).protocol !== 'https:'))
@@ -222,33 +390,7 @@ export async function provisionModelPackage(cacheRoot, manifest, options = {}) {
                 await response.body.cancel();
                 throw new ModelSetupError('integrity');
             }
-            const file = await open(join(stage, artifact.name), constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
-            const hash = createHash('sha256');
-            let bytes = 0;
-            try {
-                for await (const chunk of response.body) {
-                    if (signal.aborted)
-                        throw new ModelSetupError('cancelled');
-                    bytes += chunk.length;
-                    if (bytes > artifact.bytes)
-                        throw new ModelSetupError('integrity');
-                    hash.update(chunk);
-                    let offset = 0;
-                    while (offset < chunk.length) {
-                        const result = await file.write(chunk, offset, chunk.length - offset);
-                        if (!result.bytesWritten)
-                            throw new ModelSetupError('unavailable');
-                        offset += result.bytesWritten;
-                    }
-                }
-                if (bytes !== artifact.bytes || hash.digest('hex') !== artifact.sha256)
-                    throw new ModelSetupError('integrity');
-                await file.chmod(artifact.executable ? 0o700 : 0o600);
-                await file.sync();
-            }
-            finally {
-                await file.close();
-            }
+            await writeStaged(join(stage, artifact.name), artifact, response.body, signal);
         }
         if (options.signal?.aborted)
             throw new ModelSetupError('cancelled');

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;
+};