dsh-kingdom 2.0.0 → 3.2.0

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

@@ -0,0 +1,381 @@
+import type { EventRow, KingdomStore } from './db.js';
+import { CHANGE_EVIDENCE_LABEL, CHANGE_EVIDENCE_NOTE } from './delivery-ack.js';
+export { CHANGE_EVIDENCE_LABEL, CHANGE_EVIDENCE_NOTE };
+export declare const DELIVERY_CHANGE_SNAPSHOT_EVENT_TYPE = "DELIVERY_CHANGE_SNAPSHOT";
+export declare const DELIVERY_CHANGE_MANIFEST_VERSION = "KingdomDeliveryChangeManifest/v1";
+export declare const DELIVERY_CHANGE_SNAPSHOT_VERSION = "KingdomDeliveryWorkspaceSnapshot/v1";
+export declare const CHANGE_EVIDENCE_DRIFT = "\u8BC1\u636E\u6B63\u6587\u7F3A\u5931\u6216\u54C8\u5E0C\u6F02\u79FB\uFF0C\u4E0D\u80FD\u4F5C\u4E3A\u53EF\u4FE1\u6539\u52A8\u5B9A\u4F4D\u3002";
+/** 采集与分析的有界上限；任何一项被触发都会如实反映为部分覆盖。 */
+export interface DeliveryChangeBounds {
+    maxFiles: number;
+    maxFileBytes: number;
+    /**
+     * 单个文件的**完整内容 hash**上限；超过即无法完整比较，只能如实记 `UNKNOWN`，
+     * 不得用「真实大小 + 有界首段」的前缀摘要冒充完整内容 hash。
+     */
+    maxHashBytes: number;
+    /** 单次采集允许读取的总字节数；超出后不再读取，未比较的文件必须如实计入部分覆盖。 */
+    maxReadBytes: number;
+    maxStoredBytes: number;
+    maxDiffLines: number;
+    maxEntries: number;
+    /** Git 候选枚举的字节上限；超出即视为无法安全枚举，如实报失败而不是截断成「无改动」。 */
+    maxCandidateBytes: number;
+    /** VCS 忽略样本的字节上限；只用于报告有多少内容被 ignore 规则排除，不读取其正文。 */
+    maxIgnoredBytes: number;
+}
+export declare const DEFAULT_DELIVERY_CHANGE_BOUNDS: DeliveryChangeBounds;
+export type DeliveryChangePhase = 'PRE' | 'POST';
+/**
+ * `UNKNOWN` 只用于「无法证明是否变化」的候选：内容过长/不可读/是符号链接导致
+ * 比较不可靠。它**不是**可由主管确认的改动条目，选择它会被拒绝。
+ */
+export type DeliveryChangeStatus = 'ADDED' | 'MODIFIED' | 'DELETED' | 'UNKNOWN';
+export type DeliveryChangeEvidenceKind = 'SUPERVISOR_CONFIRMED_BOUNDED_WINDOW';
+export interface DeliverySnapshotCoverage {
+    complete: boolean;
+    observedFiles: number;
+    retainedFiles: number;
+    /** 因上限被跳过的条目数下界；达到文件或读取预算上限后不再继续读取。 */
+    omittedByLimit: number;
+    /** 采集时无法读取、因此无法证明是否变化的候选数。 */
+    omittedUnreadable: number;
+    skippedSymlinks: number;
+    skippedOversize: number;
+    binaryFiles: number;
+    /** 检测到 PEM 私钥/证书标记、因而**不保留正文**的候选数（只保留摘要）。 */
+    sensitiveBodiesSkipped: number;
+    /**
+     * 被 VCS ignore 规则排除、因而从未成为候选的路径数（只计数与保留路径名样本）。
+     *
+     * 这是**有意**的范围限定：候选集合本身完整、只是不含被忽略内容，所以它只让
+     * `complete=false`，**不**使未忽略路径的「不在快照里 = 当时不存在」失效。
+     */
+    ignoredPaths: number;
+    /** 证据目录位于工作区内时被有意排除的路径数（避免把自身快照算成改动），同理不推断枚举被截断。 */
+    evidenceRootExcluded: number;
+    reasons: string[];
+    /** 被 VCS ignore 规则排除的路径名样本；只保留路径，不含正文。 */
+    ignoredSamples: string[];
+}
+export type DeliveryFileReadability = 'READABLE' | 'ABSENT' | 'UNREADABLE' | 'SYMLINK';
+export interface DeliveryWorkspaceFileObservation {
+    /** 工作区内采集用的规范化相对路径；仅用于本地读取与条目身份，不直接作为公开展示路径。 */
+    path: string;
+    /** 仓库相对路径；Owner 展示、主管候选与「查看改动」一律使用这一路径。 */
+    repoPath: string | null;
+    size: number;
+    binary: boolean;
+    symlink: boolean;
+    oversize: boolean;
+    /**
+     * 是否命中 PEM 私钥/证书标记、因而**不保留正文**。两侧任一为 `true` 时差异条目
+     * 都不展示正文片段：否则未命中一侧的历史正文会把另一侧的主体带进公开视图。
+     */
+    sensitive: boolean;
+    /** 是否把脱敏后的正文写入了内容寻址 blob（两侧都保留，便于展示增删片段）。 */
+    retained: boolean;
+    /** 完整内容摘要；无法完整读取（超限/部分读取）时为 null，绝不退化成前缀摘要。 */
+    rawHash: string | null;
+    storedHash: string | null;
+    /** 采集时刻该路径的 `git status --porcelain` 代码；无 VCS 时为 null。 */
+    vcs: string | null;
+    /** 本次采集对该路径的实际可读性判定；决定差异能否被证明。 */
+    readability: DeliveryFileReadability;
+}
+export interface DeliveryRepoIdentity {
+    vcs: 'GIT' | 'UNAVAILABLE';
+    /** 仓库身份的不可逆摘要，避免证据里出现本机绝对路径。 */
+    identity: string | null;
+    head: string | null;
+    scope: 'REPO_ROOT' | 'WORKSPACE_SUBDIR' | 'OUTSIDE_REPO' | 'UNKNOWN';
+    reason: string | null;
+}
+export interface DeliveryWorkspaceSnapshot {
+    version: typeof DELIVERY_CHANGE_SNAPSHOT_VERSION;
+    snapshotId: string;
+    phase: DeliveryChangePhase;
+    taskId: string;
+    attemptNo: number;
+    territoryId: string;
+    workspaceKey: string;
+    executionId: string | null;
+    leaseId: string | null;
+    dispatchId: string | null;
+    repo: DeliveryRepoIdentity;
+    capturedAt: string;
+    files: DeliveryWorkspaceFileObservation[];
+    coverage: DeliverySnapshotCoverage;
+    /** 候选枚举本身的有界元数据（不含正文）：便于区分「无改动」与「没能枚举完整」。 */
+    candidateScope: {
+        kind: 'VCS_CANDIDATES';
+        candidateCount: number;
+        pathspec: string;
+        evidencePrefix: string | null;
+        evidenceRootExcluded: number;
+    };
+    /**
+     * 该时刻的候选集合是否**完整可信**：本快照里「没有该路径」是否可以当成「它当时不存在」。
+     *
+     * 只有下列条件同时成立才为 `true`：候选枚举未被文件/读取预算截断，也没有读不出来的候选。
+     *
+     * `.gitignore` 排除的内容与证据目录自身是**有意**待在候选集合之外的范围限定：候选
+     * 枚举本身是完整的，因此它们只如实记为部分覆盖（`coverage.reasons`），**不**推断
+     * 「未忽略路径的存在性不可证明」。把有意排除当成枚举截断会让真实新增无法确认。
+     */
+    enumerationComplete: boolean;
+    /**
+     * 被 ignore 规则排除的路径身份（工作区相对）；只含路径名，不含任何正文。
+     *
+     * 增删判定不只看「该路径在不在快照里」，还要看它是否出现在**另一时点**的这份身份
+     * 集合中：只改忽略规则时，内容未变的旧文件会离开或进入候选集合，那个缺项其实是被
+     * ignore，既不是窗口内新增也不是窗口内删除。
+     */
+    ignoredPathIdentities: string[];
+    /**
+     * 上述身份集合是否完整可信（枚举未被字节上限截断）。
+     *
+     * `false` 时不得把「路径不在集合里」当成「它当时未被忽略」：增删判定必须 fail-closed，
+     * 否则无法排除「另一个时点其实被 ignore」这一可能。
+     */
+    ignoredPathsComplete: boolean;
+}
+export interface DeliveryChangeHunk {
+    kind: 'ADDED' | 'REMOVED';
+    beforeLine: number | null;
+    afterLine: number | null;
+    text: string;
+}
+export interface DeliveryChangeEntry {
+    entryId: string;
+    /** 工作区相对路径；本地读取与身份用，不作为公开展示路径。 */
+    path: string;
+    /** 仓库相对路径（Owner 详情、主管候选与工作台固定展示这一条）。 */
+    repoPath: string;
+    status: DeliveryChangeStatus;
+    reasonCode: string;
+    labels: string[];
+    note: string;
+    binary: boolean;
+    bodyRetained: boolean;
+    beforeHash: string | null;
+    afterHash: string | null;
+    /** 基线正文未保留（预算/二进制/超限）时无法展示删除片段。 */
+    baselineBodyUnavailable: boolean;
+    hunks: DeliveryChangeHunk[];
+}
+export interface DeliveryChangeManifest {
+    version: typeof DELIVERY_CHANGE_MANIFEST_VERSION;
+    evidenceId: string;
+    taskId: string;
+    attemptNo: number;
+    territoryId: string;
+    workspaceKey: string;
+    repo: DeliveryRepoIdentity;
+    executionId: string | null;
+    leaseId: string | null;
+    dispatchId: string | null;
+    pre: {
+        snapshotId: string;
+        capturedAt: string;
+        coverage: DeliverySnapshotCoverage;
+    };
+    post: {
+        snapshotId: string;
+        capturedAt: string;
+        coverage: DeliverySnapshotCoverage;
+    };
+    entries: DeliveryChangeEntry[];
+    coverage: {
+        complete: boolean;
+        reasons: string[];
+        entryCount: number;
+        omitted: number;
+    };
+    note: string;
+    createdAt: string;
+}
+/** 主管 ACCEPT 时显式选中的改动引用（写入 TASK_ACCEPTED payload）。 */
+export interface DeliveryChangeEvidenceRef {
+    kind: DeliveryChangeEvidenceKind;
+    evidenceId: string;
+    attemptNo: number;
+    entryIds: string[];
+    selectionDigest: string;
+    entryCount: number;
+    selectedCount: number;
+    coverageComplete: boolean;
+    coverageReasons: string[];
+    repoHead: string | null;
+    note: string;
+}
+export interface DeliveryEvidencePaths {
+    root: string;
+    snapshots: string;
+    blobs: string;
+    manifests: string;
+}
+/**
+ * 交付改动证据的专用本机持久目录：<dshHome>/kingdom/delivery-evidence。
+ *
+ * 只保存有界、脱敏、内容寻址的快照与差异；不接触 kingdom.db 本身。
+ * `DSH_KINGDOM_EVIDENCE_ROOT` 只用于把测试指向一次性临时目录。
+ */
+export declare function deliveryEvidenceRoot(): string;
+export declare function deliveryEvidencePaths(evidenceRoot?: string): DeliveryEvidencePaths;
+export declare function readChangeBlob(evidenceRoot: string | undefined, storedHash: string): string | null;
+export type CaptureSnapshotResult = {
+    ok: true;
+    snapshot: DeliveryWorkspaceSnapshot;
+    snapshotFile: string;
+} | {
+    ok: false;
+    code: string;
+    reason: string;
+};
+export interface CaptureSnapshotInput {
+    workspacePath: string;
+    taskId: string;
+    attemptNo: number;
+    territoryId: string;
+    phase: DeliveryChangePhase;
+    executionId?: string | null;
+    leaseId?: string | null;
+    dispatchId?: string | null;
+    evidenceRoot?: string;
+    bounds?: Partial<DeliveryChangeBounds>;
+    now?: string;
+}
+/**
+ * 冻结一份有界工作区快照。**永不抛出**：采集失败只返回 `ok:false`，
+ * 调用方据此不产生任何改动链接，而不是把失败伪装成空差异。
+ *
+ * 候选路径全部来自 Git（见 {@link enumerateCandidates}）：没有可用的 Git 基准、
+ * 枚举失败或输出超限时直接返回失败，绝不退化成「扫描任意工作区正文」。
+ */
+export declare function captureWorkspaceSnapshot(input: CaptureSnapshotInput): CaptureSnapshotResult;
+export declare function readWorkspaceSnapshot(evidenceRoot: string | undefined, snapshotId: string): DeliveryWorkspaceSnapshot | null;
+export declare function deliveryChangeEvidenceId(manifest: DeliveryChangeManifest): string;
+export type BuildChangeManifestResult = {
+    ok: true;
+    manifest: DeliveryChangeManifest;
+    file: string;
+} | {
+    ok: false;
+    code: string;
+    reason: string;
+};
+/** 采集执行前的有界基线；失败返回 null（调用方不得伪造空差异）。 */
+export declare function capturePreChangeSnapshot(input: Omit<CaptureSnapshotInput, 'phase'>): DeliveryWorkspaceSnapshot | null;
+export interface CompleteChangeManifestInput {
+    workspacePath: string;
+    pre: DeliveryWorkspaceSnapshot;
+    taskId: string;
+    attemptNo: number;
+    territoryId: string;
+    executionId?: string | null;
+    leaseId?: string | null;
+    dispatchId?: string | null;
+    evidenceRoot?: string;
+    bounds?: Partial<DeliveryChangeBounds>;
+}
+/**
+ * terminal / WorkerResult 之前采集 POST 并生成差异 manifest。
+ *
+ * 采集或写入任一步失败都返回 null：宁可没有改动定位，也不产生不可信的链接。
+ */
+export declare function capturePostAndBuildChangeManifest(input: CompleteChangeManifestInput): DeliveryChangeManifest | null;
+export interface BuildChangeManifestInput {
+    evidenceRoot?: string;
+    pre: DeliveryWorkspaceSnapshot;
+    post: DeliveryWorkspaceSnapshot;
+    bounds?: Partial<DeliveryChangeBounds>;
+    resultRef?: string | null;
+    now?: string;
+}
+/** 由 PRE/POST 两份快照生成有界、脱敏的差异 manifest，并原子写入内容寻址文件。 */
+export declare function buildDeliveryChangeManifest(input: BuildChangeManifestInput): BuildChangeManifestResult;
+/** 有界行级差异：裁掉公共前后缀后，把中段如实标成 REMOVED/ADDED 片段。 */
+export declare function diffLines(before: string, after: string, maxLines: number): DeliveryChangeHunk[];
+export type VerifyChangeManifestResult = {
+    ok: true;
+    manifest: DeliveryChangeManifest;
+} | {
+    ok: false;
+    code: string;
+    reason: string;
+};
+/** 读回并按内容寻址重验 manifest 与保留正文的 hash；漂移即不可用。 */
+export declare function verifyChangeManifest(evidenceRoot: string | undefined, evidenceId: string): VerifyChangeManifestResult;
+/** 读取由主管 ACCEPT 绑定在该 Task 上的改动证据引用。 */
+export declare function readAcceptedChangeEvidence(review: EventRow | null): DeliveryChangeEvidenceRef | null;
+export declare function selectionDigest(entryIds: readonly string[]): string;
+/**
+ * 校验主管显式选择：evidence 必须存在且 hash 一致，选中的 entry 必须真实存在。
+ * 任一失败都返回错误，调用方必须拒绝并零写入。
+ */
+export declare function validateChangeSelection(evidenceRoot: string | undefined, manifest: DeliveryChangeManifest, entryIds: readonly string[], expected: {
+    taskId: string;
+    attemptNo: number;
+}): {
+    ok: true;
+    ref: DeliveryChangeEvidenceRef;
+} | {
+    ok: false;
+    code: string;
+    reason: string;
+};
+/** 事件载荷：只含 task/attempt/result、manifest/hash 与有界元数据，不含仓库正文。 */
+export declare function changeSnapshotEventPayload(manifest: DeliveryChangeManifest, resultRef: string | null): Record<string, unknown>;
+export declare function changeSnapshotEventId(kingdomId: string, taskId: string, attemptNo: number, executionRef: string | null): string;
+/** Territory canonical workspace 的不可逆摘要，用于把快照绑定到具体领地工作区。 */
+export declare function workspaceKeyOf(workspacePath: string): string | null;
+export interface ChangeSnapshotEventRef {
+    event: EventRow;
+    evidenceId: string;
+    attemptNo: number;
+    resultId: string | null;
+    executionId: string | null;
+    coverageComplete: boolean;
+    coverageReasons: string[];
+}
+/** 精确读取某 Task/attempt 的改动快照事件（不走有界 GUI 投影）。 */
+export declare function readChangeSnapshotEvent(store: KingdomStore, kingdomId: string, taskId: string, attemptNo: number): ChangeSnapshotEventRef | null;
+/** 主管候选清单用的有界条目视图（只读，不写任何事实）；展示路径是仓库相对路径。 */
+export declare function listChangeEntries(manifest: DeliveryChangeManifest, limit?: number): {
+    entryId: string;
+    repoPath: string;
+    status: string;
+    note: string;
+}[];
+/** 读回一条已确认改动条目的有界视图：只按 entry id 取，不接受任意路径。 */
+export declare function readChangeEntry(evidenceRoot: string | undefined, ref: DeliveryChangeEvidenceRef, entryId: string): {
+    ok: true;
+    entry: DeliveryChangeEntry;
+    manifest: DeliveryChangeManifest;
+} | {
+    ok: false;
+    code: string;
+    reason: string;
+};
+/** 交付条目派生用的已解析证据形状（与 `delivery-ack.ts` 的结构一致）。 */
+export interface ResolvedChangeEvidence {
+    evidenceId: string;
+    attemptNo: number;
+    repoHead: string | null;
+    coverageComplete: boolean;
+    coverageReasons: string[];
+    note: string;
+    /** 条目展示路径一律是仓库相对路径。 */
+    entries: {
+        entryId: string;
+        repoPath: string;
+        status: string;
+        note: string;
+    }[];
+}
+/**
+ * 把已确认的改动引用解析成可投影条目。任何 hash 漂移或正文缺失都返回 null，
+ * 调用方据此显示「不可定位」，而不是继续用可能被替换的正文。
+ */
+export declare function resolveChangeEvidenceForDelivery(evidenceRoot: string | undefined, ref: DeliveryChangeEvidenceRef): ResolvedChangeEvidence | null;

