@tita-agent/dsh-data-table 0.0.0-stage → 0.2.0

package/lib/contract-version.d.ts

@@ -0,0 +1,311 @@
+/**
+ * 版本模型：数据产物共享的领域模型。
+ *
+ * 包含四段：版本与步骤的记录形状（version model）、表格地址与冲突载荷
+ * （spreadsheet addresses）、自动检查点的保留策略（retention）、版本时间线与撤销目标
+ * （version tier）。
+ *
+ * 为什么必须共享：数据产物的版本面板读同一份 `VersionChange` 语义、同一套冲突载荷和时间线排序。
+ *
+ * 依赖 `./refs.js` 的 `LineageContext`。
+ */
+import type { LineageContext } from './contract-refs.js';
+/**
+ * The unified Version/Revision/Step/Event vocabulary for versioned data artifacts.
+ */
+export type ArtifactKind = 'workbook';
+/**
+ * `committed` is the saved state; `temporary` workbook versions are previews of pending
+ * work and never surface as user versions.
+ */
+export type VersionStatus = 'open' | 'committed' | 'restored' | 'superseded';
+export type VersionActor = 'user' | 'agent';
+/**
+ * Version tier (PRD v3 §4). `named` Versions are the ones a person or an Agent
+ * deliberately created — a manual save, one Agent tool call, or a restore.
+ * `auto` checkpoints are what an editing session produces on its own; they stay
+ * fully usable but are collapsed out of the default list so a user can see the
+ * versions they actually meant to make. Absent on records written before v3 and
+ * therefore read as `named`.
+ */
+export type VersionKind = 'named' | 'auto';
+/** Only `content` advances the content revision stream and forms Versions. */
+export type RevisionKind = 'content' | 'derived' | 'metadata';
+/** A user-meaningful content version. */
+export interface VersionRecord {
+    versionId: string;
+    artifactKind: ArtifactKind;
+    artifactId: string;
+    /** Display number (`V1`, `V2`) scoped to one artifact; never reused. */
+    number: number;
+    startRevision: number;
+    endRevision: number;
+    parentVersionId?: string;
+    restoredFromVersionId?: string;
+    supersededByVersionId?: string;
+    status: VersionStatus;
+    /** v3 tier; absent on pre-v3 records, which are read as `named` (§4). */
+    kind?: VersionKind;
+    actor: VersionActor;
+    summary: string;
+    intent?: string;
+    stepCount: number;
+    /** Stable hash of the content state at `endRevision`. */
+    contentHash: string;
+    createdAt: string;
+    committedAt?: string;
+    lineage?: LineageContext;
+    /** False once the low-level log was compacted past its checkpoint (§6.2). */
+    replayable: boolean;
+}
+/** One replayable action inside a Version. */
+export interface VersionStepRecord {
+    versionId: string;
+    index: number;
+    opId: string;
+    operationType: string;
+    summary: string;
+    actor: 'user' | 'agent' | 'runtime';
+    timestamp: string;
+    replayable: boolean;
+}
+export type VersionChangeKind = 'cell' | 'sheet' | 'structure' | 'variable' | 'metadata';
+/** One line of a text diff. */
+export interface TextDiffLine {
+    kind: 'add' | 'remove' | 'same';
+    text: string;
+}
+/**
+ * One difference between two versions, plugin-neutral.
+ *
+ * The extra position fields exist so the shared diff view can group and hunk
+ * the changes the way `git diff` does, instead of rendering one card per
+ * change (PRD v3.3 §7.2):
+ *
+ * - `group` is the section a change belongs to — a sheet for a workbook or another grouped artifact. The view renders one tab per group when there is
+ *   more than one.
+ * - `row`/`column` are 0-based coordinates, when the change has a position.
+ *   Adjacent changes collapse into one hunk and the header names the row range.
+ */
+export interface VersionChange {
+    kind: VersionChangeKind;
+    target: string;
+    description: string;
+    group?: string;
+    row?: number;
+    column?: number;
+    before?: unknown;
+    after?: unknown;
+    /**
+     * The cell's value is the same on both sides — only its formatting moved.
+     *
+     * Formatting a range makes Univer write a style id into every cell it covers,
+     * so a diff that reads the raw cell objects reports the range as changed even
+     * when nothing in it was edited. A reader counting differences wants content,
+     * so formatting is reported as 样式 rather than as a modification (GUI
+     * feedback 2026-09-19: 473 styled-empty cells against 11 real edits).
+     */
+    styleOnly?: boolean;
+    /** Line-level diff, present when the change is textual source. */
+    lines?: TextDiffLine[];
+}
+/** How a change reads in a diff: insertion, deletion, replacement, or 样式. */
+export type VersionChangeDirection = 'add' | 'remove' | 'modify' | 'structure' | 'style';
+/** Classify one change from what it carries, so every surface agrees. */
+export declare function versionChangeDirection(change: VersionChange): VersionChangeDirection;
+/**
+ * Spreadsheet column letters for a 0-based column index: `0 → A`, `25 → Z`,
+ * `26 → AA`.
+ *
+ * The single column-letter implementation: the Table plugin, the shared diff
+ * view and other components all used to spell addresses their own way, and the
+ * user-visible result was `Sheet1!R3C2` in version summaries and `R3C2` in the
+ * comparison gutter — while a spreadsheet address is `Sheet1!C3`.
+ */
+export declare function columnLabel(index: number): string;
+/** A1-style cell reference without a sheet: `C3`. */
+export declare function cellAddress(row: number, column: number): string;
+/**
+ * A1-style reference with the sheet it lives in: `Sheet1!C3`, or
+ * `Sheet1!A1:B3` when the change spans a range.
+ *
+ * A single cell stays `Sheet1!C3` rather than the degenerate `C3:C3`: an
+ * address is what the user reads in the formula bar, and the range form is only
+ * meaningful when it actually spans more than one cell.
+ */
+export declare function formatCellReference(ref: {
+    sheet?: string;
+    row: number;
+    column: number;
+    endRow?: number;
+    endColumn?: number;
+}): string;
+/** A single conflicting change between the caller's base and the current state. */
+export interface ConflictEntry {
+    kind: VersionChangeKind | 'content';
+    target: string;
+    description: string;
+    base?: unknown;
+    local?: unknown;
+    remote?: unknown;
+}
+/**
+ * The single 409 body both plugins return (PRD §5.1): the caller learns what it
+ * was based on, what the artifact is now, and which changes conflict, so the UI
+ * can offer "重新读取 / 查看差异" rather than a bare error string.
+ */
+export interface ConflictPayload {
+    code: 'REVISION_CONFLICT';
+    artifactKind: ArtifactKind;
+    artifactId: string;
+    baseRevision: number;
+    currentRevision: number;
+    /** Transport cursor, when the plugin distinguishes it from the content revision. */
+    changeCursor?: number;
+    conflictSet: ConflictEntry[];
+    message: string;
+    nextAction: string;
+    retryable: boolean;
+}
+export declare function conflictPayload(input: {
+    artifactKind: ArtifactKind;
+    artifactId: string;
+    baseRevision: number;
+    currentRevision: number;
+    changeCursor?: number;
+    conflictSet?: ConflictEntry[];
+    message?: string;
+    nextAction?: string;
+}): ConflictPayload;
+/**
+ * Version boundary policy shared by both plugins (PRD v3.1 §4).
+ *
+ * A Version collects **many Steps**; it is not one Version per interaction. The
+ * value below is a *session* window, not a typing debounce: while a user keeps
+ * working inside it every edit joins the same open Version, and that Version
+ * closes only when a real trigger fires —
+ *
+ * 1. the user presses 保存版本,
+ * 2. an Agent tool call commits,
+ * 3. the user leaves the artifact (the client sends `boundary: 'close'`),
+ * 4. the user has been idle for this whole window, so the session ended,
+ * 5. the Step safety cap is reached.
+ *
+ * It used to be 2s, which turned every thinking pause into its own Version and
+ * made the list read as "one Version per keystroke burst".
+ */
+export declare const VERSION_IDLE_CLOSE_MS: number;
+/**
+ * How many Steps one Version may hold before it is closed and a new Version
+ * starts (PRD v3.3 D21).
+ *
+ * This is the *only* automatic boundary besides the idle window, so it is the
+ * user-visible one: 20 steps is roughly "a burst of work I would call one
+ * version". It used to be 50, which in practice meant a session never hit the
+ * cap and therefore never became a saved Version while the tab stayed open.
+ */
+export declare const VERSION_MAX_STEPS = 20;
+/** Newest auto checkpoints kept regardless of age (PRD v3.1 §6.2, D3). */
+export declare const AUTO_CHECKPOINT_KEEP = 100;
+export interface RetentionCandidate {
+    versionId?: string;
+    id?: string;
+    number: number;
+    status: VersionStatus;
+    kind?: VersionKind;
+    /** ISO timestamp; the retention rule buckets by calendar day. */
+    createdAt?: string;
+    timestamp?: string;
+    restoredFromVersionId?: string;
+    parentVersionId?: string;
+    /** Present when the record can replay from its own start state. */
+    startContentHash?: string;
+}
+/**
+ * Which auto checkpoints a store may drop (PRD v3.1 §6.2, D3).
+ *
+ * Kept, always: every `named` Version, the newest {@link AUTO_CHECKPOINT_KEEP}
+ * auto checkpoints, the newest auto checkpoint of every older calendar day, the
+ * line head / open Version, and anything a surviving Version still references
+ * (restore origin or parent), so pruning can never break a row that remains.
+ *
+ * `versions` may be in any order; the decision only uses identity, tier and
+ * time. The caller deletes the returned records and any content they alone own.
+ */
+export declare function selectAutoCheckpointsToPrune<T extends RetentionCandidate>(versions: T[], options?: {
+    keep?: number;
+}): T[];
+/** Pre-v3 records carry no `kind`; they are user/Agent-meaningful Versions. */
+export declare function versionKindOf(version: {
+    kind?: VersionKind;
+}): VersionKind;
+/** Minimal shape the timeline ordering needs. */
+export interface VersionTimelineKey {
+    number: number;
+    timestamp?: string;
+    createdAt?: string;
+}
+/**
+ * Newest-first comparator. Every list in the drawer reads as one timeline;
+ * Version numbers are handed out in creation order, so they break ties when a
+ * record has no usable timestamp.
+ */
+export declare function compareVersionsNewestFirst(left: VersionTimelineKey, right: VersionTimelineKey): number;
+/**
+ * The one flat timeline the drawer renders (PRD v3.3 §7.3).
+ *
+ * The rule is deliberately the **same shape as the storage retention rule**
+ * (`selectAutoCheckpointsToPrune`), so the list can never hide a Version the
+ * store kept, nor offer one it dropped. A Version is listed when any of these
+ * holds:
+ *
+ * 1. it is `named` — a manual save, one Agent call, or a restore. Never hidden;
+ * 2. it is among the newest {@link AUTO_CHECKPOINT_KEEP} Versions;
+ * 3. it is the **last Version of its calendar day**.
+ *
+ * (2) and (3) are what make a user's own editing history visible: in the Data
+ * Table every browser save is an `auto` checkpoint, so hiding `auto` outright
+ * hid the per-day work the user remembered making. (3) keeps a long-running
+ * artifact to roughly one row per working day once it falls out of the recent
+ * window, while (2) keeps everything recent restorable.
+ *
+ * The result is ordered strictly newest-first; callers render `今天 / 昨天 /
+ * 更早` separators and exclude `open` Versions, which are still being written.
+ */
+export declare function versionTimeline<T extends VersionTimelineKey & {
+    kind?: VersionKind;
+}>(versions: T[], options?: {
+    keep?: number;
+}): T[];
+/** `今天 / 昨天 / 更早` list separator (PRD v3 P3). */
+export declare function versionDayLabel(timestamp: string | undefined, nowMs?: number): string | undefined;
+/**
+ * Target of "撤销这次改动" (PRD v3 §6): the newest Version older than `entry`
+ * that is still on the current line. `undefined` means this Version has no
+ * reachable predecessor, and the drawer hides the action rather than offering a
+ * restore to nothing.
+ *
+ * Records expose their identity as `versionId` (persisted) or `id` (UI rows),
+ * so both shapes are accepted.
+ */
+export interface VersionIdentity {
+    versionId?: string;
+    id?: string;
+    number: number;
+    status: VersionStatus;
+}
+export declare function versionIdentityOf(value: {
+    versionId?: string;
+    id?: string;
+}): string | undefined;
+/**
+ * Display number of the Version a restore reinstated. Persisted records carry
+ * the target id, and only the surrounding list knows its number, so the label
+ * `由 V3 恢复` is resolved here once instead of in every plugin.
+ */
+export declare function restoredFromNumberOf<T extends {
+    versionId: string;
+    number: number;
+    restoredFromVersionId?: string;
+}>(version: T, all: T[]): number | undefined;
+export declare function undoTargetOf<T extends VersionIdentity>(versions: T[], entry: VersionIdentity): T | undefined;

