@akagilnc/pi-workflow-roles 0.1.5368 → 0.1.5375

package/src/headless-host/role-turn-host.ts

@@ -36,11 +36,12 @@ import {
   headlessTurnArgs,
   isClaudePrintDescription,
   isCodexExecDescription,
-  isPlainObject,
   type HeadlessHostDescription,
 } from "./description.ts";
 import { NAVIGATOR_OUTPUT_TOOL_NAME } from "../package-contracts/navigator-output.ts";
 
+import { errorText, isRecord } from "../unknown-value.ts";
+
 export type HeadlessRoleTurnHostConfig = Readonly<{
   description: HeadlessHostDescription;
   sessionIdentity: SessionIdentityAuthority;
@@ -68,7 +69,7 @@ export type HeadlessCliResult = Readonly<{
  * envelope without stream-json `type`). Intermediate stream-json events are not.
  */
 function isHeadlessResultCandidate(value: unknown): value is HeadlessCliResult {
-  if (!isPlainObject(value)) return false;
+  if (!isRecord(value)) return false;
   const record = value as HeadlessCliResult & { type?: unknown };
   return record.type === undefined
     || record.type === "result"
@@ -131,11 +132,11 @@ function createCodexExecTurnObserver(): {
 
   return {
     observe(value) {
-      if (!isPlainObject(value)) return;
+      if (!isRecord(value)) return;
       const type = typeof value.type === "string" ? value.type : undefined;
       if (type === "thread.started" && typeof value.thread_id === "string" && value.thread_id !== "") {
         threadId = value.thread_id;
-      } else if (type === "item.completed" && isPlainObject(value.item)) {
+      } else if (type === "item.completed" && isRecord(value.item)) {
         if (value.item.type === "agent_message" && typeof value.item.text === "string") {
           finalMessage = value.item.text;
         }
@@ -161,7 +162,7 @@ function createCodexExecTurnObserver(): {
 
 function formatCodexFailurePayload(payload: unknown): string {
   if (typeof payload === "string" && payload.trim() !== "") return payload;
-  if (isPlainObject(payload)) {
+  if (isRecord(payload)) {
     if (typeof payload.message === "string" && payload.message.trim() !== "") return payload.message;
     try {
       return JSON.stringify(payload);
@@ -198,7 +199,7 @@ function resolveGitCommonDir(cwd: string): string | undefined {
       encoding: "utf8",
     });
   } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
+    const message = errorText(error);
     throw new Error(`git rev-parse --git-common-dir failed: ${message}`);
   }
   if (result.error !== undefined) {
@@ -487,7 +488,7 @@ export function createHeadlessRoleTurnHost(config: HeadlessRoleTurnHostConfig):
               ...(gitCommonDir === undefined ? {} : { writableRoots: [gitCommonDir] }),
             });
           } catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
+            const message = errorText(error);
             return {
               status: "terminal",
               result: failure("session", "HeadlessArgvFailure", "argv-failed", { diagnostic: message }, message),
@@ -559,7 +560,7 @@ export function createHeadlessRoleTurnHost(config: HeadlessRoleTurnHostConfig):
           } catch (error) {
             if (childExited) exitedSessionId = (codex ? codexObserver?.result().threadId : undefined) ?? sessionId;
             if (isHostAbortedError(error)) throw error;
-            const message = error instanceof Error ? error.message : String(error);
+            const message = errorText(error);
             const observedHostFailure = codexObserver?.result().failureDiagnostic;
             if (observedHostFailure !== undefined) {
               return {
@@ -604,7 +605,7 @@ export function createHeadlessRoleTurnHost(config: HeadlessRoleTurnHostConfig):
               } catch (error) {
                 // The host failure remains primary; retain persistence failure as
                 // secondary typed evidence instead of replacing the terminal.
-                sessionBindingDiagnostic = error instanceof Error ? error.message : String(error);
+                sessionBindingDiagnostic = errorText(error);
               }
             }
 

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/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/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-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/oauth-keepalive.ts

@@ -10,6 +10,8 @@ import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
+import { errorText, isEnoent, isRecord } from "./unknown-value.ts";
+
 export const DEFAULT_OAUTH_KEEPALIVE_PROVIDERS = ["kimi-coding"] as const;
 
 export const OAUTH_KEEPALIVE_INTERVAL_MS = 60_000;
@@ -25,10 +27,6 @@ export function oauthKeepaliveSettingPath(): string {
   );
 }
 
-function isExactRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 /**
  * Read the static keepalive provider list from the extension setting file.
  * Missing file → default ["kimi-coding"]. Malformed content fails closed.
@@ -39,7 +37,7 @@ export function readOAuthKeepaliveProviders(
 ): readonly string[] {
   try {
     const raw = JSON.parse(readFileSync(path, "utf8")) as unknown;
-    if (!isExactRecord(raw) || !Array.isArray(raw.providers)) {
+    if (!isRecord(raw) || !Array.isArray(raw.providers)) {
       throw new Error(
         "OAuth keepalive setting is malformed: expected { providers: string[] }",
       );
@@ -56,13 +54,7 @@ export function readOAuthKeepaliveProviders(
     return Object.freeze(providers);
   } catch (error) {
     // Absent optional setting uses the documented default; all other causes propagate.
-    if (
-      error instanceof Error &&
-      "code" in error &&
-      (error as NodeJS.ErrnoException).code === "ENOENT"
-    ) {
-      return DEFAULT_OAUTH_KEEPALIVE_PROVIDERS;
-    }
+    if (isEnoent(error)) return DEFAULT_OAUTH_KEEPALIVE_PROVIDERS;
     throw error;
   }
 }
@@ -125,12 +117,7 @@ function errorClassName(error: unknown): string {
 
 function formatWarning(providerId: string, error: unknown): string {
   const cls = errorClassName(error);
-  const detail =
-    error instanceof Error
-      ? error.message
-      : typeof error === "string"
-        ? error
-        : String(error);
+  const detail = errorText(error);
   return `oauth-keepalive: refresh failed for provider ${providerId} (${cls}): ${detail}`;
 }
 

package/src/package-contracts/auditor-output.ts

@@ -4,6 +4,8 @@
  */
 import { REVIEW_SUBMISSION_OUTPUT_TOOL_NAME, reviewSubmissionSchema } from "../review-submission.ts";
 
+import { isRecord } from "../unknown-value.ts";
+
 export const AUDITOR_OUTPUT_TOOL_NAME: string = REVIEW_SUBMISSION_OUTPUT_TOOL_NAME;
 
 export const auditorOutputSchema = reviewSubmissionSchema;
@@ -17,10 +19,6 @@ export type AuditorOutput =
       readonly decisionGate?: unknown;
     };
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 /** #836: no field drop — original object is the receipt. */
 export function projectLawfulAuditorOutput(value: unknown): AuditorOutput | undefined {
   return isRecord(value) ? (value as AuditorOutput) : undefined;

package/src/package-contracts/fixer-packet.ts

@@ -1,12 +1,14 @@
 import { Type, type Static } from "typebox";
 import { Value } from "typebox/value";
 
+import { isRecord } from "../unknown-value.ts";
+
 export const FIXER_PREREQUISITE_ID_PATTERN = "^[A-Za-z0-9][A-Za-z0-9._-]*$";
 
 export const fixerPrerequisiteSchema = Type.Object({
   id: Type.String({ pattern: FIXER_PREREQUISITE_ID_PATTERN }),
   requirement: Type.String({ pattern: "\\S" }),
-}, { additionalProperties: false });
+});
 
 export const fixerPrerequisitesSchema = Type.Array(fixerPrerequisiteSchema);
 export type FixerPrerequisite = Readonly<Static<typeof fixerPrerequisiteSchema>>;
@@ -45,13 +47,9 @@ function fail(cause: unknown): never {
 function parseFailure(value: unknown): never {
   if (!Array.isArray(value)) fail(new Error("Fixer prerequisites must be a JSON array"));
   for (const entry of value) {
-    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+    if (!isRecord(entry)) {
       fail(new Error("Fixer prerequisite entry must be an object with id and requirement fields"));
     }
-    const keys = Object.keys(entry);
-    if (keys.length !== 2 || !keys.includes("id") || !keys.includes("requirement")) {
-      fail(new Error("Fixer prerequisite entry fields must be exactly id and requirement"));
-    }
     if (
       typeof (entry as Record<string, unknown>).id !== "string" ||
       !(new RegExp(FIXER_PREREQUISITE_ID_PATTERN)).test((entry as { id: string }).id)

package/src/package-contracts/gatekeeper-output.ts

@@ -8,6 +8,8 @@ import { Type } from "typebox";
 import { openToolObject } from "../open-tool-schema.ts";
 import { withTerminatingOutputDeclarations } from "./terminating-infrastructure.ts";
 
+import { isRecord } from "../unknown-value.ts";
+
 export const GATEKEEPER_OUTPUT_TOOL_NAME = "ak_gatekeeper_output";
 
 /** Same open decision shape the province uses inside audit sessions. */
@@ -33,10 +35,6 @@ export type GatekeeperDirectOutput =
   | { readonly status: "dispatch"; readonly officer: "inspector" | "notary" }
   | { readonly status: "pass"; readonly findings?: readonly string[] };
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 function asStringArray(value: unknown): readonly string[] {
   if (!Array.isArray(value)) return [];
   return value.filter((item): item is string => typeof item === "string");

package/src/package-contracts/judge-output.ts

@@ -1,6 +1,5 @@
 /** Package-owned Judge output leaf — no role registration surface. */
 
-
 import { REVIEW_QUEUE_STATUSES, REVIEW_SUBMISSION_OUTPUT_TOOL_NAME } from "../review-submission.ts";
 
 export const JUDGE_OUTPUT_TOOL_NAME: string = REVIEW_SUBMISSION_OUTPUT_TOOL_NAME;