package/lib/types/core/owner-binding-intent.d.ts

@@ -132,6 +132,11 @@ export interface RoleBindDraftOperation {
         role_type: IntentRoleType;
         role_name: string;
         session_id: string;
+        /**
+         * v3.2.0：主管的任命必须同时给出领地，且席位与主理在同一事务里一次写完。
+         * 因此主管 Draft 是**单步** `role.bind`（带 territory_id），不再有第二步 territory.supervisor。
+         */
+        territory_id?: string;
     };
 }
 export interface RoleSessionDraftOperation {
@@ -160,7 +165,10 @@ export interface OwnerBindingIntentDraft {
     confirmation: typeof DIRECT_SLASH_CONFIRM_REQUIRED | null;
     ambiguity: DraftAmbiguity | null;
 }
-/** Pure materializer for the second direct Slash once role.bind returned its ID. */
+/**
+ * 旧两步流程的材料化（v3.2.0 之前：先 role.bind，再拿返回的 binding_id 执行第二步）。
+ * 3.2.0 起主管任命是单步原子命令，本函数只为仍然引用它的调用方保留，不再是 Draft 的步骤。
+ */
 export declare function canonicalTerritorySupervisorSlash(territoryId: string, supervisorBindingId: string): string | null;
 /** Parse one bounded natural-language intent without performing any write. */
 export declare function draftOwnerBindingIntent(input: OwnerBindingIntentInput): OwnerBindingIntentDraft;