@eddyskywalker/dsh-chatgpt-subscription 0.49.0 → 0.51.0

package/lib/types/host/dispatch-ledger/guard.d.ts

@@ -0,0 +1,271 @@
+/**
+ * 「调度账本」的**执行期守卫**。
+ *
+ * ## 它站在哪儿
+ *
+ * 只用 `ctx.tools.guard(exec => string | undefined)` 这一条执行期接缝：
+ * 工具声明面一个字节都不改，Kimi Code 的前缀缓存不会因为这个守卫重建一次。
+ * 守卫在 pre-execute 之后、派发之前跑；拒绝会变成 `isError` 的工具结果，
+ * 正文是 `Error: <reason>`。
+ *
+ * ## 拒绝文案格式（跨代次宿主可判定）
+ *
+ * 所有拒绝一律以 `DISPATCH_LEDGER_V2:<CODE>:` 开头。账本折叠靠**结果内容
+ * 文本**识别"这次尝试是被守卫拒的"（原生走 tool/result 的 message.content，
+ * PTC 走 tool/ptc-dispatch 的 content），所以这个前缀是跨代次宿主都能用的
+ * 判据。
+ *
+ * ## 只拒能证明的违规
+ *
+ * - 没有头部 → **放行**（旧消息降级审计），不拦。
+ * - 头部显式损坏 → 拒（解析不了就没有去重依据）。
+ * - 读不出来的状态 → 放行 + 审计。宁可漏放，也不误伤。
+ *
+ * @module dsh-chatgpt-subscription/host/dispatch-ledger/guard
+ */
+import { type MandateHeader } from './header.ts';
+import { type SessionLike } from './binding.ts';
+import { type DispatchLedgerEventLike, type DispatchLedgerState } from './ledger.ts';
+import { type DispatchPolicyDescriptor, type DispatchPolicyRoute } from './policy.ts';
+/** 守卫的拒绝码。 */
+export type DispatchDenialCode = 'MANDATE_MALFORMED' | 'MANDATE_KIND' | 'MANDATE_DUPLICATE' | 'MANDATE_BRIEF_BUSY' | 'MANDATE_LINEAGE_REQUIRED' | 'MANDATE_LINEAGE' | 'MANDATE_POLICY_STALE' | 'MANDATE_VERSION' | 'MANDATE_NOT_PARENT' | 'MANDATE_NOT_CHILD' | 'MANDATE_GRANT_EXCEEDS' | 'MANDATE_NOT_HELD' | 'MANDATE_LEDGER_FULL';
+/** 一次工具执行（守卫只读这些）。 */
+export interface DispatchGuardExecution {
+    /** 工具名。 */
+    readonly name?: unknown;
+    /** 已解析的参数。 */
+    readonly arguments?: unknown;
+    /** 调用方 agent。 */
+    readonly agent?: unknown;
+    /** 本次调用的 id（宿主在守卫之前就把调用写进了日志）。 */
+    readonly callId?: unknown;
+}
+/** 守卫读到的会话视图。 */
+export interface DispatchLedgerSessionLike extends SessionLike {
+    /** 当前日志水位。 */
+    readonly seq?: unknown;
+    /** 按序号读一条事件。 */
+    eventAt?(seq: number): DispatchLedgerEventLike | undefined;
+}
+/** 会话注册表（结构化；老宿主可能只有 get）。 */
+export interface DispatchLedgerSessions {
+    /** 按 id 取一个会话。 */
+    get(id: string): DispatchLedgerSessionLike | undefined;
+    /** 列出全部会话（one-shot 候选的来源）。 */
+    list?(): readonly DispatchLedgerSessionLike[];
+}
+/** 守卫选项。 */
+export interface DispatchLedgerGuardOptions {
+    /** 当前是否启用拦截（每次执行都重读）。 */
+    readonly enabled?: () => boolean;
+    /** 会话注册表；缺席时只做能证明的校验。 */
+    readonly sessions?: () => DispatchLedgerSessions | undefined;
+    /** 当前会话的策略描述符；缺席时跳过策略校验。 */
+    readonly policyFor?: (session: DispatchLedgerSessionLike) => DispatchPolicyDescriptor | undefined;
+    /**
+     * 当前环境的提示词修订号（由宿主注入）。
+     *
+     * 派发头的 §prompt_ref§ 必须与它一致：模型只允许从 self 结果里抄，不允许
+     * 自拟。未注入时跳过这条校验（standalone 测试宿主）。
+     */
+    readonly promptRef?: string;
+    /** 视为"派发"的工具名。 */
+    readonly dispatchTools?: readonly string[];
+    /** 共享的折叠缓存。 */
+    readonly cache?: DispatchLedgerCache;
+    /** 当前时刻（毫秒）；测试用它把预约推进到过期之后。 */
+    readonly now?: () => number;
+}
+/** 默认的派发工具名。 */
+export declare const DEFAULT_GUARD_DISPATCH_TOOLS: readonly string[];
+/**
+ * 造一条拒绝文案。
+ * @param code - 拒绝码。
+ * @param detail - 可执行的说明。
+ * @returns 拒绝文案。
+ */
+export declare function dispatchDenial(code: DispatchDenialCode, detail: string): string;
+/**
+ * 进程内的折叠缓存。
+ *
+ * ## 缓存安全措施
+ *
+ * 1. **按会话 id 分键**：不同会话的折叠结果互不污染。
+ * 2. **水位校验**：只折 seq 大于水位的��件；一旦发现水位不连续（缺口或
+ *    倒序），立刻**整段重折**——日志被替换过的情况下宁可多算一次，也不把
+ *    一份错的状态当成真的。
+ * 3. **容量上限**：最多缓存 N 个会话，超出时淘汰最早写入的那个（Map 保持
+ *    插入顺序），内存有界。
+ * 4. **只存纯数据**：缓存里只有折叠状态与序号，不持有会话对象的引用，
+ *    会话销毁后不会泄漏。
+ */
+export interface DispatchLedgerCache {
+    /** 折出一个会话的账本状态。 */
+    fold(session: DispatchLedgerSessionLike): DispatchLedgerState;
+    /** 丢弃一个会话的缓存条目。 */
+    forget(sessionId: string): void;
+    /** 丢弃全部缓存条目。 */
+    clear(): void;
+    /** 当前缓存的会话数。 */
+    size(): number;
+}
+/**
+ * 造一个折叠缓存。
+ * @param limit - 最多缓存多少个会话。
+ * @returns 缓存。
+ */
+export declare function createDispatchLedgerCache(limit?: number): DispatchLedgerCache;
+/**
+ * 读一个会话的允许路由。
+ *
+ * 会话自己记过就用自己的；没记过就沿 `header.parentSession` 往上找（深度
+ * 上限 8，与插件既有的祖先查找同一条路）。找不到就是空清单。
+ * @param session - 会话。
+ * @param sessions - 会话注册表。
+ * @returns 路由清单。
+ */
+export declare function routesForSession(session: DispatchLedgerSessionLike | undefined, sessions: DispatchLedgerSessions | undefined): DispatchPolicyRoute[];
+/**
+ * 算出一个会话的策略描述符。
+ * @param session - 会话。
+ * @param sessions - 会话注册表。
+ * @param dispatchTools - 派发工具名。
+ * @returns 策略描述符。
+ */
+export declare function policyForSession(session: DispatchLedgerSessionLike | undefined, sessions: DispatchLedgerSessions | undefined, dispatchTools?: readonly string[]): DispatchPolicyDescriptor;
+/**
+ * 读一个会话持有的、最后一次的派发 Mandate。
+ * @param session - 会话。
+ * @returns 头部；没有时 undefined。
+ */
+export declare function ownMandateOf(session: DispatchLedgerSessionLike | undefined): MandateHeader | undefined;
+/**
+ * 预约的存活时间：30 分钟。
+ *
+ * 预约是**兜底**，不是权威：权威是持久账本。预约只用来覆盖"老代没有
+ * ptc-start、当前调用还没入账"的那一小段窗口——那段窗口里账本看不见本次
+ * 并行调用，防重会漏。窗口一过（TTL 到期），防重只剩账本。
+ */
+export declare const DISPATCH_RESERVATION_TTL_MS: number;
+/** 预约表最多保留多少条。 */
+export declare const MAX_DISPATCH_RESERVATIONS = 256;
+/** 一条预约。 */
+export interface DispatchLedgerReservation {
+    /** 签发方（发起派发的会话 id）。 */
+    readonly issuer: string;
+    /** 命名空间键。 */
+    readonly ns: string;
+    /** 预约者的调用 id。 */
+    readonly callId: string;
+    /** 预约时刻（Unix 毫秒）。 */
+    readonly at: number;
+}
+/** 预约表。 */
+export interface DispatchLedgerReservations {
+    /**
+     * 这个命名空间是否已被**别的**调用预约。
+     * @param issuer - 签发方会话 id。
+     * @param ns - 命名空间键。
+     * @param callId - 本次调用 id（自己的预约不算冲突）。
+     * @returns 是否冲突。
+     */
+    conflicts(issuer: string, ns: string, callId: string): boolean;
+    /**
+     * 预约一个命名空间（**只有所有校验通过之后**才调用）。
+     * @param issuer - 签发方会话 id。
+     * @param ns - 命名空间键。
+     * @param callId - 本次调用 id。
+     */
+    reserve(issuer: string, ns: string, callId: string): void;
+    /** 当前保留的预约数（过期条目会被顺手清掉）。 */
+    size(): number;
+    /** 清空预约表。 */
+    clear(): void;
+}
+/**
+ * 造一张预约表。
+ *
+ * 键是 (issuer, ns)：同一个签发方下的同一个命名空间只能被预约一次。
+ * 过期条目在每次读写前被顺手清掉；表满时淘汰最早写入的一条。
+ * @param options - 容量、TTL 与时钟。
+ * @returns 预约表。
+ */
+export declare function createDispatchLedgerReservations(options?: {
+    readonly limit?: number;
+    readonly ttlMs?: number;
+    readonly now?: () => number;
+}): DispatchLedgerReservations;
+/**
+ * 排除**本次调用自己**之后的容量判定。
+ *
+ * ## 为什么必须排除自己
+ *
+ * 宿主在守卫执行**之前**就把这次调用写进了日志（原生 §tool/call§、PTC
+ * §tool/ptc-dispatch-start§），所以账本里已经有本次调用建出来的那条 run。
+ * 直接拿账本的条数判容量，会把"第 256 条"当成"已经有 256 条"而误拒。
+ *
+ * 所以这里先把**本次调用自己建的那条 run**（ns 相同且 §createdByCallId§ 是
+ * 本次调用）排除掉再数：剩下的条数才是"本次派发之前"的水位。于是恰好第
+ * 256 条 run、第 64 个 brief 都放行；**原先**就有 256 run / 64 brief 时才真
+ * 判满。
+ *
+ * 本函数**不改账本**：账本必须忠实保留全部幂等事实，容量判定是读侧的事。
+ *
+ * @param state - 账本状态。
+ * @param brief_id - 本次派发要用的工作项 id。
+ * @param currentNs - 本次派发的命名空间键。
+ * @param callId - 本次调用的 id。
+ * @returns 排除本次调用之后的容量判定。
+ */
+export declare function dispatchCapacityExcluding(state: DispatchLedgerState, brief_id: string, currentNs: string, callId: string | undefined): {
+    readonly runs: number;
+    readonly briefs: number;
+    readonly isNewBrief: boolean;
+    readonly runsFull: boolean;
+    readonly briefsFull: boolean;
+    readonly full: boolean;
+};
+/**
+ * 校验一次**派发**调用。
+ * @param header - 派发头。
+ * @param state - 调用方会话的账本状态。
+ * @param callId - 本次调用的 id。
+ * @param policy - 调用方的策略描述符。
+ * @returns 拒绝文案；放行时 undefined。
+ */
+export declare function checkDispatchMandate(header: MandateHeader, state: DispatchLedgerState, callId: string | undefined, policy: DispatchPolicyDescriptor | undefined, promptRef?: string, reserved?: (ns: string) => boolean): string | undefined;
+/**
+ * 校验一次**报告**（子 → 父）。
+ * @param header - 报告头。
+ * @param senderSession - 发件方的会话。
+ * @param targetId - 收件方（父）的会话 id。
+ * @param targetState - 收件方的账本状态（读不到时 undefined）。
+ * @returns 拒绝文案；放行时 undefined。
+ */
+export declare function checkReportMandate(header: MandateHeader, senderSession: DispatchLedgerSessionLike | undefined, targetId: string, targetState: DispatchLedgerState | undefined): string | undefined;
+/**
+ * 校验一次**续派**（父 → 子）。
+ * @param header - 续派头。
+ * @param senderSession - 发件方（owner）的会话。
+ * @param targetId - 收件方（子）的会话 id。
+ * @param targetSession - 收件方的会话（读不到时 undefined）。
+ * @param senderState - 发件方的账本状态。
+ * @returns 拒绝文案；放行时 undefined。
+ */
+export declare function checkSteerMandate(header: MandateHeader, senderSession: DispatchLedgerSessionLike | undefined, targetId: string, targetSession: DispatchLedgerSessionLike | undefined, senderState: DispatchLedgerState): string | undefined;
+/**
+ * 造一台调度账本守卫。
+ * @param options - 守卫选项。
+ * @returns 守卫函数。
+ */
+export declare function createDispatchLedgerGuard(options: DispatchLedgerGuardOptions): (execution: DispatchGuardExecution) => string | undefined;
+/**
+ * 装一台调度账本守卫。
+ *
+ * 只用 `ctx.tools.guard()`：工具声明面一个字节都不改。
+ * @param ctx - 宿主上下文。
+ * @param options - 守卫选项。
+ * @returns 注销守卫的函数；宿主没有 guard 接缝时是一个空操作。
+ */
+export declare function installDispatchLedgerGuard(ctx: unknown, options?: DispatchLedgerGuardOptions): () => void;
+//# sourceMappingURL=guard.d.ts.map

