pi-ghost-autocomplete 0.3.1 → 0.4.0

package/dist/intent.d.ts

@@ -0,0 +1,179 @@
+/**
+ * SPDX-License-Identifier: SSPL-1.0
+ * SPDX-FileCopyrightText: 2025 Alessandro Pungitore <alessandro@pungitore.ch>
+ */
+/**
+ * Intent detection for ghost autocompletion.
+ *
+ * Centralises all prose / path / filename heuristics so they can be shared
+ * between the deterministic fast-path engine and the LLM provider layer
+ * without circular dependencies.
+ *
+ * This module is the single source of truth for:
+ * - `PromptIntent`           — discriminated union for intent classification
+ * - `classifyPromptIntent()`  — regex-based intent classifier
+ * - `ACTION_VERBS`            — canonical action-verb list (used by isPathContext,
+ *                              draftLooksLikePathContext, and fuzzy-matcher)
+ * - `looksLikeProse()`        — single-line prose detection
+ * - `looksLikeProseContext()`  — multi-line prose detection
+ * - `isPathContext()`         — path-prefix context validation
+ * - `looksLikeFilename()`     — completion output shape detection
+ * - `draftLooksLikePathContext()` — draft context shape detection
+ *
+ * Consumers import from here; legacy re-exports live in `fast-path-engine.ts`
+ * and `providers/truncate.ts` for backward compatibility with existing tests.
+ */
+/**
+ * Coarse-grained intent of the current prompt line. Used to route the
+ * autocompletion pipeline:
+ *
+ * - `command`   — shell-like command (starts with `/`, `$`, `!`, `@`)
+ *                → deterministic + LLM
+ * - `question`  — user asks a question (starts with how/what/why/...)
+ *                → LLM only (skip deterministic)
+ * - `instruction` — imperative sentence (starts with a verb)
+ *                  → deterministic + LLM
+ * - `path-ref`  — user is typing a file path or referencing files
+ *                → deterministic only
+ * - `prose`     — natural-language sentence (none of the above)
+ *                → LLM only (skip deterministic)
+ */
+export type PromptIntent = "command" | "question" | "instruction" | "path-ref" | "prose";
+/**
+ * Action verbs that strongly signal the user is about to reference a file
+ * path. Used by `isPathContext`, `draftLooksLikePathContext`, and the
+ * fuzzy matcher's `hasActionTrigger` gate.
+ *
+ * Single canonical source — do NOT duplicate elsewhere.
+ * Covers: file manipulation (open/edit/read/write/save), navigation (cd/ls),
+ * search (find/check/look), shell commands (cat/less/head/tail/touch/mkdir/
+ * rm/cp/mv), loading (load/import/include), and general (show/view/see/run/add).
+ */
+export declare const ACTION_VERBS: Set<string>;
+/** Alternation group for use in regex character classes.  Kept in sync
+ *  with `ACTION_VERBS` — rebuild with `[...ACTION_VERBS].join("|")`.
+ *  Exported so consumers (fast-path-engine, etc.) can build verb-aware
+ *  regexes without duplicating the list. */
+export declare const ACTION_VERBS_ALT: string;
+/**
+ * Heuristic: does the text before the cursor look like natural-language prose
+ * rather than a command / path context? Returns true when there are 4+ word
+ * tokens (\w{2,}) — a strong signal the user is writing a sentence, not a
+ * filename.
+ *
+ * This prevents the fuzzy matcher from proposing `config.ts` when the user
+ * types "please add a con|" ("con" fuzzy-matches config.ts at score ~75).
+ */
+export declare function looksLikeProse(lineBeforeCursor: string): boolean;
+/** Reason a multi-line prose context fired. Used for observability so
+ *  callers can log *why* the deterministic path was suppressed. */
+export type ProseContextReason = "density" | "cohesion" | "punctuation";
+/** Detailed result of multi-line prose detection. `reason` is set iff
+ *  `isProse` is true, naming the rule that triggered. */
+export interface ProseContextResult {
+    isProse: boolean;
+    reason?: ProseContextReason;
+}
+/**
+ * Heuristic: do the surrounding lines indicate a prose context (the user
+ * is writing natural-language text across multiple lines)? Returns the
+ * verdict together with the matching reason for observability.
+ *
+ * Rules (first match wins):
+ *
+ * 1. **High word density**: the previous lines contain 8+ word tokens total
+ *    (\w{2,}) — strong signal of paragraph-level prose.
+ * 2. **Lexical cohesion**: the previous lines share ≥2 word tokens with the
+ *    current line — inspired by Hearst's TextTiling algorithm for
+ *    detecting topic continuity.
+ * 3. **Sentence punctuation**: the previous non-empty line ends with a
+ *    period or comma AND carries at least PUNCTUATION_MIN_PREV_TOKENS
+ *    alpha word tokens. The token-count guard kills shell one-liners
+ *    like `echo hello,` that would otherwise be misrouted.
+ *    Semicolons are excluded (common in code).
+ */
+export declare function classifyProseContext(previousLines: string[], currentLineBeforeCursor: string): ProseContextResult;
+/**
+ * Boolean wrapper kept for back-compat with existing tests / call sites
+ * that don't need the reason. Prefer `classifyProseContext` when the
+ * caller wants to log why prose mode triggered.
+ *
+ * @param previousLines — lines before the current line
+ * @param currentLineBeforeCursor — text on the current line before the cursor
+ */
+export declare function looksLikeProseContext(previousLines: string[], currentLineBeforeCursor: string): boolean;
+/**
+ * Heuristic: is the path-prefix token in a context that suggests the user
+ * intends to type a filename? Returns true when:
+ * - The token is inside quotes
+ * - The token is preceded by an action verb + whitespace ("read src/|")
+ * - The token starts at column 0 or after only whitespace
+ * - The preceding character is a non-letter boundary (`=`, `:`, `,`, etc.)
+ *
+ * Returns false when the token is embedded in prose (e.g. "and then src/|").
+ */
+export declare function isPathContext(lineBeforeCursor: string, _token: {
+    token: string;
+    insideQuote: boolean;
+}): boolean;
+/**
+ * Short human-readable description for each intent, suitable for injection
+ * into LLM system prompts or FIM comment headers. Single canonical source —
+ * both chat-style (`truncate.ts`) and FIM (`openai-compat-provider.ts`)
+ * providers use these so the wording stays consistent.
+ */
+export declare const INTENT_DESCRIPTION: Record<PromptIntent, string>;
+/**
+ * Classify the user's current prompt intent. Uses simple regex / keyword
+ * heuristics to decide which completion pipeline to activate.
+ *
+ * The classifier examines only the current line before the cursor (fast)
+ * plus optional previous lines for multi-line prose detection.
+ *
+ * Returns one of: `command`, `question`, `instruction`, `path-ref`, `prose`.
+ *
+ * Classification order (first match wins):
+ * 1. `command`   — line starts with `/`, `!`, `$`, `@`
+ * 2. `path-ref`  — line ends with a path-like prefix (contains `/`) or is
+ *                  inside quotes after an action verb
+ * 3. `question`  — line starts with a question word (how/what/why/...)
+ * 4. `instruction` — line starts with an action verb
+ * 5. `prose`     — multi-line prose context detected, or single-line prose
+ *                  (4+ word tokens)
+ */
+export declare function classifyPromptIntent(lineBeforeCursor: string, previousLines?: string[]): PromptIntent;
+/** Reason a prompt was classified as prose. `single-line` corresponds to
+ *  `looksLikeProse` (4+ word tokens on the current line); the others
+ *  mirror `ProseContextReason`. */
+export type ProseReason = ProseContextReason | "single-line";
+/** Detailed intent classification including the prose-rule reason when
+ *  applicable. Lets the editor log *why* the deterministic path was
+ *  suppressed without re-running the heuristic. */
+export interface IntentClassification {
+    intent: PromptIntent;
+    proseReason?: ProseReason;
+}
+/**
+ * Detailed variant of `classifyPromptIntent`. Same classification order,
+ * but returns the prose-rule reason when intent === "prose" so callers
+ * can emit observability records.
+ */
+export declare function classifyPromptIntentDetailed(lineBeforeCursor: string, previousLines?: string[]): IntentClassification;
+/**
+ * Heuristic: does the completion text look like a raw filename or path?
+ * Matches patterns like "src/foo/bar.ts", "config.json", "./path/to/file",
+ * and extensions like .ts, .js, .py, .json, .md, etc.
+ *
+ * Intentionally conservative: requires at least a 2-char extension with
+ * no trailing dot, and rejects common false positives like "hello.there"
+ * by requiring the extension part to look like a real file extension
+ * (starts with a letter, contains only letters/digits).
+ */
+export declare function looksLikeFilename(text: string): boolean;
+/**
+ * Heuristic: does the user's draft text look like they're in a path-typing
+ * context? Returns true when the draft ends with a path-like prefix
+ * (contains `/`, optionally preceded by `./` or `~/`) or when the last
+ * few words include an action verb ("read", "open", "edit", etc.).
+ */
+export declare function draftLooksLikePathContext(draft: string): boolean;

