@octocodeai/octocode-tools-core 16.6.3 → 17.0.2

package/dist/oql/schemeText.d.ts

@@ -1,20 +1,20 @@
 export declare const OQL_SCHEMA_DOC: {
     readonly schema: "oql";
-    readonly description: "octocode search — typed read-only queries over code, files, symbols, repos, packages, history, artifacts, diffs, and graph evidence. Think source + answer type + filters + read/output options; use --explain for routing; follow next.* for pages, exact reads, materialization, or proof.";
+    readonly description: "octocode search — typed read-only queries over code, files, symbols, repos, packages, history, diffs, and graph evidence. Think source + answer type + filters + read/output options; use --explain for routing; follow next.* for pages, exact reads, materialization, or proof.";
     readonly activeTargets: readonly import("./types.js").OqlActiveTarget[];
     readonly reservedTargets: readonly import("./types.js").OqlReservedTarget[];
     readonly sourceGuide: {
-        readonly local: "from:{kind:\"local\",path:\"./src\"}; shorthand: search \"term\" ./src, search ./src --tree, search file.ts --op documentSymbols. Best for local code/content/files/tree/LSP/artifacts/diff.";
+        readonly local: "from:{kind:\"local\",path:\"./src\"}; shorthand: search \"term\" ./src, search ./src --tree, search file.ts --op documentSymbols. Best for local code/content/files/tree/LSP/diff.";
         readonly github: "from:{kind:\"github\",repo:\"owner/repo\",ref?}; shorthand: search \"term\" owner/repo, search owner/repo --tree, search owner/repo#123 --target pullRequests. GitHub code is indexed/default-branch scoped; materialize for AST/LSP/local proof.";
         readonly npm: "from:{kind:\"npm\"} with target:\"packages\"; shorthand: search zod --target packages. Use to resolve package metadata and source repo, then continue with GitHub or local/materialized proof.";
         readonly materialized: "from:{kind:\"materialized\",localPath:\"/abs/path\"} after target:\"materialize\", clone, or cache fetch. Use when a remote repo/subtree must behave like local code.";
     };
     readonly plainLanguage: {
         readonly source: "`from` = where to look: local path, GitHub repo, npm, or a materialized checkout.";
-        readonly answerType: "`target` = what kind of answer you want: code matches, file content, tree, files, symbols, repos, packages, PRs, commits, artifacts, diffs, research packets, graph proof, or materialization.";
+        readonly answerType: "`target` = what kind of answer you want: code matches, file content, tree, files, symbols, repos, packages, PRs, commits, diffs, research packets, graph proof, or materialization.";
         readonly filters: "`where` = match/filter conditions for code and file discovery only: text, regex, AST shape, file fields, and boolean combinations.";
         readonly readOptions: "`fetch` = what to read once you know the file/tree: exact content, compact content, symbol outline, ranges, match slices, or tree depth.";
-        readonly targetOptions: "`params` = options that belong to one answer type, such as LSP operation, PR number, package name, artifact mode, research intent, or graph proof.";
+        readonly targetOptions: "`params` = options that belong to one answer type, such as LSP operation, PR number, package name, research intent, or graph proof.";
         readonly output: "`view`, `select`, and `controls` = response shape, projected fields, search tuning, and cost limits.";
         readonly paging: "`page` + `itemsPerPage` page the target's primary result domain. For code search that may be matched files; per-file match paging uses `controls.search.matchPage` / `--match-page`.";
     };
@@ -29,11 +29,10 @@ export declare const OQL_SCHEMA_DOC: {
         readonly 'PR list or deep-read': "target:pullRequests (owner/repo#N)";
         readonly 'commit history': "target:commits (--since/--until)";
         readonly 'a diff': "target:diff ({prNumber} for a PR patch, {baseRef,headRef,path} for two refs)";
-        readonly 'inspect a binary/archive': "target:artifacts (--inspect/--list/--strings/--extract)";
         readonly 'dead-code / reachability sweep': "target:research, then upgrade with target:graph proof:\"lsp\"";
         readonly 'make a remote repo behave like local (AST/LSP/negation)': "target:materialize (or clone / cache fetch)";
     };
-    readonly agentBestPractices: readonly ["Start with cheap orientation: --tree, --search path, --view discovery, or --content-view symbols.", "Then narrow and read exact evidence: --match-string, --start-line/--end-line, --char-offset/--char-length, or --content-view exact.", "Use snippets as discovery only; make decisions from exact content, PR/commit metadata, or LSP/graph proof.", "For semantics, run documentSymbols first to get line anchors, then references/callers/hover with symbolName + lineHint.", "For GitHub zero rows / providerUnindexed, do NOT claim absence — follow evidenceSemantics.providerUnindexed (verify path with structure, then materialize a bounded path).", "Read evidence.answerReady, evidence.complete, diagnostics, pagination, and next.* before concluding."];
+    readonly agentBestPractices: readonly ["Start with cheap orientation: --tree, --search path, --view discovery, or --content-view symbols.", "Then narrow and read exact evidence: --match-string, --start-line/--end-line, --char-offset/--char-length, or --content-view none.", "Use snippets as discovery only; make decisions from exact content, PR/commit metadata, or LSP/graph proof.", "For semantics, run documentSymbols first to get line anchors, then references/callers/hover with symbolName + lineHint.", "For GitHub zero rows / providerUnindexed, do NOT claim absence — follow evidenceSemantics.providerUnindexed (verify path with structure, then materialize a bounded path).", "Read evidence.answerReady, evidence.complete, diagnostics, pagination, and next.* before concluding."];
     readonly quickStart: {
         readonly 'text search (local)': "search \"functionName\" ./src";
         readonly 'text search (GitHub)': "search \"functionName\" vercel/next.js";
@@ -42,9 +41,8 @@ export declare const OQL_SCHEMA_DOC: {
         readonly 'commit history (GitHub)': "search vercel/next.js/packages/next/src --target commits --since 2024-01-01T00:00:00Z";
         readonly 'browse a tree (local dir or owner/repo)': "search ./src --tree   |   search vercel/next.js --tree";
         readonly 'read a file (local or owner/repo/path)': "search ./src/index.ts   |   search vercel/next.js/packages/next/src/server/config.ts";
-        readonly 'read a remote file (exact)': "search vercel/next.js/README.md --content-view exact";
+        readonly 'read a remote file (exact)': "search vercel/next.js/README.md --content-view none";
         readonly 'semantics (local/materialized)': "search ./src/index.ts --op documentSymbols   |   search ./src/index.ts --op references --symbol runCLI --line 42";
-        readonly 'artifact inspect/list': "search app.tgz --target artifacts --list   |   search dist/server.node --target artifacts --inspect";
         readonly 'PR diff (GitHub)': "search vercel/next.js#123 --target diff   |   search vercel/next.js --target diff --pr 123";
         readonly 'two-ref / two-file diff': "search src/a.ts src/b.ts --target diff   |   search owner/repo --target diff --base-ref <sha> --head-ref <sha> --path <file>";
         readonly 'structural AST (local \u2014 needs full node shape)': "search --pattern \"function $NAME($$$ARGS) { $$$BODY }\" ./src --lang ts";
@@ -81,16 +79,16 @@ export declare const OQL_SCHEMA_DOC: {
         readonly target: string;
         readonly from: "{ kind:\"local\", path } | { kind:\"github\", repo?, owner?, ref? } | { kind:\"materialized\", localPath, source? } | { kind:\"npm\" } — local row.path is relative to from.path; the pre-filled next.fetch carries the resolved ABSOLUTE path, so follow it directly rather than re-joining paths yourself";
         readonly scope: "{ path?, language?, include?, exclude?, excludeDir?, hidden?, noIgnore?, minDepth?, maxDepth? } — minDepth/maxDepth bound directory recursion depth (0-64)";
-        readonly where: "filters for code/files only: text | regex | structural | field | all | any | not. To read a matched file slice, use fetch.content.match. For PR/commit/artifact text narrowing, use that target params hint.";
+        readonly where: "filters for code/files only: text | regex | structural | field | all | any | not. To read a matched file slice, use fetch.content.match. For PR/commit text narrowing, use that target params hint.";
         readonly materialize: "{ mode:\"never\"|\"auto\"|\"required\", strategy?:\"file\"|\"tree\"|\"subtree\"|\"repo\", allowFullRepo?, forceRefresh? }";
-        readonly fetch: "{ content?: { contentView:\"exact\"|\"compact\"|\"symbols\", fullContent?, match?:{text|regex,case?}, range?:{startLine?,endLine?,contextLines?}, charOffset?, charLength? }, tree?:{ maxDepth?, pattern?, includeSizes?, extensions?, filesOnly?, directoriesOnly?, sortBy?:\"name\"|\"size\"|\"time\"|\"extension\", reverse? } } — read options for known files/trees; fetch.content.fullContent:true returns the WHOLE file in one shot (lossless, no char-window paging); to read the region around a string, anchor with fetch.content.match (NOT a top-level where, which is code/files only)";
+        readonly fetch: "{ content?: { contentView:\"none\"|\"standard\"|\"symbols\", fullContent?, match?:{text|regex,case?}, range?:{startLine?,endLine?,contextLines?}, charOffset?, charLength? }, tree?:{ maxDepth?, pattern?, includeSizes?, extensions?, filesOnly?, directoriesOnly?, sortBy?:\"name\"|\"size\"|\"time\"|\"extension\", reverse? } } — read options for known files/trees; fetch.content.fullContent:true returns the WHOLE file in one shot (lossless, no char-window paging); to read the region around a string, anchor with fetch.content.match (NOT a top-level where, which is code/files only)";
         readonly params: "target options (validated by OQL for common fields and by the backing tool exhaustively) — see params hints below";
         readonly select: "string[] projection of result/continuation fields";
         readonly view: "discovery | paginated | detailed";
         readonly controls: "{ search?: { countLinesPerFile?, countMatchesPerFile?, onlyMatching?, unique?, countUnique?, contextLines?, invertMatch?, matchWindow?, matchContentLength?, maxMatchesPerFile?, matchPage?, sort?:\"relevance\"|\"matchCount\"|\"path\"|\"modified\"|\"accessed\"|\"created\"|\"size\"|\"name\", sortReverse?, rankingProfile?, debugRanking? }, budget?: { maxFiles?, maxCandidates?, maxBytes?, maxMaterializedBytes?, maxPlanNodes?, maxBooleanExpansion?, timeoutMs? } } — output/cost controls; sort values \"size\"/\"name\" apply to target:\"files\" only (lowered to localFindFiles sortBy), the rest are code-search sorts";
         readonly limit: "number — total result cap where supported. Prefer itemsPerPage for paged research/graph/file-history continuations.";
         readonly page: "number — top-level page number for OQL windowing/continuations";
-        readonly itemsPerPage: "number — page size for the target primary result domain. For code search this may be matched files, not individual matches; per-file match paging uses controls.search.matchPage. Per-target params expose backing-tool sub-pages only (filePage/commentPage/commitPage, entryPageNumber, scanOffset, etc.).";
+        readonly itemsPerPage: "number — page size for the target primary result domain. For code search this may be matched files, not individual matches; per-file match paging uses controls.search.matchPage. Per-target params expose backing-tool sub-pages only (filePage/commentPage/commitPage, etc.).";
         readonly explain: "boolean";
     };
     readonly params: {
@@ -99,7 +97,6 @@ export declare const OQL_SCHEMA_DOC: {
         readonly packages: "{ packageName?: string | keywords?: string[], mode?:\"lean\"|\"full\", page? } — backing tool npmSearch";
         readonly pullRequests: "{ state?:\"open\"|\"closed\"|\"merged\", author?, label?, keywordsToSearch?, prNumber?, reviewMode?, filePage?, commentPage?, commitPage?, limit?, page?, matchString?, matchScope?:\"body\"|\"title\"|\"comments\"|\"reviews\"|\"all\", content? } — backing tool ghHistoryResearch; matchString filters fetched PR title/body/comments/reviews per matchScope (default body), not a search-index query — no match → zeroMatches";
         readonly commits: "{ path?, branch?, since?, until?, includeDiff?, limit?, page?, filePage?, itemsPerPage?, matchString? } — backing tool ghHistoryResearch type:\"commits\"; matchString filters commit messages; repo/directory diffs page changed files per commit with filePage/itemsPerPage";
-        readonly artifacts: "{ mode:\"inspect\"|\"list\"|\"extract\"|\"decompress\"|\"strings\"|\"unpack\", minLength?, entryPageNumber?, scanOffset?, charOffset?, charLength?, matchString? } — localBinaryInspect. matchString filters text-producing modes (extract/decompress/strings) over the current fetched payload. For large strings dumps, follow next.search on data.localPath for lossless ripgrep paging; next.artifactContent (charOffset) = next inline text window; next.artifactStrings (scanOffset) = next binary scan window. extract/unpack/decompress → tree at data.localPath (next.structure/next.files).";
         readonly diff: "{ prNumber, files? } (PR patch via ghHistoryResearch) | { baseRef, headRef, path } (direct two-ref file diff via ghGetFileContent + local line diff); neither shape -> invalidQuery repair";
         readonly research: "{ goal?, intent?:\"general\"|\"reachability\"|\"dependencies\"|\"symbols\", facets?:(\"symbols\"|\"files\"|\"dependencies\"|\"relations\")[], mode?:\"plan\"|\"analyze\"|\"prove\", maxFiles? } — TWO-PHASE: page:1+itemsPerPage:1 → data.summary (full-scope counts) and may include a bounded first packet page; page:2+ → data.packets[] continuation pages (candidates w/ retainedBy edges + per-packet next.*). Always evidence:\"candidate\"/answerReady:false (normal). Follow the row's pre-filled next.graph (proof:\"lsp\", proofLimit-bounded) to upgrade a page to LSP-proven proofStatus.";
         readonly graph: "{ goal?, intent?:\"general\"|\"reachability\"|\"dependencies\"|\"symbols\", facets?:(…)[], mode?:\"plan\"|\"analyze\"|\"prove\", maxFiles?, subject?, subjectKind?, relation?, verdict?, direction?:\"incoming\"|\"outgoing\"|\"both\", proof?:\"none\"|\"lsp\", proofLimit?, includePackets?, includeFacts?, includeEdges? } — UPGRADE PATH: run a research row's pre-filled next.graph directly. proof:\"lsp\" sets per-row proofStatus: \"confirmed-by-lsp\" (refs=0 in bounded workspace; still inspect entrypoints/exports before deletion), \"conflicting-evidence\" (refs>0 → retained, check retainedBy), \"needs-framework-graph\" (maybe an entrypoint). answerReady:false is normal — follow next.* for more pages/proof.";
@@ -132,7 +129,7 @@ export declare const OQL_SCHEMA_DOC: {
         textCase: "smart";
         regexDialectLocal: "rust";
         regexCase: "smart";
-        contentView: "compact";
+        contentView: "standard";
         contentCharLength: number;
         matchContentLength: number;
         maxPlanNodes: number;

package/dist/oql/shorthand/predicates.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `where` predicate lowering for `octocode search`.
+ *
+ * Turns the flat shorthand flags (--pattern/--rule/--regex/text, plus the
+ * file-discovery field flags like --extension/--filename/--size-greater)
+ * into the canonical `Predicate` tree. Predicate precedence within a search
+ * term is pattern > rule > regex > text.
+ */
+import type { Predicate } from '../types.js';
+import type { SearchShorthand } from './types.js';
+export declare function buildPredicate(parts: SearchShorthand): {
+    where?: Predicate;
+} | {
+    error: string;
+};

package/dist/oql/shorthand/query-controls.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `controls`/`fetch`/`materialize`/`view` lowering for `octocode search`.
+ *
+ * These are the non-predicate parts of an OQL query: search-result shaping
+ * (counting, dedup, context, ranking), content/tree fetch instructions, the
+ * materialize policy, and the discovery/paginated/detailed view mode.
+ */
+import type { OqlInputQuery, QueryControls, QueryView } from '../types.js';
+import type { SearchShorthand } from './types.js';
+export declare function queryControls(parts: SearchShorthand): QueryControls | undefined;
+export declare function fetchInstructions(parts: SearchShorthand): OqlInputQuery['fetch'] | undefined;
+export declare function materializePolicy(parts: SearchShorthand): OqlInputQuery['materialize'] | undefined;
+export declare function resolveView(value: string | undefined): {
+    view?: QueryView;
+} | {
+    error: string;
+};
+export declare function hasContentFetch(parts: SearchShorthand): boolean;

package/dist/oql/shorthand/target-params.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `params` lowering for `octocode search` — target-specific parameter bags.
+ *
+ * Every active target (semantics, repositories, packages, pullRequests,
+ * commits, diff, research/graph) accepts its own flat `params`
+ * shape; this maps the shared shorthand flags onto each target's fields.
+ */
+import type { SearchShorthand } from './types.js';
+export declare function targetParams(parts: SearchShorthand): Record<string, unknown>;

package/dist/oql/shorthand/types.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Public shorthand input types for `octocode search`.
+ *
+ * `SearchShorthand` is the flat, CLI-flag-shaped bag of parts the shorthand
+ * lowering pipeline (see ../shorthand.ts) consumes; `ShorthandResult` is what
+ * it produces (either a lowered OQL input or a typed error).
+ */
+import type { OqlInputBatch, OqlInputQuery } from '../types.js';
+/** Corpus already classified by the caller (local path vs GitHub ref). */
+export type ShorthandCorpus = {
+    kind: 'local';
+    path: string;
+} | {
+    kind: 'github';
+    repo: string;
+    path?: string;
+    ref?: string;
+} | {
+    kind: 'npm';
+};
+export interface SearchShorthand {
+    target?: string;
+    view?: string;
+    contentView?: string;
+    search?: string;
+    /** literal text term (used when no pattern/rule/regex flag is set) */
+    text?: string;
+    /** regex pattern (rust dialect unless pcre2) */
+    regex?: string;
+    pcre2?: boolean;
+    /** structural AST pattern (requires lang) */
+    pattern?: string;
+    /** structural rule, already parsed from JSON (requires lang) */
+    rule?: unknown;
+    lang?: string;
+    corpus: ShorthandCorpus;
+    materialize?: 'never' | 'auto' | 'required';
+    branch?: string;
+    forceRefresh?: boolean;
+    limit?: number;
+    page?: number;
+    itemsPerPage?: number;
+    include?: string[];
+    exclude?: string[];
+    excludeDir?: string[];
+    extension?: string;
+    filename?: string;
+    pathPattern?: string;
+    hidden?: boolean;
+    noIgnore?: boolean;
+    minDepth?: number;
+    maxDepth?: number;
+    empty?: boolean;
+    modifiedWithin?: string;
+    modifiedBefore?: string;
+    accessedWithin?: string;
+    sizeGreater?: string;
+    sizeLess?: string;
+    permissions?: string;
+    executable?: boolean;
+    readable?: boolean;
+    writable?: boolean;
+    details?: boolean;
+    showModified?: boolean;
+    caseInsensitive?: boolean;
+    caseSensitive?: boolean;
+    wholeWord?: boolean;
+    fixedString?: boolean;
+    multiline?: boolean;
+    multilineDotall?: boolean;
+    filesOnly?: boolean;
+    directoriesOnly?: boolean;
+    filesWithoutMatch?: boolean;
+    entryType?: 'file' | 'directory';
+    countLinesPerFile?: boolean;
+    countMatchesPerFile?: boolean;
+    onlyMatching?: boolean;
+    unique?: boolean;
+    countUnique?: boolean;
+    contextLines?: number;
+    invertMatch?: boolean;
+    matchWindow?: number;
+    matchContentLength?: number;
+    maxMatchesPerFile?: number;
+    matchPage?: number;
+    maxFiles?: number;
+    sort?: string;
+    sortReverse?: boolean;
+    rankingProfile?: string;
+    debugRanking?: boolean;
+    matchString?: string;
+    matchRegex?: boolean;
+    matchCaseSensitive?: boolean;
+    startLine?: number;
+    endLine?: number;
+    charOffset?: number;
+    charLength?: number;
+    fullContent?: boolean;
+    tree?: boolean;
+    includeSizes?: boolean;
+    op?: string;
+    symbol?: string;
+    symbolKind?: string;
+    uri?: string;
+    line?: number;
+    order?: number;
+    orderDirection?: string;
+    depth?: number;
+    workspaceRoot?: string;
+    format?: string;
+    owner?: string;
+    topic?: string[];
+    stars?: string;
+    forks?: string;
+    goodFirstIssues?: string;
+    license?: string;
+    created?: string;
+    updated?: string;
+    closed?: string;
+    mergedAt?: string;
+    size?: string;
+    match?: string[];
+    archived?: boolean;
+    visibility?: string;
+    concise?: boolean;
+    state?: string;
+    author?: string;
+    label?: string;
+    prNumber?: number;
+    base?: string;
+    head?: string;
+    draft?: boolean;
+    commentsContent?: boolean;
+    commitsContent?: boolean;
+    deep?: boolean;
+    patchFile?: string;
+    reviewMode?: string;
+    filePage?: number;
+    commentPage?: number;
+    commitPage?: number;
+    since?: string;
+    until?: string;
+    patches?: boolean;
+    baseRef?: string;
+    headRef?: string;
+    diffPath?: string;
+    intent?: string;
+    facets?: string[];
+    proof?: string;
+    proofLimit?: number;
+    includePackets?: boolean;
+    includeFacts?: boolean;
+    includeEdges?: boolean;
+}
+export type ShorthandResult = {
+    input: OqlInputQuery | OqlInputBatch;
+} | {
+    error: string;
+};

package/dist/oql/shorthand/utils.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Small stateless helpers shared across the shorthand lowering builders.
+ */
+/** Drop `undefined` values so callers don't emit sparse-but-present keys. */
+export declare function clean(input: Record<string, unknown>): Record<string, unknown>;
+export declare function listFromComma(value: string): string[];
+export declare function isTreeSort(value: string | undefined): value is 'name' | 'size' | 'time' | 'extension';

package/dist/oql/shorthand.d.ts

@@ -1,174 +1,5 @@
-/**
- * Shorthand lowering for `octocode search`.
- *
- * The CLI reads argv and resolves a target string to a corpus (local path vs
- * GitHub ref — the only step that needs the filesystem). Everything else —
- * which predicate the flags select, dialect, lang requirements, and assembling
- * the sugar object the normalizer accepts — lives here so it is owned once in
- * tools-core (not re-implemented in the interface) and is unit-testable without
- * argv or a terminal.
- */
-import { type OqlInputBatch, type OqlInputQuery } from './types.js';
-/** Corpus already classified by the caller (local path vs GitHub ref). */
-export type ShorthandCorpus = {
-    kind: 'local';
-    path: string;
-} | {
-    kind: 'github';
-    repo: string;
-    path?: string;
-    ref?: string;
-} | {
-    kind: 'npm';
-};
-export interface SearchShorthand {
-    target?: string;
-    view?: string;
-    contentView?: string;
-    search?: string;
-    /** literal text term (used when no pattern/rule/regex flag is set) */
-    text?: string;
-    /** regex pattern (rust dialect unless pcre2) */
-    regex?: string;
-    pcre2?: boolean;
-    /** structural AST pattern (requires lang) */
-    pattern?: string;
-    /** structural rule, already parsed from JSON (requires lang) */
-    rule?: unknown;
-    lang?: string;
-    corpus: ShorthandCorpus;
-    materialize?: 'never' | 'auto' | 'required';
-    branch?: string;
-    forceRefresh?: boolean;
-    limit?: number;
-    page?: number;
-    itemsPerPage?: number;
-    include?: string[];
-    exclude?: string[];
-    excludeDir?: string[];
-    extension?: string;
-    filename?: string;
-    pathPattern?: string;
-    hidden?: boolean;
-    noIgnore?: boolean;
-    minDepth?: number;
-    maxDepth?: number;
-    empty?: boolean;
-    modifiedWithin?: string;
-    modifiedBefore?: string;
-    accessedWithin?: string;
-    sizeGreater?: string;
-    sizeLess?: string;
-    permissions?: string;
-    executable?: boolean;
-    readable?: boolean;
-    writable?: boolean;
-    details?: boolean;
-    showModified?: boolean;
-    caseInsensitive?: boolean;
-    caseSensitive?: boolean;
-    wholeWord?: boolean;
-    fixedString?: boolean;
-    multiline?: boolean;
-    multilineDotall?: boolean;
-    filesOnly?: boolean;
-    directoriesOnly?: boolean;
-    filesWithoutMatch?: boolean;
-    entryType?: 'file' | 'directory';
-    countLinesPerFile?: boolean;
-    countMatchesPerFile?: boolean;
-    onlyMatching?: boolean;
-    unique?: boolean;
-    countUnique?: boolean;
-    contextLines?: number;
-    invertMatch?: boolean;
-    matchWindow?: number;
-    matchContentLength?: number;
-    maxMatchesPerFile?: number;
-    matchPage?: number;
-    maxFiles?: number;
-    sort?: string;
-    sortReverse?: boolean;
-    rankingProfile?: string;
-    debugRanking?: boolean;
-    matchString?: string;
-    matchRegex?: boolean;
-    matchCaseSensitive?: boolean;
-    startLine?: number;
-    endLine?: number;
-    charOffset?: number;
-    charLength?: number;
-    fullContent?: boolean;
-    tree?: boolean;
-    includeSizes?: boolean;
-    op?: string;
-    symbol?: string;
-    symbolKind?: string;
-    uri?: string;
-    line?: number;
-    order?: number;
-    orderDirection?: string;
-    depth?: number;
-    workspaceRoot?: string;
-    format?: string;
-    owner?: string;
-    topic?: string[];
-    stars?: string;
-    forks?: string;
-    goodFirstIssues?: string;
-    license?: string;
-    created?: string;
-    updated?: string;
-    closed?: string;
-    mergedAt?: string;
-    size?: string;
-    match?: string[];
-    archived?: boolean;
-    visibility?: string;
-    concise?: boolean;
-    state?: string;
-    author?: string;
-    label?: string;
-    prNumber?: number;
-    base?: string;
-    head?: string;
-    draft?: boolean;
-    commentsContent?: boolean;
-    commitsContent?: boolean;
-    deep?: boolean;
-    patchFile?: string;
-    reviewMode?: string;
-    filePage?: number;
-    commentPage?: number;
-    commitPage?: number;
-    since?: string;
-    until?: string;
-    patches?: boolean;
-    baseRef?: string;
-    headRef?: string;
-    diffPath?: string;
-    artifactMode?: string;
-    detailed?: boolean;
-    verbose?: boolean;
-    maxEntries?: number;
-    minLength?: number;
-    entryPageNumber?: number;
-    scanOffset?: number;
-    includeOffsets?: boolean;
-    archiveFile?: string;
-    intent?: string;
-    facets?: string[];
-    proof?: string;
-    proofLimit?: number;
-    includePackets?: boolean;
-    includeFacts?: boolean;
-    includeEdges?: boolean;
-}
-export type ShorthandResult = {
-    input: OqlInputQuery | OqlInputBatch;
-} | {
-    error: string;
-};
+import type { SearchShorthand, ShorthandCorpus, ShorthandResult } from './shorthand/types.js';
+export type { SearchShorthand, ShorthandCorpus, ShorthandResult };
 /**
  * Lower shorthand parts into the OQL sugar object. Predicate precedence:
  * pattern > rule > regex > text. Returns a typed error for invalid combos

package/dist/oql/targetParams.d.ts

@@ -1,17 +1,4 @@
-/**
- * Typed target-specific `params` schemas.
- *
- * Research targets (semantics/repositories/packages/pullRequests/commits/
- * artifacts/diff/research/graph) carry a `params` bag that the backing tool validates
- * exhaustively. These schemas type the documented common fields so a type
- * mistake (e.g. `prNumber:"abc"`) is caught at the OQL layer with a clear
- * `invalidQuery` instead of failing opaquely at the tool, while `.passthrough()`
- * keeps the backing tool the source of truth for the rest.
- */
-import { z } from 'zod';
 import type { OqlActiveTarget } from './types.js';
-/** Per-target params schema; targets without a `params` bag are absent. */
-export declare const TARGET_PARAM_SCHEMAS: Partial<Record<OqlActiveTarget, z.ZodTypeAny>>;
 /**
  * Validate a target's `params` bag against its typed schema. Returns `null` when
  * valid (or no schema applies), or a Zod-style error message string the caller

package/dist/oql/transformers/github/code.d.ts

@@ -1,4 +1,4 @@
-import type { OqlQuery, Predicate } from '../../types.js';
+import type { OqlQuery } from '../../types.js';
 import type { TransformResult } from '../types.js';
 export type GithubCodeSearchToolQuery = Record<string, unknown>;
 export type GithubCodeSearchTransformOptions = {
@@ -6,12 +6,4 @@ export type GithubCodeSearchTransformOptions = {
     unsupportedMessage?: string;
     unsupportedBackend?: string;
 };
-/**
- * Path-like field predicates (`basename`/`extension`/`path` with op `=`) map
- * directly onto GitHub code-search path qualifiers — the same provider route
- * OQL target:"files" uses. Returns the ghSearchCode param
- * fragment, or `null` if the predicate is not a provider-expressible path-field
- * equality (those still require materialization, per the planner files lane).
- */
-export declare function githubPathFieldParams(where: Predicate): GithubCodeSearchToolQuery | null;
 export declare function toGithubCodeSearchToolQuery(query: OqlQuery, options?: GithubCodeSearchTransformOptions): TransformResult<GithubCodeSearchToolQuery>;

package/dist/oql/types/diagnostics.d.ts

@@ -0,0 +1,22 @@
+/**
+ * OQL diagnostics — the coded, severity-ranked notices the planner/runner
+ * attach to a result envelope (unsupported predicates, truncation, auth,
+ * etc.), each optionally carrying a repair suggestion or continuation.
+ */
+import type { OqlSearchInput } from './query.js';
+import type { OqlContinuation } from './envelope.js';
+export type DiagnosticCode = 'invalidQuery' | 'ambiguousSugar' | 'unknownField' | 'unsupportedTarget' | 'unsupportedPredicate' | 'unsupportedBoolean' | 'unsupportedScope' | 'negativeUniverseRequired' | 'residualNotExact' | 'fieldTypeMismatch' | 'requiresMaterialization' | 'vendorNoEquivalent' | 'lossyTransform' | 'unsupportedVendorPredicate' | 'responseShapeMismatch' | 'materializationNotAllowed' | 'materializationFailed' | 'providerUnindexed' | 'providerSemanticsApproximate' | 'partialResult' | 'contentTruncated' | 'matchTruncated' | 'planTruncated' | 'budgetExhausted' | 'parserFailed' | 'partialParse' | 'signatureUnsupported' | 'lspUnavailable' | 'staleCache' | 'sanitized' | 'rateLimited' | 'authRequired' | 'zeroMatches' | 'symbolNotFound';
+export interface OqlDiagnostic {
+    code: DiagnosticCode;
+    severity: 'info' | 'warning' | 'error';
+    queryPath?: string;
+    predicateId?: string;
+    backend?: string;
+    message: string;
+    blocksAnswer: boolean;
+    repair?: {
+        message: string;
+        suggestedQuery?: OqlSearchInput;
+    };
+    continuation?: OqlContinuation;
+}

package/dist/oql/types/envelope.d.ts

@@ -0,0 +1,78 @@
+/**
+ * OQL result envelope — pagination, provenance, continuations, and the
+ * top-level `OqlResultEnvelope`/`OqlBatchResultEnvelope` shapes `runOqlSearch`
+ * returns.
+ */
+import type { QuerySource } from './predicates.js';
+import type { OqlCanonicalInput } from './query.js';
+import type { OqlDiagnostic } from './diagnostics.js';
+import type { OqlExplainPlan } from './planner.js';
+import type { OqlProofGradedResultRow } from './recordRows.js';
+export interface Pagination {
+    currentPage?: number;
+    totalPages?: number;
+    nextPage?: number;
+    itemsPerPage?: number;
+    totalItems?: number;
+    reportedTotalItems?: number;
+    reachableTotalItems?: number;
+    totalItemsKind?: string;
+    itemUnit?: string;
+    rowCount?: number;
+    reportedRowCount?: number;
+    totalItemsCapped?: boolean;
+    uniqueFileCount?: number;
+    hasMore: boolean;
+    next?: OqlContinuation;
+}
+export interface OqlProvenance {
+    backend: string;
+    source?: QuerySource;
+    predicateIds?: string[];
+    pushed?: string[];
+    residual?: string[];
+    routed?: string[];
+    materializedPath?: string;
+    cache?: 'hit' | 'miss' | 'refresh' | 'stale';
+}
+export interface OqlContinuation {
+    query: OqlCanonicalInput;
+    baseQueryId?: string;
+    queryIndex?: number;
+    why?: string;
+    confidence?: 'exact' | 'heuristic';
+}
+export interface OqlContinuationHint {
+    why: string;
+    confidence: 'exact' | 'heuristic';
+}
+export type EvidenceKind = 'proof' | 'partial' | 'candidate' | 'unsupported';
+export interface OqlResultEnvelope {
+    queryId?: string;
+    queryIndex?: number;
+    results: OqlProofGradedResultRow[];
+    shared?: Record<string, unknown>;
+    pagination?: Pagination;
+    next?: Record<string, OqlContinuation>;
+    nextHints?: Record<string, OqlContinuationHint>;
+    diagnostics: OqlDiagnostic[];
+    provenance: OqlProvenance[];
+    evidence: {
+        answerReady: boolean;
+        complete: boolean;
+        kind: EvidenceKind;
+    };
+    plan?: OqlExplainPlan;
+}
+export interface OqlBatchResultEnvelope {
+    batchId?: string;
+    mode: 'independent' | 'merge';
+    children: Array<{
+        queryId: string;
+        queryIndex: number;
+        envelope: OqlResultEnvelope;
+    }>;
+    merged?: OqlResultEnvelope;
+    diagnostics: OqlDiagnostic[];
+}
+export type OqlRunResult = OqlResultEnvelope | OqlBatchResultEnvelope;

package/dist/oql/types/guards.d.ts

@@ -0,0 +1,9 @@
+/**
+ * OQL type guards — runtime discriminators for the input/output union types
+ * (single query vs batch, single envelope vs batch envelope).
+ */
+import type { OqlBatch, OqlCanonicalInput, OqlInputBatch, OqlSearchInput } from './query.js';
+import type { OqlBatchResultEnvelope, OqlRunResult } from './envelope.js';
+export declare function isBatchInput(input: OqlSearchInput): input is OqlInputBatch;
+export declare function isCanonicalBatch(input: OqlCanonicalInput): input is OqlBatch;
+export declare function isBatchEnvelope(result: OqlRunResult): result is OqlBatchResultEnvelope;