@hraness/sponge 0.2.4 → 0.2.5

package/dist/src/digest/schema.js

@@ -0,0 +1,118 @@
+import { foldText, locateAll, textQuote, words } from '../annotations/quote.js';
+/**
+ * Digest v1: a one-sentence gist and 3-5 ideas, each a claim with detail and 1-2 verbatim quotes.
+ * The model proposes; this validator decides. Nothing here calls a model.
+ */
+export const ideaKinds = ['finding', 'argument', 'method', 'evidence', 'recommendation', 'counterpoint'];
+export const forms = ['article', 'video', 'paper', 'thread', 'pdf'];
+export const digestLimits = { leadChars: 155, contextWords: 50, minIdeas: 3, maxIdeas: 5, claimWords: 20, detailWords: 60, detailSentences: 3, maxQuotesPerIdea: 2, minQuoteWords: 4, quoteWords: 25, totalQuoteWords: 150, sourceQuoteShare: 0.1, maxTags: 3 };
+const object = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const keys = (v, allowed) => Object.keys(v).every(k => allowed.includes(k));
+const str = (v, max = 2000) => typeof v === 'string' && v.trim().length > 0 && v.length <= max && !/[\u0000-\u0008\u000b-\u001f\u007f]/.test(v);
+/** Sentence terminators followed by more text; abbreviations are rare enough in a 155-character lead to reject. */
+const sentences = (v) => foldText(v).split(/(?<=[.!?])\s+(?=\S)/).length;
+/** Parse an untrusted model output into a DigestV1 shape, or report why not. */
+export function parseDigest(value) {
+    const issues = [], bad = (path, code = 'shape') => { issues.push({ path, code }); };
+    if (!object(value) || !keys(value, ['schemaVersion', 'form', 'gist', 'ideas', 'tags']) || value.schemaVersion !== 1)
+        return { issues: [{ path: '', code: 'shape' }] };
+    if (!forms.includes(value.form))
+        bad('form');
+    const gist = value.gist;
+    if (!object(gist) || !keys(gist, ['lead', 'context']) || !str(gist.lead) || gist.context !== undefined && !str(gist.context))
+        bad('gist');
+    if (!Array.isArray(value.ideas) || value.ideas.length > 8)
+        bad('ideas');
+    else
+        value.ideas.forEach((idea, i) => {
+            const at = `ideas.${i}`;
+            if (!object(idea) || !keys(idea, ['claim', 'detail', 'kind', 'voice', 'quotes']) || !str(idea.claim) || !str(idea.detail) || !ideaKinds.includes(idea.kind))
+                return bad(at);
+            const voice = idea.voice;
+            if (!object(voice) || !(voice.type === 'author' && keys(voice, ['type']) || (voice.type === 'speaker' || voice.type === 'reported') && keys(voice, ['type', 'name']) && str(voice.name, 200)))
+                bad(at + '.voice');
+            if (!Array.isArray(idea.quotes) || idea.quotes.length > 4)
+                return bad(at + '.quotes');
+            idea.quotes.forEach((quote, j) => {
+                if (!object(quote) || !keys(quote, ['text', 'speaker', 'locator']) || !str(quote.text, 600) || quote.speaker !== undefined && !str(quote.speaker, 200))
+                    return bad(`${at}.quotes.${j}`);
+                const loc = quote.locator;
+                if (loc !== undefined && !(object(loc) && (loc.type === 'timestamp' && keys(loc, ['type', 'ms']) && Number.isSafeInteger(loc.ms) && loc.ms >= 0 || loc.type === 'page' && keys(loc, ['type', 'page']) && Number.isSafeInteger(loc.page) && loc.page >= 1)))
+                    bad(`${at}.quotes.${j}.locator`);
+            });
+        });
+    if (!Array.isArray(value.tags) || value.tags.some(t => !str(t, 64)))
+        bad('tags');
+    return issues.length ? { issues } : { digest: value, issues };
+}
+/** Check every v1 rule that code can decide against the captured Markdown. */
+export function checkDigest(digest, source, options = {}) {
+    const issues = [], located = [], issue = (path, code) => { issues.push({ path, code }); }, L = digestLimits;
+    if (digest.gist.lead.length > L.leadChars)
+        issue('gist.lead', 'too-long');
+    if (sentences(digest.gist.lead) !== 1)
+        issue('gist.lead', 'one-sentence');
+    if (digest.gist.context !== undefined && words(digest.gist.context) > L.contextWords)
+        issue('gist.context', 'too-long');
+    if (digest.ideas.length < L.minIdeas || digest.ideas.length > L.maxIdeas)
+        issue('ideas', 'count');
+    const claims = new Set();
+    let quoteWords = 0;
+    digest.ideas.forEach((idea, i) => {
+        const at = `ideas.${i}`;
+        if (words(idea.claim) > L.claimWords)
+            issue(at + '.claim', 'too-long');
+        if (sentences(idea.claim) !== 1)
+            issue(at + '.claim', 'one-sentence');
+        if (claims.has(foldText(idea.claim).toLowerCase()))
+            issue(at + '.claim', 'duplicate');
+        claims.add(foldText(idea.claim).toLowerCase());
+        if (words(idea.detail) > L.detailWords)
+            issue(at + '.detail', 'too-long');
+        if (sentences(idea.detail) > L.detailSentences)
+            issue(at + '.detail', 'too-many-sentences');
+        if (idea.quotes.length < 1 || idea.quotes.length > L.maxQuotesPerIdea)
+            issue(at + '.quotes', 'count');
+        idea.quotes.forEach((quote, j) => {
+            const path = `${at}.quotes.${j}`, count = words(quote.text);
+            quoteWords += count;
+            if (count > L.quoteWords)
+                issue(path, 'too-long');
+            if (count < L.minQuoteWords)
+                issue(path, 'too-short');
+            if (idea.voice.type !== 'author' && !quote.speaker)
+                issue(path, 'speaker-required');
+            const matches = locateAll(source, quote.text);
+            if (!matches.length)
+                return issue(path, 'not-verbatim');
+            // Prefer the first occurrence not already claimed by an earlier quote.
+            const match = matches.find(m => !located.some(q => m.start < q.anchor.end && q.anchor.start < m.end));
+            if (!match)
+                return issue(path, 'overlap');
+            located.push({ idea: i, quote: j, anchor: textQuote(source, match.start, match.end) });
+            if (options.supports && options.supports(idea.claim, quote.text) < (options.supportThreshold ?? 0.5))
+                issue(path, 'unsupported');
+        });
+    });
+    // Ideas follow the source: each idea's earliest located quote starts no earlier than the previous idea's.
+    let previous = -1;
+    digest.ideas.forEach((_, i) => {
+        const starts = located.filter(q => q.idea === i).map(q => q.anchor.start);
+        if (!starts.length)
+            return;
+        const first = Math.min(...starts);
+        if (first < previous)
+            issue(`ideas.${i}`, 'out-of-order');
+        previous = first;
+    });
+    if (quoteWords > L.totalQuoteWords)
+        issue('ideas', 'quote-budget');
+    // The 10% share has a 25-word floor: an exemption so a short source can still carry one full quote.
+    if (quoteWords > Math.max(L.quoteWords, Math.floor(words(source) * L.sourceQuoteShare)))
+        issue('ideas', 'quote-share');
+    if (digest.tags.length < 1 || digest.tags.length > L.maxTags || new Set(digest.tags).size !== digest.tags.length)
+        issue('tags', 'count');
+    digest.tags.forEach((tag, i) => { if (options.tags ? !options.tags.includes(tag) : !/^[a-z0-9][a-z0-9-]{0,63}$/.test(tag))
+        issue(`tags.${i}`, 'vocabulary'); });
+    return { ok: issues.length === 0, issues, quotes: located };
+}

