@oscharko-dev/keiko-local-knowledge 0.2.0

package/dist/chunking/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/chunking/types.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EACV,OAAO,EACP,UAAU,EACV,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,+BAA+B,CAAC;AAEvC,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAGnD,MAAM,MAAM,cAAc,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;AAEtD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC;CAC1C;AAGD,eAAO,MAAM,kBAAkB,MAAM,CAAC;AACtC,eAAO,MAAM,kBAAkB,KAAK,CAAC;AACrC,eAAO,MAAM,sBAAsB,KAAK,CAAC;AACzC,eAAO,MAAM,kBAAkB,QAAS,CAAC;AACzC,eAAO,MAAM,gBAAgB,OAAQ,CAAC;AACtC,eAAO,MAAM,kBAAkB,OAAQ,CAAC;AACxC,eAAO,MAAM,yBAAyB,EAAG,cAAuB,CAAC;AACjE,eAAO,MAAM,6BAA6B,gGACmK,CAAC;AAE9M,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;CACzC;AAID,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,SAAS,EAAE,kBAAkB,CAAC;IACvC,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAIhC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,SAAS,EAAE,kBAAkB,CAAC;IACvC,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IAEtC,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;CACnC;AAKD,qBAAa,aAAc,SAAQ,mBAAmB;IACpD,SAAyB,IAAI,EAAE,MAAM,CAAmB;CACzD;AAKD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC"}

package/dist/chunking/types.js

@@ -0,0 +1,26 @@
+// Type contracts for the chunking layer (Epic #189, Issue #195). Chunks are the unit of
+// retrieval — each row in the `chunks` table references exactly one parsed_unit (the
+// citation hop entrypoint) and carries `safeExcerptHash` (SHA-256 hex) instead of raw
+// text so the row is safe to copy across the trust boundary. Raw text is reconstructable
+// at retrieval time via parsed_unit → document → bytes.
+//
+// `tokenEstimator` is injected so future tokenizer upgrades (#196, #199) can swap in a
+// real tokenizer (e.g. tiktoken) without rewiring callers. The default estimator in
+// `token-estimator.ts` is intentionally crude (~4 chars per token) — see that file's
+// header for the documented limitation.
+import { KnowledgeStoreError } from "../errors.js";
+// Defaults documented inline so a caller passing `{}` gets predictable behaviour.
+export const DEFAULT_MAX_TOKENS = 400;
+export const DEFAULT_MIN_TOKENS = 64;
+export const DEFAULT_OVERLAP_TOKENS = 32;
+export const DEFAULT_MAX_CHUNKS = 50_000;
+export const MAX_CHUNK_TOKENS = 2_048;
+export const MAX_OVERLAP_TOKENS = 1_024;
+export const CHUNKING_STRATEGY_VERSION = "issue-195-v2";
+export const DEFAULT_CHUNKING_STRATEGY_KEY = `${CHUNKING_STRATEGY_VERSION}|max=${String(DEFAULT_MAX_TOKENS)}|min=${String(DEFAULT_MIN_TOKENS)}|overlap=${String(DEFAULT_OVERLAP_TOKENS)}|limit=${String(DEFAULT_MAX_CHUNKS)}|estimator=default`;
+// Distinct from KnowledgeStoreError so a test asserting "chunking guard fail-closed" cannot
+// accidentally accept any other error class. Extends KnowledgeStoreError so callers that
+// only catch the parent class still see the failure.
+export class ChunkingError extends KnowledgeStoreError {
+    name = "ChunkingError";
+}

package/dist/composition.d.ts

