@hraness/sponge 0.2.4 → 0.2.6

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

@@ -0,0 +1,126 @@
+import { type TextQuote } from '../annotations/quote.js';
+/**
+ * Digest v2: a gist led by one sentence, and 3-5 ideas in the author's order, each a claim with detail and 0-2 verbatim
+ * quotes; the digest carries 1-6 quotes in all. Digest v1 (one short lead, 1-2 quotes on every idea, ideas in source
+ * order, kind and voice required) stays readable and checkable; new digests are v2. The model proposes; this validator
+ * decides. Nothing here calls a model.
+ */
+export declare const ideaKinds: readonly ["finding", "argument", "method", "evidence", "recommendation", "counterpoint"];
+export declare const forms: readonly ["article", "video", "paper", "thread", "pdf"];
+export type Voice = {
+    type: 'author';
+} | {
+    type: 'speaker' | 'reported';
+    name: string;
+};
+export type QuoteLocator = {
+    type: 'timestamp';
+    ms: number;
+} | {
+    type: 'page';
+    page: number;
+};
+/** `attribution` is v2 only: who said it and where, as the reviewer wrote it. */
+export interface DigestQuote {
+    text: string;
+    speaker?: string;
+    attribution?: string;
+    locator?: QuoteLocator;
+}
+export interface DigestIdea {
+    claim: string;
+    detail: string;
+    kind?: typeof ideaKinds[number];
+    voice?: Voice;
+    quotes: DigestQuote[];
+}
+export interface DigestIdeaV1 extends DigestIdea {
+    kind: typeof ideaKinds[number];
+    voice: Voice;
+}
+export interface DigestV1 {
+    schemaVersion: 1;
+    form: typeof forms[number];
+    gist: {
+        lead: string;
+        context?: string;
+    };
+    ideas: DigestIdeaV1[];
+    tags: string[];
+}
+export interface DigestV2 {
+    schemaVersion: 2;
+    form: typeof forms[number];
+    gist: {
+        lead: string;
+        context?: string;
+    };
+    ideas: DigestIdea[];
+    tags: string[];
+}
+export type Digest = DigestV1 | DigestV2;
+export declare const digestSchemaVersion = 2;
+export declare const digestLimitsV1: {
+    readonly leadChars: 155;
+    readonly contextWords: 50;
+    readonly minIdeas: 3;
+    readonly maxIdeas: 5;
+    readonly claimWords: 20;
+    readonly detailWords: 60;
+    readonly detailSentences: 3;
+    readonly maxQuotesPerIdea: 2;
+    readonly minQuoteWords: 4;
+    readonly quoteWords: 25;
+    readonly totalQuoteWords: 150;
+    readonly sourceQuoteShare: 0.1;
+    readonly maxTags: 3;
+};
+/** The current (v2) limits. A gist is its lead plus context; quotes are counted per idea and per digest. */
+export declare const digestLimits: {
+    readonly leadChars: 240;
+    readonly contextWords: 80;
+    readonly gistWords: 100;
+    readonly gistSentences: 5;
+    readonly minIdeas: 3;
+    readonly maxIdeas: 5;
+    readonly claimWords: 20;
+    readonly detailWords: 60;
+    readonly detailSentences: 3;
+    readonly maxQuotesPerIdea: 2;
+    readonly minQuotes: 1;
+    readonly maxQuotes: 6;
+    readonly minQuoteWords: 4;
+    readonly quoteWords: 25;
+    readonly attributionWords: 25;
+    readonly totalQuoteWords: 150;
+    readonly sourceQuoteShare: 0.1;
+    readonly maxTags: 3;
+};
+export interface DigestIssue {
+    path: string;
+    code: string;
+}
+export interface LocatedQuote {
+    idea: number;
+    quote: number;
+    anchor: TextQuote;
+}
+export interface DigestCheck {
+    ok: boolean;
+    issues: DigestIssue[];
+    quotes: LocatedQuote[];
+}
+export interface DigestOptions {
+    /** Controlled tag vocabulary; omitted means any lowercase kebab-case tags (1-3 in v1, 0-3 in v2). */
+    tags?: readonly string[];
+    /** Optional semantic check that a quote supports its claim, e.g. embedding cosine. */
+    supports?: (claim: string, quote: string) => number;
+    supportThreshold?: number;
+}
+/** Parse an untrusted digest (v1 or v2) into its shape, or report why not. */
+export declare function parseDigest(value: unknown): {
+    digest?: Digest;
+    issues: DigestIssue[];
+};
+/** Check every rule of the digest's own version that code can decide against the captured Markdown. */
+export declare function checkDigest(digest: Digest, source: string, options?: DigestOptions): DigestCheck;

package/dist/src/digest/schema.js

