trajectories 0.0.0 → 0.1.2

package/legacy/src/types.ts

@@ -0,0 +1,436 @@
+import type { DiscoveryCheckpoint } from "./discovery.js";
+import type {
+  AnyTrajectorySource,
+  CanonicalRecord,
+  CanonicalRecordType,
+  Diagnostic,
+  NormalizedRecord,
+  SourceIdentityKind,
+} from "@letta-ai/trajectory";
+
+export type SupportedSource =
+  | "claude-code"
+  | "codex"
+  | "pi"
+  | "hermes"
+  | "omp"
+  | "openclaw"
+  | "cursor"
+  | "opencode"
+  | "gemini-cli"
+  | "deepagents"
+  | "droid"
+  | "letta-code"
+  | "openhands"
+  | "copilot-cli"
+  | "grok"
+  | "kimi"
+  | "cline"
+  | "fx"
+  | "atif"
+  | string;
+
+export interface SessionRecord {
+  id: string;
+  source: string;
+  source_path: string;
+  content_hash: string;
+  /** Version 1 is the legacy whole-session digest; version 2 is appendable. */
+  content_hash_version?: number;
+  title: string | null;
+  cwd: string | null;
+  model: string | null;
+  started_at: string | null;
+  ended_at: string | null;
+  record_count: number;
+  created_at: string;
+  updated_at: string;
+  parent_session_id?: string | null;
+  parent_tool_use_id?: string | null;
+  agent_nickname?: string | null;
+  thread_role?: string | null;
+}
+
+export interface CanonicalDbRecord {
+  id: string; // record_id
+  session_id: string;
+  source_type: string;
+  /** Native lineage provenance; absent in older schemas, null when unknown. */
+  native_session_id?: string | null;
+  binding_id?: string | null;
+  record_type: CanonicalRecordType;
+  stable_source_record_id: string | null;
+  source_identity_kind: SourceIdentityKind | null;
+  source_order_id: string;
+  component_index: number;
+  record_timestamp: string | null;
+  source_timestamp: string | null;
+  content: string | null;
+  tool_call_id: string | null;
+  tool_name: string | null;
+  tool_arguments_json: string | null;
+  tool_result_json: string | null;
+  tool_result_ok: number | null; // 1 = true, 0 = false, null
+  record_json: string;
+  content_hash: string;
+  record_hash: string;
+}
+
+export interface NormalizedSessionResult {
+  session: SessionRecord;
+  records: CanonicalDbRecord[];
+  rawNormalizedRecords: NormalizedRecord[];
+  diagnostics: Diagnostic[];
+}
+
+export interface DiscoveredSession {
+  id: string;
+  source: string;
+  path: string;
+  updatedAt?: string;
+  title?: string;
+  sizeBytes?: number;
+  /** Native storage requiring assembly before Trajectory normalization. */
+  native?:
+    | { kind: "cursor-sqlite" | "cursor-blobstore" | "opencode-sqlite" }
+    | { kind: "opencode-storage"; root: string }
+    | { kind: "fx-directory" }
+    /** `parentSessionId` is the child's edge from the parent-side subagent registry, or absent. */
+    | { kind: "grok-updates"; parentSessionId?: string }
+    /**
+     * `parentSessionId` is the enclosing session of a `subagents/<agent>/` transcript;
+     * `parentToolUseId` is the tool call that spawned it, read from the parent's wire.
+     */
+    | { kind: "kimi-wire"; parentSessionId?: string; parentToolUseId?: string };
+}
+
+export interface IngestCursor {
+  source: string;
+  listing_id: string;
+  source_path: string;
+  session_id: string | null;
+  mtime: string;
+  size: number;
+  bytes_ingested: number;
+  record_count: number;
+  status: "ok" | "failed" | "pending";
+  updated_at: string;
+  file_identity?: string | null;
+  prefix_hash?: string | null;
+  checkpoint_version?: number | null;
+  line_count?: number | null;
+  tail_offset?: number | null;
+  tail_hash?: string | null;
+}
+
+export interface IngestQueueEntry extends DiscoveredSession {
+  attempt_count: number;
+  next_attempt_at: string | null;
+  last_attempt_at: string | null;
+  last_outcome: string | null;
+}
+
+/**
+ * How far one user-initiated deletion went. `suppress` is the default and the
+ * one that keeps the store canonical: the session's rows stay, and every
+ * serving and admission surface treats the session as gone. `hard` is the
+ * explicit escape — the records, vectors, echo markers, titles, diagnostics and
+ * staged replacements were removed in the tombstone's own transaction, and only
+ * the axis that stops the source from re-admitting the session is left.
+ */
+export type TombstoneMode = "suppress" | "hard";
+
+/**
+ * One user's deletion, as the `session_tombstones` table holds it.
+ *
+ * Every column but `mode` is one deletion event and is never rewritten: the
+ * session it names, when it happened, and why (the reason is the audit row's
+ * whole point — a tombstone with no account of itself is a hole in the record).
+ * `mode` is the exception: a `suppress` tombstone can be escalated to `hard`
+ * later, which is the same deletion carried further, not a second one.
+ */
+export interface TombstoneRecord {
+  /** The Ledger session id: the axis serving knows, and the row's primary key. */
+  session_id: string;
+  source: string;
+  /**
+   * The source-native id the session was committed under
+   * (`nativeId(source, session_id)`), which is the axis a re-scan can name
+   * before it reads anything. It differs from the id a *listing* carries
+   * whenever the source groups several files under one session id.
+   */
+  native_id: string;
+  /** Where the session was ingested from, for the audit: never an admission key. */
+  source_path: string | null;
+  mode: TombstoneMode;
+  reason: string;
+  /** Records the session held when it was deleted: the deletion's own fact. */
+  record_count: number;
+  deleted_at: string;
+}
+
+/**
+ * One session's diagnostics collapsed to one entry per code. `occurrenceCount`
+ * deliberately mixes upstream meanings: codes such as `timestamps_interpolated`
+ * report affected records, the rest report one occurrence per diagnostic. Zero
+ * is a real value upstream reports and is never inflated to one.
+ */
+export interface IngestDiagnosticAggregate {
+  code: string;
+  occurrenceCount: number;
+  sample: string | null;
+  /** Earliest observation of this code, carried across staged chunks. */
+  firstSeenAt?: string;
+}
+
+/** One stored diagnostics row, as the `ingest_diagnostics` table holds it. */
+export interface IngestDiagnosticRecord {
+  session_id: string;
+  source: string;
+  code: string;
+  occurrence_count: number;
+  sample: string | null;
+  first_seen_at: string;
+  last_seen_at: string;
+}
+
+/** Store-wide diagnostics coverage, ordered by occurrences (descending). */
+export interface DiagnosticsSummary {
+  totalSessions: number;
+  totalOccurrences: number;
+  byCode: Array<{ code: string; sessions: number; occurrences: number }>;
+}
+
+/**
+ * How one source's scan ended. The set is closed: upstream listers report a
+ * missing, unreadable, or file-shaped root as an empty listing, so the status
+ * is probed scanner-side before listing and must stay reconstructible.
+ */
+export type ScanOutcomeStatus =
+  | "listable"
+  | "missing_root"
+  | "root_wrong_shape"
+  | "unreadable_root"
+  | "listing_failed";
+
+/**
+ * One source's scan outcome, recomputed per scan and never persisted. `status`
+ * describes the source's scan outcome; `root` names the primary (first
+ * readable) location, which for a multi-location source can be healthy even
+ * when `detail` records a failure elsewhere; `discovered` counts the sessions
+ * the source contributed to this scan. `detail` is either an error class plus
+ * the runtime's code or a native diagnostic's fixed message — both capped at
+ * `SCAN_OUTCOME_DETAIL_LIMIT` and free of store content — and is null when the
+ * status needs no explanation.
+ */
+export interface ScanOutcome {
+  source: string;
+  root: string;
+  status: ScanOutcomeStatus;
+  discovered: number;
+  detail?: string | null;
+}
+
+/**
+ * One source's stored coverage: the verdict of the last lease-holding pass that
+ * scanned it (`recordSourceCoverage`). State, not history — every later pass
+ * rewrites `root`, `status`, `discovered`, `detail`, and `updated_at` in place,
+ * including a source that stops being listable, so a stored row never claims a
+ * success the newest pass did not see. `first_seen_at` is stamped once and
+ * survives while the source keeps being seen, so the row also carries coverage
+ * age; `detail` is a scan-outcome detail, and is null when the status needs no
+ * explanation. Written only by a writer holding the lease; `scan` computes the
+ * same verdicts and persists nothing.
+ */
+export interface SourceCoverageRow {
+  source: string;
+  root: string;
+  status: ScanOutcomeStatus;
+  discovered: number;
+  detail: string | null;
+  first_seen_at: string;
+  updated_at: string;
+}
+
+/**
+ * What a reader sees of a stored coverage row: the same verdict without the
+ * internal `first_seen_at` stamp, which exists to make age readable inside the
+ * store rather than to widen the status contract.
+ */
+export type SourceCoverage = Omit<SourceCoverageRow, "first_seen_at">;
+
+export interface ScanResult {
+  sessions: DiscoveredSession[];
+  outcomes: ScanOutcome[];
+  /** Present only for scheduled paged discovery, never fabricated by old scanners. */
+  discovery?: DiscoveryCheckpoint[];
+}
+
+export interface ScanOptions {
+  /** Opt into a bounded history page plus a recent refresh, using durable checkpoints. */
+  discovery?: Record<string, DiscoveryCheckpoint>;
+  sources?: string[];
+  roots?: Record<string, string>;
+  limit?: number;
+}
+
+export interface BuildOptions extends ScanOptions {
+  dbPath?: string;
+  force?: boolean;
+  verbose?: boolean;
+}
+
+export interface BuildSummary {
+  scanned: number;
+  imported: number;
+  deduped: number;
+  failed: number;
+  /** Processed sessions with no stored vectors of any provider after this pass.
+   * Zero does not imply complete or provider-compatible semantic coverage. */
+  unembedded: number;
+  /** Sessions for which this invocation intentionally did no embedding work. */
+  embedding_skipped: number;
+  /** Sessions whose embedding attempt failed, possibly after partial progress. */
+  embedding_failed: number;
+  /** Listings the user deleted, refused at admission: not failures, and not
+   * imports — counted so the two other numbers stay what they claim to be. */
+  tombstoned: number;
+  totalRecords: number;
+  sources: Record<string, { scanned: number; imported: number; deduped: number; failed: number; tombstoned: number }>;
+}
+
+/**
+ * What every hit names, whichever lane produced it: the session it belongs to,
+ * where that session sits in the corpus, and the snippet to show.
+ */
+interface SearchHitBase {
+  session_id: string;
+  source: string;
+  title: string | null;
+  cwd: string | null;
+  started_at: string | null;
+  snippet: string;
+  /**
+   * The ranking the producing lane ordered by, in that lane's own units: the
+   * lexical lanes' bm25 weighted by the recency prior (C6), the semantic lane's
+   * cosine similarity, or a fused hit's positive RRF score. Lane-relative by
+   * construction — a title hit's rank and a record hit's rank are not
+   * comparable, and the emitted order is the contract, not a re-sort by these
+   * numbers (see the robot v1 note in `docs/api-surface.md`).
+   */
+  rank?: number;
+  parent_session_id?: string | null;
+  agent_nickname?: string | null;
+  thread_role?: string | null;
+}
+
+/**
+ * A hit that names one canonical record: the ordinary answer of every engine.
+ */
+export interface RecordSearchHit extends SearchHitBase {
+  record_id: string;
+  record_type: string;
+  content: string | null;
+  tool_name: string | null;
+  tool_arguments: string | null;
+  tool_result: string | null;
+  /**
+   * How this hit matched. `implicit_wildcard` marks hits that only matched
+   * because Ledger widened a zero-hit query to prefix terms, and `semantic`
+   * marks vector hits; `lexical` is the ordinary FTS5 path.
+   */
+  match_type: RecordMatchType;
+}
+
+/**
+ * A hit on a session's *title*: session-level, with no record behind it.
+ *
+ * The title index answers for a session, not for a record — the title was
+ * derived from the source's own metadata or its first user message and belongs
+ * to the trajectory as a whole, so `record_id` is `null` rather than a
+ * fabricated id pointing at a record no adapter wrote, `record_type` is
+ * `"title"` rather than a record type the hit does not have, and the snippet is
+ * the title itself. `started_at` is the session's start, which is where a
+ * consumer reading the hit should look. Wake emits the same shape (`role:
+ * "title"`, `seq: 0` and never a fake `seq`,
+ * `crates/wake-core/src/db.rs#L1676-L1700`).
+ */
+export interface TitleSearchHit extends SearchHitBase {
+  record_id: null;
+  record_type: "title";
+  content: null;
+  tool_name: null;
+  tool_arguments: null;
+  tool_result: null;
+  /** Non-null by construction: only a session whose title the store holds is indexed. */
+  title: string;
+  match_type: "title";
+}
+
+/** One search hit: a canonical record, or a session matched through its title. */
+export type SearchHit = RecordSearchHit | TitleSearchHit;
+
+/** Which retrieval engine produced a result set. */
+export type SearchMode = "lexical" | "semantic" | "hybrid";
+
+/** The match provenance a hit carrying a record can have. */
+export type RecordMatchType = "lexical" | "implicit_wildcard" | "semantic";
+
+/** Per-hit provenance within a result set; `title` marks a session-level title hit. */
+export type SearchMatchType = RecordMatchType | "title";
+
+/**
+ * Why prefix widening was refused on a zero-hit lexical query. Widening is only
+ * attempted when the primary query returned nothing, so a satisfied search
+ * reports `widened: null` instead of any of these.
+ */
+export type WideningSkipReason =
+  | "disabled"
+  | "quoted_input"
+  | "operators_present"
+  | "wildcard_present"
+  | "token_too_long"
+  | "no_widenable_tokens"
+  | "query_too_long"
+  | "corpus_over_ceiling"
+  | "no_improvement"
+  | "widened_query_failed";
+
+export interface WideningReport {
+  applied: boolean;
+  /** Hits the un-widened query returned; always 0 when widening ran. */
+  original_hits?: number;
+  /**
+   * Hits returned by the widened pass, bounded by the requested limit (so it is
+   * a lower bound whenever it equals the limit or the limit-bounded count).
+   */
+  widened_hits?: number;
+  /** Agent-readable reason widening was refused. */
+  skip_reason?: WideningSkipReason;
+}
+
+/**
+ * Honest accounting for one search: how exact the count is, how long the call
+ * took, which engine actually ran, and whether the zero-hit lexical path
+ * widened the query or fell back to escaped terms.
+ */
+export interface SearchMeta {
+  count_precision: "exact" | "lower_bound";
+  count_reason: string;
+  elapsed_ms: number;
+  search_mode: SearchMode;
+  requested_search_mode: SearchMode;
+  fallback_reason: string | null;
+  /** Null when widening was not attempted (the primary query returned hits). */
+  widened: WideningReport | null;
+}
+
+export interface QueryResult {
+  query: string;
+  /** Bounded by the caller's limit; read `meta.count_precision` before
+   * presenting this as an exact corpus count. */
+  totalHits: number;
+  sessionsCount: number;
+  hits: SearchHit[];
+  meta: SearchMeta;
+}