@akagilnc/pi-workflow-roles 0.1.5368 → 0.1.5382

package/src/host-session-record.ts

@@ -26,6 +26,8 @@ import type { RoleTurnContinuation } from "./host-contracts.ts";
 import { sitianReport } from "./sitian-facade.ts";
 import type { SitianRecordInput } from "./sitian-contracts.ts";
 
+import { errorText } from "./unknown-value.ts";
+
 /** Volume category under `<run>/session/<kind>/records.jsonl`. */
 export const HOST_SESSION_RECORD_KIND = "host-session" as const;
 
@@ -269,7 +271,7 @@ export function copyAndRecordHostDossier(options: {
       payload: {
         type: "native-session-warning",
         sessionId: options.sessionId,
-        error: error instanceof Error ? error.message : String(error),
+        error: errorText(error),
       },
     });
     return;
@@ -334,7 +336,7 @@ export function copyAndRecordHostDossier(options: {
         landingPath,
         ordinal,
         sessionId: options.sessionId,
-        error: lastError instanceof Error ? lastError.message : String(lastError),
+        error: errorText(lastError),
       },
     });
   }

package/src/inspector-contracts.ts

@@ -5,6 +5,7 @@
  */
 
 import { REVIEW_QUEUE_STATUSES, REVIEW_SUBMISSION_OUTPUT_TOOL_NAME } from "./review-submission.ts";
