@wrongstack/tools 0.309.0 → 0.310.0

package/dist/codebase-index/binary-frame.d.ts

@@ -8,26 +8,69 @@
  *  - `0x57` ('W') → binary frame: [magic] [uint32 BE length] [MessagePack]
  *  - anything else → the byte is part of a JSON text line terminated by `\n`
  *
- * Negotiation happens during the existing handshake:
- *  1. The server's `hello` frame includes `binarySupported: true` (always JSON)
- *  2. If the client supports binary, it sends `acceptsBinary: true` in its
- *     first authenticated request (still JSON, so the server can read it)
- *  3. Both sides switch to binary framing for all subsequent frames on that
- *     socket
+ * There is no negotiated mode switch — the receiver sniffs every frame's
+ * first byte (see `consume()` in project-server.ts and the client's unified
+ * reader), so JSON and binary frames interleave freely on one socket:
+ *  - the server's `hello` frame advertises `binarySupported: true` (always
+ *    JSON, so any client can read it);
+ *  - a client that wants binary simply sends binary frames
+ *    (opt-in via WRONGSTACK_INDEX_BINARY=1 — the benchmark showed NDJSON is
+ *    faster for this workload, so it stays the default);
+ *  - the server answers each request in that request's framing, and latches
+ *    outbound to binary once a client has sent any binary frame.
  *
- * Backward compatibility: if either side does not advertise binary support,
- * the connection stays on newline-delimited JSON. The protocolVersion + buildId
+ * Backward compatibility: a JSON-only client never sees a binary byte, and a
+ * binary client's frames are self-describing — the protocolVersion + buildId
  * handshake already prevents a binary build from talking to a JSON-only build
  * of a different version (the buildId changes when the compiled artifact
  * changes), so there is no protocol ambiguity in practice.
  */
 /** Magic byte that prefixes every binary frame. 'W' for WrongStack. */
 export declare const BINARY_FRAME_MAGIC = 87;
+/**
+ * Hard cap on one binary frame's declared payload length for the CLIENT
+ * reader (project-server-client.ts). A malformed or hostile peer could
+ * claim a 4 GiB frame and stall the reader; this bound is far above any
+ * legitimate IPC response.
+ *
+ * Direction split is deliberate, not an oversight: the server enforces a
+ * much tighter inbound cap (MAX_INBOUND_BINARY_FRAME_BYTES, 64 Mi) because
+ * requests are small by construction and readable before auth; the client
+ * accepts larger frames because server responses (search results, symbol
+ * graphs) are the big direction. The two constants are intentionally
+ * separate — do not "unify" them: raising the server's inbound ceiling to
+ * match would widen the unauthenticated write surface, and lowering the
+ * client's read ceiling to match would reject legitimate large responses.
+ * Both directions also cap JSON text frames at their own ceilings, so
+ * neither framing offers the larger write than the other on its side.
+ */
+export declare const MAX_BINARY_FRAME_BYTES: number;
+/**
+ * Cap on one INBOUND (client → server) binary frame. Requests are tiny (an
+ * op name plus a few arguments; the largest is an explicit reindex file
+ * list), and unlike responses this direction is readable before any auth
+ * check — a local client could otherwise declare a huge frame and make the
+ * server wait for and accumulate it. The check runs the moment the five-byte
+ * header is complete, so the connection is destroyed without ever buffering
+ * toward the declared length (bytes already delivered in the current socket
+ * chunk are freed with the destroyed connection). Matches the JSON request
+ * ceiling (PROJECT_INDEX_SERVER_MAX_FRAME_CHARS, 64 Mi) so neither framing
+ * offers a larger unauthenticated write than the other.
+ */
+export declare const MAX_INBOUND_BINARY_FRAME_BYTES: number;
 /** True if a byte stream begins with the binary-frame magic. */
 export declare function isBinaryFrame(firstByte: number): boolean;
 /**
  * Encode a message as a binary frame: [magic] [uint32 BE length] [MessagePack].
  * Returns a single Buffer ready to write to the socket.
+ *
+ * `undefined`-valued properties are stripped before encoding: MessagePack
+ * would encode them as `nil` (arriving as `null`), while the JSON framing
+ * drops them entirely — callers must not observe a different payload shape
+ * just because they negotiated binary. Plain objects are normalized
+ * recursively, and a small allowlist of well-known class instances is
+ * converted to deterministic JSON-framing shapes (see normalizeUndefined)
+ * so the same payload does not shape-shift between framings.
  */
 export declare function encodeBinaryFrame(message: unknown): Buffer;
 /**
@@ -38,6 +81,12 @@ export declare function decodeBinaryFrame(payload: Uint8Array): unknown;
 /**
  * Encode a message as a JSON text frame, terminated by `\n`.
  * This is the original wire format — kept for fallback and handshake.
+ *
+ * Parity invariant (bf-2): both framings deliver the SAME normalized tree.
+ * JSON.stringify alone silently loses Map/Set/Error/RegExp payloads (`{}`
+ * on the wire); routing through the shared normalizer makes a payload's
+ * delivered shape independent of which framing carried it. A client that
+ * negotiates binary — or fails to — sees identical data.
  */
 export declare function encodeJsonFrame(message: unknown): string;
 //# sourceMappingURL=binary-frame.d.ts.map

package/dist/codebase-index/codebase-incoming-calls-tool.d.ts

