@athenaintel/react 0.41.3 → 0.42.2

package/dist/references/src/anchors/types.d.ts

@@ -0,0 +1,474 @@
+/**
+ * Anchor types — Level 2 of the reference system.
+ *
+ * Each anchor describes a specific location within an asset.
+ * Discriminated union on `type`. Ordered alphabetically.
+ *
+ * Property names use camelCase; the `type` discriminator string stays snake_case
+ * (it's a version identifier, not a property name).
+ */
+export type CellAnchor = {
+    type: 'cell';
+    cellId: string;
+};
+export type CellRangeAnchor = {
+    type: 'cell_range';
+    startCellId: string;
+    endCellId: string;
+};
+export type CommentAnchor = {
+    type: 'comment';
+    threadId: string;
+    commentId: string;
+};
+export type CommentThreadAnchor = {
+    type: 'comment_thread';
+    threadId: string;
+};
+/**
+ * An inclusive, 1-based line range of one file of a repository source — a
+ * GitHub `catalog` asset whose files Clio indexes
+ * (`docs/clio/21-repository-source.md`). `path` is the repo-relative,
+ * `/`-separated file path: structure, not content. Distinct from the
+ * path-less `line_range` so a reader that does not know the kind fails closed
+ * instead of dropping the file. Bounds, path grammar and the byte cap are
+ * shared with Clio's `LineRangeLocator` (`./file-line-range.ts`).
+ *
+ * Wire form (canonical — parameters sorted, as Clio writes it):
+ * `anchor=file_line_range&end_line=<m>&path=<path>&start_line=<n>`.
+ */
+export type FileLineRangeAnchor = {
+    type: 'file_line_range';
+    path: string;
+    startLine: number;
+    endLine: number;
+};
+export type LineAnchor = {
+    type: 'line';
+    line: number;
+};
+export type LineRangeAnchor = {
+    type: 'line_range';
+    startLine: number;
+    endLine: number;
+};
+/**
+ * A single chat message in a session transcript.
+ *
+ * `messageId` is the **Athena message tracking id** — the same uuid4 that
+ * appears as `user_message_tracking_id` / `ai_message_tracking_id` in Keryx
+ * activity attributions (built by `build_agent_attributions`,
+ * agora/services/keryx/client.py), as `trackingId` on session Y.Doc
+ * liveMessages, as the `data-message-tracking-id` DOM attribute, and as the
+ * existing `scroll_to_message` URL param in Olympus. It is NOT the LangChain
+ * checkpoint `message.id`.
+ *
+ * Wire form: `anchor=msg&msg_id=…` (the pre-rename spellings
+ * `anchor=message&message_id=…` are still parsed).
+ */
+export type MessageAnchor = {
+    type: 'msg';
+    messageId: string;
+};
+/**
+ * Inclusive span of session messages in transcript order. Both ids are
+ * Athena message tracking ids (see `MessageAnchor`).
+ */
+export type MessageRangeAnchor = {
+    type: 'msg_range';
+    startMessageId: string;
+    endMessageId: string;
+};
+/**
+ * One top-level block (paragraph, heading, list, table, code fence, …) of a
+ * session message's markdown body. `messageId` is the Athena message tracking
+ * id (see `MessageAnchor`); `block` is the 1-based position among the
+ * message's top-level blocks. `hash` is an optional short fingerprint of the
+ * block's normalized text (see `messageBlockHash`) so consumers can detect
+ * that the block at that position no longer holds the linked content.
+ *
+ * URL params: `msg_id`, `block`, `hash`.
+ */
+export type MessageBlockAnchor = {
+    type: 'msg_block';
+    messageId: string;
+    block: number;
+    hash?: string;
+};
+/**
+ * A heading-delimited section of a session message: the heading whose slug
+ * (see `messageHeadingSlug`) equals `heading`, through the block before the
+ * next heading of the same or a higher level. `nth` (1-based) disambiguates
+ * repeated headings; absent ⇒ first.
+ *
+ * URL params: `msg_id`, `heading`, `nth`.
+ */
+export type MessageSectionAnchor = {
+    type: 'msg_section';
+    messageId: string;
+    heading: string;
+    nth?: number;
+};
+/**
+ * An exact text span inside a session message. `text` is the quoted excerpt,
+ * matched against the message's whitespace-normalized plain text (see
+ * `normalizeMessageText`). Optional `block` narrows the search to one
+ * top-level block (1-based); optional `prefix` / `suffix` are the normalized
+ * text immediately before / after the span, used to pick between repeated
+ * occurrences. Consumers fall back to the block, then the whole message, when
+ * the span can't be found.
+ *
+ * URL params: `msg_id`, `text`, `block`, `prefix`, `suffix`.
+ */
+export type MessageTextAnchor = {
+    type: 'msg_text';
+    messageId: string;
+    text: string;
+    block?: number;
+    prefix?: string;
+    suffix?: string;
+};
+export type PageAnchor = {
+    type: 'page';
+    page: number;
+};
+/**
+ * A file path inside an asset, optionally narrowed to a 1-based source
+ * location. `column` is only meaningful when `line` is present.
+ */
+export type PathAnchor = {
+    type: 'path';
+    path: string;
+    line?: number;
+    column?: number;
+};
+export type PageRangeAnchor = {
+    type: 'page_range';
+    startPage: number;
+    endPage: number;
+};
+/** Coordinate unit for a `page_rect` anchor. Absent ⇒ `percent`. */
+export declare const PageRectUnit: {
+    /** Percentages of the page dimensions (0-100). Resolution-independent. */
+    readonly Percent: 'percent';
+    /**
+     * PDF points (1/72"), the unit of the legacy `bbox_left/bbox_top/...`
+     * citation-URL params and of PDF viewer page coordinates.
+     */
+    readonly Point: 'point';
+};
+export type PageRectUnit = (typeof PageRectUnit)[keyof typeof PageRectUnit];
+/**
+ * Rectangular region on a specific page. `x`/`y`/`width`/`height` are in
+ * `unit` coordinates — percentages of the page dimensions (0-100) when
+ * `unit` is absent or `percent`, PDF points when `unit` is `point`.
+ */
+export type PageRectAnchor = {
+    type: 'page_rect';
+    page: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    unit?: PageRectUnit;
+};
+/**
+ * A quoted text span on a specific page. `text` is the selected excerpt,
+ * re-located by text search when the anchor is resolved. Optional `prefix` /
+ * `suffix` are the normalized text immediately before / after the span, used
+ * to pick between repeated occurrences of `text` on the page (the same
+ * contract as `MessageTextAnchor`). Optional `hash` is a short fingerprint of
+ * the cited unit's normalized text (the `MessageBlockAnchor` pattern:
+ * `messageBlockHash`, 32-bit FNV-1a as 8 hex chars) so a consumer can tell a
+ * stale citation from a live one and fall back to text search. The anchor
+ * never stores geometry; rectangles are derived when it is resolved.
+ *
+ * URL params: `page`, `text`, `prefix`, `suffix`, `hash`.
+ */
+export type PageTextAnchor = {
+    type: 'page_text';
+    page: number;
+    text: string;
+    prefix?: string;
+    suffix?: string;
+    hash?: string;
+};
+export type PmNodeAnchor = {
+    type: 'pm_node';
+    nodeId: string;
+};
+export type PmNodeRangeAnchor = {
+    type: 'pm_node_range';
+    startNodeId: string;
+    endNodeId: string;
+};
+/** Pixel-based region anchor for images. Coordinates relative to natural image dimensions. */
+export type PixelRangeAnchor = {
+    type: 'pixel_range';
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/** ProseMirror mark pointer; composite `markType:instanceId` (e.g. CommentsKit `thread` + thread id). */
+export type PmMarkAnchor = {
+    type: 'pm_mark';
+    markId: string;
+};
+/** Percentage-based region (0-100). Resolution-independent. */
+export type RectAnchor = {
+    type: 'rect';
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/**
+ * Named slice of an asset's persisted metadata (e.g. a computer asset's `status` / `ports`
+ * section), or a section of a recording's generated notes (`decisions`, `action_items`,
+ * `open_questions`, `notes`). `topic` is the 1-based `### topic` under a recording's Notes
+ * (`section=notes&topic=2`), as Clio's notes hits name it; absent for every other section.
+ */
+export type SectionAnchor = {
+    type: 'section';
+    section: string;
+    topic?: number;
+};
+/**
+ * How a cited value relates to a generative (query) anchor's result.
+ *
+ * Absent ⇒ consumers MUST treat it as `supporting`. The (de)serializer never
+ * defaults it, so round-trips stay exact.
+ */
+export declare const QueryResultRelationship: {
+    /** The cell value IS (a cell of) the query result — a 1:1 extraction. */
+    readonly Exact: 'exact';
+    /**
+     * The cell value is authored (e.g. a narrative claim); the query result is
+     * supporting evidence / justification, not the value itself. Re-running the
+     * query is read-only verification and never replaces the cell value.
+     */
+    readonly Supporting: 'supporting';
+};
+export type QueryResultRelationship = (typeof QueryResultRelationship)[keyof typeof QueryResultRelationship];
+/**
+ * Generative anchor — a value derived from a semantic-model (Cube.js) query.
+ *
+ * Unlike positional anchors (page/cell/line), the "location" is the
+ * transformation itself: the full Cube.js query spec that was run. Re-running
+ * it is read-only verification; it never overwrites the cited value.
+ */
+export type SemanticQueryAnchor = {
+    type: 'semantic_query';
+    /** The full Cube.js query spec that produced the result (the codified transformation). */
+    query: Record<string, unknown>;
+    /** Cited measure/dimension id, e.g. `orders.total_revenue`. Omit ⇒ the whole result is the evidence. */
+    field?: string;
+    /** Dimension/key values identifying the cited row. Robust to re-ordering, unlike `rowIndex`. */
+    rowKey?: Record<string, string>;
+    /** Positional fallback row selector. */
+    rowIndex?: number;
+    /** Whether the cell value equals the result (`exact`) or is authored evidence (`supporting`). */
+    relationship?: QueryResultRelationship;
+    /** Provenance: semantic-model schema version at run time. */
+    schemaVersion?: number;
+    /** Provenance: sha256 of the deployed YAML at run time, for drift detection. */
+    schemaHash?: string;
+    /**
+     * Provenance for lakehouse-backed models: each source table's Iceberg identity
+     * and snapshot when the value was computed (`"<namespace>.<table>"` →
+     * `"<table_uuid>:<snapshot_id>"`, the snapshot empty for a table never written).
+     * Compared with the live tables by the freshness check.
+     */
+    sourceSnapshots?: Record<string, string>;
+    /** Provenance: the result's "data as of" instant (ISO-8601 UTC) at capture. */
+    dataAsOf?: string;
+};
+/**
+ * One or more shapes on a presentation slide. `shapeIds` are stable Yjs
+ * ElementIds (the SDK's `shape.shape_id`) and resolve the anchor on their
+ * own; `slideId` / `slideIndex` (1-based) are optional refinements.
+ */
+export type ShapeAnchor = {
+    type: 'shape';
+    slideId?: string;
+    slideIndex?: number;
+    shapeIds: string[];
+};
+/**
+ * A single cell. `chartId` (`chart=`) names the chart anchored at the cell
+ * when the place is that chart, not the cell's value: a chart sits right of
+ * and below its anchor cell, so a reader reveals it from that corner.
+ */
+export type SheetCellAnchor = {
+    type: 'sheet_cell';
+    sheetId: number;
+    cell: string;
+    chartId?: string;
+};
+export type SheetRangeAnchor = {
+    type: 'sheet_range';
+    sheetId: number;
+    range: string;
+    /**
+     * The spreadsheet engine's shift-log frontier (writer id → seq, `RncEngine.shiftLogFrontier`) the
+     * moment `range` was taken, so a reader with the live engine can resolve the range to its current
+     * coordinates after rows/columns were inserted or deleted since (`RncEngine.transformRange`).
+     * Absent on an anchor taken without an engine, which resolves to `range` as stored.
+     */
+    frontier?: Record<string, number>;
+};
+/** A whole worksheet / sheet tab in a spreadsheet. */
+export type SheetTabAnchor = {
+    type: 'sheet_tab';
+    sheetId: number;
+};
+/**
+ * A named Excel table (ListObject) within a worksheet. Stable identity:
+ * the table's name survives sorts, inserts, and row additions that would
+ * break a raw `sheet_range`. Use this anchor in preference to
+ * `sheet_range` whenever the user is binding to a structured table.
+ *
+ * `fallbackRange` is an optional A1-style range used by resolvers when
+ * the table has been deleted or renamed — best-effort recovery.
+ */
+export type SheetTableAnchor = {
+    type: 'sheet_table';
+    sheetId: number;
+    tableName: string;
+    fallbackRange?: string;
+};
+/**
+ * One table of an Orion lakehouse namespace, addressed on the namespace asset
+ * (tables have no asset rows). `table` is the name within the namespace;
+ * `tableUuid` is the Iceberg table UUID, the stable identity that detects a
+ * drop-and-recreate or rename; `snapshotId` pins a read to one Iceberg
+ * snapshot (an unsupported pinned read is rejected, never served from current
+ * data).
+ */
+export type LakehouseTableAnchor = {
+    type: 'lakehouse_table';
+    table: string;
+    tableUuid?: string;
+    snapshotId?: string;
+};
+/**
+ * A whole slide of a PPTX deck. `slideId` is the stable Yjs SlideId (the
+ * SDK's `slide.slide_id`); `slideIndex` is the 1-based display position.
+ * At least one must be present; producers should emit both when known.
+ */
+export type SlideAnchor = {
+    type: 'slide';
+    slideId?: string;
+    slideIndex?: number;
+};
+/**
+ * Generative anchor — a value derived from a SQL query.
+ *
+ * The transformation is the SQL text, carried inline or (preferred) as a
+ * governed, re-runnable `query_snippet` asset. Re-running it is read-only
+ * verification; it never overwrites the cited value.
+ */
+export type SqlQueryAnchor = {
+    type: 'sql_query';
+    /** The SQL that produced the result. Optional when `querySnippetAssetId` is set. */
+    sql?: string;
+    /** A re-runnable `query_snippet` asset that holds the SQL (preferred over inline `sql`). */
+    querySnippetAssetId?: string;
+    /** SQL dialect, e.g. `postgres`, `snowflake`. */
+    dialect?: string;
+    /** Cited result column name. Omit ⇒ the whole result is the evidence. */
+    field?: string;
+    /** Identifying column values for the cited row. Robust to re-ordering, unlike `rowIndex`. */
+    rowKey?: Record<string, string>;
+    /** Positional fallback row selector. */
+    rowIndex?: number;
+    /** Whether the cell value equals the result (`exact`) or is authored evidence (`supporting`). */
+    relationship?: QueryResultRelationship;
+};
+/** Time string in "H:MM:SS" / "MM:SS" / "M:SS" format. No plain seconds. */
+export type TimeAnchor = {
+    type: 'time';
+    time: string;
+};
+export type TimeRangeAnchor = {
+    type: 'time_range';
+    startTime: string;
+    endTime: string;
+};
+/**
+ * A tool invocation in a session transcript. `toolCallId` is the
+ * LangChain-native tool call id (the key used by session Y.Doc
+ * liveToolCalls), NOT an Athena message tracking id. `messageId` is the
+ * tracking id of the assistant message that issued the call, when the
+ * producer knows it (Keryx activity carries both as `tool_call_id` and
+ * `ai_message_tracking_id`); it lets a consumer still land on the owning
+ * message when the call itself is not in view (e.g. an abandoned branch).
+ */
+export type ToolCallAnchor = {
+    type: 'tool_call';
+    toolCallId: string;
+    messageId?: string;
+};
+export type Anchor = CellAnchor | CellRangeAnchor | CommentAnchor | CommentThreadAnchor | FileLineRangeAnchor | LineAnchor | LineRangeAnchor | MessageAnchor | MessageRangeAnchor | MessageBlockAnchor | MessageSectionAnchor | MessageTextAnchor | PageAnchor | PageRangeAnchor | PathAnchor | PageRectAnchor | PageTextAnchor | PixelRangeAnchor | PmNodeAnchor | PmNodeRangeAnchor | PmMarkAnchor | RectAnchor | SectionAnchor | SemanticQueryAnchor | ShapeAnchor | SheetCellAnchor | SheetRangeAnchor | SheetTabAnchor | SheetTableAnchor | LakehouseTableAnchor | SlideAnchor | SqlQueryAnchor | TimeAnchor | TimeRangeAnchor | ToolCallAnchor;
+export type AnchorType = Anchor['type'];
+export declare const AnchorType: {
+    readonly Cell: 'cell';
+    readonly CellRange: 'cell_range';
+    readonly Comment: 'comment';
+    readonly CommentThread: 'comment_thread';
+    readonly FileLineRange: 'file_line_range';
+    readonly Line: 'line';
+    readonly LineRange: 'line_range';
+    readonly Message: 'msg';
+    readonly MessageRange: 'msg_range';
+    readonly MessageBlock: 'msg_block';
+    readonly MessageSection: 'msg_section';
+    readonly MessageText: 'msg_text';
+    readonly Page: 'page';
+    readonly PageRange: 'page_range';
+    readonly Path: 'path';
+    readonly PageRect: 'page_rect';
+    readonly PageText: 'page_text';
+    readonly PixelRange: 'pixel_range';
+    readonly PmMark: 'pm_mark';
+    readonly PmNode: 'pm_node';
+    readonly PmNodeRange: 'pm_node_range';
+    readonly Rect: 'rect';
+    readonly Section: 'section';
+    readonly SemanticQuery: 'semantic_query';
+    readonly Shape: 'shape';
+    readonly SheetCell: 'sheet_cell';
+    readonly SheetRange: 'sheet_range';
+    readonly SheetTab: 'sheet_tab';
+    readonly SheetTable: 'sheet_table';
+    readonly LakehouseTable: 'lakehouse_table';
+    readonly Slide: 'slide';
+    readonly SqlQuery: 'sql_query';
+    readonly Time: 'time';
+    readonly TimeRange: 'time_range';
+    readonly ToolCall: 'tool_call';
+};
+/**
+ * Pre-rename session anchor spellings that are still accepted on input so
+ * links shared before the `msg*` rename keep resolving. Output always uses
+ * the current names (see `serialize.ts`).
+ */
+export declare const LEGACY_ANCHOR_TYPES: Readonly<Record<string, AnchorType>>;
+export declare function isAnchorType(value: unknown): value is AnchorType;
+/**
+ * Quick check: validates only the `type` discriminator string.
+ * For full structural validation, use `parseAnchor` from `./schemas`.
+ */
+export declare function isAnchor(value: unknown): value is Anchor;
+/** Runtime form of TimeAnchor with pre-computed seconds. */
+export type TimeAnchorSeconds = {
+    type: 'time_seconds';
+    timeSeconds: number;
+};
+/** Runtime form of TimeRangeAnchor with pre-computed seconds. */
+export type TimeRangeAnchorSeconds = {
+    type: 'time_range_seconds';
+    startTimeSeconds: number;
+    endTimeSeconds: number;
+};

package/dist/references/src/asset-bounds.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Asset bounds for anchor validation.
+ * Used when editing anchors — validates time inputs against duration,
+ * rect inputs against dimensions, etc.
+ */
+export type AssetBounds = {
+    type: 'audio' | 'video' | 'meeting' | 'phone_call' | 'browse' | 'desktop_session' | 'mobile_session';
+    /** Total duration in seconds */
+    duration: number;
+    /** Current playback position in seconds (optional, for "use current" default) */
+    currentTime?: number;
+} | {
+    type: 'image' | 'pdf';
+    /** Width in pixels */
+    width: number;
+    /** Height in pixels */
+    height: number;
+} | {
+    type: 'page_rect';
+    page: number;
+    width: number;
+    height: number;
+} | {
+    type: 'line' | 'line_range';
+    /** Total line count for validation (optional) */
+    lineCount?: number;
+};

package/dist/references/src/asset-links.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `@athenaintel/references/asset-links` — what a renderer of asset mentions
+ * and citations needs, with no schema validation behind it.
+ *
+ * An asset mention is `[@Label](…/dashboard/spaces/?asset_ids=…&type=…)` (or
+ * `mention://asset?id=…`); with an anchor it is a citation. This entry decodes
+ * those links into an `AssetReference` (anchor, version, `meta.assetType`,
+ * `meta.excerpt`), labels the anchor the way Olympus's chips label it, and
+ * writes the anchor (or the whole reference, as a Spaces link) back in its
+ * canonical query form.
+ *
+ * It is the one entry the `@athenaintel/react` SDK bundles, so it must stay
+ * free of `zod` (the root entry's object and callable codecs validate with
+ * it, and the published SDK carries no zod): `asset-links.test.ts` walks its
+ * import graph and fails on a module that reaches it.
+ */
+export { formatReferenceAnchor, type ReferenceAnchorFormatMode } from './anchors/format';
+export { serializeAnchorToParams } from './anchors/serialize';
+export type { Anchor } from './anchors/types';
+export { decodeFromAssetMentionUri } from './formats/uri/asset-mention-uri';
+export { decodeFromAssetSpacesUrl, encodeToAssetSpacesUrl } from './formats/uri/asset-spaces-url';
+export { quoteSheetName } from './sheet-name';
+export type { AssetMeta, AssetReference } from './types';

package/dist/references/src/asset-reference.d.ts

@@ -0,0 +1,16 @@
+import type { Anchor } from './anchors/types';
+import type { AssetMeta, AssetReference } from './types';
+/** What an asset reference is built from: an asset's id, title and type. */
+export interface AssetLike {
+    readonly id: string;
+    readonly title: string;
+    readonly athenaOriginalType: string;
+}
+/**
+ * Build a canonical {@link AssetReference}: the asset's id, an optional anchor, and its meta (title
+ * and type, which `opts.meta` overrides key by key).
+ */
+export declare function assetToReference(asset: AssetLike, opts?: {
+    anchor?: Anchor;
+    meta?: Partial<AssetMeta>;
+}): AssetReference;

package/dist/references/src/formats/format-catalog.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Single inventory of every format the reference system recognises.
+ *
+ * This file is the source of truth for:
+ *   - Format name constants (`UriFormat`, `ObjectFormat`)
+ *   - The flat catalog listing every format with its wire type, `Referenced`
+ *     discriminator, and preferred flag
+ *   - Derived helpers for lookup
+ *
+ * Detection, decode, and encode functions live in their own files — they
+ * accept different shapes and can't be meaningfully unified.  But the
+ * *metadata* about each format belongs here so nothing drifts.
+ *
+ * Add new formats here first, then wire up detection + codec.
+ */
+import type { Referenced } from '../types';
+export type WireType = 'uri' | 'object';
+export declare const UriFormat: {
+    readonly AssetSpacesUrl: 'asset_spaces_url';
+    readonly NavigationSpacesUrl: 'navigation_spaces_url';
+    readonly AssetMentionUri: 'asset_mention_uri';
+    readonly CallableMentionUri: 'callable_mention_uri';
+    readonly PersonMentionUri: 'person_mention_uri';
+    readonly GroupMentionUri: 'group_mention_uri';
+    readonly PreReferenceUri: 'pre_reference_uri';
+};
+export type UriFormat = (typeof UriFormat)[keyof typeof UriFormat];
+export declare const ObjectFormat: {
+    readonly Asset: 'asset_object';
+    readonly Callable: 'callable_object';
+    readonly Person: 'person_object';
+    readonly Group: 'group_object';
+    readonly ExternalUrl: 'external_url_object';
+    readonly Navigation: 'navigation_object';
+    readonly PreReferenceObject: 'pre_reference_object';
+};
+export type ObjectFormat = (typeof ObjectFormat)[keyof typeof ObjectFormat];
+export declare function isCanonicalObjectFormat(format: unknown): format is ObjectFormat;
+export type DetectedUriFormat = {
+    kind: 'uri';
+    format: UriFormat;
+    url: URL;
+} | {
+    kind: 'unknown_url';
+    url: string;
+} | {
+    kind: 'unrecognized';
+};
+export type DetectedObjectFormat = {
+    kind: 'object';
+    format: ObjectFormat;
+    data: Record<string, unknown>;
+} | {
+    kind: 'unrecognized';
+};
+export type FormatEntry = {
+    /** Wire-level name — the string stored or detected at runtime. */
+    format: string;
+    /** URI or object. */
+    wire: WireType;
+    /**
+     * Level 1 discriminator this format always produces.
+     * `null` when the format is polymorphic (pre-reference formats determine
+     * `referenced` at decode time from the payload itself).
+     */
+    referenced: Referenced | null;
+    /** True when this is the canonical write format for its `referenced` + `wire` pair. */
+    preferred: boolean;
+};
+export declare const FORMAT_CATALOG: readonly FormatEntry[];
+/** Look up the catalog entry for a format name. */
+export declare function getFormatEntry(format: string): FormatEntry | undefined;
+/**
+ * Level 1 discriminator for a known format.
+ * Returns `null` for polymorphic legacy formats, `undefined` if the format is unknown.
+ */
+export declare function getReferencedForFormat(format: string): Referenced | null | undefined;
+/** The preferred format name for a given `referenced` + wire combination. */
+export declare function getPreferredFormat(referenced: Referenced, wire: WireType): string | undefined;

package/dist/references/src/formats/markdown/parse-reference-markdown.d.ts

@@ -0,0 +1,28 @@
+import type { Reference } from '../../types';
+/**
+ * Pattern for `[@Title](url)`.
+ * Group 1: full match, 2: display name (without `@`), 3: inner URL.
+ *
+ * The title may hold balanced brackets one level deep, as CommonMark link text
+ * does (`[@Plan [Q3]](url)`), or a lone `[` (`[@Draft [WIP](url)`): asset titles
+ * carry both and the serializer writes titles verbatim.
+ * A pair followed by `(scheme://` or `(/` ends the title there, so a
+ * lone-bracket title cannot swallow the mention after it; `[@Plan [Q3](Review)](url)` still
+ * keeps its whole title.
+ *
+ * Not global — callers add `g` when scanning prose:
+ * `new RegExp(MARKDOWN_AT_LINK.source, 'g')`
+ */
+export declare const MARKDOWN_AT_LINK: RegExp;
+/**
+ * Parse already-split markdown at-link chunks into a runtime Reference.
+ *
+ * Callers are responsible for splitting the `[@Title](url)` format; this
+ * function takes the two parts directly.  The `displayName` should NOT
+ * include the leading `@` — that is a wire-level marker added/stripped
+ * by serializers and renderers.
+ *
+ * Internally delegates to `parseReferenceURI` for the inner URL, then
+ * merges `displayName` into the appropriate `meta` field.
+ */
+export declare function parseReferenceMarkdownChunks(displayName: string, innerUrl: string): Reference;

package/dist/references/src/formats/markdown/reference-display-name.d.ts

@@ -0,0 +1,6 @@
+import type { Reference } from '../../types';
+/**
+ * Default display label for markdown `[@Title](uri)` when no explicit title is passed.
+ * Aligns with converter-olympus `getDisplayNameFromReference` behaviour.
+ */
+export declare function getDisplayNameFromReference(ref: Reference): string;

package/dist/references/src/formats/object/asset-object.d.ts

@@ -0,0 +1,9 @@
+import type { AssetReference } from '../../types';
+/**
+ * Decode: `{ format: 'asset_object', ... }` → AssetReference
+ */
+export declare function decodeFromAssetObject(data: Record<string, unknown>): AssetReference;
+/**
+ * Encode: AssetReference → object with `format: 'asset_object'`
+ */
+export declare function encodeToAssetObject(reference: AssetReference): Record<string, unknown>;

package/dist/references/src/formats/object/callable-object.d.ts

@@ -0,0 +1,6 @@
+import type { CallableReference } from '../../types';
+export declare function decodeFromCallableObject(data: Record<string, unknown>): CallableReference;
+/**
+ * Encode: CallableReference → object with `format: 'callable_object'`
+ */
+export declare function encodeToCallableObject(ref: CallableReference): Record<string, unknown>;

package/dist/references/src/formats/object/decode-reference-object-payload.d.ts

@@ -0,0 +1,3 @@
+import { ObjectFormat } from '../format-catalog';
+import type { Reference } from '../../types';
+export declare function decodeReferenceObjectPayload(format: ObjectFormat, data: Record<string, unknown>): Reference;