@peasant-labs/fairtrade 0.0.6 → 0.0.9

package/dist/lib/types/graph/SessionLane.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @param {object} props
+ * @param {string} props.sessionId
+ * @param {string} props.title
+ * @param {import('@peasant-labs/schema').Harness} [props.harness]
+ * @param {boolean} [props.hovered]
+ * @param {boolean} [props.selected]
+ * @param {(sessionId: string|null) => void} props.onHover
+ * @param {(sessionId: string) => void} props.onSelect
+ * @param {Array<{ghostHash:string, subject?:string, resolution:string, method:string, confidence:string}>} [props.unresolvedGhosts]
+ * @param {string} [props.className]
+ */
+export default function SessionLane({ sessionId, title, harness, hovered, selected, onHover, onSelect, unresolvedGhosts, className, ...rest }: {
+    sessionId: string;
+    title: string;
+    harness?: import("@peasant-labs/schema").Harness;
+    hovered?: boolean;
+    selected?: boolean;
+    onHover: (sessionId: string | null) => void;
+    onSelect: (sessionId: string) => void;
+    unresolvedGhosts?: Array<{
+        ghostHash: string;
+        subject?: string;
+        resolution: string;
+        method: string;
+        confidence: string;
+    }>;
+    className?: string;
+}): any;

package/dist/lib/types/graph/SessionOverflowDisclosure.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @param {object} props
+ * @param {string} props.commitHash - or any owning-row id; used to key the reducer's `toggle-commit-sessions`.
+ * @param {Array<{sessionId:string, title:string, harness?:import('@peasant-labs/schema').Harness}>} props.overflow - the sessions beyond the inline-2.
+ * @param {boolean} props.expanded
+ * @param {(id: string) => void} props.onToggle
+ * @param {(sessionId: string) => void} [props.onSelect]
+ * @param {string} [props.itemLabel='sessions']
+ * @param {string} [props.className]
+ */
+export default function SessionOverflowDisclosure({ commitHash, overflow, expanded, onToggle, onSelect, itemLabel, className, ...rest }: {
+    commitHash: string;
+    overflow: Array<{
+        sessionId: string;
+        title: string;
+        harness?: import("@peasant-labs/schema").Harness;
+    }>;
+    expanded: boolean;
+    onToggle: (id: string) => void;
+    onSelect?: (sessionId: string) => void;
+    itemLabel?: string;
+    className?: string;
+}): any;

package/dist/lib/types/graph/TouchedFileCluster.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @param {object} props
+ * @param {string} props.commitHash
+ * @param {string[]} props.files - already ordered by the caller (DOI intrinsic, or visit order when a session is selected).
+ * @param {boolean} props.expanded
+ * @param {(id: string) => void} props.onToggle
+ * @param {(file: string) => void} [props.onOpenDiff]
+ * @param {string} [props.className]
+ */
+export default function TouchedFileCluster({ commitHash, files, expanded, onToggle, onOpenDiff, className, ...rest }: {
+    commitHash: string;
+    files: string[];
+    expanded: boolean;
+    onToggle: (id: string) => void;
+    onOpenDiff?: (file: string) => void;
+    className?: string;
+}): any;

package/dist/lib/types/graph/changeGraph.d.ts