package/dist/src/digest/store.d.ts

@@ -0,0 +1,57 @@
+import type { DatabaseSync } from 'node:sqlite';
+import { type DigestOptions, type DigestV1 } from './schema.js';
+import { type ReviewStatus } from '../store/changes.js';
+export type { ReviewStatus };
+/** Per-field review of a digest. Only accepted fields can ever be published. */
+export interface DigestReview {
+    gist?: ReviewStatus;
+    ideas?: (ReviewStatus | null)[];
+    quotes?: (ReviewStatus | null)[][];
+}
+export interface Derivation {
+    id: string;
+    itemId: string;
+    revisionId: string;
+    kind: 'digest';
+    producer: unknown;
+    inputHash: string;
+    output: DigestV1;
+    review: DigestReview;
+    createdAt: string;
+}
+/** A parsed digest serialized in fixed key order, so key order never makes a different object. */
+export declare function canonicalDigest(d: DigestV1): string;
+/** Content address of a derivation: the same output from the same input is the same immutable object on every device. */
+export declare const derivationId: (revisionId: string, kind: string, inputHash: string, output: string) => string;
+/**
+ * Store a draft digest only when every v1 rule passes against the revision it was made from.
+ * Drafts are immutable data, not change-log entries; a different output is a new object.
+ */
+export declare function putDigest(db: DatabaseSync, input: {
+    itemId: string;
+    revisionId: string;
+    producer: Record<string, unknown>;
+    inputHash: string;
+    output: unknown;
+    options?: DigestOptions;
+}): {
+    id: string;
+    duplicate: boolean;
+};
+/** The newest digest made from the item's current revision. */
+export declare function currentDigest(db: DatabaseSync, itemId: string): Derivation | undefined;
+export declare function readDigest(db: DatabaseSync, id: string): Derivation | undefined;
+/** The newest stored digest for exactly these inputs, so a rerun reuses it instead of asking the model again. */
+export declare function findDigest(db: DatabaseSync, revisionId: string, inputHash: string): Derivation | undefined;
+/** Review fields of a digest. Each changed path is its own change: `review.gist`, `review.ideas.<i>`, `review.quotes.<i>.<j>`. */
+export declare function reviewDigest(db: DatabaseSync, id: string, review: DigestReview): Derivation;
+/** The accepted subset of a digest. Rejected or unreviewed fields never leave the device. */
+export declare function acceptedDigest(d: Derivation): {
+    lead?: string;
+    ideas: {
+        claim: string;
+        detail: string;
+        kind: string;
+        quotes: string[];
+    }[];
+} | undefined;

