@akagilnc/pi-workflow-roles 0.1.4204 → 0.1.4228

package/dist/session-dialogue.js

@@ -0,0 +1,221 @@
+/**
+ * 对话事实适配（ADR 0075 `dialogue-only` / `no-tool-output` / `speaker-required`）。
+ *
+ * 「对话」＝人类输入内容 + 助手回话内容，由各宿主的**结构化会话事件**适配而来。
+ * 排除按来源、不按正文：说话人自己写下的文字一律原样保留，其中引用了 ADR 段落
+ * 或工具结果也不删（#901 Out of Scope「不做正文过滤」）。
+ *
+ * 不入录的是工具结果载荷、附件记录与注入块——它们是独立的机器事件，不是谁说的话。
+ *
+ * 适配规则按宿主并列，不硬套某一宿主的类型名；一行产出 0..n 条对话事实。
+ */
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * 原生 id：行级或消息体级主键的单一实现（bound 解析与落盘共用）。
+ * Pi/CC：行上 `uuid`/`id`；Codex：`response_item.payload.id`（或 `message.id`）。
+ */
+export function nativeEventId(row) {
+    for (const key of ["uuid", "id"]) {
+        const value = row[key];
+        if (typeof value === "string" && value !== "")
+            return value;
+    }
+    for (const nestKey of ["message", "payload"]) {
+        const nested = row[nestKey];
+        if (!isRecord(nested))
+            continue;
+        for (const key of ["uuid", "id"]) {
+            const value = nested[key];
+            if (typeof value === "string" && value !== "")
+                return value;
+        }
+    }
+    return undefined;
+}
+/** 说话人文本块类型：Pi/CC `text`；Codex rollout `input_text` / `output_text`。 */
+const SPEAKER_TEXT_PART_TYPES = new Set(["text", "input_text", "output_text"]);
+/** 文本块串接：content 为字符串即其本身，为数组则只取说话人文本片段（逐块过滤）。 */
+function textParts(content) {
+    if (typeof content === "string")
+        return content === "" ? [] : [content];
+    if (!Array.isArray(content))
+        return [];
+    const out = [];
+    for (const part of content) {
+        if (!isRecord(part) || !SPEAKER_TEXT_PART_TYPES.has(String(part.type)))
+            continue;
+        const text = part.text;
+        if (typeof text === "string" && text !== "")
+            out.push(text);
+    }
+    return out;
+}
+/**
+ * 取出 Pi/CC 消息体，或 Codex `response_item.payload.type=message`。
+ * developer 与注入用的 user 不在此层用正文识别——见整卷 Codex 规则。
+ */
+function responseItemMessage(row) {
+    if (row.type !== "response_item" || !isRecord(row.payload))
+        return undefined;
+    if (row.payload.type !== "message")
+        return undefined;
+    return row.payload;
+}
+function messageBody(row) {
+    if (isRecord(row.message))
+        return row.message;
+    return responseItemMessage(row);
+}
+function speakerOf(message) {
+    if (message.role === "assistant")
+        return "runner";
+    if (message.role === "user")
+        return "owner";
+    // developer / toolResult 等不是说话人回话。
+    return undefined;
+}
+/**
+ * Codex `content_item_kinds`：行上结构化来源种类（不读正文）。
+ * 真 user 带 `user.text` / `user.image`；注入为 `agents_md.instructions`、
+ * `environments.environment_context`、`plugins.recommendations` 等。
+ */
+function codexContentItemKinds(message) {
+    const pass = message.internal_chat_message_metadata_passthrough;
+    if (!isRecord(pass) || !Array.isArray(pass.content_item_kinds))
+        return undefined;
+    const kinds = [];
+    for (const kind of pass.content_item_kinds) {
+        if (typeof kind === "string" && kind !== "")
+            kinds.push(kind);
+    }
+    return kinds;
+}
+/** response_item role=user 是否为真说话人输入（kinds 含 user.*）。 */
+function isCodexOwnerResponseItemUser(message) {
+    if (message.role !== "user")
+        return false;
+    const kinds = codexContentItemKinds(message);
+    // 无 kinds 的旧卷：不能结构化分辨注入与真 user，宁缺勿把注入当陛下。
+    if (kinds === undefined)
+        return false;
+    return kinds.some((kind) => kind.startsWith("user."));
+}
+/**
+ * 入队事件适配：人类这次输入经队列的来源。
+ * 配对的出队事件不另取，也不做正文比对去重——被吸收的插话正是靠入队事件入录
+ * （它没有独立的消息记录，#901 用户故事 11）。
+ */
+function fromQueueEvent(row) {
+    if (row.type !== "queue-operation" || row.operation !== "enqueue")
+        return [];
+    const content = row.content;
+    if (typeof content !== "string" || content === "")
+        return [];
+    const id = nativeEventId(row);
+    return [{ speaker: "owner", text: content, ...(id === undefined ? {} : { id }) }];
+}
+/**
+ * 消息事件适配：助手回话，以及未经入队事件记录的人类输入。
+ * 思考块、工具调用块、工具结果块按块排除；同消息的说话人 text 保留
+ * （#901 排除按来源不按正文；混合块不得整条丢弃）。
+ * Codex response_item user：仅 `content_item_kinds` 含 `user.*` 时入录。
+ */
+function fromMessageEvent(row) {
+    const message = messageBody(row);
+    if (message === undefined)
+        return [];
+    if (message.role === "toolResult")
+        return [];
+    const speaker = speakerOf(message);
+    if (speaker === undefined)
+        return [];
+    // Codex response_item user：按行上 kinds 结构化判定，不咬正文、不靠 turn 序。
+    if (row.type === "response_item" && speaker === "owner") {
+        if (!isCodexOwnerResponseItemUser(message))
+            return [];
+    }
+    const parts = textParts(message.content);
+    if (parts.length === 0)
+        return [];
+    const text = parts.join("");
+    if (text === "")
+        return [];
+    // 与 bound lookup 同源：nativeEventId 已含 payload/message id。
+    const id = nativeEventId(row);
+    return [{ speaker, text, ...(id === undefined ? {} : { id }) }];
+}
+/** 该行是否为可产出 owner 对话正文的消息（工具结果块不算；旁路 text 算）。 */
+function isOwnerDialogueMessage(row) {
+    // CC/Pi queue pairing only — Codex owner path is separate.
+    if (row.type === "response_item" || row.type === "event_msg")
+        return false;
+    return fromMessageEvent(row).some((event) => event.speaker === "owner");
+}
+/** 该行是否为 runner 回话事件（用于解除未物化的 dequeue 配对）。 */
+function isRunnerMessage(row) {
+    const message = messageBody(row);
+    return message !== undefined && message.role === "assistant";
+}
+/**
+ * 逐次来源配对：仅当对应 enqueue 已由 fromQueueEvent 实际形成 retained owner
+ * 对话时，才把随后的物化 user 当副本跳过。FIFO 对齐 enqueue→dequeue/remove。
+ * 无正文 enqueue、旧宿主或其他不可投影形状：dequeue 不产生 skip，后续真人
+ * user 原样保留。未物化的 retained dequeue（被吸收插话）遇 runner 解除。
+ * 不用「卷内曾出现 enqueue」整卷布尔，也不按正文过滤。
+ */
+function ownerMessagesMaterializingQueue(rows) {
+    const skip = new Set();
+    /** 各 enqueue 是否已留下 owner 对话，按入队顺序等 dequeue/remove 消费。 */
+    const retainedByEnqueue = [];
+    let pendingSkips = 0;
+    for (let index = 0; index < rows.length; index += 1) {
+        const row = rows[index];
+        if (row === undefined)
+            continue;
+        if (row.type === "queue-operation") {
+            if (row.operation === "enqueue") {
+                retainedByEnqueue.push(fromQueueEvent(row).length > 0);
+                continue;
+            }
+            if (row.operation === "dequeue" || row.operation === "remove") {
+                const retained = retainedByEnqueue.shift();
+                // 只在 enqueue 真留下对话且本事件是 dequeue 物化时才跳过后续 user。
+                // remove 只消费队列槽，不制造 skip（无物化消息）。
+                if (row.operation === "dequeue" && retained === true) {
+                    pendingSkips += 1;
+                }
+                continue;
+            }
+        }
+        if (isRunnerMessage(row)) {
+            pendingSkips = 0;
+            continue;
+        }
+        if (pendingSkips > 0 && isOwnerDialogueMessage(row)) {
+            skip.add(index);
+            pendingSkips -= 1;
+        }
+    }
+    return skip;
+}
+/**
+ * 整卷适配：返回与入参行等长的对话事实数组（该行不是对话则为空数组）。
+ * 需要整卷视野：enqueue/dequeue 配对跨行。
+ */
+export function adaptSessionDialogue(rows) {
+    const skipOwner = ownerMessagesMaterializingQueue(rows);
+    return rows.map((row, index) => {
+        if (row === undefined)
+            return [];
+        const queued = fromQueueEvent(row);
+        if (queued.length > 0)
+            return queued;
+        // Codex event_msg.user_message 无 content_item_kinds 等 provenance，旧 exec
+        // 卷中与 worker entrypoint 注入同形——无法证明为 owner 则不取（不猜、不咬正文）。
+        if (skipOwner.has(index))
+            return [];
+        return fromMessageEvent(row);
+    });
+}

