dsh-kingdom 1.0.0 → 2.0.0

package/lib/types/core/cost.d.ts

@@ -0,0 +1,99 @@
+import type { KingdomStore } from './db.js';
+/** Provider buckets are disjoint; reasoning is already included in output. */
+export interface ProviderTokenCounts {
+    uncachedInputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    reasoningTokens?: number;
+    routes?: readonly {
+        provider: string;
+        model: string;
+    }[];
+}
+/** Neutral source observation. It cannot change role, task, or execution authority. */
+export interface RoleUsageObservation {
+    type: 'KingdomRoleUsage/v1';
+    source: 'provider-reported';
+    sourceUnitRef: string;
+    runtimeInstanceRef: string;
+    sessionRef: string;
+    bindingId: string;
+    roleType: 'CHANCELLOR' | 'SUPERVISOR';
+    taskIds: string[];
+    attribution: 'TASK' | 'SHARED' | 'UNATTRIBUTED';
+    startedAt: string;
+    startedLedgerSeq: number;
+    observationSequence: number;
+    status: 'IN_PROGRESS' | 'COMPLETE' | 'UNAVAILABLE';
+    reasonCode: string | null;
+    observedRequests: number;
+    reportedRequests: number;
+    usage: ProviderTokenCounts | null;
+}
+export interface PromptCostObservation {
+    type: 'KingdomPromptCost/v1';
+    source: 'assembly-byte-observation';
+    sourceUnitRef: string;
+    bindingId: string;
+    roleType: string;
+    toolsBefore: number;
+    toolsAfter: number;
+    toolsBytesBefore: number;
+    toolsBytesAfter: number;
+    sections: {
+        name: string;
+        bytes: number;
+    }[];
+    contexts: {
+        name: string;
+        bytes: number;
+    }[];
+    /** Assembly has no final history envelope; never substitute a zero. */
+    historyBytes: null;
+    tokenEstimate: null;
+    mode: 'off' | 'pilot';
+    reasonCode: string | null;
+}
+export declare function validProviderCounts(usage: ProviderTokenCounts): boolean;
+export declare function recordUsageCoverageGap(store: KingdomStore, kingdomId: string, sourceUnitRef: string, reasonCode: 'ROLE_IDENTITY_AMBIGUOUS'): void;
+/** Arbitrary plugin names are not trusted metadata. Only fixed public categories reach the ledger. */
+export declare function safePromptPartName(value: string, index: number, type: 'section' | 'context'): string;
+export declare function recordRoleUsage(store: KingdomStore, kingdomId: string, input: RoleUsageObservation): boolean;
+export interface AdditionalRoleCostSummary {
+    scope: 'OBSERVED_GOVERNANCE_TURNS';
+    units: number;
+    completeUnits: number;
+    pendingUnits: number;
+    unknownUnits: number;
+    attributionGapCount: number;
+    observedRequests: number;
+    reportedRequests: number;
+    verifiedTokens: number | null;
+    byRole: {
+        roleType: string;
+        units: number;
+        completeUnits: number;
+        verifiedTokens: number | null;
+    }[];
+    sharedTokens: number | null;
+    unattributedTokens: number | null;
+    amount: null;
+    amountStatus: 'PRICE_NOT_CONFIGURED';
+    coverageNote: string;
+}
+/** Lost observer continuity is unknown usage, never proof a Runtime stopped. */
+export declare function closeInterruptedRoleObservations(store: KingdomStore, kingdomId: string, runtimeInstanceRef: string): number;
+export declare function readAdditionalRoleCost(store: KingdomStore, kingdomId: string, taskId?: string): AdditionalRoleCostSummary;
+/** Add only non-Worker observations; Worker dispatch reports are already counted by budget.ts. */
+export declare function readIncompleteRoleUsageSourceRefs(store: KingdomStore, kingdomId: string): string[];
+/** Frozen carry-in sources preserve work already pending when the first policy was created. */
+export declare function readAdditionalBudgetUsage(store: KingdomStore, kingdomId: string, sinceEventSeq: number, carriedSourceRefs?: readonly string[]): {
+    verifiedTokens: number;
+    unknownUnits: number;
+    pendingUnits: number;
+    attributionGapCount: number;
+};
+export declare function recordPromptCost(store: KingdomStore, kingdomId: string, input: PromptCostObservation): void;
+export declare function readLatestPromptCosts(store: KingdomStore, kingdomId: string): PromptCostObservation[];

