@fractalsynapse/dsh-chapters 0.0.0-stage → 0.2.21

package/lib/enrich.js

@@ -0,0 +1,267 @@
+import { PLUGIN_VERSION } from "./version.js";
+const TITLE_CAP = 160;
+// #188: 600 → 2400. The summary is no longer a retrieval blurb — it is the chapter's guidance
+// value for the suggestion director, which reads title+summary+plots INSTEAD of the body. The cap
+// stays (frontmatter hygiene) and its truncation stays LOUD (' …[truncated]'), but 2-3 sentences
+// cannot carry a chapter's decisions, findings, and open threads.
+const SUMMARY_CAP = 2400;
+const TOPIC_MAX = 10;
+const TOPIC_LEN = 48;
+// §7.5 mining bounds: few, short, and traceable. One chapter is not allowed to
+// mint a dozen standing orders for a session tree.
+const RULE_MAX = 3;
+const RULE_TEXT_MIN = 10;
+const RULE_TEXT_CAP = 320;
+const RULE_QUOTE_CAP = 200;
+const PART_CAP = 1200;
+const TOTAL_IN_CAP = 8000;
+const BODY_HEAD_TOKENS = 200;
+// The default ceiling for ONE auxiliary completion — the annotation pass (which now
+// also carries mined rules) and the conflicts report.
+//
+// 900 was the pre-mining number. Measured 2026-10-21, mining real chapters at
+// `qwen3.8-flash`: the provider reported completion usage of 969–3237 tokens against a
+// 700-token request, because REASONING tokens are counted in completion usage. A ceiling
+// with room only for the visible JSON truncates mid-object, and a truncated answer
+// parses as "no rules" — a silent loss that reads like a model with nothing to say. So
+// the budget covers the thinking, not just the answer: 4000, configurable as
+// `enrichmentMaxTokens` so no call site carries a literal.
+//
+// Unchanged: the input caps and the one-retry ladder. Cost is bounded by chapters per
+// drain, not by this number.
+export const ENRICH_MAX_TOKENS_DEFAULT = 4000;
+const INSTRUCTION = 'You annotate one archived chapter of a coding-agent conversation for retrieval. '
+    + 'Reply with ONLY one JSON object, no prose, no code fences, shaped exactly: '
+    + '{"title": "<one descriptive sentence, <=120 chars>", '
+    + '"summary": "<a DETAILED summary — one to three paragraphs capturing the decisions made, findings established, state changed, and threads left open, written for a reader who must direct future work from this chapter alone>", '
+    + '"topics": ["<lowercase short labels, 3 to 10>"], "rules": [{"text": "<one imperative standing instruction>", "category": "<short slug>", "quote": "<the user\u0027s own words verbatim>"}]}. '
+    + 'Topics are semantic labels (concepts, not file paths). Base everything strictly on the material below.\n'
+    + 'rules is OPTIONAL and for durable steering only: a convention, invariant or pitfall the USER stated '
+    + 'that should keep applying to future work in this project (e.g. "run the tape replay before tagging"). '
+    + 'Do NOT report one-off task details, preferences about this chapter only, or anything you inferred. '
+    + 'Every rule MUST quote the user\u0027s own words verbatim in "quote"; if no rule is backed by a literal user '
+    + 'sentence, omit "rules" or send []. At most 3. They are reviewed and usually invisible to the model that wrote them.';
+/** cap a piece of the slice; truncation is EXPLICIT, never silent. */
+function cap(text, n) {
+    const t = defuseInjections(text).trim();
+    if (t.length <= n)
+        return t;
+    return t.slice(0, n) + ' …[truncated]';
+}
+/**
+ * Host-injected spans enter the chapter as ⟦omitted:host-injected <label>,
+ * N chars…⟧ markers whose COUNT and length are machine state (a dev box
+ * carries a skills catalog message; a runner does not). The ladder annotates
+ * CONVERSATION — record §"host-injected context is not conversation": in the
+ * enricher's input every marker collapses to a fixed token. Without this the
+ * 8000-char input cap lands at different offsets per machine (measured on
+ * hosted CI 2026-09-25: recorded prompts cut ' …[truncated]' at offset 1771
+ * while the runner's shorter material sent the full tail — the exchange
+ * missed, the ladder starved).
+ */
+function defuseInjections(text) {
+    return text
+        .replace(/⟦omitted:host-injected[^⟧]*⟧/g, '⟦injected-context⟧')
+        .replace(/(?:⟦injected-context⟧[ \t\n]*){2,}/g, '⟦injected-context⟧ ');
+}
+/**
+ * Assemble the model input: capped slice, stable order, hard total budget.
+ * Deterministic — same chapter material always produces the same prompt,
+ * which is what makes the queue's chapter+model idempotency key sound.
+ *
+ * @param codegraphContext Optional structural context from CodeGraph (symbols,
+ *   call paths). When present, appended as a bounded block so the enricher can
+ *   produce more precise topics. Absent → identical output to before this feature.
+ */
+export function buildEnrichInput(meta, slice, bodyHead, codegraphContext) {
+    const parts = [INSTRUCTION, '', `CURRENT TITLE: ${cap(meta.title, TITLE_CAP)}`];
+    if (slice.firstAssistant !== undefined)
+        parts.push(`FIRST ASSISTANT: ${cap(slice.firstAssistant, PART_CAP)}`);
+    if (slice.lastAssistant !== undefined)
+        parts.push(`LAST ASSISTANT: ${cap(slice.lastAssistant, PART_CAP)}`);
+    for (const [i, r] of slice.requests.slice(-3).entries())
+        parts.push(`REQUEST ${i + 1}: ${cap(r, PART_CAP)}`);
+    parts.push('', 'CHAPTER BODY (opening):', cap(bodyHead, BODY_HEAD_TOKENS * 4));
+    // CodeGraph structural context: symbols and their immediate relationships,
+    // verified against the project index. Helps the enricher produce structurally
+    // precise topics (e.g. "auth-middleware" instead of just "auth"). Capped at
+    // 800 chars to stay within TOTAL_IN_CAP; absent → zero bytes added.
+    if (codegraphContext !== undefined && codegraphContext.trim().length > 0) {
+        parts.push('', 'CODE STRUCTURE (from CodeGraph index):', cap(codegraphContext, 800));
+    }
+    let text = parts.join('\n');
+    if (text.length > TOTAL_IN_CAP)
+        text = text.slice(0, TOTAL_IN_CAP) + '\n…[input truncated]';
+    return text;
+}
+/** label sanitizer: lowercase, bracket/quote-free, bounded; null if unusable. */
+function cleanTopic(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    const t = raw.trim().toLowerCase().replace(/["'`[\]{}()<>|\\]/g, '').replace(/\s+/g, ' ').trim();
+    if (t.length === 0 || t.length > TOPIC_LEN)
+        return null;
+    return t;
+}
+/**
+ * The validator. Tolerates code fences and surrounding prose (extracts the
+ * first JSON object), then requires every field well-shaped. Returns null —
+ * never throws — on ANY failure; the retry-then-keep-deterministic ladder is
+ * the caller's loop by design.
+ */
+export function parseEnrichResult(text) {
+    const m = /\{[\s\S]*\}/.exec(text);
+    if (m === null)
+        return null;
+    let obj;
+    try {
+        obj = JSON.parse(m[0]);
+    }
+    catch {
+        return null;
+    }
+    if (typeof obj !== 'object' || obj === null)
+        return null;
+    const o = obj;
+    if (typeof o.title !== 'string' || typeof o.summary !== 'string' || !Array.isArray(o.topics))
+        return null;
+    const title = o.title.trim();
+    const summary = o.summary.trim();
+    if (title.length === 0 || summary.length === 0)
+        return null;
+    const topics = [];
+    for (const t of o.topics) {
+        const c = cleanTopic(t);
+        if (c !== null && !topics.includes(c))
+            topics.push(c);
+        if (topics.length >= TOPIC_MAX)
+            break;
+    }
+    if (topics.length === 0)
+        return null;
+    // rules are additive: absent, malformed or empty ⇒ no mined rules, and the
+    // annotation itself still commits. A bad `rules` array must never cost a
+    // chapter its title/summary/topics (the ladder's never-blank guarantee).
+    const rules = [];
+    if (Array.isArray(o.rules)) {
+        for (const raw of o.rules) {
+            if (typeof raw !== 'object' || raw === null)
+                continue;
+            const r = raw;
+            if (typeof r.text !== 'string' || typeof r.quote !== 'string')
+                continue;
+            const text = r.text.trim();
+            const quote = r.quote.trim().replace(/^["'`]+|["'`]+$/g, '');
+            if (text.length < RULE_TEXT_MIN || text.length > RULE_TEXT_CAP * 3 || quote.length === 0)
+                continue;
+            const category = typeof r.category === 'string'
+                ? r.category.trim().toLowerCase().replace(/[^a-z0-9-]/g, '').slice(0, 24)
+                : '';
+            rules.push({ text: text.slice(0, RULE_TEXT_CAP), category, quote: quote.slice(0, RULE_QUOTE_CAP) });
+            if (rules.length >= RULE_MAX)
+                break;
+        }
+    }
+    return {
+        title: title.slice(0, TITLE_CAP),
+        // #188: the summary clamp stays LOUD — the input-side cap() has always announced itself
+        // ("truncation is EXPLICIT, never silent"); the output side was a bare slice, which is the same
+        // silence wearing a different hat. The marker fits INSIDE the cap, so the bound is real.
+        summary: summary.length > SUMMARY_CAP
+            ? `${summary.slice(0, SUMMARY_CAP - 13)} …[truncated]`
+            : summary,
+        topics,
+        rules,
+    };
+}
+const MINE_INSTRUCTION = 'You read one archived chapter of a coding-agent conversation and write the STANDING ORDERS that '
+    + 'would keep this project focused. Reply with ONLY a JSON object: '
+    + '{"rules": [{"text": "<one imperative, generalizable instruction>", "category": "<short slug>", "basis": "<stated|inferred>", "quote": "<a short verbatim phrase from the material, or empty>"}]}. '
+    + 'Infer what the material implies even when nobody spelled it out — a convention, an invariant, a trap '
+    + 'that bit this work and will bite again — but each rule must GENERALIZE beyond this chapter: a '
+    + 'one-off task detail is not a rule. `basis` is stated when a human sentence in the material backs it, '
+    + 'inferred when you judged it. At most 3; send {"rules":[]} when nothing durable applies. Do not '
+    + 'restate the chapter\u2019s contents.';
+/** The rules-only prompt for a dedicated mining model (§7.5, `rulesModel`). */
+export function buildMineInput(slice, bodyHead) {
+    const parts = [MINE_INSTRUCTION, ''];
+    for (const [i, r] of slice.requests.slice(-4).entries())
+        parts.push(`REQUEST ${i + 1}: ${cap(r, PART_CAP)}`);
+    if (slice.lastAssistant !== undefined)
+        parts.push(`LAST ASSISTANT: ${cap(slice.lastAssistant, PART_CAP)}`);
+    parts.push('', 'CHAPTER BODY:', cap(bodyHead, 6000));
+    let text = parts.join('\n');
+    if (text.length > TOTAL_IN_CAP)
+        text = text.slice(0, TOTAL_IN_CAP) + '\n…[input truncated]';
+    return text;
+}
+/**
+ * Validate a mining-only answer. Bounds are the same as the annotation path's
+ * `rules` field so the two routes cannot produce differently-shaped candidates;
+ * an unknown `basis` falls back to the conservative `inferred`.
+ */
+export function parseMinedRules(text) {
+    const m = /\{[\s\S]*\}/.exec(text);
+    if (m === null)
+        return [];
+    let obj;
+    try {
+        obj = JSON.parse(m[0]);
+    }
+    catch {
+        return [];
+    }
+    const o = obj;
+    if (typeof o !== 'object' || o === null || !Array.isArray(o.rules))
+        return [];
+    const out = [];
+    for (const raw of o.rules) {
+        if (typeof raw !== 'object' || raw === null)
+            continue;
+        const r = raw;
+        if (typeof r.text !== 'string')
+            continue;
+        const textOk = r.text.trim();
+        if (textOk.length < RULE_TEXT_MIN || textOk.length > RULE_TEXT_CAP * 3)
+            continue;
+        const quote = typeof r.quote === 'string' ? r.quote.trim().slice(0, RULE_QUOTE_CAP) : '';
+        const category = typeof r.category === 'string' ? r.category.trim().toLowerCase().replace(/[^a-z0-9-]/g, '').slice(0, 24) : '';
+        out.push({ text: textOk.slice(0, RULE_TEXT_CAP), category, quote, basis: r.basis === 'stated' ? 'stated' : 'inferred' });
+        if (out.length >= RULE_MAX)
+            break;
+    }
+    return out;
+}
+/**
+ * Merge an enrichment result into the chapter's model-owned fields.
+ * - result === null (ladder bottomed out) → PURE no-op, values + provenance
+ *   untouched (deterministic P1 values survive forever).
+ * - same values AND same newest model author → no-op (idempotent re-run).
+ * - otherwise: fields update; each provenance chain grows newest-first, one
+ *   entry per model (re-annotation by a newer model never erases history).
+ * The verbatim BODY is not in this module's universe — callers may only
+ * rewrite frontmatter fields (record §6.2), body hash-verified elsewhere.
+ */
+export function applyEnrich(current, result, model, at) {
+    if (result === null)
+        return { values: current, changed: false };
+    const sameValues = current.title === result.title
+        && current.summary === result.summary
+        && current.topics.join('\u0000') === result.topics.join('\u0000');
+    const authoredBySame = ['title', 'summary', 'topics'].every((f) => {
+        const top = current.generated?.[f]?.[0];
+        return top?.by === 'model' && top.model === model;
+    });
+    if (sameValues && authoredBySame)
+        return { values: current, changed: false };
+    const gen = { title: [], summary: [], topics: [] };
+    // pluginVersion rides with the model name (#61): a row must say WHICH build annotated it, not just
+    // when, or attribution is mtime-archaeology for the next person.
+    const mark = { by: 'model', model, at, pluginVersion: PLUGIN_VERSION };
+    for (const f of ['title', 'summary', 'topics']) {
+        const chain = current.generated?.[f] ?? [];
+        gen[f] = [mark, ...chain.filter((c) => !(c.by === 'model' && c.model === model))];
+    }
+    return { values: { ...current, title: result.title, summary: result.summary, topics: result.topics, generated: gen }, changed: true };
+}
+//# sourceMappingURL=enrich.js.map

package/lib/enrich.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"enrich.js","sourceRoot":"","sources":["../src/enrich.ts"],"names":[],"mappings":"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"}

package/lib/gitops.d.ts

@@ -0,0 +1,107 @@
+export interface RemoteSpec {
+    url: string;
+    /** Scoped per-harness token (record §2.1); absent for file:// remotes. */
+    token?: string;
+}
+export interface GitOpResult {
+    ok: boolean;
+    detail: string;
+    changed?: boolean;
+    /** Machine-readable failure class (r35 lesson: the caller must NOT regex
+     * prose — the network failure's wording once contained 'diverge'). */
+    code?: 'diverged' | 'network' | 'rejected' | 'origin-mismatch' | 'auth' | 'not_found';
+}
+export interface CommitAuthor {
+    name: string;
+    email: string;
+}
+/**
+ * Classify an isomorphic-git transport error. A rejected credential (HTTP
+ * 401/403, or the auth-phrase fallback) MUST come back as `auth`, not the
+ * generic `network` the catch blocks used to assume — otherwise /chapters-status
+ * tells the user "remote unreachable" when the truth is "your token is bad,
+ * re-link it". 404/401-on-repo maps to not_found (private-but-missing vs
+ * forbidden are genuinely ambiguous over smart HTTP; auth wins when a token
+ * was actually sent).
+ */
+export declare function classifyGitTransportError(error: unknown): {
+    code: 'auth' | 'not_found' | 'network';
+    detail: string;
+};
+/**
+ * Ensure a clone exists at `dir` for `remote`. A non-repo dir is cloned
+ * (single branch, main); an existing repo is left alone — pull/ff is the
+ * caller's step. A non-empty non-repo dir is dead transport: moved aside
+ * (`<dir>.stale-<ts>`, contents preserved) and cloned fresh. The r39-era e2e
+ * failure class was exactly this residue making every later clone refuse;
+ * renaming aside is strictly weaker than what the diverged-rebuild path
+ * already does (removeMirror rm -rf) — the mirror is transport, the store
+ * is truth (§3.1).
+ */
+export declare function ensureClone(dir: string, remote: RemoteSpec, opts?: {
+    defaultBranch?: string;
+}): Promise<GitOpResult>;
+/**
+ * Commit every workdir file whose content differs from HEAD. Does not trust
+ * `statusMatrix` — on isomorphic-git 1.42 it reports stale index state right
+ * after a commit (verified: a clean repo still reports [1,1,1]); the
+ * workdir-vs-HEAD content comparison is the honest diff. Untracked dotfiles
+ * and .git are out of scope (the mirror holds knowledge files only).
+ */
+export declare function stageAllAndCommit(dir: string, message: string, author: CommitAuthor): Promise<GitOpResult>;
+/** Fetch the remote and fast-forward the local branch. ff-only, always. */
+export declare function pullFastForward(dir: string, remote: RemoteSpec, opts?: {
+    defaultBranch?: string;
+}): Promise<GitOpResult>;
+export declare const isLocalUpstreamUrl: (url: string) => boolean;
+/** file:///a/b -> /a/b ; ~ -> homedir ; relative resolved against `cwd`. */
+export declare function resolveLocalUpstreamPath(url: string, cwd: string): string;
+/** local-upstream ops take a url that is a resolved absolute path (sync.ts
+ * resolves before calling; the driver dispatches on the shape). */
+export declare function ensureCloneLocal(mirrorDir: string, upstreamPath: string, opts?: {
+    defaultBranch?: string;
+}): Promise<GitOpResult>;
+export declare function pullLocal(mirrorDir: string, upstreamPath: string, opts?: {
+    defaultBranch?: string;
+}): Promise<GitOpResult>;
+export declare function pushLocal(mirrorDir: string, upstreamPath: string, opts?: {
+    defaultBranch?: string;
+}): Promise<GitOpResult>;
+/** Mirror provenance: which upstream this mirror was last bound to (http OR
+ * local) — an origin change is detected on EVERY ensureClone, local or not. */
+export declare const originSentinel: (mirrorDir: string) => string;
+export declare function recordOrigin(mirrorDir: string, url: string): Promise<void>;
+export declare function readOrigin(mirrorDir: string): string | null;
+export interface GitDriver {
+    ensureClone(dir: string, remote: RemoteSpec, opts?: {
+        defaultBranch?: string;
+    }): Promise<GitOpResult>;
+    initLocal(dir: string, remote?: RemoteSpec, opts?: {
+        defaultBranch?: string;
+    }): Promise<GitOpResult>;
+    removeMirror(dir: string): Promise<GitOpResult>;
+    stageAllAndCommit(dir: string, message: string, author: CommitAuthor): Promise<GitOpResult>;
+    pullFastForward(dir: string, remote: RemoteSpec, opts?: {
+        defaultBranch?: string;
+    }): Promise<GitOpResult>;
+    push(dir: string, remote: RemoteSpec, opts?: {
+        defaultBranch?: string;
+    }): Promise<GitOpResult>;
+}
+/**
+ * Initialize a local-only mirror (offline mode, record §5.3): the remote is
+ * unreachable, but the mirror is transport over truth we own — publish,
+ * index, commit, and search keep working; push waits for the remote.
+ */
+export declare function initLocal(dir: string, remote?: RemoteSpec, opts?: {
+    defaultBranch?: string;
+}): Promise<GitOpResult>;
+/** Delete the mirror working tree + git dir entirely. SAFE ONLY because the
+ * mirror is transport (§3.1): the workspace store holds the truth, and the
+ * rebuild republishes from it (the diverged-offline recovery, §5.3). */
+export declare function removeMirror(dir: string): Promise<GitOpResult>;
+/** Push the local branch; a rejected (non-ff) push comes back for the caller to ff-and-retry. */
+export declare function push(dir: string, remote: RemoteSpec, opts?: {
+    defaultBranch?: string;
+}): Promise<GitOpResult>;
+export declare const isomorphicDriver: GitDriver;