+import { isRecord } from "./unknown-value.ts";
 
 export const INSPECTOR_OUTPUT_TOOL_NAME: string = REVIEW_SUBMISSION_OUTPUT_TOOL_NAME;
 export const INSPECTOR_SOURCE_RUN_FLAG = {
@@ -21,7 +22,7 @@ export type InspectorOutput =
   | { readonly status: "escalate"; readonly reason?: unknown; readonly findings?: unknown };
 
 export function validateRecordedInspectorOutput(value: unknown): InspectorOutput {
-  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+  if (!isRecord(value)) {
     throw new Error("Inspector output has no execution discriminator");
   }
   let status: unknown;

package/src/inspector-role.ts

@@ -1,5 +1,6 @@
 import type { Static } from "typebox";
 import { reviewSubmissionSchema } from "./review-submission.ts";
+import { roleSubmissionDeclaration } from "./role-submission-declarations.ts";
 import {
   INSPECTOR_OUTPUT_TOOL_NAME,
   validateRecordedInspectorOutput,
@@ -25,10 +26,4 @@ export type InspectorRuntimeDependencies = {
 /**
  * 决定工具规格。生命周期装配归注册信封 owner——src/role-runtime.ts（ADR 0018）。
  */
-export const INSPECTOR_TOOL_SPEC = {
-  name: INSPECTOR_OUTPUT_TOOL_NAME,
-  label: "台院输出",
-  description: "台院终局回执，状态为 converged、continue 或 escalate。",
-  promptSnippet: "台院终局回执",
-  parameters: inspectorOutputSchema,
-} as const;
+export const INSPECTOR_TOOL_SPEC = roleSubmissionDeclaration("inspector");

package/src/judge-role.ts

@@ -1,10 +1,7 @@
-import {
-  type RoleHost,
-  type HostContext,
-  type HostToolResult,
-} from "./host-contracts.ts";
-import type { Static } from "typebox";
-import { reviewSubmissionSchema } from "./review-submission.ts";
+import { type RoleHost } from "./host-contracts.ts";
+import { REVIEW_QUEUE_STATUSES, reviewSubmissionSchema, type ReviewQueueWord } from "./review-submission.ts";
+import { registerFiledSubmissionTool } from "./filed-submission.ts";
+import { roleSubmissionDeclaration } from "./role-submission-declarations.ts";
 import { type GatekeeperSubject } from "./gatekeeper-role.ts";
 import {
   JUDGE_OUTPUT_TOOL_NAME,
@@ -31,10 +28,10 @@ export async function runJudgeGates(input: {
     readonly runDirectory?: string;
   } | void>;
 }): Promise<{
-  readonly status: "converged" | "continue" | "escalate";
+  readonly status: ReviewQueueWord;
   readonly passes: readonly {
     readonly subject: GatekeeperSubject;
-    readonly status: "converged" | "continue" | "escalate";
+    readonly status: ReviewQueueWord;
     readonly receipt: unknown;
     readonly runId?: string;
     readonly runDirectory?: string;
@@ -42,7 +39,7 @@ export async function runJudgeGates(input: {
 }> {
   const passes: {
     subject: GatekeeperSubject;
-    status: "converged" | "continue" | "escalate";
+    status: ReviewQueueWord;
     receipt: unknown;
     runId?: string;
     runDirectory?: string;
@@ -50,10 +47,11 @@ export async function runJudgeGates(input: {
   for (const subject of JUDGE_GATES) {
     if (await input.gateAlreadyConverged(subject)) continue;
     const pass = await input.runGate(subject);
-    const status = pass?.status;
-    if (pass === undefined || (status !== "converged" && status !== "continue" && status !== "escalate")) {
+    const received = pass?.status;
+    if (pass === undefined || typeof received !== "string" || !REVIEW_QUEUE_STATUSES.has(received)) {
       throw new Error("judge gate returned no conclusion");
     }
+    const status = received as ReviewQueueWord;
     passes.push({
       subject,
       status,
@@ -90,18 +88,8 @@ export function createJudgeRoleRuntime(
       if (soul.length === 0) throw new Error("Judge soul is empty");
       if (!lifecycleRegistered) {
         lifecycleRegistered = true;
-        pi.registerTool({
-          name: JUDGE_OUTPUT_TOOL_NAME,
-          label: "大理寺输出",
-          description: "提交大理寺终局判词；交卷调用结束后，由公开调用接缝按判词状态执行适用审核。",
-          promptSnippet: "提交大理寺终局判词",
-          parameters: judgeVerdictSchema,
-          async execute(toolCallId: string, parameters: Static<typeof judgeVerdictSchema>, signal: AbortSignal | undefined, _onUpdate: unknown, ctx: HostContext): Promise<HostToolResult<unknown>> {
-            if (soul === undefined) throw new Error("大理寺职分未装载");
-            // ADR 0003: record the original receipt and end the tool call first.
-            // The public seam reads status and chooses the next route.
-            return { content: [], details: parameters, terminate: true };
-          },
+        registerFiledSubmissionTool(pi, roleSubmissionDeclaration("judge"), {
+          readyError: () => (soul === undefined ? "大理寺职分未装载" : undefined),
         });
         pi.on("before_agent_start", (event) => {
           if (soul === undefined) throw new Error("大理寺职分未装载");

package/src/ledger-session-read.ts

@@ -4,6 +4,8 @@
  */
 import { readFile } from "node:fs/promises";
 
+import { isRecord } from "./unknown-value.ts";
+
 export type LedgerSessionRow = Record<string, unknown>;
 
 /**
@@ -32,10 +34,6 @@ export class LedgerSessionJsonlError extends Error {
   }
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 /**
  * One physical JSONL line as the single kernel saw it.
  * `row` present = syntactically complete session object at that 1-based line.
@@ -339,4 +337,3 @@ export function intervalRowsAroundAnchor(
   return { rows: rows.slice(start, end), closed: end < rows.length };
 }
 
-

package/src/merger-contracts.ts

@@ -3,17 +3,19 @@ import { exactUtf8 } from "./exact-utf8.ts";
 import { openToolObject } from "./open-tool-schema.ts";
 import { withTerminatingOutputDeclarations } from "./package-contracts/terminating-infrastructure.ts";
 
-const materialSchema = Type.Object({ bytesBase64: Type.String(), sha256: Type.String() }, { additionalProperties: false });
-const checkSchema = Type.Object({ name: Type.String({ minLength: 1 }), argv: Type.Array(Type.String({ minLength: 1 }), { minItems: 1 }) }, { additionalProperties: false });
+import { isRecord } from "./unknown-value.ts";
+
+const materialSchema = Type.Object({ bytesBase64: Type.String(), sha256: Type.String() });
+const checkSchema = Type.Object({ name: Type.String({ minLength: 1 }), argv: Type.Array(Type.String({ minLength: 1 }), { minItems: 1 }) });
 export const mergerInputSchema = Type.Object({
   attemptId: Type.String({ minLength: 1, description: "对账 attempt 身份（transport）" }),
   targetObjectId: Type.String({ description: "材料：target parent OID；可空" }),
   sourceObjectId: Type.String({ description: "材料：source parent OID；可空" }),
-  materials: Type.Object({ task: materialSchema, authority: materialSchema, targetIntent: materialSchema, sourceIntent: materialSchema }, { additionalProperties: false }),
+  materials: Type.Object({ task: materialSchema, authority: materialSchema, targetIntent: materialSchema, sourceIntent: materialSchema }),
   expectedConflictPaths: Type.Array(Type.String(), { description: "材料：当前未合并路径；可空" }),
   resolutionScope: Type.Array(Type.String(), { description: "材料：解析范围提示；可空" }),
   authorizedChecks: Type.Array(checkSchema),
-}, { additionalProperties: false });
+});
 // #836 r16 class 1: attemptId/report/diagnosis/mergeCommitId are LLM/human-read
 // narrative content (candidate stored as submitted) — no code branches on their
 // length. mergerInputSchema (host-authored material, not role output) is out of scope.
@@ -42,7 +44,6 @@ export type MergerOutput =
   | { status: "escalate"; attemptId: string; diagnosis: string; report: string };
 export const MERGER_OUTPUT_TOOL_NAME = "ak_merger_output";
 
-const record = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v);
 const blank = (v: unknown) => typeof v !== "string" || v.trim().length === 0;
 export class MergerInputContractError extends Error {
   constructor(message = "Merger input violates its exact contract") { super(message); this.name = "MergerInputContractError"; }
@@ -53,16 +54,16 @@ const asString = (v: unknown): string => typeof v === "string" ? v : "";
 const asStringArray = (v: unknown): string[] => Array.isArray(v) ? v.filter((item): item is string => typeof item === "string") : [];
 
 function readMaterial(value: unknown, label: string): MergerMaterial {
-  if (!record(value) || typeof value.bytesBase64 !== "string") fail(`Merger ${label} material is malformed`);
+  if (!isRecord(value) || typeof value.bytesBase64 !== "string") fail(`Merger ${label} material is malformed`);
   exactUtf8(Buffer.from(value.bytesBase64, "base64"), `Merger ${label} material`);
   return { bytesBase64: value.bytesBase64, sha256: typeof value.sha256 === "string" ? value.sha256 : "" };
 }
 
 export function validateMergerInput(value: unknown): MergerInput {
-  if (!record(value) || blank(value.attemptId)) fail("Merger input requires a non-empty attemptId for accounting");
-  if (!record(value.materials)) fail("Merger materials are missing");
+  if (!isRecord(value) || blank(value.attemptId)) fail("Merger input requires a non-empty attemptId for accounting");
+  if (!isRecord(value.materials)) fail("Merger materials are missing");
   const materials = { task: readMaterial(value.materials.task, "task"), authority: readMaterial(value.materials.authority, "authority"), targetIntent: readMaterial(value.materials.targetIntent, "targetIntent"), sourceIntent: readMaterial(value.materials.sourceIntent, "sourceIntent") };
-  const authorizedChecks = Array.isArray(value.authorizedChecks) ? value.authorizedChecks.filter((check): check is Record<string, unknown> => record(check)).map(c => ({ name: asString(c.name), argv: asStringArray(c.argv).filter(a => a.trim().length > 0) })).filter(c => c.name.trim().length > 0 && c.argv.length > 0) : [];
+  const authorizedChecks = Array.isArray(value.authorizedChecks) ? value.authorizedChecks.filter((check): check is Record<string, unknown> => isRecord(check)).map(c => ({ name: asString(c.name), argv: asStringArray(c.argv).filter(a => a.trim().length > 0) })).filter(c => c.name.trim().length > 0 && c.argv.length > 0) : [];
   return deepFreeze(structuredClone({ attemptId: (value.attemptId as string).trim(), targetObjectId: asString(value.targetObjectId), sourceObjectId: asString(value.sourceObjectId), materials, expectedConflictPaths: asStringArray(value.expectedConflictPaths), resolutionScope: asStringArray(value.resolutionScope), authorizedChecks }) as MergerInput);
 }
 

package/src/merger-role.ts

@@ -1,10 +1,11 @@
-import type { RoleHost, HostContext } from "./host-contracts.ts";
+import type { RoleHost } from "./host-contracts.ts";
 import {
   MERGER_OUTPUT_TOOL_NAME,
-  mergerOutputSchema,
   validateMergerInput,
   type MergerInput,
 } from "./merger-contracts.ts";
+import { registerFiledSubmissionTool } from "./filed-submission.ts";
+import { roleSubmissionDeclaration } from "./role-submission-declarations.ts";
 import { exactUtf8 } from "./exact-utf8.ts";
 
 export { MERGER_OUTPUT_TOOL_NAME };
@@ -35,12 +36,8 @@ export function createMergerRoleRuntime(pi: RoleHost, dependencies: MergerRoleDe
       activation = { soul, input };
       if (!registered) {
         registered = true;
-        pi.registerTool({
-          name: MERGER_OUTPUT_TOOL_NAME, label: "合并输出", description: "提交合并结果；输出分支为 completed 与 escalate。", promptSnippet: "提交合并结果", parameters: mergerOutputSchema,
-          async execute(_id: string, params: unknown, _signal: AbortSignal | undefined, _update: unknown, _ctx: HostContext) {
-            if (!activation) throw new Error("校书郎未激活");
-            return { content: [], details: params, terminate: true as const };
-          },
+        registerFiledSubmissionTool(pi, roleSubmissionDeclaration("merger"), {
+          readyError: () => (activation === undefined ? "校书郎未激活" : undefined),
         });
         pi.on("before_agent_start", (event) => {
           if (!activation) throw new Error("校书郎未激活");

package/src/navigator-attendance.ts

@@ -1,4 +1,3 @@
-import { createHash } from "node:crypto";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
@@ -64,6 +63,9 @@ import { createReceiptDeliveryPolicy, NO_RECEIPT_LIFECYCLE_ENTRY_TYPE } from "./
 import { navigatorProseFromUnknown } from "./package-contracts/navigator-output.ts";
 import { persistNavigatorWorkBase } from "./navigator-work-base.ts";
 
+import { sha256Hex } from "./sha256.ts";
+import { isRecord } from "./unknown-value.ts";
+
 export const NAVIGATOR_EVENT_TYPE = "ak-navigator-attendance" as const;
 export { NAVIGATOR_ROUTE_PLAYBOOK_FAILURE_ENTRY };
 
@@ -167,25 +169,21 @@ function unavailableKey(value: unknown): NavigatorUnavailableKey | undefined {
     : undefined;
 }
 
-function exactRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 /** Correlate one rejected prepare call/result inside the just-finished prompt. */
 function rejectedPrepareReason(entries: readonly unknown[], start: number): string | undefined {
   const recent = entries.slice(start);
   const prepareCalls = new Set<string>();
   for (const entry of recent) {
-    if (!exactRecord(entry) || entry.type !== "message" || !exactRecord(entry.message)
+    if (!isRecord(entry) || entry.type !== "message" || !isRecord(entry.message)
       || entry.message.role !== "assistant" || !Array.isArray(entry.message.content)) continue;
     for (const part of entry.message.content) {
-      if (exactRecord(part) && part.type === "toolCall" && part.name === NAVIGATOR_PREPARE_TOOL_NAME
+      if (isRecord(part) && part.type === "toolCall" && part.name === NAVIGATOR_PREPARE_TOOL_NAME
         && typeof part.id === "string") prepareCalls.add(part.id);
     }
   }
   let reason: string | undefined;
   for (const entry of recent) {
-    if (!exactRecord(entry) || entry.type !== "message" || !exactRecord(entry.message)
+    if (!isRecord(entry) || entry.type !== "message" || !isRecord(entry.message)
       || entry.message.role !== "toolResult" || entry.message.isError !== true) continue;
     const callId = entry.message.toolCallId;
     if (entry.message.toolName !== NAVIGATOR_PREPARE_TOOL_NAME
@@ -194,7 +192,7 @@ function rejectedPrepareReason(entries: readonly unknown[], start: number): stri
     }
     const content = entry.message.content;
     const text = Array.isArray(content)
-      ? content.flatMap((part) => exactRecord(part) && typeof part.text === "string" ? [part.text] : []).join("")
+      ? content.flatMap((part) => isRecord(part) && typeof part.text === "string" ? [part.text] : []).join("")
       : typeof content === "string" ? content : "";
     if (text.trim() !== "") reason = text.trim();
   }
@@ -220,7 +218,7 @@ export function navigatorSubjectKey(
   if (provenance === "placeholder") return subjectRoot;
   const normalized = subject.trim().replace(/\s+/g, " ");
   if (normalized === "") return subjectRoot;
-  return `${subjectRoot}#${createHash("sha256").update(normalized).digest("hex").slice(0, 32)}`;
+  return `${subjectRoot}#${sha256Hex(normalized).slice(0, 32)}`;
 }
 
 /**
@@ -485,10 +483,10 @@ export function createNavigatorAttendance(options: NavigatorAttendanceOptions) {
             return undefined;
           }
           const nativeFailure = [...activeSession.entries()].reverse().find((entry: unknown) => {
-            if (!exactRecord(entry) || entry.type !== "message" || !exactRecord(entry.message)) return false;
+            if (!isRecord(entry) || entry.type !== "message" || !isRecord(entry.message)) return false;
             return entry.message.role === "assistant" && typeof entry.message.errorMessage === "string" && entry.message.errorMessage.trim() !== "";
           });
-          const nativeMessage = exactRecord(nativeFailure) && exactRecord(nativeFailure.message) ? nativeFailure.message : undefined;
+          const nativeMessage = isRecord(nativeFailure) && isRecord(nativeFailure.message) ? nativeFailure.message : undefined;
           const errorMessage = nativeMessage !== undefined && typeof nativeMessage.errorMessage === "string"
             ? nativeMessage.errorMessage
             : "Navigator did not submit direction advice";

package/src/navigator-invocation-identity.ts

@@ -19,6 +19,7 @@
 
 import { LEGACY_REVIEW_OUTPUT_ROLES, PACKAGED_ROLE_REGISTRY } from "./packaged-role-registry.ts";
 import { isUuidV7, uuidv7 } from "./uuidv7.ts";
+import { isRecord } from "./unknown-value.ts";
 import { workSubjectKeysEqual } from "./work-subject-identity.ts";
 
 export const NAVIGATOR_INVOCATION_ENTRY = "ak-navigator-invocation" as const;
@@ -83,7 +84,7 @@ export function extractInfrastructureFailureEvidence(error: unknown): Record<str
  * (ADR 0040 — discriminators select the branch, they do not ban extras).
  */
 export function hasNavigatorInfrastructureFailureBase(value: unknown): boolean {
-  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  if (!isRecord(value)) return false;
   const record = value as Record<string, unknown>;
   for (const key of NAVIGATOR_INFRASTRUCTURE_FAILURE_KEYS) {
     if (!Object.hasOwn(record, key)) return false;
@@ -160,7 +161,7 @@ function invocationPhaseFromUnknown(value: unknown): InvocationPhase | undefined
 export function parseInvocationMarkerIdentity(
   data: unknown,
 ): InvocationMarkerIdentity | undefined {
-  if (data === null || typeof data !== "object" || Array.isArray(data)) return undefined;
+  if (!isRecord(data)) return undefined;
   const record = data as Record<string, unknown>;
   const invocationId = record.invocationId;
   if (typeof invocationId !== "string") return undefined;

package/src/navigator-public-session.ts

@@ -29,6 +29,8 @@ import {
   navigatorWorkContextFile,
 } from "./navigator-work-base.ts";
 
+import { isRecord } from "./unknown-value.ts";
+
 /**
  * Ledger process home for navigator attendance: admitted HostContext.runDirectory
  * first, else a parent session file under .ak-roles. Never context.home / env HOME /
@@ -54,10 +56,6 @@ async function resolveNavigatorLedgerHome(context: HostContext): Promise<string
 /** Resume key only — points at a host run principal, never stores advice prose. */
 export const NAVIGATOR_HOST_RUN_POINTER_ENTRY = "ak-navigator-host-run";
 
-function exactRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 export function runIdFromNavigatorDirectory(runDirectory: string): string | undefined {
   const entry = basename(runDirectory);
   const suffix = "@navigator";
@@ -69,10 +67,10 @@ export function runIdFromNavigatorDirectory(runDirectory: string): string | unde
 export function readNavigatorHostRunPointer(entries: readonly unknown[]): string | undefined {
   for (let index = entries.length - 1; index >= 0; index -= 1) {
     const entry = entries[index];
-    if (!exactRecord(entry)) continue;
+    if (!isRecord(entry)) continue;
     if (entry.type === "custom" && entry.customType === NAVIGATOR_HOST_RUN_POINTER_ENTRY) {
       const data = entry.data;
-      if (exactRecord(data) && typeof data.runId === "string" && data.runId.trim() !== "") {
+      if (isRecord(data) && typeof data.runId === "string" && data.runId.trim() !== "") {
         return data.runId.trim();
       }
     }

package/src/navigator-role.ts

@@ -1,16 +1,10 @@
-import { NAVIGATOR_OUTPUT_TOOL_NAME, navigatorOutputSchema } from "./package-contracts/navigator-output.ts";
+import { roleSubmissionDeclaration } from "./role-submission-declarations.ts";
 
 /**
  * 决定工具规格。生命周期装配归注册信封 owner——src/role-runtime.ts（ADR 0018）。
  * #959: navigator speaks free-form prose; tool is a lifecycle vehicle only.
  */
-export const NAVIGATOR_TOOL_SPEC = {
-  name: NAVIGATOR_OUTPUT_TOOL_NAME,
-  label: "游奕使建议",
-  description: "游奕使终局回执：散文建议，原样呈现。",
-  promptSnippet: "游奕使建议",
-  parameters: navigatorOutputSchema,
-} as const;
+export const NAVIGATOR_TOOL_SPEC = roleSubmissionDeclaration("navigator");
 
 export type NavigatorRuntimeDependencies = {
   loadSoul(): Promise<string>;

package/src/navigator-session-contracts.ts

@@ -13,6 +13,7 @@ import { Value } from "typebox/value";
 import type { HostContext, HostInstitutionalModelSelection } from "./host-contracts.ts";
 import type { NoReceiptLifecycleFacts } from "./receipt-delivery-policy.ts";
 
+import { isRecord, errorText, isEnoent } from "./unknown-value.ts";
 
 export const NAVIGATOR_PREPARE_TOOL_NAME = "ak_navigator_prepare" as const;
 
@@ -53,16 +54,12 @@ export function navigatorUnavailableError(
   error: unknown,
   cause: NavigatorUnavailableKey = source,
 ): NavigatorUnavailableError {
-  const message = error instanceof Error ? error.message : String(error);
+  const message = errorText(error);
   return error instanceof NavigatorUnavailableError
     ? error
     : new NavigatorUnavailableError(source, message, cause, error);
 }
 
-function exactRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 export function navigatorProviderFailureFromStatus(status: number | undefined): NavigatorProviderFailureFact | undefined {
   if (status === 401 || status === 403) return { source: "auth", cause: "auth" };
   if (status === 429) return { source: "quota", cause: "quota" };
@@ -86,7 +83,7 @@ export function navigatorProviderFailureFromError(error: unknown): NavigatorProv
     if (cursor instanceof NavigatorUnavailableError) {
       return { source: cursor.unavailableSource, cause: cursor.unavailableCause };
     }
-    if (!exactRecord(cursor)) {
+    if (!isRecord(cursor)) {
       cursor = cursor instanceof Error ? cursor.cause : undefined;
       continue;
     }
@@ -111,13 +108,13 @@ export function navigatorProviderFailureFromError(error: unknown): NavigatorProv
 export function navigatorProviderFailureFromDiagnostics(diagnostics: unknown): NavigatorProviderFailureFact | undefined {
   if (!Array.isArray(diagnostics)) return undefined;
   for (const diagnostic of diagnostics) {
-    if (!exactRecord(diagnostic)) continue;
+    if (!isRecord(diagnostic)) continue;
     if (diagnostic.type === "provider_transport_failure") return { source: "transport", cause: "transport" };
-    if (exactRecord(diagnostic.error)) {
+    if (isRecord(diagnostic.error)) {
       const fromCode = navigatorProviderFailureFromCode(diagnostic.error.code);
       if (fromCode !== undefined) return fromCode;
     }
-    if (exactRecord(diagnostic.details)) {
+    if (isRecord(diagnostic.details)) {
       const status = typeof diagnostic.details.status === "number"
         ? diagnostic.details.status
         : typeof diagnostic.details.statusCode === "number"
@@ -225,13 +222,13 @@ export function navigatorModelSettingPath(): string {
 export async function readNavigatorModelSetting(path = navigatorModelSettingPath()): Promise<string> {
   try {
     const raw = JSON.parse(await readFile(path, "utf8")) as unknown;
-    if (!exactRecord(raw) || typeof raw.model !== "string" || raw.model.trim() === "") {
+    if (!isRecord(raw) || typeof raw.model !== "string" || raw.model.trim() === "") {
       throw new Error("Navigator model setting is malformed");
     }
     return raw.model;
   } catch (error) {
     // #178: missing file is absence (no package default).
-    if (error instanceof Error && "code" in error && (error as NodeJS.ErrnoException).code === "ENOENT") {
+    if (isEnoent(error)) {
       throw new Error("Navigator model setting is missing");
     }
     throw error;

package/src/navigator-work-base.ts

@@ -8,6 +8,7 @@ import { readFile } from "node:fs/promises";
 import { basename, dirname, join, resolve } from "node:path";
 
 import { writeFileAtomically } from "./atomic-write.ts";
+import { isEnoent, isRecord } from "./unknown-value.ts";
 
 export const NAVIGATOR_WORK_CONTEXT_BASENAME = "work-context.json";
 
@@ -51,9 +52,7 @@ export async function persistNavigatorWorkBase(
     const current = await readFile(path, "utf8");
     if (current === next) return path;
   } catch (error) {
-    if (!(error instanceof Error && "code" in error && (error as NodeJS.ErrnoException).code === "ENOENT")) {
-      throw error;
-    }
+    if (!isEnoent(error)) throw error;
   }
   await writeFileAtomically(path, next);
   return path;
@@ -66,9 +65,7 @@ export async function readNavigatorWorkBase(path: string): Promise<NavigatorWork
   try {
     text = await readFile(canonical, "utf8");
   } catch (error) {
-    if (error instanceof Error && "code" in error && (error as NodeJS.ErrnoException).code === "ENOENT") {
-      return undefined;
-    }
+    if (isEnoent(error)) return undefined;
     throw error;
   }
   let parsed: unknown;
@@ -77,7 +74,7 @@ export async function readNavigatorWorkBase(path: string): Promise<NavigatorWork
   } catch {
     return undefined;
   }
-  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return undefined;
+  if (!isRecord(parsed)) return undefined;
   const record = parsed as Record<string, unknown>;
   if (typeof record.subject !== "string" || typeof record.authority !== "string") return undefined;
   if (record.authority.trim() === "") return undefined;
@@ -89,7 +86,7 @@ function jsonObjectFromPrompt(prompt: string): Record<string, unknown> | undefin
   if (!head.startsWith("{")) return undefined;
   try {
     const parsed: unknown = JSON.parse(head);
-    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return undefined;
+    if (!isRecord(parsed)) return undefined;
     return parsed as Record<string, unknown>;
   } catch {
     return undefined;

package/src/navigator-work-context.ts

@@ -6,6 +6,7 @@ import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
 
 import { loadDoctorCase } from "./doctor-evidence.ts";
+import { isEnoent } from "./unknown-value.ts";
 import { runDirectoryFromHostContext, type HostContext } from "./host-contracts.ts";
 import {
   navigatorSubjectKey,
@@ -114,7 +115,7 @@ export async function loadNavigatorWorkContext(
         break;
       }
     } catch (error) {
-      if (!(error instanceof Error && "code" in error && (error as NodeJS.ErrnoException).code === "ENOENT")) throw error;
+      if (!isEnoent(error)) throw error;
     }
   }
   const authority = resolveNavigatorAuthorityMaterial(input, authorityMaterial);

package/src/notary-contracts.ts

@@ -5,6 +5,8 @@
  */
 import { REVIEW_SUBMISSION_OUTPUT_TOOL_NAME, reviewSubmissionSchema } from "./review-submission.ts";
 
+import { isRecord } from "./unknown-value.ts";
+
 export const NOTARY_OUTPUT_TOOL_NAME: string = REVIEW_SUBMISSION_OUTPUT_TOOL_NAME;
 export const NOTARY_SOURCE_RUN_FLAG = {
   name: "ak-notary-source-run",
@@ -41,10 +43,6 @@ export type NotaryOutput =
       readonly findings?: unknown;
     };
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 /**
  * Recognize one lawful explicit Notary release (converged | continue | escalate).
  * #753: no field rewrite — submitted params retained as-is (no disposition forge,
@@ -52,7 +50,7 @@ function isRecord(value: unknown): value is Record<string, unknown> {
  */
 export function projectLawfulNotaryOutput(value: unknown): NotaryOutput | undefined {
   // #836: no field drop
-  return (typeof value === "object" && value !== null && !Array.isArray(value))
+  return (isRecord(value))
     ? (value as NotaryOutput)
     : undefined;
 }
@@ -72,7 +70,7 @@ export function retainNotarySubmission(value: unknown): unknown {
  * Does not gate role admission — callers must not use this to reject a submission.
  */
 export function validateRecordedNotaryOutput(value: unknown): NotaryOutput {
-  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+  if (!isRecord(value)) {
     throw new Error("Notary output is not an object");
   }
   return value as NotaryOutput;

package/src/notary-role.ts

@@ -1,4 +1,6 @@
-import type { RoleHost, HostContext, HostToolResult } from "./host-contracts.ts";
+import type { RoleHost, HostContext } from "./host-contracts.ts";
+import { registerFiledSubmissionTool } from "./filed-submission.ts";
+import { roleSubmissionDeclaration } from "./role-submission-declarations.ts";
 /**
  * Public Notary role runtime — direct officer seat (not through Gatekeeper province).
  * Caller supplies only a source-run locator; Notary self-fetches authoritative materials.
@@ -10,7 +12,6 @@ import {
   NOTARY_OUTPUT_TOOL_NAME,
   NOTARY_SOURCE_RUN_FLAG,
   NOTARY_TICKET_FLAG,
-  notaryOutputSchema,
   type NotarySourceRunLocator,
 } from "./notary-contracts.ts";
 
@@ -156,24 +157,8 @@ export function createNotaryRoleRuntime(
 
       if (!registered) {
         registered = true;
-        pi.registerTool({
-          name: NOTARY_OUTPUT_TOOL_NAME,
-          label: "符宝郎输出",
-          description: "提交引文保真与票面对齐的 converged/continue/escalate 决议。",
-          promptSnippet: "提交符宝郎决议",
-          parameters: notaryOutputSchema,
-          async execute(toolCallId: string, parameters: unknown, _signal: AbortSignal | undefined, _onUpdate: unknown, ctx: HostContext, ): Promise<HostToolResult<unknown>> {
-            if (activation === undefined) {
-              throw new Error("符宝郎未激活");
-            }
-            // #753: handler only records — params as submitted, no findings/disposition rewrite.
-            // #541 infra declaration + sole-final barrier are ledger-owned (#575).
-            return {
-              content: [],
-              details: parameters,
-              terminate: true as const,
-            };
-          },
+        registerFiledSubmissionTool(pi, roleSubmissionDeclaration("notary"), {
+          readyError: () => (activation === undefined ? "符宝郎未激活" : undefined),
         });
         // Evidence assembly only (ADR 0018): soul + bound projection.
         // Ticket value is envelope-admitted at activate — not re-read from flags here.