@hraness/sponge 0.2.5 → 0.3.0

package/dist/src/digest/endpoint.js

@@ -1,4 +1,4 @@
-import { DigestError } from './pipeline.js';
+import { SpongeError } from '../errors.js';
 /**
  * A user-started local OpenAI-compatible server (llama.cpp `llama-server`, LM Studio, Ollama). Captured text must not
  * leave the machine, so only literal loopback HTTP origins are accepted, redirects are refused, and Sponge never starts a server.
@@ -9,17 +9,23 @@ export function loopbackEndpoint(value) {
         url = new URL(value);
     }
     catch {
-        throw new DigestError('invalid-input');
+        throw new SpongeError('invalid-input');
     }
     // A hostname such as `localhost` resolves through configuration Sponge does not control; only literal addresses pass.
-    if (url.protocol !== 'http:' || !['127.0.0.1', '[::1]'].includes(url.hostname) || url.username || url.password || url.search || url.hash || !['', '/', '/v1', '/v1/'].includes(url.pathname))
-        throw new DigestError('invalid-input');
+    if (url.protocol !== 'http:' ||
+        !['127.0.0.1', '[::1]'].includes(url.hostname) ||
+        url.username ||
+        url.password ||
+        url.search ||
+        url.hash ||
+        !['', '/', '/v1', '/v1/'].includes(url.pathname))
+        throw new SpongeError('invalid-input');
     return new URL(url.origin);
 }
 async function readCapped(response, max) {
     const reader = response.body?.getReader(), chunks = [];
     if (!reader)
-        throw new DigestError('unavailable');
+        throw new SpongeError('unavailable');
     let size = 0;
     for (;;) {
         const { done, value } = await reader.read();
@@ -28,7 +34,7 @@ async function readCapped(response, max) {
         size += value.byteLength;
         if (size > max) {
             await reader.cancel().catch(() => undefined);
-            throw new DigestError('limit-exceeded');
+            throw new SpongeError('limit-exceeded');
         }
         chunks.push(value);
     }
@@ -37,7 +43,9 @@ async function readCapped(response, max) {
 const label = (v, max = 128) => typeof v === 'string' && v.trim() && v.length <= max && !/[\u0000-\u001f\u007f]/.test(v) ? v.trim() : undefined;
 /** GGUF quantization from a model filename, e.g. `gemma-4-12b-it-Q4_K_M.gguf` → `Q4_K_M`. */
 export function quantizationOf(path) {
-    return /(?:^|[-_.])((?:IQ|Q)\d(?:_[A-Z0-9]+)*|BF16|F16|F32)(?=\.gguf$|[-_.])/i.exec(path.split('/').pop() ?? '')?.[1]?.toUpperCase();
+    return /(?:^|[-_.])((?:IQ|Q)\d(?:_[A-Z0-9]+)*|BF16|F16|F32)(?=\.gguf$|[-_.])/i
+        .exec(path.split('/').pop() ?? '')?.[1]
+        ?.toUpperCase();
 }
 /**
  * Confirm the server lists `model`, read what identity it exposes (llama.cpp `/props`, Ollama `/api/version`),
@@ -46,58 +54,86 @@ export function quantizationOf(path) {
 export async function connectEndpoint(options) {
     const origin = loopbackEndpoint(options.endpoint), request = options.fetch ?? fetch, model = label(options.model, 256);
     if (!model)
-        throw new DigestError('invalid-input');
+        throw new SpongeError('invalid-input');
     const get = async (path) => {
-        const signal = AbortSignal.any([options.signal ?? new AbortController().signal, AbortSignal.timeout(options.probeTimeoutMs ?? 10000)]);
+        const signal = AbortSignal.any([
+            options.signal ?? new AbortController().signal,
+            AbortSignal.timeout(options.probeTimeoutMs ?? 10000),
+        ]);
         try {
-            const r = await request(new URL(path, origin), { signal, redirect: 'error', headers: { accept: 'application/json' } });
+            const r = await request(new URL(path, origin), {
+                signal,
+                redirect: 'error',
+                headers: { accept: 'application/json' },
+            });
             return r.ok ? JSON.parse(await readCapped(r, 1 << 20)) : undefined;
         }
         catch (error) {
             if (options.signal?.aborted)
-                throw new DigestError('cancelled');
-            if (error instanceof DigestError)
+                throw new SpongeError('cancelled');
+            if (error instanceof SpongeError)
                 throw error;
             return undefined;
         }
     };
-    const models = await get('/v1/models');
+    const models = (await get('/v1/models'));
     if (!Array.isArray(models?.data))
-        throw new DigestError('unavailable');
-    if (!models.data.some(m => m?.id === model))
-        throw new DigestError('invalid-input');
-    const props = await get('/props'), build = label(props?.build_info);
+        throw new SpongeError('unavailable');
+    if (!models.data.some((m) => m?.id === model))
+        throw new SpongeError('invalid-input');
+    const props = (await get('/props')), build = label(props?.build_info);
     let runtime = build ? `llama.cpp ${build}` : undefined;
     if (!runtime) {
         const ollama = label((await get('/api/version'))?.version);
         runtime = ollama ? `ollama ${ollama}` : 'openai-compatible';
     }
-    const identity = { model, quantization: (typeof props?.model_path === 'string' && quantizationOf(props.model_path)) || quantizationOf(model) || 'unknown', runtime };
-    return { identity, generate: (messages, schema, generate) => complete(origin, request, model, messages, schema, generate) };
+    const identity = {
+        model,
+        quantization: (typeof props?.model_path === 'string' && quantizationOf(props.model_path)) || quantizationOf(model) || 'unknown',
+        runtime,
+    };
+    return {
+        identity,
+        generate: (messages, schema, generate) => complete(origin, request, model, messages, schema, generate),
+    };
 }
 async function complete(origin, request, model, messages, schema, o) {
-    const body = JSON.stringify({ model, messages, stream: false, temperature: o.temperature, seed: o.seed, max_tokens: o.maxTokens, response_format: { type: 'json_schema', json_schema: { name: 'sponge_digest', strict: true, schema } } });
-    const response = await request(new URL('/v1/chat/completions', origin), { method: 'POST', signal: o.signal, redirect: 'error', headers: { 'content-type': 'application/json', accept: 'application/json' }, body });
+    const body = JSON.stringify({
+        model,
+        messages,
+        stream: false,
+        temperature: o.temperature,
+        seed: o.seed,
+        max_tokens: o.maxTokens,
+        response_format: { type: 'json_schema', json_schema: { name: 'sponge_digest', strict: true, schema } },
+    });
+    const response = await request(new URL('/v1/chat/completions', origin), {
+        method: 'POST',
+        signal: o.signal,
+        redirect: 'error',
+        headers: { 'content-type': 'application/json', accept: 'application/json' },
+        body,
+    });
     if (!response.ok) {
         await response.body?.cancel().catch(() => undefined);
-        throw new DigestError('unavailable');
+        throw new SpongeError('unavailable');
     }
     let parsed;
     try {
         parsed = JSON.parse(await readCapped(response, o.maxOutputBytes * 2 + 65536));
     }
     catch (error) {
-        if (error instanceof DigestError)
+        if (error instanceof SpongeError)
             throw error;
-        throw new DigestError('unavailable');
+        throw new SpongeError('unavailable');
     }
     const choice = parsed?.choices?.[0];
     if (choice?.finish_reason === 'length')
-        throw new DigestError('limit-exceeded');
+        throw new SpongeError('limit-exceeded');
     const content = choice?.message?.content;
     if (typeof content !== 'string' || !content.trim())
-        throw new DigestError('unavailable');
+        throw new SpongeError('unavailable');
     if (Buffer.byteLength(content) > o.maxOutputBytes)
-        throw new DigestError('limit-exceeded');
+        throw new SpongeError('limit-exceeded');
     return content;
 }

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

@@ -1,11 +1,10 @@
-import { forms, type DigestIssue, type DigestOptions, type DigestV1 } from './schema.js';
-import type { LibraryStore } from '../store/index.js';
-import type { Derivation } from '../store/foundation.js';
+import { forms, type DigestIssue, type DigestOptions, type DigestV2 } from './schema.js';
+import type { Derivation, DigestCandidate } from './derivation.js';
 /**
- * Model-agnostic Digest v1 drafting. The model sees numbered passages and cites a passage id plus a short exact
- * span; code snaps, orders, prunes and checks. Nothing leaves this module except through the injected model.
+ * Model-agnostic Digest v2 drafting. The model sees numbered passages and cites a passage id plus a short exact
+ * span; code snaps, prunes and checks. Nothing leaves this module except through the injected model.
  */