package/lib/types/core/db.d.ts

@@ -443,6 +443,12 @@ export declare class KingdomStore {
     tombstoneTerritoryRow(territoryId: string, reason: string | null): void;
     /** v0.7.0（M2）：设置 Territory 主理 Supervisor（scope relation；NULL=未指派=fail-closed）。 */
     updateTerritorySupervisor(territoryId: string, supervisorBindingId: string | null): void;
+    updateTerritoryMetadata(territoryId: string, name: string, summary: string | null): void;
+    getEventById(eventId: string): EventRow | null;
+    /** Global append cursor; callers predicting a receipt sequence must hold the write transaction. */
+    eventSequence(): number;
+    /** Owner topology guards include RECOVERING and unknown future nonterminal states. */
+    listUnsettledOwnerExecutions(kingdomId: string): ExecutionRow[];
     insertTaskAssignment(row: TaskAssignmentRow): TaskAssignmentRow;
     /** 当前 active assignment（partial unique index 保证至多一条）。 */
     getActiveAssignmentForTask(taskId: string): TaskAssignmentRow | null;
@@ -511,6 +517,12 @@ export declare class KingdomStore {
      * GUI 比较 revision 就知道要不要重绘，不必 diff 整个 snapshot。
      */
     revision(kingdomId: string): number;
+    /** Observations and future admission/window policy cannot change an in-flight Runner relation. */
+    runnerContextRevision(kingdomId: string, scope?: {
+        taskId: string;
+        workerBindingId: string;
+        sessionRef: string;
+    }): number;
     /**
      * v0.7.0（M2）：外层事务包装——HANDOFF 等**原子治理操作**（多步写 + 事件）整体提交/回滚。
      * appendEvent 的内层 BEGIN 在事务中会抛错，由 appendEvent 的嵌套容忍逻辑接管（见下）。
@@ -556,6 +568,15 @@ export declare class KingdomStore {
     }): TaskRow;
     listWorkerResults(taskId: string): WorkerResultRow[];
     latestWorkerResult(taskId: string): WorkerResultRow | null;
+    /** Exact task/attempt lookup; unrelated kingdom activity cannot hide the reviewed attempt. */
+    latestTaskReworkEvent(kingdomId: string, taskId: string, reviewedAttemptNo: number): EventRow | null;
+    listDispatchUsageEvents(dispatchId: string): EventRow[];
+    /** Complete exact budget ledger; display event windows must never be used as accounting history. */
+    listBudgetEvents(kingdomId: string): EventRow[];
+    listWorkspaceAdmissionEvents(kingdomId: string): EventRow[];
+    listRuntimeCostEvents(kingdomId: string): EventRow[];
+    listActorEventsSince(kingdomId: string, actorId: string, afterSeq: number): EventRow[];
+    getLatestRuntimeRoleUsageEvent(kingdomId: string, sourceUnitRef: string): EventRow | null;
     /** 已落库的最大 attempt_no；无结果时为 0。下一次尝试 = 本值 + 1。 */
     maxAttemptNo(taskId: string): number;
     /**

package/lib/types/core/governed-claim.d.ts

@@ -0,0 +1,7 @@
+import type { KingdomStore } from './db.js';
+/** One terminal dispatch produces one Claim. Runtime completion never accepts a task. */
+export declare function submitGovernedClaim(store: KingdomStore, dispatchId: string, summary: string): {
+    created: boolean;
+    summary: string;
+    outcome: string;
+};

package/lib/types/core/governed.d.ts

@@ -1,4 +1,7 @@
 import { KingdomStore, type AffinityRow, type LeaseRow, type CapabilityDecisionRow, type DispatchRecordRow, type ExecutionRow, type EventRow, StaleStateError } from './db.js';
+import { type BudgetAdmissionHandle } from './budget.js';
+import { type WorkspaceAdmissionHandle } from './workspace-admission.js';
+import { type CollaborationReadiness } from './collaboration.js';
 /** 完整 Runtime Session identity（M3-S1 冻结：(runtime_type, runtime_instance_ref, session_ref)）。 */
 export interface SessionIdentity {
     runtimeType: string;
@@ -13,7 +16,7 @@ export declare class GovernedApiError extends Error {
 export declare class SchemaV4NotMigratedError extends GovernedApiError {
     constructor();
 }
-export type RunnerContextPhase = 'OPEN' | 'ACQUIRED' | 'BOUND' | 'TERMINAL' | 'RECOVERING' | 'RELEASED' | 'INVALID';
+export type RunnerContextPhase = 'OPEN' | 'ACQUIRED' | 'BOUND' | 'TERMINAL' | 'RECOVERING' | 'RECOVERY_TERMINAL' | 'RELEASED' | 'INVALID';
 export type RunnerContextErrorCode = 'RELATION_MISSING' | 'RELATION_MISMATCH' | 'INVALID_HANDLE' | 'INVALID_VERSION' | 'STALE_VERSION' | 'INVALID_ORDER' | 'RECOVERING' | 'RELEASED';
 export declare class RunnerContextError extends GovernedApiError {
     readonly code: RunnerContextErrorCode;
@@ -94,6 +97,18 @@ export declare class RunnerContextPort {
      */
     correlateRuntimeExecution<T>(handle: RunnerContextHandle, version: RunnerContextVersion, runtimeExecutionRef: string, action: (context: RunnerContextActionContext) => T): RunnerContextMutationResult<T>;
     observeTerminal<T>(handle: RunnerContextHandle, version: RunnerContextVersion, action: (context: RunnerContextActionContext) => T): RunnerContextMutationResult<T>;
+    /** Observation timeout retains this original capability; the factory still rejects RECOVERING. */
+    deferRecovery(handle: RunnerContextHandle, version: RunnerContextVersion): RunnerContextMutationResult<ReturnType<typeof markGovernedDispatchRecovering>>;
+    /** Only the original deferred port can consume late evidence; no recovered factory or new Runner. */
+    checkRecovery(handle: RunnerContextHandle, version: RunnerContextVersion): RunnerContextView;
+    recoverTerminal(handle: RunnerContextHandle, version: RunnerContextVersion, input: TerminalEvidenceInput & {
+        runtimeExecutionRef: string;
+    }): RunnerContextMutationResult<{
+        dispatch: DispatchRecordRow;
+        execution: ExecutionRow;
+        lease: LeaseRow;
+    }>;
+    settleRecovery<T>(handle: RunnerContextHandle, version: RunnerContextVersion, action: (context: RunnerContextActionContext) => T): RunnerContextMutationResult<T>;
     settle<T>(handle: RunnerContextHandle, version: RunnerContextVersion, action: (context: RunnerContextActionContext) => T): RunnerContextMutationResult<T>;
 }
 /**
@@ -224,6 +239,9 @@ export interface PrepareGovernedDispatchInput {
     dispatchId?: string;
     preparedAt?: string;
     detail?: string | null;
+    budgetAdmission?: BudgetAdmissionHandle;
+    workspaceAdmission?: WorkspaceAdmissionHandle;
+    collaboration?: CollaborationReadiness | null;
 }
 export interface PreparedGovernedDispatchRows {
     execution: ExecutionRow;

package/lib/types/core/kingdom.d.ts

@@ -1,4 +1,5 @@
 import { KingdomStore } from './db.js';
+import { type OwnerEventSource } from './owner-control.js';
 export interface InitResult {
     action: 'initialized' | 'attached';
     kingdomId: string;
@@ -38,3 +39,5 @@ export declare class KingdomManager {
     rescan(): InitResult;
     close(): void;
 }
+/** Synchronous fact writer shared by direct init and the Owner receipt transaction. */
+export declare function initializeKingdomFacts(store: KingdomStore, kingdomName: string, ownerName: string, source?: OwnerEventSource): InitResult;

package/lib/types/core/owner-control.d.ts

@@ -9,17 +9,33 @@
 import type { KingdomStore, RoleBindingRow } from './db.js';
 import type { AdminAuth } from './binding.js';
 declare const OWNER_CONTROL_MARKER: unique symbol;
+export interface OwnerEventSource {
+    source_channel: 'LOCAL_DIRECT_SLASH' | 'LOCAL_OWNER_GUI';
+    authorization_source?: 'LOCAL_DIRECT_SLASH';
+    decision_id?: string;
+    operation_id?: string;
+}
+export interface OwnerOperationMatch {
+    operation: string;
+    input: unknown;
+}
+/** Stable JSON for exact, immutable operation matching. Undefined follows JSON semantics. */
+export declare function ownerInputHash(input: unknown): string;
 export interface OwnerControlCapability {
     readonly [OWNER_CONTROL_MARKER]: true;
 }
 /** Mint a capability for the direct local Slash handler only. */
 export declare function issueOwnerControlCapability(): OwnerControlCapability;
 export declare function isOwnerControlCapability(value: unknown): value is OwnerControlCapability;
+/** Internal controller seam; requires the original direct capability, never HTTP data. */
+export declare function issueOwnerOperationCapability(authority: OwnerControlCapability, store: KingdomStore, kingdomId: string, match: OwnerOperationMatch, source: OwnerEventSource): OwnerControlCapability;
+export declare function revokeOwnerOperationCapability(capability: OwnerControlCapability): void;
 export interface OwnerControlCheck {
     ok: true;
     owner: RoleBindingRow | null;
     ownerId: string;
-    sourceChannel: 'LOCAL_DIRECT_SLASH';
+    sourceChannel: 'LOCAL_DIRECT_SLASH' | 'LOCAL_OWNER_GUI';
+    eventSource: OwnerEventSource;
 }
 export interface OwnerControlFailure {
     ok: false;
@@ -30,8 +46,8 @@ export interface OwnerControlFailure {
  * OWNER.session_id and all caller/session fields; the only authority input is
  * the opaque capability minted by the direct Slash adapter.
  */
-export declare function requireOwnerControl(store: KingdomStore, kingdomId: string, capability: unknown): OwnerControlCheck | OwnerControlFailure;
+export declare function requireOwnerControl(store: KingdomStore, kingdomId: string, capability: unknown, match?: OwnerOperationMatch): OwnerControlCheck | OwnerControlFailure;
 /** Convert the direct capability into the shared Core admin input. */
 export declare function ownerControlAuth(capability: OwnerControlCapability): AdminAuth;
-export declare function ownerEventPayload(operation: string, fields?: Record<string, unknown>): Record<string, unknown>;
+export declare function ownerEventPayload(operation: string, fields?: Record<string, unknown>, source?: OwnerEventSource): Record<string, unknown>;
 export {};

package/lib/types/core/owner-window.d.ts

@@ -0,0 +1,226 @@
+import type { KingdomStore } from './db.js';
+import { type ExecutionProfileV1 } from './binding.js';
+import { type OwnerControlCapability } from './owner-control.js';
+import { type BudgetPolicyParameters } from './budget.js';
+import { type PlanAdoptionParameters, type CollaborationPlanView } from './collaboration.js';
+export declare const OWNER_MUTATION_ACTIONS: readonly ["init", "territory.create", "territory.update", "territory.supervisor", "role.bind", "role.session", "ceiling", "execution-profile", "budget.policy", "plan.adopt"];
+export type OwnerMutationAction = typeof OWNER_MUTATION_ACTIONS[number];
+export type OwnerManagedRole = 'CHANCELLOR' | 'SUPERVISOR' | 'WORKER';
+export interface OwnerDecisionScope {
+    kingdomWide: boolean;
+    territoryIds: string[];
+    bindingIds: string[];
+    roleTypes: OwnerManagedRole[];
+    targetSessionIds: string[];
+    workspaceRoots: string[];
+}
+export interface OwnerDecisionInput {
+    kingdomId: string | null;
+    actions: OwnerMutationAction[];
+    scope: OwnerDecisionScope;
+    ttlMs: number;
+}
+declare const OWNER_DECISION_HANDLE: unique symbol;
+export interface OwnerDecisionHandle {
+    readonly [OWNER_DECISION_HANDLE]: true;
+}
+export interface OwnerDecisionView {
+    decisionId: string;
+    kingdomId: string | null;
+    ownerId: string | null;
+    actions: OwnerMutationAction[];
+    scope: OwnerDecisionScope;
+    createdAt: string;
+    expiresAt: string;
+    state: 'ACTIVE' | 'EXPIRED' | 'REVOKED' | 'CONSUMED';
+}
+export interface OwnerValidationFailure {
+    ok: false;
+    code: string;
+    message: string;
+}
+export type OwnerValidationResult = {
+    ok: true;
+} | OwnerValidationFailure;
+export interface OwnerSessionValidationInput {
+    kingdomId: string;
+    roleType: 'CHANCELLOR' | 'SUPERVISOR';
+    bindingId: string | null;
+    sessionId: string;
+    signal: AbortSignal;
+}
+export interface OwnerProfileValidationInput {
+    kingdomId: string;
+    bindingId: string;
+    roleType: OwnerManagedRole;
+    profile: Readonly<ExecutionProfileV1> | null;
+    signal: AbortSignal;
+}
+export interface OwnerRuntimeSessionChoice {
+    id: string;
+    label: string;
+}
+export interface OwnerDecisionControllerOptions {
+    now?: () => number;
+    validationTimeoutMs?: number;
+    validateTargetSession: (input: OwnerSessionValidationInput) => Promise<OwnerValidationResult>;
+    validateExecutionProfile: (input: OwnerProfileValidationInput) => Promise<OwnerValidationResult>;
+    listTargetSessions: (input: {
+        sessionIds: readonly string[];
+        signal: AbortSignal;
+    }) => Promise<readonly OwnerRuntimeSessionChoice[]>;
+}
+export interface OwnerOperationCatalog {
+    plans?: CollaborationPlanView[];
+    territories: {
+        id: string;
+        name: string;
+    }[];
+    bindings: {
+        id: string;
+        roleType: string;
+        roleName: string;
+    }[];
+    runtimeSessions: OwnerRuntimeSessionChoice[];
+    workspaceRoots: string[];
+}
+export type OwnerOperationInput = {
+    action: 'init';
+    parameters: {
+        kingdom_name: string;
+        owner_name: string;
+    };
+} | {
+    action: 'territory.create';
+    parameters: {
+        name: string;
+        workspace_path: string;
+        summary?: string | null;
+    };
+} | {
+    action: 'territory.update';
+    parameters: {
+        territory_id: string;
+        name?: string;
+        summary?: string | null;
+    };
+} | {
+    action: 'territory.supervisor';
+    parameters: {
+        territory_id: string;
+        supervisor_binding_id: string;
+    };
+} | {
+    action: 'role.bind';
+    parameters: {
+        role_type: OwnerManagedRole;
+        role_name: string;
+        session_id?: string | null;
+    };
+} | {
+    action: 'role.session';
+    parameters: {
+        binding_id: string;
+        session_id: string;
+    };
+} | {
+    action: 'ceiling';
+    parameters: {
+        ceiling: Record<string, boolean>;
+    };
+} | {
+    action: 'execution-profile';
+    parameters: {
+        binding_id: string;
+        profile: ExecutionProfileV1 | null;
+    };
+} | {
+    action: 'budget.policy';
+    parameters: BudgetPolicyParameters;
+} | {
+    action: 'plan.adopt';
+    parameters: PlanAdoptionParameters;
+};
+export interface OwnerOperationPreview {
+    prepareId: string;
+    operationId: string;
+    decisionId: string;
+    action: OwnerMutationAction;
+    summary: string;
+    changes: {
+        label: string;
+        before: string | null;
+        after: string | null;
+    }[];
+    affected: {
+        territoryIds: string[];
+        bindingIds: string[];
+    };
+    createdAt: string;
+    expiresAt: string;
+}
+export interface OwnerOperationReceipt {
+    type: 'KingdomOwnerOperationReceipt/v1';
+    operationId: string;
+    prepareId: string;
+    decisionId: string;
+    kingdomId: string;
+    ownerId: string;
+    action: OwnerMutationAction;
+    inputHash: string;
+    status: 'APPLIED';
+    target: {
+        type: 'kingdom' | 'territory' | 'binding' | 'collaboration-plan';
+        id: string;
+    };
+    receiptSeq: number;
+    appliedAt: string;
+    message: string;
+}
+export declare class OwnerOperationError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** Trusted-local decision registry. Public IDs and JSON views never confer authority. */
+export declare class OwnerDecisionController {
+    private readonly store;
+    private readonly options;
+    private readonly decisions;
+    private readonly now;
+    private readonly timeout;
+    private disposed;
+    constructor(store: KingdomStore, options: OwnerDecisionControllerOptions);
+    activate(capability: OwnerControlCapability, input: OwnerDecisionInput): {
+        handle: OwnerDecisionHandle;
+        decision: OwnerDecisionView;
+    };
+    inspect(handle: OwnerDecisionHandle): OwnerDecisionView | null;
+    catalog(handle: OwnerDecisionHandle): Promise<OwnerOperationCatalog>;
+    prepare(handle: OwnerDecisionHandle, raw: OwnerOperationInput, options?: {
+        signal?: AbortSignal;
+    }): Promise<OwnerOperationPreview>;
+    commit(handle: OwnerDecisionHandle, input: {
+        prepareId: string;
+        operationId: string;
+    }, options?: {
+        signal?: AbortSignal;
+    }): Promise<OwnerOperationReceipt>;
+    receipt(handle: OwnerDecisionHandle, operationId: string): OwnerOperationReceipt | null;
+    revoke(handle: OwnerDecisionHandle): OwnerDecisionView;
+    dispose(): void;
+    private expire;
+    private invalidate;
+    private active;
+    private assertActive;
+    private observe;
+    private validate;
+    private context;
+    private guardUnsettled;
+    private changes;
+    private apply;
+    /** Synchronous closed dispatcher: no callback or transport receives an administration capability. */
+    private mutate;
+    private event;
+    private receiptEventId;
+}
+export {};

package/lib/types/core/task-service.d.ts

@@ -10,6 +10,42 @@ export interface CommandContext {
     principal?: Principal;
     auth: AuthView;
 }
+/**
+ * 角色校验。
+ *
+ * `declarative`（Phase 1/2 延续）：只确认王国里存在该角色的 binding，
+ * **不验证调用者就是该角色** —— 这是本地可信演示权限，
+ * snapshot 的 `auth.trustLevel` 会如实报成 `local-demo`，GUI 必须显著标注。
+ *
+ * `session-bound`：额外要求调用方 session 与 binding.session_id 一致；
+ * binding 未绑定 session 时**拒绝**（无法验证就不放行，不猜）。
+ */
+export declare function requireRole(store: KingdomStore, ctx: CommandContext, roleType: string): {
+    ok: true;
+    binding: RoleBindingRow;
+} | {
+    ok: false;
+    code: KingdomErrorCode;
+    message: string;
+};
+/**
+ * Resolve the exact ACTIVE Supervisor named by the Task Territory.
+ *
+ * Session-bound callers must prove that the named binding belongs to their
+ * Runtime session. A caller that proves a different ACTIVE Supervisor role is
+ * out of scope; a caller that proves no ACTIVE Supervisor role is unauthorized.
+ * Declarative/local-demo keeps its historical low-trust behavior, but still
+ * resolves the Territory pointer instead of attributing writes to an arbitrary
+ * first Supervisor row.
+ */
+export declare function resolveTaskSupervisor(store: KingdomStore, ctx: CommandContext, task: TaskRow): {
+    ok: true;
+    binding: RoleBindingRow;
+} | {
+    ok: false;
+    code: KingdomErrorCode;
+    message: string;
+};
 /** 公共 governed start 只能由真实 session-bound Supervisor 进入执行器前的授权门。 */
 export declare function resolveGovernedStartSupervisor(store: KingdomStore, ctx: CommandContext, taskId: string): {
     ok: true;

package/lib/types/core/territory.d.ts

@@ -17,6 +17,13 @@ export interface DeleteTerritoryInput {
 }
 export declare function createTerritory(store: KingdomStore, input: CreateTerritoryInput, auth?: AdminAuth): string;
 export declare function listTerritories(store: KingdomStore, kingdomId: string): string;
+/** Metadata-only update. Workspace paths and identity are immutable through this operation. */
+export declare function updateTerritory(store: KingdomStore, input: {
+    kingdomId: string;
+    territoryId: string;
+    name?: string;
+    summary?: string | null;
+}, auth?: AdminAuth): string;
 /**
  * v0.7.0（M2）：设置 Territory 主理 Supervisor（Topology Administration Plane）。
  * - 仅 direct Owner Control capability 可执行（requireAdmin → requireOwnerControl）；

package/lib/types/core/usage.d.ts

@@ -0,0 +1,26 @@
+import type { KingdomStore } from './db.js';
+import type { DshDispatchUsageObservation } from '../adapter/dsh-usage.js';
+export interface DispatchUsageView {
+    type: 'KingdomDispatchUsage/v1';
+    dispatchId: string;
+    taskId: string;
+    attemptNo: number;
+    source: 'provider-reported';
+    status: 'COMPLETE' | 'PARTIAL' | 'UNAVAILABLE';
+    reasonCode: string | null;
+    observedRequests: number;
+    reportedRequests: number;
+    turn: number | null;
+    throughSeq: number | null;
+    usage: {
+        uncachedInputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+        cacheReadTokens?: number;
+        cacheWriteTokens?: number;
+        reasoningTokens?: number;
+    } | null;
+}
+export declare function readDispatchUsage(store: KingdomStore, dispatchId: string): DispatchUsageView | null;
+/** Runtime usage is a separate observation, never terminal/cleanup or task governance evidence. */
+export declare function recordDispatchUsage(store: KingdomStore, dispatchId: string, observed: DshDispatchUsageObservation): void;

package/lib/types/core/workspace-admission.d.ts

@@ -0,0 +1,43 @@
+import type { KingdomStore } from './db.js';
+export type WorkspaceAccess = 'READ_ONLY' | 'WRITE';
+export interface WorkspaceAdmissionInput {
+    kingdomId: string;
+    taskId: string;
+    attemptNo: number;
+    workerBindingId: string;
+    workspacePath: string;
+    access: WorkspaceAccess;
+}
+declare const WORKSPACE_HANDLE: unique symbol;
+export interface WorkspaceAdmissionHandle {
+    readonly [WORKSPACE_HANDLE]: true;
+}
+export declare class WorkspaceAdmissionError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** Resolve existing aliases. A missing directory is rechecked again before dispatch. */
+export declare function canonicalWorkspaceKey(path: string): string;
+export declare function workspaceKeysOverlap(a: string, b: string): boolean;
+/** Both entry points check occupancy inside their fact-creation transaction. Unknown paths overlap conservatively. */
+export declare function assertWorkspaceAvailable(store: KingdomStore, kingdomId: string, key: string | null, access: WorkspaceAccess): void;
+/** Called within the same admission transaction as plan checks and budget reservation. */
+export declare function reserveWorkspaceAdmission(store: KingdomStore, input: WorkspaceAdmissionInput): WorkspaceAdmissionHandle;
+export declare function bindWorkspaceAdmissionInTransaction(store: KingdomStore, handle: WorkspaceAdmissionHandle | undefined, input: {
+    kingdomId: string;
+    taskId: string;
+    attemptNo: number;
+    workerBindingId: string;
+    dispatchId: string;
+    leaseId: string;
+}): void;
+export declare function cancelWorkspaceAdmissionIfSafe(store: KingdomStore, handle: WorkspaceAdmissionHandle): boolean;
+export declare function finishWorkspaceAdmissionInvocation(handle: WorkspaceAdmissionHandle): void;
+export declare function readWorkspaceReservations(store: KingdomStore, kingdomId: string): {
+    taskId: string;
+    attemptNo: number;
+    access: WorkspaceAccess;
+    state: string;
+    recovery: boolean;
+}[];
+export {};

package/lib/types/dispatch/evidence.d.ts

@@ -7,6 +7,7 @@
  * - G12 Foreign/Unmanaged Dispatch 检测：active dispatch 期间出现**非本次 dispatch 的
  *   user 消息** → 标记 untrusted（禁止 settle/release 并声称可信）。
  */
+import { type DshSessionEventSource } from '../adapter/dsh-session-events.js';
 /**
  * turn/end reason → 已知终态 outcome 映射（Owner FINAL REAL-DSH VALIDATION WINDOW · 不改 Schema）：
  *   completed(+assistant) → COMPLETED；aborted → ABORTED；blocked/error/max-tokens → FAILED；
@@ -31,11 +32,7 @@ export interface DispatchEvidence {
     /** 判定为 TERMINAL 的可信理由（turn completed + assistant 消息）。 */
     terminalReason: string | null;
 }
-export interface SessionEventsLike {
-    events: readonly {
-        type: string;
-        data?: Record<string, unknown>;
-    }[];
+export interface SessionEventsLike extends DshSessionEventSource {
 }
 /**
  * 重建一次 dispatch 的执行证据。

package/lib/types/dispatch/service.d.ts

@@ -13,7 +13,11 @@
  */
 import type { KingdomStore, ExecutionRow, DispatchRecordRow, LeaseRow, CapabilityDecisionRow } from '../core/db.js';
 import type { RuntimeAdapter, RuntimeTrustFence, RuntimeTrustFenceExpectation, SessionHandle, DispatchReceipt } from '../adapter/contract.js';
+import type { BudgetAdmissionHandle } from '../core/budget.js';
+import type { WorkspaceAdmissionHandle } from '../core/workspace-admission.js';
+import type { CollaborationReadiness } from '../core/collaboration.js';
 export interface GovernedDispatchInput {
+    stillAuthorized?: () => boolean;
     store: KingdomStore;
     adapter: RuntimeAdapter;
     kingdomId: string;
@@ -29,6 +33,9 @@ export interface GovernedDispatchInput {
     requestSnapshot: string;
     inputRefJson: string;
     payloadHash: string;
+    budgetAdmission?: BudgetAdmissionHandle;
+    workspaceAdmission?: WorkspaceAdmissionHandle;
+    collaboration?: CollaborationReadiness | null;
     /** 终端等待选项（测试可调小）。 */
     pollIntervalMs?: number;
     maxPolls?: number;
@@ -74,6 +81,17 @@ export type CleanupReceipt = {
 };
 /** Keep adapter evidence and settlement reasons bounded before persistence. */
 export declare const MAX_CLEANUP_EVIDENCE_LENGTH = 16384;
+export interface GovernedReconcileResult {
+    status: 'WAIT' | 'RECOVERING' | 'TERMINAL';
+    reason: string;
+    dispatchId: string;
+    cleanupReceipt?: CleanupReceipt;
+    summary?: string;
+}
+/** Plugin teardown drops process evidence, never releases a governance Lease. */
+export declare function discardGovernedRecoveryContexts(store: KingdomStore): void;
+/** Explicit, single-flight observation of an existing original dispatch; never calls dispatch/materialize. */
+export declare function reconcileGovernedDispatch(store: KingdomStore, dispatchId: string, stillAuthorized: () => boolean): Promise<GovernedReconcileResult>;
 /**
  * 受治理派发（TX-3..TX-5）：
  * 1. Execution + Intent（同一事务，COMMIT POINT）→ 2. dispatch（commit 之后）→