@hraness/wordcell 0.21.2 → 0.22.0

package/src/cli-program.ts

@@ -96,6 +96,14 @@ import {
   openKnowledgePortfolio,
   type PortfolioSearchResult,
 } from "./portfolio.js";
+import {
+  DEFAULT_PUBLISH_LIST_LIMIT,
+  MAX_PUBLISH_LIST_LIMIT,
+  publishVault,
+  renderPublishReportText,
+  type PublishSelectionInput,
+} from "./publish.js";
+import { serveSite } from "./serve.js";
 import {
   MAX_AUTHORIZED_VAULTS,
   loadPortfolioRegistry,
@@ -140,11 +148,14 @@ import {
   MAX_SEARCH_RELATED_SEEDS,
   MAX_SEARCH_RESULTS,
   openKnowledgeBase,
+  searchEvidenceRank,
   type KnowledgeBaseGraphOptions,
   type KnowledgeBaseSearchMode,
   type KnowledgeBaseSearchOrdering,
   type KnowledgeBaseSearchResult,
 } from "./sdk.js";
+import { MAX_RERANK_CANDIDATES, type SearchReranker } from "./rerank.js";
+import { createCliTypeSafeReranker } from "./rerank-credentials.js";
 import {
   refreshVault,
   scanVault,
@@ -215,7 +226,16 @@ async function loadSearchRulesFile(path: string): Promise<SearchRulesV1> {
   return parseSearchRules(input);
 }
 
-export const usage = `wordcell — auditable capture and derived links for Markdown vaults
+export const usage = `wordcell — a local knowledge base for coding agents
+
+Start here (no account or model needed):
+  wordcell init kb
+  wordcell note create notes/decision --title "A decision" --body "Keep retries bounded." --root kb
+  wordcell search "retries" --root kb --mode exact
+
+Already have Markdown? Search it with --root <your-notes-directory>.
+Use --mode exact for model-free search; optional hybrid search needs a local index.
+Quick start and examples: https://wordcell.io/docs
 
 Usage:
   wordcell init [directory] [--json]
@@ -243,12 +263,14 @@ Usage:
   wordcell percolate [note] [--proofs] [--root <directory>] [--min-support <count>] [--limit <count>] [--json]
   wordcell list [--root <directory>] [--where <path=value>] [--has <path>] [--tag <tag>] [--scope <repository-path>] [--sort <field>] [--order <asc|desc>] [--limit <count>] [--json]
   wordcell index [--root <directory>] [--database <path>] [--force] [--json]
-  wordcell search <query> [--root <directory>] [--repo <repository>] [--database <path>] [--mode <hybrid|exact|keyword|semantic>] [--rules <file>] [--priority] [--where <path=value>] [--has <path>] [--tag <tag>] [--scope <repository-path>] [--related <note>] [--graph-depth <1|2>] [--no-graph] [--history | --no-history | --require-history] [--limit <count>] [--candidate-limit <count>] [--min-score <score>] [--json]
+  wordcell search <query> [--root <directory>] [--repo <repository>] [--database <path>] [--mode <hybrid|exact|keyword|semantic>] [--rules <file>] [--priority] [--where <path=value>] [--has <path>] [--tag <tag>] [--scope <repository-path>] [--related <note>] [--graph-depth <1|2>] [--no-graph] [--history | --no-history | --require-history] [--limit <count>] [--candidate-limit <count>] [--min-score <score>] [--rerank <typesafe>] [--rerank-limit <2..25>] [--json]
   wordcell history <note> [--root <directory>] [--repo <repository>] [--limit <count>] [--cochanged-limit <count>] [--json]
   wordcell history search <query-or-path> [--root <directory>] [--repo <repository>] [--limit <count>] [--commit-limit <count>] [--cochanged-limit <count>] [--json]
   wordcell evaluate <manifest.json> [--root <directory>] [--repo <repository>] [--database <path>] [--retriever <id>] [--split <development|test|all>] [--limit <count>] [--cutoff <count>] [--timeout <milliseconds>] [--baseline <id>] [--model-file <path>] [--cache-state <cold|mixed|warm>] [--json]
   wordcell portfolio search <query> --registry <file> --workspace <directory> (--shared | --vault <owner/id>...) [--mode <hybrid|exact|keyword|semantic>] [--rules <file>] [--priority] [--limit <count>] [--require-all] [--json]
   wordcell portfolio audit --registry <file> --workspace <directory> (--all | --shared | --vault <owner/id>...) [--strict] [--json]
+  wordcell publish --out <directory> [--root <directory>] [--index <path>] [--include <path>]... [--exclude <path>]... [--include-glob <pattern>]... [--exclude-glob <pattern>]... [--where <path=value>]... [--has <path>]... [--tag <tag>]... [--scope <repository-path>]... [--from <note> [--depth <count>] [--direction <in|out|both>]] [--title <title>] [--description <text>] [--base-path <path>] [--base-url <url>] [--noindex] [--no-index-content] [--deterministic] [--dry-run] [--list-limit <0-1000>] [--force] [--json]
+  wordcell serve --root <directory> [--host <host>] [--port <port>] [--json]
   wordcell inbox [--root <directory>] [--source-prefix <directory>] [--limit <count>] [--json]
   wordcell context <repository-path> [--root <vault>] [--repo <repository>] [--kind <auto|file|directory>] [--json]
   wordcell agents identity <repository-scope> [--json]
@@ -256,6 +278,12 @@ Usage:
   wordcell agents audit [--root <vault>] [--repo <repository>] [--json]
   wordcell doctor [--json]
   wordcell adapters [--json]
+  wordcell support [--json | protocol --json | offer --json | shown <id> | release <id> | dismiss | snooze | enable | status --json]
+
+Optional support uses separate local preferences. HRANESS_SUPPORT=off or
+HRANESS_SUPPORT_AUDIENCE=off keeps invitations quiet; explicit support remains available.
+Agents receive discovery on stderr after useful standalone work. Human mode requires
+HRANESS_SUPPORT_AUDIENCE=human and an interactive stderr. No command signs up or pays.
 
 Run \`wordcell clip --help\` for web capture options or \`wordcell pdf --help\` for PDF conversion options.
 `;
@@ -353,6 +381,8 @@ type ParsedCommand =
       readonly limit?: number;
       readonly candidateLimit?: number;
       readonly minScore?: number;
+      readonly rerank?: "typesafe";
+      readonly rerankLimit?: number;
       readonly query: string;
       readonly json: boolean;
     }
@@ -440,6 +470,31 @@ type ParsedCommand =
       readonly minSupport: number;
       readonly limit: number;
       readonly json: boolean;
+    }
+  | {
+      readonly kind: "publish";
+      readonly root: string;
+      readonly out: string;
+      readonly index?: string;
+      readonly title?: string;
+      readonly description?: string;
+      readonly basePath?: string;
+      readonly baseUrl?: string;
+      readonly noindex: boolean;
+      readonly indexContent: boolean;
+      readonly deterministic: boolean;
+      readonly dryRun: boolean;
+      readonly listLimit: number;
+      readonly force: boolean;
+      readonly selection: PublishSelectionInput;
+      readonly json: boolean;
+    }
+  | {
+      readonly kind: "serve";
+      readonly root: string;
+      readonly host: string;
+      readonly port: number;
+      readonly json: boolean;
     };
 
 type ParseResult =
