JX-BPOS/apps/api/src/modules/ledger/contract.ts

/**
 * module: ledger —— 对外类型(编码规范 §10.1)。只有类型和常量,没有实现。
 */
import type {
  LedgerAddress,
  LedgerKey,
  LedgerPage,
  LedgerQuery,
  LedgerRow,
  ObjectDeclaration,
  TaskId,
  WriteKind,
} from '@contracts';
import type { MaterializedObject, MergeConflict, MergeNotice, MergedObject } from './internal/domain/schema-merge.ts';
import type { ConflictFinding } from './internal/domain/task-view.ts';

export type { LedgerAddress, LedgerKey, LedgerPage, LedgerQuery, LedgerRow, ObjectDeclaration, WriteKind };
export type { MaterializedObject, MergeConflict, MergeNotice, MergedObject, ConflictFinding };

export class DraftConflictError extends Error {
  constructor(readonly findings: readonly ConflictFinding[]) {
    super(`草稿与正式版并发冲突:${findings.length} 处字段已被他单改动`);
    this.name = 'DraftConflictError';
  }
}

export class SchemaConflictError extends Error {
  constructor(readonly conflicts: readonly MergeConflict[]) {
    super(`台账声明语义互斥,交数据管理裁决:${conflicts.map((c) => `${c.field}(${c.message})`).join('; ')}`);
    this.name = 'SchemaConflictError';
  }
}

export class ObjectNotMaterializedError extends Error {
  constructor(readonly address: string) {
    super(`台账对象未物化:${address}`);
    this.name = 'ObjectNotMaterializedError';
  }
}

/** 声明合并与物化的结果 —— 安装静态审读它:conflicts 非空即不上架 */
export type SchemaApplyResult = {
  readonly merged: MergedObject | undefined;
  readonly notices: readonly MergeNotice[];
  readonly conflicts: readonly MergeConflict[];
  readonly applied: boolean;
};

export type ObjectAddress = { readonly domain: string; readonly object: string };

export type SystemWrite = {
  readonly address: ObjectAddress;
  readonly key: LedgerKey;
  readonly values: LedgerRow;
  /** 归因:哪条入站 / 哪次流转产生了这次系统写 */
  readonly cause: { readonly kind: 'inbound' | 'engine' | 'governance'; readonly ref: string };
  /** 系统写也可挂到任务上(入站归一到某任务),数据事件的目标即它 */
  readonly taskId?: TaskId;
};

export type DraftWrite = {
  readonly taskId: TaskId;
  readonly address: ObjectAddress;
  readonly key: LedgerKey;
  readonly patch: LedgerRow;
  readonly tombstone?: boolean;
};

export type ReleaseWriteResult = {
  readonly mergedRows: number;
  readonly emittedEvents: number;
  /**
   * **试跑单被挡下的主数据行数** —— 合到出参里去,是因为界面不撒谎:
   * 放行痕上写「合并 N 行」而其中几行根本没进表,那句话就是假的。
   * 非试跑单恒为 0。
   */
  readonly simulatedRows: number;
  /**
   * 合并进正式版的那些行(键 + 值)。
   * 「落地收敛,输出口才发射」——发射的载荷就该是**这些已落地的事实**,
   * 而不是从作用域里再猜一遍:放行后草稿层已清空,再猜就什么也猜不到。
   */
  readonly merged: ReadonlyArray<{
    readonly domain: string;
    readonly object: string;
    readonly key: Record<string, unknown>;
    readonly values: Record<string, unknown>;
  }>;
};

/**
 * 写三分是**三个不同方法**,不是一个带 flag 的方法 —— 调用方拿不到「绕门」的形态(§7.2)。
 *   systemWrite  —— 登记世界已发生的事实,不过放行门,写正式版并**即时**抛数据事件
 *   draftWrite   —— 任务级草稿层,读己之写,**不抛**事件
 *   releaseWrite —— 放行通过,草稿合并入正式版,**此刻**抛数据事件;原子且过冲突检查
 */
export type LedgerService = {
  applyDeclarations(declarations: readonly ObjectDeclaration[]): Promise<SchemaApplyResult[]>;
  describe(address: ObjectAddress): Promise<MaterializedObject | undefined>;
  /** 出参带人读名(表注释);没登记就没有 label,呈现退回对象键 */
  listObjects(): Promise<Array<ObjectAddress & { label?: string | undefined }>>;

  systemWrite(write: SystemWrite): Promise<void>;
  draftWrite(write: DraftWrite): Promise<void>;
  /**
   * **撤掉本单草稿层的一行** —— 写错了得有退路(2026-08-01 加)。
   *
   * 不是第四种写:它只作用在**本单草稿层**,正式版一个字都动不了,也不抛事件 ——
   * 撤的是「我这一单还没过门的那一笔」。放行门的位置没变。
   *
   * 没有它的后果实测过:客户说本轮跳过的那颗料被写进了有效清单,条目数报 9 而表里躺着 10,
   * 判据 `record_rows = line_total` 正确地拦住,而模型**改不动** ——
   * 它唯一能改的是那个数(改了 skipped_total 又不对),13 次拒回、23 拍、234k token 才熔断。
   * 门拦住一件办错的事却不给改正的手段,那扇门就只是个死胡同。
   */
  draftDrop(drop: { taskId: TaskId; address: ObjectAddress; key: Record<string, unknown> }): Promise<boolean>;
  releaseWrite(taskId: TaskId): Promise<ReleaseWriteResult>;

  /** 正式版查询 —— 跨任务只见过门的事实 */
  query(query: LedgerQuery): Promise<LedgerPage>;
  /** 任务视图 = 正式版 + 本任务草稿层 */
  taskView(taskId: TaskId, query: LedgerQuery): Promise<LedgerPage>;
  /**
   * **本任务自己写的**草稿条目(读己之写的读面)。
   * 与 `taskView` 的区别:那个是「正式版 + 我的草稿」的合并视图,
   * 这个只回我写过的那些行 —— 引擎求值要区分「这一单的事实」与「别人放行后的事实」。
   */
  taskDrafts(taskId: TaskId): Promise<Array<{ domain: string; object: string; key: Record<string, unknown>; patch: Record<string, unknown> }>>;
  /** 落地预检第五项:数据冲突检查 */
  checkConflicts(taskId: TaskId): Promise<ConflictFinding[]>;
  discardDrafts(taskId: TaskId): Promise<void>;
};