@@ -0,0 +1,57 @@
+import { type CapsuleSet, type CapsuleSetId, type KnowledgeCapsuleId, type KnowledgeSourceId, type KnowledgeSourceScopeKind } from "@oscharko-dev/keiko-contracts";
+import { type AddCapsuleSourceInput } from "./source-lifecycle.js";
+import type { KnowledgeStore } from "./store.js";
+export type CompositionErrorCode = "empty-source-batch" | "duplicate-source-in-batch" | "source-already-linked" | "empty-capsule-list" | "duplicate-capsule-in-batch";
+export declare class CompositionError extends Error {
+    readonly code: CompositionErrorCode;
+    constructor(code: CompositionErrorCode, message: string);
+}
+export interface ComposedRetrievalScope {
+    readonly capsuleSetId: CapsuleSetId;
+    readonly capsuleIds: readonly KnowledgeCapsuleId[];
+    readonly sourceIds: readonly KnowledgeSourceId[];
+    readonly alwaysQueryCapsuleIds: readonly KnowledgeCapsuleId[];
+    readonly sourceRoutingByCapsule: ReadonlyMap<KnowledgeCapsuleId, string>;
+}
+export interface RetrievalCapsuleSummary {
+    readonly id: KnowledgeCapsuleId;
+    readonly displayName: string;
+    readonly sourceCount: number;
+    readonly alwaysQuery: boolean;
+}
+export interface RetrievalSourceSummary {
+    readonly id: KnowledgeSourceId;
+    readonly displayName: string;
+    readonly capsuleId: KnowledgeCapsuleId;
+    readonly scopeKind: KnowledgeSourceScopeKind;
+}
+export interface RetrievalScopeDisclosure {
+    readonly capsuleSetId: CapsuleSetId;
+    readonly capsuleSummaries: readonly RetrievalCapsuleSummary[];
+    readonly sourceSummaries: readonly RetrievalSourceSummary[];
+}
+export type CapsuleMembershipChangeKind = "add-source" | "remove-source" | "compose-set";
+export interface CapsuleMembershipChange {
+    readonly id: string;
+    readonly capsuleId: KnowledgeCapsuleId;
+    readonly changeKind: CapsuleMembershipChangeKind;
+    readonly sourceId: KnowledgeSourceId | undefined;
+    readonly detailsJson: string | undefined;
+    readonly occurredAt: number;
+}
+export interface AddSourcesToCapsuleResult {
+    readonly capsuleId: KnowledgeCapsuleId;
+    readonly addedSourceIds: readonly KnowledgeSourceId[];
+}
+export interface ComposeCapsulesOptions {
+    readonly displayName: string;
+    readonly description?: string;
+    readonly capsuleIds: readonly KnowledgeCapsuleId[];
+    readonly tags?: readonly string[];
+}
+export declare function buildComposedRetrievalScope(store: KnowledgeStore, capsuleSetId: CapsuleSetId): ComposedRetrievalScope;
+export declare function describeRetrievalScope(scope: ComposedRetrievalScope, store: KnowledgeStore): RetrievalScopeDisclosure;
+export declare function addSourcesToCapsule(store: KnowledgeStore, capsuleId: KnowledgeCapsuleId, inputs: readonly AddCapsuleSourceInput[]): AddSourcesToCapsuleResult;
+export declare function composeCapsules(store: KnowledgeStore, opts: ComposeCapsulesOptions): CapsuleSet;
+export declare function listCapsuleMembershipChanges(store: KnowledgeStore, capsuleId: KnowledgeCapsuleId): readonly CapsuleMembershipChange[];
+//# sourceMappingURL=composition.d.ts.map

package/dist/composition.d.ts.map

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

package/dist/composition.js