package/dist/src/digest/store.js

@@ -0,0 +1,77 @@
+import { checkDigest, parseDigest } from './schema.js';
+import { markdownFor } from '../annotations/store.js';
+import { mutate } from '../store/changes.js';
+import { StoreError } from '../store/types.js';
+import { digest, hash } from '../store/files.js';
+const now = () => new Date().toISOString();
+const fail = (code = 'invalid-input') => { throw new StoreError(code); };
+/** A parsed digest serialized in fixed key order, so key order never makes a different object. */
+export function canonicalDigest(d) {
+    return JSON.stringify({ schemaVersion: d.schemaVersion, form: d.form, gist: { lead: d.gist.lead, ...(d.gist.context !== undefined ? { context: d.gist.context } : {}) }, ideas: d.ideas.map(i => ({ claim: i.claim, detail: i.detail, kind: i.kind, voice: i.voice.type === 'author' ? { type: 'author' } : { type: i.voice.type, name: i.voice.name }, quotes: i.quotes.map(q => ({ text: q.text, ...(q.speaker !== undefined ? { speaker: q.speaker } : {}), ...(q.locator ? { locator: q.locator.type === 'timestamp' ? { type: 'timestamp', ms: q.locator.ms } : { type: 'page', page: q.locator.page } } : {}) })) })), tags: [...d.tags] });
+}
+/** Content address of a derivation: the same output from the same input is the same immutable object on every device. */
+export const derivationId = (revisionId, kind, inputHash, output) => digest(JSON.stringify(['derivation-v1', revisionId, kind, inputHash, output]));
+/**
+ * Store a draft digest only when every v1 rule passes against the revision it was made from.
+ * Drafts are immutable data, not change-log entries; a different output is a new object.
+ */
+export function putDigest(db, input) {
+    hash(input.inputHash);
+    const producer = JSON.stringify(input.producer);
+    if (!producer || Buffer.byteLength(producer) > 4096)
+        fail();
+    const revision = db.prepare('SELECT item_id FROM revisions WHERE id=?').get(input.revisionId);
+    if (revision?.item_id !== input.itemId)
+        fail('unavailable');
+    const parsed = parseDigest(input.output);
+    if (!parsed.digest)
+        throw Object.assign(new StoreError('invalid-input'), { issues: parsed.issues });
+    const check = checkDigest(parsed.digest, markdownFor(db, input.revisionId), input.options);
+    if (!check.ok)
+        throw Object.assign(new StoreError('invalid-input'), { issues: check.issues });
+    const output = canonicalDigest(parsed.digest);
+    if (Buffer.byteLength(output) > 65536)
+        fail();
+    const id = derivationId(input.revisionId, 'digest', input.inputHash, output);
+    if (db.prepare('SELECT 1 FROM derivations WHERE id=?').get(id))
+        return { id, duplicate: true };
+    db.prepare("INSERT INTO derivations(id,item_id,revision_id,kind,schema_version,producer_json,input_hash,output_json,created_at) VALUES(?,?,?,'digest',1,?,?,?,?)").run(id, input.itemId, input.revisionId, producer, input.inputHash, output, now());
+    return { id, duplicate: false };
+}
+function derivationRow(r) { return { id: String(r.id), itemId: String(r.item_id), revisionId: String(r.revision_id), kind: 'digest', producer: JSON.parse(String(r.producer_json)), inputHash: String(r.input_hash), output: JSON.parse(String(r.output_json)), review: JSON.parse(String(r.review_json)), createdAt: String(r.created_at) }; }
+/** The newest digest made from the item's current revision. */
+export function currentDigest(db, itemId) {
+    const r = db.prepare("SELECT d.* FROM derivations d JOIN items i ON i.id=d.item_id AND i.current_revision=d.revision_id WHERE d.item_id=? AND d.kind='digest' ORDER BY d.created_at DESC,d.rowid DESC LIMIT 1").get(itemId);
+    return r ? derivationRow(r) : undefined;
+}
+export function readDigest(db, id) { const r = db.prepare("SELECT * FROM derivations WHERE id=? AND kind='digest'").get(id); return r ? derivationRow(r) : undefined; }
+/** The newest stored digest for exactly these inputs, so a rerun reuses it instead of asking the model again. */
+export function findDigest(db, revisionId, inputHash) { hash(inputHash); const r = db.prepare("SELECT * FROM derivations WHERE revision_id=? AND kind='digest' AND input_hash=? ORDER BY created_at DESC,rowid DESC LIMIT 1").get(revisionId, inputHash); return r ? derivationRow(r) : undefined; }
+/** Review fields of a digest. Each changed path is its own change: `review.gist`, `review.ideas.<i>`, `review.quotes.<i>.<j>`. */
+export function reviewDigest(db, id, review) {
+    const row = db.prepare("SELECT * FROM derivations WHERE id=? AND kind='digest'").get(id) ?? fail('unavailable'), d = derivationRow(row);
+    const status = (v) => v === null || v === 'accepted' || v === 'rejected';
+    if (typeof review !== 'object' || review === null || Object.keys(review).some(k => !['gist', 'ideas', 'quotes'].includes(k)))
+        fail();
+    if (review.gist !== undefined && review.gist !== 'accepted' && review.gist !== 'rejected')
+        fail();
+    if (review.ideas !== undefined && (!Array.isArray(review.ideas) || review.ideas.length !== d.output.ideas.length || !review.ideas.every(status)))
+        fail();
+    if (review.quotes !== undefined && (!Array.isArray(review.quotes) || review.quotes.length !== d.output.ideas.length || review.quotes.some((q, i) => !Array.isArray(q) || q.length !== d.output.ideas[i].quotes.length || !q.every(status))))
+        fail();
+    const paths = [];
+    if (review.gist !== undefined)
+        paths.push(['review.gist', review.gist, d.review.gist ?? null]);
+    review.ideas?.forEach((v, i) => paths.push([`review.ideas.${i}`, v, d.review.ideas?.[i] ?? null]));
+    review.quotes?.forEach((q, i) => q.forEach((v, j) => paths.push([`review.quotes.${i}.${j}`, v, d.review.quotes?.[i]?.[j] ?? null])));
+    for (const [path, next, prior] of paths)
+        if (next !== prior)
+            mutate(db, 'derivation', id, path, next);
+    return derivationRow(db.prepare('SELECT * FROM derivations WHERE id=?').get(id));
+}
+/** The accepted subset of a digest. Rejected or unreviewed fields never leave the device. */
+export function acceptedDigest(d) {
+    const ideas = d.output.ideas.flatMap((idea, i) => d.review.ideas?.[i] === 'accepted' ? [{ claim: idea.claim, detail: idea.detail, kind: idea.kind, quotes: idea.quotes.filter((_, j) => d.review.quotes?.[i]?.[j] === 'accepted').map(q => q.text) }] : []);
+    const lead = d.review.gist === 'accepted' ? d.output.gist.lead : undefined;
+    return lead || ideas.length ? { ...(lead ? { lead } : {}), ideas } : undefined;
+}

