@hraness/sponge 0.3.0 → 0.3.2

package/dist/src/annotations/quote.d.ts

@@ -7,6 +7,8 @@ export interface TextQuote {
     start: number;
     end: number;
 }
+/** Spoken text without transcript cues, whitespace collapsed: what a reader quotes from a transcript. */
+export declare function stripCues(raw: string): string;
 export declare function foldText(value: string): string;
 /** Every occurrence of `quote` in `source`, compared after folding. */
 export declare function locateAll(source: string, quote: string): {

package/dist/src/annotations/quote.js

@@ -1,9 +1,20 @@
 const context = 32;
 const graphemes = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
 const escapable = /^[\\`*_{}[\]()#+\-.!|>~<"']$/;
+/** A transcript cue at a line start: `- [00:02] ` (clipped captions) or `[00:00:02] ` (Sponge transcripts). */
+const cue = /^[ \t]*(?:[-*+][ \t]+)?\[(?:\d{1,2}:)?\d{1,2}:\d{2}\][ \t]+/;
+/** Spoken text without transcript cues, whitespace collapsed: what a reader quotes from a transcript. */
+export function stripCues(raw) {
+    return raw
+        .split('\n')
+        .map((line) => line.replace(cue, ''))
+        .join('\n')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
 /**
  * Fold the differences a reader cannot see: Markdown escapes, curly quotes, dashes, runs of
- * whitespace and Unicode normalization. Folding works on grapheme clusters, each NFC-normalized;
+ * whitespace, line-start transcript cues and Unicode normalization. Folding works on grapheme clusters, each NFC-normalized;
  * every folded code unit of a cluster maps to the cluster's raw bounds, so `map[i]` and `ends[i]`
  * bound the raw text of folded unit i and matches map back exactly.
  */
@@ -19,6 +30,17 @@ function fold(raw) {
     };
     for (let c = 0; c < clusters.length; c++) {
         const { segment, index } = clusters[c];
+        // A transcript cue reads as the space between caption lines, so a quote of the speech spans them.
+        const marker = (index === 0 || raw[index - 1] === '\n') && cue.exec(raw.slice(index, index + 32));
+        if (marker) {
+            const stop = index + marker[0].length;
+            if (!space && text.length)
+                emit(' ', index, stop);
+            space = true;
+            while (c + 1 < clusters.length && clusters[c + 1].index < stop)
+                c++;
+            continue;
+        }
         // An escaped character maps to its backslash, so a match starting there keeps the escape.
         let ch = segment, end = index + segment.length;
         if (segment === '\\' && c + 1 < clusters.length && escapable.test(clusters[c + 1].segment)) {
@@ -98,6 +120,12 @@ function rendered(raw) {
     for (let i = 0; i < raw.length; i++) {
         let ch = raw[i], at = i;
         if (lineStart) {
+            const c = cue.exec(raw.slice(i, i + 32));
+            if (c) {
+                i += c[0].length - 1;
+                lineStart = false;
+                continue;
+            }
             const m = /^[ \t]*(?:>[ \t]?|#{1,6}[ \t]+|[-*+][ \t]+|\d{1,3}[.)][ \t]+)*/.exec(raw.slice(i, i + 64));
             if (m[0].length) {
                 i += m[0].length - 1;

package/dist/src/cli/commands.js

@@ -591,7 +591,7 @@ export const commands = [
         summary: "Set or reset an item's title",
         usage: [
             ['title set ITEM TEXT', 'Use TEXT as the title; refresh and import never change it'],
-            ['title reset ITEM', 'Restore the default: the import note title, else the captured title'],
+            ['title reset ITEM', 'Restore the default: the captured title (a local scan takes its import note title)'],
         ],
         positional: (p) => (p[0] === 'set' && p.length === 3) || (p[0] === 'reset' && p.length === 2),
         flags: {},
@@ -791,5 +791,5 @@ export const usageOf = (name) => command(name)
     .join('\n');
 export function commandHelp(name) {
     const c = command(name), flags = Object.keys(c.flags);
-    return `sponge ${c.name} — ${c.summary}\n\nUsage:\n${c.usage.map(row).join('').replace(/^  /gm, '  sponge ')}${flags.length ? `\nFlags: ${flags.map((f) => '--' + f).join(' ')}\n` : ''}\nGlobal flags: --library /absolute/path --json --debug\n`;
+    return `sponge ${c.name} — ${c.summary}\n\nUsage:\n${c.usage.map(([synopsis, description]) => row([`sponge ${synopsis}`, description])).join('')}${flags.length ? `\nFlags: ${flags.map((f) => '--' + f).join(' ')}\n` : ''}\nGlobal flags: --library /absolute/path --json --debug\n`;
 }

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

@@ -4,7 +4,7 @@ import type { Derivation, DigestCandidate } from './derivation.js';
  * 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-v4";
+export declare const PROMPT_VERSION = "sponge-digest-prompt-v5";
 export type ChatMessage = {
     role: 'system' | 'user' | 'assistant';
     content: string;

package/dist/src/digest/pipeline.js

@@ -1,4 +1,4 @@
-import { foldText, locateAll, locateLoose, words } from '../annotations/quote.js';
+import { foldText, locateAll, locateLoose, stripCues, words } from '../annotations/quote.js';
 import { checkDigest, digestLimits as L, forms, parseDigest, } from './schema.js';
 import { SpongeError } from '../errors.js';
 import { sha256 } from '../util/hash.js';
@@ -6,7 +6,7 @@ import { sha256 } from '../util/hash.js';
  * 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 const PROMPT_VERSION = 'sponge-digest-prompt-v4';
+export const PROMPT_VERSION = 'sponge-digest-prompt-v5';
 /** 24k characters is roughly 6k tokens of passages, leaving room for instructions and output in an 8k context on an 8 GB Mac. */
 const defaultDigestParams = {
     temperature: 0,
@@ -97,7 +97,9 @@ function lastSentenceEnd(window) {
         best = m.index + m[0].length;
     return best;
 }
-const display = (p) => `[${p.id}] ${collapse(p.text)}`;
+const display = (p) => `[${p.id}] ${stripCues(p.text)}`;
+/** A raw source span as a quote: transcript cues inside it are dropped, so the quote reads as the speech. */
+const spoken = (raw) => (raw.includes('\n') && stripCues(raw) !== collapse(raw) ? stripCues(raw) : raw);
 /** Pack passages into sections of at most `budget` display characters, preferring heading boundaries past half a budget. */
 export function sectionsOf(list, budget) {
     const out = [];
@@ -148,7 +150,7 @@ export function draftSchema(passageCount, vocabulary) {
     return {
         type: 'object',
         additionalProperties: false,
-        required: ['lead', 'ideas', 'tags'],
+        required: ['lead', 'context', 'ideas', 'tags'],
         properties: {
             lead: str(L.leadChars),
             context: str(600),
@@ -177,16 +179,36 @@ function notesSchema(first, last) {
         },
     };
 }
-const system = (budget, vocabulary) => `You write a Digest v2 of one source for a private reading library. Reply with JSON only, matching the schema.
-- lead: one dense sentence of at most ${L.leadChars} characters: who (author, organization or product by name) did or argues what, with the concrete specifics that make it this source (names, numbers, mechanism). Not a teaser.
-- context: optional, at most ${L.contextWords} words: the key evidence, numbers or limits the lead could not hold. Lead and context together stay within ${L.gistWords} words and ${L.gistSentences} sentences.
+/**
+ * Style examples are invented sources shaped like reviewed digests (short verdict claims, dense details); no library
+ * text. They show voice only: the model must still draw every claim and number from the source it is given.
+ */
+const styleExamples = `Style examples (invented sources; copy the voice, never the content):
+Source: a database company's post on moving its write path to object storage.
+  lead: Acme moves Ledger's write path onto an append-only log in S3 and cuts p99 commit latency from 40 ms to 9 ms.
+  context: Postgres becomes a read replica rebuilt from the log. Batching makes object storage affordable; single-row workloads still get slower.
+  claim: The log is the database. | detail: Every write appends one immutable segment; Postgres is rebuilt from the log and serves reads only.
+  claim: Batching pays for the bucket. | detail: Commits wait up to 5 ms, so one PUT carries about 300 writes and request cost falls 40-fold.
+  claim: Small writers lose. | detail: Under ten writes per second, latency is higher than before the move.
+Source: an essay arguing that taste is a skill.
+  lead: Mara Lind argues taste is trained by making and comparing many small things, not inherited, and that teams can schedule it.
+  claim: Taste is trained. | detail: Lind's students improved most after drawing fifty quick versions, not after studying masters.
+  claim: Volume beats polish early. | detail: Side-by-side comparison of many rough drafts sharpens judgment faster than finishing one.
+Bad claim: The essay explores how practice over time shapes a person's sense of taste.
+Good claim: Taste is trained.`;
+const system = (budget, vocabulary) => `You write a Digest v2 of one source for a private reading library, in the owner's voice: terse, declarative, specific. Reply with JSON only, matching the schema.
+- lead: one sentence of at most ${L.leadChars} characters stating this source's specific thesis or result: who (author, organization or product by name) shows or argues what, with the number, name or mechanism that makes it this source. Do not restate the title, describe the source ("This article discusses"), or tease.
+- context: 1 or 2 sentences, at most 45 words: the evidence, method, numbers or limits the lead could not hold. Lead and context together stay within ${L.gistWords} words and ${L.gistSentences} sentences.
 - ideas: ${L.minIdeas} to ${L.maxIdeas} (prefer ${L.maxIdeas} when the source has them), in the order the author makes them, covering the whole source including its caveats and limits. Each idea is a claim with detail:
-  - claim: one short sentence of at most ${L.claimWords} words (often 4 to 10) that asserts something; never a topic label.
-  - detail: at most ${L.detailWords} words in at most ${L.detailSentences} sentences: the specific evidence, mechanism, numbers or limits from the source.
+  - claim: a verdict of 4 to 8 words (never more than 12): subject, verb, point, naming this source's own subject ("Batching pays for the bucket", not "Costs drop"). Something a reader could disagree with; never a topic label or a description of the source.
+  - detail: one or two sentences, 15 to 30 words, dense with the source's own names, numbers, mechanism or limits behind the claim. Do not repeat the claim.
   - quotes: 0 to ${L.maxQuotesPerIdea} that support this idea, each a contiguous span copied character for character from one numbered passage, ${minQuoteWords + 2} to 20 words, with that passage number. A quote is a fragment, not a whole long sentence: when a sentence runs past 20 words, copy only its strongest part. No added quotation marks or ellipses. Give attribution (who said it) when it is not the author. Prefer reader highlights.
 - Attach at least ${L.minQuotes} and at most ${L.maxQuotes} quotes in all; ${L.minQuotes + 1} to 3 is typical. All quotes together stay within ${budget} words and never overlap.
 - tags: 0 to ${L.maxTags} ${vocabulary?.length ? `from: ${vocabulary.join(', ')}` : 'lowercase kebab-case topics'}; usually one subject tag.
-Use only what the source says.`;
+Plain words. Name things and use numbers. No hedges or filler: may, might, potentially, various, significantly, key, crucial, notably, highlights, explores, discusses, "the author argues", "the article".
+Use only what the source says.
+
+${styleExamples}`;
 function sourceBlock(title, form, list, highlights) {
     let heading;
     const lines = [];
@@ -275,7 +297,7 @@ export function snapQuote(source, text, within) {
     const folded = locateAll(source, text);
     if (folded.length) {
         const m = pick(folded);
-        return { text: m ? source.slice(m.start, m.end) : text, match: 'folded' };
+        return { text: m ? spoken(source.slice(m.start, m.end)) : text, match: 'folded' };
     }
     const loose = (within && pick(locateLoose(source, text, within))) || pick(locateLoose(source, text));
     if (!loose)
@@ -286,7 +308,7 @@ export function snapQuote(source, text, within) {
         start--;
     while (end < source.length && /[*_`]/.test(source[end]))
         end++;
