@akagilnc/pi-workflow-roles 0.1.4035 → 0.1.4193

package/dist/submission-ledger.js

@@ -1,7 +1,10 @@
+import { join } from "node:path";
 import { resolveActivationLedgerHome, tryHomeFromAkRolesPath, } from "./activation-ledger-topology.js";
+import { courtAttemptIdFromHostContext, runDirectoryFromHostContext, } from "./host-contracts.js";
 import { isAuditEscalationProjection } from "./audit-escalation.js";
 import { runIdFromRunDirectory } from "./run-terminal-artifacts.js";
 import { readSitianRecords, resolveSitianRecordPathInLedger, sitianReport } from "./sitian-facade.js";
+import { findRunDirectoryById } from "./public-cli/run-lifecycle.js";
 import { isCorrectableExecuteError } from "./submission-correctable-error.js";
 import { failOnInfrastructureFailureDeclaration } from "./package-contracts/terminating-infrastructure.js";
 /**
@@ -10,8 +13,8 @@ import { failOnInfrastructureFailureDeclaration } from "./package-contracts/term
  * otherwise session header id. Never a shared "unbound" bucket.
  */
 function runIdentity(context) {
-    const directory = process.env.AK_ROLE_RUN_DIR;
-    if (typeof directory === "string" && directory.length > 0) {
+    const directory = runDirectoryFromHostContext(context);
+    if (directory !== undefined) {
         const fromDir = runIdFromRunDirectory(directory);
         if (fromDir !== undefined)
             return fromDir;
@@ -27,26 +30,45 @@ function runIdentity(context) {
  */
 export const COURT_ATTEMPT_ENV = "AK_ROLE_COURT_ATTEMPT";
 function attemptIdentity(context, runId) {
-    const courtAttempt = process.env[COURT_ATTEMPT_ENV];
-    if (typeof courtAttempt === "string" && courtAttempt.length > 0)
+    const courtAttempt = courtAttemptIdFromHostContext(context);
+    if (courtAttempt !== undefined)
         return courtAttempt;
     return context.sessionManager.getHeader?.()?.id ?? context.sessionManager.getLeafId?.() ?? `${runId}:initial`;
 }
-function submissionRecordFile(cwd, runId, home) {
-    const ledgerHome = resolveActivationLedgerHome(home);
+/**
+ * Resolve the submission-ledger record file for a run.
+ * Unknown run (no sessionParent and no discoverable directory) → undefined so
+ * read APIs return their empty set at the read boundary. Write paths always
+ * supply sessionParent and keep the ownership gate.
+ */
+async function submissionRecordFile(cwd, runId, scope) {
+    const ledgerHome = resolveActivationLedgerHome(scope.home);
+    let sessionParent = scope.sessionParent;
+    if (sessionParent === undefined) {
+        const discoveredRun = await findRunDirectoryById(scope.home, runId);
+        if (discoveredRun === undefined)
+            return undefined;
+        sessionParent = join(discoveredRun, "session", "session.jsonl");
+    }
     return resolveSitianRecordPathInLedger({
         level: "event",
         kind: "candidate",
         subject: { runId },
         cwd,
+        sessionParent,
     }, ledgerHome).recordFile;
 }
-async function readOwnedSubmissionRecords(cwd, runId, home) {
-    const file = submissionRecordFile(cwd, runId, home);
+async function readOwnedSubmissionRecords(cwd, runId, scope = {}) {
+    const file = await submissionRecordFile(cwd, runId, scope);
+    if (file === undefined) {
+        return { file: undefined, owned: [] };
+    }
     const { records } = await readSitianRecords(file);
     return {
         file,
-        owned: records.filter((record) => typeof record.subject === "object" && record.subject !== null && record.subject.runId === runId),
+        owned: records.filter((record) => typeof record.subject === "object"
+            && record.subject !== null
+            && record.subject.runId === runId),
     };
 }
 function resolveReadScope(homeOrScope) {
@@ -85,8 +107,8 @@ function recordAttemptId(record) {
  * outranking the current attempt's own real host-turn failure signal
  * (#637 original intent, restored narrowly).
  */
-export async function hasFreshAttemptSubmission(cwd, runId, attemptId, home) {
-    const { owned } = await readOwnedSubmissionRecords(cwd, runId, home);
+export async function hasFreshAttemptSubmission(cwd, runId, attemptId, homeOrScope) {
+    const { owned } = await readOwnedSubmissionRecords(cwd, runId, resolveReadScope(homeOrScope));
     return owned.some((record) => {
         if (recordAttemptId(record) !== attemptId)
             return false;
@@ -151,10 +173,8 @@ function rowFromPayload(kind, payload, accepted, roleFallback) {
  * recorded attemptId + toolCallId so distinct court attempts stay distinct (#881).
  * `accepted` is the original payload; never rebuilt from a status/facts envelope.
  */
-export async function readRecordedSubmissionRows(cwd, runId, homeOrScope) {
-    const scope = resolveReadScope(homeOrScope);
-    const { owned } = await readOwnedSubmissionRecords(cwd, runId, scope.home);
-    const scoped = recordsForAttempt(owned, scope.attemptId);
+function mapOwnedToSubmissionRows(owned) {
+    const scoped = owned;
     const out = [];
     const indexByCall = new Map();
     // Recover seat identity for historical non-sealed rows that omitted role (#881).
@@ -238,6 +258,29 @@ export async function readRecordedSubmissionRows(cwd, runId, homeOrScope) {
     }
     return out;
 }
+/**
+ * All recorded role submissions in ledger order (#836 multi-submit).
+ * `accepted` is the original payload; never rebuilt from a status/facts envelope.
+ * Presentation stays run-scoped: attemptId on the read scope is a recording tag,
+ * not a visibility gate (#836).
+ */
+export async function readRecordedSubmissionRows(cwd, runId, homeOrScope) {
+    const scope = resolveReadScope(homeOrScope);
+    const { owned } = await readOwnedSubmissionRecords(cwd, runId, scope);
+    const scoped = recordsForAttempt(owned, scope.attemptId);
+    return mapOwnedToSubmissionRows(scoped);
+}
+/**
+ * Settlement-only this-court rows (#879 return path).
+ * Filters by attemptId for court-scoped roleOutcome; does not replace the
+ * run-scoped presentation API above (#836 visibility gate stays pass-through).
+ */
+export async function readAttemptScopedSubmissionRows(cwd, runId, attemptId, home) {
+    if (attemptId.length === 0)
+        return [];
+    const { owned } = await readOwnedSubmissionRecords(cwd, runId, home === undefined ? {} : { home });
+    return mapOwnedToSubmissionRows(owned.filter((record) => recordAttemptId(record) === attemptId));
+}
 /**
  * All raw role payloads in ledger order (#836 multi-submit).
  * Returns `accepted` bytes as stored — unknown, never re-wrapped.
@@ -252,7 +295,7 @@ export async function hasRecordedSubmission(cwd, runId, homeOrScope) {
 /** Latest non-final outcome on the run ledger (settlement residual precedence). */
 export async function readLatestSubmissionOutcome(cwd, runId, homeOrScope) {
     const scope = resolveReadScope(homeOrScope);
-    const { owned } = await readOwnedSubmissionRecords(cwd, runId, scope.home);
+    const { owned } = await readOwnedSubmissionRecords(cwd, runId, scope);
     const scoped = recordsForAttempt(owned, scope.attemptId);
     for (let index = scoped.length - 1; index >= 0; index -= 1) {
         const record = scoped[index];
@@ -265,14 +308,33 @@ export async function readLatestSubmissionOutcome(cwd, runId, homeOrScope) {
     }
     return undefined;
 }
-async function restoreState(cwd, runId, home) {
-    const { file, owned } = await readOwnedSubmissionRecords(cwd, runId, home);
+async function restoreState(cwd, runId, scope) {
+    const located = await readOwnedSubmissionRecords(cwd, runId, scope);
+    // Unknown-run empty set: no prior chain. Owned rows without a file are an internal bug.
+    if (located.file === undefined) {
+        if (located.owned.length !== 0) {
+            throw new Error(`submission ledger invariant: owned rows present without recordFile for run ${runId}`);
+        }
+        return { sequence: 0 };
+    }
+    const { file, owned } = located;
     const last = owned.at(-1);
     return {
-        ...(last === undefined ? {} : { prior: { identity: last.identity, recordFile: file, kind: last.kind, level: last.level } }),
+        ...(last === undefined
+            ? {}
+            : {
+                prior: {
+                    identity: last.identity,
+                    recordFile: file,
+                    kind: last.kind,
+                    level: last.level,
+                },
+            }),
         sequence: owned.reduce((maximum, record) => {
             const payload = record.payload;
-            return payload?.type === "candidate" && typeof payload.sequence === "number" ? Math.max(maximum, payload.sequence) : maximum;
+            return payload?.type === "candidate" && typeof payload.sequence === "number"
+                ? Math.max(maximum, payload.sequence)
+                : maximum;
         }, 0),
     };
 }
@@ -284,22 +346,40 @@ async function restoreState(cwd, runId, home) {
  */
 export function createSubmissionLedgerHost(host, outputTools, failInfrastructure = (error) => { throw error; }, projectClosure = () => undefined, options) {
     const states = new Map();
+    /** Sole HostContext-derived run coordinate for restore and append (never process.env). */
+    const sessionParentFromContext = (context) => {
+        const runDirectory = runDirectoryFromHostContext(context);
+        if (runDirectory !== undefined) {
+            return join(runDirectory, "session", "session.jsonl");
+        }
+        const sessionFile = context.sessionManager.getSessionFile?.();
+        if (typeof sessionFile === "string" && sessionFile.length > 0)
+            return sessionFile;
+        const sessionDir = context.sessionManager.getSessionDir?.();
+        if (typeof sessionDir === "string" && sessionDir.length > 0) {
+            return join(sessionDir, "session.jsonl");
+        }
+        return undefined;
+    };
     const resolveHomeFromContext = (context) => {
         if (options?.home !== undefined)
             return options.home;
-        const sessionFile = context.sessionManager.getSessionFile?.() || context.sessionManager.getSessionDir?.();
-        return typeof sessionFile === "string" && sessionFile.length > 0
-            ? tryHomeFromAkRolesPath(sessionFile)
-            : undefined;
+        const sessionParent = sessionParentFromContext(context);
+        return sessionParent !== undefined ? tryHomeFromAkRolesPath(sessionParent) : undefined;
     };
     const stateFor = (context, runId) => states.get(runId) ?? (() => {
         const home = resolveHomeFromContext(context);
-        const pending = restoreState(context.cwd, runId, home);
+        const sessionParent = sessionParentFromContext(context);
+        const pending = restoreState(context.cwd, runId, {
+            ...(home === undefined ? {} : { home }),
+            ...(sessionParent === undefined ? {} : { sessionParent }),
+        });
         states.set(runId, pending);
         return pending;
     })();
     const appendFor = (state, context, runId, attemptId, event) => {
         const home = resolveHomeFromContext(context);
+        const sessionParent = sessionParentFromContext(context);
         const pointer = sitianReport({
             level: "event",
             kind: event.type,
@@ -309,6 +389,7 @@ export function createSubmissionLedgerHost(host, outputTools, failInfrastructure
             source: "role-runtime",
             cwd: context.cwd,
             ...(home !== undefined ? { home } : {}),
+            ...(sessionParent === undefined ? {} : { sessionParent }),
         });
         state.prior = pointer;
         return pointer;

package/dist/ticket-provenance.js

@@ -6,10 +6,11 @@ import { createHash } from "node:crypto";
 import { appendFileSync, mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { resolveSitianRecordPath, sitianReport, readSitianRecords, } from "./sitian-facade.js";
+import { isSafePositiveTicketNumber } from "./run-ticket-number.js";
 import { TICKET_PROVENANCE_HUMAN_VIEW, TICKET_PROVENANCE_KIND, projectTicketProvenanceDiagnostic, projectTicketProvenanceEntry, } from "./ticket-provenance-contracts.js";
 /** Subject string for ticket-keyed volumes — history follows the ticket. */
 export function ticketProvenanceSubject(ticketNumber) {
-    if (!Number.isSafeInteger(ticketNumber) || ticketNumber < 1) {
+    if (!isSafePositiveTicketNumber(ticketNumber)) {
         throw new Error(`ticket-provenance subject requires a positive ticket number, got ${String(ticketNumber)}`);
     }
     return String(ticketNumber);
@@ -71,6 +72,7 @@ export function appendTicketProvenanceEntry(input) {
         identity,
         subject,
         cwd: input.cwd,
+        sessionParent: input.sessionParent,
         ...(input.home === undefined ? {} : { home: input.home }),
         host: input.host ?? "diarist",
         source: input.source ?? "diarist",

package/dist/user-dialogue-stdin.js

@@ -0,0 +1,33 @@
+/**
+ * Typed user-dialogue stdin transport (#879 / #471).
+ * 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.
+ */
+export const USER_DIALOGUE_STDIN_KIND = "ak-user-dialogue";
+export function encodeUserDialogueStdin(body) {
+    return JSON.stringify({ kind: USER_DIALOGUE_STDIN_KIND, body });
+}
+function isUserDialogueEnvelope(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const record = value;
+    return record.kind === USER_DIALOGUE_STDIN_KIND && typeof record.body === "string";
+}
+/**
+ * Host read: recover original dialogue after a trim-capable pipe.
+ * Non-envelope text (interactive Pi, officer JSON, headless raw body) is unchanged.
+ */
+export function readUserDialogueStdin(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed.startsWith("{"))
+        return raw;
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (isUserDialogueEnvelope(parsed))
+            return parsed.body;
+    }
+    catch {
+        // Not our envelope — leave caller bytes intact.
+    }
+    return raw;
+}

package/extensions/role-runtime.ts

@@ -111,6 +111,7 @@ export default function roleRuntime(pi: ExtensionAPI): void {
   registerNavigatorModelCommand(pi);
   const navigatorSessionFactory = createNativeNavigatorSessionFactory();
   createPiRoleRuntimeExtension({
+    packageRoot,
     loadJudgeSoul: () => loadMainRoleSessionMaterials("judge"),
     loadFixerSoul: () => loadMainRoleSessionMaterials("fixer"),
     loadFixPacket: (path) => readFile(path, "utf8"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akagilnc/pi-workflow-roles",
-  "version": "0.1.4035",
+  "version": "0.1.4193",
   "description": "Soul-bound workflow roles for Pi",
   "type": "module",
   "license": "Apache-2.0",
@@ -47,7 +47,8 @@
     "test:integration": "node --import tsx --import ./scripts/test-process-env-preload.mjs --test test/unit/**/*.test.ts test/contract/**/*.test.ts test/integration/**/*.test.ts",
     "test:all": "node scripts/run-test-all.mjs",
     "test:adjudication": "node --import tsx --import ./scripts/test-process-env-preload.mjs --test test/adjudication/**/*.test.ts",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "migrate:book-topology": "node dist/migrate-book-topology.js"
   },
   "pi": {
     "extensions": []

package/resources/836-deleted-machine-instruction-inventory.md

@@ -1,6 +1,6 @@
 # #836 删 5：从代码迁出的机器指令句清单
 
-供陛下过目。不改 soul。确需对角色说的话归入本包资源（ADR 0073）。指针句（附件路径、卷宗指针、「请重读」）保留为中立机器文本，不在本表。
+供陛下过目。不改 soul。确需对角色说的话归入本包资源（ADR 0073）。指针句（附件路径、卷宗指针）保留为中立机器文本／绑定材料，不在本表。「请重读」开场已由 #879 废止，不再保留。
 
 | 原位点 | 原句（代码自写） | 处置 |
 |---|---|---|

package/scripts/build-package.mjs

@@ -22,12 +22,14 @@ const entries = [
   "activation-ledger-topology",
   "activation-reconciliation",
   "archivist-record-entry",
-  // Pure subject nest topology — cold discovery without SessionManager (#636).
-  "archivist-record-topology",
   // Session material loaders used by published non-bundle roots.
   "session-opening-materials",
   // Value-import closure of published non-bundle roots (build-package-only loadable).
   "auditor-dossier-tool",
+  // Static import of auditor-dossier-tool / placement path authority (#859).
+  "role-run-placement",
+  // Static import of role-run-placement (safe-positive ticket invariant).
+  "run-ticket-number",
   "canonical-json",
   "compliance-transport",
   "countersign-contracts",
@@ -141,6 +143,35 @@ export async function buildHeadlessProductionHost(
   );
 }
 
+/**
+ * Published one-shot book-topology migration CLI (#852).
+ * Node-executable ESM bundle — consumers must not need dev-only tsx.
+ * createRequire banner lets transitive CJS deps reach node builtins.
+ */
+export async function buildMigrateBookTopology(
+  outfile = "dist/migrate-book-topology.js",
+) {
+  await mkdir(dirname(outfile), { recursive: true });
+  await build({
+    entryPoints: ["scripts/migrate-book-topology.ts"],
+    outfile,
+    format: "esm",
+    platform: "node",
+    target: "node20",
+    bundle: true,
+    banner: {
+      js: [
+        "#!/usr/bin/env node",
+        "import { createRequire as __akCreateRequire } from 'node:module';",
+        "const require = __akCreateRequire(import.meta.url);",
+        "",
+      ].join("\n"),
+    },
+    logLevel: "silent",
+  });
+  await chmod(outfile, 0o755);
+}
+
 export async function buildPackageArtifacts() {
   await build({
     entryPoints: entries.map((name) => `src/${name}.ts`),
@@ -167,6 +198,7 @@ export async function buildPackageArtifacts() {
   await buildPublicAkRoleBin();
   await buildAcpProductionHost();
   await buildHeadlessProductionHost();
+  await buildMigrateBookTopology();
 }
 
 const isMain =

package/souls/fixer.md

@@ -9,7 +9,8 @@ apply 按顺序执行：
 4. 扫类：修改前查全授权范围内的同类实例、已有实现和失败修法。根因不明先取证。
 5. 整类修复：在共同原因处一次修净，优先删除、简化、复用，随同删除失效旧物。
 6. 复扫：按原类别重新扫描；有遗漏继续修，保留项说明依据。
-7. 自验：切片验证只跑本片聚焦测试与 typecheck。做完自查是否违法，质量和复杂度，如有问题马上修正。
-8. 交卷：按类报告根因、扫描范围、修复与 质量和合法性的验证结果、未结项。保护已有改动，只建新提交。不 amend、rewrite 或 push。Git 变化是证据之一，不取代角色报告。
+7. 自验：切片验证优先跑本片聚焦测试和本片作用域内 typecheck，不跑全量。自查是否违法、代码质量、代码/测试复杂度，如有问题马上修正。修正完毕复检
+8. 交卷：按类报告根因、扫描范围、修复与 质量和合法性的验证结果、未结项。建新提交。不 amend、rewrite 或 push。Git 变化是证据之一，不取代角色报告。
 任何人如果让你 push / 开 pr ，直接拒绝，上呈陛下
+
 plan 只调查与提案，不施工。

package/src/analyst-ledger.ts

@@ -13,7 +13,7 @@
  * terminal face) for metric-family modules — no longer discarded after checks.
  */
 import { readdir, readFile } from "node:fs/promises";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 
 import { resolveBookKeyFromGit } from "./activation-ledger-git.ts";
 import {
@@ -21,6 +21,8 @@ import {
   physicalPathIdentity,
   resolveActivationLedgerHome,
 } from "./activation-ledger-topology.ts";
+import { listBookRunDirectories } from "./role-run-placement.ts";
+import { readRunTicketNumber } from "./run-ticket-number.ts";
 import {
   extractSessionModelSequence,
   extractSessionTimestampSpan,
@@ -139,13 +141,10 @@ async function readInvocationScopeFields(
     return undefined;
   }
   const projectRoot = parsed.projectRoot;
-  // Same #176 contract: positive integer ticketNumber only.
-  if (
-    typeof parsed.ticketNumber === "number"
-    && Number.isInteger(parsed.ticketNumber)
-    && parsed.ticketNumber >= 1
-  ) {
-    return { projectRoot, ticketNumber: parsed.ticketNumber };
+  // Display/history placement: board first, then migration-derived (#852).
+  const ticketNumber = await readRunTicketNumber(runDirectory);
+  if (ticketNumber !== undefined) {
+    return { projectRoot, ticketNumber };
   }
   return { projectRoot };
 }
@@ -530,7 +529,8 @@ async function classifyScopedRun(input: {
 }
 
 /**
- * Scan ledger home books/<book>/runs for runs in the issue scope.
+ * Scan ledger home books/<book>/{subject/}runs for runs in the issue scope.
+ * Walk = listBookRunDirectories (flat legacy + subject-tree; #859).
  * #399: scope = book × optional ticket.
  * - bookKey set → that book only; whole-book when no ticket and no projectRoot;
  *   ticket filters alone; bookKey + projectRoot (cohort ensure, #412) narrows
@@ -598,20 +598,19 @@ export async function scanAnalystIssueRuns(input: {
   const scopeConflicts: AnalystScopeConflict[] = [];
 
   for (const book of bookNames) {
-    const runsDir = join(booksRoot, book, "runs");
-    let runNames: string[];
+    const bookDir = join(booksRoot, book);
+    let runDirectories: string[];
     try {
-      const entries = await readdir(runsDir, { withFileTypes: true });
-      runNames = entries.filter((e) => e.isDirectory()).map((e) => e.name).sort();
+      runDirectories = await listBookRunDirectories(bookDir);
     } catch (error) {
       if (isMissingPathError(error)) continue;
       throw error;
     }
 
-    for (const runName of runNames) {
+    for (const runDirectory of runDirectories) {
+      const runName = basename(runDirectory);
       const parsed = parseRunDirectoryName(runName);
       if (parsed === undefined) continue;
-      const runDirectory = join(runsDir, runName);
 
       let scopeFields: InvocationScopeFields | undefined;
       try {