@hraness/sponge 0.2.6 → 0.3.0

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

@@ -5,15 +5,15 @@ import { type TextQuote } from '../annotations/quote.js';
  * 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;
 } | {
@@ -27,20 +27,20 @@ export interface DigestQuote {
     attribution?: string;
     locator?: QuoteLocator;
 }
-export interface DigestIdea {
+interface DigestIdea {
     claim: string;
     detail: string;
-    kind?: typeof ideaKinds[number];
+    kind?: (typeof ideaKinds)[number];
     voice?: Voice;
     quotes: DigestQuote[];
 }
-export interface DigestIdeaV1 extends DigestIdea {
-    kind: typeof ideaKinds[number];
+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;
@@ -50,7 +50,7 @@ export interface DigestV1 {
 }
 export interface DigestV2 {
     schemaVersion: 2;
-    form: typeof forms[number];
+    form: (typeof forms)[number];
     gist: {
         lead: string;
         context?: string;
@@ -60,21 +60,6 @@ export interface DigestV2 {
 }
 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;
@@ -100,7 +85,7 @@ export interface DigestIssue {
     path: string;
     code: string;
 }
-export interface LocatedQuote {
+interface LocatedQuote {
     idea: number;
     quote: number;
     anchor: TextQuote;
@@ -124,3 +109,4 @@ export declare function parseDigest(value: unknown): {
 };
 /** 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

@@ -5,14 +5,47 @@ import { foldText, locateAll, textQuote, words } from '../annotations/quote.js';
  * 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 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 };
+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 };
+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);
 /** 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;
@@ -20,42 +53,73 @@ const sentencesV1 = (v) => foldText(v).split(/(?<=[.!?])\s+(?=\S)/).length;
 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)
+    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) || !(v2 && idea.kind === undefined || 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 (!(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))))
+            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))
+                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 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 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');
@@ -103,7 +167,7 @@ export function checkDigest(digest, source, options = {}) {
             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) });
@@ -117,7 +181,7 @@ export function checkDigest(digest, source, options = {}) {
     let previous = -1;
     if (!v2)
         digest.ideas.forEach((_, i) => {
-            const starts = located.filter(q => q.idea === i).map(q => q.anchor.start);
+            const starts = located.filter((q) => q.idea === i).map((q) => q.anchor.start);
             if (!starts.length)
                 return;
             const first = Math.min(...starts);
@@ -130,9 +194,13 @@ export function checkDigest(digest, source, options = {}) {
     // 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)
+    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;

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

@@ -4,13 +4,46 @@
  * 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']);
+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-'];
+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',
+]);
+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) {
+function fieldKey(field) {
     try {
         return decodeURIComponent(field.split('=', 1)[0].replaceAll('+', ' ')).toLowerCase();
     }
@@ -18,12 +51,20 @@ export function fieldKey(field) {
         return undefined;
     }
 }
-export function isSecretField(key) { return secretFields.has(key) || secretPrefixes.some(p => key.startsWith(p)); }
+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); });
+    const fields = search
+        .slice(1)
+        .split('&')
+        .filter((field) => {
+        const key = fieldKey(field);
+        return key === undefined || !drop(key);
+    });
     return fields.length ? '?' + fields.join('&') : '';
 }
 /**
@@ -42,11 +83,22 @@ export function isCapabilityUrl(locator) {
         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); }))
+    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')
+    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))

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

@@ -3,15 +3,13 @@ export interface ItemUri {
     uri: string;
     role: 'primary' | 'alias';
     resolvable: boolean;
-    origin: 'locator' | 'revision';
+    origin: 'locator' | 'revision' | 'metadata' | 'user';
 }
 /** `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
@@ -24,7 +22,10 @@ export declare function deriveUris(input: {
     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;
+/**
+ * How the first source was reached decides the default visibility; see docs/decisions/sync-and-publishing.md.
+ * An imported local file with a recorded web address (`webUri`, origin 'metadata') is classed by that address instead.
+ */
+export declare function accessClass(realm: string, locator: string, webUri?: 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';