@akagilnc/pi-workflow-roles 0.1.5365 → 0.1.5375

package/src/run-terminal-artifacts.ts

@@ -11,6 +11,8 @@ import { basename, dirname, join } from "node:path";
 
 import { roleRunArtifactsDirectory } from "./role-run-placement.ts";
 
+import { isRecord, errorText, isMissingPathError } from "./unknown-value.ts";
+
 export const RUN_TERMINAL_ARTIFACT_FILES = [
   "report.json",
   "error.json",
@@ -49,22 +51,6 @@ export type RunTerminalArtifactRead =
       readonly reason: string;
     };
 
-function isMissingPathError(error: unknown): boolean {
-  return (
-    error instanceof Error
-    && "code" in error
-    && (error.code === "ENOENT" || error.code === "ENOTDIR")
-  );
-}
-
-function errorText(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 /**
  * Minimum producer-owned face shared by settlement terminal artifacts
  * (report / error / audit-incomplete). Consumer-driven: enough to identify a

package/src/run-ticket-number.ts

@@ -8,18 +8,12 @@
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 
+import { isEnoent, isRecord } from "./unknown-value.ts";
+
 /** Sole on-disk page for worktree-basename ticket derivation (#865). */
 export const MIGRATION_TICKET_DERIVATION_PAGE =
   "migration-ticket-derivation.json" as const;
 
-function isEnoent(error: unknown): boolean {
-  return (
-    error instanceof Error &&
-    "code" in error &&
-    (error as NodeJS.ErrnoException).code === "ENOENT"
-  );
-}
-
 /** Sole safe-positive ticket invariant (bind / admission / placement / readers). */
 export function isSafePositiveTicketNumber(value: unknown): value is number {
   return typeof value === "number" && Number.isSafeInteger(value) && value >= 1;
@@ -69,10 +63,10 @@ async function readJsonObject(
 ): Promise<Record<string, unknown> | undefined> {
   try {
     const raw: unknown = JSON.parse(await readFile(path, "utf8"));
-    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    if (!isRecord(raw)) {
       return undefined;
     }
-    return raw as Record<string, unknown>;
+    return raw;
   } catch (error) {
     if (isEnoent(error)) return undefined;
     throw error;

package/src/session-assistant-usage.ts

@@ -7,6 +7,8 @@ import { join } from "node:path";
 
 import type { PublicSummonResult } from "./public-role-summons.ts";
 
+import { errorText } from "./unknown-value.ts";
+
 export async function readAssistantUsageFromSessionFile(
   sessionFile: string,
 ): Promise<Usage | undefined> {
@@ -30,7 +32,7 @@ export async function readAssistantUsageFromSessionFile(
       });
   } catch (error) {
     throw new Error(
-      `session usage parse failed (${sessionFile}): ${error instanceof Error ? error.message : String(error)}`,
+      `session usage parse failed (${sessionFile}): ${errorText(error)}`,
       { cause: error },
     );
   }

package/src/session-dialogue.ts

@@ -1,3 +1,4 @@
+import { isRecord } from "./unknown-value.ts";
 /**
  * 对话事实适配（ADR 0075 `dialogue-only` / `no-tool-output` / `speaker-required`）。
  *
@@ -20,10 +21,6 @@ export type DialogueEvent = {
   readonly id?: string;
 };
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 /**
  * 原生 id：行级或消息体级主键的单一实现（bound 解析与落盘共用）。
  * Pi/CC：行上 `uuid`/`id`；Codex：`response_item.payload.id`（或 `message.id`）。

package/src/session-identity.ts

@@ -42,7 +42,6 @@ export function createSessionIdentityAuthority(
   };
 }
 
-
 /**
  * Native session/thread id already stored for this principal on `host`.
  * Public explicit resume reads it once and hands it to the host adapter.

package/src/sitian-reader.ts

@@ -15,9 +15,7 @@ import type {
   SitianRecord,
 } from "./sitian-contracts.ts";
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
+import { isRecord, errorText } from "./unknown-value.ts";
 
 /** Read a Sitian record volume with full traversal and non-destructive diagnostics. */
 export async function readSitianRecords(recordFile: string): Promise<SitianReadResult> {
@@ -53,7 +51,7 @@ export async function readSitianRecords(recordFile: string): Promise<SitianReadR
         kind: "malformed",
         line: index + 1,
         raw: line,
-        error: error instanceof Error ? error.message : String(error),
+        error: errorText(error),
       });
     }
   }

package/src/submission-correctable-error.ts

@@ -6,6 +6,8 @@ import {
   WorkerUnfinishedReasonReminderError,
 } from "./submission-errors.ts";
 