@@ -0,0 +1,310 @@
+// composition.ts — Knowledge Capsule composition layer (Epic #189, Issue #263).
+//
+// Foundry-IQ "no global pool" rule lives in the type system (every record carries
+// capsuleId/sourceId) and the SQL FKs. This module is the in-memory union and the
+// audit-trail-emitting batch operations on top of that — pure functions over the store's
+// existing capsule, source, and CapsuleSet primitives; no new vectors, no SQL joins
+// across capsules.
+//
+// Exports:
+//   * buildComposedRetrievalScope(store, setId)  → in-memory {capsuleIds, sourceIds, …}
+//   * describeRetrievalScope(scope, store)        → UI-safe disclosure for the future #198
+//   * addSourcesToCapsule(store, capsuleId, …)   → multi-source link + audit + updated_at
+//   * composeCapsules(store, opts)                → createCapsuleSet + audit in one transaction
+//   * listCapsuleMembershipChanges(store, id)     → audit reader for capsule history view
+//   * CompositionError / CompositionErrorCode     → typed error surface
+//   * ComposedRetrievalScope / RetrievalScopeDisclosure / CapsuleMembershipChange / …
+//
+// All multi-row writes wrap in BEGIN/COMMIT/ROLLBACK so a partial batch never lands.
+import { randomUUID } from "node:crypto";
+import { isSafeDisplaySummary, validateKnowledgeSourceScope, } from "@oscharko-dev/keiko-contracts";
+import { getCapsule } from "./capsule-lifecycle.js";
+import { getCapsuleSet, createCapsuleSet, createCapsuleSetWithinTxn, } from "./capsule-set-lifecycle.js";
+import { KnowledgeNotFoundError, KnowledgeStoreError } from "./errors.js";
+import { listCapsuleSources } from "./source-lifecycle.js";
+import { validateSourceRoutingForCapsule } from "./source-routing-validation.js";
+export class CompositionError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "CompositionError";
+        this.code = code;
+    }
+}
+// ─── buildComposedRetrievalScope ────────────────────────────────────────────────
+export function buildComposedRetrievalScope(store, capsuleSetId) {
+    const set = getCapsuleSet(store, capsuleSetId);
+    if (set === undefined) {
+        throw new KnowledgeNotFoundError(`CapsuleSet not found: ${String(capsuleSetId)}`);
+    }
+    return composeScopeFromSet(store, set);
+}
+function composeScopeFromSet(store, set) {
+    const capsules = loadMemberCapsules(store, set.capsuleIds);
+    const sourceIds = collectUniqueSourceIds(capsules);
+    const alwaysQueryCapsuleIds = capsules.filter((c) => c.alwaysQuery === true).map((c) => c.id);
+    const routingMap = new Map();
+    for (const capsule of capsules) {
+        validateSourceRoutingForCapsule(capsule, listCapsuleSources(store, capsule.id));
+        if (capsule.sourceRoutingInstructions !== undefined) {
+            routingMap.set(capsule.id, capsule.sourceRoutingInstructions);
+        }
+    }
+    return {
+        capsuleSetId: set.id,
+        capsuleIds: set.capsuleIds,
+        sourceIds,
+        alwaysQueryCapsuleIds,
+        sourceRoutingByCapsule: routingMap,
+    };
+}
+function loadMemberCapsules(store, ids) {
+    const out = [];
+    for (const id of ids) {
+        const capsule = getCapsule(store, id);
+        if (capsule !== undefined)
+            out.push(capsule);
+    }
+    return out;
+}
+function collectUniqueSourceIds(capsules) {
+    const seen = new Set();
+    const out = [];
+    for (const capsule of capsules) {
+        for (const sid of capsule.sourceIds) {
+            const key = String(sid);
+            if (!seen.has(key)) {
+                seen.add(key);
+                out.push(sid);
+            }
+        }
+    }
+    return out;
+}
+// ─── describeRetrievalScope ─────────────────────────────────────────────────────
+export function describeRetrievalScope(scope, store) {
+    const alwaysQuerySet = new Set(scope.alwaysQueryCapsuleIds.map(String));
+    const capsuleSummaries = [];
+    const sourceSummaries = [];
+    for (const capsuleId of scope.capsuleIds) {
+        const capsule = getCapsule(store, capsuleId);
+        if (capsule === undefined)
+            continue;
+        const sources = listCapsuleSources(store, capsuleId);
+        capsuleSummaries.push({
+            id: capsule.id,
+            displayName: capsule.displayName,
+            sourceCount: sources.length,
+            alwaysQuery: alwaysQuerySet.has(String(capsule.id)),
+        });
+        for (const source of sources) {
+            sourceSummaries.push(summariseSource(source, capsule.id));
+        }
+    }
+    return {
+        capsuleSetId: scope.capsuleSetId,
+        capsuleSummaries,
+        sourceSummaries,
+    };
+}
+function summariseSource(source, capsuleId) {
+    return {
+        id: source.id,
+        displayName: source.displayName,
+        capsuleId,
+        scopeKind: source.scope.kind,
+    };
+}
+// ─── addSourcesToCapsule ────────────────────────────────────────────────────────
+const TOUCH_UPDATED_AT_SQL = "UPDATE capsules SET updated_at = :now WHERE id = :id";
+const INSERT_AUDIT_SQL = "INSERT INTO capsule_membership_changes (id, capsule_id, change_kind, source_id, details_json, occurred_at) VALUES (:id, :capsule_id, :change_kind, :source_id, :details_json, :occurred_at)";
+export function addSourcesToCapsule(store, capsuleId, inputs) {
+    if (inputs.length === 0) {
+        throw new CompositionError("empty-source-batch", `addSourcesToCapsule called with an empty source list for capsule ${String(capsuleId)}.`);
+    }
+    assertNoDuplicateInputIds(inputs);
+    const capsule = getCapsule(store, capsuleId);
+    if (capsule === undefined) {
+        throw new KnowledgeNotFoundError(`Capsule not found: ${String(capsuleId)}`);
+    }
+    assertNoneAlreadyLinked(store, capsuleId, inputs);
+    assertSafeSourceInputs(inputs);
+    return runAddSourcesTransaction(store, capsuleId, inputs);
+}
+function assertSafeSourceInputs(inputs) {
+    for (const input of inputs) {
+        if (input.displayName.trim().length === 0 || !isSafeDisplaySummary(input.displayName)) {
+            throw new KnowledgeStoreError("displayName must be a browser-safe non-empty string");
+        }
+        if (input.description !== undefined && !isSafeDisplaySummary(input.description)) {
+            throw new KnowledgeStoreError("description must be browser-safe when set");
+        }
+        for (const tag of input.tags) {
+            if (tag.trim().length === 0 || !isSafeDisplaySummary(tag)) {
+                throw new KnowledgeStoreError("tag must be a browser-safe non-empty string");
+            }
+        }
+        const result = validateKnowledgeSourceScope(input.scope);
+        if (!result.ok) {
+            throw new KnowledgeStoreError(result.errors.join(" "));
+        }
+    }
+}
+function assertNoDuplicateInputIds(inputs) {
+    const seen = new Set();
+    for (const input of inputs) {
+        const key = String(input.id);
+        if (seen.has(key)) {
+            throw new CompositionError("duplicate-source-in-batch", `Source id ${key} appears more than once in the batch.`);
+        }
+        seen.add(key);
+    }
+}
+function assertNoneAlreadyLinked(store, capsuleId, inputs) {
+    const existing = new Set(listCapsuleSources(store, capsuleId).map((s) => String(s.id)));
+    for (const input of inputs) {
+        if (existing.has(String(input.id))) {
+            throw new CompositionError("source-already-linked", `Source ${String(input.id)} is already linked to capsule ${String(capsuleId)}.`);
+        }
+    }
+}
+function runAddSourcesTransaction(store, capsuleId, inputs) {
+    const db = store._internal.db;
+    const now = store._internal.now();
+    // addSourceToCapsule already opens its own BEGIN/COMMIT — we cannot nest. Instead we
+    // open ONE explicit transaction here and bypass the per-source helper, inlining the
+    // insert against the same `capsule_sources` table.
+    db.exec("BEGIN");
+    try {
+        const insertKnowledgeSource = db.prepare("INSERT INTO knowledge_sources (id, display_name, description, tags_json, scope_kind, scope_json, created_at, updated_at) VALUES (:id, :display_name, :description, :tags_json, :scope_kind, :scope_json, :created_at, :updated_at) ON CONFLICT(id) DO UPDATE SET display_name = excluded.display_name, description = excluded.description, tags_json = excluded.tags_json, scope_kind = excluded.scope_kind, scope_json = excluded.scope_json, updated_at = excluded.updated_at");
+        const insertSource = db.prepare("INSERT INTO capsule_sources (id, capsule_id, display_name, description, tags_json, scope_kind, scope_json, created_at, updated_at) VALUES (:id, :capsule_id, :display_name, :description, :tags_json, :scope_kind, :scope_json, :created_at, :updated_at)");
+        const insertAudit = db.prepare(INSERT_AUDIT_SQL);
+        for (const input of inputs) {
+            const params = {
+                id: input.id,
+                display_name: input.displayName,
+                description: input.description ?? null,
+                tags_json: JSON.stringify(input.tags),
+                scope_kind: input.scope.kind,
+                scope_json: scopeJsonWithoutKind(input.scope),
+                created_at: now,
+                updated_at: now,
+            };
+            insertKnowledgeSource.run(params);
+            insertSource.run({ ...params, capsule_id: capsuleId });
+            insertAudit.run({
+                id: randomUUID(),
+                capsule_id: capsuleId,
+                change_kind: "add-source",
+                source_id: input.id,
+                details_json: null,
+                occurred_at: now,
+            });
+        }
+        db.prepare(TOUCH_UPDATED_AT_SQL).run({ now, id: capsuleId });
+        db.exec("COMMIT");
+    }
+    catch (error) {
+        db.exec("ROLLBACK");
+        throw error;
+    }
+    return {
+        capsuleId,
+        addedSourceIds: inputs.map((i) => i.id),
+    };
+}
+function scopeJsonWithoutKind(scope) {
+    const copy = {};
+    for (const [key, value] of Object.entries(scope)) {
+        if (key === "kind")
+            continue;
+        copy[key] = value;
+    }
+    return JSON.stringify(copy);
+}
+// ─── composeCapsules ────────────────────────────────────────────────────────────
+export function composeCapsules(store, opts) {
+    if (opts.capsuleIds.length === 0) {
+        throw new CompositionError("empty-capsule-list", "composeCapsules requires at least one capsule id.");
+    }
+    assertNoDuplicateCapsuleIds(opts.capsuleIds);
+    // Verify EVERY capsule id resolves BEFORE we open the CapsuleSet transaction. The
+    // create+audit pair must be atomic; failing partway through with the set already on
+    // disk would leave a dangling reference.
+    for (const id of opts.capsuleIds) {
+        const exists = getCapsule(store, id);
+        if (exists === undefined) {
+            throw new KnowledgeNotFoundError(`Capsule not found: ${String(id)}`);
+        }
+    }
+    return runComposeTransaction(store, opts);
+}
+function assertNoDuplicateCapsuleIds(ids) {
+    const seen = new Set();
+    for (const id of ids) {
+        const key = String(id);
+        if (seen.has(key)) {
+            throw new CompositionError("duplicate-capsule-in-batch", `Capsule id ${key} appears more than once in the composition request.`);
+        }
+        seen.add(key);
+    }
+}
+function runComposeTransaction(store, opts) {
+    // A single BEGIN/COMMIT wraps both the CapsuleSet write and the audit rows so a crash
+    // between them cannot leave a set with no audit trail. `createCapsuleSetWithinTxn` skips
+    // its own BEGIN/COMMIT to make this nesting possible (SQLite forbids nested transactions).
+    const setInput = buildCreateCapsuleSetInput(opts);
+    const db = store._internal.db;
+    const now = store._internal.now();
+    db.exec("BEGIN");
+    try {
+        createCapsuleSetWithinTxn(store, setInput, now);
+        const details = JSON.stringify({ setId: String(setInput.id) });
+        const stmt = db.prepare(INSERT_AUDIT_SQL);
+        for (const capsuleId of opts.capsuleIds) {
+            stmt.run({
+                id: randomUUID(),
+                capsule_id: capsuleId,
+                change_kind: "compose-set",
+                source_id: null,
+                details_json: details,
+                occurred_at: now,
+            });
+        }
+        db.exec("COMMIT");
+    }
+    catch (error) {
+        db.exec("ROLLBACK");
+        throw error;
+    }
+    const set = getCapsuleSet(store, setInput.id);
+    if (set === undefined) {
+        throw new Error(`runComposeTransaction: row not found after commit for ${String(setInput.id)}`);
+    }
+    return set;
+}
+function buildCreateCapsuleSetInput(opts) {
+    const id = randomUUID();
+    const base = {
+        id,
+        displayName: opts.displayName,
+        tags: opts.tags ?? [],
+        capsuleIds: opts.capsuleIds,
+    };
+    return opts.description !== undefined ? { ...base, description: opts.description } : base;
+}
+const SELECT_AUDIT_SQL = "SELECT id, capsule_id, change_kind, source_id, details_json, occurred_at FROM capsule_membership_changes WHERE capsule_id = :c ORDER BY occurred_at ASC, id ASC";
+export function listCapsuleMembershipChanges(store, capsuleId) {
+    const rows = store._internal.db.prepare(SELECT_AUDIT_SQL).all({ c: capsuleId });
+    return rows.map((row) => mapAuditRow(row));
+}
+function mapAuditRow(row) {
+    return {
+        id: row.id,
+        capsuleId: row.capsule_id,
+        changeKind: row.change_kind,
+        sourceId: row.source_id === null ? undefined : row.source_id,
+        detailsJson: row.details_json ?? undefined,
+        occurredAt: row.occurred_at,
+    };
+}

