@treeseed/dsh-chapters 0.1.0

package/lib/indexing.js

@@ -0,0 +1,212 @@
+/**
+ * Layer 2 of the two-layer index (knowledge-repo.md §10.2): the compressed,
+ * searchable, sharded index derived from chapter frontmatter + Layer-1
+ * curation facts. PURE + DETERMINISTIC: same inputs → same shards, and an
+ * empty manifest rebuilds the whole index identically (the recovery path).
+ *
+ * Shards are one file per canonical topic (alphabetical — bounded files,
+ * writes from different chapters usually touch different shards). Layer 1
+ * (`edits/<harness>/curation.jsonl`) is where humans and the plugin inject
+ * aliases, weights, pins, and group facts; this module applies them.
+ */
+/**
+ * S5 (record §4.3 boundary): fragment coherence at the INDEX level only.
+ * Legacy compaction fragments (turn-blind slices titled 'Earlier history'/
+ * 'Conversation span') that sit adjacent by chapter number within one
+ * session tree cohere into a single search entry citing every member file.
+ * Nothing on disk merges, no chapter is rewritten, the split rule is
+ * untouched — a pure function of what is already stored, so it is idempotent
+ * and vanishes if any member is reverted.
+ */
+const FRAGMENT_TITLE = /^(?:Earlier history|Conversation span)/;
+function chapterNumber(path) {
+    const base = path.split('/').pop() ?? '';
+    const n = /^(\d+)-/.exec(base);
+    return n !== null ? Number(n[1]) : null;
+}
+export function stitchFragments(entries) {
+    // group by session directory, keep input order
+    const byDir = new Map();
+    const loose = [];
+    for (const e of entries) {
+        const dir = e.path.split('/').slice(0, -1).join('/');
+        const isFrag = FRAGMENT_TITLE.test(e.title);
+        if (!isFrag || chapterNumber(e.path) === null) {
+            loose.push(e);
+            continue;
+        }
+        const list = byDir.get(dir);
+        if (list === undefined)
+            byDir.set(dir, [e]);
+        else
+            list.push(e);
+    }
+    const out = [...loose];
+    for (const [dir, frags] of byDir) {
+        const sorted = [...frags].sort((a, b) => (chapterNumber(a.path) ?? 0) - (chapterNumber(b.path) ?? 0));
+        let i = 0;
+        while (i < sorted.length) {
+            let j = i;
+            while (j + 1 < sorted.length &&
+                (chapterNumber(sorted[j + 1].path) ?? -1) === (chapterNumber(sorted[j].path) ?? -1) + 1)
+                j++;
+            const run = sorted.slice(i, j + 1);
+            if (run.length > 1) {
+                const head = run[0];
+                out.push({
+                    ...head,
+                    title: `${head.title} — ${run.length} consecutive parts (stitched)`,
+                    topics: [...new Set(run.flatMap((r) => r.topics))],
+                    paths: run.map((r) => r.path),
+                });
+            }
+            else if (run.length === 1)
+                out.push(run[0]);
+            i = j + 1;
+        }
+        void dir;
+    }
+    // stable, deterministic: original entry order by path
+    out.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+    return out;
+}
+const hashOf = (text) => {
+    // FNV-1a 32-bit — deterministic, no crypto import needed in the pure core;
+    // collision-resistance is not a security property here, only change-detection.
+    let h = 0x811c9dc5;
+    for (let i = 0; i < text.length; i += 1) {
+        h ^= text.charCodeAt(i);
+        h = Math.imul(h, 0x01000193) >>> 0;
+    }
+    return h.toString(16).padStart(8, '0');
+};
+export const hashEntry = (e) => hashOf(`${e.path}|${e.title}|${[...e.topics].sort().join(',')}|${e.kind}|${e.mtime ?? 0}`);
+/** Minimal frontmatter reader for the `key: value` lines render.ts writes. */
+export function parseFrontmatter(text) {
+    const out = {};
+    const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+    if (m === null)
+        return out;
+    const body = m[1] ?? '';
+    for (const line of body.split(/\r?\n/)) {
+        const kv = /^([A-Za-z][A-Za-z0-9]*):\s*(.*)$/.exec(line);
+        if (kv === null)
+            continue;
+        const key = kv[1];
+        let value = kv[2].trim();
+        if (value.startsWith('[') && value.endsWith(']')) {
+            out[key] = value.slice(1, -1).split(',').map((v) => v.trim().replace(/^"|"$/g, '')).filter((v) => v.length > 0);
+        }
+        else {
+            out[key] = value.replace(/^"|"$/g, '');
+        }
+    }
+    return out;
+}
+/** A chapter file's text → IndexEntry (topics from frontmatter, kind from `kind:`). */
+export function entryFromChapter(path, text, mtime) {
+    const fm = parseFrontmatter(text);
+    const topics = fm.topics;
+    return {
+        path,
+        title: typeof fm.title === 'string' ? fm.title : path,
+        topics: Array.isArray(topics) ? topics : [],
+        kind: fm.kind === 'rule' ? 'rule' : 'chapter',
+        ...(typeof fm.category === 'string' && fm.category !== '' ? { category: fm.category } : {}),
+        ...(mtime !== undefined ? { mtime } : {}),
+    };
+}
+/** Layer-1 parse: one JSON fact per line; malformed lines are skipped (logged by the caller). */
+export function parseCuration(text) {
+    const facts = [];
+    for (const line of text.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (trimmed === '')
+            continue;
+        try {
+            const fact = JSON.parse(trimmed);
+            if (typeof fact?.type === 'string')
+                facts.push(fact);
+        }
+        catch {
+            /* malformed line: skipped, not fatal (append-only appenders may race) */
+        }
+    }
+    return facts;
+}
+/**
+ * Build the sharded index. Aliases canonicalize topics (from→to, transitive),
+ * pinned topics sort first inside their position, weights scale the sort
+ * within a topic, and the manifest tracks per-entry hashes for the
+ * incremental fast path (an empty manifest = full rebuild = identical output).
+ */
+export function buildIndexShards(entries, curation, manifest = {}) {
+    const alias = new Map();
+    for (const f of curation) {
+        if (f.type === 'topic-alias')
+            alias.set(f.from, f.to);
+    }
+    const canonical = (topic) => {
+        let t = topic;
+        let guard = 0;
+        while (alias.has(t) && guard < 16) {
+            t = alias.get(t);
+            guard += 1;
+        }
+        return t;
+    };
+    const pins = new Set(curation.filter((f) => f.type === 'topic-pin').map((f) => f.topic));
+    const weights = new Map();
+    for (const f of curation) {
+        if (f.type === 'topic-weight')
+            weights.set(canonical(f.topic), f.weight);
+    }
+    const byTopic = new Map();
+    const manifestNext = { ...manifest };
+    let changed = false;
+    for (const e of entries) {
+        const hash = hashEntry(e);
+        const prev = manifest[e.path];
+        if (prev !== undefined && prev.hash === hash) {
+            // unchanged entry: keep its shard content contribution by still
+            // including it (shards are rebuilt from entries, not diffs — the
+            // manifest gates the COMMIT, shard content is always whole)
+        }
+        else {
+            changed = true;
+        }
+        manifestNext[e.path] = { hash, at: new Date().toISOString() };
+        for (const rawTopic of e.topics) {
+            const topic = canonical(rawTopic);
+            if (topic === '')
+                continue;
+            const list = byTopic.get(topic) ?? [];
+            list.push(e);
+            byTopic.set(topic, list);
+        }
+    }
+    // entries gone from the input drop out of the shards but stay in the
+    // manifest? No — the index is a pure function of current entries: prune.
+    for (const path of Object.keys(manifestNext)) {
+        if (!entries.some((e) => e.path === path))
+            delete manifestNext[path];
+    }
+    const shards = new Map();
+    const topicNames = [...byTopic.keys()].sort();
+    for (const topic of topicNames) {
+        const entriesForTopic = byTopic.get(topic);
+        const weight = weights.get(topic) ?? 1;
+        entriesForTopic.sort((a, b) => (b.mtime ?? 0) - (a.mtime ?? 0));
+        const lines = entriesForTopic.map((e) => `${e.mtime !== undefined ? new Date(e.mtime).toISOString().slice(0, 10) : '----'} | ${e.kind} | ${e.title} | ${e.path}`);
+        const header = [
+            `# topic: ${topic}`,
+            pins.has(topic) ? '(pinned)' : '',
+            `entries: ${entriesForTopic.length} · weight ${weight}`,
+            '',
+        ].filter((l) => l !== '').join('\n');
+        shards.set(topic, `${header}\n${lines.join('\n')}\n`);
+    }
+    void canonical;
+    return { shards, manifest: manifestNext, changed, topics: topicNames };
+}
+//# sourceMappingURL=indexing.js.map