-export declare const PROMPT_VERSION = "sponge-digest-prompt-v1";
+export declare const PROMPT_VERSION = "sponge-digest-prompt-v4";
 export type ChatMessage = {
     role: 'system' | 'user' | 'assistant';
     content: string;
@@ -29,7 +28,7 @@ export interface DigestModel {
     generate(messages: ChatMessage[], schema: JsonSchema, options: GenerateOptions): Promise<string>;
 }
 /** Output-shaping parameters are hashed; time and byte bounds are not, because they only decide whether a run finishes. */
-export interface DigestParams {
+interface DigestParams {
     temperature: number;
     seed: number;
     maxTokens: number;
@@ -39,17 +38,7 @@ export interface DigestParams {
     deadlineMs: number;
     maxOutputBytes: number;
 }
-/** 24k characters is roughly 6k tokens of passages, leaving room for instructions and output in an 8k context on an 8 GB Mac. */
-export declare const defaultDigestParams: DigestParams;
-export type DigestErrorCode = 'invalid-input' | 'unavailable' | 'cancelled' | 'limit-exceeded';
-export declare class DigestError extends Error {
-    readonly code: DigestErrorCode;
-    readonly issues?: DigestIssue[] | undefined;
-    constructor(code: DigestErrorCode, issues?: DigestIssue[] | undefined);
-}
-export type Form = typeof forms[number];
-/** Quotes under this many words carry no evidence; the checker is gaining the same floor. */
-export declare const minQuoteWords = 4;
+export type Form = (typeof forms)[number];
 export interface Passage {
     id: number;
     start: number;
@@ -57,30 +46,29 @@ export interface Passage {
     heading: string;
     text: string;
 }
-export interface Highlight {
+interface Highlight {
     text: string;
     start?: number;
 }
-/** Sorted-key JSON; the only serialization that enters input hashes. */
+/**
+ * Sorted-key JSON; the only serialization that enters input hashes. Deliberately not `util/canonical.ts`: this one
+ * accepts finite non-integer numbers (temperature) and writes `undefined` array entries as null, so merging would
+ * change digest input hashes.
+ */
 export declare function canonicalJson(value: unknown): string;
 /** Paragraph-level passages with raw offsets. Headings label passages; code fences and image-only blocks are not quotable. */
 export declare function passages(markdown: string, maxChars?: number): Passage[];
 /** Pack passages into sections of at most `budget` display characters, preferring heading boundaries past half a budget. */
 export declare function sectionsOf(list: Passage[], budget: number): Passage[][];
-export declare const quoteBudget: (markdown: string) => number;
 /** JSON Schema for the model's draft. Tags become an enum when a vocabulary is given. */
 export declare function draftSchema(passageCount: number, vocabulary?: readonly string[]): JsonSchema;
-export declare function notesSchema(first: number, last: number): JsonSchema;
-interface Draft {
-    digest: DigestV1;
-    cites: (number | undefined)[][];
-}
 export interface QuoteStats {
     exact: number;
     folded: number;
     snapped: number;
     missing: number;
     short: number;
+    trimmed?: number;
 }
 export type QuoteMatch = 'exact' | 'folded' | 'snapped' | 'missing';
 /**
@@ -94,8 +82,11 @@ export declare function snapQuote(source: string, text: string, within?: {
     text: string;
     match: QuoteMatch;
 };
-/** Snap every quote in place and drop quotes under `minQuoteWords`. */
-export declare function snapQuotes(draft: Draft, source: string, list: Passage[]): QuoteStats;
+/**
+ * A located quote over the word limit keeps its leading words: a prefix of a source span is still verbatim. Trailing
+ * clause punctuation goes; unlocated quotes are left for the checker.
+ */
+export declare function trimQuote(text: string, max?: number): string;
 export interface DraftInput {
     revisionId: string;
     markdown: string;
@@ -126,7 +117,7 @@ export interface DraftTrace {
     };
 }
 export interface DraftResult {
-    output: DigestV1;
+    output: DigestV2;
     inputHash: string;
     producer: Record<string, unknown>;
     options: DigestOptions;
@@ -136,11 +127,41 @@ export interface DraftResult {
 export declare function digestInputHash(input: Pick<DraftInput, 'revisionId' | 'markdown' | 'form' | 'highlights' | 'vocabulary' | 'params' | 'supportThreshold' | 'embed'> & {
     model: ModelIdentity;
 }): string;
-/** Unqualified on real claims: a deliberately low bar that only catches quotes unrelated to their claim. */
-export declare const defaultSupportThreshold = 0.35;
 export declare function draftDigest(input: DraftInput): Promise<DraftResult>;
+/**
+ * What `createDigest` needs from a library (a `LibraryStore` satisfies it). Declared here, not imported, so drafting
+ * never depends on the store.
+ */
+export interface DigestStore {
+    read(itemId: string): {
+        revisionId: string;
+        markdown: string;
+        title: string;
+        kind: string;
+    } | null;
+    annotations: {
+        list(itemId: string): {
+            kind: string;
+            revisionId: string | null;
+            anchored?: boolean;
+            anchor: unknown;
+        }[];
+    };
+    derivations: {
+        find(kind: 'digest', revisionId: string, inputHash: string): Derivation | undefined;
+        put(kind: 'digest', input: {
+            itemId: string;
+            revisionId: string;
+            producer: Record<string, unknown>;
+        } & DigestCandidate): {
+            id: string;
+            duplicate: boolean;
+        };
+        read(kind: 'digest', id: string): Derivation | undefined;
+    };
+}
 /** Draft and store a digest for the item's current revision. A matching input hash returns the stored draft without calling the model. */
-export declare function createDigest(store: LibraryStore, itemId: string, model: DigestModel, options?: Omit<DraftInput, 'revisionId' | 'markdown' | 'title' | 'form' | 'model' | 'highlights'>): Promise<{
+export declare function createDigest(store: DigestStore, itemId: string, model: DigestModel, options?: Omit<DraftInput, 'revisionId' | 'markdown' | 'title' | 'form' | 'model' | 'highlights'>): Promise<{
     derivation: Derivation;
     duplicate: boolean;
     trace?: DraftTrace;