package/dist/conversation/citation-attacher.d.ts

@@ -0,0 +1,8 @@
+import type { RetrievalReference } from "@oscharko-dev/keiko-contracts";
+import type { ConversationCitationReference } from "./types.js";
+export interface AttachCitationsResult {
+    readonly text: string;
+    readonly citations: readonly ConversationCitationReference[];
+}
+export declare function attachCitationsToAnswer(answer: string, references: readonly RetrievalReference[]): AttachCitationsResult;
+//# sourceMappingURL=citation-attacher.d.ts.map

package/dist/conversation/citation-attacher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"citation-attacher.d.ts","sourceRoot":"","sources":["../../src/conversation/citation-attacher.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAqB,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAE3F,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,YAAY,CAAC;AAEhE,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,SAAS,6BAA6B,EAAE,CAAC;CAC9D;AAYD,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,SAAS,kBAAkB,EAAE,GACxC,qBAAqB,CAkBvB"}

package/dist/conversation/citation-attacher.js

@@ -0,0 +1,55 @@
+// Citation attachment (Epic #189, Issue #200). Extracts inline `[n]` markers from the
+// answer text and maps each marker to its `RetrievalReference` by 1-based index. The
+// Conversation Center UI surfaces the returned `citations` array as clickable footnotes;
+// `text` is the (unchanged) answer string the BFF persists to the chat row.
+//
+// Tolerance rules (the markers are LLM output — never assume well-formed):
+//   * `[0]` and `[n]` for n > references.length are silently dropped. We do NOT mutate
+//     the answer text — keeping the original prose means the UI can still display the
+//     stray marker; the citations array just won't link it.
+//   * Duplicate markers (`[1]` appearing twice) produce two entries in the citations
+//     array, in document order. The UI is responsible for de-duplicating if it wants a
+//     "unique footnotes" view.
+//   * Markers with leading zeros (`[01]`) are accepted to match what some models emit;
+//     the parsed integer is what's matched against the reference list.
+//   * Bracket glyphs beyond ASCII `[ ]` are accepted: CJK lenticular `【n】` and fullwidth
+//     `［n］`. Some models (e.g. gpt-oss) emit these instead of ASCII brackets; without
+//     this tolerance their citations would be lost and the caller would fall back to
+//     attaching every reference. The original glyph is preserved in `marker`.
+//   * No regex backtracking traps — the pattern is `[bracket](\d+)[bracket]`, linear in the
+//     answer length, bounded by digit count (each class matches exactly one character).
+// Linear scan; the pattern has no alternation or unbounded lookbehind so backtracking is
+// O(n) in the answer length. ECMAScript's `RegExp` with the `g` flag is the simplest
+// portable implementation; we cannot share a single static instance across calls because
+// `lastIndex` is mutated during iteration (a single shared instance would corrupt under
+// concurrent generator runs).
+// Open ∈ { [ , 【 (U+3010), ［ (U+FF3B) }; close ∈ { ] , 】 (U+3011), ］ (U+FF3D) }. Each
+// class matches exactly one character so the linear-scan / no-backtracking property holds.
+// Mismatched pairs (`[1】`) are accepted intentionally — markers are untrusted LLM output.
+const MARKER_PATTERN = /[[【［](\d+)[\]】］]/g;
+export function attachCitationsToAnswer(answer, references) {
+    if (answer.length === 0 || references.length === 0) {
+        return { text: answer, citations: [] };
+    }
+    const citations = [];
+    const re = new RegExp(MARKER_PATTERN.source, "g");
+    let match;
+    while ((match = re.exec(answer)) !== null) {
+        const marker = match[0];
+        const raw = match[1];
+        if (raw === undefined)
+            continue;
+        const index = Number.parseInt(raw, 10);
+        if (!Number.isFinite(index) || index < 1 || index > references.length)
+            continue;
+        const reference = references[index - 1];
+        if (reference === undefined)
+            continue;
+        citations.push(buildCitationEntry(marker, index, reference));
+    }
+    return { text: answer, citations };
+}
+function buildCitationEntry(marker, index, reference) {
+    const citation = reference.citation;
+    return { marker, index, citation, reference };
+}

