@vibefield/rosetta-room 0.0.0-stage → 0.1.0

package/dist/lib/transcript/sittings.d.ts

@@ -0,0 +1,75 @@
+import type { TimelineEntry } from "@vibefield/rosetta-protocol";
+/** A silence this long or longer means the reader left and came back. */
+export declare const SITTING_PAUSE_MS: number;
+/** Adjacent successful setting commands inside this window may share one
+ * compact configuration group. Conversational prompts never use this rule. */
+export declare const PROMPT_CLUSTER_MS: number;
+/**
+ * The viewer-local day a timestamp falls in, as `YYYY-MM-DD`. The same form
+ * `lib/model.ts`'s `getCalendarDayKey` buckets the heatmap in — copied rather
+ * than imported because that module pulls in JSX through the agent marks, and
+ * this one must stay importable by a plain node test.
+ */
+export declare function calendarDayKey(timestamp: number): string;
+/**
+ * Precision follows distance, in the words the session list already uses:
+ * `Today`, `Yesterday`, `Mon 24 Aug` — and the year only when it is not this
+ * one. `lib/format.ts`'s `dayLabel` is canonical for the first three; this adds
+ * §07's year rule on top of it so the pill and the session list never disagree.
+ */
+export declare function sittingDayLabel(timestamp: number, now: number): string;
+export interface Sitting {
+    /** Stable across renders: the first row's `timeline_id`. */
+    readonly key: string;
+    /** `YYYY-MM-DD`, viewer-local. Null when no row in the sitting is stamped. */
+    readonly dayKey: string | null;
+    /** `Today` · `Yesterday` · `Mon 31 Aug` · `24 Aug 2025`. */
+    readonly dayLabel: string | null;
+    /** The pill's time, drawn only when the reader actually came back: null for
+     * the first sitting and for a day that turned without a pause. */
+    readonly resumedAt: number | null;
+    /** The silence before this sitting. Null when the cut was a day change with
+     * no pause of fifteen minutes or more. */
+    readonly pauseMs: number | null;
+    /** The cut crossed a calendar day, so the pill names it. True for the first
+     * sitting, whose pill is the day alone. */
+    readonly dayChanged: boolean;
+    readonly isFirst: boolean;
+    readonly startedAt: number | null;
+    readonly endedAt: number | null;
+    readonly rows: readonly TimelineEntry[];
+}
+/**
+ * Fold ordered entries into sittings: open a new one before any entry whose
+ * calendar day differs from the previous stamped entry's, or whose gap from it
+ * is SITTING_PAUSE_MS or more.
+ *
+ * A row with `at: null` NEVER cuts — a missing stamp is not evidence that the
+ * reader left. Nor does a stamp that runs backwards: real transcripts carry
+ * out-of-order stamps (a compaction summary lands before the command that
+ * caused it), and a negative gap is a record artefact, not a silence.
+ */
+export declare function sittings(rows: readonly TimelineEntry[], now?: number): Sitting[];
+/** One row of the pill's menu: `Mon 31 Aug · 1 sitting`. */
+export interface DayEntry {
+    readonly dayKey: string;
+    readonly dayLabel: string;
+    readonly sittingCount: number;
+    /** Pressing the row lands the transcript on this sitting's first row. */
+    readonly firstSittingKey: string;
+    readonly startedAt: number | null;
+}
+/**
+ * The day list the pill opens into, in document order. A sitting that could
+ * not name its day is left out rather than filed under a guess.
+ */
+export declare function dayList(list: readonly Sitting[]): DayEntry[];
+/** `3 sittings` on the session row — the same count, from the same threshold. */
+export declare function sittingCount(rows: readonly TimelineEntry[], now?: number): number;
+/**
+ * The time half of the setting-group rule. Whether both rows are successful
+ * human setting commands, or a response stood between them, is the document's
+ * business; `turns.ts` owns those checks and sets
+ * `Turn.clusteredWithPrevious`.
+ */
+export declare function withinPromptCluster(previousAt: number | null, currentAt: number | null): boolean;

package/dist/lib/transcript/sittings.js