@@ -58,6 +58,10 @@ export type CommitGraphRow = {
      * a recorded session sits behind this commit (→ filled dot + sparkle)
      */
     session?: boolean;
+    /**
+     * named sessions bound to this commit
+     */
+    sessionRefs?: import("./types.js").TimelineSessionPayload[];
     /**
      * this commit merged a branch back in (→ merged chip)
      */
@@ -103,4 +107,12 @@ export type ChangesGraph = {
      * number of merged changes
      */
     mergedCount: number;
+    /**
+     * sessions not linked to a commit in this timeline window
+     */
+    unlinkedSessions: import("./types.js").TimelineSessionPayload[];
+    /**
+     * sessions linked to a commit outside the displayed default-branch window
+     */
+    outsideWindowSessions: import("./types.js").TimelineSessionPayload[];
 };

package/dist/lib/types/graph/codeMapState.d.ts

@@ -0,0 +1,240 @@
+/** @param {unknown} value @returns {value is number} */
+export function isCodeMapViewportScale(value: unknown): value is number;
+/**
+ * Creates a canonical, JSON-safe code-map interaction state.
+ * @param {Partial<CodeMapState>|null} [seed]
+ * @returns {CodeMapState}
+ */
+export function createCodeMapState(seed?: Partial<CodeMapState> | null): CodeMapState;
+/** @param {CodeMapState} left @param {CodeMapState} right */
+export function codeMapStatesEqual(left: CodeMapState, right: CodeMapState): boolean;
+/**
+ * Applies one semantic interaction and returns a fresh canonical state.
+ * @param {CodeMapState} state
+ * @param {CodeMapAction} action
+ * @returns {CodeMapState}
+ */
+export function reduceCodeMapState(state: CodeMapState, action: CodeMapAction): CodeMapState;
+/**
+ * Pure derivation of the timeline's highlight state. Hover is
+ * subordinate to selection: both are returned independently so a caller can render
+ * selection at primary weight (amber fill) and hover as a secondary/additive
+ * layer (stroke width-step + glow) without one clearing the other. Escape
+ * clears hover, then selection; see `resolveEscapeAction`.
+ * @param {{edges: Array<{sessionId:string, commitHash:string, ghost?:boolean}>}|undefined|null} payload
+ * @param {CodeMapState} state
+ * @returns {{selected: TimelineHighlight, hovered: TimelineHighlight}}
+ */
+export function deriveTimelineHighlight(payload: {
+    edges: Array<{
+        sessionId: string;
+        commitHash: string;
+        ghost?: boolean;
+    }>;
+} | undefined | null, state: CodeMapState): {
+    selected: TimelineHighlight;
+    hovered: TimelineHighlight;
+};
+/**
+ * The Escape-key contract: "Escape clears hover then selection."
+ * Pure and reusable by every primitive that captures the key, so the two-step
+ * behavior lives in exactly one place. Returns null when there is nothing to clear.
+ * @param {CodeMapState} state
+ * @returns {{type:'hover-session', sessionId:null} | {type:'select-session', sessionId:null} | null}
+ */
+export function resolveEscapeAction(state: CodeMapState): {
+    type: "hover-session";
+    sessionId: null;
+} | {
+    type: "select-session";
+    sessionId: null;
+} | null;
+/**
+ * Derives the complete navigator and canvas inputs from payload plus canonical state.
+ * Returned nodes are plain public payload data; no private indexes or depths are attached.
+ * @param {import('./types.js').CodeMapPayload|undefined|null} payload
+ * @param {CodeMapState} state
+ * @returns {CodeMapView}
+ */
+export function deriveCodeMapView(payload: import("./types.js").CodeMapPayload | undefined | null, state: CodeMapState): CodeMapView;
+/** @typedef {import('./types.js').MapNodePayload} MapNodePayload */
+/**
+ * The COMPLETE public timeline/ranking action surface. Frozen here: names are
+ * consumed downstream (the timeline surface, the ranked entry list) and are never renamed.
+ * @typedef {{type:'replace'|'hydrate', state:Partial<CodeMapState>} | {type:'set-presentation', presentation:CodeMapPresentation} | {type:'select'|'toggle-expanded'|'open-in-map', id:string} | {type:'focus', id:string|null} | {type:'clear-selection'} | {type:'set-filter', filter:string} | {type:'set-expanded', ids:Iterable<string>} | {type:'set-grain', grain:CodeMapGrain} | {type:'set-viewport', viewport:CodeMapViewport|null} | {type:'reveal', id:string, grain:CodeMapGrain, expandedIds:Iterable<string>} | {type:'hover-session', sessionId:string|null} | {type:'select-session', sessionId:string|null} | {type:'toggle-commit-sessions', commitHash:string} | {type:'toggle-ghost-group', successorHash:string} | {type:'set-rank-mode', rankMode:CodeMapRankMode} | {type:'set-scent-filter', scentFilter:string|null} | {type:'set-rank-expanded', expanded:boolean}} CodeMapAction
+ */
+/**
+ * @typedef {object} CodeMapState
+ * @property {1} version
+ * @property {CodeMapPresentation} presentation
+ * @property {string|null} selectedId
+ * @property {CodeMapGrain} grain
+ * @property {string[]} expandedIds
+ * @property {string} navigatorFilter
+ * @property {string|null} navigatorFocusedId
+ * @property {CodeMapViewport|null} viewport
+ * @property {string|null} hoveredSessionId - transient; set/cleared by `hover-session`, never persisted to the route.
+ * @property {string|null} selectedSessionId - lingers after the pointer leaves; route-persisted (shareable deep link).
+ * @property {string[]} expandedCommitSessions - disclosure keys: commit hashes for sessions, `files:<hash>` for touched files, and `ranked:all` for the ranked-list cap.
+ * @property {string[]} expandedGhostGroups - successor commit hashes with their ghost group expanded.
+ * @property {CodeMapRankMode} rankMode - ranked-entry-list scoring mode.
+ * @property {string|null} scentFilter - one `SCENT_TAGS` member, or null for no filter.
+ */
+/** @typedef {{node:import('./types.js').MapNodePayload, depth:number, parentId:string|null, childIds:string[], hasChildren:boolean, canExpand:boolean, forcedOpen:boolean, expanded:boolean}} CodeMapNavigatorRow */
+/** @typedef {{orderedIds:string[], rootIds:string[], childIdsByParent:Record<string,string[]>, depthById:Record<string,number>}} CodeMapHierarchy */
+/** @typedef {{allNodes:import('./types.js').MapNodePayload[], nodes:import('./types.js').MapNodePayload[], visibleIds:string[], selectedId:string|null, grain:CodeMapGrain, expandedIds:string[], viewport:CodeMapViewport|null, hierarchy:CodeMapHierarchy}} CodeMapCanvasView */
+/** @typedef {{state:CodeMapState, rows:CodeMapNavigatorRow[], focusedId:string|null, selected:import('./types.js').MapNodePayload|null, staleSelectedId:string|null, canvas:CodeMapCanvasView}} CodeMapView */
+export const CODE_MAP_STATE_VERSION: 1;
+export const CODE_MAP_VIEWPORT_SCALE: Readonly<{
+    min: 0.35;
+    max: 2.4;
+}>;
+export const CODE_MAP_GRAIN_DEPTH: Readonly<{
+    project: 0;
+    package: 1;
+    file: 1;
+}>;
+export type TimelineHighlight = {
+    sessionId: string | null;
+    commitHashes: string[];
+    ghostHashes: string[];
+    edges: Array<{
+        sessionId: string;
+        commitHash: string;
+        ghost?: boolean;
+    }>;
+};
+export type CodeMapPresentation = "navigator" | "canvas";
+export type CodeMapGrain = "project" | "package" | "file";
+export type CodeMapViewport = {
+    scale: number;
+    panX: number;
+    panY: number;
+};
+export type CodeMapRankMode = "relevance" | "debt" | "churn";
+export type MapNodePayload = import("./types.js").MapNodePayload;
+/**
+ * The COMPLETE public timeline/ranking action surface. Frozen here: names are
+ * consumed downstream (the timeline surface, the ranked entry list) and are never renamed.
+ */
+export type CodeMapAction = {
+    type: "replace" | "hydrate";
+    state: Partial<CodeMapState>;
+} | {
+    type: "set-presentation";
+    presentation: CodeMapPresentation;
+} | {
+    type: "select" | "toggle-expanded" | "open-in-map";
+    id: string;
+} | {
+    type: "focus";
+    id: string | null;
+} | {
+    type: "clear-selection";
+} | {
+    type: "set-filter";
+    filter: string;
+} | {
+    type: "set-expanded";
+    ids: Iterable<string>;
+} | {
+    type: "set-grain";
+    grain: CodeMapGrain;
+} | {
+    type: "set-viewport";
+    viewport: CodeMapViewport | null;
+} | {
+    type: "reveal";
+    id: string;
+    grain: CodeMapGrain;
+    expandedIds: Iterable<string>;
+} | {
+    type: "hover-session";
+    sessionId: string | null;
+} | {
+    type: "select-session";
+    sessionId: string | null;
+} | {
+    type: "toggle-commit-sessions";
+    commitHash: string;
+} | {
+    type: "toggle-ghost-group";
+    successorHash: string;
+} | {
+    type: "set-rank-mode";
+    rankMode: CodeMapRankMode;
+} | {
+    type: "set-scent-filter";
+    scentFilter: string | null;
+} | {
+    type: "set-rank-expanded";
+    expanded: boolean;
+};
+export type CodeMapState = {
+    version: 1;
+    presentation: CodeMapPresentation;
+    selectedId: string | null;
+    grain: CodeMapGrain;
+    expandedIds: string[];
+    navigatorFilter: string;
+    navigatorFocusedId: string | null;
+    viewport: CodeMapViewport | null;
+    /**
+     * - transient; set/cleared by `hover-session`, never persisted to the route.
+     */
+    hoveredSessionId: string | null;
+    /**
+     * - lingers after the pointer leaves; route-persisted (shareable deep link).
+     */
+    selectedSessionId: string | null;
+    /**
+     * - disclosure keys: commit hashes for sessions, `files:<hash>` for touched files, and `ranked:all` for the ranked-list cap.
+     */
+    expandedCommitSessions: string[];
+    /**
+     * - successor commit hashes with their ghost group expanded.
+     */
+    expandedGhostGroups: string[];
+    /**
+     * - ranked-entry-list scoring mode.
+     */
+    rankMode: CodeMapRankMode;
+    /**
+     * - one `SCENT_TAGS` member, or null for no filter.
+     */
+    scentFilter: string | null;
+};
+export type CodeMapNavigatorRow = {
+    node: import("./types.js").MapNodePayload;
+    depth: number;
+    parentId: string | null;
+    childIds: string[];
+    hasChildren: boolean;
+    canExpand: boolean;
+    forcedOpen: boolean;
+    expanded: boolean;
+};
+export type CodeMapHierarchy = {
+    orderedIds: string[];
+    rootIds: string[];
+    childIdsByParent: Record<string, string[]>;
+    depthById: Record<string, number>;
+};
+export type CodeMapCanvasView = {
+    allNodes: import("./types.js").MapNodePayload[];
+    nodes: import("./types.js").MapNodePayload[];
+    visibleIds: string[];
+    selectedId: string | null;
+    grain: CodeMapGrain;
+    expandedIds: string[];
+    viewport: CodeMapViewport | null;
+    hierarchy: CodeMapHierarchy;
+};
+export type CodeMapView = {
+    state: CodeMapState;
+    rows: CodeMapNavigatorRow[];
+    focusedId: string | null;
+    selected: import("./types.js").MapNodePayload | null;
+    staleSelectedId: string | null;
+    canvas: CodeMapCanvasView;
+};

package/dist/lib/types/graph/graphContractPolicy.d.ts

@@ -0,0 +1,24 @@
+/** @param {Array<{kind:string, provenance:string}>} insights */
+export function assertInsightContractValues(insights: Array<{
+    kind: string;
+    provenance: string;
+}>): void;
+/** @param {Array<{readAttribution:string, readState:string}>} nodes */
+export function assertRankingContractValues(nodes: Array<{
+    readAttribution: string;
+    readState: string;
+}>): void;
+/** @typedef {import('@peasant-labs/schema').InsightKind} InsightKind */
+/** @typedef {import('@peasant-labs/schema').InsightProvenance} InsightProvenance */
+/** @typedef {import('@peasant-labs/schema').ReadAttributionState} ReadAttributionState */
+/** @typedef {import('@peasant-labs/schema').ReadStateGrade} ReadStateGrade */
+/** @typedef {{markerClass:string}} InsightProvenancePresentation */
+export const INSIGHT_KIND_LABELS: Readonly<Readonly<Record<"unusual" | "decision" | "friction" | "retry_loop", string>>>;
+export const INSIGHT_PROVENANCE_PRESENTATIONS: Readonly<Readonly<Record<"mechanical" | "mined", InsightProvenancePresentation>>>;
+export type InsightKind = import("@peasant-labs/schema").InsightKind;
+export type InsightProvenance = import("@peasant-labs/schema").InsightProvenance;
+export type ReadAttributionState = import("@peasant-labs/schema").ReadAttributionState;
+export type ReadStateGrade = import("@peasant-labs/schema").ReadStateGrade;
+export type InsightProvenancePresentation = {
+    markerClass: string;
+};

package/dist/lib/types/graph/index.d.ts

@@ -1,11 +1,28 @@
 export { default as Changes } from "./Changes.jsx";
 export { default as ChangeDetail } from "./ChangeDetail.jsx";
+export { default as CodeMapNavigator } from "./CodeMapNavigator.jsx";
+export { assertTimelineNavigationAction } from "./timelineNavigation.js";
+export { default as SessionLane } from "./SessionLane.jsx";
+export { default as GhostCommitNode } from "./GhostCommitNode.jsx";
+export { default as GhostGroup } from "./GhostGroup.jsx";
+export { default as HighlightEdge } from "./HighlightEdge.jsx";
+export { default as SessionOverflowDisclosure } from "./SessionOverflowDisclosure.jsx";
+export { default as RankedRow } from "./RankedRow.jsx";
+export { default as ScentTag } from "./ScentTag.jsx";
+export { default as RankModeControl } from "./RankModeControl.jsx";
+export { default as InsightPanel } from "./InsightPanel.jsx";
+export { default as TouchedFileCluster } from "./TouchedFileCluster.jsx";
 export type MapNodeKind = import("./types.js").MapNodeKind;
 export type ChangeBinding = import("./types.js").ChangeBinding;
 export type EdgeViolationKind = import("./types.js").EdgeViolationKind;
 export type FileChangeStatus = import("./types.js").FileChangeStatus;
 export type DiffLineKind = import("./types.js").DiffLineKind;
+export type InsightKind = import("@peasant-labs/schema").InsightKind;
+export type InsightProvenance = import("@peasant-labs/schema").InsightProvenance;
+export type ReadAttributionState = import("@peasant-labs/schema").ReadAttributionState;
+export type ReadStateGrade = import("@peasant-labs/schema").ReadStateGrade;
 export type CommitRefPayload = import("./types.js").CommitRefPayload;
+export type TimelineSessionPayload = import("./types.js").TimelineSessionPayload;
 export type MapEdgePayload = import("./types.js").MapEdgePayload;
 export type ActivityEdgePayload = import("./types.js").ActivityEdgePayload;
 export type EdgeViolationPayload = import("./types.js").EdgeViolationPayload;
@@ -23,8 +40,25 @@ export type DiffLinePayload = import("./types.js").DiffLinePayload;
 export type DiffHunkPayload = import("./types.js").DiffHunkPayload;
 export type ChangeDiffPayload = import("./types.js").ChangeDiffPayload;
 export type CodeMapPayload = import("./types.js").CodeMapPayload;
+export type CodeMapPresentation = import("./codeMapState.js").CodeMapPresentation;
+export type CodeMapGrain = import("./codeMapState.js").CodeMapGrain;
+export type CodeMapViewport = import("./codeMapState.js").CodeMapViewport;
+export type CodeMapState = import("./codeMapState.js").CodeMapState;
+export type CodeMapAction = import("./codeMapState.js").CodeMapAction;
+export type CodeMapNavigatorRow = import("./codeMapState.js").CodeMapNavigatorRow;
+export type CodeMapCanvasView = import("./codeMapState.js").CodeMapCanvasView;
+export type CodeMapView = import("./codeMapState.js").CodeMapView;
+export type TimelineNavigationAction = import("./timelineNavigation.js").TimelineNavigationAction;
+export type CodeMapRankMode = import("./codeMapState.js").CodeMapRankMode;
+export type TimelineHighlight = import("./codeMapState.js").TimelineHighlight;
+export type RankInputNode = import("./ranking.js").RankInputNode;
+export type RankedRowData = import("./ranking.js").RankedRow;
+export type DebtState = import("./ranking.js").DebtState;
 export { default as CodeMap, codeMapPayloadToMapData } from "./CodeMap.jsx";
 export { default as CodeMapComposition, DefaultMapLegend } from "./CodeMapComposition.jsx";
+export { CODE_MAP_STATE_VERSION, CODE_MAP_VIEWPORT_SCALE, isCodeMapViewportScale, codeMapStatesEqual, createCodeMapState, reduceCodeMapState, deriveCodeMapView, deriveTimelineHighlight, resolveEscapeAction } from "./codeMapState.js";
 export { GraphAppShell, GraphSectionNav, GRAPH_APP_SECTIONS } from "../inuse/InUseShell.jsx";
 export { buildChangesGraph, humanizeAge } from "./changeGraph.js";
-export { MAP_NODE_KINDS, CHANGE_BINDINGS, EDGE_VIOLATION_KINDS, FILE_CHANGE_STATUSES, DIFF_LINE_KINDS } from "./types.js";
+export { DOI_WEIGHTS, DEBT_VIEWED, COVERAGE_CAP, RECENCY_HALF_LIFE_DAYS, RANK_FLOOR, RANK_CAP, SCENT_TAGS, debtState, debt, coverage, hunkClears, partialReadHoverText, debtHoverText, scentTagsFor, rankMapNodesIntrinsic, deriveRankedRows, rankMapNodes, gateRankedRows } from "./ranking.js";
+export { assertChangeDetailPayloadEnums, assertChangeDiffPayloadEnums, assertCodeMapPayloadEnums, MAP_NODE_KINDS, CHANGE_BINDINGS, EDGE_VIOLATION_KINDS, FILE_CHANGE_STATUSES, DIFF_LINE_KINDS } from "./types.js";
+export { MapNodeKind, AllMapNodeKinds, isMapNodeKind, ChangeBinding, AllChangeBindings, isChangeBinding, EdgeViolationKind, AllEdgeViolationKinds, isEdgeViolationKind, FileChangeStatus, AllFileChangeStatuses, isFileChangeStatus, DiffLineKind, AllDiffLineKinds, isDiffLineKind, InsightKind, AllInsightKinds, isInsightKind, InsightProvenance, AllInsightProvenances, isInsightProvenance, ReadAttributionState, AllReadAttributionStates, isReadAttributionState, ReadStateGrade, AllReadStateGrades, isReadStateGrade } from "@peasant-labs/schema";

package/dist/lib/types/graph/ranking.d.ts

@@ -0,0 +1,222 @@
+/**
+ * Comprehension-debt state resolution over MapNode scalars only (no per-hunk
+ * wire data required; the formula is pure over ReadState plus the three
+ * region-coverage counts).
+ * @param {RankInputNode} node
+ * @returns {DebtState}
+ */
+export function debtState(node: RankInputNode): DebtState;
+/**
+ * Comprehension-debt magnitude. `state` must be the value `debtState(node)` returned for
+ * the SAME node (kept as a parameter, not recomputed, so callers that already
+ * branched on `debtState` never pay for or risk re-deriving it differently).
+ * @param {RankInputNode} node @param {DebtState} state
+ * @returns {number}
+ */
+export function debt(node: RankInputNode, state: DebtState): number;
+/** `coverage`: an unattributable hunk caps it strictly below 1 (COVERAGE_CAP). @param {RankInputNode} node */
+export function coverage(node: RankInputNode): number;
+/** `hunkClears`: the named state gate, never shadowed by a fallback. @param {RankInputNode} node */
+export function hunkClears(node: RankInputNode): boolean;
+/**
+ * The path-conditioned partial-read hover copy. Returns null
+ * for every non-`partial-read` state. Callers only call this after checking
+ * `debtState(node) === 'partial-read'`.
+ * @param {RankInputNode} node
+ * @returns {string|null}
+ */
+export function partialReadHoverText(node: RankInputNode): string | null;
+/**
+ * State-specific honesty copy for every visible debt tag. The copy describes
+ * recorded evidence and always remains a prompt, never a claim about a person.
+ * @param {RankInputNode} node
+ * @param {DebtState} state
+ * @returns {string|null}
+ */
+export function debtHoverText(node: RankInputNode, state: DebtState): string | null;
+/**
+ * Up to two scent tags per row, including the softened `viewed`
+ * treatment and the multi-state debt vocabulary. The `partial-read` state
+ * reuses the strong/softened tag with the path-conditioned hover. No new
+ * tag for the partial state.
+ * @param {RankInputNode} node @param {DebtState} state @param {{focusId?:string|null, parentOf?:Map<string,string|null>, distanceToFocus?:number|null, maxTouch?:number, hoveredOrSelectedSessionId?:string|null}} [context]
+ * @returns {string[]}
+ */
+export function scentTagsFor(node: RankInputNode, state: DebtState, context?: {
+    focusId?: string | null;
+    parentOf?: Map<string, string | null>;
+    distanceToFocus?: number | null;
+    maxTouch?: number;
+    hoveredOrSelectedSessionId?: string | null;
+}): string[];
+/**
+ * Computes only payload/rank-mode intrinsic terms. A caller can memoize this
+ * object by node-array identity and rank mode; focus, filter, hover and session
+ * selection belong exclusively to `deriveRankedRows` below.
+ * @param {RankInputNode[]} nodes
+ * @param {{rankMode?: RankMode, nowMs?: number}} [options]
+ * @returns {IntrinsicRanking}
+ */
+export function rankMapNodesIntrinsic(nodes: RankInputNode[], options?: {
+    rankMode?: RankMode;
+    nowMs?: number;
+}): IntrinsicRanking;
+/**
+ * Applies focus distance, active-session scent, sort, and filter to memoized
+ * intrinsic terms. Ties break by node id; all-equal intrinsic terms stay 0.
+ * @param {IntrinsicRanking} intrinsicRanking
+ * @param {{focusId?: string|null, scentFilter?: string|null, hoveredOrSelectedSessionId?: string|null}} [options]
+ * @returns {RankedRow[]}
+ */
+export function deriveRankedRows(intrinsicRanking: IntrinsicRanking, options?: {
+    focusId?: string | null;
+    scentFilter?: string | null;
+    hoveredOrSelectedSessionId?: string | null;
+}): RankedRow[];
+/** Compatibility composition of the public two-phase ranking API.
+ * @param {RankInputNode[]} nodes
+ * @param {{rankMode?: RankMode, focusId?: string|null, scentFilter?: string|null, hoveredOrSelectedSessionId?: string|null, nowMs?: number}} [options]
+ */
+export function rankMapNodes(nodes: RankInputNode[], options?: {
+    rankMode?: RankMode;
+    focusId?: string | null;
+    scentFilter?: string | null;
+    hoveredOrSelectedSessionId?: string | null;
+    nowMs?: number;
+}): RankedRow[];
+/**
+ * Threshold gating: show `DOI >= max(0.25, 0.5*maxDOI)`, floor 5, cap 25,
+ * then a single "show all N files" expander. Deterministic, fixture-pinnable.
+ * In debt mode, known debt is included before thresholded unknown/clear rows,
+ * so threshold and cap gating cannot hide actionable evidence behind unknowns.
+ * @param {RankedRow[]} rows @param {{expanded?: boolean, rankMode?:RankMode}} [options]
+ * @returns {{visible: RankedRow[], total: number, overflowCount: number}}
+ */
+export function gateRankedRows(rows: RankedRow[], options?: {
+    expanded?: boolean;
+    rankMode?: RankMode;
+}): {
+    visible: RankedRow[];
+    total: number;
+    overflowCount: number;
+};
+/** @typedef {import('@peasant-labs/schema').ReadAttributionState} ReadAttributionState */
+/** @typedef {import('@peasant-labs/schema').ReadStateGrade} ReadStateGrade */
+/** @typedef {'relevance'|'debt'|'churn'} RankMode */
+/** @typedef {'unknown'|'none'|'reviewed'|'partial-read'|'viewed'|'no-recorded-read'} DebtState */
+/**
+ * One node's ranking-relevant scalars. Every field is read-only input; nothing
+ * here is mutated. `lastTouchMs` and `parent` are optional client-side hints
+ * hints. An absent value means "no recency/tree-focus
+ * signal", never a fabricated 0.
+ * @typedef {object} RankInputNode
+ * @property {string} id
+ * @property {string} name
+ * @property {number} touchCount
+ * @property {number} effortDensity - 0..1
+ * @property {number} agentEditedCount
+ * @property {number} readCount
+ * @property {ReadAttributionState} readAttribution
+ * @property {ReadStateGrade} readState - composed effective read-state grade for the CURRENT content version
+ * @property {number} changedRegionCount - total changed regions (Hall)
+ * @property {number} attributedRegionCount - attributed regions (H, M)
+ * @property {number} reviewedRegionCount - reviewed-of-attributed regions (N)
+ * @property {number} [lastTouchMs]
+ * @property {string|null} [parent]
+ * @property {string|null} [recentSessionId] - the session that most recently edited this node, if known
+ */
+/** @typedef {{id:string, name:string, doi:number, debtState:DebtState, debt:number, coverage:number, hunkClears:boolean, scentTags:string[], hoverText:string|null}} RankedRow */
+/** @typedef {{node:RankInputNode, intrinsic:number, debtState:DebtState, debt:number, coverage:number, hunkClears:boolean, hoverText:string|null}} IntrinsicRankedNode */
+/** @typedef {{rankMode:RankMode, rows:IntrinsicRankedNode[], parentOf:Map<string,string|null>, maxTouch:number}} IntrinsicRanking */
+/** DOI (degree-of-interest) term weights. Sum to 1.0 and are fixture-pinned. */
+export const DOI_WEIGHTS: Readonly<{
+    touch: 0.35;
+    effortDensity: 0.25;
+    debt: 0.25;
+    recency: 0.15;
+}>;
+/** Comprehension-debt constants, declared beside DOI_WEIGHTS per the frozen contract. */
+export const DEBT_VIEWED: 0.5;
+export const COVERAGE_CAP: 0.9;
+/** Recency half-life, days. */
+export const RECENCY_HALF_LIFE_DAYS: 14;
+/** Threshold-gating constants. */
+export const RANK_FLOOR: 5;
+export const RANK_CAP: 25;
+/**
+ * The seven-member scent-tag closed set. Exhaustiveness is enforced by
+ * `code-map-ranking.yaml`'s guard: every member must have at least one
+ * derivation case, so a future eighth tag without a case reddens.
+ * @type {readonly string[]}
+ */
+export const SCENT_TAGS: readonly string[];
+export type ReadAttributionState = import("@peasant-labs/schema").ReadAttributionState;
+export type ReadStateGrade = import("@peasant-labs/schema").ReadStateGrade;
+export type RankMode = "relevance" | "debt" | "churn";
+export type DebtState = "unknown" | "none" | "reviewed" | "partial-read" | "viewed" | "no-recorded-read";
+/**
+ * One node's ranking-relevant scalars. Every field is read-only input; nothing
+ * here is mutated. `lastTouchMs` and `parent` are optional client-side hints
+ * hints. An absent value means "no recency/tree-focus
+ * signal", never a fabricated 0.
+ */
+export type RankInputNode = {
+    id: string;
+    name: string;
+    touchCount: number;
+    /**
+     * - 0..1
+     */
+    effortDensity: number;
+    agentEditedCount: number;
+    readCount: number;
+    readAttribution: ReadAttributionState;
+    /**
+     * - composed effective read-state grade for the CURRENT content version
+     */
+    readState: ReadStateGrade;
+    /**
+     * - total changed regions (Hall)
+     */
+    changedRegionCount: number;
+    /**
+     * - attributed regions (H, M)
+     */
+    attributedRegionCount: number;
+    /**
+     * - reviewed-of-attributed regions (N)
+     */
+    reviewedRegionCount: number;
+    lastTouchMs?: number;
+    parent?: string | null;
+    /**
+     * - the session that most recently edited this node, if known
+     */
+    recentSessionId?: string | null;
+};
+export type RankedRow = {
+    id: string;
+    name: string;
+    doi: number;
+    debtState: DebtState;
+    debt: number;
+    coverage: number;
+    hunkClears: boolean;
+    scentTags: string[];
+    hoverText: string | null;
+};
+export type IntrinsicRankedNode = {
+    node: RankInputNode;
+    intrinsic: number;
+    debtState: DebtState;
+    debt: number;
+    coverage: number;
+    hunkClears: boolean;
+    hoverText: string | null;
+};
+export type IntrinsicRanking = {
+    rankMode: RankMode;
+    rows: IntrinsicRankedNode[];
+    parentOf: Map<string, string | null>;
+    maxTouch: number;
+};

package/dist/lib/types/graph/timelineNavigation.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Fail closed at untyped JavaScript boundaries before a host interprets a timeline gesture.
+ * The accepted object shapes are exact so additions require an explicit contract change.
+ *
+ * @param {unknown} value
+ * @returns {asserts value is TimelineNavigationAction}
+ */
+export function assertTimelineNavigationAction(value: unknown): asserts value is TimelineNavigationAction;
+export type TimelineNavigationAction = {
+    type: "open-change";
+    change: {
+        id: string;
+        branch: string | null;
+    };
+} | {
+    type: "open-session";
+    sessionId: string;
+    source: {
+        kind: "commit";
+        commit: {
+            id: string;
+            branch: string | null;
+        };
+    } | {
+        kind: "unlinked";
+    } | {
+        kind: "outside-window";
+    };
+} | {
+    type: "open-map";
+} | {
+    type: "show-older";
+};