package/dist/conversation/citation-excerpts.d.ts

@@ -0,0 +1,4 @@
+import type { CitationReference, KnowledgeCapsuleId } from "@oscharko-dev/keiko-contracts";
+import type { KnowledgeStore } from "../store.js";
+export declare function readCitationExcerpt(store: KnowledgeStore, capsuleId: KnowledgeCapsuleId, citation: CitationReference, maxChars?: number): string;
+//# sourceMappingURL=citation-excerpts.d.ts.map

package/dist/conversation/citation-excerpts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"citation-excerpts.d.ts","sourceRoot":"","sources":["../../src/conversation/citation-excerpts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAG3F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAgDlD,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,cAAc,EACrB,SAAS,EAAE,kBAAkB,EAC7B,QAAQ,EAAE,iBAAiB,EAC3B,QAAQ,SAA4B,GACnC,MAAM,CAgBR"}

package/dist/conversation/citation-excerpts.js

@@ -0,0 +1,41 @@
+import { readDocumentTextSpan } from "../discovery/persist.js";
+const DEFAULT_MAX_EXCERPT_CHARS = 900;
+function readDocumentText(store, capsuleId, citation) {
+    const row = store._internal.db
+        .prepare("SELECT normalized_text FROM document_texts WHERE capsule_id = :capsule_id AND document_id = :document_id")
+        .get({
+        capsule_id: capsuleId,
+        document_id: citation.documentId,
+    });
+    const stored = row?.normalized_text;
+    return typeof stored === "string" ? store._internal.contentCipher.openText(stored) : undefined;
+}
+function capExcerpt(raw, maxChars) {
+    const trimmed = raw.trim();
+    if (trimmed.length <= maxChars)
+        return trimmed;
+    return `${trimmed.slice(0, maxChars).trimEnd()}…`;
+}
+function sliceExcerpt(text, start, end, maxChars) {
+    if (text.length === 0)
+        return "";
+    const safeStart = Math.max(0, Math.min(text.length, start ?? 0));
+    const safeEnd = Math.max(safeStart, Math.min(text.length, end ?? safeStart + maxChars));
+    return capExcerpt(text.slice(safeStart, safeEnd), maxChars);
+}
+// Reads a citation's excerpt as a bounded span. When the chunk carries character offsets the span is
+// read through `readDocumentTextSpan` (SUBSTR over `document_texts` for small files OR over the
+// bounded `document_text_windows` rows for progressively-extracted large files), so a large
+// document's citation excerpt renders without materializing the whole document text. Chunks without
+// offsets fall back to the full small-file text projection.
+export function readCitationExcerpt(store, capsuleId, citation, maxChars = DEFAULT_MAX_EXCERPT_CHARS) {
+    const { characterStart, characterEnd } = citation;
+    if (characterStart !== undefined && characterEnd !== undefined) {
+        const span = readDocumentTextSpan(store._internal.db, store._internal.contentCipher, capsuleId, citation.documentId, characterStart, characterEnd);
+        return span === undefined ? "" : capExcerpt(span, maxChars);
+    }
+    const text = readDocumentText(store, capsuleId, citation);
+    if (text === undefined)
+        return "";
+    return sliceExcerpt(text, characterStart, characterEnd, maxChars);
+}

