@hraness/sponge 0.2.5 → 0.3.0

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

@@ -1,38 +1,56 @@
 import { type TextQuote } 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.
+ * 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"];
+declare const ideaKinds: readonly ["finding", "argument", "method", "evidence", "recommendation", "counterpoint"];
 export declare const forms: readonly ["article", "video", "paper", "thread", "pdf"];
-export type Voice = {
+type Voice = {
     type: 'author';
 } | {
     type: 'speaker' | 'reported';
     name: string;
 };
-export type QuoteLocator = {
+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 {
+interface DigestIdea {
     claim: string;
     detail: string;
-    kind: typeof ideaKinds[number];
-    voice: Voice;
+    kind?: (typeof ideaKinds)[number];
+    voice?: Voice;
     quotes: DigestQuote[];
 }
+interface DigestIdeaV1 extends DigestIdea {
+    kind: (typeof ideaKinds)[number];
+    voice: Voice;
+}
 export interface DigestV1 {
     schemaVersion: 1;
-    form: typeof forms[number];
+    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;
@@ -40,17 +58,25 @@ export interface DigestV1 {
     ideas: DigestIdea[];
     tags: string[];
 }
+export type Digest = DigestV1 | DigestV2;
+export declare const digestSchemaVersion = 2;
+/** 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: 155;
-    readonly contextWords: 50;
+    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;
@@ -59,7 +85,7 @@ export interface DigestIssue {
     path: string;
     code: string;
 }
-export interface LocatedQuote {
+interface LocatedQuote {
     idea: number;
     quote: number;
     anchor: TextQuote;
@@ -70,16 +96,17 @@ export interface DigestCheck {
     quotes: LocatedQuote[];
 }
 export interface DigestOptions {
-    /** Controlled tag vocabulary; omitted means any 1-3 lowercase tags. */
+    /** 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 model output into a DigestV1 shape, or report why not. */
+/** Parse an untrusted digest (v1 or v2) into its shape, or report why not. */
 export declare function parseDigest(value: unknown): {
-    digest?: DigestV1;
+    digest?: Digest;
     issues: DigestIssue[];
 };
-/** Check every v1 rule that code can decide against the captured Markdown. */
-export declare function checkDigest(digest: DigestV1, source: string, options?: DigestOptions): DigestCheck;
+/** 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;
+export {};

package/dist/src/digest/schema.js

@@ -1,92 +1,173 @@
 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.
+ * 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'];
+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 };
+export const digestSchemaVersion = 2;
+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 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. */
+/** 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)
+    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))
+    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))
+            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 (!object(voice) || !(voice.type === 'author' && keys(voice, ['type']) || (voice.type === 'speaker' || voice.type === 'reported') && keys(voice, ['type', 'name']) && str(voice.name, 200)))
+            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, ['text', 'speaker', 'locator']) || !str(quote.text, 600) || quote.speaker !== undefined && !str(quote.speaker, 200))
+                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)))
+                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)))
+    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. */
+/** 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 }); }, L = digestLimits;
-    if (digest.gist.lead.length > L.leadChars)
+    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 (sentences(digest.gist.lead) !== 1)
+    if (count(lead) !== 1)
         issue('gist.lead', 'one-sentence');
-    if (digest.gist.context !== undefined && words(digest.gist.context) > L.contextWords)
+    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;
+    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 (sentences(idea.claim) !== 1)
+        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 (sentences(idea.detail) > L.detailSentences)
+        if (count(idea.detail) > L.detailSentences)
             issue(at + '.detail', 'too-many-sentences');
-        if (idea.quotes.length < 1 || idea.quotes.length > L.maxQuotesPerIdea)
+        // 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}`, count = words(quote.text);
-            quoteWords += count;
-            if (count > L.quoteWords)
+            const path = `${at}.quotes.${j}`, n = words(quote.text);
+            quoteWords += n;
+            quoteCount++;
+            if (n > L.quoteWords)
                 issue(path, 'too-long');
-            if (count < L.minQuoteWords)
+            if (n < L.minQuoteWords)
                 issue(path, 'too-short');
-            if (idea.voice.type !== 'author' && !quote.speaker)
+            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));
+            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) });
@@ -94,25 +175,32 @@ export function checkDigest(digest, source, options = {}) {
                 issue(path, 'unsupported');
         });
     });
-    // Ideas follow the source: each idea's earliest located quote starts no earlier than the previous idea's.
+    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;
-    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 (!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 < 1 || digest.tags.length > L.maxTags || new Set(digest.tags).size !== digest.tags.length)
+    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'); });
+    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/errors.d.ts

@@ -0,0 +1,46 @@
+import type { ErrorCode } from '../contracts/index.js';
+export type { ErrorCode };
+/** Public codes: the frozen v1 ErrorEnvelope vocabulary. Exit statuses and hints are keyed by these. */
+export declare const publicCodes: readonly ["grant-permission", "repair-auth", "unsupported", "unavailable", "rate-limited", "partial", "cleanup-required", "cancelled", "invalid-input", "unclassified", "integrity", "limit-exceeded", "runtime-missing", "schema-newer", "owner-busy"];
+/** Detail codes narrow a public code. They are stored as job reasons, matched by callers, and printed as `reason`. */
+declare const parents: {
+    readonly 'invalid-index': "invalid-input";
+    readonly 'stale-index': "unavailable";
+    readonly 'incomplete-index': "unavailable";
+    readonly 'cancelled-index': "unavailable";
+    readonly 'invalid-search-query': "invalid-input";
+    readonly 'invalid-search-vector': "invalid-input";
+    readonly 'invalid-search-index': "integrity";
+    readonly 'search-generation-missing': "unavailable";
+    readonly 'unsupported-vector-runtime': "unsupported";
+    readonly 'not-digest': "unsupported";
+    readonly malformed: "invalid-input";
+    readonly 'no-capture': "invalid-input";
+};
+export type DetailCode = keyof typeof parents;
+export type SpongeCode = ErrorCode | DetailCode;
+export declare const indexCodes: readonly DetailCode[];
+export declare const isSpongeCode: (value: unknown) => value is SpongeCode;
+/** The one code→exit-status table (contracts `exitCodes`: 0 success, 1 failure, 2 invalid input, 3 partial, 4 action required, 130 cancelled). */
+export declare const exitStatus: Readonly<Record<ErrorCode, number>>;
+/** The one code→user-facing hint table. Fixed text only: never paths, sources, credentials or upstream prose. */
+export declare const hints: Readonly<Record<ErrorCode, string>>;
+export interface SpongeErrorOptions {
+    detail?: Record<string, unknown>;
+    cause?: unknown;
+    issues?: readonly unknown[];
+}
+/** The one error type. `message` is the code, so bare `String(error)` never carries detail, paths or causes. */
+export declare class SpongeError extends Error {
+    readonly code: SpongeCode;
+    readonly detail?: Record<string, unknown>;
+    readonly issues?: readonly any[];
+    constructor(code: SpongeCode, options?: SpongeErrorOptions);
+}
+/** A thrown value's code: a SpongeError's, or any object's `code` when it is a Sponge code; otherwise the fallback. */
+export declare function codeOf(error: unknown, fallback?: SpongeCode): SpongeCode;
+/** The public code for a code or thrown value. */
+export declare function publicCode(value: unknown, fallback?: SpongeCode): ErrorCode;
+export declare const exitFor: (value: unknown) => number;
+/** The cause chain for --debug only: names, codes, details, messages and the first stack. */
+export declare function debugChain(error: unknown): string;

package/dist/src/errors.js

@@ -0,0 +1,117 @@
+/** Public codes: the frozen v1 ErrorEnvelope vocabulary. Exit statuses and hints are keyed by these. */
+export const publicCodes = [
+    'grant-permission',
+    'repair-auth',
+    'unsupported',
+    'unavailable',
+    'rate-limited',
+    'partial',
+    'cleanup-required',
+    'cancelled',
+    'invalid-input',
+    'unclassified',
+    'integrity',
+    'limit-exceeded',
+    'runtime-missing',
+    'schema-newer',
+    'owner-busy',
+];
+/** Detail codes narrow a public code. They are stored as job reasons, matched by callers, and printed as `reason`. */
+const parents = {
+    'invalid-index': 'invalid-input',
+    'stale-index': 'unavailable',
+    'incomplete-index': 'unavailable',
+    'cancelled-index': 'unavailable',
+    'invalid-search-query': 'invalid-input',
+    'invalid-search-vector': 'invalid-input',
+    'invalid-search-index': 'integrity',
+    'search-generation-missing': 'unavailable',
+    'unsupported-vector-runtime': 'unsupported',
+    'not-digest': 'unsupported',
+    malformed: 'invalid-input',
+    'no-capture': 'invalid-input',
+};
+export const indexCodes = [
+    'invalid-index',
+    'stale-index',
+    'incomplete-index',
+    'cancelled-index',
+];
+const known = new Set([...publicCodes, ...Object.keys(parents)]);
+export const isSpongeCode = (value) => typeof value === 'string' && known.has(value);
+/** The one code→exit-status table (contracts `exitCodes`: 0 success, 1 failure, 2 invalid input, 3 partial, 4 action required, 130 cancelled). */
+export const exitStatus = {
+    'grant-permission': 4,
+    'repair-auth': 4,
+    'cleanup-required': 4,
+    'runtime-missing': 4,
+    'owner-busy': 4,
+    'invalid-input': 2,
+    partial: 3,
+    cancelled: 130,
+    unsupported: 1,
+    unavailable: 1,
+    'rate-limited': 1,
+    unclassified: 1,
+    integrity: 1,
+    'limit-exceeded': 1,
+    'schema-newer': 1,
+};
+/** The one code→user-facing hint table. Fixed text only: never paths, sources, credentials or upstream prose. */
+export const hints = {
+    'grant-permission': 'Grant the requested permission, then retry.',
+    'repair-auth': 'Sign in again or repair the saved connection, then retry.',
+    unsupported: 'This source or platform is not supported.',
+    unavailable: 'Not found or not reachable now. Check the identifier, or retry later.',
+    'rate-limited': 'The source is rate limiting requests. Retry later.',
+    partial: 'Saved with missing parts. Refresh later to try again.',
+    'cleanup-required': 'A previous run left work to clean up. Run `sponge queue recover`.',
+    cancelled: 'Cancelled.',
+    'invalid-input': 'Check the command and its arguments. Run `sponge help COMMAND`.',
+    unclassified: 'Unexpected failure. Run again with --debug for details.',
+    integrity: 'A verification check failed. Nothing was changed. Run `sponge doctor`.',
+    'limit-exceeded': 'A size, count or time limit was exceeded.',
+    'runtime-missing': 'A required runtime is not installed. Run `sponge setup`.',
+    'schema-newer': 'This library was written by a newer Sponge. Upgrade Sponge.',
+    'owner-busy': 'Another Sponge process owns the library. Wait for it, or run `sponge queue recover` after it stops.',
+};
+/** The one error type. `message` is the code, so bare `String(error)` never carries detail, paths or causes. */
+export class SpongeError extends Error {
+    code;
+    detail;
+    issues;
+    constructor(code, options = {}) {
+        super(code, options.cause === undefined ? undefined : { cause: options.cause });
+        this.code = code;
+        this.name = 'SpongeError';
+        if (options.detail)
+            this.detail = options.detail;
+        if (options.issues)
+            this.issues = options.issues;
+    }
+}
+/** A thrown value's code: a SpongeError's, or any object's `code` when it is a Sponge code; otherwise the fallback. */
+export function codeOf(error, fallback = 'unclassified') {
+    const code = error?.code;
+    return isSpongeCode(code) ? code : fallback;
+}
+/** The public code for a code or thrown value. */
+export function publicCode(value, fallback = 'unclassified') {
+    const code = isSpongeCode(value) ? value : codeOf(value, fallback);
+    return Object.hasOwn(parents, code) ? parents[code] : code;
+}
+export const exitFor = (value) => exitStatus[publicCode(value)];
+/** The cause chain for --debug only: names, codes, details, messages and the first stack. */
+export function debugChain(error) {
+    const lines = [];
+    let current = error, depth = 0;
+    while (current !== undefined && current !== null && depth < 8) {
+        const e = current;
+        lines.push(`${depth ? 'caused by' : 'error'}: ${String(e.name ?? typeof current)}${e.code !== undefined ? ` [${String(e.code)}]` : ''}${e.message !== undefined && e.message !== e.code ? ` ${String(e.message)}` : ''}${e.detail !== undefined ? ` ${JSON.stringify(e.detail)}` : ''}`);
+        if (!depth && typeof e.stack === 'string')
+            lines.push(...e.stack.split('\n').slice(1, 8));
+        current = current instanceof Error || typeof current === 'object' ? e.cause : undefined;
+        depth++;
+    }
+    return lines.map((line) => 'debug: ' + line).join('\n') + '\n';
+}

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

@@ -6,11 +6,6 @@
  */
 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;