@@ -0,0 +1,147 @@
+import { dayLabel } from "../format.js";
+/** A silence this long or longer means the reader left and came back. */
+export const SITTING_PAUSE_MS = 15 * 60_000;
+/** Adjacent successful setting commands inside this window may share one
+ * compact configuration group. Conversational prompts never use this rule. */
+export const PROMPT_CLUSTER_MS = 5 * 60_000;
+const MINUTES_TO_MS = 60_000;
+/** The viewer's offset, minutes east of UTC. */
+function viewerUtcOffsetMinutes() {
+    return -new Date().getTimezoneOffset();
+}
+/**
+ * The viewer-local day a timestamp falls in, as `YYYY-MM-DD`. The same form
+ * `lib/model.ts`'s `getCalendarDayKey` buckets the heatmap in — copied rather
+ * than imported because that module pulls in JSX through the agent marks, and
+ * this one must stay importable by a plain node test.
+ */
+export function calendarDayKey(timestamp) {
+    const date = new Date(timestamp + viewerUtcOffsetMinutes() * MINUTES_TO_MS);
+    const month = String(date.getUTCMonth() + 1).padStart(2, "0");
+    const day = String(date.getUTCDate()).padStart(2, "0");
+    return `${date.getUTCFullYear()}-${month}-${day}`;
+}
+/**
+ * Precision follows distance, in the words the session list already uses:
+ * `Today`, `Yesterday`, `Mon 24 Aug` — and the year only when it is not this
+ * one. `lib/format.ts`'s `dayLabel` is canonical for the first three; this adds
+ * §07's year rule on top of it so the pill and the session list never disagree.
+ */
+export function sittingDayLabel(timestamp, now) {
+    const then = new Date(timestamp);
+    if (then.getFullYear() !== new Date(now).getFullYear()) {
+        return then.toLocaleDateString("en-GB", {
+            day: "numeric",
+            month: "short",
+            year: "numeric",
+        });
+    }
+    return dayLabel(timestamp, now);
+}
+/**
+ * Fold ordered entries into sittings: open a new one before any entry whose
+ * calendar day differs from the previous stamped entry's, or whose gap from it
+ * is SITTING_PAUSE_MS or more.
+ *
+ * A row with `at: null` NEVER cuts — a missing stamp is not evidence that the
+ * reader left. Nor does a stamp that runs backwards: real transcripts carry
+ * out-of-order stamps (a compaction summary lands before the command that
+ * caused it), and a negative gap is a record artefact, not a silence.
+ */
+export function sittings(rows, now = Date.now()) {
+    const open = [];
+    let previousAt = null;
+    for (const row of rows) {
+        const at = row.at;
+        const current = open.at(-1);
+        if (current === undefined) {
+            open.push({ rows: [row], resumedAt: null, pauseMs: null, dayChanged: true });
+            if (at !== null)
+                previousAt = at;
+            continue;
+        }
+        if (at === null || previousAt === null) {
+            current.rows.push(row);
+            continue;
+        }
+        const gap = at - previousAt;
+        const pauseMs = gap >= SITTING_PAUSE_MS ? gap : null;
+        const dayChanged = calendarDayKey(at) !== calendarDayKey(previousAt);
+        if (pauseMs === null && !dayChanged) {
+            current.rows.push(row);
+            previousAt = at;
+            continue;
+        }
+        open.push({
+            rows: [row],
+            // The time is what the reader resumed at, so it is drawn only when there
+            // was something to resume from.
+            resumedAt: pauseMs === null ? null : at,
+            pauseMs,
+            dayChanged,
+        });
+        previousAt = at;
+    }
+    return open.map((sitting, index) => {
+        const stamps = sitting.rows
+            .map((row) => row.at)
+            .filter((value) => value !== null);
+        const startedAt = stamps.length === 0 ? null : Math.min(...stamps);
+        const endedAt = stamps.length === 0 ? null : Math.max(...stamps);
+        return {
+            key: sitting.rows[0].timeline_id,
+            dayKey: startedAt === null ? null : calendarDayKey(startedAt),
+            dayLabel: startedAt === null ? null : sittingDayLabel(startedAt, now),
+            resumedAt: sitting.resumedAt,
+            pauseMs: sitting.pauseMs,
+            dayChanged: sitting.dayChanged,
+            isFirst: index === 0,
+            startedAt,
+            endedAt,
+            rows: sitting.rows,
+        };
+    });
+}
+/**
+ * The day list the pill opens into, in document order. A sitting that could
+ * not name its day is left out rather than filed under a guess.
+ */
+export function dayList(list) {
+    const days = [];
+    const byKey = new Map();
+    for (const sitting of list) {
+        if (sitting.dayKey === null || sitting.dayLabel === null)
+            continue;
+        const seen = byKey.get(sitting.dayKey);
+        if (seen === undefined) {
+            byKey.set(sitting.dayKey, days.length);
+            days.push({
+                dayKey: sitting.dayKey,
+                dayLabel: sitting.dayLabel,
+                sittingCount: 1,
+                firstSittingKey: sitting.key,
+                startedAt: sitting.startedAt,
+            });
+            continue;
+        }
+        const existing = days[seen];
+        days[seen] = { ...existing, sittingCount: existing.sittingCount + 1 };
+    }
+    return days;
+}
+/** `3 sittings` on the session row — the same count, from the same threshold. */
+export function sittingCount(rows, now = Date.now()) {
+    return sittings(rows, now).length;
+}
+/**
+ * The time half of the setting-group rule. Whether both rows are successful
+ * human setting commands, or a response stood between them, is the document's
+ * business; `turns.ts` owns those checks and sets
+ * `Turn.clusteredWithPrevious`.
+ */
+export function withinPromptCluster(previousAt, currentAt) {
+    if (previousAt === null || currentAt === null)
+        return false;
+    const gap = currentAt - previousAt;
+    return gap >= 0 && gap <= PROMPT_CLUSTER_MS;
+}