package/dist/conversation/grounded-answer-runner.d.ts

@@ -0,0 +1,9 @@
+import type { RetrievalDependencies } from "../retrieval/retrieval-runner.js";
+import type { AnswerGenerator, ConversationGroundedAnswer, ConversationGroundedQuery } from "./types.js";
+export interface GroundedAnswerDependencies {
+    readonly retrieval: RetrievalDependencies;
+    readonly answerGenerator: AnswerGenerator;
+    readonly signal?: AbortSignal;
+}
+export declare function runGroundedAnswer(deps: GroundedAnswerDependencies, query: ConversationGroundedQuery): Promise<ConversationGroundedAnswer>;
+//# sourceMappingURL=grounded-answer-runner.d.ts.map

package/dist/conversation/grounded-answer-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grounded-answer-runner.d.ts","sourceRoot":"","sources":["../../src/conversation/grounded-answer-runner.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,kCAAkC,CAAC;AAG9E,OAAO,KAAK,EACV,eAAe,EACf,0BAA0B,EAC1B,yBAAyB,EAC1B,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,SAAS,EAAE,qBAAqB,CAAC;IAC1C,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;IAG1C,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,0BAA0B,EAChC,KAAK,EAAE,yBAAyB,GAC/B,OAAO,CAAC,0BAA0B,CAAC,CA4CrC"}

