@kaelio/ktx 0.13.0 → 0.14.0

package/dist/skills/gdrive_synthesize/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: gdrive_synthesize
+description: Synthesize durable KTX wiki pages from staged Google Drive document pulls. Load when a WorkUnit contains Google Doc raw files from `docs/**`.
+callers: [memory_agent]
+---
+
+# Google Drive Doc Synthesis
+
+Use this skill when a WorkUnit contains staged Google Drive content from `docs/**`.
+
+## Role
+
+Each WorkUnit is one Google Doc plus its metadata. Read the assigned raw files, then write a small set of durable wiki entries that capture reusable organizational knowledge. Write final memory directly; do not write candidates.
+
+## Required Workflow
+
+1. Read the WorkUnit notes and `rawFiles` list. Document content lives in `page.md`; `metadata.json` holds title, path, url, modified time, and Drive folder context.
+2. For each assigned doc, call `read_raw_file`, or `read_raw_span` for oversized docs when the notes specify a span.
+3. Search `wiki_search` for existing pages that overlap the WorkUnit topics. Prefer updating an existing page over creating a duplicate.
+4. Use `context_evidence_search`, `context_evidence_read`, and `context_evidence_neighbors` when indexed document chunks would help reconcile related facts. Pass `chunkId` and `documentId` values verbatim as returned by the evidence tools.
+5. Write durable business knowledge with `wiki_write`. Aim for a small number of high-quality pages per doc. Include `rawPaths` with the exact Google Drive raw files that support each page.
+6. If a doc references warehouse, dbt, Looker, Metabase, or MetricFlow objects, you may verify them with `discover_data`, `entity_details`, `sql_execution`, `sl_discover`, or `sl_read_source`, but Google Drive docs are knowledge-only in v1. Do not create semantic-layer sources under the `gdrive` connection.
+7. For every deleted raw path in the Eviction Set, call `eviction_list`, decide retention, then `emit_eviction_decision`. Do this even when no wiki write is needed.
+
+## What To Capture
+
+Capture durable, reusable company knowledge:
+
+- policies, workflows, process rules, ownership conventions, and operating procedures
+- product definitions, business terminology, and organizational guidance
+- source-of-truth statements, caveats, conflict notes, and supersession guidance
+- cross-system aliases that connect doc terminology to warehouse, dbt, Looker, Metabase, or MetricFlow names
+
+Skip noisy or transient content:
+
+- brainstorming notes with no durable rule
+- task lists, meeting scheduling details, and time-bounded status updates
+- duplicate docs with no new fact
+- shallow summaries that add no reusable policy or definition
+
+## Quality
+
+Prefer fewer, stronger entries. Every wiki entry must cite at least one Google Doc using its title or path and last modified date when available. When evidence conflicts, write a conflict note inside the wiki page rather than choosing silently.
+
+If one doc covers several related ideas, synthesize the shared durable rules instead of writing one thin page per paragraph. For oversized spans, read only the assigned span unless the WorkUnit explicitly asks for neighboring context.
+
+Search existing wiki pages for the same `tables:` or `sl_refs:` frontmatter and for source-of-truth aliases before creating a new page. If an existing page already documents the same warehouse object or business concept, update it instead of creating a differently named duplicate.
+
+## Citation Style
+
+```md
+## Agentic Harness
+- The harness provides the operational framework that turns an agent prototype into a production system.
+- Source: Google Doc - Herness, last modified 2026-05-24.
+- Conflict note: An older internal note uses a narrower definition focused only on tool wiring; treat the current Google Doc as the durable operating definition unless replaced explicitly.
+```
+
+## Semantic-Layer Rules
+
+- Google Drive docs are knowledge-only in v1; keep durable output in wiki pages.
+- Do not create semantic-layer sources under the `gdrive` connection.
+- If a doc references an existing warehouse or semantic-layer object and you can verify it, you may attach `sl_refs` in wiki output after confirmation.
+- If a doc mentions a table or source that cannot be verified, keep the identifier in wiki text as unverified or use `emit_unmapped_fallback` only when the missing physical object itself is the important durable fact.
+
+## Identifier Verification Protocol
+
+Before writing a wiki page on any topic:
+
+1. `discover_data({query: "<topic>"})` - see what wikis, SL sources, and raw
+   tables already exist. Prefer updating existing pages over creating new ones.
+
+Before emitting any `schema.table` or `schema.table.column` into a wiki body,
+`tables:` frontmatter, `sl_refs`, or `emit_unmapped_fallback`:
+
+2. `entity_details({connectionId, targets: [{display: "<identifier>"}]})` -
+   confirm the identifier resolves; inspect native types, FK/PK, and
+   sampleValues.
+3. For literal values from the doc, such as status codes or plan tiers,
+   check whether they appear in `entity_details` sampleValues for the relevant
+   column. If sampleValues is short or the sample may have missed real values,
+   run a `sql_execution` probe with the same warehouse connection id:
+   `sql_execution({connectionId, sql: "SELECT DISTINCT <col> FROM <ref> LIMIT 50"})`.
+4. If the candidate identifier still does not resolve, do one of:
+   - Use `sql_execution({connectionId, sql: "SELECT 1 FROM <ref> LIMIT 0"})`.
+     If it errors, the identifier is fictional.
+   - Wrap the identifier in `[unverified - from <rawPath>]` in the wiki body,
+     citing the exact raw path that mentioned it.
+   - When recording `emit_unmapped_fallback` with `no_physical_table`, include
+     the failing probe error in `clarification`.
+5. Never copy `<schema>.<table>` placeholder strings from these instructions
+   into output.
+
+## Tools
+
+Allowed: `read_raw_file`, `read_raw_span`, `wiki_search`, `wiki_read`, `wiki_write`, `discover_data`, `entity_details`, `sql_execution`, `sl_discover`, `sl_read_source`, `context_evidence_search`, `context_evidence_read`, `context_evidence_neighbors`, `emit_unmapped_fallback`, `eviction_list`, `emit_eviction_decision`.
+
+Not allowed: `context_candidate_write`, `context_candidate_mark`, `sl_write_source`, `sl_edit_source`, `sl_validate`.

