BPOS-TMP-REPO/api-report/apps/api/src/modules/ledger/contract.d.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 declare class DraftConflictError extends Error {
    readonly findings: readonly ConflictFinding[];
    constructor(findings: readonly ConflictFinding[]);
}
export declare class SchemaConflictError extends Error {
    readonly conflicts: readonly MergeConflict[];
    constructor(conflicts: readonly MergeConflict[]);
}
export declare class ObjectNotMaterializedError extends Error {
    readonly address: string;
    constructor(address: string);
}
/** 声明合并与物化的结果 —— 安装静态审读它: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;
};
/**
 * **放行写的范围**(2026-08-27,数据工单确认即入库)。
 *
 * 不给 = 整单放行:草稿层全部并进正式表、清空。
 * 给了 = 只并这几张表 —— 它们的门不是放行卡,是**数据工单的确认**(那张卡的提交闸
 * 盯的就是这几张表:必填齐了才按得下确认,确认那一刻就入库)。并过的行**留在草稿层、
 * 打上已落地记号**:它仍是本单写下的行(任务视图 / `mine:` / `_rows` 照旧认它),
 * 只是整单放行时不再写它、不再为它抛事件。
 * `cause` 落进数据事件的归因(`ledger-write:<cause>`),回看时认得出是哪张卡签下去的。
 */
export type ReleaseScope = {
    readonly only: readonly ObjectAddress[];
    readonly cause: string;
};
export type ReleaseWriteResult = {
    readonly mergedRows: number;
    readonly emittedEvents: number;
    /**
     * **早已落地、这次不再写的行数**(2026-08-27)—— 数据工单确认时并进去的那几行,
     * 整单放行时只把它们当事实读回来(出口载荷要它们),不再写、不再抛事件。
     * 放行痕上要分开说:「合并 N 行」里若混着这几行,那句话就多报了。
     */
    readonly landedEarlierRows: 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>;
    /**
     * 放行写。`scope` 见 `ReleaseScope`:不给 = 整单;给了 = 只并那几张表(数据工单确认那一道门),
     * 并过的行留在草稿层打记号。**不是第四种写**,也不是绕门:同一条冲突检查 → 原子合并 → 抛事件的路,
     * 只是门换成了那张卡的确认闸 —— 落哪几张表由发卡的人说了算(`gateLedgers`),调用方指不了别的表进来
     * (清单没声明的表这一单本就写不进草稿层)。
     */
    releaseWrite(taskId: TaskId, scope?: ReleaseScope): 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>;
        /** 已在数据工单确认那一道门上并进正式表(见 `ReleaseScope`);仍是本单写下的行 */
        landed: boolean;
    }>>;
    /** 落地预检第五项:数据冲突检查;`only` 给了就只查那几张表(与 `releaseWrite` 的 scope 同一口径) */
    checkConflicts(taskId: TaskId, only?: readonly ObjectAddress[]): Promise<ConflictFinding[]>;
    discardDrafts(taskId: TaskId): Promise<void>;
};