package/dist/conversation/grounded-answer-runner.js

@@ -0,0 +1,61 @@
+// Grounded-answer runner (Epic #189, Issue #200). The single entry point the
+// Conversation Center BFF will call: question text + capsule scope ⇒ structured answer
+// with attached citations, ready to persist to the chat row and the audit ledger.
+//
+// Composition (all dependencies UNCHANGED from #199):
+//   1. `runLocalKnowledgeRetrieval` resolves scope + policy and produces ranked refs.
+//   2. `assembleGroundedContext` projects the refs into a `LocalKnowledgeGroundedContextPack`.
+//   3. The injected `AnswerGenerator` turns the pack into an answer string. The runner
+//      passes through the AbortSignal so cancellation reaches the model call.
+//   4. `attachCitationsToAnswer` scans the answer for `[n]` markers and pairs them with
+//      the original reference array.
+//
+// No-evidence short-circuit: if retrieval returns `noEvidence: true` the runner returns
+// immediately WITHOUT invoking the generator. The audit ledger / UI surfaces the
+// `reason` so the user sees an honest "we found nothing" message rather than a
+// hallucinated answer.
+//
+// This module owns NO new business logic — it is wiring. Every behaviour invariant
+// (scope resolution, embedding identity check, strictest-policy floor, answer-grounding
+// rejection) is enforced by the underlying retrieval layer; the runner merely composes.
+import { assembleGroundedContext } from "../retrieval/context-pack-assembler.js";
+import { runLocalKnowledgeRetrieval } from "../retrieval/retrieval-runner.js";
+import { attachCitationsToAnswer } from "./citation-attacher.js";
+export async function runGroundedAnswer(deps, query) {
+    const retrieval = await runLocalKnowledgeRetrieval({
+        store: deps.retrieval.store,
+        embeddingAdapter: deps.retrieval.embeddingAdapter,
+        ...(deps.signal !== undefined ? { signal: deps.signal } : {}),
+    }, {
+        text: query.text,
+        ...(query.capsuleId !== undefined ? { capsuleId: query.capsuleId } : {}),
+        ...(query.capsuleSetId !== undefined ? { capsuleSetId: query.capsuleSetId } : {}),
+        ...(query.topK !== undefined ? { topK: query.topK } : {}),
+        ...(query.minScore !== undefined ? { minScore: query.minScore } : {}),
+    });
+    const pack = assembleGroundedContext(retrieval.references);
+    if (retrieval.noEvidence) {
+        return {
+            answer: "",
+            references: retrieval.references,
+            citations: [],
+            pack,
+            noEvidence: true,
+            ...(retrieval.reason !== undefined ? { reason: retrieval.reason } : {}),
+        };
+    }
+    const answerText = await deps.answerGenerator.generate({
+        query,
+        pack,
+        references: retrieval.references,
+        ...(deps.signal !== undefined ? { signal: deps.signal } : {}),
+    });
+    const attached = attachCitationsToAnswer(answerText, retrieval.references);
+    return {
+        answer: attached.text,
+        references: retrieval.references,
+        citations: attached.citations,
+        pack,
+        noEvidence: false,
+    };
+}