package/lib/types/host/dispatch-ledger/guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../../../../src/host/dispatch-ledger/guard.ts"],"names":[],"mappings":"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"}

package/lib/types/host/dispatch-ledger/header.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Mandate v2 的**头部文法与 schema**。
+ *
+ * ## 头部长什么样
+ *
+ * 头部是**一段围栏块**，必须从文本的**第 0 个字符**开始（允许前导空白），
+ * 后面紧跟 JSON 与结束围栏：
+ *
+ * ```
+ * ```dsh-mandate-v2
+ * {"v":2,"kind":"dispatch","brief_id":"b-7f","run_id":"r-1","idem":"i-1", ...}
+ * ```
+ *
+ * 三种状态，缺一不可：
+ *
+ * - `none`：文本不以围栏开头 → **没有头部**（旧消息）。调用方按"降级审计"
+ *   处理，不做拦截。
+ * - `invalid`：围栏在，但 JSON 非法、字段越界、版本不认识、kind 与字段组合
+ *   不合法 → **头部损坏**。
+ * - `ok`：解析出符合 v2 schema 的头部。
+ *
+ * ## 为什么头部里没有 session id
+ *
+ * 模型**天然不知道自己的 session id**，而"owner 必须等于我的 session id"
+ * 这种要求模型根本无法满足。身份全部由宿主从持久事实推导：签发方是发起
+ * 派发的那次调用的会话，持有方是自身日志里含有这份 Mandate 的子会话，
+ * 报告接收方是持有方的 `header.parentSession`。
+ *
+ * ## 为什么正文不进头部
+ *
+ * 头部会被抄进子会话日志与父会话的 inbox 日志，正文再抄一遍就是双份存储。
+ * 正文由**插件自己算出的 sha256** 锚定（围栏之后的全部文本），账本只存哈希。
+ *
+ * 模型**不能**在头部里提供正文哈希：提供了就是伪造，schema 会因为未知字段
+ * 直接判它损坏。哈希只由插件算，模型无从干预。
+ *
+ * @module dsh-chatgpt-subscription/host/dispatch-ledger/header
+ */
+/** 围栏协议 id：头部围栏的固定标识。 */
+export declare const MANDATE_PROTOCOL_ID = "dsh-mandate-v2";
+/** 头部格式版本（`v`）。 */
+export declare const MANDATE_HEADER_VERSION = 2;
+/** 受支持的授权快照版本（`mandate_version`）。 */
+export declare const MANDATE_SUPPORTED_MANDATE_VERSION = 1;
+/** 围栏内 JSON 的最大 UTF-8 字节数。 */
+export declare const MANDATE_HEADER_MAX_BYTES = 4096;
+/** id 字段允许的字符集。 */
+export declare const MANDATE_ID_PATTERN: RegExp;
+/** 头部的开场围栏。 */
+export declare const MANDATE_FENCE_OPEN: string;
+/** 头部的收尾围栏。 */
+export declare const MANDATE_FENCE_CLOSE = "```";
+/** 消息角色。 */
+export type MandateKind = 'dispatch' | 'report' | 'steer';
+/** 报告状态。 */
+export type MandateReportStatus = 'ready' | 'hand_back' | 'blocked' | 'failed' | 'dropped';
+/** 策略引用。 */
+export interface MandatePolicyRef {
+    /** 策略 id。 */
+    readonly id: string;
+    /** 策略版本。 */
+    readonly version: string;
+    /** 策略摘要（前缀）。 */
+    readonly sha256: string;
+}
+/** 一次运行的引用（血缘用）。 */
+export interface MandateRunRef {
+    /** 工作项 id。 */
+    readonly brief_id: string;
+    /** 运行 id。 */
+    readonly run_id: string;
+    /** 幂等键。 */
+    readonly idem: string;
+}
+/** 上下文扩权声明。 */
+export interface MandateGrant {
+    /** 允许的后续上下文引用。 */
+    readonly context: readonly string[];
+}
+/** 一份解析通过的 Mandate v2 头部。 */
+export interface MandateHeader {
+    /** 头部格式版本。 */
+    readonly v: 2;
+    /** 消息角色。 */
+    readonly kind: MandateKind;
+    /** 工作项 id（跨运行稳定）。 */
+    readonly brief_id: string;
+    /** 运行 id（一次派发尝试）。 */
+    readonly run_id: string;
+    /** 运行内的幂等键。 */
+    readonly idem: string;
+    /** 授权快照版本。 */
+    readonly mandate_version: number;
+    /** 提示词修订号。 */
+    readonly prompt_ref: string;
+    /** 策略引用。 */
+    readonly policy: MandatePolicyRef;
+    /** 原始任务的**引用**（不是正文）。 */
+    readonly task?: readonly string[];
+    /** 结构化边界。 */
+    readonly boundary?: readonly string[];
+    /** 允许的后续上下文。 */
+    readonly followup?: readonly string[];
+    /** 血缘：本次运行接替的那一次运行。 */
+    readonly parent_mandate?: MandateRunRef | null;
+    /** 上下文扩权声明（只有 steer 带）。 */
+    readonly grant?: MandateGrant | null;
+    /** 报告状态（只有 report 带）。 */
+    readonly status?: MandateReportStatus;
+}
+/** 解析状态。 */
+export type MandateParseState = 'none' | 'invalid' | 'ok';
+/** 一次头部解析的结果。 */
+export interface MandateParseResult {
+    /** 解析状态。 */
+    readonly state: MandateParseState;
+    /** 解析通过时的头部。 */
+    readonly header?: MandateHeader;
+    /** 失败原因（`invalid` 时有）。 */
+    readonly reason?: string;
+    /** 围栏之后的正文（`ok` 时有）。 */
+    readonly body?: string;
+}
+/**
+ * 解析一段文本里的 Mandate v2 头部。
+ *
+ * 这是**纯函数**：同样的文本永远得到同样的结果，不抛错。
+ * @param text - 候选文本（一段提示词或一条消息）。
+ * @returns 解析结果。
+ */
+export declare function parseMandateHeader(text: unknown): MandateParseResult;
+/**
+ * 取出围栏之后的正文。
+ *
+ * 正文是"任务描述"本身：它不进账本，只被插件算出的 sha256 锚定。
+ * @param text - 含头部的文本。
+ * @returns 正文；没有头部时 undefined。
+ */
+export declare function mandateBodyOf(text: unknown): string | undefined;
+/**
+ * 算出一个头部的命名空间键。
+ *
+ * 命名空间 = (brief_id, run_id, idem)。它由第一次派发尝试占用，此后**永不
+ * 可复用**；`released` 只解禁 brief，不解禁命名空间。
+ * @param header - 头部。
+ * @returns 命名空间键。
+ */
+export declare function mandateNamespaceKey(header: MandateHeader): string;
+/**
+ * 算出一个命名空间键。
+ * @param brief_id - 工作项 id。
+ * @param run_id - 运行 id。
+ * @param idem - 幂等键。
+ * @returns 命名空间键。
+ */
+export declare function mandateNamespaceKeyOf(brief_id: string, run_id: string, idem: string): string;
+/**
+ * 算出一个头部所属的工作项键。
+ * @param header - 头部。
+ * @returns 工作项 id。
+ */
+export declare function mandateBriefKey(header: MandateHeader): string;
+/**
+ * 取出一个头部的运行引用（血缘用）。
+ * @param header - 头部。
+ * @returns 运行引用。
+ */
+export declare function mandateRunRefOf(header: MandateHeader): MandateRunRef;
+//# sourceMappingURL=header.d.ts.map