@@ -462,6 +517,8 @@ type CliDependencies = GraphCliDependencies & {
   readonly indexSemanticVault?: typeof indexSemanticVault;
   readonly openKnowledgeBase?: typeof openKnowledgeBase;
   readonly openKnowledgeBaseEvaluation?: typeof openKnowledgeBaseEvaluation;
+  /** Test seam; production wiring builds the TypeSafe reranker lazily per flag. */
+  readonly rerankers?: readonly SearchReranker[];
   readonly digestEvaluationModel?: (path: string) => Promise<string>;
   readonly evaluationNow?: () => Date;
   readonly createNote?: typeof createNote;
@@ -473,6 +530,8 @@ type CliDependencies = GraphCliDependencies & {
   readonly buildRepositoryMemoryContext?: typeof buildRepositoryMemoryContext;
   readonly auditAgentGuideRepository?: typeof auditAgentGuideRepository;
   readonly validateMarkdownAttachments?: typeof validateMarkdownAttachments;
+  readonly publishVault?: typeof publishVault;
+  readonly serveSite?: typeof serveSite;
 };
 
 function safe(value: string): string {
@@ -860,6 +919,195 @@ function parseListCommand(arguments_: readonly string[]): ParseResult {
   };
 }
 
+function parsePublishCommand(arguments_: readonly string[]): ParseResult {
+  let root = ".";
+  let out: string | undefined;
+  let index: string | undefined;
+  let title: string | undefined;
+  let description: string | undefined;
+  let basePath: string | undefined;
+  let baseUrl: string | undefined;
+  let noindex = false;
+  let indexContent = true;
+  let deterministic = false;
+  let dryRun = false;
+  let listLimit = DEFAULT_PUBLISH_LIST_LIMIT;
+  let force = false;
+  let json = false;
+  let from: string | undefined;
+  let depth = 1;
+  let direction: LinkDirection = "both";
+  const includes: string[] = [];
+  const excludes: string[] = [];
+  const includeGlobs: string[] = [];
+  const excludeGlobs: string[] = [];
+  const filters: MetadataFilter[] = [];
+  const tags: string[] = [];
+  const repositoryScopes: string[] = [];
+
+  for (let cursor = 0; cursor < arguments_.length; cursor += 1) {
+    const argument = arguments_[cursor];
+    if (argument === undefined) continue;
+    if (argument === "--json") { json = true; continue; }
+    if (argument === "--noindex") { noindex = true; continue; }
+    if (argument === "--no-index-content") { indexContent = false; continue; }
+    if (argument === "--deterministic") { deterministic = true; continue; }
+    if (argument === "--dry-run") { dryRun = true; continue; }
+    if (argument === "--force") { force = true; continue; }
+    if (
+      argument === "--root" || argument === "--out" || argument === "--index"
+      || argument === "--title" || argument === "--description"
+      || argument === "--base-path" || argument === "--base-url"
+      || argument === "--include" || argument === "--exclude"
+      || argument === "--include-glob" || argument === "--exclude-glob"
+      || argument === "--list-limit"
+      || argument === "--where" || argument === "--has" || argument === "--tag"
+      || argument === "--scope" || argument === "--repository-scope"
+      || argument === "--from" || argument === "--depth" || argument === "--direction"
+    ) {
+      const value = readValue(arguments_, cursor);
+      if (value === null) return { ok: false, message: `${argument} requires a value` };
+      if (argument === "--root") root = value;
+      else if (argument === "--out") out = value;
+      else if (argument === "--index") index = value;
+      else if (argument === "--title") title = value;
+      else if (argument === "--description") description = value;
+      else if (argument === "--base-path") basePath = value;
+      else if (argument === "--base-url") baseUrl = value;
+      else if (argument === "--include") includes.push(value);
+      else if (argument === "--exclude") excludes.push(value);
+      else if (argument === "--include-glob") includeGlobs.push(value);
+      else if (argument === "--exclude-glob") excludeGlobs.push(value);
+      else if (argument === "--list-limit") {
+        if (!/^(0|[1-9][0-9]*)$/u.test(value) || Number(value) > MAX_PUBLISH_LIST_LIMIT) {
+          return { ok: false, message: `--list-limit must be an integer from 0 through ${MAX_PUBLISH_LIST_LIMIT}` };
+        }
+        listLimit = Number(value);
+      }
+      else if (argument === "--from") from = value;
+      else if (argument === "--depth") {
+        const parsed = Number(value);
+        if (!Number.isSafeInteger(parsed) || parsed < 1 || parsed > 10) {
+          return { ok: false, message: "--depth must be an integer from 1 through 10" };
+        }
+        depth = parsed;
+      } else if (argument === "--direction") {
+        if (value !== "in" && value !== "out" && value !== "both") {
+          return { ok: false, message: "--direction must be in, out, or both" };
+        }
+        direction = value;
+      } else if (argument === "--tag") {
+        if (tags.length >= MAX_QUERY_TAGS) {
+          return { ok: false, message: `Query tags may contain at most ${MAX_QUERY_TAGS} entries.` };
+        }
+        tags.push(value);
+      } else if (argument === "--scope" || argument === "--repository-scope") {
+        if (repositoryScopes.length >= MAX_REPOSITORY_SCOPES) {
+          return { ok: false, message: `Repository scope filters may contain at most ${MAX_REPOSITORY_SCOPES} entries.` };
+        }
+        repositoryScopes.push(value);
+      } else if (argument === "--has") {
+        if (value.trim() === "") return { ok: false, message: "--has requires a metadata path" };
+        if (filters.length >= MAX_QUERY_FILTERS) {
+          return { ok: false, message: `Query filters may contain at most ${MAX_QUERY_FILTERS} entries.` };
+        }
+        filters.push({ kind: "exists", path: value });
+      } else {
+        const equals = value.indexOf("=");
+        const path = equals === -1 ? "" : value.slice(0, equals).trim();
+        if (path === "") return { ok: false, message: "--where requires path=value" };
+        const scalar = metadataScalar(value.slice(equals + 1));
+        if (!scalar.ok) return scalar;
+        if (filters.length >= MAX_QUERY_FILTERS) {
+          return { ok: false, message: `Query filters may contain at most ${MAX_QUERY_FILTERS} entries.` };
+        }
+        filters.push({ kind: "equals", path, value: scalar.value });
+      }
+      cursor += 1;
+      continue;
+    }
+    return {
+      ok: false,
+      message: argument.startsWith("--")
+        ? "unknown publish option"
+        : "publish does not accept positional arguments",
+    };
+  }
+
+  if (out === undefined) return { ok: false, message: "publish requires --out <directory>" };
+  try {
+    validateQueryOptions({ filters, tags, repositoryScopes });
+  } catch (error: unknown) {
+    return { ok: false, message: error instanceof Error ? error.message : String(error) };
+  }
+  const selection: PublishSelectionInput = {
+    includes,
+    excludes,
+    includeGlobs,
+    excludeGlobs,
+    filters,
+    tags,
+    repositoryScopes,
+    ...(from === undefined ? {} : { from: { note: from, depth, direction } }),
+  };
+  return {
+    ok: true,
+    value: {
+      kind: "publish",
+      root,
+      out,
+      noindex,
+      indexContent,
+      deterministic,
+      dryRun,
+      listLimit,
+      force,
+      selection,
+      json,
+      ...(index === undefined ? {} : { index }),
+      ...(title === undefined ? {} : { title }),
+      ...(description === undefined ? {} : { description }),
+      ...(basePath === undefined ? {} : { basePath }),
+      ...(baseUrl === undefined ? {} : { baseUrl }),
+    },
+  };
+}
+
+function parseServeCommand(arguments_: readonly string[]): ParseResult {
+  let root: string | undefined;
+  let host = "127.0.0.1";
+  let port = 8080;
+  let json = false;
+  for (let cursor = 0; cursor < arguments_.length; cursor += 1) {
+    const argument = arguments_[cursor];
+    if (argument === undefined) continue;
+    if (argument === "--json") { json = true; continue; }
+    if (argument === "--root" || argument === "--host" || argument === "--port") {
+      const value = readValue(arguments_, cursor);
+      if (value === null) return { ok: false, message: `${argument} requires a value` };
+      if (argument === "--root") root = value;
+      else if (argument === "--host") host = value;
+      else {
+        const parsed = Number(value);
+        if (!Number.isSafeInteger(parsed) || parsed < 0 || parsed > 65_535) {
+          return { ok: false, message: "--port must be an integer from 0 through 65535" };
+        }
+        port = parsed;
+      }
+      cursor += 1;
+      continue;
+    }
+    return {
+      ok: false,
+      message: argument.startsWith("--")
+        ? "unknown serve option"
+        : "serve does not accept positional arguments",
+    };
+  }
+  if (root === undefined) return { ok: false, message: "serve requires --root <directory>" };
+  return { ok: true, value: { kind: "serve", root, host, port, json } };
+}
+
 function parseInboxCommand(arguments_: readonly string[]): ParseResult {
   let root = ".";
   let index: string | undefined;
@@ -936,6 +1184,8 @@ function parseSemanticCommand(command: "index" | "search", arguments_: readonly
   let limit: number | undefined;
   let candidateLimit: number | undefined;
   let minScore: number | undefined;
+  let rerank: "typesafe" | undefined;
+  let rerankLimit: number | undefined;
   let graphDepth: number | undefined;
   let noGraph = false;
   let history = false;
@@ -997,6 +1247,8 @@ function parseSemanticCommand(command: "index" | "search", arguments_: readonly
       || argument === "--limit"
       || argument === "--candidate-limit"
       || argument === "--min-score"
+      || argument === "--rerank"
+      || argument === "--rerank-limit"
       || argument === "--where"
       || argument === "--has"
       || argument === "--tag"
@@ -1012,6 +1264,17 @@ function parseSemanticCommand(command: "index" | "search", arguments_: readonly
           return { ok: false, message: "--mode must be hybrid, exact, keyword, or semantic" };
         }
         mode = value;
+      } else if (argument === "--rerank") {
+        if (value !== "typesafe") {
+          return { ok: false, message: "--rerank must be typesafe" };
+        }
+        rerank = value;
+      } else if (argument === "--rerank-limit") {
+        const parsed = Number(value);
+        if (!Number.isSafeInteger(parsed) || parsed < 2 || parsed > MAX_RERANK_CANDIDATES) {
+          return { ok: false, message: `--rerank-limit must be an integer from 2 through ${MAX_RERANK_CANDIDATES}` };
+        }
+        rerankLimit = parsed;
       } else if (argument === "--where") {
         const equals = value.indexOf("=");
         const path = equals === -1 ? "" : value.slice(0, equals).trim();
@@ -1141,6 +1404,9 @@ function parseSemanticCommand(command: "index" | "search", arguments_: readonly
       message: "Search minimum score applies only to hybrid, keyword, or semantic mode.",
     };
   }
+  if (rerankLimit !== undefined && rerank === undefined) {
+    return { ok: false, message: "--rerank-limit requires --rerank typesafe" };
+  }
   if (priority && rulesPath === undefined) {
     return { ok: false, message: "--priority requires --rules" };
   }
@@ -1179,6 +1445,8 @@ function parseSemanticCommand(command: "index" | "search", arguments_: readonly
       ...(limit === undefined ? {} : { limit }),
       ...(candidateLimit === undefined ? {} : { candidateLimit }),
       ...(minScore === undefined ? {} : { minScore }),
+      ...(rerank === undefined ? {} : { rerank }),
+      ...(rerankLimit === undefined ? {} : { rerankLimit }),
       query,
       json,
     },
@@ -1932,6 +2200,8 @@ export function parseArguments(arguments_: readonly string[]): ParseResult {
   if (command === "note") return parseNoteCommand(arguments_.slice(1));
   if (command === "relation") return parseRelationCommand(arguments_.slice(1));
   if (command === "percolate") return parsePercolateCommand(arguments_.slice(1));
+  if (command === "publish") return parsePublishCommand(arguments_.slice(1));
+  if (command === "serve") return parseServeCommand(arguments_.slice(1));
   return { ok: false, message: "unknown command" };
 }
 
@@ -1954,10 +2224,28 @@ function renderKnowledgeBaseSearch(result: KnowledgeBaseSearchResult): string {
   const lines = [
     `${result.mode[0]?.toLocaleUpperCase("en-US") ?? ""}${result.mode.slice(1)} results for “${safe(result.query)}” (${result.results.length})${result.partial ? " [partial]" : ""}`,
   ];
+  const rerankLane = result.diagnostics.lanes.find(({ lane }) => lane === "rerank");
+  if (rerankLane !== undefined) {
+    lines.push(
+      `  Rerank: typesafe over ${rerankLane.results} candidates (${rerankLane.status})`
+        + (rerankLane.message === undefined ? "" : ` — ${safe(rerankLane.message)}`),
+    );
+    const receipt = rerankLane.rerank;
+    if (receipt?.accounting !== undefined) {
+      const { attempted, candidates, completed, elapsedMs, usageComplete } = receipt.accounting;
+      lines.push(`  Rerank requests: ${attempted}/${candidates} attempted, ${completed} settled; ${elapsedMs.toFixed(0)} ms`
+        + (usageComplete ? "; usage complete" : "; usage incomplete, additional charges may be unknown"));
+      if (rerankLane.status !== "ready" && receipt.usage !== undefined) {
+        lines.push(`  Known rerank usage: ${receipt.usage.inputTokens ?? 0} input tokens, ${receipt.usage.outputTokens ?? 0} output tokens`);
+      }
+    }
+  }
   if (result.results.length === 0) lines.push("  None.");
   for (const hit of result.results) {
     const location = `${safe(hit.path)}${hit.line === undefined ? "" : `:${hit.line}`}`;
-    const evidence = hit.evidence.map((item) => `${item.kind}#${item.rank}`).join(", ");
+    const evidence = hit.evidence
+      .map((item) => `${item.kind}#${searchEvidenceRank(item)}`)
+      .join(", ");
     lines.push(`  ${hit.rank}. ${hit.score.toFixed(3)}  ${location} — ${safe(hit.title)} [${safe(evidence)}]`);
     if (hit.snippet !== "") lines.push(`    ${safe(hit.snippet)}`);
   }
@@ -1993,12 +2281,17 @@ async function runSemantic(
   const searchRules = command.rulesPath === undefined
     ? undefined
     : await loadSearchRulesFile(command.rulesPath);
-  const kb = await (dependencies.openKnowledgeBase ?? openKnowledgeBase)({
-    root: command.root,
-    repository: command.repository,
-    ...(command.database === undefined ? {} : { database: command.database }),
-    ...(searchRules === undefined ? {} : { searchRules }),
-  });
+  const kb = await (dependencies.openKnowledgeBase ?? openKnowledgeBase)(
+    {
+      root: command.root,
+      repository: command.repository,
+      ...(command.database === undefined ? {} : { database: command.database }),
+      ...(searchRules === undefined ? {} : { searchRules }),
+    },
+    ...(command.rerank === undefined
+      ? []
+      : [{ rerankers: dependencies.rerankers ?? [await createCliTypeSafeReranker()] }]),
+  );
   try {
     const result = await kb.search({
       query: command.query,
@@ -2014,6 +2307,12 @@ async function runSemantic(
         ? {}
         : { candidateLimit: command.candidateLimit }),
       ...(command.minScore === undefined ? {} : { minScore: command.minScore }),
+      ...(command.rerank === undefined ? {} : {
+        rerank: {
+          engine: command.rerank,
+          ...(command.rerankLimit === undefined ? {} : { limit: command.rerankLimit }),
+        },
+      }),
     });
     output.stdout(command.json
       ? terminalSafeJson(result)
@@ -2828,6 +3127,49 @@ async function runList(
   return 0;
 }
 
+async function runPublish(
+  command: Extract<ParsedCommand, { readonly kind: "publish" }>,
+  output: Output,
+  dependencies: CliDependencies,
+): Promise<number> {
+  const result = await (dependencies.publishVault ?? publishVault)({
+    root: command.root,
+    out: command.out,
+    noindex: command.noindex,
+    indexContent: command.indexContent,
+    deterministic: command.deterministic,
+    dryRun: command.dryRun,
+    listLimit: command.listLimit,
+    force: command.force,
+    selection: command.selection,
+    ...(command.index === undefined ? {} : { index: command.index }),
+    ...(command.title === undefined ? {} : { title: command.title }),
+    ...(command.description === undefined ? {} : { description: command.description }),
+    ...(command.basePath === undefined ? {} : { basePath: command.basePath }),
+    ...(command.baseUrl === undefined ? {} : { baseUrl: command.baseUrl }),
+  });
+  output.stdout(command.json
+    ? terminalSafeJson(result.report)
+    : sanitizeTerminalText(renderPublishReportText(result.report, command.dryRun)));
+  return 0;
+}
+
+async function runServe(
+  command: Extract<ParsedCommand, { readonly kind: "serve" }>,
+  output: Output,
+  dependencies: CliDependencies,
+): Promise<number> {
+  const site = await (dependencies.serveSite ?? serveSite)({
+    root: command.root,
+    host: command.host,
+    port: command.port,
+  });
+  output.stdout(command.json
+    ? terminalSafeJson({ root: site.root, host: site.host, port: site.port, url: site.url })
+    : `Serving ${safe(site.root)} at ${safe(site.url)}\n`);
+  return 0;
+}
+
 async function runCatalog(
   command: Extract<ParsedCommand, { readonly kind: "catalog" }>,
   output: Output,
@@ -3574,6 +3916,8 @@ export async function main(
     }
     if (command.kind === "percolate") return await runPercolate(command, output, dependencies);
     if (command.kind === "list") return await runList(command, output, dependencies);
+    if (command.kind === "publish") return await runPublish(command, output, dependencies);
+    if (command.kind === "serve") return await runServe(command, output, dependencies);
     if (command.kind === "inbox") return await runInbox(command, output, dependencies);
     if (command.kind === "catalog") return await runCatalog(command, output, dependencies);
     return await runVault(command, output, dependencies);

package/src/cli.ts

@@ -3,4 +3,15 @@ import { runExecutable } from "./cli-program.js";
 
 export * from "./cli-program.js";
 
-if (import.meta.main) process.exitCode = await runExecutable();
+if (import.meta.main) {
+  const { standaloneSupportEnvironment, isUsefulSupportResult, runProductSupportCommand, showProductSupportInvitation } = await import("./support.js");
+  const env = standaloneSupportEnvironment();
+  const args = process.argv.slice(2);
+  if (args[0] === "support") {
+    process.exitCode = await runProductSupportCommand(args.slice(1), { env });
+  } else {
+    const exitCode = await runExecutable(args);
+    process.exitCode = exitCode;
+    if (exitCode === 0 && isUsefulSupportResult(args, env)) await showProductSupportInvitation({ env });
+  }
+}

package/src/clip/acquire.ts

@@ -146,6 +146,8 @@ async function runCommand(
   stdin?: string,
 ): Promise<CommandResult> {
   const child = Bun.spawn([...command], {
+    // Bun otherwise inherits its launch-time environment instead of current CLI preferences.
+    env: process.env,
     stdin: stdin === undefined ? "ignore" : new Blob([stdin]),
     stdout: "pipe",
     stderr: "pipe",

package/src/clip/doctor.ts

@@ -172,6 +172,8 @@ async function readBoundedStream(stream: ReadableStream<Uint8Array>, maxBytes: n
 
 export const runDiagnosticCommand: DiagnosticCommandRunner = async (specification) => {
   const child = Bun.spawn([...specification.command], {
+    // Bun otherwise inherits its launch-time environment instead of current CLI preferences.
+    env: process.env,
     stdin: "ignore",
     stdout: "pipe",
     stderr: "pipe",

package/src/clip/media.ts

@@ -274,6 +274,8 @@ export const runMediaCommand: MediaCommandRunner = async (specification) => {
   if (executable === undefined) throw new Error("media command is empty");
   const useProcessGroup = process.platform !== "win32";
   const child = spawn(executable, specification.command.slice(1), {
+    // Bun otherwise inherits its launch-time environment instead of current CLI preferences.
+    env: process.env,
     ...(specification.cwd === undefined ? {} : { cwd: specification.cwd }),
     detached: useProcessGroup,
     stdio: ["pipe", "pipe", "pipe"],

package/src/index.ts

@@ -11,7 +11,11 @@ export * from "./init.js";
 export * from "./navigation.js";
 export * from "./oh-adoption.js";
 export * from "./percolate.js";
+export * from "./publish.js";
+export * from "./publish-model.js";
 export * from "./query.js";
+export * from "./rerank.js";
+export * from "./rerank-typesafe.js";
 export * from "./repository-memory.js";
 export * from "./search.js";
 export * from "./semantic.js";

package/src/oh/authority.ts

@@ -3,7 +3,7 @@ import { isProxy } from "node:util/types";
 import { canonicalJson, canonicalSha256, type KnowledgeGraphChangeV1, type KnowledgeGraphRecordV1 } from "@hraness/oh";
 import {
   createOhProjectionDatasetV1, createOhProjectionFactV1, createOhProjectionSnapshotV1,
-  evaluateOhProjectionV1, parseOhProjectionResultV1, type OhProjectionProofV1,
+  parseOhProjectionResultV1, type OhProjectionProofV1,
 } from "@hraness/oh/projection";
 import { createOhSqliteStoreAuthorityV1 } from "@hraness/oh/sqlite";
 import { createOhStoreProfileV1, OH_WORKING_STORE_PROFILE_V1, type OhStoreV1 } from "@hraness/oh/store";
@@ -11,6 +11,7 @@ import {
   GRAPH_LIMITS, GraphAuthorityError, type GraphAuthority, type GraphProof,
   type GraphQueryLimits, type GraphQueryRequest, type GraphQueryResult, type GraphSnapshot,
 } from "../graph-authority-model";
+import { evaluateOhProjectionWithFallbackV1, loadProjectionRustEngineV1 } from "./projection-rust";
 import { compileGraphProgram, normalizeGraphQueryRequest } from "./programs";
 import { GRAPH_EXTRACTOR_SHA256, GRAPH_MANIFEST_KEY, manifestGraphRecord, parseGraphSnapshot, sourceGraphRecord } from "./snapshot";
 import { deepFreeze, detachedData, exactKeys } from "./validation";
@@ -95,6 +96,7 @@ export async function openOhGraphAdapter(input: GraphSnapshot, options: OhGraphA
     const materialized = await selectedStore.snapshot({ maximumRecords: GRAPH_LIMITS.notes + 1 });
     if (canonicalJson(materialized.records) !== canonicalJson(expected)) throw new GraphAuthorityError("corrupt-cache", "Graph reconciliation did not retain exact source records.");
     const projectionSnapshot = createOhProjectionSnapshotV1({ ...materialized, spaceId });
+    const rustEngine = await loadProjectionRustEngineV1();
     const recordMap = new Map(records.map((record, index) => [record.key, { record, source: snapshot.records[index]! }]));
     const assertOpen = () => { if (closed) throw new GraphAuthorityError("closed", "The graph authority is closed."); };
     const assertCurrent = async () => {
@@ -141,10 +143,17 @@ export async function openOhGraphAdapter(input: GraphSnapshot, options: OhGraphA
       });
       try {
         const dataset = createOhProjectionDatasetV1({ extractorSha256: GRAPH_EXTRACTOR_SHA256, factPackId: "wordcell.graph-facts", factPackRevision: 1, facts, snapshot: projectionSnapshot });
-        const result = evaluateOhProjectionV1({ ...program, dataset, snapshot: projectionSnapshot, options: {
-          maximumDerivedTuples: limits.derivedTuples, maximumRounds: limits.rounds, maximumWorkUnits: limits.workUnits,
-          maximumProofDepth: limits.proofDepth, maximumProofNodes: limits.proofNodes, maximumTotalProofNodes: limits.totalProofNodes, maximumResultBytes: limits.resultBytes,
-        } });
+        const result = evaluateOhProjectionWithFallbackV1({
+          dataset,
+          engine: rustEngine,
+          rulePack: program.rulePack,
+          query: program.query,
+          snapshot: projectionSnapshot,
+          options: {
+            maximumDerivedTuples: limits.derivedTuples, maximumRounds: limits.rounds, maximumWorkUnits: limits.workUnits,
+            maximumProofDepth: limits.proofDepth, maximumProofNodes: limits.proofNodes, maximumTotalProofNodes: limits.totalProofNodes, maximumResultBytes: limits.resultBytes,
+          },
+        });
         if (parseOhProjectionResultV1(result, result.identity.projectionSha256) === null) throw new GraphAuthorityError("corrupt-cache", "Oh returned an invalid bounded projection result.");
         await assertCurrent();
         const proofBudget = { remaining: limits.resultBytes };