package/dist/sitian-facade.js

@@ -2,6 +2,7 @@ import { appendSitianRecord } from "./sitian-appender.js";
 export * from "./sitian-contracts.js";
 export * from "./sitian-appender.js";
 export * from "./sitian-reader.js";
+export * from "./sitian-volume.js";
 function sitianReport(input) {
   return appendSitianRecord(input);
 }

package/dist/sitian-volume.js

@@ -0,0 +1,67 @@
+/**
+ * Sitian whole-file volume I/O (ADR 0065 records-owner / record-entry).
+ *
+ * Owns destination resolution, create, raw read, and whole-file rewrite for
+ * kinds whose persistence shape is not the appender SitianRecord row
+ * (ticket-provenance header + bare dialogue lines, #901). Appender kernel
+ * stays append-only; this module does not restore append watermarks.
+ */
+import { appendFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { ensureRealDirectoryTree, errorText, } from "./activation-ledger-topology.js";
+import { writeFileAtomically } from "./atomic-write.js";
+import { resolveSitianRecordPath } from "./sitian-appender.js";
+import { SitianInfrastructureError, } from "./sitian-contracts.js";
+/** Resolve a volume path from ambient topology — callers never pick the destination. */
+export function resolveSitianVolume(input) {
+    const path = resolveSitianRecordPath(input);
+    return { recordFile: path.recordFile, volumeDir: path.sessionDir };
+}
+/**
+ * Ensure the volume directory + file exist.
+ * Append-open creates an absent volume without truncating concurrent first writers.
+ */
+export function ensureSitianVolume(input) {
+    try {
+        const { sessionDir, recordFile, ledgerHome } = resolveSitianRecordPath(input);
+        ensureRealDirectoryTree(ledgerHome, sessionDir);
+        appendFileSync(recordFile, "", "utf8");
+        return { recordFile, volumeDir: sessionDir };
+    }
+    catch (error) {
+        if (error instanceof SitianInfrastructureError)
+            throw error;
+        throw new SitianInfrastructureError(`Sitian volume ensure failure: ${errorText(error)}`, { cause: error });
+    }
+}
+/** Raw volume text. Absent file → text undefined (not an error). */
+export async function readSitianVolumeText(input) {
+    const { recordFile } = resolveSitianVolume(input);
+    try {
+        return { recordFile, text: await readFile(recordFile, "utf8") };
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return { recordFile, text: undefined };
+        }
+        throw new SitianInfrastructureError(`Sitian volume read failure: ${errorText(error)}`, { cause: error });
+    }
+}
+/**
+ * Replace the entire volume body (whole-file reproject).
+ * Same-directory temp + rename — never truncate the live inode in place
+ * (#901 sole diary; reuse atomic-write, no parallel persist mechanism).
+ * Not append; no identity claim / torn-tail watermark — those stay on appender.
+ */
+export async function rewriteSitianVolume(input) {
+    try {
+        const volume = ensureSitianVolume(input);
+        await writeFileAtomically(volume.recordFile, input.body);
+        return volume;
+    }
+    catch (error) {
+        if (error instanceof SitianInfrastructureError)
+            throw error;
+        throw new SitianInfrastructureError(`Sitian volume rewrite failure: ${errorText(error)}`, { cause: error });
+    }
+}