package/lib/types/host/dispatch-ledger/header.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"header.d.ts","sourceRoot":"","sources":["../../../../src/host/dispatch-ledger/header.ts"],"names":[],"mappings":"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"}

package/lib/types/host/dispatch-ledger/index.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 「调度账本」的宿主装配：一次性注册只读工具 + 装一台执行期守卫。
+ *
+ * ## 装配纪律
+ *
+ * - 工具**一次性注册**：描述与参数表是编译期常量，会话中途不会多一个或少一个
+ *   工具，模型的工具记忆与 Kimi 的前缀缓存都不受影响。
+ * - 守卫只走 `ctx.tools.guard()`：工具声明面一个字节都不改。
+ * - **不登记任何投影**：账本直接折会话日志（快照或按序号读），所以老宿主没有
+ *   投影服务时功能照样完整。
+ * - 开关复用现有的 `dispatchExecutionGuard` 设置，不新增设置项。
+ *
+ * @module dsh-chatgpt-subscription/host/dispatch-ledger/index
+ */
+import { type DispatchLedgerCache, type DispatchLedgerSessionLike, type DispatchLedgerSessions } from './guard.ts';
+import { DISPATCH_LEDGER_TOOL } from './tool.ts';
+import type { DispatchPolicyDescriptor } from './policy.ts';
+/** 宿主装配选项。 */
+export interface DispatchLedgerHostOptions {
+    /** 当前是否启用（每次执行都重读）。 */
+    readonly enabled?: () => boolean;
+    /** 会话注册表（缺席时 tree 范围退化为当前会话）。 */
+    readonly sessions?: () => DispatchLedgerSessions | undefined;
+    /** 当前会话的策略描述符；缺省时按会话自己记录的路由算。 */
+    readonly policyFor?: (session: DispatchLedgerSessionLike) => DispatchPolicyDescriptor | undefined;
+    /** 视为"派发"的工具名。 */
+    readonly dispatchTools?: readonly string[];
+    /** 共享的折叠缓存（缺省时新建一个）。 */
+    readonly cache?: DispatchLedgerCache;
+    /**
+     * 当前环境的提示词修订号。
+     *
+     * 由宿主在**装配时**算好（对 preset 的稳定序列化文本取摘要）并注入：模型
+     * 只能从工具的 self 结果里把它抄进头部，不允许自拟。守卫用同一个值校验
+     * 派发头。
+     */
+    readonly promptRef?: string;
+}
+/**
+ * 把一份任意结构的对象序列化成**稳定文本**。
+ *
+ * 键按字典序排序，所以同一份内容在任何进程、任何代次宿主上都得到逐字相同
+ * 的文本；§JSON.stringify§ 不排序，靠它算出来的摘要会随字面量的键顺序漂移。
+ * @param value - 候选值。
+ * @returns 稳定文本。
+ */
+export declare function canonicalPromptSourceText(value: unknown): string;
+/**
+ * 装上调度账本：只读工具 + 执行期守卫。
+ * @param ctx - 宿主上下文。
+ * @param options - 装配选项。
+ * @returns 拆除装配的函数。
+ */
+export declare function installDispatchLedger(ctx: unknown, options?: DispatchLedgerHostOptions): () => void;
+export { DISPATCH_LEDGER_TOOL };
+//# sourceMappingURL=index.d.ts.map

package/lib/types/host/dispatch-ledger/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/host/dispatch-ledger/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAIL,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC9B,KAAK,sBAAsB,EAC5B,MAAM,YAAY,CAAA;AACnB,OAAO,EAA4B,oBAAoB,EAAE,MAAM,WAAW,CAAA;AAC1E,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAA;AAE3D,cAAc;AACd,MAAM,WAAW,yBAAyB;IACxC,uBAAuB;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,OAAO,CAAA;IAChC,iCAAiC;IACjC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,sBAAsB,GAAG,SAAS,CAAA;IAC5D,iCAAiC;IACjC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,yBAAyB,KAAK,wBAAwB,GAAG,SAAS,CAAA;IACjG,kBAAkB;IAClB,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1C,wBAAwB;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,mBAAmB,CAAA;IACpC;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAShE;AA0CD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,OAAO,EACZ,OAAO,GAAE,yBAA8B,GACtC,MAAM,IAAI,CA2CZ;AAED,OAAO,EAAE,oBAAoB,EAAE,CAAA"}