+import { errorText } from "./unknown-value.ts";
+
 /** Shared, unforgeable identity for submission errors that the same session may correct. */
 const correctableSubmissionErrorBrand = Symbol("ak-roles.correctable-submission-error");
 
@@ -49,7 +51,7 @@ export type CorrectableExecuteRejectionProjection = {
 export function projectCorrectableExecuteRejection(
   error: unknown,
 ): CorrectableExecuteRejectionProjection {
-  const diagnostic = error instanceof Error ? error.message : String(error);
+  const diagnostic = errorText(error);
   if (error instanceof GatekeeperDecisionError) {
     return { diagnostic, details: { ...(error.result as Record<string, unknown>) } };
   }

package/src/submission-errors.ts

@@ -1,5 +1,6 @@
 import type { SubmissionGateNonPassResult } from "./gatekeeper-role.ts";
 import { readableGateItem } from "./readable-gate-item.ts";
+import { isRecord } from "./unknown-value.ts";
 
 /**
  * Tool-result text the parent model sees (#753 / #750 evidence).
@@ -69,7 +70,7 @@ export function unreadableDiscriminatorNotice(field: string, received: unknown):
 
 /** The received discriminator only — never the rest of the receipt. */
 export function receivedDiscriminator(receipt: unknown, field: string): unknown {
-  if (receipt === null || typeof receipt !== "object" || Array.isArray(receipt)) return undefined;
+  if (!isRecord(receipt)) return undefined;
   if (!Object.hasOwn(receipt, field)) return undefined;
   return (receipt as Record<string, unknown>)[field];
 }

package/src/submission-gate.ts

@@ -36,7 +36,7 @@ export function latestQueueStatus(terminal: TerminalResult | undefined): string
   if (outcome.kind === "audit_escalation") return "escalate";
   if (outcome.kind !== "accepted") return undefined;
   const latest = outcome.payloads?.[outcome.payloads.length - 1];
-  if (latest !== null && typeof latest === "object" && !Array.isArray(latest)) {
+  if (isRecord(latest)) {
     const status = (latest as { status?: unknown }).status;
     if (typeof status === "string" && status.trim() !== "") return status;
   }
@@ -54,6 +54,8 @@ export function latestQueuePayload(terminal: TerminalResult | undefined): unknow
 }
 import { sessionFileFromPublicSummon } from "./session-assistant-usage.ts";
 
+import { isRecord } from "./unknown-value.ts";
+
 /**
  * Shared-envelope default officer summon (ADR 0018).
  * Role modules must not own this drive seam — only project results.

package/src/submission-ledger.ts

@@ -12,7 +12,6 @@ import {
   type RoleHost,
 } from "./host-contracts.ts";
 
-
 import { runIdFromRunDirectory } from "./run-terminal-artifacts.ts";
 import { readSitianRecords, resolveSitianRecordPathInLedger, sitianReport, type RecordPointer } from "./sitian-facade.ts";
 import type { SitianRecord } from "./sitian-contracts.ts";
@@ -22,6 +21,8 @@ import { isCorrectableExecuteError } from "./submission-correctable-error.ts";
 import { failOnInfrastructureFailureDeclaration, infrastructureFailureDiagnostic } from "./package-contracts/terminating-infrastructure.ts";
 import { REVIEW_SUBMISSION_OUTPUT_TOOL_NAME } from "./review-submission.ts";
 
+import { isRecord, errorText } from "./unknown-value.ts";
+
 export type SubmissionCall = { readonly id: string; readonly name: string };
 export type SubmissionOutcomeKind = "correctable-rejection" | "audit-escalation" | "infrastructure";
 /** Typed correctable-rejection codes — bounce/reminder paths only (#836: no sole/non-terminate reject). */
@@ -662,9 +663,7 @@ export function createSubmissionLedgerHost(
             // host-failure seam. Tool identity comes from the registry map.
             const reviewEscalate = tool.name === REVIEW_SUBMISSION_OUTPUT_TOOL_NAME
               && infrastructureFailureDiagnostic(params) !== undefined
-              && params !== null
-              && typeof params === "object"
-              && !Array.isArray(params)
+              && isRecord(params)
               && (params as Record<string, unknown>).status === "escalate";
             if (!reviewEscalate) {
               failOnInfrastructureFailureDeclaration(
@@ -688,7 +687,7 @@ export function createSubmissionLedgerHost(
                 toolCallId,
                 outcome: "correctable-rejection",
                 code: "typed-bounce",
-                diagnostic: error instanceof Error ? error.message : String(error),
+                diagnostic: errorText(error),
                 role,
                 accepted: params,
               });
@@ -699,7 +698,7 @@ export function createSubmissionLedgerHost(
                 attemptId,
                 toolCallId,
                 outcome: "infrastructure",
-                diagnostic: error instanceof Error ? error.message : String(error),
+                diagnostic: errorText(error),
                 role,
                 accepted: params,
               });

package/src/ticket-provenance-contracts.ts

@@ -1,3 +1,4 @@
+import { isRecord } from "./unknown-value.ts";
 /**
  * 起居录（ticket-provenance）typed 形状 —— ADR 0075 / ADR 0081 / #1090。
  *
@@ -61,10 +62,6 @@ export type TicketProvenanceLine = {
   readonly text: string;
 };
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 function positiveInteger(value: unknown): number | undefined {
   if (typeof value === "number" && Number.isSafeInteger(value) && value >= 1) return value;
   if (typeof value === "string" && /^[1-9][0-9]*$/.test(value)) {

package/src/ticket-provenance.ts

@@ -32,6 +32,8 @@ import {
   type TicketProvenanceSession,
 } from "./ticket-provenance-contracts.ts";
 
+import { errorText } from "./unknown-value.ts";
+
 /**
  * Typed input failure for diarist bounds/session path (reask, not infrastructure).
  * Accept hook discriminates with instanceof — never Error.message prefixes.
@@ -281,7 +283,7 @@ async function projectSessionRanges(input: {
     if (error instanceof TicketProvenanceInputError) throw error;
     const code = errnoCode(error);
     if (code === "ENOENT" || code === "ENOTDIR" || code === "EISDIR") {
-      const detail = error instanceof Error ? error.message : String(error);
+      const detail = errorText(error);
       throw new TicketProvenanceInputError(
         `session unreadable: ${input.session.path} (${detail})`,
         { cause: error },

package/src/ticket-snapshot.ts

@@ -13,6 +13,8 @@
  */
 import { createGhApiRunner, type GhApiRunner } from "./gh-api-runner.ts";
 
+import { isRecord } from "./unknown-value.ts";
+
 export type BookRepoBinding = {
   bookKey: string;
   owner: string;
@@ -92,10 +94,6 @@ export class TicketSnapshotApiError extends Error {
   }
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 function requireNonEmpty(value: string, label: string): string {
   const trimmed = value.trim();
   if (!trimmed) throw new Error(`${label} must be a non-empty string`);

package/src/ticket-trajectory.ts

@@ -46,6 +46,7 @@ import {
 } from "./package-contracts/terminating-tools.ts";
 import { LEGACY_REVIEW_OUTPUT_ROLES, PACKAGED_ROLE_REGISTRY } from "./packaged-role-registry.ts";
 
+import { isRecord, isMissingPathError } from "./unknown-value.ts";
 
 /** Declared refresh bound for the same viewing surface (seconds). */
 export const DEFAULT_REFRESH_BOUNDARY_SECONDS = 30;
@@ -122,14 +123,6 @@ export type TicketTrajectoryRun = {
 
 type ParsedRun = TicketTrajectoryRun;
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function isMissingPathError(error: unknown): boolean {
-  return error instanceof Error && "code" in error && (error.code === "ENOENT" || error.code === "ENOTDIR");
-}
-
 /** realpath when the node exists; lexical path only for recognized absence — never for other errors. */
 async function realpathOrLexicalIfMissing(path: string): Promise<string> {
   try {

package/src/typed-provider-http.ts

@@ -5,6 +5,8 @@
 import { readFile, unlink, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 
+import { isEnoent, isRecord } from "./unknown-value.ts";
+
 const TYPED_HTTP_FILE = "typed-provider-http.json";
 
 export type TypedProviderHttpObservation = {
@@ -27,13 +29,7 @@ export async function clearTypedProviderHttpObservation(
   try {
     await unlink(typedProviderHttpPath(runDirectory));
   } catch (error) {
-    if (
-      error instanceof Error &&
-      "code" in error &&
-      (error as { code?: unknown }).code === "ENOENT"
-    ) {
-      return;
-    }
+    if (isEnoent(error)) return;
     throw error;
   }
 }
@@ -75,17 +71,11 @@ export async function readLatestTypedProviderHttpObservation(
   try {
     text = await readFile(typedProviderHttpPath(runDirectory), "utf8");
   } catch (error) {
-    if (
-      error instanceof Error &&
-      "code" in error &&
-      (error as { code?: unknown }).code === "ENOENT"
-    ) {
-      return undefined;
-    }
+    if (isEnoent(error)) return undefined;
     throw error;
   }
   const raw: unknown = JSON.parse(text);
-  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+  if (!isRecord(raw)) {
     throw new Error("typed provider HTTP observation must be a JSON object");
   }
   const record = raw as Record<string, unknown>;

package/src/unknown-value.ts

@@ -0,0 +1,34 @@
+import { Guard } from "typebox/guard";
+
+/**
+ * Sole readers for a plain object, a Node errno, and an Error message.
+ * Callers choose which codes count; ENOTDIR is not ENOENT.
+ * Plain objects are TypeBox `Guard.IsObjectNotArray`.
+ */
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return Guard.IsObjectNotArray(value);
+}
+
+export function errnoCode(error: unknown): string | undefined {
+  return error !== null && typeof error === "object" && "code" in error
+    && typeof (error as { code: unknown }).code === "string"
+    ? (error as { code: string }).code
+    : undefined;
+}
+
+/** `Error.message`, otherwise `String(value)`. */
+export function errorText(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** True only for ENOENT on an Error. ENOTDIR and every other code stay distinct. */
+export function isEnoent(error: unknown): boolean {
+  return error instanceof Error && errnoCode(error) === "ENOENT";
+}
+
+/** ENOENT or ENOTDIR on an Error. */
+export function isMissingPathError(error: unknown): boolean {
+  const code = errnoCode(error);
+  return error instanceof Error && (code === "ENOENT" || code === "ENOTDIR");
+}

package/src/user-dialogue-stdin.ts

@@ -3,6 +3,8 @@
  * Pi's piped-stdin reader trims the wrapper; the body field keeps original bytes.
  * No size cap and no path/pointer substitute — the whole dialogue rides the envelope.
  */
+import { isRecord } from "./unknown-value.ts";
+
 export const USER_DIALOGUE_STDIN_KIND = "ak-user-dialogue" as const;
 
 export type UserDialogueStdinEnvelope = {
@@ -15,7 +17,7 @@ export function encodeUserDialogueStdin(body: string): string {
 }
 
 function isUserDialogueEnvelope(value: unknown): value is UserDialogueStdinEnvelope {
-  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  if (!isRecord(value)) return false;
   const record = value as { kind?: unknown; body?: unknown };
   return record.kind === USER_DIALOGUE_STDIN_KIND && typeof record.body === "string";
 }

package/src/worker-role.ts

@@ -29,6 +29,8 @@ import {
   matchFixerBashForbiddenLiteral,
 } from "./fixer-bash-seatbelt.ts";
 
+import { isRecord } from "./unknown-value.ts";
+
 export {
   CODER_OUTPUT_TOOL_NAME,
   FIXER_OUTPUT_TOOL_NAME,
@@ -104,10 +106,6 @@ export type WorkerRoleRuntime = {
   armSubmissionGate(cwd: string, parent: { getSessionFile(): string | undefined }): void;
 };
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 /** Read only the field that selects the worker's next package-owned path. */
 function workerStatusOf(output: WorkerOutput): string | undefined {
   return isRecord(output) && typeof output.status === "string"
@@ -130,7 +128,6 @@ export function validateWorkerOutput(
   return validateAcceptedWorkerDetails(output, "Coder") as CoderOutput;
 }
 
-
 /** Reminder bounces stay typed rejects; IO/infrastructure keep identity via host failInfrastructure. */
 function assertAcceptableThroughHost(
   submissionGate: { assertAcceptable(status: string, details?: unknown): void },

package/src/worker-submission-gates.ts

@@ -17,6 +17,8 @@ import {
 } from "./submission-errors.ts";
 import { WORKER_DONE_STATUSES } from "./worker-submission-contracts.ts";
 
+import { isRecord } from "./unknown-value.ts";
+
 export { WorkerCommitReminderError, WorkerPrefixReminderError, WorkerUnfinishedReasonReminderError } from "./submission-errors.ts";
 export { WORKER_DONE_STATUSES } from "./worker-submission-contracts.ts";
 
@@ -152,15 +154,11 @@ function uninstallPackageWorkerHooks(cwd: string): void {
   }
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 /** ADR 0050: a written explanation, including text carried by an object key. */
 function containsWrittenReason(value: unknown): boolean {
   if (typeof value === "string") return value.trim().length > 0;
   if (Array.isArray(value)) return value.some(containsWrittenReason);
-  if (typeof value === "object" && value !== null) {
+  if (isRecord(value)) {
     return Object.entries(value).some(
       ([key, item]) => containsWrittenReason(key) || containsWrittenReason(item),
     );
@@ -169,8 +167,8 @@ function containsWrittenReason(value: unknown): boolean {
 }
 
 function unfinishedReasonPresent(details?: unknown): boolean {
-  if (typeof details !== "object" || details === null || Array.isArray(details)) return false;
-  return containsWrittenReason((details as { reason?: unknown }).reason);
+  if (!isRecord(details)) return false;
+  return containsWrittenReason(details.reason);
 }
 
 function readGateState(session: HostRecordSession): {