package/dist/ticket-provenance-contracts.js

@@ -1,63 +1,146 @@
 /**
- * 起居录（ticket-provenance）typed contracts — ADR 0075 / #582.
- * JSONL is the sole authority; md is a derived human face.
+ * 起居录（ticket-provenance）typed 形状 —— ADR 0075「2026-09-14 修订」/ #901。
+ *
+ * 一册＝一个文件：第一行册子头，其后每行一条对话。
+ * 每轮按册子头当前各区间**重投影**这份唯一文件：册子头与各条定位可更新，
+ * 正文原样不改（`single-volume` / `one-volume-per-issue`）。
  */
 /** Sitian kind for per-ticket court diary volumes. */
 export const TICKET_PROVENANCE_KIND = "ticket-provenance";
-/** Human-read view filename co-located with the JSONL volume. */
-export const TICKET_PROVENANCE_HUMAN_VIEW = "起居录.md";
-/** Payload discriminator: diagnostic residue (not a diary body entry). */
-export const TICKET_PROVENANCE_RECORD_CLASS_DIAGNOSTIC = "diagnostic";
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-const DIAGNOSTIC_KINDS = new Set([
-    "collector-failed",
-    "issue-source-failed",
-    "quote-verify-failed",
-]);
+function positiveInteger(value) {
+    if (typeof value === "number" && Number.isSafeInteger(value) && value >= 1)
+        return value;
+    if (typeof value === "string" && /^[1-9][0-9]*$/.test(value)) {
+        const parsed = Number(value);
+        if (Number.isSafeInteger(parsed))
+            return parsed;
+    }
+    return undefined;
+}
+function nonNegativeInteger(value) {
+    if (typeof value === "number" && Number.isSafeInteger(value) && value >= 0)
+        return value;
+    if (typeof value === "string" && /^(0|[1-9][0-9]*)$/.test(value)) {
+        const parsed = Number(value);
+        if (Number.isSafeInteger(parsed))
+            return parsed;
+    }
+    return undefined;
+}
+function projectSpeaker(value) {
+    return value === "owner" || value === "runner" ? value : undefined;
+}
+function projectBound(value) {
+    if (!isRecord(value))
+        return undefined;
+    const id = typeof value.id === "string" && value.id !== "" ? value.id : undefined;
+    const line = positiveInteger(value.line);
+    if (id === undefined && line === undefined)
+        return undefined;
+    return { ...(id === undefined ? {} : { id }), ...(line === undefined ? {} : { line }) };
+}
 /**
- * Project a typed diagnostic payload (recordClass discriminator only).
- * Disguised diary-entry shapes are not diagnostics — no branch-intermediate compat.
+ * 投影起居郎交上来的边界。
+ * 端点无法指名、卷路径缺失即返回 undefined——调用者据此走既有 reask 请其重交，
+ * 不猜、不补、不中止本轮（`reask-not-explode`）。
  */