package/lib/indexing.js.map

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

package/lib/injections.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The one boundary that decides which bytes of the durable log are CONVERSATION
+ * and which are host-injected context (knowledge-repo.md §15 amendment,
+ * "host-injected context is not conversation").
+ *
+ * Why this exists: the harness injects project context — workspace instruction
+ * files (whatever a given project's AGENTS.md holds), the runtime-context
+ * snapshot, the skill catalog — and injected events arrive in the log either as
+ * their own `user/message` (source.kind `agent-instructions`, `plugin`, …) or
+ * riding INSIDE human messages as `<system-reminder>` spans. A target project's
+ * instruction text is that project's business: it must not be archived into the
+ * shared knowledge corpus, searched by other workspaces, re-quoted into
+ * enrichment input, or bloating a child's re-archive of its own TOC notice
+ * generation after generation.
+ *
+ * Precedents this rule follows, not invents:
+ * - `signature.ts` (r28) already excluded these events from per-turn topic
+ *   signatures after measuring their poison: every signature gained the
+ *   injected filenames and drowned the real topic signal.
+ * - `tests/e2e/model-proxy.ts` (user decision 2026-09-20, AGENTS-BLIND) already
+ *   masks the same classes for tape matching, on the same reasoning:
+ *   development artifacts, every real project ships its own.
+ *
+ * What is NOT touched: the durable session log (invariant: append-only, always —
+ * the originals live on in the parent session), and genuine conversation bytes
+ * (a human typing the words "AGENTS.md" in prose is conversation and stays
+ * verbatim; only the structural injected forms are removed).
+ *
+ * Pure module: no cordis, no fs, no network.
+ */
+/** A user/message is human-authored when it carries no source, or source.kind
+ * 'user' (unlabelled keeps working for seeded fixtures — same rule the
+ * signature layer has used since r28). Everything else — 'agent-instructions',
+ * 'plugin' (the TOC notice, runtime snapshots), 'tool', 'system' — is injected
+ * context, not conversation. Exported so signature.ts imports the SAME
+ * predicate; the two layers must never drift on what counts as a turn. */
+export declare function isHumanAuthored(data: Record<string, unknown>): boolean;
+/** Label for the omission marker: kind, plus plugin name when the source
+ * carries one (so `plugin:dsh-chapters` is recognizable in a chapter). */
+export declare function sourceLabel(data: Record<string, unknown>): string;
+/** Strip every injected span from a message's text; deterministic, idempotent
+ * (the marker we emit below cannot re-trigger this rule). */
+export declare function stripReminderSpans(text: string): {
+    text: string;
+    removedChars: number;
+};
+/** The visible, greppable, countable marker an omission leaves behind. One
+ * shape for every class so downstream assertions (and the sentinel integration
+ * test) pin a single prefix. */
+export declare const omittedMarker: (what: string, chars: number) => string;
+/**
+ * The single screen the renderer and anything else consuming conversation text
+ * should use: what survives as chapter text, and what was omitted (event-level
+ * for non-human sources, span-level inside otherwise-human messages).
+ */
+export interface Screened {
+    /** Conversation text to render (human messages: span-stripped; non-human: ''). */
+    text: string;
+    /** True when the whole event is injected context (non-human source). */
+    omittedEvent: boolean;
+    /** Character count removed by this screen (event-level OR span-level). */
+    removedChars: number;
+    /** Source label for the event (for the marker + tests). */
+    sourceKind: string;
+}
+export declare function screenConversation(data: Record<string, unknown>, rawText: string, role: 'user' | 'assistant'): Screened;

package/lib/injections.js

@@ -0,0 +1,83 @@
+/**
+ * The one boundary that decides which bytes of the durable log are CONVERSATION
+ * and which are host-injected context (knowledge-repo.md §15 amendment,
+ * "host-injected context is not conversation").
+ *
+ * Why this exists: the harness injects project context — workspace instruction
+ * files (whatever a given project's AGENTS.md holds), the runtime-context
+ * snapshot, the skill catalog — and injected events arrive in the log either as
+ * their own `user/message` (source.kind `agent-instructions`, `plugin`, …) or
+ * riding INSIDE human messages as `<system-reminder>` spans. A target project's
+ * instruction text is that project's business: it must not be archived into the
+ * shared knowledge corpus, searched by other workspaces, re-quoted into
+ * enrichment input, or bloating a child's re-archive of its own TOC notice
+ * generation after generation.
+ *
+ * Precedents this rule follows, not invents:
+ * - `signature.ts` (r28) already excluded these events from per-turn topic
+ *   signatures after measuring their poison: every signature gained the
+ *   injected filenames and drowned the real topic signal.
+ * - `tests/e2e/model-proxy.ts` (user decision 2026-09-20, AGENTS-BLIND) already
+ *   masks the same classes for tape matching, on the same reasoning:
+ *   development artifacts, every real project ships its own.
+ *
+ * What is NOT touched: the durable session log (invariant: append-only, always —
+ * the originals live on in the parent session), and genuine conversation bytes
+ * (a human typing the words "AGENTS.md" in prose is conversation and stays
+ * verbatim; only the structural injected forms are removed).
+ *
+ * Pure module: no cordis, no fs, no network.
+ */
+/** A user/message is human-authored when it carries no source, or source.kind
+ * 'user' (unlabelled keeps working for seeded fixtures — same rule the
+ * signature layer has used since r28). Everything else — 'agent-instructions',
+ * 'plugin' (the TOC notice, runtime snapshots), 'tool', 'system' — is injected
+ * context, not conversation. Exported so signature.ts imports the SAME
+ * predicate; the two layers must never drift on what counts as a turn. */
+export function isHumanAuthored(data) {
+    const source = data.source;
+    return source?.kind === undefined || source.kind === 'user';
+}
+/** Label for the omission marker: kind, plus plugin name when the source
+ * carries one (so `plugin:dsh-chapters` is recognizable in a chapter). */
+export function sourceLabel(data) {
+    const source = data.source;
+    if (source === undefined)
+        return 'unlabelled';
+    return source.kind === 'plugin' && typeof source.plugin === 'string'
+        ? `plugin:${source.plugin}`
+        : String(source.kind ?? 'unknown');
+}
+/**
+ * The structural injection span. Anchored on the exact harness tag, case
+ * sensitive (the tape's own skill-catalog rule is case sensitive for the same
+ * reason: ordinary prose quoting the tag is vanishingly rare, and the cost of a
+ * false positive is a marked, countable omission — never a silent rewrite of
+ * history, the original bytes stay in the session log). The unclosed-tail form
+ * `[\s\S]*?(</system-reminder>|$)` mirrors the tape's masking of truncated
+ * injections.
+ */
+const REMINDER_SPAN = /<system-reminder>[\s\S]*?(?:<\/system-reminder>|$)/g;
+/** Strip every injected span from a message's text; deterministic, idempotent
+ * (the marker we emit below cannot re-trigger this rule). */
+export function stripReminderSpans(text) {
+    const removed = text.match(REMINDER_SPAN)?.join('').length ?? 0;
+    if (removed === 0)
+        return { text, removedChars: 0 };
+    return { text: text.replace(REMINDER_SPAN, '').trim(), removedChars: removed };
+}
+/** The visible, greppable, countable marker an omission leaves behind. One
+ * shape for every class so downstream assertions (and the sentinel integration
+ * test) pin a single prefix. */
+export const omittedMarker = (what, chars) => `⟦omitted:host-injected ${what}, ${chars} chars — project state, not conversation⟧`;
+export function screenConversation(data, rawText, role) {
+    if (role === 'user' && !isHumanAuthored(data)) {
+        return { text: '', omittedEvent: true, removedChars: rawText.length, sourceKind: sourceLabel(data) };
+    }
+    // Assistant text is model output, but a runtime snapshot has been observed
+    // appended to role user|system by the harness — screening assistant spans
+    // too costs one regex and can only ever mark, never invent, text.
+    const { text, removedChars } = stripReminderSpans(rawText);
+    return { text, omittedEvent: false, removedChars, sourceKind: 'user' };
+}
+//# sourceMappingURL=injections.js.map

package/lib/injections.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"injections.js","sourceRoot":"","sources":["../src/injections.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;;;;0EAK0E;AAC1E,MAAM,UAAU,eAAe,CAAC,IAA6B;IAC3D,MAAM,MAAM,GAAG,IAAI,CAAC,MAAuC,CAAA;IAC3D,OAAO,MAAM,EAAE,IAAI,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM,CAAA;AAC7D,CAAC;AAED;0EAC0E;AAC1E,MAAM,UAAU,WAAW,CAAC,IAA6B;IACvD,MAAM,MAAM,GAAG,IAAI,CAAC,MAAwD,CAAA;IAC5E,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,YAAY,CAAA;IAC7C,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ;QAClE,CAAC,CAAC,UAAU,MAAM,CAAC,MAAM,EAAE;QAC3B,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,IAAI,SAAS,CAAC,CAAA;AACtC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,aAAa,GAAG,qDAAqD,CAAA;AAE3E;6DAC6D;AAC7D,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC,MAAM,IAAI,CAAC,CAAA;IAC/D,IAAI,OAAO,KAAK,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC,EAAE,CAAA;IACnD,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,YAAY,EAAE,OAAO,EAAE,CAAA;AAChF,CAAC;AAED;;gCAEgC;AAChC,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,IAAY,EAAE,KAAa,EAAU,EAAE,CACnE,0BAA0B,IAAI,KAAK,KAAK,2CAA2C,CAAA;AAkBrF,MAAM,UAAU,kBAAkB,CAAC,IAA6B,EAAE,OAAe,EAAE,IAA0B;IAC3G,IAAI,IAAI,KAAK,MAAM,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9C,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,CAAC,MAAM,EAAE,UAAU,EAAE,WAAW,CAAC,IAAI,CAAC,EAAE,CAAA;IACtG,CAAC;IACD,2EAA2E;IAC3E,0EAA0E;IAC1E,kEAAkE;IAClE,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAA;IAC1D,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,CAAA;AACxE,CAAC"}

package/lib/notice.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The TOC notice: the single synthetic `user/message` that seeds a continuation.
+ *
+ * This module exists because of the 66-log lesson from `dsh-session-fork`
+ * (docs/development.md § L1): a message source outside the kernel's accepted
+ * vocabulary is not a cosmetic bug — stored logs that fail replay refuse to
+ * load, retroactively. The kernel's seed validator is not published as a
+ * callable, so the vocabulary here is pinned two ways and guarded by
+ * test/notice.test.ts:
+ *
+ *  1. Behaviorally, from the Phase 0 seed probes — every rejection and
+ *     acceptance recorded in spikes/probe/FINDINGS.md § The seed contract
+ *     (an object `source` with a non-empty string `kind`; `role: 'user'`; a
+ *     non-empty string `id`; array `content`; contiguous seq from 0).
+ *  2. Structurally, from the installed host's published types —
+ *     `@deepseek-ai/dsh-llm/lib/types/message.d.ts` `MessageSourceMap` (kinds
+ *     `user | plugin | model | tool`, merge-extensible) and `ContextForm`
+ *     (`instructions | catalog | notice | relay | recall | snapshot`), plus
+ *     `@deepseek-ai/dsh-session`'s `assertMessageEventShape`
+ *     (lib/index.js:927-957 in 0.1.5-rc.1-era builds) for the seed-time checks.
+ *
+ * `plugin: 'dsh-chapters'` + `form: 'snapshot'` mirrors how
+ * `@deepseek-ai/dsh-system-prompt` delivers assembled context in real logs:
+ * attributable to its producer, and rendered by whatever the UI already does
+ * for snapshots. INVARIANT 2: exactly one event, at seq 0. Never a slice of
+ * the parent's log.
+ */
+import type { SessionEventLike } from './types.ts';
+/** Our bundle id as it appears in `source.plugin`. Changing this orphans every already-seeded continuation. */
+export declare const NOTICE_PLUGIN = "dsh-chapters";
+/** The section name our TOC rides under inside the snapshot. */
+export declare const NOTICE_SECTION = "chapters:toc";
+/**
+ * Message source kinds the base vocabulary accepts (installed host,
+ * `dsh-llm/lib/types/message.d.ts` `MessageSourceMap`). The map is
+ * merge-extensible — other plugins add kinds (`agent-instructions`,
+ * `skill-catalog` were observed in production logs) — but WE may only emit
+ * kinds from this list, and only via the local validator.
+ */
+export declare const ACCEPTED_SOURCE_KINDS: readonly ["user", "plugin", "model", "tool"];
+/** `ContextForm` values, exactly as published (semantic, never visual). */
+export declare const ACCEPTED_CONTEXT_FORMS: readonly ["instructions", "catalog", "snapshot", "notice", "relay", "recall"];
+export interface TocNoticeOptions {
+    /** Fresh unique id per notice — the kernel rejects a seed message without one. */
+    newId: () => string;
+    time?: number;
+}
+/**
+ * Build the one seed event for a continuation. Throws rather than emit an
+ * event the kernel would reject at seed time — a refusal here is cheap, a
+ * bricked log is not.
+ */
+export declare function buildTocNotice(tocText: string, opts: TocNoticeOptions): SessionEventLike;
+/**
+ * Transcription of the kernel's seed-time checks (assertMessageEventShape +
+ * the recorded rejections). Kept as an exported predicate so tests pin our
+ * output against the same rules the host applies, and any future notice
+ * variant fails HERE, at the boundary of authorship.
+ */
+export declare function assertKernelAcceptedUserMessage(event: SessionEventLike): void;

package/lib/notice.js

@@ -0,0 +1,84 @@
+/** Our bundle id as it appears in `source.plugin`. Changing this orphans every already-seeded continuation. */
+export const NOTICE_PLUGIN = 'dsh-chapters';
+/** The section name our TOC rides under inside the snapshot. */
+export const NOTICE_SECTION = 'chapters:toc';
+/**
+ * Message source kinds the base vocabulary accepts (installed host,
+ * `dsh-llm/lib/types/message.d.ts` `MessageSourceMap`). The map is
+ * merge-extensible — other plugins add kinds (`agent-instructions`,
+ * `skill-catalog` were observed in production logs) — but WE may only emit
+ * kinds from this list, and only via the local validator.
+ */
+export const ACCEPTED_SOURCE_KINDS = ['user', 'plugin', 'model', 'tool'];
+/** `ContextForm` values, exactly as published (semantic, never visual). */
+export const ACCEPTED_CONTEXT_FORMS = [
+    'instructions', 'catalog', 'snapshot', 'notice', 'relay', 'recall',
+];
+/**
+ * Build the one seed event for a continuation. Throws rather than emit an
+ * event the kernel would reject at seed time — a refusal here is cheap, a
+ * bricked log is not.
+ */
+export function buildTocNotice(tocText, opts) {
+    if (tocText.trim().length === 0)
+        throw new Error('chapters: TOC notice text must not be empty');
+    const id = opts.newId();
+    if (id.length === 0)
+        throw new Error('chapters: notice message needs a non-empty id ("lacks an identified message")');
+    const event = {
+        type: 'user/message',
+        seq: 0, // seeds must be contiguous from 0 (FINDINGS: a seq-3 seed is rejected)
+        time: opts.time ?? Date.now(),
+        surfaceOp: 'append',
+        data: {
+            id,
+            role: 'user',
+            source: {
+                kind: 'plugin',
+                plugin: NOTICE_PLUGIN,
+                form: 'snapshot',
+                sections: [{ name: NOTICE_SECTION, text: tocText }],
+            },
+            // content mirrors sections[0].text byte-identically: the model reads
+            // `content`; the UI and attribution read `source`. One text, two faces.
+            content: [{ type: 'text', text: tocText }],
+        },
+    };
+    assertKernelAcceptedUserMessage(event);
+    return event;
+}
+/**
+ * Transcription of the kernel's seed-time checks (assertMessageEventShape +
+ * the recorded rejections). Kept as an exported predicate so tests pin our
+ * output against the same rules the host applies, and any future notice
+ * variant fails HERE, at the boundary of authorship.
+ */
+export function assertKernelAcceptedUserMessage(event) {
+    if (event.type !== 'user/message')
+        throw new Error(`chapters: unexpected notice event type ${event.type}`);
+    const data = event.data;
+    if (data === undefined || typeof data !== 'object')
+        throw new Error('chapters: notice event needs data');
+    if (typeof data.id !== 'string' || data.id.length === 0) {
+        throw new Error('chapters: seed user/message lacks an identified message');
+    }
+    if (data.role !== 'user')
+        throw new Error('chapters: seed message must have role "user"');
+    const source = data.source;
+    if (source === undefined || typeof source !== 'object' || typeof source.kind !== 'string' || source.kind.length === 0) {
+        throw new Error('chapters: seed message has invalid source (object with non-empty string kind required)');
+    }
+    if (!ACCEPTED_SOURCE_KINDS.includes(source.kind)) {
+        throw new Error(`chapters: source kind "${source.kind}" is outside the pinned vocabulary`);
+    }
+    if (source.kind === 'plugin' && (typeof source.plugin !== 'string' || source.plugin.length === 0)) {
+        throw new Error('chapters: plugin source must name its producer');
+    }
+    if (source.form !== undefined && !ACCEPTED_CONTEXT_FORMS.includes(source.form)) {
+        throw new Error(`chapters: context form "${String(source.form)}" is outside the published ContextForm union`);
+    }
+    if (!Array.isArray(data.content) || data.content.length === 0) {
+        throw new Error('chapters: seed message has invalid content');
+    }
+}
+//# sourceMappingURL=notice.js.map

package/lib/notice.js.map

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

package/lib/provider.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Knowledge-transport providers (knowledge-repo.md §3.2, extended by the §15
+ * amendment "transport is pluggable; git is one provider").
+ *
+ * The sync loop's transport surface is exactly six verbs — ensureClone,
+ * initLocal, removeMirror, stageAllAndCommit, pullFastForward, push — every one
+ * returning `{ok, detail, code?}` because §5.3 makes transport best-effort by
+ * rule: a transport failure degrades to local-only, it never throws into a
+ * conversation. A `SyncProvider` is those verbs plus an identity: `kind` (what
+ * the project record says it is, and what status lines print) and `describe`
+ * (one honest line for /chapters-status — e.g. which remote, which head).
+ *
+ * What a provider is NOT: storage. The workspace store stays the truth in
+ * every mode (§3.1); the mirror directory is materialized the same way whether
+ * a git clone or a remote API fills it, so search, rules, index build, and the
+ * read path never learn who transported the bytes. Adding a backend means
+ * implementing these six verbs and registering the kind — nothing else may
+ * grow provider-specific branches.
+ */
+import { type GitDriver } from './gitops.ts';
+import type { ProjectRecord } from './sync.ts';
+export type ProviderKind = 'git' | 'treedx';
+export interface SyncProvider extends GitDriver {
+    readonly kind: ProviderKind;
+    /** One human line describing where this project's transport points. */
+    describe(project: ProjectRecord): string;
+}
+/** The default provider: pure-JS git over HTTPS / local paths (record §3.2). */
+export declare const gitProvider: SyncProvider;
+export declare function registerProvider(provider: SyncProvider): void;
+/**
+ * Resolve the transport for a project record. `kind` absent = 'git' (every
+ * record written before providers existed parses to this default).
+ * Throws for an unknown/unregistered kind — callers degrade loudly (§5.3):
+ * the sync pass reports local-only with the reason; nothing silently reroutes.
+ */
+export declare function selectProvider(project: Pick<ProjectRecord, 'kind' | 'remote'>): SyncProvider;
+/**
+ * Reconcile a remote target's scheme with the configured `knowledgeProvider`
+ * policy ('auto' | 'git' | 'treedx'). A contradiction throws — NOTHING ever
+ * silently falls back into a different pool; the caller degrades loudly
+ * (auto-link skips + warns; /chapters-link refuses with the message).
+ */
+export declare function providerKindFor(targetKind: ProviderKind, policy: string): ProviderKind;

package/lib/provider.js

@@ -0,0 +1,66 @@
+/**
+ * Knowledge-transport providers (knowledge-repo.md §3.2, extended by the §15
+ * amendment "transport is pluggable; git is one provider").
+ *
+ * The sync loop's transport surface is exactly six verbs — ensureClone,
+ * initLocal, removeMirror, stageAllAndCommit, pullFastForward, push — every one
+ * returning `{ok, detail, code?}` because §5.3 makes transport best-effort by
+ * rule: a transport failure degrades to local-only, it never throws into a
+ * conversation. A `SyncProvider` is those verbs plus an identity: `kind` (what
+ * the project record says it is, and what status lines print) and `describe`
+ * (one honest line for /chapters-status — e.g. which remote, which head).
+ *
+ * What a provider is NOT: storage. The workspace store stays the truth in
+ * every mode (§3.1); the mirror directory is materialized the same way whether
+ * a git clone or a remote API fills it, so search, rules, index build, and the
+ * read path never learn who transported the bytes. Adding a backend means
+ * implementing these six verbs and registering the kind — nothing else may
+ * grow provider-specific branches.
+ */
+import { isomorphicDriver } from "./gitops.js";
+/** The default provider: pure-JS git over HTTPS / local paths (record §3.2). */
+export const gitProvider = {
+    ...isomorphicDriver,
+    kind: 'git',
+    describe: (project) => `git · ${project.remote}`,
+};
+// Registration is a map keyed by kind; Phase C's treedx module adds its entry.
+// Kept as a registry (not a switch) so provider selection stays open while
+// `kind` stays closed: an unknown kind is a LOUD refusal, never a silent
+// fallback to git that would sync someone's chapters into the wrong pool.
+const registry = new Map([['git', gitProvider]]);
+export function registerProvider(provider) {
+    registry.set(provider.kind, provider);
+}
+/**
+ * Resolve the transport for a project record. `kind` absent = 'git' (every
+ * record written before providers existed parses to this default).
+ * Throws for an unknown/unregistered kind — callers degrade loudly (§5.3):
+ * the sync pass reports local-only with the reason; nothing silently reroutes.
+ */
+export function selectProvider(project) {
+    const kind = project.kind ?? 'git';
+    const provider = registry.get(kind);
+    if (provider === undefined) {
+        throw new Error(`knowledge provider '${kind}' is not registered (remote ${project.remote})`);
+    }
+    return provider;
+}
+/**
+ * Reconcile a remote target's scheme with the configured `knowledgeProvider`
+ * policy ('auto' | 'git' | 'treedx'). A contradiction throws — NOTHING ever
+ * silently falls back into a different pool; the caller degrades loudly
+ * (auto-link skips + warns; /chapters-link refuses with the message).
+ */
+export function providerKindFor(targetKind, policy) {
+    if (policy === 'auto')
+        return targetKind;
+    if (policy !== 'git' && policy !== 'treedx') {
+        throw new Error(`knowledgeProvider policy '${policy}' is not one of auto | git | treedx`);
+    }
+    if (policy !== targetKind) {
+        throw new Error(`knowledgeProvider policy '${policy}' contradicts the remote target (a ${targetKind} remote) — fix one; there is no automatic fallback`);
+    }
+    return policy;
+}
+//# sourceMappingURL=provider.js.map