@treeseed/dsh-chapters 0.1.0

package/lib/enrich.d.ts

@@ -0,0 +1,73 @@
+/**
+ * P2 S1 — the enrichment pass, pure core (record §6.1).
+ *
+ * One structured call per ARCHIVED chapter, input = the cheap slice the user
+ * specified (user requests + first/last assistant message, capped, plus the
+ * first ~200 tokens of the chapter body), output = validated JSON:
+ *   {"title": "...", "summary": "...", "topics": ["...", ...]}
+ *
+ * No fs, no harness, no model here — the queue (S2) wires the fetcher. This
+ * module guarantees the properties the record stakes:
+ *   - VALIDATION BEFORE COMMIT: parseEnrichResult accepts nothing malformed;
+ *   - NEVER BLOCKS OR BLANKS: applyEnrich(null) is a pure no-op — the
+ *     deterministic title/summary/topics from P1 survive any model failure.
+ */
+export interface EnrichSlice {
+    requests: string[];
+    firstAssistant?: string;
+    lastAssistant?: string;
+}
+export interface EnrichResult {
+    title: string;
+    summary: string;
+    topics: string[];
+}
+export type GeneratedMark = {
+    by: 'deterministic';
+} | {
+    by: 'model';
+    model: string;
+    at: string;
+};
+export interface GeneratedProvenance {
+    title: GeneratedMark[];
+    summary: GeneratedMark[];
+    topics: GeneratedMark[];
+}
+export type EnrichableFields = 'title' | 'summary' | 'topics';
+export declare const ENRICH_MAX_TOKENS = 350;
+/**
+ * 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.
+ */
+export declare function buildEnrichInput(meta: {
+    title: string;
+}, slice: EnrichSlice, bodyHead: string): string;
+/**
+ * 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 declare function parseEnrichResult(text: string): EnrichResult | null;
+export interface CurrentValues {
+    title: string;
+    summary: string;
+    topics: string[];
+    generated?: Partial<GeneratedProvenance>;
+}
+/**
+ * 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 declare function applyEnrich(current: CurrentValues, result: EnrichResult | null, model: string, at: string): {
+    values: CurrentValues;
+    changed: boolean;
+};

package/lib/enrich.js

@@ -0,0 +1,150 @@
+/**
+ * P2 S1 — the enrichment pass, pure core (record §6.1).
+ *
+ * One structured call per ARCHIVED chapter, input = the cheap slice the user
+ * specified (user requests + first/last assistant message, capped, plus the
+ * first ~200 tokens of the chapter body), output = validated JSON:
+ *   {"title": "...", "summary": "...", "topics": ["...", ...]}
+ *
+ * No fs, no harness, no model here — the queue (S2) wires the fetcher. This
+ * module guarantees the properties the record stakes:
+ *   - VALIDATION BEFORE COMMIT: parseEnrichResult accepts nothing malformed;
+ *   - NEVER BLOCKS OR BLANKS: applyEnrich(null) is a pure no-op — the
+ *     deterministic title/summary/topics from P1 survive any model failure.
+ */
+const TITLE_CAP = 160;
+const SUMMARY_CAP = 600;
+const TOPIC_MAX = 10;
+const TOPIC_LEN = 48;
+const PART_CAP = 1200;
+const TOTAL_IN_CAP = 8000;
+const BODY_HEAD_TOKENS = 200;
+export const ENRICH_MAX_TOKENS = 350;
+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": "<2-3 informative sentences>", "topics": ["<lowercase short labels, 3 to 10>"]}. '
+    + 'Topics are semantic labels (concepts, not file paths). Base everything strictly on the material below.';
+/** 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.
+ */
+export function buildEnrichInput(meta, slice, bodyHead) {
+    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));
+    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;
+    return {
+        title: title.slice(0, TITLE_CAP),
+        summary: summary.slice(0, SUMMARY_CAP),
+        topics,
+    };
+}
+/**
+ * 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: [] };
+    const mark = { by: 'model', model, at };
+    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;