-export function projectTicketProvenanceDiagnostic(value) {
+export function projectTicketProvenanceSessions(value) {
+    // Empty array = lawful empty selection (no dialogue ranges this turn).
+    // Non-array / malformed member = unusable bounds → caller reasks.
+    if (!Array.isArray(value))
+        return undefined;
+    if (value.length === 0)
+        return [];
+    const sessions = [];
+    for (const raw of value) {
+        if (!isRecord(raw))
+            return undefined;
+        const path = raw.path;
+        if (typeof path !== "string" || path.trim() === "")
+            return undefined;
+        if (!Array.isArray(raw.ranges) || raw.ranges.length === 0)
+            return undefined;
+        const ranges = [];
+        for (const rawRange of raw.ranges) {
+            if (!isRecord(rawRange))
+                return undefined;
+            const from = projectBound(rawRange.from);
+            const to = projectBound(rawRange.to);
+            if (from === undefined || to === undefined)
+                return undefined;
+            ranges.push({ from, to });
+        }
+        sessions.push({ path, ranges });
+    }
+    return sessions;
+}
+/**
+ * 投影补写集合。缺该字段＝无补写（不拒收）；成员形状不成立的整条跳过——
+ * 它没有绑定位置，放不回去。
+ */
+export function projectTicketProvenanceAmendments(value) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const raw of value) {
+        if (!isRecord(raw))
+            continue;
+        const s = nonNegativeInteger(raw.s);
+        const line = positiveInteger(raw.line);
+        const speaker = projectSpeaker(raw.speaker);
+        const text = raw.text;
+        if (s === undefined || line === undefined || speaker === undefined)
+            continue;
+        if (typeof text !== "string")
+            continue;
+        out.push({ s, line, speaker, text });
+    }
+    return out;
+}
+/** 读回册子头（文件第一行）。形状不成立即 undefined——按无册处理，不猜。 */
+export function projectTicketProvenanceHeader(value) {
     if (!isRecord(value))
         return undefined;
-    if (value.recordClass !== TICKET_PROVENANCE_RECORD_CLASS_DIAGNOSTIC) {
+    const ticket = positiveInteger(value.ticket);
+    if (ticket === undefined)
         return undefined;
-    }
-    if (typeof value.diagnosticKind !== "string" ||
-        !DIAGNOSTIC_KINDS.has(value.diagnosticKind)) {
+    if (typeof value.repo !== "string")
         return undefined;
-    }
-    if (typeof value.cause !== "string" || value.cause.length === 0) {
+    if (typeof value.createdAt !== "string" || typeof value.updatedAt !== "string") {
         return undefined;
     }
-    if (typeof value.recordedAt !== "string" || value.recordedAt.length === 0) {
+    // Malformed sessions stay unusable — do not wash into lawful empty (失败诚实).
+    const sessions = projectTicketProvenanceSessions(value.sessions);
+    if (sessions === undefined)
         return undefined;
-    }
     return {
-        recordClass: TICKET_PROVENANCE_RECORD_CLASS_DIAGNOSTIC,
-        diagnosticKind: value.diagnosticKind,
-        cause: value.cause,
-        recordedAt: value.recordedAt,
-        ...(typeof value.reason === "string" ? { reason: value.reason } : {}),
+        repo: value.repo,
+        ticket,
+        createdAt: value.createdAt,
+        updatedAt: value.updatedAt,
+        sessions,
     };
 }
-/**
- * Project a lawful diary entry from unknown payload bytes.
- * Shape is not an admission gate for role output; this is the diarist/write seam
- * self-check so garbage does not enter the volume.
- * Diagnostics (recordClass discriminator) are not entries.
- */
-export function projectTicketProvenanceEntry(value) {
+/** 读回一条对话行。 */
+export function projectTicketProvenanceLine(value) {
     if (!isRecord(value))
         return undefined;
-    if (value.recordClass === TICKET_PROVENANCE_RECORD_CLASS_DIAGNOSTIC) {
+    const speaker = projectSpeaker(value.speaker);
+    const s = nonNegativeInteger(value.s);
+    if (speaker === undefined || s === undefined)
         return undefined;
-    }
-    if (typeof value.sourceKind !== "string" || typeof value.transcript !== "string") {
+    if (typeof value.text !== "string")
         return undefined;
-    }
-    return value;
+    const line = positiveInteger(value.line);
+    const id = typeof value.id === "string" && value.id !== "" ? value.id : undefined;
+    return {
+        speaker,
+        s,
+        ...(line === undefined ? {} : { line }),
+        ...(id === undefined ? {} : { id }),
+        text: value.text,
+    };
 }