package/dist/src/identity/query-policy.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The one query-field policy shared by source keys (src/app/source.ts) and shareable URIs (uri.ts).
+ * Source keys drop only `campaignFields`; changing that list changes every existing source key.
+ * Shareable URIs also drop `clickTrackers` and every credential-like field, so a published URI
+ * never carries a capability. See docs/decisions/sync-and-publishing.md.
+ */
+export declare const campaignFields: ReadonlySet<string>;
+export declare const clickTrackers: ReadonlySet<string>;
+/** Credential-like query keys, compared case-insensitively. Presence makes a capture private by default. */
+export declare const secretFields: ReadonlySet<string>;
+export declare const secretPrefixes: readonly string[];
+/** The decoded, lowercased key of one raw `a=b` field, or undefined when it does not decode. */
+export declare function fieldKey(field: string): string | undefined;
+export declare function isSecretField(key: string): boolean;
+/** Filter raw fields: URLSearchParams mutation rewrites unknown signed query bytes. */
+export declare function filterQuery(search: string, drop: (key: string) => boolean): string;
+/**
+ * A link that grants access by itself: userinfo, a credential-like query key, or a known
+ * anyone-with-the-link path. Deliberately short; documented in the decision record.
+ */
+export declare function isCapabilityUrl(locator: string): boolean;