-    return { text: source.slice(start, end), match: 'snapped' };
+    return { text: spoken(source.slice(start, end)), match: 'snapped' };
 }
 /**
  * A located quote over the word limit keeps its leading words: a prefix of a source span is still verbatim. Trailing
@@ -332,7 +354,11 @@ const pruneable = new Set(['not-verbatim', 'overlap', 'unsupported', 'too-long',
  * budget (second quotes first, longest first), never the last quote. Quoteless ideas stay: v2 allows them.
  */
 function prune(draft, issues, source, options) {
-    const dropped = { quotes: 0, ideas: 0, tags: 0 }, d = draft.digest, bad = new Set(issues
+    const dropped = { quotes: 0, ideas: 0, tags: 0 }, d = draft.digest;
+    // Context is optional in Digest v2: an over-long gist loses its context rather than the draft.
+    if (d.gist.context !== undefined && issues.some((i) => i.path === 'gist' || i.path === 'gist.context'))
+        delete d.gist.context;
+    const bad = new Set(issues
         .filter((i) => /^ideas\.\d+\.quotes\.\d+(?:\.attribution)?$/.test(i.path) && pruneable.has(i.code))
         .map((i) => i.path.replace(/\.attribution$/, '')));
     d.ideas.forEach((idea, i) => {

package/dist/src/errors.d.ts

@@ -16,6 +16,8 @@ declare const parents: {
     readonly 'not-digest': "unsupported";
     readonly malformed: "invalid-input";
     readonly 'no-capture': "invalid-input";
+    readonly 'parent-missing': "invalid-input";
+    readonly 'target-exists': "invalid-input";
 };
 export type DetailCode = keyof typeof parents;
 export type SpongeCode = ErrorCode | DetailCode;

package/dist/src/errors.js

@@ -30,6 +30,8 @@ const parents = {
     'not-digest': 'unsupported',
     malformed: 'invalid-input',
     'no-capture': 'invalid-input',
+    'parent-missing': 'invalid-input',
+    'target-exists': 'invalid-input',
 };
 export const indexCodes = [
     'invalid-index',

package/dist/src/importers/jungle-store.d.ts

@@ -12,8 +12,12 @@ export type DigestAction = 'new' | 'unchanged' | 'not-convertible' | 'not-digest
 export type VisibilityAction = 'set-public' | 'set-private' | 'restore-default' | 'unchanged' | 'kept-user-edit' | 'guarded' | 'default-policy';
 /** Local captures only (no web URI of their own): `uri` records the note's `source_url`. Later notes on one capture leave it to the first (`other-note`). */
 export type UriAction = 'new' | 'unchanged' | 'web-capture' | 'other-note' | 'no-source-url' | 'capability';
-/** The first note's title is the item's default title (`noteTitle`); `kept-user-edit` records it while the user's override stays shown. */
-export type TitleAction = 'set' | 'unchanged' | 'other-note' | 'kept-user-edit';
+/**
+ * Local captures only, like `uri`: the first note's title becomes the default title (`noteTitle`) of a capture whose own
+ * title is a file name; `kept-user-edit` records it while the user's override stays shown. A web capture keeps its
+ * captured title (`web-capture`).
+ */
+export type TitleAction = 'set' | 'unchanged' | 'web-capture' | 'other-note' | 'kept-user-edit';
 /** `firstNote` is false for a later note on a capture an earlier note in the same run already used; `firstNoteUri` is the URI that note records (a dry run has not written it). */
 export interface JungleNoteInput {
     itemId: string;

package/dist/src/importers/jungle-store.js

@@ -45,9 +45,11 @@ export function uriAction(local, firstNote, sourceUrl, recorded) {
     const { uri, refused } = noteUri(sourceUrl);
     return uri ? { action: uri === recorded ? 'unchanged' : 'new', uri } : { action: refused };
 }
-function titleAction(db, input) {
+function titleAction(db, input, local) {
     if (input.firstNote === false)
         return 'other-note';
+    if (!local)
+        return 'web-capture';
     const title = input.editorial.title.trim(), item = db.prepare('SELECT title_note,title_override FROM items WHERE id=?').get(input.itemId);
     if (item?.title_override !== null && item?.title_override !== undefined)
         return 'kept-user-edit';
@@ -138,7 +140,7 @@ export function planJungleNote(db, input) {
         ...(digestId ? { digestId } : {}),
         digest: action,
         uri: uri.action,
-        title: titleAction(db, input),
+        title: titleAction(db, input, local),
         visibility,
     };
 }
@@ -162,9 +164,9 @@ export function applyJungleNote(db, input) {
     // A local capture takes the note's web address and title before visibility is decided, so the published state applies to it.
     if (plan.uri === 'new')
         setMetadataUri(db, input.itemId, uriAction(true, true, input.editorial.sourceUrl).uri);
-    // The note's title is the item's default; a refresh changes only the captured title, and the user's override wins over both.
+    // A local capture's default title is the note's; a refresh changes only the captured title, and the user's override wins over both.
     const title = input.editorial.title.trim();
-    if (input.firstNote !== false &&
+    if ((plan.title === 'set' || plan.title === 'kept-user-edit') &&
         title &&
         Buffer.byteLength(title) <= 4096 &&
         title !== db.prepare('SELECT title_note FROM items WHERE id=?').get(input.itemId)?.title_note)

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

@@ -6,8 +6,8 @@ import type { BundleVerifier } from './inspect.js';
  * `sponge import jungle DIR`: every Jungle Reading note (`kb/notes/reading/<slug>.md`) onto the item holding its capture.
  * The capture goes through the verified bundle import (always as a private association); the note becomes an accepted
  * editorial derivation, plus an accepted Digest v2 when it converts without altering owner text (non-verbatim, short and
- * overflowing quotes are dropped and reported); the note's title becomes the item's default title (a user override still wins), and a
- * local capture (no web URI of its own) takes the note's `source_url`;
+ * overflowing quotes are dropped and reported); a local capture (no web URI of its own) takes the note's `source_url` and its
+ * title as the default title (a user override still wins), while a web capture keeps its captured title;
  * `reading.status` becomes the item's visibility. Jungle is only read. A dry run reads the notes, captures and library and writes nothing.
  */
 export interface JungleImportOptions {

package/dist/src/importers/jungle.js

@@ -139,7 +139,7 @@ export async function importJungle(store, jungle, options = {}) {
                 throw entry;
             }
             // Two notes on one capture share its item, in a dry run too.
-            // The first note on a capture decides its default title and a local capture's URI; later notes see the URI it records.
+            // The first note on a capture decides a local capture's URI and default title; later notes see the URI it records.
             const firstNote = !seen.has(link), firstNoteUri = seen.get(link);
             entry.item = prior || !firstNote ? 'existing' : 'new';
             if (firstNote)
@@ -174,7 +174,13 @@ export async function importJungle(store, jungle, options = {}) {
                         ...(issues.length ? { digestIssues: issues } : {}),
                         ...(quotes ? { quotes } : {}),
                         uri: uri.action,
-                        title: !firstNote ? 'other-note' : noteTitle && Buffer.byteLength(noteTitle) <= 4096 ? 'set' : 'unchanged',
+                        title: !firstNote
+                            ? 'other-note'
+                            : !local
+                                ? 'web-capture'
+                                : noteTitle && Buffer.byteLength(noteTitle) <= 4096
+                                    ? 'set'
+                                    : 'unchanged',
                         visibility: visibilityAction({ access, default: defaultVisibility(access, 'private'), override: null }, editorial.status, false).action,
                     });
                 }

package/dist/src/portability/files.js

@@ -112,8 +112,18 @@ export function copyVerified(source, target, record) {
 export function newDirectory(path) {
     if (resolve(path) !== path)
         throw new SpongeError('invalid-input');
-    safeDirectory(dirname(path));
-    mkdirSync(path, { mode: 0o700 });
+    try {
+        safeDirectory(dirname(path));
+        mkdirSync(path, { mode: 0o700 });
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'ENOENT')
+            throw new SpongeError('parent-missing', { cause: error });
+        if (code === 'EEXIST')
+            throw new SpongeError('target-exists', { cause: error });
+        throw error;
+    }
     const stat = lstatSync(path);
     return { root: path, device: stat.dev, inode: stat.ino };
 }

package/native/runtime-manifest.json

@@ -27,14 +27,14 @@
     }
   ],
   "build": {
-    "asrSourceSha256": "2862d5869808e2f048767f075ddb234aa7535bc7242550365efcfb718cc7f7b8",
+    "asrSourceSha256": "8bd77ebffabae786902304eacb983fc950f70c981fb1538696517d85052c9407",
     "clangVersion": "Apple clang version 21.0.0 (clang-2100.1.1.101)",
-    "embeddingSourceSha256": "a584f43c8af9743612984804f3fa2df0d204f13481c3a2d6d06b521e7661bc2e",
+    "embeddingSourceSha256": "2b0cd2b9c52c9dee578a3be50a443d528d5204d47f3f9ba750f6a1f37a191e78",
     "swiftVersion": "Apple Swift version 6.3.3 (swiftlang-6.3.3.1.3 clang-2100.1.1.101)"
   },
   "minimumMacOS": "26.0",
-  "packageVersion": "0.3.0",
+  "packageVersion": "0.3.2",
   "platform": "darwin",
   "schemaVersion": 1,
-  "sourceCommit": "8b1dc263364669190b4bec2ed5d7141a838e0841"
+  "sourceCommit": "e9eb0613365859c5809a05e8ad909504ac6e8d66"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hraness/sponge",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "A local library for captured articles and verified offline assets.",
   "repository": {
     "type": "git",