package/dist/lib/transcript/tail-scroll.d.ts

@@ -0,0 +1,36 @@
+export interface TailState {
+    readonly away: boolean;
+    readonly unseen: number;
+}
+/** One owner for live-follow and its animation. DOM scroll events observe
+ * positions; wheel/touch/key intent can interrupt before the next frame. */
+export declare class TailScroll {
+    private following;
+    private ready;
+    private landed;
+    private opening;
+    private unseen;
+    private frame;
+    private previousTime;
+    private returningToLatest;
+    private writtenTop;
+    private state;
+    private readonly element;
+    private readonly publish;
+    private readonly reduced;
+    constructor(element: HTMLElement, publish: (state: TailState) => void, reduced: () => boolean);
+    get isFollowing(): boolean;
+    get isAnimating(): boolean;
+    private bottom;
+    private setFollowing;
+    private emit;
+    private write;
+    private stop;
+    pause: () => void;
+    onScroll: () => void;
+    update(ready: boolean, arrivals: number, opening?: boolean): void;
+    resize: () => void;
+    private tick;
+    latest: () => void;
+    dispose(): void;
+}

package/dist/lib/transcript/tail-scroll.js

@@ -0,0 +1,167 @@
+import { tailStep } from "./tail-state.js";
+/** One owner for live-follow and its animation. DOM scroll events observe
+ * positions; wheel/touch/key intent can interrupt before the next frame. */
+export class TailScroll {
+    following = true;
+    ready = false;
+    landed = false;
+    opening = false;
+    unseen = 0;
+    frame = null;
+    previousTime = 0;
+    returningToLatest = false;
+    writtenTop;
+    state = { away: false, unseen: 0 };
+    element;
+    publish;
+    reduced;
+    constructor(element, publish, reduced) {
+        this.element = element;
+        this.publish = publish;
+        this.reduced = reduced;
+        this.writtenTop = element.scrollTop;
+        this.setFollowing(true);
+    }
+    get isFollowing() {
+        return this.following;
+    }
+    get isAnimating() {
+        return this.frame !== null;
+    }
+    bottom() {
+        return Math.max(0, this.element.scrollHeight - this.element.clientHeight);
+    }
+    setFollowing(value) {
+        this.following = value;
+        this.element.toggleAttribute("data-following", value);
+    }
+    emit() {
+        const away = this.ready &&
+            !this.following &&
+            (this.bottom() - this.element.scrollTop > 32 || this.unseen > 0);
+        const unseen = this.following ? 0 : this.unseen;
+        if (away === this.state.away && unseen === this.state.unseen)
+            return;
+        this.state = { away, unseen };
+        this.publish(this.state);
+    }
+    write(top) {
+        this.element.scrollTop = top;
+        this.writtenTop = this.element.scrollTop;
+    }
+    stop() {
+        if (this.frame !== null)
+            cancelAnimationFrame(this.frame);
+        this.frame = null;
+        this.returningToLatest = false;
+    }
+    pause = () => {
+        this.stop();
+        this.setFollowing(false);
+        this.emit();
+    };
+    onScroll = () => {
+        if (!this.ready)
+            return;
+        const top = this.element.scrollTop;
+        // During an explicit return, native PageUp/anchor easing may keep sending
+        // positions for several frames. Fresh input and focus own interrupts;
+        // those stale position events must not cancel the reader's latest click.
+        if (!this.returningToLatest && Math.abs(top - this.writtenTop) > 1) {
+            this.stop();
+            this.setFollowing(false);
+        }
+        this.writtenTop = top;
+        if (this.bottom() - top <= 8) {
+            this.setFollowing(true);
+            this.unseen = 0;
+        }
+        this.emit();
+    };
+    update(ready, arrivals, opening = false) {
+        this.opening = opening;
+        this.ready = ready;
+        if (!ready) {
+            this.stop();
+            this.emit();
+            return;
+        }
+        this.unseen += arrivals;
+        if (!this.landed) {
+            this.landed = true;
+            // Open a session at its latest message before paint. Search anchors
+            // pause follow before reaching here and retain their own landing.
+            if (this.following)
+                this.write(this.bottom());
+        }
+        else {
+            this.resize();
+        }
+        this.emit();
+    }
+    resize = () => {
+        if (!this.ready)
+            return;
+        if (!this.following) {
+            this.emit();
+            return;
+        }
+        if (this.opening || this.reduced()) {
+            this.stop();
+            this.write(this.bottom());
+            this.unseen = 0;
+            this.emit();
+        }
+        else if (Math.abs(this.bottom() - this.element.scrollTop) <= 0.5) {
+            this.stop();
+            this.unseen = 0;
+            this.emit();
+        }
+        else if (this.frame === null) {
+            this.previousTime = performance.now();
+            this.frame = requestAnimationFrame(this.tick);
+        }
+    };
+    tick = (time) => {
+        this.frame = null;
+        if (!this.following || !this.ready)
+            return;
+        const target = this.bottom();
+        const before = this.element.scrollTop;
+        this.write(this.reduced() ? target : tailStep(before, target, time - this.previousTime));
+        // Browsers quantize scrollTop to device pixels. At high refresh rates a
+        // subpixel step can round back to the same position forever. Make one
+        // pixel of progress when that happens, bounded by the remaining distance.
+        if (this.element.scrollTop === before && target !== before) {
+            this.write(before + Math.sign(target - before) * Math.min(1, Math.abs(target - before)));
+        }
+        this.previousTime = time;
+        if (Math.abs(target - this.element.scrollTop) <= 1) {
+            this.write(target);
+            this.returningToLatest = false;
+            this.unseen = 0;
+            this.emit();
+        }
+        else {
+            this.frame = requestAnimationFrame(this.tick);
+        }
+    };
+    latest = () => {
+        this.stop();
+        // PageUp/PageDown and anchor navigation can leave a native smooth scroll
+        // in flight. Cancel it now, before its queued scroll event can interrupt
+        // the first frame of this explicitly requested return to latest.
+        this.element.scrollTo({ top: this.element.scrollTop, behavior: "instant" });
+        this.writtenTop = this.element.scrollTop;
+        this.returningToLatest = true;
+        this.setFollowing(true);
+        this.resize();
+        if (this.bottom() - this.element.scrollTop <= 8)
+            this.unseen = 0;
+        this.emit();
+    };
+    dispose() {
+        this.stop();
+        this.element.removeAttribute("data-following");
+    }
+}

