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;
};
export type ReleaseWriteResult = {
    readonly mergedRows: number;
    readonly emittedEvents: 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>;
    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>;
};