@akagilnc/pi-workflow-roles 0.1.4062 → 0.1.4196

package/dist/submission-ledger.js

@@ -1,8 +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";
 /**
@@ -33,21 +35,40 @@ function attemptIdentity(context, runId) {
         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) {
@@ -86,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;
@@ -245,7 +266,7 @@ function mapOwnedToSubmissionRows(owned) {
  */
 export async function readRecordedSubmissionRows(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);
     return mapOwnedToSubmissionRows(scoped);
 }
@@ -257,7 +278,7 @@ export async function readRecordedSubmissionRows(cwd, runId, homeOrScope) {
 export async function readAttemptScopedSubmissionRows(cwd, runId, attemptId, home) {
     if (attemptId.length === 0)
         return [];
-    const { owned } = await readOwnedSubmissionRecords(cwd, runId, home);
+    const { owned } = await readOwnedSubmissionRecords(cwd, runId, home === undefined ? {} : { home });
     return mapOwnedToSubmissionRows(owned.filter((record) => recordAttemptId(record) === attemptId));
 }
 /**
@@ -274,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];
@@ -287,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),
     };
 }
@@ -306,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,
@@ -331,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akagilnc/pi-workflow-roles",
-  "version": "0.1.4062",
+  "version": "0.1.4196",
   "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/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/countersign.md

@@ -9,13 +9,13 @@
 1 第一法源立法（最高法）：该票起居录，全局宪法，仓内治理文件；
 
 2 第二法源立法：
-适用 ADR——由你自行检索，按票面触及的席位、接缝、术语在 docs/adr 与 CONTEXT.md 查全，票面引没引都算——并逐键列出其决策键；质量法、审刑院法典；
+适用 ADR——由你自行检索，按票面触及的席位、接缝、术语在 docs/adr 与 CONTEXT.md 查全，票面引没引都算——并逐条列出其决定；质量法、审刑院法典；
 
 3 第二法源合法性检查：判断第二法源 以及 输入的 prompt等 对比第一法源是否有超出，不足，曲解。如有，除非有陛下原话批准，否则直接封驳 要求改正或陛下批准。
 
 **二、相抵** 票面，相关票与在飞分支与法源有无抵触。
 
-**三、缺失** 法源要求的，票面有没有漏：适用 ADR 未被引用即缺失，引用须写 `docs/adr/...md` 路径；ADR 每个决策键须有落点或明写「由 #x 承接」；验收面须覆盖票面每条主张；前置产物、决定、答复须在；承重主张的源头不存在、不支持、已过时，同为缺失。缺失列表在能力范围内一次扫完，尽量避免因缺失导致多轮往返。
+**三、缺失** 法源要求的，票面有没有漏：适用 ADR 未被引用即缺失，引用须写 `docs/adr/...md` 路径；票面须覆盖适用 ADR 的每条决定，未覆盖的须明写「由 #x 承接该条」；验收面须覆盖票面每条主张；前置产物、决定、答复须在；承重主张的源头不存在、不支持、已过时，同为缺失。缺失列表在能力范围内一次扫完，尽量避免因缺失导致多轮往返。
 
 **四、擅加** 票面有没有超出法源的机制、约束、验收、术语。
 

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 {