package/dist/lib/transcript/tail-state.d.ts

@@ -0,0 +1,17 @@
+/** Ordinals belong to sessions, not the merged team chronology. New sources
+ * start with a baseline; history, patches and replay cannot inflate the count. */
+export interface TailRow {
+    readonly session_id: string;
+    readonly timeline_id: string;
+    readonly ordinal: number;
+}
+export declare class TailArrivals {
+    private maxima;
+    update<T extends TailRow>(rows: readonly T[]): T[];
+    /** Even an empty initial snapshot establishes this session's live tail. */
+    prime(sessionId: string): void;
+    reset(): void;
+}
+/** Time-based easing stays equally smooth on 60 Hz and 120 Hz displays.
+ * Retargeting never restarts a browser smooth-scroll on each streamed token. */
+export declare function tailStep(current: number, target: number, elapsed: number): number;

package/dist/lib/transcript/tail-state.js

@@ -0,0 +1,30 @@
+export class TailArrivals {
+    maxima = new Map();
+    update(rows) {
+        const fresh = [];
+        const next = new Map(this.maxima);
+        for (const row of rows) {
+            const previous = this.maxima.get(row.session_id);
+            if (previous !== undefined && row.ordinal > previous)
+                fresh.push(row);
+            next.set(row.session_id, Math.max(next.get(row.session_id) ?? -1, row.ordinal));
+        }
+        this.maxima = next;
+        return fresh;
+    }
+    /** Even an empty initial snapshot establishes this session's live tail. */
+    prime(sessionId) {
+        if (!this.maxima.has(sessionId))
+            this.maxima.set(sessionId, -1);
+    }
+    reset() {
+        this.maxima.clear();
+    }
+}
+/** Time-based easing stays equally smooth on 60 Hz and 120 Hz displays.
+ * Retargeting never restarts a browser smooth-scroll on each streamed token. */
+export function tailStep(current, target, elapsed) {
+    if (Math.abs(target - current) <= 0.5)
+        return target;
+    return current + (target - current) * (1 - Math.exp(-Math.min(elapsed, 64) / 70));
+}