package/lib/contract-version.js

@@ -0,0 +1,270 @@
+/** Classify one change from what it carries, so every surface agrees. */
+export function versionChangeDirection(change) {
+    // Formatting is checked first: its before/after are equal, so every rule
+    // below would call it a replacement.
+    if (change.styleOnly === true)
+        return 'style';
+    if (change.kind !== 'cell' && change.kind !== 'variable')
+        return 'structure';
+    const hasBefore = change.before !== undefined && change.before !== null && String(change.before) !== '';
+    const hasAfter = change.after !== undefined && change.after !== null && String(change.after) !== '';
+    if (!hasBefore && hasAfter)
+        return 'add';
+    if (hasBefore && !hasAfter)
+        return 'remove';
+    return 'modify';
+}
+/* ------------------------------------------------- spreadsheet addresses */
+/**
+ * Spreadsheet column letters for a 0-based column index: `0 → A`, `25 → Z`,
+ * `26 → AA`.
+ *
+ * The single column-letter implementation: the Table plugin, the shared diff
+ * view and other components all used to spell addresses their own way, and the
+ * user-visible result was `Sheet1!R3C2` in version summaries and `R3C2` in the
+ * comparison gutter — while a spreadsheet address is `Sheet1!C3`.
+ */
+export function columnLabel(index) {
+    let value = Math.max(0, Math.floor(index)) + 1;
+    let label = '';
+    while (value > 0) {
+        const remainder = (value - 1) % 26;
+        label = String.fromCharCode(65 + remainder) + label;
+        value = Math.floor((value - 1) / 26);
+    }
+    return label;
+}
+/** A1-style cell reference without a sheet: `C3`. */
+export function cellAddress(row, column) {
+    return `${columnLabel(column)}${Math.max(0, Math.floor(row)) + 1}`;
+}
+/**
+ * A1-style reference with the sheet it lives in: `Sheet1!C3`, or
+ * `Sheet1!A1:B3` when the change spans a range.
+ *
+ * A single cell stays `Sheet1!C3` rather than the degenerate `C3:C3`: an
+ * address is what the user reads in the formula bar, and the range form is only
+ * meaningful when it actually spans more than one cell.
+ */
+export function formatCellReference(ref) {
+    const address = cellAddress(ref.row, ref.column);
+    const spans = ref.endRow !== undefined && ref.endColumn !== undefined
+        && (ref.endRow !== ref.row || ref.endColumn !== ref.column);
+    const range = spans ? `${address}:${cellAddress(ref.endRow, ref.endColumn)}` : address;
+    const sheet = ref.sheet?.trim();
+    return sheet === undefined || sheet === '' ? range : `${sheet}!${range}`;
+}
+export function conflictPayload(input) {
+    return {
+        code: 'REVISION_CONFLICT',
+        artifactKind: input.artifactKind,
+        artifactId: input.artifactId,
+        baseRevision: input.baseRevision,
+        currentRevision: input.currentRevision,
+        ...(input.changeCursor === undefined ? {} : { changeCursor: input.changeCursor }),
+        conflictSet: input.conflictSet ?? [],
+        message: input.message ?? `内容已变化：请求基于 revision ${input.baseRevision}，当前是 ${input.currentRevision}`,
+        nextAction: input.nextAction ?? '重新读取最新版本后重试；需要保留本地修改时先查看差异',
+        retryable: true,
+    };
+}
+/**
+ * Version boundary policy shared by both plugins (PRD v3.1 §4).
+ *
+ * A Version collects **many Steps**; it is not one Version per interaction. The
+ * value below is a *session* window, not a typing debounce: while a user keeps
+ * working inside it every edit joins the same open Version, and that Version
+ * closes only when a real trigger fires —
+ *
+ * 1. the user presses 保存版本,
+ * 2. an Agent tool call commits,
+ * 3. the user leaves the artifact (the client sends `boundary: 'close'`),
+ * 4. the user has been idle for this whole window, so the session ended,
+ * 5. the Step safety cap is reached.
+ *
+ * It used to be 2s, which turned every thinking pause into its own Version and
+ * made the list read as "one Version per keystroke burst".
+ */
+export const VERSION_IDLE_CLOSE_MS = 10 * 60_000;
+/**
+ * How many Steps one Version may hold before it is closed and a new Version
+ * starts (PRD v3.3 D21).
+ *
+ * This is the *only* automatic boundary besides the idle window, so it is the
+ * user-visible one: 20 steps is roughly "a burst of work I would call one
+ * version". It used to be 50, which in practice meant a session never hit the
+ * cap and therefore never became a saved Version while the tab stayed open.
+ */
+export const VERSION_MAX_STEPS = 20;
+/* --------------------------------------- auto checkpoint retention (v3.1) */
+/** Newest auto checkpoints kept regardless of age (PRD v3.1 §6.2, D3). */
+export const AUTO_CHECKPOINT_KEEP = 100;
+function candidateId(value) {
+    return value.versionId ?? value.id;
+}
+function candidateTime(value) {
+    return value.createdAt ?? value.timestamp;
+}
+function calendarDay(iso) {
+    if (iso === undefined)
+        return undefined;
+    const at = Date.parse(iso);
+    if (!Number.isFinite(at))
+        return undefined;
+    const date = new Date(at);
+    return `${date.getFullYear()}-${date.getMonth() + 1}-${date.getDate()}`;
+}
+/**
+ * Which auto checkpoints a store may drop (PRD v3.1 §6.2, D3).
+ *
+ * Kept, always: every `named` Version, the newest {@link AUTO_CHECKPOINT_KEEP}
+ * auto checkpoints, the newest auto checkpoint of every older calendar day, the
+ * line head / open Version, and anything a surviving Version still references
+ * (restore origin or parent), so pruning can never break a row that remains.
+ *
+ * `versions` may be in any order; the decision only uses identity, tier and
+ * time. The caller deletes the returned records and any content they alone own.
+ */
+export function selectAutoCheckpointsToPrune(versions, options = {}) {
+    const keep = options.keep ?? AUTO_CHECKPOINT_KEEP;
+    const auto = versions
+        .filter(version => versionKindOf(version) === 'auto')
+        .sort((left, right) => right.number - left.number);
+    const candidates = new Set();
+    // Older days keep their last checkpoint, so a long-running session still has
+    // one row per working day instead of a hard cliff at exactly `keep`.
+    const seenDays = new Set(auto.slice(0, Math.max(0, keep))
+        .map(version => calendarDay(candidateTime(version)))
+        .filter((day) => day !== undefined));
+    for (const version of auto.slice(Math.max(0, keep))) {
+        const day = calendarDay(candidateTime(version));
+        if (day !== undefined && !seenDays.has(day)) {
+            seenDays.add(day);
+            continue;
+        }
+        candidates.add(version);
+    }
+    if (candidates.size === 0)
+        return [];
+    // Nothing that survives may point at a pruned record: a restore origin and a
+    // parent are both reasons to keep a checkpoint that would otherwise go.
+    const survivors = versions.filter(version => !candidates.has(version));
+    const protectedIds = new Set();
+    for (const version of survivors) {
+        if (version.restoredFromVersionId !== undefined)
+            protectedIds.add(version.restoredFromVersionId);
+        // The parent is only load-bearing while a record has no start state of its
+        // own to replay from; otherwise protecting it would retain a whole chain.
+        if (version.startContentHash === undefined && version.parentVersionId !== undefined) {
+            protectedIds.add(version.parentVersionId);
+        }
+    }
+    if (protectedIds.size > 0) {
+        for (const version of [...candidates]) {
+            const id = candidateId(version);
+            if (id !== undefined && protectedIds.has(id))
+                candidates.delete(version);
+        }
+    }
+    return [...candidates];
+}
+/* ------------------------------------------------- version tier (v3, §4/§7) */
+/** Pre-v3 records carry no `kind`; they are user/Agent-meaningful Versions. */
+export function versionKindOf(version) {
+    return version.kind === 'auto' ? 'auto' : 'named';
+}
+/**
+ * Newest-first comparator. Every list in the drawer reads as one timeline;
+ * Version numbers are handed out in creation order, so they break ties when a
+ * record has no usable timestamp.
+ */
+export function compareVersionsNewestFirst(left, right) {
+    const leftAt = left.timestamp ?? left.createdAt;
+    const rightAt = right.timestamp ?? right.createdAt;
+    const leftMs = leftAt === undefined ? Number.NaN : Date.parse(leftAt);
+    const rightMs = rightAt === undefined ? Number.NaN : Date.parse(rightAt);
+    if (Number.isFinite(leftMs) && Number.isFinite(rightMs) && leftMs !== rightMs)
+        return rightMs - leftMs;
+    return right.number - left.number;
+}
+/**
+ * The one flat timeline the drawer renders (PRD v3.3 §7.3).
+ *
+ * The rule is deliberately the **same shape as the storage retention rule**
+ * (`selectAutoCheckpointsToPrune`), so the list can never hide a Version the
+ * store kept, nor offer one it dropped. A Version is listed when any of these
+ * holds:
+ *
+ * 1. it is `named` — a manual save, one Agent call, or a restore. Never hidden;
+ * 2. it is among the newest {@link AUTO_CHECKPOINT_KEEP} Versions;
+ * 3. it is the **last Version of its calendar day**.
+ *
+ * (2) and (3) are what make a user's own editing history visible: in the Data
+ * Table every browser save is an `auto` checkpoint, so hiding `auto` outright
+ * hid the per-day work the user remembered making. (3) keeps a long-running
+ * artifact to roughly one row per working day once it falls out of the recent
+ * window, while (2) keeps everything recent restorable.
+ *
+ * The result is ordered strictly newest-first; callers render `今天 / 昨天 /
+ * 更早` separators and exclude `open` Versions, which are still being written.
+ */
+export function versionTimeline(versions, options = {}) {
+    const keep = Math.max(0, options.keep ?? AUTO_CHECKPOINT_KEEP);
+    const ordered = [...versions].sort(compareVersionsNewestFirst);
+    const listed = new Set();
+    // 1. deliberate Versions, always.
+    for (const version of ordered) {
+        if (versionKindOf(version) === 'named')
+            listed.add(version);
+    }
+    // 2. the newest `keep` Versions of any kind.
+    for (const version of ordered.slice(0, keep))
+        listed.add(version);
+    // 3. the last Version of every calendar day, walking back from the newest so
+    //    the *last* one of each day is the one that survives.
+    const seenDays = new Set();
+    for (const version of ordered) {
+        const day = calendarDay(version.timestamp ?? version.createdAt);
+        if (day === undefined || seenDays.has(day))
+            continue;
+        seenDays.add(day);
+        listed.add(version);
+    }
+    return ordered.filter(version => listed.has(version));
+}
+/** `今天 / 昨天 / 更早` list separator (PRD v3 P3). */
+export function versionDayLabel(timestamp, nowMs = Date.now()) {
+    if (timestamp === undefined)
+        return undefined;
+    const value = Date.parse(timestamp);
+    if (!Number.isFinite(value))
+        return undefined;
+    const startOfDay = (ms) => {
+        const date = new Date(ms);
+        return new Date(date.getFullYear(), date.getMonth(), date.getDate()).getTime();
+    };
+    const days = Math.round((startOfDay(nowMs) - startOfDay(value)) / 86_400_000);
+    if (days <= 0)
+        return '今天';
+    return days === 1 ? '昨天' : '更早';
+}
+export function versionIdentityOf(value) {
+    return value.versionId ?? value.id;
+}
+/**
+ * Display number of the Version a restore reinstated. Persisted records carry
+ * the target id, and only the surrounding list knows its number, so the label
+ * `由 V3 恢复` is resolved here once instead of in every plugin.
+ */
+export function restoredFromNumberOf(version, all) {
+    if (version.restoredFromVersionId === undefined)
+        return undefined;
+    return all.find(candidate => candidate.versionId === version.restoredFromVersionId)?.number;
+}
+export function undoTargetOf(versions, entry) {
+    const entryId = versionIdentityOf(entry);
+    const older = versions
+        .filter(candidate => candidate.number < entry.number && versionIdentityOf(candidate) !== entryId)
+        .sort((left, right) => right.number - left.number);
+    return older.find(candidate => candidate.status !== 'superseded') ?? older[0];
+}