@hasna/knowledge 0.2.7 → 0.2.9

package/src/cli.ts

@@ -10,7 +10,9 @@ import { getKnowledgeDbStats, migrateKnowledgeDb, openKnowledgeDb } from './know
 import { createArtifactStore } from './artifact-store';
 import { initializeWikiLayout } from './wiki-layout';
 import { ingestOpenFilesManifest } from './manifest-ingest';
+import { ingestSourceRef } from './source-ingest';
 import { consumeOpenFilesOutbox } from './outbox-consume';
+import { resolveOpenFilesSource } from './source-resolver';
 import { approvalStatus, assertS3ReadAllowed, assertWebSearchAllowed, createApprovalGate, recordAuditEvent, recordRedactionFindings, redactSecrets, resolveSafetyPolicy } from './safety';
 import pkg from '../package.json' with { type: 'json' };
 
@@ -49,6 +51,7 @@ interface Flags {
   tag?: string;
   format?: string;
   completions?: string;
+  purpose?: string;
   noColor?: boolean;
   scope?: string;
   olderThan?: number;
@@ -62,7 +65,7 @@ interface ParseResult {
   flags: Flags;
 }
 
-const COMMANDS = ['add', 'list', 'get', 'delete', 'update', 'archive', 'restore', 'upsert', 'untag', 'export', 'prune', 'dedupe', 'stats', 'paths', 'db', 'wiki', 'ingest', 'reindex', 'safety', 'help'];
+const COMMANDS = ['add', 'list', 'get', 'delete', 'update', 'archive', 'restore', 'upsert', 'untag', 'export', 'prune', 'dedupe', 'stats', 'paths', 'db', 'wiki', 'source', 'ingest', 'reindex', 'safety', 'help'];
 const COMMAND_ALIASES: Record<string, string> = {
   ls: 'list',
   rm: 'delete',
@@ -97,6 +100,7 @@ function parseArgs(argv: string[]): ParseResult {
       case '--tag': case '-t': flags.tag = argv[i + 1]; i += 1; break;
       case '--format': flags.format = argv[i + 1]; i += 1; break;
       case '--completions': flags.completions = argv[i + 1]; i += 1; break;
+      case '--purpose': flags.purpose = argv[i + 1]; i += 1; break;
       case '--no-color': flags.noColor = true; break;
       case '--scope': flags.scope = argv[i + 1]; i += 1; break;
       case '--older-than': flags.olderThan = Number(argv[i + 1]); i += 1; break;
@@ -165,7 +169,9 @@ Commands:
   paths                        Show resolved workspace/store paths
   db init|stats                Initialize or inspect local knowledge.db
   wiki init                    Initialize scalable wiki/schema/index/log artifacts
+  source resolve <source-ref>  Resolve read-only source content and citation evidence
   ingest manifest <file|s3://> Ingest an open-files manifest into knowledge.db
+  ingest source <source-ref>   Ingest a read-only source ref into knowledge.db
   reindex outbox <file|s3://>  Consume open-files change events and invalidate chunks
   safety status|check|approve|audit|redact
   help [command]               Show help
@@ -173,6 +179,7 @@ Commands:
 Global Options:
   --json                      Output JSON
   --store <path>              Override store path
+  --purpose <name>            Read-only source purpose (default: knowledge_answer)
   --scope local|global|project  Store scope (default: global ~/.hasna/apps/knowledge/)
   --no-color                  Disable color output
   --completions <shell>       Output completions for bash|zsh|fish
@@ -229,7 +236,8 @@ function printCommandHelp(command: string): void {
   if (command === 'paths') { console.log('Usage: open-knowledge paths [--scope local|global|project] [--json]'); return; }
   if (command === 'db') { console.log('Usage: open-knowledge db init|stats [--scope local|global|project] [--json]'); return; }
   if (command === 'wiki') { console.log('Usage: open-knowledge wiki init [--scope local|global|project] [--json]'); return; }
-  if (command === 'ingest') { console.log('Usage: open-knowledge ingest manifest <file|s3://bucket/key> [--scope local|global|project] [--json]'); return; }
+  if (command === 'source') { console.log('Usage: open-knowledge source resolve <source-ref> [--purpose knowledge_answer|knowledge_index] [--limit <n>] [--scope local|global|project] [--json]'); return; }
+  if (command === 'ingest') { console.log('Usage: open-knowledge ingest manifest <file|s3://bucket/key> | source <source-ref> [--purpose knowledge_index] [--scope local|global|project] [--json]'); return; }
   if (command === 'reindex') { console.log('Usage: open-knowledge reindex outbox <file|s3://bucket/key> [--scope local|global|project] [--json]'); return; }
   if (command === 'safety') { console.log('Usage: open-knowledge safety status|check|approve|audit|redact [args] [--scope local|global|project] [--json]'); return; }
   printGlobalHelp();
@@ -276,11 +284,11 @@ async function run(argv: string[]): Promise<void> {
   if (flags.completions) {
     const shell = flags.completions;
     if (shell === 'bash') {
-      console.log(`_open_knowledge() { local cur; cur="${"$"}{COMP_WORDS[COMP_CWORD]}"; COMPREPLY=($(compgen -W "add list get update archive restore upsert untag delete export prune dedupe stats paths db wiki ingest reindex safety help ls rm edit unarchive --json --yes --help --version --desc --page --limit --search --sort --id --store --title --content --url --tag --format --completions --no-color --scope --archived --include-archived" -- "$cur")); }; complete -F _open_knowledge open-knowledge`);
+      console.log(`_open_knowledge() { local cur; cur="${"$"}{COMP_WORDS[COMP_CWORD]}"; COMPREPLY=($(compgen -W "add list get update archive restore upsert untag delete export prune dedupe stats paths db wiki source ingest reindex safety help ls rm edit unarchive --json --yes --help --version --desc --page --limit --search --sort --id --store --title --content --url --tag --format --completions --purpose --no-color --scope --archived --include-archived" -- "$cur")); }; complete -F _open_knowledge open-knowledge`);
     } else if (shell === 'zsh') {
-      console.log(`#compdef open-knowledge\n_open_knowledge() { _arguments -C "1: :(add list get update archive restore upsert untag delete export prune dedupe stats paths db wiki ingest reindex safety help ls rm edit unarchive)" "(--json)--json" "(--yes)-y" "(--help)--help" "(--version)--version" "(--desc)--desc" "(--archived)--archived" "(--include-archived)--include-archived" "(-p --page)"{-p,--page}"[page number]:number:" "(-l --limit)"{-l,--limit}"[items per page]:number:" "(-s --search)"{-s,--search}"[search text]:text:" "(--sort)--sort"\{created,title\}:" "(--id)--id[item id]:id:" "(--store)--store[store path]:path:" "(--title)--title[new title]:" "(--content)--content[new content]:" "(--url)--url[source url]:" "(-t --tag)"{-t,--tag}"[tag]:tag:" "(--format)--format[json|jsonl]:" "(--completions)--completions[output completions]:shell:(bash zsh fish):" "(--no-color)--no-color[disable color]" "(--scope)--scope"\{local,global,project\}:" }; _open_knowledge`);
+      console.log(`#compdef open-knowledge\n_open_knowledge() { _arguments -C "1: :(add list get update archive restore upsert untag delete export prune dedupe stats paths db wiki source ingest reindex safety help ls rm edit unarchive)" "(--json)--json" "(--yes)-y" "(--help)--help" "(--version)--version" "(--desc)--desc" "(--archived)--archived" "(--include-archived)--include-archived" "(-p --page)"{-p,--page}"[page number]:number:" "(-l --limit)"{-l,--limit}"[items per page]:number:" "(-s --search)"{-s,--search}"[search text]:text:" "(--sort)--sort"\{created,title\}:" "(--id)--id[item id]:id:" "(--store)--store[store path]:path:" "(--title)--title[new title]:" "(--content)--content[new content]:" "(--url)--url[source url]:" "(-t --tag)"{-t,--tag}"[tag]:tag:" "(--format)--format[json|jsonl]:" "(--completions)--completions[output completions]:shell:(bash zsh fish):" "(--purpose)--purpose[purpose]:" "(--no-color)--no-color[disable color]" "(--scope)--scope"\{local,global,project\}:" }; _open_knowledge`);
     } else if (shell === 'fish') {
-      console.log(`complete -c open-knowledge -f; complete -c open-knowledge -a "add list get update archive restore upsert untag delete export prune dedupe stats paths db wiki ingest reindex safety help ls rm edit unarchive"; complete -c open-knowledge -l json; complete -c open-knowledge -l yes -s y; complete -c open-knowledge -l help -s h; complete -c open-knowledge -l version -s v; complete -c open-knowledge -l desc; complete -c open-knowledge -l archived; complete -c open-knowledge -l include-archived; complete -c open-knowledge -s p -l page; complete -c open-knowledge -s l -l limit; complete -c open-knowledge -s s -l search; complete -c open-knowledge -l sort; complete -c open-knowledge -l id; complete -c open-knowledge -l store; complete -c open-knowledge -l title; complete -c open-knowledge -l content; complete -c open-knowledge -l url; complete -c open-knowledge -s t -l tag; complete -c open-knowledge -l format; complete -c open-knowledge -l completions; complete -c open-knowledge -l no-color; complete -c open-knowledge -l scope -a "local global project"`);
+      console.log(`complete -c open-knowledge -f; complete -c open-knowledge -a "add list get update archive restore upsert untag delete export prune dedupe stats paths db wiki source ingest reindex safety help ls rm edit unarchive"; complete -c open-knowledge -l json; complete -c open-knowledge -l yes -s y; complete -c open-knowledge -l help -s h; complete -c open-knowledge -l version -s v; complete -c open-knowledge -l desc; complete -c open-knowledge -l archived; complete -c open-knowledge -l include-archived; complete -c open-knowledge -s p -l page; complete -c open-knowledge -s l -l limit; complete -c open-knowledge -s s -l search; complete -c open-knowledge -l sort; complete -c open-knowledge -l id; complete -c open-knowledge -l store; complete -c open-knowledge -l title; complete -c open-knowledge -l content; complete -c open-knowledge -l url; complete -c open-knowledge -s t -l tag; complete -c open-knowledge -l format; complete -c open-knowledge -l completions; complete -c open-knowledge -l purpose; complete -c open-knowledge -l no-color; complete -c open-knowledge -l scope -a "local global project"`);
     } else {
       throw new Error("Invalid --completions value. Use 'bash', 'zsh', or 'fish'.");
     }
@@ -476,24 +484,64 @@ async function run(argv: string[]): Promise<void> {
     }
   }
 
-  if (command === 'ingest') {
+  if (command === 'source') {
     const action = positional[1] ?? '';
-    if (action !== 'manifest') throw new Error("Invalid ingest action. Use 'manifest'.");
-    const input = positional[2];
-    if (!input) throw new Error('Usage: open-knowledge ingest manifest <file|s3://bucket/key>');
+    if (action !== 'resolve') throw new Error("Invalid source action. Use 'resolve'.");
+    const sourceRef = positional[2];
+    if (!sourceRef) throw new Error('Usage: open-knowledge source resolve <source-ref>');
     const resolvedWorkspace = ensureKnowledgeWorkspace(workspace.home);
     const config = readKnowledgeConfig(resolvedWorkspace.configPath);
     const safetyPolicy = resolveSafetyPolicy(config, resolvedWorkspace);
-    const result = await ingestOpenFilesManifest({
+    const result = await resolveOpenFilesSource({
       dbPath: resolvedWorkspace.knowledgeDbPath,
-      input,
-      config,
+      sourceRef,
+      purpose: flags.purpose,
+      limit: flags.limit,
       safetyPolicy,
     });
-    output({ ok: true, ...result, message: `Ingested ${result.items_seen} manifest item(s)` }, flags.json);
+    output({
+      ok: true,
+      ...result,
+      message: result.resolved
+        ? `Resolved ${result.source_ref} (${result.content.chunks_returned}/${result.content.chunks_total} chunks)`
+        : `Source not indexed: ${sourceRef}`,
+    }, flags.json);
     return;
   }
 
+  if (command === 'ingest') {
+    const action = positional[1] ?? '';
+    const resolvedWorkspace = ensureKnowledgeWorkspace(workspace.home);
+    const config = readKnowledgeConfig(resolvedWorkspace.configPath);
+    const safetyPolicy = resolveSafetyPolicy(config, resolvedWorkspace);
+    if (action === 'manifest') {
+      const input = positional[2];
+      if (!input) throw new Error('Usage: open-knowledge ingest manifest <file|s3://bucket/key>');
+      const result = await ingestOpenFilesManifest({
+        dbPath: resolvedWorkspace.knowledgeDbPath,
+        input,
+        config,
+        safetyPolicy,
+      });
+      output({ ok: true, ...result, message: `Ingested ${result.items_seen} manifest item(s)` }, flags.json);
+      return;
+    }
+    if (action === 'source') {
+      const sourceRef = positional[2];
+      if (!sourceRef) throw new Error('Usage: open-knowledge ingest source <source-ref>');
+      const result = await ingestSourceRef({
+        dbPath: resolvedWorkspace.knowledgeDbPath,
+        sourceRef,
+        purpose: flags.purpose,
+        config,
+        safetyPolicy,
+      });
+      output({ ok: true, ...result, message: `Ingested source ${result.source_ref} (${result.chunks_inserted} chunks)` }, flags.json);
+      return;
+    }
+    throw new Error("Invalid ingest action. Use 'manifest' or 'source'.");
+  }
+
   if (command === 'reindex') {
     const action = positional[1] ?? '';
     if (action !== 'outbox') throw new Error("Invalid reindex action. Use 'outbox'.");

package/src/manifest-ingest.ts

@@ -24,6 +24,17 @@ export interface ManifestIngestOptions {
   chunkOverlapChars?: number;
 }
 
+export interface ManifestItemsIngestOptions {
+  dbPath: string;
+  items: ManifestObject[];
+  sourceLabel: string;
+  readAction?: string;
+  safetyPolicy?: SafetyPolicy;
+  now?: Date;
+  maxChunkChars?: number;
+  chunkOverlapChars?: number;
+}
+
 export interface ManifestIngestResult {
   path: string;
   db_path: string;
@@ -36,7 +47,7 @@ export interface ManifestIngestResult {
   skipped: number;
 }
 
-type ManifestObject = Record<string, unknown>;
+export type ManifestObject = Record<string, unknown>;
 
 interface NormalizedManifestItem {
   raw: ManifestObject;
@@ -405,6 +416,23 @@ function insertChunks(db: Database, sourceRevisionId: string, item: NormalizedMa
 }
 
 export async function ingestOpenFilesManifest(options: ManifestIngestOptions): Promise<ManifestIngestResult> {
+  const now = options.now ?? new Date();
+  if (options.safetyPolicy) assertWriteAllowed(options.dbPath, options.safetyPolicy);
+  migrateKnowledgeDb(options.dbPath);
+  const text = await readManifestInput(options.input, options.config, options.safetyPolicy);
+  const items = parseManifestText(text);
+  return ingestOpenFilesManifestItems({
+    dbPath: options.dbPath,
+    items,
+    sourceLabel: options.input,
+    safetyPolicy: options.safetyPolicy,
+    now,
+    maxChunkChars: options.maxChunkChars,
+    chunkOverlapChars: options.chunkOverlapChars,
+  });
+}
+
+export async function ingestOpenFilesManifestItems(options: ManifestItemsIngestOptions): Promise<ManifestIngestResult> {
   const now = (options.now ?? new Date()).toISOString();
   const maxChunkChars = options.maxChunkChars ?? 4000;
   const chunkOverlapChars = options.chunkOverlapChars ?? 200;
@@ -413,8 +441,6 @@ export async function ingestOpenFilesManifest(options: ManifestIngestOptions): P
 
   if (options.safetyPolicy) assertWriteAllowed(options.dbPath, options.safetyPolicy);
   migrateKnowledgeDb(options.dbPath);
-  const text = await readManifestInput(options.input, options.config, options.safetyPolicy);
-  const items = parseManifestText(text);
   const db = openKnowledgeDb(options.dbPath);
   try {
     const result = db.transaction(() => {
@@ -426,13 +452,13 @@ export async function ingestOpenFilesManifest(options: ManifestIngestOptions): P
       let skipped = 0;
       recordAuditEvent(db, {
         event_type: 'source_read',
-        action: options.input.startsWith('s3://') ? 's3_manifest_read' : 'local_manifest_read',
-        target_uri: options.input,
+        action: options.readAction ?? (options.sourceLabel.startsWith('s3://') ? 's3_manifest_read' : 'local_manifest_read'),
+        target_uri: options.sourceLabel,
         decision: 'allow',
-        metadata: { items: items.length, read_only: true },
+        metadata: { items: options.items.length, read_only: true },
         created_at: now,
       });
-      for (const raw of items) {
+      for (const raw of options.items) {
         const item = normalizeManifestItem(raw, now);
         const sourceId = upsertSource(db, item, now);
         const revisionId = upsertRevision(db, sourceId, item, now);
@@ -450,13 +476,13 @@ export async function ingestOpenFilesManifest(options: ManifestIngestOptions): P
         action: 'knowledge_manifest_ingest',
         target_uri: options.dbPath,
         decision: 'allow',
-        metadata: { items: items.length, sources: seenSources.size, revisions: seenRevisions.size, chunks_inserted: chunksInserted, redactions },
+        metadata: { items: options.items.length, sources: seenSources.size, revisions: seenRevisions.size, chunks_inserted: chunksInserted, redactions },
         created_at: now,
       });
       return {
-        path: options.input,
+        path: options.sourceLabel,
         db_path: options.dbPath,
-        items_seen: items.length,
+        items_seen: options.items.length,
         sources_upserted: seenSources.size,
         revisions_upserted: seenRevisions.size,
         chunks_inserted: chunksInserted,

package/src/mcp.js

@@ -7,6 +7,8 @@ import pkg from '../package.json' with { type: 'json' };
 import { defaultStorePath, loadStore, saveStore, makeId, withLock } from './store.ts';
 import { ensureKnowledgeWorkspace, readKnowledgeConfig, resolveScopedWorkspace } from './workspace.ts';
 import { parseSourceRef } from './source-ref.ts';
+import { resolveOpenFilesSource } from './source-resolver.ts';
+import { resolveSafetyPolicy } from './safety.ts';
 
 const storePathField = z.string().optional().describe('Path to the JSON store file');
 const scopeField = z.enum(['local', 'global', 'project']).optional().describe('Workspace scope');
@@ -102,6 +104,29 @@ export function buildServer() {
     }
   });
 
+  registerTool(server, 'ok_resolve_source', 'Resolve source content', 'Resolve an indexed source ref through the read-only open-files boundary and return chunk citation evidence', {
+    source_ref: z.string().describe('Source reference URI, preferably open-files://...'),
+    purpose: z.string().optional().describe('Read-only purpose label, default knowledge_answer'),
+    limit: z.number().optional().describe('Maximum chunks to return, default 10'),
+    scope: scopeField,
+  }, async ({ source_ref, purpose, limit, scope }) => {
+    const workspace = ensureKnowledgeWorkspace(resolveScopedWorkspace(scope).home);
+    const config = readKnowledgeConfig(workspace.configPath);
+    const safetyPolicy = resolveSafetyPolicy(config, workspace);
+    try {
+      const result = await resolveOpenFilesSource({
+        dbPath: workspace.knowledgeDbPath,
+        sourceRef: source_ref,
+        purpose,
+        limit,
+        safetyPolicy,
+      });
+      return jsonText({ ok: true, ...result });
+    } catch (error) {
+      return errorText(error instanceof Error ? error.message : String(error));
+    }
+  });
+
   registerTool(server, 'ok_add', 'Add a knowledge item', 'Add a new item to the knowledge store', {
     title: z.string().describe('Item title'),
     content: z.string().describe('Item content/body'),

package/src/source-ingest.ts

@@ -0,0 +1,268 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { basename } from 'node:path';
+import { ingestOpenFilesManifestItems, type ManifestIngestResult, type ManifestObject } from './manifest-ingest';
+import { parseSourceRef, type SourceRef } from './source-ref';
+import { resolveOpenFilesSource } from './source-resolver';
+import type { KnowledgeConfig } from './workspace';
+import { assertS3ReadAllowed, assertWebSearchAllowed, type SafetyPolicy } from './safety';
+
+export interface SourceIngestOptions {
+  dbPath: string;
+  sourceRef: string;
+  purpose?: string;
+  config?: KnowledgeConfig;
+  safetyPolicy?: SafetyPolicy;
+  now?: Date;
+}
+
+export interface SourceIngestResult extends ManifestIngestResult {
+  source_ref: string;
+  content_source: 'catalog_chunks' | 'extracted_text_ref' | 'file' | 's3' | 'web';
+  read_only: true;
+  hash: string;
+}
+
+interface ResolvedText {
+  text: string;
+  contentSource: SourceIngestResult['content_source'];
+  title: string | null;
+  mime: string | null;
+  size: number | null;
+  hash: string | null;
+  revision: string | null;
+  extractedTextRef: string | null;
+  metadata: Record<string, unknown>;
+  permissions: Record<string, unknown>;
+}
+
+function sha256Text(text: string): string {
+  return `sha256:${createHash('sha256').update(text).digest('hex')}`;
+}
+
+function stripHtml(html: string): string {
+  return html
+    .replace(/<script[\s\S]*?<\/script>/gi, ' ')
+    .replace(/<style[\s\S]*?<\/style>/gi, ' ')
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/&nbsp;/g, ' ')
+    .replace(/&amp;/g, '&')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/\s+\n/g, '\n')
+    .replace(/\n\s+/g, '\n')
+    .replace(/[ \t]{2,}/g, ' ')
+    .trim();
+}
+
+async function readS3Text(uri: string, config?: KnowledgeConfig, safetyPolicy?: SafetyPolicy): Promise<string> {
+  const parsed = new URL(uri);
+  const bucket = parsed.hostname;
+  const key = decodeURIComponent(parsed.pathname.replace(/^\/+/, ''));
+  if (!bucket || !key) throw new Error(`Invalid S3 source URI: ${uri}`);
+  if (safetyPolicy) assertS3ReadAllowed(uri, safetyPolicy);
+  const [{ S3Client, GetObjectCommand }, { fromIni }] = await Promise.all([
+    import('@aws-sdk/client-s3'),
+    import('@aws-sdk/credential-providers'),
+  ]);
+  const s3Config = config?.storage.type === 's3' && config.storage.s3?.bucket === bucket ? config.storage.s3 : undefined;
+  const client = new S3Client({
+    region: s3Config?.region,
+    credentials: s3Config?.profile ? fromIni({ profile: s3Config.profile }) : undefined,
+    maxAttempts: s3Config?.max_attempts,
+  });
+  const response = await client.send(new GetObjectCommand({ Bucket: bucket, Key: key }));
+  if (!response.Body) return '';
+  return await response.Body.transformToString();
+}
+
+async function readWebText(uri: string, safetyPolicy?: SafetyPolicy): Promise<{ text: string; mime: string | null }> {
+  if (safetyPolicy) assertWebSearchAllowed(safetyPolicy);
+  const response = await fetch(uri, {
+    headers: {
+      accept: 'text/markdown,text/plain,text/html,application/json;q=0.8,*/*;q=0.5',
+      'user-agent': '@hasna/knowledge source-ingest',
+    },
+  });
+  if (!response.ok) throw new Error(`Web source read failed ${response.status}: ${uri}`);
+  const mime = response.headers.get('content-type');
+  const body = await response.text();
+  return { text: mime?.includes('html') ? stripHtml(body) : body, mime };
+}
+
+function titleForRef(parsed: SourceRef): string | null {
+  if (parsed.kind === 'file') return basename(parsed.path);
+  if (parsed.kind === 's3') return basename(parsed.key);
+  if (parsed.kind === 'web') return basename(new URL(parsed.url).pathname) || parsed.url;
+  return parsed.path ? basename(parsed.path) : parsed.id;
+}
+
+async function readDirectSourceText(parsed: SourceRef, config?: KnowledgeConfig, safetyPolicy?: SafetyPolicy): Promise<ResolvedText> {
+  if (parsed.kind === 'file') {
+    if (!existsSync(parsed.path)) throw new Error(`Source file not found: ${parsed.path}`);
+    const text = readFileSync(parsed.path, 'utf8');
+    return {
+      text,
+      contentSource: 'file',
+      title: titleForRef(parsed),
+      mime: 'text/plain',
+      size: text.length,
+      hash: sha256Text(text),
+      revision: null,
+      extractedTextRef: null,
+      metadata: { path: parsed.path },
+      permissions: { mode: 'read_only' },
+    };
+  }
+
+  if (parsed.kind === 's3') {
+    const text = await readS3Text(parsed.uri, config, safetyPolicy);
+    return {
+      text,
+      contentSource: 's3',
+      title: titleForRef(parsed),
+      mime: 'text/plain',
+      size: text.length,
+      hash: sha256Text(text),
+      revision: null,
+      extractedTextRef: null,
+      metadata: { bucket: parsed.bucket, key: parsed.key },
+      permissions: { mode: 'read_only' },
+    };
+  }
+
+  if (parsed.kind === 'web') {
+    const web = await readWebText(parsed.url, safetyPolicy);
+    return {
+      text: web.text,
+      contentSource: 'web',
+      title: titleForRef(parsed),
+      mime: web.mime,
+      size: web.text.length,
+      hash: sha256Text(web.text),
+      revision: null,
+      extractedTextRef: null,
+      metadata: { url: parsed.url },
+      permissions: { mode: 'read_only' },
+    };
+  }
+
+  throw new Error(`Direct source reading is not available for ${parsed.uri}`);
+}
+
+async function readTextRef(uri: string, config?: KnowledgeConfig, safetyPolicy?: SafetyPolicy): Promise<{ text: string; contentSource: SourceIngestResult['content_source'] }> {
+  if (uri.startsWith('open-files://')) {
+    throw new Error('Open-files extracted text refs require an open-files resolver API. Ingest an open-files manifest with extracted_text or an extracted_text_ref using file://, s3://, or https://.');
+  }
+  const parsed = parseSourceRef(uri);
+  const direct = await readDirectSourceText(parsed, config, safetyPolicy);
+  return { text: direct.text, contentSource: 'extracted_text_ref' };
+}
+
+async function readOpenFilesSourceText(options: SourceIngestOptions): Promise<ResolvedText> {
+  const resolved = await resolveOpenFilesSource({
+    dbPath: options.dbPath,
+    sourceRef: options.sourceRef,
+    purpose: options.purpose ?? 'knowledge_index',
+    limit: 100,
+    safetyPolicy: options.safetyPolicy,
+    now: options.now,
+  });
+  if (!resolved.resolved) {
+    throw new Error('Open-files source is not in the local knowledge catalog. Ingest an open-files manifest first or use the open-files resolver API.');
+  }
+  if (resolved.revision?.extracted_text_uri && !resolved.content.text_available) {
+    const textRef = await readTextRef(resolved.revision.extracted_text_uri, options.config, options.safetyPolicy);
+    return {
+      text: textRef.text,
+      contentSource: textRef.contentSource,
+      title: resolved.source?.title ?? null,
+      mime: resolved.content.mime,
+      size: textRef.text.length,
+      hash: resolved.revision.hash ?? sha256Text(textRef.text),
+      revision: resolved.revision.revision,
+      extractedTextRef: resolved.revision.extracted_text_uri,
+      metadata: resolved.source?.metadata ?? {},
+      permissions: resolved.source?.permissions ?? { mode: 'read_only' },
+    };
+  }
+  if (resolved.chunks.length === 0) {
+    throw new Error('Open-files source has no extracted text chunks yet. Ingest an open-files manifest with extracted_text or extracted_text_ref first.');
+  }
+  const text = resolved.chunks.map((chunk) => chunk.text).join('\n\n');
+  return {
+    text,
+    contentSource: 'catalog_chunks',
+    title: resolved.source?.title ?? null,
+    mime: resolved.content.mime,
+    size: text.length,
+    hash: resolved.revision?.hash ?? sha256Text(text),
+    revision: resolved.revision?.revision ?? null,
+    extractedTextRef: resolved.revision?.extracted_text_uri ?? null,
+    metadata: resolved.source?.metadata ?? {},
+    permissions: resolved.source?.permissions ?? { mode: 'read_only' },
+  };
+}
+
+function manifestItemForSource(sourceRef: string, parsed: SourceRef, resolved: ResolvedText, purpose: string): ManifestObject {
+  const hash = resolved.hash ?? sha256Text(resolved.text);
+  const metadata = {
+    ...resolved.metadata,
+    source_ref: sourceRef,
+    content_source: resolved.contentSource,
+    read_only: true,
+  };
+  const item: ManifestObject = {
+    source_ref: sourceRef,
+    name: resolved.title ?? titleForRef(parsed),
+    mime: resolved.mime ?? 'text/plain',
+    size: resolved.size ?? resolved.text.length,
+    hash,
+    revision: resolved.revision ?? hash,
+    status: 'active',
+    updated_at: new Date().toISOString(),
+    permissions: {
+      mode: 'read_only',
+      allowed_purposes: [purpose],
+      ...resolved.permissions,
+    },
+    metadata,
+    extracted_text_ref: resolved.extractedTextRef,
+    extracted_text: resolved.text,
+  };
+  if (parsed.kind === 'open-files') {
+    if (parsed.entity === 'file') item.file_id = parsed.id;
+    if (parsed.entity === 'source') {
+      item.source_id = parsed.id;
+      item.path = parsed.path;
+    }
+  }
+  if (parsed.kind === 'file') item.path = parsed.path;
+  if (parsed.kind === 's3') item.path = parsed.key;
+  if (parsed.kind === 'web') item.url = parsed.url;
+  return item;
+}
+
+export async function ingestSourceRef(options: SourceIngestOptions): Promise<SourceIngestResult> {
+  const purpose = options.purpose ?? 'knowledge_index';
+  const parsed = parseSourceRef(options.sourceRef);
+  const resolved = parsed.kind === 'open-files'
+    ? await readOpenFilesSourceText(options)
+    : await readDirectSourceText(parsed, options.config, options.safetyPolicy);
+  const item = manifestItemForSource(options.sourceRef, parsed, resolved, purpose);
+  const result = await ingestOpenFilesManifestItems({
+    dbPath: options.dbPath,
+    items: [item],
+    sourceLabel: options.sourceRef,
+    readAction: 'source_ref_ingest_read',
+    safetyPolicy: options.safetyPolicy,
+    now: options.now,
+  });
+  return {
+    ...result,
+    source_ref: options.sourceRef,
+    content_source: resolved.contentSource,
+    read_only: true,
+    hash: String(item.hash),
+  };
+}

package/src/source-ref.ts

@@ -82,6 +82,18 @@ export function parseSourceRef(uri: string): SourceRef {
   throw new Error(`Unsupported source ref scheme: ${uri}`);
 }
 
+export function catalogSourceUriForRef(uri: string, parsed = parseSourceRef(uri)): string {
+  if (parsed.kind === 'open-files' && parsed.entity === 'file' && parsed.revision_id) {
+    return uri.replace(/\/revision\/[^/]+$/, '');
+  }
+  return uri;
+}
+
+export function revisionIdForSourceRef(uri: string): string | null {
+  const parsed = parseSourceRef(uri);
+  return parsed.kind === 'open-files' && parsed.entity === 'file' ? parsed.revision_id ?? null : null;
+}
+
 export function isSupportedSourceRef(uri: string): boolean {
   try {
     parseSourceRef(uri);