package/dist/skills/wiki_capture/SKILL.md

@@ -112,6 +112,30 @@ All three fields use REPLACE semantics on update:
 - Pass `[]` → field is cleared.
 - Pass `[values]` → replaces existing with exactly those values (no merging).
 
+## Connection scoping
+
+A project may have several databases whose schemas reuse the same concept names
+(two warehouses each with `orders`, `customers`, …). The `connections`
+frontmatter field keeps database-specific pages from polluting searches about
+other databases.
+
+- The `wiki_write` tool accepts a `connections` field (list of connection ids,
+  same REPLACE semantics as `tags`). Absent or empty ⇒ the page is **unscoped**
+  and applies to every connection.
+- When this ingest/turn is scoped to a connection (its id appears in the prompt
+  context — e.g. `connectionId: warehouse` in the SL Sources header or the
+  `<context>` block), set `connections: [<that id>]` on pages whose content is
+  **specific to that database** ("in this warehouse `user_id` is the device id,
+  not the account id"). Pair this with a connection-distinctive key so two
+  databases' same-concept pages can coexist: `orders_sales_db`, not `orders`.
+- Leave `connections` empty for clearly **org-wide** knowledge ("fiscal year
+  starts in February") so it stays visible everywhere. Do not scope a page to a
+  connection just because the turn happened to be connection-scoped.
+- Keys are still a flat, global namespace; `connections` does not namespace
+  them. A connection-scoped write whose key already belongs to a page scoped to
+  a *different* connection is rejected to prevent silently overwriting it — pick
+  a connection-distinctive key instead.
+
 ## Editing existing pages
 
 Two modes:

package/dist/sql.js

@@ -1,5 +1,6 @@
 import { FEDERATED_CONNECTION_ID } from './context/connections/federation.js';
 import { executeProjectReadOnlySql } from './context/connections/project-sql-executor.js';
+import { assertSqlQueryableConnection } from './context/connections/dialects.js';
 import { resolveConfiguredConnection } from './context/connections/resolve-connection.js';
 import { loadKtxProject } from './context/project/project.js';
 import { sqlAnalysisDialectForDriver } from './context/sql-analysis/dialect.js';
@@ -90,6 +91,9 @@ export async function runKtxSql(args, io = process, deps = {}) {
         const connection = isFederated ? undefined : resolveConfiguredConnection(project.config, args.connectionId);
         driver = isFederated ? 'duckdb' : String(connection?.driver ?? 'unknown').toLowerCase();
         demoConnection = isFederated ? false : isDemoConnection(args.connectionId, connection);
+        if (!isFederated) {
+            assertSqlQueryableConnection(args.connectionId, connection?.driver);
+        }
         const createSqlAnalysis = deps.createSqlAnalysis ??
             (() => createManagedDaemonSqlAnalysisPort({
                 cliVersion: args.cliVersion,

package/dist/status-project.d.ts

@@ -75,6 +75,10 @@ interface LocalStatsIngestPerConnection {
     connectionId: string;
     adapter: string;
     lastCompletedAt: string;
+    skippedObjects: Array<{
+        name: string;
+        reason: string;
+    }>;
 }
 interface LocalStatsSemanticLayerEntry {
     connectionId: string;

package/dist/status-project.js

@@ -4,6 +4,7 @@ import { runClaudeCodeAuthProbe } from './context/llm/claude-code-runtime.js';
 import { CODEX_ISOLATION_WARNING, CODEX_ISOLATION_WARNING_FIX, } from './context/llm/codex-isolation.js';
 import { runCodexAuthProbe } from './context/llm/codex-runtime.js';
 import { ktxLocalStateDbPath } from './context/project/local-state-db.js';
+import { listReferencedConnectionIds } from './context/wiki/local-knowledge.js';
 import { isQueryHistoryEnabled, queryHistoryDialectForConnection, } from './context/ingest/adapters/historic-sql/connection-dialect.js';
 import { historicSqlProbeCatalogName, runHistoricSqlReadinessProbe, } from './context/ingest/historic-sql-probes.js';
 import { formatClaudeCodePromptCachingFix, formatClaudeCodePromptCachingWarning, ignoredClaudeCodePromptCachingFields, } from './claude-code-prompt-caching.js';
@@ -387,6 +388,29 @@ function buildStorageStatus(config) {
         gitAuthor: config.storage.git.author,
     };
 }
+/**
+ * Warn (never fail) when stored wiki pages reference connection ids that are no
+ * longer in `ktx.yaml`. Config and page content evolve independently, so a
+ * dangling reference is a soft condition — the pages still load, search, and
+ * read; it just signals a typo or a removed connection.
+ */
+async function buildUnknownConnectionWarning(project) {
+    let referenced;
+    try {
+        referenced = await listReferencedConnectionIds(project);
+    }
+    catch {
+        return null;
+    }
+    const unknown = referenced.filter((id) => !Object.hasOwn(project.config.connections, id));
+    if (unknown.length === 0) {
+        return null;
+    }
+    return {
+        message: `Wiki pages reference connection id(s) not in ktx.yaml: ${unknown.join(', ')}. Those pages still load and search.`,
+        fix: 'Add the connection(s) via `ktx setup`, or update the pages’ `connections` frontmatter.',
+    };
+}
 function buildWarnings(config, connections, llm, embeddings) {
     const warnings = [];
     for (const adapter of config.ingest.adapters) {
@@ -555,6 +579,21 @@ function tryQuery(run, fallback) {
         return fallback;
     }
 }
+function skippedObjectsFromReportBody(bodyJson) {
+    try {
+        const body = JSON.parse(bodyJson);
+        const skipped = body.fetch?.skipped;
+        if (!Array.isArray(skipped))
+            return [];
+        return skipped.map((issue) => ({
+            name: typeof issue.entityId === 'string' && issue.entityId.length > 0 ? issue.entityId : 'object',
+            reason: typeof issue.message === 'string' ? issue.message : 'introspection failed',
+        }));
+    }
+    catch {
+        return [];
+    }
+}
 /** @internal */
 export async function buildLocalStatsStatus(project) {
     const dbPath = ktxLocalStateDbPath(project);
@@ -581,8 +620,10 @@ export async function buildLocalStatsStatus(project) {
         const totalCompletedRuns = tryQuery(() => db
             .prepare(`SELECT COUNT(*) AS n FROM local_ingest_reports WHERE status = 'done'`)
             .get()?.n ?? 0, 0);
-        const ingestRows = tryQuery(() => db
-            .prepare(`SELECT connection_id, adapter, MAX(completed_at) AS last_completed_at
+        const ingestRows = tryQuery(() => 
+        // SQLite returns body_json from the MAX(completed_at) row for each group.
+        db
+            .prepare(`SELECT connection_id, adapter, MAX(completed_at) AS last_completed_at, body_json
              FROM local_ingest_reports
              WHERE status = 'done'
              GROUP BY connection_id, adapter`)
@@ -595,6 +636,7 @@ export async function buildLocalStatsStatus(project) {
                     connectionId: row.connection_id,
                     adapter: row.adapter,
                     lastCompletedAt: row.last_completed_at,
+                    skippedObjects: skippedObjectsFromReportBody(row.body_json),
                 });
             }
         }
@@ -683,6 +725,10 @@ export async function buildProjectStatus(project, options = {}) {
     const queryHistory = await buildQueryHistoryStatus(project, options);
     const pipeline = buildPipelineStatus(config);
     const warnings = buildWarnings(config, connections, llm, embeddings);
+    const unknownConnectionWarning = await buildUnknownConnectionWarning(project);
+    if (unknownConnectionWarning) {
+        warnings.push(unknownConnectionWarning);
+    }
     const localStats = await buildLocalStatsStatus(project);
     const { verdict, reason, nextActions } = buildVerdict(llm, embeddings, connections, queryHistory, warnings);
     return {
@@ -796,6 +842,12 @@ function renderLocalStats(lines, stats, dim, bold) {
         const adapterWidth = Math.max(...ingest.perConnection.map((entry) => entry.adapter.length));
         for (const entry of ingest.perConnection) {
             lines.push(`      ${entry.connectionId.padEnd(nameWidth)}   ${dim(entry.adapter.padEnd(adapterWidth))}   ${dim(`last ${formatRelativeFromNow(entry.lastCompletedAt)}`)}`);
+            if (entry.skippedObjects.length > 0) {
+                const first = entry.skippedObjects[0];
+                const extra = entry.skippedObjects.length - 1;
+                const detail = `${first.name}: ${first.reason}${extra > 0 ? ` (+${extra} more)` : ''}`;
+                lines.push(`      ${' '.repeat(nameWidth)}   ${dim(`${entry.skippedObjects.length} object${entry.skippedObjects.length === 1 ? '' : 's'} skipped — ${detail}`)}`);
+            }
         }
     }
     if (stats.wikiPages.length === 0) {

package/dist/telemetry/events.d.ts

@@ -62,10 +62,10 @@ export declare const telemetryEventSchemas: {
         isCi: z.ZodBoolean;
         step: z.ZodEnum<{
             embeddings: "embeddings";
+            databases: "databases";
             project: "project";
             models: "models";
             sources: "sources";
-            databases: "databases";
             context: "context";
             runtime: "runtime";
             secrets: "secrets";
@@ -254,9 +254,9 @@ export declare const telemetryEventSchemas: {
         queryVerb: z.ZodEnum<{
             show: "show";
             with: "with";
+            explain: "explain";
             select: "select";
             other: "other";
-            explain: "explain";
         }>;
         referencedTableCount: z.ZodNumber;
         durationMs: z.ZodNumber;

package/dist/text-ingest.d.ts

@@ -2,6 +2,7 @@ import type { MemoryAgentInput } from './context/memory/types.js';
 import type { MemoryIngestStatus } from './context/memory/memory-runs.js';
 import { type KtxLocalProject } from './context/project/project.js';
 import type { KtxCliIo } from './cli-runtime.js';
+import { type VerbatimIngestorPort } from './verbatim-ingest.js';
 export interface KtxTextIngestArgs {
     projectDir: string;
     texts: string[];
@@ -10,6 +11,8 @@ export interface KtxTextIngestArgs {
     userId: string;
     json: boolean;
     failFast: boolean;
+    /** Code-driven verbatim ingest: store the document body unchanged, LLM derives metadata only. */
+    verbatim?: boolean;
 }
 /** @internal */
 export interface TextMemoryIngestPort {
@@ -24,6 +27,7 @@ export interface KtxTextIngestDeps {
         projectDir: string;
     }) => Promise<KtxLocalProject>;
     createMemoryIngest?: (project: KtxLocalProject) => TextMemoryIngestPort;
+    createVerbatimIngestor?: (project: KtxLocalProject) => VerbatimIngestorPort;
     readFile?: (path: string) => Promise<string>;
     readStdin?: () => Promise<string>;
     now?: () => number;

package/dist/text-ingest.js

@@ -4,11 +4,15 @@ import { createLocalProjectMemoryIngest } from './context/memory/local-memory.js
 import { loadKtxProject } from './context/project/project.js';
 import { createRepainter, initViewState, renderContextBuildView } from './context-build-view.js';
 import { formatDuration } from './demo-metrics.js';
+import { createLocalProjectVerbatimIngestor, } from './verbatim-ingest.js';
 const INLINE_TEXT_LABEL_MAX_LENGTH = 50;
 const ANSI_ESCAPE_PATTERN = /\x1B\[[0-?]*[ -/]*[@-~]/g;
 function defaultCreateMemoryIngest(project) {
     return createLocalProjectMemoryIngest(project);
 }
+function defaultCreateVerbatimIngestor(project) {
+    return createLocalProjectVerbatimIngestor(project);
+}
 async function defaultReadStdin() {
     const chunks = [];
     process.stdin.setEncoding('utf-8');
@@ -72,17 +76,17 @@ async function loadItems(args, deps) {
     args.texts.forEach((content, index) => {
         const label = textLabel(content, index, usedTextLabels);
         usedTextLabels.add(label);
-        items.push({ label, content });
+        items.push({ label, content, origin: { kind: 'text' } });
     });
     const readFile = deps.readFile ?? defaultReadFile;
     const readStdin = deps.readStdin ?? defaultReadStdin;
     for (const file of args.files) {
         if (file === '-') {
-            items.push({ label: stdinLabel(items), content: await readStdin() });
+            items.push({ label: stdinLabel(items), content: await readStdin(), origin: { kind: 'stdin' } });
         }
         else {
             const path = resolve(file);
-            items.push({ label: basename(path), content: await readFile(path) });
+            items.push({ label: basename(path), content: await readFile(path), origin: { kind: 'file', path } });
         }
     }
     return items;
@@ -112,13 +116,13 @@ function makeTarget(label) {
 function allTargets(state) {
     return [...state.primarySources, ...state.contextSources];
 }
-function renderTextIngestView(state, styled) {
+function renderTextIngestView(state, styled, verbatim) {
     return renderContextBuildView(state, {
         styled,
-        title: 'Ingesting text memory',
-        contextGroupLabel: 'Texts',
-        sourceIngestRunningText: 'capturing...',
-        completedItemName: { singular: 'text', plural: 'texts' },
+        title: verbatim ? 'Writing verbatim pages' : 'Ingesting text memory',
+        contextGroupLabel: verbatim ? 'Documents' : 'Texts',
+        sourceIngestRunningText: verbatim ? 'writing...' : 'capturing...',
+        completedItemName: verbatim ? { singular: 'page', plural: 'pages' } : { singular: 'text', plural: 'texts' },
     });
 }
 function summarizeCaptured(captured) {
@@ -173,7 +177,9 @@ export async function runKtxTextIngest(args, io, deps = {}) {
         return 1;
     }
     const project = await (deps.loadProject ?? loadKtxProject)({ projectDir: args.projectDir });
-    const memoryIngest = (deps.createMemoryIngest ?? defaultCreateMemoryIngest)(project);
+    const isVerbatim = args.verbatim === true;
+    const verbatimIngestor = isVerbatim ? (deps.createVerbatimIngestor ?? defaultCreateVerbatimIngestor)(project) : null;
+    const memoryIngest = isVerbatim ? null : (deps.createMemoryIngest ?? defaultCreateMemoryIngest)(project);
     const now = deps.now ?? (() => Date.now());
     const batchId = now();
     const state = initViewState(items.map((item) => makeTarget(item.label)));
@@ -182,7 +188,7 @@ export async function runKtxTextIngest(args, io, deps = {}) {
     const repainter = isTTY ? createRepainter(io) : null;
     const results = [];
     state.startedAt = now();
-    const paint = () => repainter?.paint(renderTextIngestView(state, true));
+    const paint = () => repainter?.paint(renderTextIngestView(state, true, isVerbatim));
     paint();
     let spinnerInterval = null;
     if (repainter) {
@@ -204,28 +210,50 @@ export async function runKtxTextIngest(args, io, deps = {}) {
             const target = targets[index];
             target.status = 'running';
             target.startedAt = now();
-            target.detailLine = 'capturing...';
+            target.detailLine = isVerbatim ? 'writing...' : 'capturing...';
             target.progressUpdatedAtMs = target.startedAt;
             paint();
             let runId = null;
             let result;
             try {
-                const ingestInput = {
-                    userId: args.userId,
-                    chatId: `cli-text-ingest-${batchId}-${index + 1}`,
-                    userMessage: `Ingest external text artifact ${artifactReference(item.label)} into ktx memory.`,
-                    assistantMessage: item.content.trim(),
-                    ...(args.connectionId ? { connectionId: args.connectionId } : {}),
-                    sourceType: 'external_ingest',
-                };
-                const ingest = await memoryIngest.ingest(ingestInput);
-                runId = ingest.runId;
-                await memoryIngest.waitForRun(runId);
-                const status = await memoryIngest.status(runId);
-                if (!status) {
-                    throw new Error(`Memory ingest run "${runId}" was not found.`);
+                if (verbatimIngestor) {
+                    const verbatimItem = {
+                        origin: item.origin,
+                        content: item.content,
+                        ...(args.connectionId ? { connectionId: args.connectionId } : {}),
+                    };
+                    const outcome = await verbatimIngestor.ingest(verbatimItem);
+                    result = {
+                        label: item.label,
+                        runId: null,
+                        status: 'done',
+                        captured: { wiki: [outcome.pageKey], sl: [], xrefs: [] },
+                        commitHash: outcome.commitHash,
+                        error: null,
+                    };
+                }
+                else {
+                    // memoryIngest is set whenever verbatim is off — they are mutually exclusive.
+                    if (!memoryIngest) {
+                        throw new Error('Memory ingest was not initialized.');
+                    }
+                    const ingestInput = {
+                        userId: args.userId,
+                        chatId: `cli-text-ingest-${batchId}-${index + 1}`,
+                        userMessage: `Ingest external text artifact ${artifactReference(item.label)} into ktx memory.`,
+                        assistantMessage: item.content.trim(),
+                        ...(args.connectionId ? { connectionId: args.connectionId } : {}),
+                        sourceType: 'external_ingest',
+                    };
+                    const ingest = await memoryIngest.ingest(ingestInput);
+                    runId = ingest.runId;
+                    await memoryIngest.waitForRun(runId);
+                    const status = await memoryIngest.status(runId);
+                    if (!status) {
+                        throw new Error(`Memory ingest run "${runId}" was not found.`);
+                    }
+                    result = resultFromStatus(item.label, status);
                 }
-                result = resultFromStatus(item.label, status);
             }
             catch (error) {
                 result = errorResult(item.label, runId, error);
@@ -254,17 +282,18 @@ export async function runKtxTextIngest(args, io, deps = {}) {
         writeJsonResult(args, results, io);
     }
     else if (repainter) {
-        repainter.paint(renderTextIngestView(state, true));
+        repainter.paint(renderTextIngestView(state, true, isVerbatim));
         writePlainFailures(results, io);
     }
     else {
-        io.stdout.write(renderTextIngestView(state, false));
+        io.stdout.write(renderTextIngestView(state, false, isVerbatim));
         writePlainFailures(results, io);
     }
     if (!args.json && results.length > 0) {
         const duration = state.totalElapsedMs > 0 ? ` in ${formatDuration(state.totalElapsedMs)}` : '';
         const outcome = results.some((result) => result.status === 'error') ? 'finished with failures' : 'finished';
-        io.stdout.write(`Text memory ingest ${outcome}${duration}.\n`);
+        const label = isVerbatim ? 'Verbatim ingest' : 'Text memory ingest';
+        io.stdout.write(`${label} ${outcome}${duration}.\n`);
     }
     return results.some((result) => result.status === 'error') ? 1 : 0;
 }

package/dist/verbatim-ingest.d.ts

@@ -0,0 +1,46 @@
+import type { KtxLlmRuntimePort } from './context/llm/runtime-port.js';
+import type { KtxLocalProject } from './context/project/project.js';
+import type { WikiFrontmatter } from './context/wiki/types.js';
+import type { KtxEmbeddingProvider } from './llm/types.js';
+export interface VerbatimIngestOrigin {
+    kind: 'file' | 'text' | 'stdin';
+    /** Present only for `kind: 'file'`; the resolved path the key basename is derived from. */
+    path?: string;
+}
+/** @internal */
+export declare function splitInputDocument(raw: string): {
+    frontmatter: Record<string, unknown>;
+    body: string;
+};
+/** @internal */
+export declare function deriveVerbatimPageKey(origin: VerbatimIngestOrigin, body: string): string;
+/** @internal */
+export declare function deriveDegradedSummary(body: string): string;
+/** @internal */
+export declare function buildVerbatimFrontmatter(input: {
+    inputFrontmatter: Record<string, unknown>;
+    summary: string;
+    tags: string[];
+    slRefs: string[];
+    connectionId?: string;
+}): WikiFrontmatter & Record<string, unknown>;
+export interface VerbatimIngestItem {
+    origin: VerbatimIngestOrigin;
+    content: string;
+    connectionId?: string;
+}
+export interface VerbatimIngestResult {
+    pageKey: string;
+    outcome: 'written' | 'unchanged';
+    connections: string[];
+    commitHash: string | null;
+}
+export interface VerbatimIngestorPort {
+    ingest(item: VerbatimIngestItem): Promise<VerbatimIngestResult>;
+}
+export interface CreateLocalProjectVerbatimIngestorDeps {
+    /** `undefined` ⇒ resolve from project config; `null` ⇒ force degraded (offline) metadata. */
+    llmRuntime?: KtxLlmRuntimePort | null;
+    embeddingProvider?: KtxEmbeddingProvider | null;
+}
+export declare function createLocalProjectVerbatimIngestor(project: KtxLocalProject, deps?: CreateLocalProjectVerbatimIngestorDeps): VerbatimIngestorPort;