package/dist/metrics.d.ts

@@ -1,6 +1,17 @@
-export type CompletionMode = "deterministic" | "llm";
+/**
+ * SPDX-License-Identifier: SSPL-1.0
+ * SPDX-FileCopyrightText: 2025 Alessandro Pungitore <alessandro@pungitore.ch>
+ */
+/**
+ * Source of truth for all completion modes. Both the type union (compile-time)
+ * and the parser whitelist (runtime, in `bench.ts`) derive from this array so
+ * adding a mode means updating one place.
+ */
+export declare const COMPLETION_MODES: readonly ["deterministic", "llm", "cache", "trie", "speculative-warm", "provisional", "profile-slash"];
+export type CompletionMode = (typeof COMPLETION_MODES)[number];
 export type RequestResult = "produced" | "empty" | "rejected" | "aborted" | "error";
-export type AcceptanceOutcome = "accepted" | "dismissed" | "stale" | "expired";
+export type AcceptanceOutcome = "accepted" | "accepted-partial" | "dismissed" | "stale" | "expired";
+export type QualityAttribution = "accepted" | "dismissed-attributed" | "unknown";
 export type RejectionReason = "stale-text" | "newline" | "too-long" | "assistant-phrasing" | "duplicate-suffix" | "markdown" | "empty" | "echo-token";
 export interface ProviderLatency {
     provider: string;
@@ -25,7 +36,91 @@ export interface MetricsRecord {
      * Never set for LLM mode (would risk leaking output text).
      */
     matchedPath?: string;
+    /** Characters of the ghost the user accepted (full or partial). */
+    acceptedChars?: number;
+    /** Chars from suggestion that matched the user's eventual committed text. */
+    prefixMatchLen?: number;
+    /** Levenshtein distance between top-1 candidate and committed line. */
+    editDistance?: number;
+    /** Count of Ctrl+Right partial accepts on this candidate. */
+    partialAccepts?: number;
+    /** 1-based rank accepted at time of accept (M3 candidate sets). */
+    candidateRank?: number;
+    /** Number of candidates considered. */
+    candidateCount?: number;
+    /** Number of Alt+]/Alt+[ cycles before acceptance. */
+    cycledCount?: number;
+    /** Prefix-match length per rank — numeric only. */
+    prefixMatchLenByRank?: number[];
+    /** saved@k by k. */
+    savedAt?: {
+        "1"?: number;
+        "3"?: number;
+        "5"?: number;
+    };
+    /** Time the ghost was visible to the user, in ms. */
+    displayDurationMs?: number;
+    /** Whether quality fields above are reliable for this record. */
+    qualityAttribution?: QualityAttribution;
+    /** Provider time-to-first-token in ms (streaming providers only). */
+    ttftMs?: number;
+    /** Time from provisional ghost render to LLM swap, in ms. */
+    provisionalSwapMs?: number;
+    /** True iff provisional matched LLM within prefix-match >= 0.8. */
+    provisionalWasCorrect?: boolean;
+    /**
+     * True iff a provisional→LLM swap was rendered and the user dismissed or
+     * aborted within `SWAP_FLICKER_WINDOW_MS`. Tracks the perceived flicker
+     * cost of swaps — the `PI_GHOST_PROVISIONAL_PREFER=1` knob trades raw
+     * recall for a lower value of this rate.
+     */
+    provisionalSwapFlicker?: boolean;
+    /**
+     * True iff the ghost was visible for less than `SHORT_HOVER_DISMISS_MS`
+     * before the user dismissed it. Mild negative signal — emitted on the
+     * non-accept record so M8 / future weighting can read it without joining
+     * separate streams. The actual hover duration is in `displayDurationMs`.
+     */
+    shortHoverDismiss?: boolean;
+    /**
+     * True iff the user typed at least `TYPED_PAST_DIVERGENT_THRESHOLD`
+     * consecutive characters that diverged from the served ghost without
+     * accepting it (#5). The detection runs across consecutive stale
+     * finalizations on the same line, so a single keystroke doesn't trip
+     * it — the run resets on any accept. When set, the editor also applies
+     * a session-trie penalty against the (prefix, ghost) pair so future
+     * suggestions on the same prefix are de-prioritised.
+     */
+    typedPastDivergent?: boolean;
+    /** Heuristic: acceptedChars * userAvgMsPerChar - perceivedLatencyMs. */
+    estimatedTimeSavedMs?: number;
+    /**
+     * True when the user deleted >50% of inserted text within the regret
+     * window after acceptance. See PRD §6 M5a.
+     */
+    acceptRegret?: boolean;
+    /** Inserted characters subsequently deleted within the regret window. */
+    regretDeletedChars?: number;
+    /** Combined behavior fingerprint at the time this record was logged. */
+    versionFingerprint?: string;
+    /**
+     * Top candidate's raw `editProximityScore` (un-normalized output of the
+     * scorer the reranker received). Pure observability — bench/replay
+     * correlate it with `acceptance` to validate the feature weight. Set
+     * only when reranker actually ran and edit-history was enabled.
+     */
+    editProximityScore?: number;
+    /**
+     * Size of the `EditHistoryRing` snapshot at predict time. Useful for
+     * filtering out records where the ring was still warming up.
+     */
+    editHistorySize?: number;
 }
+/**
+ * Debug records have a loose payload by necessity (different kinds carry
+ * different shapes). The redactor below scrubs any field that looks like
+ * raw prompt/completion content before serialization — see `redactDebug`.
+ */
 export interface DebugRecord {
     ts: number;
     requestId: string;
@@ -53,4 +148,9 @@ export declare class MetricsLogger {
     flush(): Promise<void>;
     private enqueue;
 }
-//# sourceMappingURL=metrics.d.ts.map
+/**
+ * Strip any debug-record field not on the pass-through whitelist. Replaces
+ * the value with a `[redacted: type=T len=N]` placeholder so debugging still
+ * sees that *something* was there, without leaking content. SEC-27.
+ */
+export declare function redactDebug(rec: DebugRecord): DebugRecord;

package/dist/path-index.d.ts

@@ -1,3 +1,7 @@
+/**
+ * SPDX-License-Identifier: SSPL-1.0
+ * SPDX-FileCopyrightText: 2025 Alessandro Pungitore <alessandro@pungitore.ch>
+ */
 export interface PathIndexOptions {
     cap?: number;
     signal?: AbortSignal;
@@ -17,4 +21,3 @@ export interface PathIndex {
  * path completion this session".
  */
 export declare function buildPathIndex(cwd: string, opts?: PathIndexOptions): Promise<PathIndex | null>;
-//# sourceMappingURL=path-index.d.ts.map

package/dist/path-matcher.d.ts

@@ -1,3 +1,7 @@
+/**
+ * SPDX-License-Identifier: SSPL-1.0
+ * SPDX-FileCopyrightText: 2025 Alessandro Pungitore <alessandro@pungitore.ch>
+ */
 import type { PathIndex } from "./path-index.js";
 export interface PathToken {
     token: string;
@@ -11,6 +15,15 @@ export interface PathPrefixMatch {
 export interface FindPathPrefixOptions {
     limit?: number;
     recentPaths?: Set<string> | null;
+    /**
+     * PRD §M4 — bounded boost from persistent path frequency. Caller passes
+     * `(path) => profileStore.profilePathBoost(path)` which returns a value
+     * in `[0, MAX_PATH_BOOST]` (0.2). Multiplied by 1e3 in the score formula
+     * so it ranks below recent-mention (1e6) but above path length, breaking
+     * ties between equally-fresh matches in favor of historically-frequent
+     * paths. Cannot beat subtree (1e9) — exact session matches still win.
+     */
+    profileBoost?: ((path: string) => number) | null;
 }
 /**
  * Extract a path-like token from the end of `before` (text before the cursor).
@@ -29,4 +42,3 @@ export declare function extractPathPrefixToken(before: string): PathToken | null
  * (nothing to insert).
  */
 export declare function findPathPrefix(index: PathIndex, token: string, opts?: FindPathPrefixOptions | number): PathPrefixMatch | null;
-//# sourceMappingURL=path-matcher.d.ts.map

package/dist/profile-store.d.ts

@@ -0,0 +1,85 @@
+/**
+ * SPDX-License-Identifier: SSPL-1.0
+ * SPDX-FileCopyrightText: 2025 Alessandro Pungitore <alessandro@pungitore.ch>
+ */
+/**
+ * Stateful wrapper around `profile.ts` for the editor. Holds the in-memory
+ * `ProfileIndex`, serializes writes, triggers periodic compaction, and
+ * exposes a synchronous lookup surface for the editor's hot path.
+ *
+ * Lifecycle:
+ *  1. `create(cwd)` — loads + indexes the JSONL once. Returns a disabled
+ *     store if `PI_GHOST_PROFILE=off`. Errors during load yield an empty
+ *     index (best-effort).
+ *  2. `captureCommit(text)` / `captureAccept(prefix, completion, weight)`
+ *     — append to disk (async, fire-and-forget) and merge into the
+ *     in-memory index so the next lookup sees them immediately.
+ *  3. Every `COMPACT_CHECK_EVERY` writes the store runs `compactIfNeeded`
+ *     in the background. Compaction reloads the index after rewrite.
+ *
+ * `disabled` is a public boolean so callers can short-circuit lookups
+ * without an extra function call on the keystroke path.
+ */
+import { DEFAULT_DECAY_DAYS, type ProfileIndex } from "./profile.js";
+export declare class ProfileStore {
+    private readonly cwd;
+    readonly disabled: boolean;
+    private index;
+    private writeQueue;
+    private writesSinceCompact;
+    private decayDays;
+    private constructor();
+    /**
+     * Build a store and load the JSONL into memory. Caller awaits before
+     * exposing the store to the editor so the index is hot on first
+     * keystroke. Disabled stores short-circuit load entirely.
+     */
+    static create(cwd: string, env?: NodeJS.ProcessEnv): Promise<ProfileStore>;
+    getIndex(): ProfileIndex;
+    get decayDaysSetting(): number;
+    /**
+     * Capture user-committed text. Extracts paths + slash + trigrams, drops
+     * sensitive messages entirely. Returns the count of records emitted —
+     * useful for tests/diagnostics.
+     */
+    captureCommit(text: string, ts?: number): number;
+    /**
+     * Capture an accept (full or partial). `weight` defaults to 3 to match
+     * PRD §M2 trie weights. Returns true when a record was emitted.
+     */
+    captureAccept(prefix: string, completion: string, weight?: number, ts?: number): boolean;
+    /** Public lookup surfaces — thin wrappers around `profile.ts`. */
+    bestSlashMatch(prefix: string): {
+        cmd: string;
+        weight: number;
+    } | null;
+    profileBias(text: string): number;
+    profilePathBoost(path: string): number;
+    /**
+     * Provisional fallback (PRD §M3.5b) — look up an exact-prefix accept
+     * record. Returns the completion tokens + summed weight, or null when
+     * the prefix has never been the exact key of a captured accept.
+     * `prefix` is hashed in-process; the raw string never leaves memory.
+     */
+    lookupAcceptByPrefix(prefix: string): {
+        completionTokens: string[];
+        weight: number;
+    } | null;
+    /** Flush any pending writes — call before process exit. */
+    flush(): Promise<void>;
+    /**
+     * Append records both in-memory and to disk. In-memory merge happens
+     * synchronously so the very next lookup sees the new weight; the disk
+     * write is queued through `writeQueue` to serialize concurrent commits.
+     */
+    private mergeAndPersist;
+    /**
+     * Inline equivalent of `buildIndex` for a small record batch. The
+     * fresh-record path skips decay since we just wrote `ts`. Keeping this
+     * separate from `profile.buildIndex` avoids reindexing the whole store
+     * on every keystroke.
+     */
+    private applyToIndex;
+}
+/** Exported for tests — surface compactor knob without re-exporting `profile.ts`. */
+export { DEFAULT_DECAY_DAYS };

package/dist/profile.d.ts

@@ -0,0 +1,167 @@
+/**
+ * SPDX-License-Identifier: SSPL-1.0
+ * SPDX-FileCopyrightText: 2025 Alessandro Pungitore <alessandro@pungitore.ch>
+ */
+export declare const PROFILE_REL = ".pi/ghost-autocomplete/profile.jsonl";
+export declare const DEFAULT_MAX_BYTES: number;
+export declare const DEFAULT_DECAY_DAYS = 90;
+export declare const DROP_BELOW_WEIGHT = 0.1;
+export declare const MAX_NGRAM_N = 4;
+export declare const TRIGRAM_N = 3;
+export type ProfileKind = "ngram" | "path" | "slash" | "accept";
+/**
+ * One on-disk record. `weight` accumulates across captures and decays over
+ * time. `accept` records carry both `prefixHash` (for exact-prefix learning)
+ * and `prefixTailTokens` + `completionTokens` (already tokenized).
+ */
+export interface ProfileRecord {
+    ts: number;
+    kind: ProfileKind;
+    weight: number;
+    /** `kind=ngram`: ordered token tuple. */
+    tokens?: string[];
+    /** Trigram length when `kind=ngram`. */
+    n?: number;
+    /** `kind=path` / `kind=slash`: literal value. */
+    value?: string;
+    /** `kind=accept`: SHA-256 hex digest of the prefix at accept time. */
+    prefixHash?: string;
+    /** `kind=accept`: trailing tokens of the prefix (cap 4). */
+    prefixTailTokens?: string[];
+    /** `kind=accept`: tokens of the completion (cap 8). */
+    completionTokens?: string[];
+}
+/**
+ * In-memory aggregated view of the profile. The maps are weight-sums per
+ * key. `acceptByPrefix` is keyed by `prefixHash` so exact-prefix history is
+ * available without storing the raw prefix.
+ */
+export interface ProfileIndex {
+    ngram: Map<string, number>;
+    path: Map<string, number>;
+    slash: Map<string, number>;
+    acceptByPrefix: Map<string, {
+        completionTokens: string[];
+        weight: number;
+    }>;
+    totalAcceptRecords: number;
+}
+export declare function emptyIndex(): ProfileIndex;
+/**
+ * Tokenize a string into the same word-token form the profile stores. Drops
+ * the empty string, deduplicates whitespace, and lowercases nothing — code
+ * identifiers are case-sensitive.
+ */
+export declare function tokenize(text: string): string[];
+/**
+ * Generate n-grams of size `n` from `tokens`. Returns empty when there are
+ * fewer than `n` tokens.
+ */
+export declare function ngrams(tokens: string[], n: number): string[][];
+/**
+ * SHA-256 hex of a prefix string. The hash is the disk-storable surrogate
+ * for the prefix — same prefix always maps to the same key, but the raw
+ * prefix never leaves the process.
+ */
+export declare function prefixHash(prefix: string): string;
+/**
+ * Extract candidate paths from free text. Same shape used by `recent-paths.ts`
+ * but kept independent so changes to recent-paths semantics don't drift
+ * the profile schema. Matches `foo/bar.ts`, `src/a/b.tsx`, etc.
+ */
+export declare function extractPaths(text: string): string[];
+/**
+ * Extract `/slash-command` tokens from free text. Limited to a-z prefix
+ * plus alphanumerics/hyphen/underscore to avoid false matches on URLs
+ * (`https://…`) or expressions (`x/y`).
+ */
+export declare function extractSlash(text: string): string[];
+/**
+ * Build profile records from a committed user message. Capture path +
+ * slash + trigram ngrams. Sanitize check runs FIRST: messages with
+ * sensitive content are dropped entirely (consistent with session trie).
+ */
+export declare function recordsFromCommit(text: string, ts?: number): ProfileRecord[];
+/**
+ * Build an `accept` record for a full or partial acceptance. `prefix` is
+ * hashed; `completion` is tokenized. The raw prefix never appears in the
+ * returned record. Drops the whole record if either side fails sanitize.
+ */
+export declare function recordFromAccept(prefix: string, completion: string, weight?: number, ts?: number): ProfileRecord | null;
+/**
+ * Append one or more records to the JSONL file. Returns silently on write
+ * failure — profile logging must never break ghost completion.
+ */
+export declare function appendRecords(cwd: string, recs: ProfileRecord[]): Promise<void>;
+/**
+ * Parse the JSONL file into an array of records. Silently skips malformed
+ * lines (partial trailing write) and records missing required fields.
+ * Returns an empty array when the file does not exist.
+ */
+export declare function loadRecords(cwd: string): Promise<ProfileRecord[]>;
+export declare function parseRecords(body: string): ProfileRecord[];
+/**
+ * Build the in-memory aggregated index from a record list. Decays records
+ * older than `decayDays` by halving their weight; drops weights below
+ * `DROP_BELOW_WEIGHT` (0.1). `now` defaults to `Date.now()`; expose for
+ * deterministic tests.
+ */
+export declare function buildIndex(records: ProfileRecord[], opts?: {
+    decayDays?: number;
+    now?: number;
+}): ProfileIndex;
+/**
+ * Look up the weight of a trigram (already tokenized + joined). Returns 0
+ * when missing. Callers should also tokenize the candidate text the same
+ * way the writer did.
+ */
+export declare function ngramWeight(idx: ProfileIndex, tokens: string[]): number;
+/**
+ * Profile-bias score for a candidate completion. PRD §M4
+ * "Ranking-from-prior": `α·log(1 + ngramWeight) + β·pathWeight + γ·slashWeight`.
+ * Returns 0 when the index is empty or the candidate has no signal —
+ * neutral input to the reranker.
+ */
+export declare function profileBias(idx: ProfileIndex, text: string, weights?: {
+    alpha?: number;
+    beta?: number;
+    gamma?: number;
+}): number;
+/**
+ * Bounded boost for deterministic path matches. Capped so persistent
+ * frequency cannot beat a fresh exact-prefix path-prefix match (PRD §M4
+ * "Deterministic path/fuzzy ranking"). The cap is a constant 0.2 — tune
+ * once we have replay data.
+ */
+export declare const MAX_PATH_BOOST = 0.2;
+export declare function profilePathBoost(idx: ProfileIndex, path: string): number;
+/**
+ * Slash-command frequency score. Used by the editor's slash fast-path:
+ * given a `/cmd-prefix`, return the best-matching full command by weight.
+ * Returns null when nothing in the index extends `prefix`.
+ */
+export declare function bestSlashMatch(idx: ProfileIndex, prefix: string): {
+    cmd: string;
+    weight: number;
+} | null;
+/**
+ * Rotate + compact when the file exceeds `maxBytes`. Strategy: load all
+ * records, decay them, sum weights per (kind, key), drop sub-threshold
+ * entries, write the compacted file back. Returns true when a rotation
+ * happened. Best-effort — swallows errors.
+ */
+export declare function compactIfNeeded(cwd: string, opts?: {
+    maxBytes?: number;
+    decayDays?: number;
+    now?: number;
+}): Promise<boolean>;
+/**
+ * Compact a record list in memory: decay aged weights, sum per (kind,key),
+ * drop sub-threshold. Pure function — exposed for unit tests.
+ */
+export declare function compactRecords(records: ProfileRecord[], opts?: {
+    decayDays?: number;
+    now?: number;
+}): ProfileRecord[];
+/** Parse `PI_GHOST_PROFILE_DECAY_DAYS`. Falls back to default when invalid. */
+export declare function parseDecayDaysEnv(raw: string | undefined): number;

package/dist/providers/cloud-provider.d.ts

@@ -1,10 +1,22 @@
+/**
+ * SPDX-License-Identifier: SSPL-1.0
+ * SPDX-FileCopyrightText: 2025 Alessandro Pungitore <alessandro@pungitore.ch>
+ */
 import type { CloudProviderConfig } from "../config.js";
-import type { GhostProvider, GhostRequest } from "./types.js";
+import type { GhostProvider, GhostRequest, StreamDelta } from "./types.js";
 export declare class CloudProvider implements GhostProvider {
     private readonly config;
     readonly name = "ghost-cloud";
     constructor(config: CloudProviderConfig);
     get debounceMs(): number;
     predict(req: GhostRequest): Promise<string | null>;
+    /**
+     * PRD §M3.5a — stream tokens from the upstream provider via pi-ai's
+     * `stream()`. Yields `text_delta` events as `StreamDelta` chunks
+     * including a running `cumulative` to spare the editor from tracking
+     * concatenation state. `sanitizeCompletion` runs once on the final
+     * assembled text after the stream ends — running it per-chunk would
+     * truncate mid-token and break ghost rendering.
+     */
+    predictStream(req: GhostRequest): AsyncIterable<StreamDelta>;
 }
-//# sourceMappingURL=cloud-provider.d.ts.map

package/dist/providers/local-provider.d.ts

@@ -1,5 +1,9 @@
+/**
+ * SPDX-License-Identifier: SSPL-1.0
+ * SPDX-FileCopyrightText: 2025 Alessandro Pungitore <alessandro@pungitore.ch>
+ */
 import type { LocalProviderConfig } from "../config.js";
-import type { GhostProvider, GhostRequest } from "./types.js";
+import type { GhostProvider, GhostRequest, StreamDelta } from "./types.js";
 export declare class LocalProvider implements GhostProvider {
     private readonly config;
     readonly name = "ghost-local";
@@ -7,5 +11,11 @@ export declare class LocalProvider implements GhostProvider {
     get debounceMs(): number;
     preflight(): Promise<boolean>;
     predict(req: GhostRequest): Promise<string | null>;
+    /**
+     * PRD §M3.5a — Ollama/vLLM streaming via the OpenAI-completions stream
+     * endpoint. Same opts as `predict`, just driven by the runner's
+     * streaming variant.
+     */
+    predictStream(req: GhostRequest): AsyncIterable<StreamDelta>;
+    private callOpts;
 }
-//# sourceMappingURL=local-provider.d.ts.map