@@ -0,0 +1,138 @@
+import { foldText, locateAll, textQuote, words } from '../annotations/quote.js';
+/**
+ * Digest v2: a gist led by one sentence, and 3-5 ideas in the author's order, each a claim with detail and 0-2 verbatim
+ * quotes; the digest carries 1-6 quotes in all. Digest v1 (one short lead, 1-2 quotes on every idea, ideas in source
+ * order, kind and voice required) stays readable and checkable; new digests are v2. 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 digestSchemaVersion = 2;
+export const digestLimitsV1 = { 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 };
+/** The current (v2) limits. A gist is its lead plus context; quotes are counted per idea and per digest. */
+export const digestLimits = { leadChars: 240, contextWords: 80, gistWords: 100, gistSentences: 5, minIdeas: 3, maxIdeas: 5, claimWords: 20, detailWords: 60, detailSentences: 3, maxQuotesPerIdea: 2, minQuotes: 1, maxQuotes: 6, minQuoteWords: 4, quoteWords: 25, attributionWords: 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);
+/** v1: sentence terminators followed by more text; abbreviations are rare enough in a 155-character lead to reject. */
+const sentencesV1 = (v) => foldText(v).split(/(?<=[.!?])\s+(?=\S)/).length;
+/** v2: a terminator (and closing quotes) followed by a capital or digit, the same split Jungle's first-sentence lead uses, so `e.g. this` stays one sentence. */
+const sentences = (v) => foldText(v).split(/(?<=[.!?]["')]*)\s+(?=["(]?[A-Z0-9])/).length;
+/** Parse an untrusted digest (v1 or v2) into its 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 && value.schemaVersion !== 2)
+        return { issues: [{ path: '', code: 'shape' }] };
+    const v2 = value.schemaVersion === 2;
+    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) || !(v2 && idea.kind === undefined || ideaKinds.includes(idea.kind)))
+                return bad(at);
+            const voice = idea.voice;
+            if (!(v2 && voice === undefined) && !(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, v2 ? ['text', 'speaker', 'attribution', 'locator'] : ['text', 'speaker', 'locator']) || !str(quote.text, 600) || quote.speaker !== undefined && !str(quote.speaker, 200) || quote.attribution !== undefined && !str(quote.attribution, 600))
+                    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 rule of the digest's own version that code can decide against the captured Markdown. */
+export function checkDigest(digest, source, options = {}) {
+    const issues = [], located = [], issue = (path, code) => { issues.push({ path, code }); }, v2 = digest.schemaVersion === 2, L = v2 ? digestLimits : digestLimitsV1, count = v2 ? sentences : sentencesV1;
+    const { lead, context } = digest.gist;
+    if (lead.length > L.leadChars)
+        issue('gist.lead', 'too-long');
+    if (count(lead) !== 1)
+        issue('gist.lead', 'one-sentence');
+    if (context !== undefined && words(context) > L.contextWords)
+        issue('gist.context', 'too-long');
+    if (v2 && words(lead) + (context === undefined ? 0 : words(context)) > digestLimits.gistWords)
+        issue('gist', 'too-long');
+    if (v2 && count(lead) + (context === undefined ? 0 : count(context)) > digestLimits.gistSentences)
+        issue('gist', 'too-many-sentences');
+    if (digest.ideas.length < L.minIdeas || digest.ideas.length > L.maxIdeas)
+        issue('ideas', 'count');
+    const claims = new Set();
+    let quoteWords = 0, quoteCount = 0;
+    digest.ideas.forEach((idea, i) => {
+        const at = `ideas.${i}`;
+        if (words(idea.claim) > L.claimWords)
+            issue(at + '.claim', 'too-long');
+        if (count(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 (count(idea.detail) > L.detailSentences)
+            issue(at + '.detail', 'too-many-sentences');
+        // v1 needs a quote on every idea; v2 allows quoteless ideas and counts quotes per digest below.
+        if (idea.quotes.length < (v2 ? 0 : 1) || idea.quotes.length > L.maxQuotesPerIdea)
+            issue(at + '.quotes', 'count');
+        idea.quotes.forEach((quote, j) => {
+            const path = `${at}.quotes.${j}`, n = words(quote.text);
+            quoteWords += n;
+            quoteCount++;
+            if (n > L.quoteWords)
+                issue(path, 'too-long');
+            if (n < L.minQuoteWords)
+                issue(path, 'too-short');
+            if (quote.attribution !== undefined && words(quote.attribution) > digestLimits.attributionWords)
+                issue(path + '.attribution', 'too-long');
+            if (idea.voice && 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');
+        });
+    });
+    if (v2 && (quoteCount < digestLimits.minQuotes || quoteCount > digestLimits.maxQuotes))
+        issue('ideas', 'quote-count');
+    // v1 only: ideas follow the source, each idea's earliest located quote starting no earlier than the previous idea's.
+    let previous = -1;
+    if (!v2)
+        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 < (v2 ? 0 : 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 Digest, type DigestOptions } 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: Digest;
+    review: DigestReview;
+    createdAt: string;
+}
+/** A parsed digest serialized in fixed key order, so key order never makes a different object. Optional fields appear only when present. */
+export declare function canonicalDigest(d: Digest): 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 it is Digest v2 and every v2 rule passes against the revision it was made from.
+ * Stored v1 digests stay readable; new ones are v2. 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 (v1 or v2). Rejected or unreviewed fields never leave the device; v1 ideas keep their kind. */
+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,79 @@
+import { checkDigest, digestSchemaVersion, 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. Optional fields appear only when present. */
+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, ...(i.kind !== undefined ? { kind: i.kind } : {}), ...(i.voice ? { 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.attribution !== undefined ? { attribution: q.attribution } : {}), ...(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 it is Digest v2 and every v2 rule passes against the revision it was made from.
+ * Stored v1 digests stay readable; new ones are v2. 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 });
+    if (parsed.digest.schemaVersion !== digestSchemaVersion)
+        throw Object.assign(new StoreError('invalid-input'), { issues: [{ path: 'schemaVersion', code: 'superseded' }] });
+    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',?,?,?,?,?)").run(id, input.itemId, input.revisionId, parsed.digest.schemaVersion, 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 (v1 or v2). Rejected or unreviewed fields never leave the device; v1 ideas keep their kind. */
+export function acceptedDigest(d) {
+    const ideas = d.output.ideas.flatMap((idea, i) => d.review.ideas?.[i] === 'accepted' ? [{ claim: idea.claim, detail: idea.detail, ...(idea.kind !== undefined ? { 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;