dsh-kingdom 2.0.0 → 3.2.0

package/lib/types/core/delivery-ack.d.ts

@@ -0,0 +1,688 @@
+import type { EventRow, KingdomStore, RoleBindingRow, TaskRow, WorkerResultRow } from './db.js';
+import type { CommandContext } from './task-service.js';
+export declare const DELIVERY_ACK_EVENT_TYPE = "OWNER_DELIVERY_ITEM_ACKNOWLEDGED";
+/** 知悉回执载荷版本；形状变化时必须递增，旧记录按旧版本读取。 */
+export declare const DELIVERY_ACK_PAYLOAD_VERSION = "KingdomDeliveryItemAck/v1";
+/**
+ * 交付条目提问与回复：**两条独立**的治理事实，写在既有 events 账本里。
+ *
+ * 它们与「知悉」无关：提问不是知悉、不是 ACCEPT、不是 Task DONE，也不改变任何
+ * Task/Claim/审查/发布状态；回复同理。二者都不触发任何自动派发、唤醒或后续动作。
+ */
+export declare const DELIVERY_QUESTION_EVENT_TYPE = "OWNER_DELIVERY_ITEM_QUESTIONED";
+export declare const DELIVERY_REPLY_EVENT_TYPE = "OWNER_DELIVERY_ITEM_ANSWERED";
+export declare const DELIVERY_QUESTION_PAYLOAD_VERSION = "KingdomDeliveryItemQuestion/v1";
+export declare const DELIVERY_REPLY_PAYLOAD_VERSION = "KingdomDeliveryItemReply/v1";
+/** 需要最小化投影的事件类型；通用事件投影只保留元数据，绝不带问答正文。 */
+export declare const DELIVERY_QUESTION_EVENT_TYPES: readonly string[];
+/** 交付页的三层结构：成果摘要 → 模块/事项 → 证据/改动。 */
+export declare const DELIVERY_ITEM_LAYERS: readonly ["SUMMARY", "MODULE", "EVIDENCE"];
+export type DeliveryItemLayer = (typeof DELIVERY_ITEM_LAYERS)[number];
+/**
+ * 条目槽位：与所属层一起构成身份的命名空间。
+ *
+ * `artifacts`（产物引用）与 `risks`（执行者报告的风险）同属 EVIDENCE 层。
+ * 若身份只用「层 + 位置」，追加一个 artifact 会把后面所有 risk 的位置整体
+ * 后移，使旧的 risk 条目 ID 被另一个 artifact 占用——既有知悉会错误地指向
+ * 另一条内容。因此身份必须带槽位，各类条目在各自槽位内独立编号。
+ *
+ * `CHANGE` 槽位承载「主管确认的改动证据」条目；它的身份来自稳定的 entry id，
+ * 而不是位置，避免主管换选改动时旧条目 ID 被挪用。
+ */
+export declare const DELIVERY_ITEM_SLOTS: readonly ["SUMMARY", "ARTIFACT", "RISK", "CHANGE"];
+export type DeliveryItemSlot = (typeof DELIVERY_ITEM_SLOTS)[number];
+/**
+ * 「查看改动」可信度分类。
+ *
+ * - `REPO_RELATIVE_VERIFIED`：可验证的仓库相对路径 + 固定源码版本/差异。只有
+ *   主管在 ACCEPT 中显式选择、且本地内容寻址证据 hash 重验通过时才成立。
+ * - `NOT_LOCATABLE`：无可信来源。GUI 必须明确显示「不可定位」而不是给出链接。
+ */
+export declare const DELIVERY_CHANGE_REF_KINDS: readonly ["REPO_RELATIVE_VERIFIED", "NOT_LOCATABLE"];
+export type DeliveryChangeRefKind = (typeof DELIVERY_CHANGE_REF_KINDS)[number];
+/** 界面与报告共用的固定标注：这是主管确认的改动证据，不是作者证据。 */
+export declare const CHANGE_EVIDENCE_LABEL = "\u4E3B\u7BA1\u786E\u8BA4\u7684\u6539\u52A8\u8BC1\u636E";
+export declare const CHANGE_EVIDENCE_NOTE = "\u672C\u5DEE\u5F02\u6765\u81EA\u672C\u6B21 Task/attempt \u7A97\u53E3\u524D\u540E\u7684\u6709\u754C\u672C\u5730\u5FEB\u7167\uFF0C\u5E76\u7531\u8BE5\u9886\u5730\u5F53\u524D ACTIVE \u4E3B\u7BA1\u5728\u540C\u4E00\u4E8B\u52A1\u7684 ACCEPT \u4E2D\u663E\u5F0F\u9009\u62E9\u786E\u8BA4\u3002\u5B83\u53EA\u8BC1\u660E\u8FD9\u4E9B\u4ED3\u5E93\u76F8\u5BF9\u8DEF\u5F84\u5728\u7A97\u53E3\u5185\u53D1\u751F\u53D8\u5316\uFF1B\u4E0D\u8BC1\u660E Git \u4F5C\u8005\u8EAB\u4EFD\uFF0C\u4E5F\u4E0D\u8BC1\u660E\u7531\u54EA\u4E2A\u6267\u884C\u8005\u5199\u5165\u3002";
+/** 已确认改动证据的最小可投影形状（由 `delivery-change.ts` 解析后传入）。 */
+export interface DeliveryChangeEvidenceItem {
+    entryId: string;
+    /** 仓库相对路径；公开展示、链接与内容版本都用它，不使用工作区相对路径。 */
+    repoPath: string;
+    status: string;
+    note: string;
+}
+export interface DeliveryChangeEvidenceInput {
+    evidenceId: string;
+    attemptNo: number;
+    repoHead: string | null;
+    coverageComplete: boolean;
+    coverageReasons: string[];
+    note: string;
+    entries: DeliveryChangeEvidenceItem[];
+}
+export interface DeliveryChangeRef {
+    kind: DeliveryChangeRefKind;
+    /** 仅 `REPO_RELATIVE_VERIFIED` 时存在，且必须通过严格校验。 */
+    repoPath: string | null;
+    /** 固定源码版本或差异标识；缺失即不可信。 */
+    revision: string | null;
+    reasonCode: string | null;
+    note: string;
+    /** 已确认证据的 manifest id 与条目 id；只在可信时存在。 */
+    evidenceId?: string | null;
+    entryId?: string | null;
+    /** 固定标注「主管确认的改动证据」。 */
+    evidenceLabel?: string | null;
+    /** 部分覆盖时的诚实提示；完整覆盖为 null。 */
+    coverageNote?: string | null;
+}
+export interface DeliveryItemDetail {
+    label: string;
+    detail: string;
+    sourceRef: DeliverySourceRef | null;
+}
+export interface DeliveryItemContent {
+    layer: DeliveryItemLayer;
+    label: string;
+    detail: string;
+    sourceRef: DeliverySourceRef | null;
+    change: DeliveryChangeRef;
+    details: DeliveryItemDetail[];
+}
+export interface DeliveryItem {
+    /** 稳定 ID：同一交付内同一角色条目在任意重建中保持相同。 */
+    itemId: string;
+    /** 内容版本：条目内容（含主管接受的 attempt）变化时改变。 */
+    contentHash: string;
+    content: DeliveryItemContent;
+}
+export interface DeliverySourceRef {
+    entityType: 'worker_results' | 'tasks' | 'executions';
+    entityId: string | null;
+}
+/** Owner 知悉一次回执；只记录 principal、条目/版本与时间，不采集理由或理解程度。 */
+export interface DeliveryAcknowledgement {
+    deliveryId: string;
+    itemId: string;
+    contentHash: string;
+    ownerId: string;
+    acknowledgedAt: string;
+    eventSeq: number;
+    eventId: string;
+    /** 该次知悉写入时交付所依据的接受证据强度（历史回执为 UNKNOWN）。 */
+    acceptanceEvidenceKind: DeliveryAcceptanceEvidenceKind | 'UNKNOWN';
+    /** 该次知悉写入时是否 exact result-bound。 */
+    acceptanceEvidenceExact: boolean;
+}
+export type DeliveryAcknowledgementState = 'ACKNOWLEDGED' | 'PENDING' | 'PENDING_REVISION';
+/**
+ * 主管 ACCEPT 确认交付时**实际可核对到**的证据强度。
+ *
+ * - `EXACT_RESULT_BOUND`：`TASK_ACCEPTED` 同时锁定了本次 Claim 的 `reviewed_result_id`
+ *   与 `reviewed_result_digest`，且两者都与当前 Claim 一致。这是新格式的强证据。
+ * - `LEGACY_ATTEMPT_ONLY`：immutable v1.0.0 的合法 `TASK_ACCEPTED` 只有
+ *   `reviewed_attempt_no`（以及 decision/reviewer/claimed_outcome 等真实字段），
+ *   既没有 `reviewed_result_id` 也没有 `reviewed_result_digest`。Owner 2026-09-27
+ *   裁决允许知悉这类历史交付，但必须标注「历史接受证据较弱」：它只按真实事件字段
+ *   与**同 Task/attempt 的唯一 WorkerResult** 判定，不冒充 exact result-bound。
+ * - 新格式两字段只出现其一、digest 不一致、或 JSON 形状与真实 v1.0.0 事件不符时
+ *   一律拒绝（`invalid`），不会退回弱判据，也不会静默隐藏历史交付。
+ */
+export declare const DELIVERY_ACCEPTANCE_EVIDENCE_KINDS: readonly ["EXACT_RESULT_BOUND", "LEGACY_ATTEMPT_ONLY"];
+export type DeliveryAcceptanceEvidenceKind = (typeof DELIVERY_ACCEPTANCE_EVIDENCE_KINDS)[number];
+/** 历史（v1.0.0）接受证据的固定标注文案；工作台与 Owner 窗口共用同一措辞。 */
+export declare const LEGACY_ACCEPTANCE_EVIDENCE_NOTE = "\u5386\u53F2\u63A5\u53D7\u8BC1\u636E\u8F83\u5F31\uFF1A\u8BE5 Task/attempt \u7684 TASK_ACCEPTED \u662F v1.0.0 \u65E7\u683C\u5F0F\uFF0C\u53EA\u6709\u5C1D\u8BD5\u7F16\u53F7\uFF0C\u7F3A\u5C11\u88AB\u5BA1\u67E5\u7ED3\u679C ID \u4E0E\u5185\u5BB9\u6458\u8981\uFF1B\u672C\u6761\u6309\u771F\u5B9E\u4E8B\u4EF6\u5B57\u6BB5\u4E0E\u540C Task/attempt \u7684\u552F\u4E00 WorkerResult \u5224\u5B9A\uFF0C\u4E0D\u6784\u6210 exact result-bound \u8BC1\u636E\u3002";
+export interface DeliveryAcceptanceEvidence {
+    attemptNo: number;
+    /** 被审查结果的 ID；legacy 判定下是本 Task/attempt 唯一 WorkerResult 的 ID。 */
+    resultId: string;
+    /** true 仅当 `reviewed_result_id` 与 `reviewed_result_digest` 都与当前 Claim 一致。 */
+    exactResultBound: boolean;
+    /** 与事件 attempt 匹配的 WorkerResult 数量；legacy 必须恰好为 1。 */
+    matchingResultCount: number;
+}
+export interface DeliveryAcceptanceClassification {
+    kind: DeliveryAcceptanceEvidenceKind;
+    evidence: DeliveryAcceptanceEvidence;
+    legacyNote: string | null;
+}
+export interface DeliveryItemAcknowledgementView {
+    state: DeliveryAcknowledgementState;
+    /** 当前版本是否已有 Owner 知悉。 */
+    acknowledged: boolean;
+    /** 旧版本的知悉只留历史，不覆盖当前版本。 */
+    historicalCount: number;
+    acknowledgedAt: string | null;
+    acknowledgedByOwnerId: string | null;
+    acknowledgementEventSeq: number | null;
+    /**
+     * 当前版本那次知悉写入时依据的接受证据强度。
+     * 旧回执或尚无当前版本知悉时为 `UNKNOWN`，不猜测。
+     */
+    acknowledgedAcceptanceEvidenceKind: DeliveryAcceptanceEvidenceKind | 'UNKNOWN';
+    /** 当前版本那次知悉写入时是否 exact result-bound。 */
+    acknowledgedAcceptanceEvidenceExact: boolean;
+}
+export declare function digestText(value: string): string;
+/**
+ * 交付身份 = 一个 Task 的一条交付时间线。
+ *
+ * 刻意**不含** attempt/result：同一 Task 的后续已接受尝试是同一交付的新版本，
+ * 因此条目 ID 保持稳定，旧知悉随内容版本变化自动降为历史。若是每次尝试换一个
+ * 交付身份，旧知悉就无法作为「同一条目的历史」被识别。
+ */
+export declare function deliveryIdFor(taskId: string): string;
+/**
+ * 条目 ID 来自条目在交付结构中的**位置**（层 + 槽位 + 槽位内位置），
+ * 不来自可变化的正文，因此同一逻辑条目改版后仍是同一条。新增条目会追加
+ * 新 ID，旧条目 ID 不变；不同槽位（产物引用 / 风险）之间也不会互相挪用。
+ */
+export declare function deliveryItemId(deliveryId: string, layer: DeliveryItemLayer, slot: DeliveryItemSlot, position: number): string;
+/**
+ * 改动证据条目的身份来自稳定 entry id（= 仓库相对路径的摘要），不来自位置：
+ * 主管换选或增删改动时，旧条目 ID 不会被另一条改动占用。
+ */
+export declare function deliveryChangeItemId(deliveryId: string, entryId: string): string;
+/**
+ * 内容版本 = 结构、标签、正文、证据文本与改动引用状态（含可见 note、已确认
+ * 证据 id 与条目 id）的规范化摘要。
+ *
+ * 只在字段真实存在时把 evidenceId/entryId 纳入摘要，因此未带改动证据的既有
+ * 条目版本保持不变，历史知悉不会被本次扩展误判为改版。
+ */
+export declare function deliveryContentHash(content: DeliveryItemContent): string;
+/**
+ * 严格校验仓库相对路径。
+ *
+ * 拒绝：绝对路径、Windows 盘符、UNC/网络共享、`..` 逃逸、`.git` 内部路径、控制字符、
+ * 反斜杠（仓库相对路径一律使用 `/`）。任何不通过的值都不得成为链接。
+ */
+export declare function validateRepoRelativePath(value: unknown): string | null;
+/** 固定源码版本/差异标识：有界、无空白的 opaque 标识（含 git 的 `~`/`^` 相对写法）。 */
+export declare function validateSourceRevision(value: unknown): string | null;
+/**
+ * 只有「通过严格校验的仓库相对路径 + 固定版本」才构成可信改动引用。
+ * 其余一切（任意 Claim 字符串、本机绝对路径、现有 `SourceRef`）都返回 null，
+ * 由调用方明确渲染为不可定位。
+ */
+export declare function trustedChangeRef(repoPath: unknown, revision: unknown): {
+    repoPath: string;
+    revision: string;
+} | null;
+export interface AcceptedDelivery {
+    task: TaskRow;
+    claim: WorkerResultRow;
+}
+/**
+ * 只有**同一 Task/attempt 的主管 ACCEPT** 才确认交付。
+ *
+ * `TASK_ACCEPTED` 事件必须同时锁定本次 Claim 的 attempt、`result_id` 与内容
+ * 摘要（`reviewed_result_digest`，与主管审查写入端使用同一 `ownerInputHash`）。
+ * 只比对 attempt 会让一条针对同一 attempt 但另一份/已改内容的 ACCEPT 冒充确认，
+ * 因此三者缺一不可。
+ *
+ * 这是严格的**布尔**判据：新格式必须两字段齐备并一致，两字段只出现其一即拒绝。
+ * 需要区分「历史接受证据较弱」的调用方请看 {@link classifyAcceptedDelivery}。
+ */
+export declare function acceptedDelivery(store: KingdomStore, claim: WorkerResultRow | null, latestReview: EventRow | null): boolean;
+/**
+ * 把一次主管 ACCEPT 判定为「exact result-bound」或「历史接受证据较弱」，或 null（拒绝）。
+ *
+ * 判据（任一条不成立即返回 null，不返回较弱证据）：
+ * - Task 处于 `DONE`，最近一次主管裁定是 `TASK_ACCEPTED`（`readLatestReviewEvent`
+ *   已限定 `actor_role = SUPERVISOR`）且 `decision = 'ACCEPT'`；
+ * - `reviewed_attempt_no` 必须等于本次 Claim 的 attempt；
+ * - **新格式**：`reviewed_result_id` 与 `reviewed_result_digest` 必须同时存在、均为
+ *   字符串，并分别等于本次 Claim 的 `result_id` 与 `ownerInputHash(claim)`；
+ * - **旧格式（v1.0.0）**：两个新格式字段必须**同时缺失**，payload 必须**恰好**由
+ *   v1.0.0 的五个真实字段（decision / reviewed_attempt_no / reason /
+ *   reviewer_binding_id / claimed_outcome）组成——缺一个或多一个都不是旧格式，
+ *   且该 Task/attempt 恰好只有一条 WorkerResult 且就是本次 Claim。缺少这一唯一性
+ *   核对时无法排除「同一 attempt 有多份结果」，因此拒绝。
+ *
+ * 旧格式只做上述真实字段核对，不虚构 result-bound 证据：它证明的是「该尝试的唯一
+ * 已记录结果被接受」，而不是「该事件的摘要与这份内容一致」。
+ */
+export declare function classifyAcceptedDelivery(store: KingdomStore, claim: WorkerResultRow | null, latestReview: EventRow | null): DeliveryAcceptanceClassification | null;
+/** 读取某 Task 最近一次主管裁定事件（与投影窗口无关的精确读取）。 */
+export declare function readLatestReviewEvent(store: KingdomStore, kingdomId: string, taskId: string): EventRow | null;
+export declare const CREDENTIAL_REDACTION_PATTERN: RegExp;
+/** 只做凭据关键字 + 完整值（含 Bearer 等 scheme）替换；调用方决定是否再做路径脱敏。 */
+export declare function redactCredentialText(value: string): string;
+/**
+ * 交付文本的公开呈现脱敏。
+ *
+ * 沿用工作台投影既有的公开内容规则（`src/gui/snapshot.ts` 的
+ * `sanitizePublicJsonString` public-content 分支）：本机绝对路径、UNC 路径与
+ * 内联凭据替换为占位符。刻意只做这一件事——不做递归 JSON 遍历，也不是
+ * 新的通用脱敏框架；核心派生一次脱敏，所有呈现面（Owner 窗口与工作台投影）
+ * 都不会再看到原始 Claim 文本。
+ */
+export declare function redactDeliveryText(value: string): string;
+/**
+ * 从已确认的交付派生三层条目。
+ *
+ * 摘要层恒有 1 条（内容为执行者自述摘要）；每条 `artifacts` 与 `risks` 各派生一条
+ * 证据层条目。所有条目都带独立 ID 与内容版本，外层知悉不会覆盖子条。
+ *
+ * 位置在每个槽位内独立编号，因此追加 artifact 不会移动既有 risk 的身份。
+ *
+ * `changeEvidence` 只在主管在 ACCEPT 中显式选择了改动引用、且本地内容寻址证据
+ * hash 重验通过时传入。它派生的条目**不是**执行者自述，而是有界窗口观测 +
+ * 主管确认；标签固定为「主管确认的改动证据」，且绝不声称 Git 证明作者身份。
+ */
+export declare function deriveDeliveryItems(taskId: string, claim: WorkerResultRow, changeEvidence?: DeliveryChangeEvidenceInput | null): DeliveryItem[];
+/** 按 delivery + item 读取全部历史知悉（升序），包括旧版本。 */
+export declare function readDeliveryAcknowledgements(store: KingdomStore, kingdomId: string, deliveryId: string): DeliveryAcknowledgement[];
+/**
+ * 汇总某交付内每条条目的当前知悉状态。
+ *
+ * - 当前 `contentHash` 已有知悉 → `ACKNOWLEDGED`
+ * - 只有旧版本知悉 → `PENDING_REVISION`（旧知悉仅留历史）
+ * - 从无知悉 → `PENDING`
+ *
+ * `ownerId` 是当前王国 Owner principal：知悉回执必须归属于该 principal，
+ * 其他 actor 的历史事件（即使事件类型相同）都不构成 Owner 知悉。
+ */
+export declare function deliveryAcknowledgementView(acknowledgements: DeliveryAcknowledgement[], item: DeliveryItem, ownerId: string): DeliveryItemAcknowledgementView;
+export declare class DeliveryAcknowledgementError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** 幂等事件 ID：同一交付条目版本的再次知悉不会写出第二条事实。 */
+export declare function deliveryAckEventId(kingdomId: string, deliveryId: string, itemId: string, contentHash: string): string;
+export interface RecordDeliveryAcknowledgementInput {
+    kingdomId: string;
+    deliveryId: string;
+    itemId: string;
+    contentHash: string;
+    taskId: string;
+    attemptNo: number;
+    resultId: string;
+    ownerId: string;
+    ownerBindingId: string | null;
+    itemLabel: string;
+    acknowledgedAt: string;
+    /** 已确认的改动证据；仅在主管已选择且本地 hash 重验通过时传入，用于派生相同条目集合。 */
+    changeEvidence?: DeliveryChangeEvidenceInput | null;
+    /**
+     * Owner Control Plane 归因（source_channel / decision_id / operation_id）。
+     * 与既有 `OWNER_OPERATION_APPLIED` 回执同款，便于把知悉事实回溯到具体操作。
+     */
+    attribution?: Record<string, unknown>;
+}
+/**
+ * 追加一条 Owner 知悉事实。
+ *
+ * 前置校验（任一失败即零写入）：
+ * - Task 当前确实处于「主管 ACCEPT 确认交付」状态；
+ * - 传入的 `deliveryId`/`itemId`/`contentHash` 与当前派生结果完全一致
+ *   （防止对旧版本或伪造条目写入知悉）。
+ *
+ * 幂等：同一 (delivery, item, contentHash) 已有记录时原样返回，不追加事件。
+ */
+export declare function recordDeliveryAcknowledgement(store: KingdomStore, input: RecordDeliveryAcknowledgementInput): DeliveryAcknowledgement;
+/** 界面与报告共用的固定措辞：回复只说明主管回答了这个问题。 */
+export declare const DELIVERY_QUESTION_NOTE = "\u63D0\u95EE\u4E0E\u56DE\u590D\u53EA\u662F\u5BF9\u8BDD\u8BB0\u5F55\uFF1A\u5B83\u4EEC\u4E0D\u4EE3\u8868 Owner \u77E5\u6089\u3001\u8D28\u91CF\u8BA4\u53EF\u3001\u4EBA\u7C7B\u9A8C\u6536\u3001Task DONE\uFF0C\u4E5F\u4E0D\u6539\u53D8\u4EFB\u4F55\u4EFB\u52A1\u3001\u5BA1\u67E5\u6216\u53D1\u5E03\u72B6\u6001\u3002";
+/** 未被主管实际读取时只能说「待领取」，不声称已通知或已阅读。 */
+export declare const DELIVERY_QUESTION_UNCLAIMED = "\u5F85\u9886\u53D6\uFF08\u5C1A\u672A\u786E\u8BA4\u4E3B\u7BA1\u5DF2\u8BFB\u53D6\uFF09";
+/**
+ * 回复可达性。`REPLY_ACCESSIBLE` 之外的状态都不得写入回复：
+ * 旧主管退任、session 更换或领地改绑时，问题保持可见但明确不可达，不会自动转给继任者。
+ */
+export declare const DELIVERY_REPLY_STATES: readonly ["REPLY_ACCESSIBLE", "REVIEWER_BINDING_MISSING", "REVIEWER_BINDING_RETIRED", "REVIEWER_SESSION_CHANGED", "SUPERVISOR_REBOUND"];
+export type DeliveryReplyState = (typeof DELIVERY_REPLY_STATES)[number];
+/**
+ * 一条问题相对**当前交付目录**的版本关系。
+ *
+ * - `CURRENT`：该条目此刻重新派生出的版本与问题冻结版本一致（已验证当前）。
+ * - `HISTORICAL`：该条目仍可派生，但版本已变化（可确认的旧版本）。
+ * - `UNVERIFIABLE`：该条目此刻无法从当前 ACCEPT/证据重新派生（例如 CHANGE 证据
+ *   丢失或被替换）；既不能当成当前版，也不能断言它是旧版。后两者都不计当前待办、
+ *   不可回复，但仍可读。
+ */
+export declare const DELIVERY_ITEM_VERSION_STATES: readonly ["CURRENT", "HISTORICAL", "UNVERIFIABLE"];
+export type DeliveryItemVersionState = (typeof DELIVERY_ITEM_VERSION_STATES)[number];
+/** 版本关系判据：只有精确命中当前派生版本才算当前；派生失败一律 fail-as-unknown。 */
+export declare function classifyDeliveryItemVersion(currentItemContentHash: string | null, questionContentHash: string): DeliveryItemVersionState;
+export interface DeliveryQuestion {
+    questionId: string;
+    deliveryId: string;
+    taskId: string;
+    itemId: string;
+    itemLabel: string;
+    contentHash: string;
+    attemptNo: number;
+    resultId: string;
+    /** `TASK_ACCEPTED` 事件所记的主管 binding；这是首版唯一合法的接收者。 */
+    reviewerBindingId: string;
+    /** ACCEPT 证据强度与 exact result-bound（问题写入时冻结）。 */
+    acceptanceEvidenceKind: DeliveryAcceptanceEvidenceKind | 'UNKNOWN';
+    acceptanceEvidenceExact: boolean;
+    ownerId: string;
+    ownerBindingId: string | null;
+    /**
+     * 写入这条问题的 prepared Owner operation；旧记录为 null。
+     *
+     * 它与事件 ID 互为核对：同一 operation 重放必须命中同一 ID，不同 operation
+     * 不得因正文相同而被判为同一条问题。
+     */
+    operationId: string | null;
+    /** 已脱敏的问题正文；只经 Owner 授权窗口或责任主管 Tool 返回。 */
+    questionText: string;
+    askedAt: string;
+    eventId: string;
+    eventSeq: number;
+    reply: DeliveryQuestionReply | null;
+    replyState: DeliveryReplyState;
+    /** 领地主理当前指向的 Supervisor binding；未指派或不存在时为 null。 */
+    currentSupervisorBindingId: string | null;
+    /**
+     * 这条问题相对**当前交付目录**的版本关系：已验证当前、可确认的旧版本，或无法重验。
+     *
+     * 逐条按该条目当前重新派生出的 `contentHash` 判定：后两者仍可读、仍保留原文与回复，
+     * 但**不计当前待办**，界面也不得声称「当前可回复」。这不是可写状态，只是当前交付
+     * 目录与问题冻结版本之间的比较结果。
+     */
+    itemVersion: DeliveryItemVersionState;
+    /** 该条目此刻重新派生出的内容版本；无法派生时为 null，此时不声称任何版本关系。 */
+    currentItemContentHash: string | null;
+}
+export interface DeliveryQuestionReply {
+    questionId: string;
+    responderBindingId: string;
+    /** 已脱敏的回复正文。 */
+    replyText: string;
+    repliedAt: string;
+    eventId: string;
+    eventSeq: number;
+}
+/** 某交付条目的问答线程（Owner 窗口与工作台元数据共用入口）。 */
+export interface DeliveryItemQuestionThread {
+    deliveryId: string;
+    taskId: string;
+    itemId: string;
+    itemLabel: string;
+    /** 目标条目在本次读取中使用的当前内容版本；无法重验时为 null。 */
+    contentHash: string | null;
+    questions: DeliveryQuestion[];
+    answeredCount: number;
+    /** 已验证当前内容版本且尚无回复的条数；历史版与无法重验的未答问题都不计入。 */
+    pendingCount: number;
+    /** 属于可确认的旧内容版本、仅留历史的条数。 */
+    historyCount: number;
+    /** 当前交付目录无法重验该条目版本、因此不声称任何版本关系的条数。 */
+    unverifiableCount: number;
+    /** 最近一条**当前版本**问题；没有当前版本问题时为 null。 */
+    currentQuestionId: string | null;
+    /** 最近一条当前版本问题的内容版本；没有当前版本问题时为 null。 */
+    currentContentHash: string | null;
+}
+/**
+ * 问题事实 ID：**以一次 prepared Owner operation 为界**，不以正文去重。
+ *
+ * 同一 prepared operation 重试（含 submit 重放）由调用方传入同一 operationId，
+ * 因此得到同一事件 ID，只写一条事实；两个**不同** operation 即使针对同一条目、
+ * 同一内容版本、输入完全相同的文字，也各自形成独立问题——提问身份属于一次 Owner
+ * 操作，不属于那段文本。
+ *
+ * 旧记录（冻结时尚未携带 operationId）用写入时冻结的 questionId/contentHash/正文
+ * 派生，保证同一历史问题在任何重放中仍是同一身份。
+ */
+export declare function deliveryQuestionEventId(input: {
+    kingdomId: string;
+    deliveryId: string;
+    itemId: string;
+    contentHash: string;
+    operationId?: string | null;
+    questionId?: string | null;
+    questionText?: string | null;
+}): string;
+/**
+ * 幂等回复 ID：**只由 question ID 决定**，与正文无关。
+ *
+ * 一个问题因此至多存在一条回复事实行；同一文本重试回原事实，不同文本在同一
+ * `BEGIN IMMEDIATE` 事务里看到既有回复行并明确冲突。事件 ID 不含正文，两个并发
+ * 连接不可能各自写出「不同 ID 的双事实」。
+ */
+export declare function deliveryReplyEventId(kingdomId: string, questionId: string): string;
+/**
+ * 读取一条已确认交付的**全部**提问与回复。**只按精确引用的既有事件行读取**，不依赖
+ * 任何有界的最近事件投影：账本里没有记录的问题就不存在。
+ *
+ * 返回的线程按**问题自身**的 item/contentHash 归类，不用首问代表整条交付：
+ * `itemId`/`itemLabel`/`contentHash` 只描述最早那条问题所属的条目，调用方必须用
+ * {@link deliveryQuestionThreadForItem} 按目标条目过滤。
+ */
+export declare function readDeliveryQuestionThread(store: KingdomStore, kingdomId: string, deliveryId: string): DeliveryItemQuestionThread | null;
+/**
+ * 一个**已有提问记录**的精确条目（Owner 只读问答历史入口用；不含任何正文）。
+ *
+ * 它只从权威账本里的提问事实派生，因此条目即使已离开当前交付目录（例如 CHANGE
+ * 证据丢失、条目已改版消失）也仍然可发现；是否可读仍由调用方按窗口 scope 与动作判定。
+ */
+export interface DeliveryQuestionHistoryTarget {
+    deliveryId: string;
+    taskId: string;
+    itemId: string;
+    itemLabel: string;
+    questionCount: number;
+    /** 已验证当前版本且尚无回复的条数；历史版与无法重验的都不计入。 */
+    pendingCount: number;
+    answeredCount: number;
+    historyCount: number;
+    unverifiableCount: number;
+    lastAskedAt: string;
+    /** 最近一条问题相对当前派生版本的版本关系。 */
+    latestItemVersion: DeliveryItemVersionState;
+    /** 该条目此刻重新派生出的内容版本；无法派生时为 null。 */
+    currentContentHash: string | null;
+}
+/**
+ * 列出本王国**已有提问记录**的精确条目索引（按最近提问时间倒序）。
+ *
+ * 只查既有提问事件账本，不依赖任何有界的最近事件投影或当前交付目录：这正是
+ * 「旧问答仍可发现」的最小入口。正文与回复正文不在这里返回，调用方仍须按窗口
+ * scope 过滤后展示，且这些条目**不能**被当作新提问目标（prepare 另有精确重验）。
+ */
+export declare function listDeliveryQuestionHistory(store: KingdomStore, kingdomId: string): DeliveryQuestionHistoryTarget[];
+/**
+ * 一个**精确条目**此刻重新派生出的版本（itemId、contentHash 与当前标签）。
+ *
+ * Owner 的精确 task/item 回读必须用它做版本真值，**不能**用有界展示目录：展示目录
+ * 为了界面规模会截断较旧条目，但那些条目依然是可以精确重验的当前版本。返回 null
+ * 表示该条目此刻无法从当前 ACCEPT/证据重新派生。
+ */
+export declare function readDeliveryItemVersion(store: KingdomStore, kingdomId: string, taskId: string, itemId: string): {
+    itemId: string;
+    contentHash: string;
+    label: string;
+} | null;
+/**
+ * 过滤出**某一交付条目**的问答线程。
+ *
+ * 按每条问题自己的 `itemId` 归类，再按调用方给出的精确 `contentHash` 区分已验证当前、
+ * 历史版与无法重验；不以整条交付的首问代表其他条目。`contentHash` 为 null 表示当前
+ * 交付目录无法重验该条目，此时所有问题都标为无法重验而不是当前版。条目下没有任何
+ * 提问时返回 null，调用方据此说明「该条还没有提问记录」，而不是给出空线程或另一条的线程。
+ */
+export declare function deliveryQuestionThreadForItem(thread: DeliveryItemQuestionThread | null, itemId: string, contentHash: string | null): DeliveryItemQuestionThread | null;
+/**
+ * 回复可达性判据。
+ *
+ * 首版接收者是 `TASK_ACCEPTED` 所记的主管 binding（问题写入时冻结）。这里先看该
+ * binding 自身：不存在 → `REVIEWER_BINDING_MISSING`；已退任 → `REVIEWER_BINDING_RETIRED`；
+ * 领地当前主理已不是它 → `SUPERVISOR_REBOUND`；没有可用于回复的 session →
+ * `REVIEWER_SESSION_CHANGED`。只有全部成立才是 `REPLY_ACCESSIBLE`，否则 fail-closed。
+ *
+ * `claimedSessionId` 是调用方**实际用来证明身份**的 session：它与 binding 当前
+ * session 不一致（即主管已换 session）时同样不可达，避免旧 session 的调用者被误判为
+ * 当前责任主管。
+ */
+export declare function classifyDeliveryReplyAccess(store: KingdomStore, kingdomId: string, reviewerBindingId: string, currentSupervisorBindingId: string | null, claimedSessionId?: string | null): {
+    state: DeliveryReplyState;
+    detail: string;
+};
+/** 公开事件投影的最大字段集：问答正文永不出现。 */
+export declare function toDeliveryQuestionEventPayload(row: EventRow): Record<string, unknown>;
+export declare class DeliveryQuestionError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare const DELIVERY_QUESTION_TEXT_LIMIT = 2000;
+export declare const DELIVERY_REPLY_TEXT_LIMIT = 4000;
+/**
+ * 提问/回复正文的写入形状：先做与公开呈现同一套凭据与路径脱敏，再折叠空白并限长。
+ *
+ * 事实里因此永远不保存未脱敏正文；投影端即使错误地透传字段，也不会带出凭据或本机路径。
+ */
+export declare function boundedQuestionText(value: string, limit: number): string;
+export interface RecordDeliveryQuestionInput {
+    kingdomId: string;
+    deliveryId: string;
+    taskId: string;
+    itemId: string;
+    itemLabel: string;
+    contentHash: string;
+    attemptNo: number;
+    resultId: string;
+    ownerId: string;
+    ownerBindingId: string | null;
+    /** 写入这条问题的 prepared Owner operation；同一 operation 重放必须幂等。 */
+    operationId: string;
+    questionText: string;
+    askedAt: string;
+    /** 已确认的改动证据；与知悉同一来源，保证 CHANGE 条目的清单可重算。 */
+    changeEvidence?: DeliveryChangeEvidenceInput | null;
+    attribution?: Record<string, unknown>;
+}
+/**
+ * 追加一条 Owner 提问事实。
+ *
+ * 前置校验（任一失败即零写入）：
+ * - Task 当前确实处于「同一 Task/attempt 的主管 ACCEPT 确认交付」状态；
+ * - 传入的 delivery/item/contentHash/attempt/result 与当前派生结果完全一致；
+ * - `itemId` 必须正好指向一条提问槽位：入口每次只提交一条精确条目。
+ *
+ * 幂等：同一 `operationId`（即同一次 prepared operation 的重试与重放）已有记录时
+ * 原样返回；**不同 operation 即使问题文字相同，也各自是一条独立问题事实**。
+ */
+export declare function recordDeliveryQuestion(store: KingdomStore, input: RecordDeliveryQuestionInput): {
+    questionId: string;
+    askedAt: string;
+    eventId: string;
+    eventSeq: number;
+    created: boolean;
+};
+/** 回复写入结果：`created=false` 表示同一回复文本已存在，未新增事实。 */
+export interface RecordDeliveryReplyResult {
+    questionId: string;
+    reply: DeliveryQuestionReply;
+    created: boolean;
+}
+/**
+ * 追加一条主管回复事实。
+ *
+ * 写入门槛（任一失败即零写入）：
+ * - 问题必须存在于账本里，且属于本王国、本条交付；
+ * - 传入 item/contentHash/attempt/result 必须与问题记录完全一致，同时仍等于当前
+ *   已确认交付的派生结果（条目改版后不得回复到旧版本）；
+ * - 回复者必须**正好**是问题记录的主管 binding，且该 binding 此刻仍 ACTIVE、仍是
+ *   领地当前主理、其 session 仍是调用者用来证明身份的那个 session；
+ * - CHANGE 条目必须按**当前 ACCEPT 引用**在同一写锁内重新读取并重验证据：证据漂移、
+ *   被替换或条目改版时不再派生该条目，回复 fail-closed。
+ *
+ * 锁前入口校验（`replyToDeliveryQuestion`）只用于尽早拒绝与给出可读原因，**不是**
+ * 写入授权：上面这些可变授权事实全部在 `BEGIN IMMEDIATE` 取得写锁之后重新读取。
+ * 否则「A 先通过入口校验 → B 退任/改绑并提交 → A 再取锁写回复」会写出已失效的回复。
+ * 幂等重试仍在锁内最先判定：既有回复行 + 同一文本原样返回，不因随后改绑而报错，
+ * 也不会新增第二条事实。
+ *
+ * 一问最多一个当前回复，且**只由 question ID 决定回复事件 ID**：同一问题在任何
+ * 并发连接上都只可能写出一条回复事实行。同一文本重试幂等；不同文本明确拒绝。
+ * 「重验 + 单次写入」整体在 `store.withImmediateTransaction` 的 `BEGIN IMMEDIATE`
+ * 事务内完成：该包装在取得写锁之前不执行回调，BEGIN 因 BUSY/LOCKED/I-O/MISUSE
+ * 失败时原样抛出且**零回复写入**，绝不把 BEGIN 失败当作「已有外层事务」继续。
+ * 两个并发连接因此被 SQLite 串行化，不会各自看到空回复而写出双事实。
+ */
+export declare function recordDeliveryReply(store: KingdomStore, input: {
+    kingdomId: string;
+    questionId: string;
+    responderBindingId: string;
+    /**
+     * 调用者用来证明身份的 session（Core 已由 DSH Runtime 核对的 ACTIVE session）。
+     * 锁内会再与 responder binding 当前 session 比对：主管已换 session 时，旧 session
+     * 的调用者不能被当作当前责任主管。
+     */
+    callerSessionId: string;
+    replyText: string;
+    repliedAt: string;
+    attribution?: Record<string, unknown>;
+}): RecordDeliveryReplyResult;
+/**
+ * 按精确 questionId 从权威账本读取一条问题；形状不可核对或不属于该王国时为 null。
+ */
+export declare function readQuestionById(store: KingdomStore, kingdomId: string, questionId: string): DeliveryQuestion | null;
+/** `TASK_ACCEPTED` 事件所记的主管 binding；形状不可核对时为 null（fail-closed）。 */
+export declare function deliveryReviewerBindingId(review: EventRow | null): string | null;
+/**
+ * 主管回复一个提问。
+ *
+ * 与收件箱共用同一套 session-bound 门槛：调用者必须已由 Core 证明为**真实、当前**的
+ * 同领地 ACTIVE 主管 session；问题必须正好写给该 binding，且该 binding 仍是领地当前
+ * 主理（退任、换 session、领地改绑一律拒绝，不改投继任者）。失败零写入。
+ *
+ * 这里的每一条都只是**早拒**：`recordDeliveryReply` 会在同一个写锁事务内用真实
+ * caller session、当前 binding 状态、当前领地主理与当前 ACCEPT 证据重新核对一遍，
+ * 因此锁前状态在等待写锁期间发生变化也不会写出失效回复。
+ *
+ * A question is answered at most once: the same reply text retried is idempotent, a
+ * different reply for the same question is rejected. A reply writes only this one
+ * conversation fact — never an acknowledgement, Task/Claim, supervisor ACCEPT, Owner
+ * acceptance or release fact, and never a dispatch/follow-up/wakeup.
+ */
+export declare function replyToDeliveryQuestion(store: KingdomStore, ctx: CommandContext, input: {
+    questionId: string;
+    replyText: string;
+}): {
+    ok: true;
+    text: string;
+} | {
+    ok: false;
+    code: string;
+    message: string;
+};
+/** 一个 session 的全部 ACTIVE SUPERVISOR 绑定及其合并收件箱。 */
+export interface SessionDeliveryQuestionInbox {
+    /** 该 session 当前可证明的全部 ACTIVE SUPERVISOR binding。 */
+    bindings: RoleBindingRow[];
+    entries: DeliveryQuestionInboxEntry[];
+}
+/**
+ * 按 session 读取**全部**可证明绑定的收件箱。
+ *
+ * 一个 session 可以合法持有多个 ACTIVE SUPERVISOR 绑定；只取第一个会让后续绑定的问题
+ * 静默消失。这里逐 binding 精确读取再合并：每条问题只有一个接收主管，因此不会重复。
+ * 领地界仍是这些 binding 当前主理领地的并集，授权仍由调用方用真实 session 判定。
+ * 找不到任何 binding 时返回空列表，由调用方 fail-closed。
+ */
+export declare function readDeliveryQuestionInboxForSession(store: KingdomStore, kingdomId: string, sessionId: string | null | undefined): SessionDeliveryQuestionInbox;
+export interface DeliveryQuestionInboxScope {
+    /** 调用者由 Core 证明的当前主管 binding；只返回**写给它**的问题。 */
+    reviewerBindingId: string;
+    /** 该主管当前主理的领地；仅用于展示范围的界，授权仍由 session-bound 身份判定。 */
+    territoryIds?: readonly string[];
+}
+/** 收件箱里的一条问题：正文、回复、当前可达性。 */
+export interface DeliveryQuestionInboxEntry {
+    question: DeliveryQuestion;
+    taskTitle: string;
+    territoryName: string;
+}
+/**
+ * 按权威账本精确读取**只属于该主管 binding**的提问。
+ *
+ * 刻意不是「最近事件投影」：逐条从 events 表按 delivery 精确查询，因此不会被
+ * 有界的最近事件窗口截断，也不会看到其他主管或其他领地的问题。
+ */
+export declare function readDeliveryQuestionInbox(store: KingdomStore, kingdomId: string, scope: DeliveryQuestionInboxScope): DeliveryQuestionInboxEntry[];