package/dist/conversation/index.d.ts

@@ -0,0 +1,5 @@
+export { runGroundedAnswer, type GroundedAnswerDependencies } from "./grounded-answer-runner.js";
+export { ModelGatewayAnswerGenerator, AnswerGroundingRejectedError, buildPromptMessages, type ChatGateway, type ModelGatewayAnswerGeneratorOptions, } from "./model-gateway-answer-generator.js";
+export { attachCitationsToAnswer, type AttachCitationsResult } from "./citation-attacher.js";
+export type { AnswerGenerator, AnswerGeneratorInput, ConversationCitationReference, ConversationGroundedAnswer, ConversationGroundedQuery, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/conversation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/conversation/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,iBAAiB,EAAE,KAAK,0BAA0B,EAAE,MAAM,6BAA6B,CAAC;AAEjG,OAAO,EACL,2BAA2B,EAC3B,4BAA4B,EAC5B,mBAAmB,EACnB,KAAK,WAAW,EAChB,KAAK,kCAAkC,GACxC,MAAM,qCAAqC,CAAC;AAE7C,OAAO,EAAE,uBAAuB,EAAE,KAAK,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAE7F,YAAY,EACV,eAAe,EACf,oBAAoB,EACpB,6BAA6B,EAC7B,0BAA0B,EAC1B,yBAAyB,GAC1B,MAAM,YAAY,CAAC"}

package/dist/conversation/index.js

@@ -0,0 +1,7 @@
+// Public surface of the conversation/ layer (Epic #189, Issue #200). Wires the #199
+// retrieval pipeline into the Conversation Center BFF. Consumers outside this package
+// import from the package barrel in ../index.ts; the subdirectory is never imported
+// directly (ADR-0019 direction rule 3e + trust-8).
+export { runGroundedAnswer } from "./grounded-answer-runner.js";
+export { ModelGatewayAnswerGenerator, AnswerGroundingRejectedError, buildPromptMessages, } from "./model-gateway-answer-generator.js";
+export { attachCitationsToAnswer } from "./citation-attacher.js";

package/dist/conversation/model-gateway-answer-generator.d.ts

@@ -0,0 +1,28 @@
+import type { CapsuleAnswerGroundingPolicy, ChatMessage, GatewayRequest, NormalizedResponse } from "@oscharko-dev/keiko-contracts";
+import type { LocalKnowledgeGroundedContextPack } from "../retrieval/context-pack-assembler.js";
+import type { AnswerGenerator, AnswerGeneratorInput } from "./types.js";
+type CitationMetadataRedactor = (value: string) => string;
+export interface ChatGateway {
+    readonly chat: (request: GatewayRequest) => Promise<NormalizedResponse>;
+}
+export interface ModelGatewayAnswerGeneratorOptions {
+    readonly chatGateway: ChatGateway;
+    readonly modelId: string;
+    readonly policy: CapsuleAnswerGroundingPolicy;
+    readonly redactCitationMetadata?: CitationMetadataRedactor;
+}
+export declare class AnswerGroundingRejectedError extends Error {
+    readonly name: string;
+    constructor();
+}
+export declare class ModelGatewayAnswerGenerator implements AnswerGenerator {
+    private readonly chatGateway;
+    private readonly modelId;
+    private readonly policy;
+    private readonly redactCitationMetadata;
+    constructor(options: ModelGatewayAnswerGeneratorOptions);
+    generate(input: AnswerGeneratorInput): Promise<string>;
+}
+export declare function buildPromptMessages(question: string, pack: LocalKnowledgeGroundedContextPack, redactCitationMetadata?: CitationMetadataRedactor): readonly ChatMessage[];
+export {};
+//# sourceMappingURL=model-gateway-answer-generator.d.ts.map