@@ -26,6 +26,12 @@ interface IncomingCallsOutput {
     symbol: string;
     calls: CallSite[];
     total: number;
+    /**
+     * True when the project server served a previous generation's cached
+     * answer during a refresh. Results are internally consistent but may lag
+     * the files currently being indexed.
+     */
+    stale?: boolean | undefined;
     /** Non-empty when the index blocked the query (not ready, indexing, failed). */
     indexStatus?: string | undefined;
     /** Advisory note when the symbol was not found in the index. */

package/dist/codebase-index/codebase-outgoing-calls-tool.d.ts

@@ -26,6 +26,12 @@ interface OutgoingCallsOutput {
     symbol: string;
     calls: CallSite[];
     total: number;
+    /**
+     * True when the project server served a previous generation's cached
+     * answer during a refresh. Results are internally consistent but may lag
+     * the files currently being indexed.
+     */
+    stale?: boolean | undefined;
     /** Non-empty when the index blocked the query (not ready, indexing, failed). */
     indexStatus?: string | undefined;
     /** Advisory note when the symbol was not found, or unresolved refs exist. */

package/dist/codebase-index/codebase-search-tool.d.ts

@@ -4,7 +4,7 @@
  * Usage: codebase-search({
  *   query: string,        // search terms
  *   kind?: string,       // class|function|interface|method|const|...
- *   lang?: string,       // ts|tsx|js|jsx|go|py|rs
+ *   lang?: string,       // ts|tsx|js|jsx|go|py|rs|java|ruby|… (derived from EXT_TO_LANG)
  *   file?: string,       // filter to a specific file path (substring match)
  *   limit?: number,      // max results (default 20, max 100)
  * })
@@ -16,12 +16,16 @@
  * slow this tool down but can never freeze the terminal.
  */
 import type { Tool } from '@wrongstack/core/types';
-import type { SearchResult } from './schema.js';
+import type { SearchResult, SymbolLang } from './schema.js';
 /**
- * Language ids the index understands. Single source for the `lang` enum here
- * and the `langs` validation in codebase-index-tool.ts.
+ * Language ids the index understands — DERIVED from `EXT_TO_LANG`
+ * (languages.ts), the same table that decides which files get indexed, so
+ * this enum can no longer drift from the indexer's actual coverage (~40
+ * languages, including java/ruby/php/swift/md/css/… that the old
+ * hand-maintained 9-item list silently rejected). Single source for the
+ * `lang` enum here and the `langs` validation in codebase-index-tool.ts.
  */
-export declare const INDEXABLE_LANG_IDS: readonly ['ts', 'tsx', 'js', 'jsx', 'go', 'py', 'rs', 'json', 'yaml'];
+export declare const INDEXABLE_LANG_IDS: readonly SymbolLang[];
 export declare const codebaseSearchTool: Tool<CodebaseSearchInput, CodebaseSearchOutput>;
 interface CodebaseSearchInput {
     query: string;
@@ -41,6 +45,12 @@ interface CodebaseSearchOutput {
     results: SearchResult[];
     total: number;
     query: string;
+    /**
+     * True when the project server served a previous generation's cached
+     * answer during a refresh. Results are internally consistent but may lag
+     * the files currently being indexed.
+     */
+    stale?: boolean | undefined;
     /** Non-empty when the index blocked the search (not ready, indexing, failed). */
     indexStatus?: string | undefined;
 }

package/dist/codebase-index/index-service.d.ts

@@ -11,7 +11,7 @@
  * run on one event loop, so a pooled connection is both safe and substantially
  * cheaper than re-running schema/FTS drift checks for every edited file.
  */
-import type { CallSite, CodeMapGraph, IndexResult, IndexStats } from './schema.js';
+import type { CodeMapGraph, IndexResult, IndexStats } from './schema.js';
 import type { CallRefsOpArgs, IndexOpArgs, SearchOpArgs, SearchOpResult, StatsOpArgs } from './worker-protocol.js';
 export interface ServiceHooks {
     signal?: AbortSignal | undefined;
@@ -33,24 +33,8 @@ export declare function fileGraphService(args: StatsOpArgs & {
 export declare function symbolGraphService(args: StatsOpArgs & {
     fileFilter: string;
 }): CodeMapGraph;
-/** Result of an incoming calls query. */
-export interface IncomingCallsResult {
-    calls: CallSite[];
-    symbolFound: boolean;
-    /** True when `file` was scoped but the name is ambiguous (other files define it too). */
-    ambiguous: boolean;
-    /** Total matching call sites before the limit was applied. */
-    totalMatches: number;
-}
-/** Result of an outgoing calls query. */
-export interface OutgoingCallsResult {
-    calls: CallSite[];
-    symbolFound: boolean;
-    /** Number of refs whose target could not be resolved (to_id IS NULL). */
-    unresolvedCount: number;
-    /** Total matching call sites before the limit was applied. */
-    totalMatches: number;
-}
+import type { IncomingCallsResult, OutgoingCallsResult } from './worker-protocol/contracts.js';
+export type { IncomingCallsResult, OutgoingCallsResult };
 /** Incoming call sites for a named symbol (who calls/uses this symbol?). */
 export declare function incomingCallsService(args: CallRefsOpArgs): IncomingCallsResult;
 /** Outgoing call sites for a named symbol (what does this symbol call/use?). */