package/dist/lib/transcript/turns.d.ts

@@ -0,0 +1,192 @@
+import type { AttachmentKind, AttachmentRef, CanonicalText, CitationRef, CollaborationEvent, Notice, SummaryPurpose, TimelineEntry } from "@vibefield/rosetta-protocol";
+import type { LedgerLine, RunSummary } from "./ledger.js";
+import type { LedgerContext } from "./vocabulary.js";
+/** One image/attachment occurrence, including unavailable bytes. */
+export interface AttachmentFact {
+    readonly key: string;
+    readonly kind: AttachmentKind;
+    readonly name: string | null;
+    readonly mediaType: string | null;
+    readonly byteLen: number | null;
+    readonly width: number | null;
+    readonly height: number | null;
+    readonly missing: boolean;
+    readonly ref: AttachmentRef | null;
+    readonly caption: string;
+}
+/** Native wrappers and image grammar belong to adapters, never the renderer. */
+export declare function readAttachments(text: string | null, refs: readonly AttachmentRef[]): {
+    text: string | null;
+    attachments: AttachmentFact[];
+};
+export interface AttachmentMention {
+    readonly start: number;
+    readonly end: number;
+    readonly target: AttachmentFact;
+}
+/** Exact canonical Unicode-scalar spans, converted once to JS string offsets.
+ * Missing images retain their link; undocumented numbering stays plain text. */
+export declare function attachmentMentions(text: string, attachments: readonly AttachmentFact[]): readonly AttachmentMention[];
+export interface LocalSetting {
+    readonly kind: "model" | "effort";
+    readonly label: "Model" | "Effort";
+    readonly value: string;
+}
+export interface Prompt {
+    readonly key: string;
+    readonly row: TimelineEntry;
+    /** The prompt row plus an absorbed `command_output` notice — the pair is one
+     * object (§03 H), so the marker never draws twice. */
+    readonly rows: readonly TimelineEntry[];
+    readonly at: number | null;
+    readonly text: string | null;
+    readonly attachments: readonly AttachmentFact[];
+    /** Draw a pill, not a panel: this prompt is a local command. */
+    readonly isCommand: boolean;
+    readonly command: string | null;
+    /** The command's reply, riding beside the pill in the caption ramp. */
+    readonly commandOutput: string | null;
+    readonly commandOutputRow: TimelineEntry | null;
+    /** A successful local setting change, reduced to label + canonical value. */
+    readonly setting: LocalSetting | null;
+    /** The parent session sent this, not a person (`parent_invocation`). */
+    readonly fromParent: boolean;
+    /** Machine-delivered context has prompt semantics but never human styling. */
+    readonly machine: MachinePrompt | null;
+}
+export interface MachinePrompt {
+    readonly label: string;
+    readonly sender: string | null;
+}
+/** Project a normalized setting value into the two words the reader needs.
+ * Diagnostics deliberately fail this predicate and retain the generic command
+ * treatment, so compact presentation never conceals a rejected command. */
+export declare function localSetting(command: string | null, output: string | null): LocalSetting | null;
+export type Segment = {
+    readonly kind: "prose";
+    readonly key: string;
+    readonly row: TimelineEntry;
+    readonly at: number | null;
+    readonly text: string | null;
+    readonly attachments: readonly AttachmentFact[];
+    readonly citations: readonly CitationRef[];
+    readonly citationLabels: readonly string[];
+} | {
+    readonly kind: "thinking";
+    readonly key: string;
+    readonly row: TimelineEntry;
+    readonly at: number | null;
+    readonly text: string;
+    /** From adjacent stamps — what `more · reasoning, 12s` states. */
+    readonly spanMs: number | null;
+} | {
+    readonly kind: "ledger";
+    readonly key: string;
+    readonly at: number | null;
+    /** Every row in the run, in order: the tool rows and the thoughts,
+     * notices and summaries between them (R-1). */
+    readonly rows: readonly TimelineEntry[];
+    /** The tool lines, folded (T-3) — what the sentence counts and what the
+     * worker subthreads hang from. */
+    readonly lines: readonly LedgerLine[];
+    /** The ladder, in order. */
+    readonly members: readonly LedgerMember[];
+    readonly summary: RunSummary;
+} | {
+    readonly kind: "marker";
+    readonly key: string;
+    readonly row: TimelineEntry;
+    readonly at: number | null;
+    readonly notice: Notice;
+    readonly text: string;
+    /** A runtime error takes red TEXT — still a line, never a filled alarm. */
+    readonly tone: "plain" | "failed";
+} | {
+    readonly kind: "summary";
+    readonly key: string;
+    readonly row: TimelineEntry;
+    readonly at: number | null;
+    readonly purpose: SummaryPurpose;
+    readonly text: string;
+} | {
+    readonly kind: "compaction";
+    readonly key: string;
+    readonly row: TimelineEntry;
+    /** The summary and, when proven, its neighboring boundary, in order. */
+    readonly rows: readonly TimelineEntry[];
+    readonly at: number | null;
+    readonly text: CanonicalText;
+} | {
+    readonly kind: "collaboration";
+    readonly key: string;
+    readonly row: TimelineEntry;
+    readonly at: number | null;
+    readonly event: CollaborationEvent;
+};
+/**
+ * One drawn member of a run's ladder: a tool line, or the thought, notice or
+ * summary that happened between two lines. Inside the ladder each keeps the
+ * form it had as a segment; only the run's head is new (transcript-fold).
+ */
+export type LedgerMember = {
+    readonly kind: "line";
+    readonly key: string;
+    readonly line: LedgerLine;
+} | Extract<Segment, {
+    kind: "thinking" | "marker" | "summary";
+}>;
+/** A reply's list-price cost (§4.1.3). `microUsd` is null when nothing in the
+ * reply could be priced; `partial` when some of its usage could not be. */
+export interface ResponseCost {
+    readonly microUsd: number | null;
+    readonly partial: boolean;
+}
+export interface ResponseHead {
+    /** The model the reply opened with. A mid-reply change is a `model_changed`
+     * marker in the segments, never a second head (§05 draws exactly that). */
+    readonly model: string | null;
+    readonly effort: string | null;
+    /** Reported tokens across the reply's response groups. Null means the agent
+     * never reported any, which must never be coerced to zero. */
+    readonly tokens: number | null;
+    /** List-price cost of the reply's usage; null when it carried none. */
+    readonly cost: ResponseCost | null;
+    readonly startedAt: number | null;
+    readonly endedAt: number | null;
+    readonly spanMs: number | null;
+}
+export interface Turn {
+    /** Stable across renders: the prompt's `timeline_id`, else the first row's. */
+    readonly key: string;
+    readonly prompt: Prompt | null;
+    /** One head per reply (T-4). Null when nothing agent-authored answered. */
+    readonly head: ResponseHead | null;
+    readonly segments: readonly Segment[];
+    /** Where the eyebrow belongs: the index of the first agent-authored segment,
+     * so a leading marker is not drawn under a head it does not belong to. */
+    readonly headIndex: number;
+    /** Every row in the turn, in order — anchors, focus landing, watermark. */
+    readonly rows: readonly TimelineEntry[];
+    readonly at: number | null;
+    /** §07: this successful human setting command joins the previous setting
+     * command's compact group. Conversational and parent-agent prompts are
+     * always standalone turns. */
+    readonly clusteredWithPrevious: boolean;
+}
+export interface DocumentOptions {
+    /** Paths draw relative to the session's own cwd, then home-relative. */
+    readonly context?: LedgerContext;
+    /** Team child rows interleaved into their parent's shared chronology. Their
+     * native parent-invocation group must not masquerade as a human turn here. */
+    readonly sharedCollaborationSessionIds?: ReadonlySet<string>;
+    /** Rows that begin a new sitting (§07). A run never straddles a pill, so it
+     * is cut before each of these; `document-model.ts` supplies them. */
+    readonly cutBefore?: ReadonlySet<string>;
+}
+/**
+ * Fold an ordered timeline into turns. Pure: no clock, no IO. The rows behind
+ * every prompt, segment and ledger line stay reachable, so the anchors, the
+ * focus landing and the live watermark all keep working off `timeline_id` and
+ * `ordinal` exactly as they do today.
+ */
+export declare function documentTurns(rows: readonly TimelineEntry[], options?: DocumentOptions): Turn[];