package/dist/src/identity/query-policy.js

@@ -0,0 +1,55 @@
+/**
+ * The one query-field policy shared by source keys (src/app/source.ts) and shareable URIs (uri.ts).
+ * Source keys drop only `campaignFields`; changing that list changes every existing source key.
+ * Shareable URIs also drop `clickTrackers` and every credential-like field, so a published URI
+ * never carries a capability. See docs/decisions/sync-and-publishing.md.
+ */
+export const campaignFields = new Set(['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content', 'utm_id']);
+export const clickTrackers = new Set(['fbclid', 'gclid', 'dclid', 'msclkid', 'mc_cid', 'mc_eid', 'igshid']);
+/** Credential-like query keys, compared case-insensitively. Presence makes a capture private by default. */
+export const secretFields = new Set(['token', 'key', 'sig', 'signature', 'auth', 'access_token', 'code', 'rlkey', 'session', 'password', 'secret', 'api_key', 'apikey', 'auth_token', 'id_token', 'refresh_token', 'client_secret']);
+export const secretPrefixes = ['x-amz-', 'x-goog-'];
+/** The decoded, lowercased key of one raw `a=b` field, or undefined when it does not decode. */
+export function fieldKey(field) {
+    try {
+        return decodeURIComponent(field.split('=', 1)[0].replaceAll('+', ' ')).toLowerCase();
+    }
+    catch {
+        return undefined;
+    }
+}
+export function isSecretField(key) { return secretFields.has(key) || secretPrefixes.some(p => key.startsWith(p)); }
+/** Filter raw fields: URLSearchParams mutation rewrites unknown signed query bytes. */
+export function filterQuery(search, drop) {
+    if (!search)
+        return '';
+    const fields = search.slice(1).split('&').filter(field => { const key = fieldKey(field); return key === undefined || !drop(key); });
+    return fields.length ? '?' + fields.join('&') : '';
+}
+/**
+ * A link that grants access by itself: userinfo, a credential-like query key, or a known
+ * anyone-with-the-link path. Deliberately short; documented in the decision record.
+ */
+export function isCapabilityUrl(locator) {
+    let url;
+    try {
+        url = new URL(locator);
+    }
+    catch {
+        return false;
+    }
+    if (!['http:', 'https:'].includes(url.protocol))
+        return false;
+    if (url.username || url.password)
+        return true;
+    if (url.search && url.search.slice(1).split('&').some(field => { const key = fieldKey(field); return key !== undefined && isSecretField(key); }))
+        return true;
+    const host = url.hostname.replace(/^www\./, ''), path = url.pathname;
+    // Google Docs, Sheets, Slides, Forms, Drawings and Drive files shared "anyone with the link".
+    if ((host === 'docs.google.com' && /^\/(document|spreadsheets|presentation|forms|drawings)\/d\/[^/]+/.test(path) && !/^\/[^/]+\/d\/e\//.test(path) || host === 'drive.google.com' && /^\/(file\/d|drive\/folders)\/[^/]+/.test(path)) && url.searchParams.get('usp') === 'sharing')
+        return true;
+    // Dropbox shared links are capabilities with or without rlkey.
+    if ((host === 'dropbox.com' || host === 'dl.dropboxusercontent.com') && /^\/(s|sh|scl)\//.test(path))
+        return true;
+    return false;
+}

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

@@ -0,0 +1,30 @@
+/** One shareable identifier. Resolvable URIs may be published; fingerprints and local ids never are by default. */
+export interface ItemUri {
+    uri: string;
+    role: 'primary' | 'alias';
+    resolvable: boolean;
+    origin: 'locator' | 'revision';
+}
+/** `capability`: a public-realm or imported link that grants access by itself (see query-policy.ts). */
+export type AccessClass = 'public' | 'account' | 'local' | 'imported' | 'capability';
+export declare const maxUriBytes = 8192;
+/** Same-work identity drops fragments, click trackers and credential-like fields that the source key keeps for capture fidelity. */
+export declare function shareableWebUri(locator: string): string;
+/** Provider identifiers name the same work across URL spellings, hosts and mirrors. */
+export declare function providerUris(href: string): string[];
+export declare function isResolvable(uri: string): boolean;
+/**
+ * Derive an item's URIs from its first source and, once captured, its source PDF. Total: a
+ * locator that cannot be parsed, carries userinfo or is too long yields only `sponge:item/<id>`.
+ * A local file never exposes its path: before capture it is `sponge:item/<id>`, afterwards
+ * `urn:sha256:<file hash>`, which matches the same file anywhere but is not resolvable.
+ */
+export declare function deriveUris(input: {
+    itemId: string;
+    locator: string;
+    sourcePdfSha256?: string;
+}): ItemUri[];
+/** How the first source was reached decides the default visibility; see docs/decisions/sync-and-publishing.md. */
+export declare function accessClass(realm: string, locator: string): AccessClass;
+/** Public only when the source was public. Imports keep their source's publication decision. */
+export declare function defaultVisibility(access: AccessClass, importedPrivacy?: string): 'public' | 'private';

package/dist/src/identity/uri.js

@@ -0,0 +1,94 @@
+import { normalizeWebLocator } from '../app/source.js';
+import { clickTrackers, filterQuery, isCapabilityUrl, isSecretField } from './query-policy.js';
+export const maxUriBytes = 8192;
+/** Same-work identity drops fragments, click trackers and credential-like fields that the source key keeps for capture fidelity. */
+export function shareableWebUri(locator) {
+    const url = new URL(normalizeWebLocator(locator));
+    url.hash = '';
+    if (url.search)
+        url.search = filterQuery(url.search, key => clickTrackers.has(key) || isSecretField(key));
+    return url.href;
+}
+const youtubeId = /^[A-Za-z0-9_-]{11}$/;
+const decoded = (value) => { try {
+    return decodeURIComponent(value);
+}
+catch {
+    return undefined;
+} };
+/** Provider identifiers name the same work across URL spellings, hosts and mirrors. */
+export function providerUris(href) {
+    const url = new URL(href), host = url.hostname.replace(/^(www|m|mobile)\./, ''), parts = url.pathname.split('/').filter(Boolean), out = [];
+    if (host === 'youtube.com' || host === 'music.youtube.com') {
+        const id = url.pathname === '/watch' ? url.searchParams.get('v') : ['shorts', 'live', 'embed'].includes(parts[0]) ? parts[1] : undefined;
+        if (id && youtubeId.test(id))
+            out.push('youtube:' + id);
+    }
+    if (host === 'youtu.be' && youtubeId.test(parts[0] ?? ''))
+        out.push('youtube:' + parts[0]);
+    if ((host === 'x.com' || host === 'twitter.com') && parts[1] === 'status' && /^\d{1,25}$/.test(parts[2] ?? ''))
+        out.push('x:status/' + parts[2]);
+    if (host === 'arxiv.org' && ['abs', 'pdf'].includes(parts[0]) && parts[1]) {
+        const id = parts.slice(1).join('/').replace(/\.pdf$/, '').replace(/v\d+$/, '');
+        if (/^(\d{4}\.\d{4,5}|[a-z-]+(\.[A-Z]{2})?\/\d{7})$/.test(id))
+            out.push('arxiv:' + id);
+    }
+    if ((host === 'doi.org' || host === 'dx.doi.org') && /^10\.\d{4,9}$/.test(parts[0] ?? '') && parts.length > 1) {
+        const doi = decoded(parts.join('/'));
+        if (doi && !/[\u0000-\u001f\u007f]/.test(doi))
+            out.push('doi:' + doi.toLowerCase());
+    }
+    return out;
+}
+export function isResolvable(uri) { return /^(https?:|doi:|arxiv:|isbn:|youtube:|x:)/.test(uri); }
+/**
+ * Derive an item's URIs from its first source and, once captured, its source PDF. Total: a
+ * locator that cannot be parsed, carries userinfo or is too long yields only `sponge:item/<id>`.
+ * A local file never exposes its path: before capture it is `sponge:item/<id>`, afterwards
+ * `urn:sha256:<file hash>`, which matches the same file anywhere but is not resolvable.
+ */
+export function deriveUris(input) {
+    const out = [], add = (uri, origin) => { if (uri.length >= 3 && Buffer.byteLength(uri) <= maxUriBytes && !out.some(u => u.uri === uri))
+        out.push({ uri, role: out.length ? 'alias' : 'primary', resolvable: isResolvable(uri), origin }); };
+    if (/^https?:/i.test(input.locator)) {
+        let web;
+        try {
+            web = shareableWebUri(input.locator);
+        }
+        catch {
+            web = undefined;
+        }
+        if (web && Buffer.byteLength(web) <= maxUriBytes) {
+            add(web, 'locator');
+            try {
+                for (const uri of providerUris(web))
+                    add(uri, 'locator');
+            }
+            catch { /* a provider alias is optional */ }
+        }
+    }
+    if (input.sourcePdfSha256)
+        add('urn:sha256:' + input.sourcePdfSha256, 'revision');
+    if (!out.length)
+        add('sponge:item/' + input.itemId, 'locator');
+    return out;
+}
+/** How the first source was reached decides the default visibility; see docs/decisions/sync-and-publishing.md. */
+export function accessClass(realm, locator) {
+    if (locator.startsWith('file:'))
+        return 'local';
+    if (realm.startsWith('connection:'))
+        return 'account';
+    // A guard on top of the source rule: a link that is itself a credential is never public by default.
+    if (isCapabilityUrl(locator))
+        return 'capability';
+    if (realm.startsWith('import:'))
+        return 'imported';
+    return realm === '' || realm === 'public' ? 'public' : 'account';
+}
+/** Public only when the source was public. Imports keep their source's publication decision. */
+export function defaultVisibility(access, importedPrivacy) {
+    if (access === 'public')
+        return 'public';
+    return access === 'imported' && importedPrivacy === 'published' ? 'public' : 'private';
+}

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

@@ -0,0 +1,24 @@
+import type { DatabaseSync } from 'node:sqlite';
+import { type AccessClass, type ItemUri } from './uri.js';
+export type Visibility = 'public' | 'private';
+/** Recompute derived URIs; metadata and user URIs are left alone. Idempotent. */
+export declare function syncUris(db: DatabaseSync, itemId: string): void;
+/**
+ * Fill URIs for items created before schema 5, inside migration 5. Each item is its own savepoint:
+ * one hostile locator leaves that item without URIs instead of making the library unopenable.
+ */
+export declare function backfillUris(db: DatabaseSync): {
+    filled: number;
+    skipped: number;
+};
+export declare function itemUris(db: DatabaseSync, itemId: string): ItemUri[];
+/** Items sharing any URI with `uri`: the local half of "who else is reading this". */
+export declare function itemsForUri(db: DatabaseSync, uri: string): string[];
+export interface VisibilityState {
+    access: AccessClass;
+    default: Visibility;
+    override: Visibility | null;
+    effective: Visibility;
+}
+export declare function visibility(db: DatabaseSync, itemId: string): VisibilityState;
+export declare function setVisibility(db: DatabaseSync, itemId: string, value: Visibility | null): VisibilityState;

package/dist/src/identity/visibility.js

@@ -0,0 +1,75 @@
+import { accessClass, defaultVisibility, deriveUris } from './uri.js';
+import { mutate } from '../store/changes.js';
+import { StoreError } from '../store/types.js';
+import { text } from '../store/files.js';
+const fail = (code = 'invalid-input') => { throw new StoreError(code); };
+function firstSource(db, itemId) { return db.prepare('SELECT realm_key,locator FROM source_refs WHERE item_id=? ORDER BY rowid LIMIT 1').get(itemId); }
+/** Recompute derived URIs; metadata and user URIs are left alone. Idempotent. */
+export function syncUris(db, itemId) {
+    const source = firstSource(db, itemId);
+    if (!source)
+        return;
+    const pdf = db.prepare("SELECT ra.sha256 FROM items i JOIN revision_assets ra ON ra.revision_id=i.current_revision WHERE i.id=? AND ra.relationship='source-pdf' ORDER BY ra.ordinal LIMIT 1").get(itemId);
+    const uris = deriveUris({ itemId, locator: String(source.locator), ...(pdf ? { sourcePdfSha256: String(pdf.sha256) } : {}) });
+    const current = db.prepare("SELECT uri,role,resolvable,origin FROM item_uris WHERE item_id=? AND origin IN ('locator','revision') ORDER BY uri").all(itemId).map(r => `${r.uri}|${r.role}|${r.resolvable}|${r.origin}`).join('\n');
+    const next = uris.map(u => `${u.uri}|${u.role}|${Number(u.resolvable)}|${u.origin}`).sort().join('\n');
+    if (current === next)
+        return;
+    db.prepare("DELETE FROM item_uris WHERE item_id=? AND origin IN ('locator','revision')").run(itemId);
+    // A derived primary replaces any other primary; keep later metadata/user URIs as aliases.
+    db.prepare("UPDATE item_uris SET role='alias' WHERE item_id=?").run(itemId);
+    for (const u of uris)
+        db.prepare('INSERT INTO item_uris VALUES(?,?,?,?,?) ON CONFLICT(item_id,uri) DO UPDATE SET role=excluded.role,resolvable=excluded.resolvable,origin=excluded.origin').run(itemId, u.uri, u.role, Number(u.resolvable), u.origin);
+}
+/**
+ * Fill URIs for items created before schema 5, inside migration 5. Each item is its own savepoint:
+ * one hostile locator leaves that item without URIs instead of making the library unopenable.
+ */
+export function backfillUris(db) {
+    const missing = db.prepare("SELECT i.id FROM items i WHERE NOT EXISTS (SELECT 1 FROM item_uris u WHERE u.item_id=i.id AND u.role='primary') AND EXISTS (SELECT 1 FROM source_refs r WHERE r.item_id=i.id)").all().map(r => String(r.id));
+    let skipped = 0;
+    for (const id of missing) {
+        db.exec('SAVEPOINT backfill_uri');
+        try {
+            syncUris(db, id);
+            db.exec('RELEASE backfill_uri');
+        }
+        catch {
+            db.exec('ROLLBACK TO backfill_uri; RELEASE backfill_uri');
+            skipped++;
+        }
+    }
+    return { filled: missing.length - skipped, skipped };
+}
+export function itemUris(db, itemId) {
+    return db.prepare("SELECT uri,role,resolvable,origin FROM item_uris WHERE item_id=? ORDER BY role='alias',uri").all(itemId).map(r => ({ uri: String(r.uri), role: r.role, resolvable: !!r.resolvable, origin: r.origin }));
+}
+/** Items sharing any URI with `uri`: the local half of "who else is reading this". */
+export function itemsForUri(db, uri) {
+    text(uri, 8192);
+    return db.prepare('SELECT DISTINCT u.item_id FROM item_uris u JOIN items i ON i.id=u.item_id WHERE u.uri=? AND i.deleted_at IS NULL ORDER BY u.item_id').all(uri).map(r => String(r.item_id));
+}
+export function visibility(db, itemId) {
+    const item = db.prepare('SELECT visibility,deleted_at FROM items WHERE id=?').get(itemId) ?? fail('unavailable'), source = firstSource(db, itemId);
+    const access = source ? accessClass(String(source.realm_key), String(source.locator)) : 'local';
+    const reading = db.prepare('SELECT state_json FROM reading_state WHERE item_id=?').get(itemId);
+    let importedPrivacy;
+    try {
+        importedPrivacy = reading ? JSON.parse(String(reading.state_json))?.sourcePrivacy : undefined;
+    }
+    catch {
+        importedPrivacy = undefined;
+    }
+    const base = defaultVisibility(access, importedPrivacy), override = (item.visibility ?? null);
+    return { access, default: base, override, effective: item.deleted_at ? 'private' : override ?? base };
+}
+export function setVisibility(db, itemId, value) {
+    if (value !== null && value !== 'public' && value !== 'private')
+        fail();
+    const item = db.prepare('SELECT visibility,deleted_at FROM items WHERE id=?').get(itemId);
+    if (!item || item.deleted_at)
+        fail('unavailable');
+    if ((item.visibility ?? null) !== value)
+        mutate(db, 'item', itemId, 'visibility', value);
+    return visibility(db, itemId);
+}

package/dist/src/importers/apply.d.ts

@@ -1,4 +1,5 @@
 import type { LibraryStore } from '../store/index.js';
+import { type ImportEntry } from './manifest.js';
 import { type BundleVerifier } from './inspect.js';
 import type { CaptureRuntime } from '../acquisition/runtime.js';
 export interface ImportOptions {
@@ -25,5 +26,14 @@ export interface ImportReport {
     }[];
     nextOffset: number | null;
 }
+/** One verified bundle: a receipt short-circuits, a dry run stops after verification, otherwise the capture is promoted through the queue. */
+export declare function importBundleEntry(store: LibraryStore, root: string, namespace: string, entry: ImportEntry, verify: BundleVerifier, dryRun: boolean, signal?: AbortSignal): Promise<{
+    status: 'ready' | 'imported' | 'duplicate';
+    sourceHash: string;
+    historicalIntegrity: 'verified' | 'unavailable';
+    itemId?: string;
+}>;
+/** The revision a bundle import committed: content-addressed by its source hash. */
+export declare const importBundleHash: (sourceHash: string) => string;
 /** Additive bounded batches. Every applied entry is reverified; source bundles are read-only. */
 export declare function importManifest(store: LibraryStore, path: string, options: ImportOptions): Promise<ImportReport>;