@danypops/papyrus 0.15.0 → 0.15.2

package/extension/src/context-view.ts

@@ -13,19 +13,6 @@ const SEGMENT_COLORS: Record<ContextSegment["key"], ThemeColor> = {
 	other: "muted",
 };
 
-/** Short, fixed-width column labels for the vertical deep-dive graph -- must match VERTICAL_BAR_WIDTH exactly so each label sits centered under its own bar. */
-const SEGMENT_SHORT_LABELS: Record<ContextSegment["key"], string> = {
-	rules: "Rul",
-	tasks: "Tsk",
-	skills: "Skl",
-	basePrompt: "Bse",
-	messageHistory: "Msg",
-	other: "Oth",
-};
-
-const VERTICAL_BAR_HEIGHT = 6;
-const VERTICAL_BAR_WIDTH = 3;
-
 /**
  * One row in the unified scrollable view. Every segment that has any real (nonzero) content
  * is fully expanded inline -- there is no separate "select a segment, then drill in" step.
@@ -117,16 +104,10 @@ class ContextViewport {
 		} else {
 			lines.push(theme.fg("dim", "No real usage reported yet — sizes below are Papyrus's own estimates only"));
 		}
-		lines.push(renderContextBar(theme, this.breakdown.segments, contentWidth, this.breakdown.effectiveBudget ?? undefined));
+		lines.push(renderContextBar(theme, this.breakdown.segments, contentWidth, this.breakdown.effectiveBudget ?? undefined, this.breakdown.totalTokens ?? undefined));
 		if (this.breakdown.overshootTokens > 0) {
 			lines.push(truncateToWidth(theme.fg("warning", `Estimates exceed real total by ~${this.breakdown.overshootTokens} tok — sizes below are approximate, not exact`), contentWidth, ""));
 		}
-		const verticalBars = renderContextVerticalBars(theme, this.breakdown.segments);
-		if (verticalBars.length > 0) {
-			lines.push("");
-			lines.push(theme.fg("dim", "Composition of used tokens:"));
-			for (const barLine of verticalBars) lines.push(truncateToWidth(barLine, contentWidth, ""));
-		}
 		lines.push("");
 
 		this.visibleWindow().forEach(({ row, index }) => {
@@ -161,6 +142,26 @@ class ContextViewport {
 	}
 }
 
+/**
+ * Distributes `totalCells` proportionally across `weights` (parallel arrays), guaranteeing
+ * every genuinely-positive weight gets at least one cell when there is room for all of them
+ * to (totalCells >= weights.length) -- a real, nonzero segment must stay visible even when
+ * dwarfed by a much larger one, not round away to nothing. The largest resulting cell count
+ * absorbs whatever rounding leaves over or short, so the sum always equals totalCells exactly.
+ */
+function distributeCells(weights: readonly number[], totalCells: number): number[] {
+	const sum = weights.reduce((a, b) => a + b, 0);
+	if (sum <= 0 || totalCells <= 0 || weights.length === 0) return weights.map(() => 0);
+	let cells = weights.map((weight) => Math.round((weight / sum) * totalCells));
+	if (totalCells >= weights.length) cells = cells.map((count) => (count === 0 ? 1 : count));
+	const diff = totalCells - cells.reduce((a, b) => a + b, 0);
+	if (diff !== 0) {
+		const maxIndex = cells.indexOf(Math.max(...cells));
+		cells[maxIndex] = (cells[maxIndex] ?? 0) + diff;
+	}
+	return cells;
+}
+
 /**
  * Renders the context window as one horizontal stacked bar: one colored run of block
  * characters per USED segment, followed by a gray/dim run of "░" cells for the remaining,
@@ -169,23 +170,30 @@ class ContextViewport {
  * divide-by-zero, since 0 used really does mean the whole window is empty right now.
  *
  * `capacity` is the real denominator (Papyrus's own effectiveBudget, matching the percentage
- * already shown in the text line above this bar) that used-vs-unused is measured against. When
- * omitted, or when usage has already exceeded it (overshoot / near-compaction), the bar falls
- * back to filling 100% of its width proportionally among segments -- there is no "unused" left
- * to show gray for once real usage has met or passed the real budget.
+ * already shown in the text line above this bar). `usedTokens` is the real, ground-truth used
+ * amount (breakdown.totalTokens) the used-vs-unused split is measured against -- NOT the sum of
+ * `segments`' own estimates. That distinction is load-bearing: a live-reported bug showed a
+ * fully solid bar with zero gray even though the header read "55.9% of usable budget", because
+ * the old code compared `capacity` against the SUM of estimated segments, which independently
+ * overshot both the real total and the capacity itself (a session whose message-history
+ * estimate alone summed to over 1.5M tokens against a real ~550k total) -- the exact estimate-
+ * overshoot dishonesty `overshootTokens` exists to surface elsewhere was silently defeating the
+ * bar's own gray/used split. `usedTokens` defaults to the segment sum only when omitted, for
+ * callers with no real total available. Segments still split the USED portion proportionally to
+ * their own estimated share of each other (via distributeCells, which also guarantees a tiny
+ * nonzero segment stays visible rather than rounding to nothing next to a much larger one).
  */
-export function renderContextBar(theme: Theme, segments: ReadonlyArray<ContextSegment>, width: number, capacity?: number): string {
-	const total = segments.reduce((sum, segment) => sum + segment.estimatedTokens, 0);
-	if (total <= 0 || width <= 0) return theme.fg("dim", "░".repeat(Math.max(0, width)));
-	const nonZero = segments.filter((segment) => segment.estimatedTokens > 0);
-	const usedWidth = capacity !== undefined && capacity > total ? Math.min(width, Math.round((total / capacity) * width)) : width;
+export function renderContextBar(theme: Theme, segments: ReadonlyArray<ContextSegment>, width: number, capacity?: number, usedTokens?: number): string {
+	const estimatedSum = segments.reduce((sum, segment) => sum + segment.estimatedTokens, 0);
+	if (estimatedSum <= 0 || width <= 0) return theme.fg("dim", "░".repeat(Math.max(0, width)));
+	const realUsed = usedTokens ?? estimatedSum;
+	const usedWidth = capacity !== undefined ? Math.max(0, Math.min(width, Math.round((realUsed / capacity) * width))) : width;
 
-	let used = 0;
+	const nonZero = segments.filter((segment) => segment.estimatedTokens > 0);
+	const cellCounts = distributeCells(nonZero.map((segment) => segment.estimatedTokens), usedWidth);
 	let output = "";
 	nonZero.forEach((segment, index) => {
-		const isLast = index === nonZero.length - 1;
-		const cells = isLast ? usedWidth - used : Math.round((segment.estimatedTokens / total) * usedWidth);
-		used += cells;
+		const cells = cellCounts[index] ?? 0;
 		if (cells > 0) output += theme.fg(SEGMENT_COLORS[segment.key], "█".repeat(cells));
 	});
 	const emptyWidth = width - usedWidth;
@@ -193,36 +201,6 @@ export function renderContextBar(theme: Theme, segments: ReadonlyArray<ContextSe
 	return output;
 }
 
-/**
- * Renders the "used" portion's own composition as a small vertical bar chart, one column per
- * segment with real content, scaled so the largest segment fills the full height -- the
- * "deep dive" graph, complementing the horizontal used-vs-unused bar above it. Any segment
- * with real (nonzero) tokens gets at least one filled row so it stays visible even next to a
- * much larger segment. Returns an empty array (nothing to render) when no segment has any
- * tokens yet, matching the same zero-noise principle as the row list below it.
- */
-export function renderContextVerticalBars(theme: Theme, segments: ReadonlyArray<ContextSegment>): string[] {
-	const visible = segments.filter((segment) => segment.estimatedTokens > 0);
-	if (visible.length === 0) return [];
-	const max = Math.max(...visible.map((segment) => segment.estimatedTokens));
-	const filledRows = new Map(visible.map((segment) => [segment.key, Math.max(1, Math.round((segment.estimatedTokens / max) * VERTICAL_BAR_HEIGHT))]));
-
-	const lines: string[] = [];
-	for (let row = 0; row < VERTICAL_BAR_HEIGHT; row++) {
-		const rowsFromBottom = VERTICAL_BAR_HEIGHT - row;
-		let line = "";
-		for (const segment of visible) {
-			const filled = (filledRows.get(segment.key) ?? 0) >= rowsFromBottom;
-			line += `${filled ? theme.fg(SEGMENT_COLORS[segment.key], "█".repeat(VERTICAL_BAR_WIDTH)) : " ".repeat(VERTICAL_BAR_WIDTH)} `;
-		}
-		lines.push(line);
-	}
-	let legend = "";
-	for (const segment of visible) legend += `${theme.fg(SEGMENT_COLORS[segment.key], SEGMENT_SHORT_LABELS[segment.key])} `;
-	lines.push(legend);
-	return lines;
-}
-
 /** Non-interactive fallback (print mode, RPC, etc.): the same unified row list, as plain text lines. */
 function fallbackReport(breakdown: ContextBreakdown): string {
 	const totalLine = breakdown.totalTokens !== null

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.15.0",
+  "version": "0.15.2",
   "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
   "type": "module",
   "keywords": ["pi-package"],

package/src/constants.ts

@@ -30,7 +30,8 @@ export const CONTEXT_ESTIMATE_CHARACTERS_PER_TOKEN = 4;
  * tree when estimating /context's message-history and task segments. Both are genuine trees
  * built from external, mutable state (a session file; the live Task graph) -- the node bound
  * is a defensive measure against a corrupted/adversarial parentId chain forming an accidental
- * cycle, matching the same cycle-safety discipline already applied to ConversationJournal
+ * cycle, matching the same cycle-safety discipline established by the (since-removed;
+ * see Doc "ConversationJournal design record") ConversationJournal domain's own reply-chain
  * traversal and deliberately hardening past a real, confirmed gap in Pi's own getBranch() (no
  * cycle guard at all). Set generously: a real, ordinary (non-branching) long-running session
  * is one long linear chain, so a naively small bound truncates the walk after counting only a
@@ -92,8 +93,9 @@ export const SKILL_MAX_RENDERED_BYTES = 1_048_576;
  * to (existing Tasks/Rules/Docs via ordinary edges, not just its own static body/extra
  * fields), and a Skill can link to and invoke other Skills. Both traversals are bounded and
  * cycle-safe -- a skill-calls-skill edge cycle must not infinite-loop invocation, matching
- * the cycle-safety discipline already established for ConversationJournal reply chains and
- * task dependency graphs.
+ * the same cycle-safety discipline established by task dependency graphs and the
+ * (since-removed; see Doc "ConversationJournal design record") ConversationJournal domain's
+ * own reply chains.
  */
 export const SKILL_INVOCATION_MAX_LINKED_ARTIFACTS = 20;
 export const SKILL_INVOCATION_MAX_CALL_DEPTH = 4;

package/src/domain/log-entry.ts

@@ -10,9 +10,10 @@
  * first-class concern here in a way it deliberately is NOT for the permanent
  * artifact_events/task_events audit trails: logs are meant to be rotated, not kept forever.
  *
- * Mirrors ConversationJournal's own discipline (idempotency via a caller-constructed
- * composite operationId, explicit non-silent truncation) since both are append-only,
- * externally-sourced record streams -- but logs have no reply structure and do carry a
+ * Mirrors the (since-removed; see Doc "ConversationJournal design record") ConversationJournal
+ * domain's own discipline (idempotency via a caller-constructed composite operationId,
+ * explicit non-silent truncation) since both are append-only, externally-sourced record
+ * streams -- but logs have no reply structure and do carry a
  * retention policy, which a durable conversation record deliberately does not.
  */
 
@@ -49,8 +50,9 @@ export interface LogEntry {
 	/**
 	 * Idempotency key. Must be a composite the caller constructs (e.g. `${sessionId}:${turn}`),
 	 * never a bare upstream id alone -- a source's own local ids are commonly unique only
-	 * within one recording run, not globally, matching ConversationJournal's identical
-	 * operationId discipline and the concrete case it generalizes from (Pi's /tree lessons).
+	 * within one recording run, not globally, matching the same operationId discipline
+	 * established by the (since-removed) ConversationJournal domain and the concrete case
+	 * it generalizes from (Pi's /tree lessons).
 	 */
 	readonly operationId: string;
 	readonly sessionId?: string;

package/src/domain-services.ts

@@ -388,8 +388,9 @@ function skillInvocationBody(skill: Artifact): string {
  * workflow execution already uses for skill-to-task edges): invoking the parent recursively
  * composes the linked skill's own invocation. Bounded and cycle-safe -- a skill-calls-skill
  * edge cycle degrades to a marker instead of infinite-looping, matching the cycle-safety
- * discipline already established for ConversationJournal reply chains and task dependency
- * graphs. `visited` and `depth` are recursion-internal; callers should not pass them.
+ * discipline established by task dependency graphs and the (since-removed; see Doc
+ * "ConversationJournal design record") ConversationJournal domain's own reply chains.
+ * `visited` and `depth` are recursion-internal; callers should not pass them.
  */
 export function skillInvocation(artifacts: ArtifactStore, id: string, visited: Set<string> = new Set(), depth = 0): string {
 	const skill = requireKind(artifacts, id, "skill");

package/src/ports/log-store.ts

@@ -1,10 +1,11 @@
 import type { LogEntry, LogSource } from "../domain/log-entry.ts";
 
 /**
- * Persistence port for the `log` domain. Deliberately minimal, matching
- * ConversationJournalStore's own split: this is dumb storage (idempotency-key lookup,
- * insert, bounded-at-the-service-layer reads) plus one operation the store must own because
- * only it knows real row counts -- retention trimming.
+ * Persistence port for the `log` domain. Deliberately minimal, matching the split established
+ * by the (since-removed; see Doc "ConversationJournal design record") ConversationJournalStore:
+ * this is dumb storage (idempotency-key lookup, insert, bounded-at-the-service-layer reads)
+ * plus one operation the store must own because only it knows real row counts -- retention
+ * trimming.
  */
 export interface LogStore {
 	ensureSource(sourceId: string, label: string, projectRoot: string | null): LogSource;

package/src/adapters/in-memory-conversation-journal-store.ts

@@ -1,48 +0,0 @@
-import type { JournalPost, JournalThread } from "../domain/conversation-journal.ts";
-import type { ConversationJournalStore } from "../ports/conversation-journal-store.ts";
-
-/**
- * Bounded in-memory conformance fixture -- the reference implementation the
- * conversationJournalConformanceSuite is proven against first, before any real
- * persistence backend needs to satisfy the same contract.
- */
-export class InMemoryConversationJournalStore implements ConversationJournalStore {
-	private readonly threads = new Map<string, JournalThread>();
-	private readonly posts = new Map<string, JournalPost>();
-	private readonly postIdsByOperationId = new Map<string, string>();
-	private readonly postIdsByThread = new Map<string, string[]>();
-
-	ensureThread(threadId: string): JournalThread {
-		const existing = this.threads.get(threadId);
-		if (existing) return existing;
-		const thread: JournalThread = { id: threadId, createdAt: new Date().toISOString() };
-		this.threads.set(threadId, thread);
-		return thread;
-	}
-
-	getThread(threadId: string): JournalThread | undefined {
-		return this.threads.get(threadId);
-	}
-
-	findPostByOperationId(operationId: string): JournalPost | undefined {
-		const postId = this.postIdsByOperationId.get(operationId);
-		return postId ? this.posts.get(postId) : undefined;
-	}
-
-	insertPost(post: JournalPost): void {
-		this.posts.set(post.id, post);
-		this.postIdsByOperationId.set(post.operationId, post.id);
-		const ids = this.postIdsByThread.get(post.threadId) ?? [];
-		ids.push(post.id);
-		this.postIdsByThread.set(post.threadId, ids);
-	}
-
-	getPost(id: string): JournalPost | undefined {
-		return this.posts.get(id);
-	}
-
-	postsForThread(threadId: string): readonly JournalPost[] {
-		const ids = this.postIdsByThread.get(threadId) ?? [];
-		return ids.map((id) => this.posts.get(id)!);
-	}
-}

package/src/conversation-journal-service.ts

@@ -1,87 +0,0 @@
-/**
- * conversation-journal-service.ts — host-neutral ConversationJournal application layer.
- *
- * Owns idempotency (checking operationId before insert) and bounds enforcement; the
- * ConversationJournalStore port underneath is dumb storage. See
- * src/domain/conversation-journal.ts for the domain shapes and the design rationale.
- */
-import {
-	ancestorChain,
-	boundContent,
-	buildThreadTree,
-	CONVERSATION_JOURNAL_READ_MAX_POSTS,
-	validateAppendPostCommand,
-	type AppendPostCommand,
-	type AppendPostResult,
-	type JournalPost,
-	type JournalThread,
-	type ReadThreadQuery,
-	type ThreadPage,
-	type ThreadTreeNode,
-} from "./domain/conversation-journal.ts";
-import type { ConversationJournalStore } from "./ports/conversation-journal-store.ts";
-
-export class ConversationJournalService {
-	constructor(private readonly store: ConversationJournalStore) {}
-
-	appendPost(command: AppendPostCommand): AppendPostResult {
-		validateAppendPostCommand(command);
-
-		const existing = this.store.findPostByOperationId(command.operationId);
-		if (existing) return { post: existing, replayed: true };
-
-		if (command.replyToPostId !== undefined && !this.store.getPost(command.replyToPostId)) {
-			throw new Error(`replyToPostId "${command.replyToPostId}" not found`);
-		}
-
-		this.store.ensureThread(command.threadId);
-		const { content, truncated } = boundContent(command.content);
-		const post: JournalPost = {
-			id: crypto.randomUUID(),
-			threadId: command.threadId,
-			...(command.replyToPostId !== undefined ? { replyToPostId: command.replyToPostId } : {}),
-			authorId: command.authorId,
-			content,
-			truncated,
-			timestamp: new Date().toISOString(),
-			sourceSessionId: command.sourceSessionId,
-			operationId: command.operationId,
-			references: command.references ? [...command.references] : [],
-		};
-		this.store.insertPost(post);
-		return { post, replayed: false };
-	}
-
-	getThread(threadId: string): JournalThread | undefined {
-		return this.store.getThread(threadId);
-	}
-
-	getPost(id: string): JournalPost | undefined {
-		return this.store.getPost(id);
-	}
-
-	/** Bounded, explicit-completeness thread read. Never silently drops posts past the bound. */
-	readThread(query: ReadThreadQuery): ThreadPage {
-		const limit = query.limit;
-		if (!Number.isInteger(limit) || limit < 1 || limit > CONVERSATION_JOURNAL_READ_MAX_POSTS) {
-			throw new Error(`readThread limit must be between 1 and ${CONVERSATION_JOURNAL_READ_MAX_POSTS}`);
-		}
-		const all = [...this.store.postsForThread(query.threadId)].sort(
-			(left, right) => left.timestamp.localeCompare(right.timestamp) || left.id.localeCompare(right.id),
-		);
-		const truncated = all.length > limit;
-		return { posts: all.slice(0, limit), truncated };
-	}
-
-	/** Reconstructed reply tree for a thread, bounded and orphan/cycle-safe -- see buildThreadTree. */
-	readThreadTree(threadId: string): ThreadTreeNode[] {
-		return buildThreadTree(this.store.postsForThread(threadId));
-	}
-
-	/** Root-first ancestor chain for one post -- the host-neutral equivalent of Pi's getBranch(). */
-	ancestorsOf(postId: string): JournalPost[] {
-		const posts = this.store.postsForThread(this.store.getPost(postId)?.threadId ?? "");
-		const byId = new Map(posts.map((post) => [post.id, post]));
-		return ancestorChain(postId, byId);
-	}
-}

package/src/domain/conversation-journal.ts

@@ -1,168 +0,0 @@
-/**
- * domain/conversation-journal.ts — host-neutral ConversationJournal domain.
- *
- * See decision-discourse-as-a-layer-above-sessions-separate-conver-p832 and
- * pis-tree-implementation-concrete-lessons-for-the-discourse-s-wnrs (Papyrus docs) for the
- * design this implements and the concrete lessons behind each choice below.
- *
- * A Thread is the conversation's own stable identity, independent of whichever host
- * process/session recorded any given Post into it. This module and its package source
- * must never mention host runtime names (no "Pi") -- sourceSessionId is a generic
- * provenance field on a Post, not a host-specific concept, and the host decides what
- * value to put there.
- */
-
-export const CONVERSATION_JOURNAL_CONTENT_MAX_CHARACTERS = 20_000;
-export const CONVERSATION_JOURNAL_SOURCE_ID_MAX_LENGTH = 256;
-export const CONVERSATION_JOURNAL_MAX_REFERENCES_PER_POST = 50;
-/** Bounds a single readThread call; retention/eviction beyond this is a host/persistence concern, not this domain's. */
-export const CONVERSATION_JOURNAL_READ_MAX_POSTS = 500;
-/** Bounds reply-chain traversal so a cycle (accidental or adversarial) cannot infinite-loop a tree build -- see the Pi /tree lessons doc for why this must not be assumed away. */
-export const CONVERSATION_JOURNAL_MAX_TRAVERSAL_DEPTH = 10_000;
-
-export type JournalAuthor = "human" | "agent";
-
-/** A reference to an artifact owned outside this journal -- verified by the host, never asserted. */
-export interface ArtifactReference {
-	readonly kind: string;
-	readonly id: string;
-}
-
-export interface JournalThread {
-	readonly id: string;
-	readonly createdAt: string;
-}
-
-export interface JournalPost {
-	readonly id: string;
-	readonly threadId: string;
-	/** Absent only for a thread's first post. */
-	readonly replyToPostId?: string;
-	readonly authorId: JournalAuthor;
-	readonly content: string;
-	/** True when content was cut to CONVERSATION_JOURNAL_CONTENT_MAX_CHARACTERS -- never silently. */
-	readonly truncated: boolean;
-	readonly timestamp: string;
-	/** Which host session/process recorded this post. Provenance, never this domain's top-level container -- see the layering decision doc. */
-	readonly sourceSessionId: string;
-	/**
-	 * Idempotency key. Must be a composite of (sourceSessionId, a host-local entry id),
-	 * constructed by the caller -- never a bare host entry id alone. A host's own entry
-	 * ids are commonly unique only within one recording session, not globally; using one
-	 * alone as a global idempotency key risks a false dedup collision between two
-	 * unrelated sessions. See the Pi /tree lessons doc for the concrete case this
-	 * generalizes from.
-	 */
-	readonly operationId: string;
-	readonly references: readonly ArtifactReference[];
-}
-
-export interface AppendPostCommand {
-	readonly threadId: string;
-	readonly replyToPostId?: string;
-	readonly authorId: JournalAuthor;
-	readonly content: string;
-	readonly sourceSessionId: string;
-	readonly operationId: string;
-	readonly references?: readonly ArtifactReference[];
-}
-
-export interface AppendPostResult {
-	readonly post: JournalPost;
-	/** True when this exact operationId was already journaled and this call was a safe no-op replay. */
-	readonly replayed: boolean;
-}
-
-export interface ReadThreadQuery {
-	readonly threadId: string;
-	readonly limit: number;
-}
-
-export interface ThreadPage {
-	readonly posts: readonly JournalPost[];
-	/** True when more posts exist beyond `limit` -- never silently drop the tail without saying so. */
-	readonly truncated: boolean;
-}
-
-/** One node of a reconstructed reply tree; see buildThreadTree. */
-export interface ThreadTreeNode {
-	readonly post: JournalPost;
-	readonly children: ThreadTreeNode[];
-}
-
-function requireBounded(value: string, label: string, maxLength: number): string {
-	if (value.length === 0) throw new Error(`${label} is required`);
-	if (value.length > maxLength) throw new Error(`${label} exceeds ${maxLength} characters`);
-	return value;
-}
-
-export function validateAppendPostCommand(command: AppendPostCommand): void {
-	requireBounded(command.threadId, "threadId", CONVERSATION_JOURNAL_SOURCE_ID_MAX_LENGTH);
-	requireBounded(command.sourceSessionId, "sourceSessionId", CONVERSATION_JOURNAL_SOURCE_ID_MAX_LENGTH);
-	requireBounded(command.operationId, "operationId", CONVERSATION_JOURNAL_SOURCE_ID_MAX_LENGTH * 2);
-	if (command.content.length === 0) throw new Error("content is required");
-	if (command.authorId !== "human" && command.authorId !== "agent") throw new Error('authorId must be "human" or "agent"');
-	const references = command.references ?? [];
-	if (references.length > CONVERSATION_JOURNAL_MAX_REFERENCES_PER_POST) {
-		throw new Error(`a post is bounded to ${CONVERSATION_JOURNAL_MAX_REFERENCES_PER_POST} references; got ${references.length}`);
-	}
-}
-
-/** Applies the explicit truncation bound. Never silently drops the truncation fact -- callers must surface `truncated`. */
-export function boundContent(content: string): { content: string; truncated: boolean } {
-	if (content.length <= CONVERSATION_JOURNAL_CONTENT_MAX_CHARACTERS) return { content, truncated: false };
-	return { content: content.slice(0, CONVERSATION_JOURNAL_CONTENT_MAX_CHARACTERS), truncated: true };
-}
-
-/**
- * Reconstructs the reply tree from a flat list of posts (as returned by one bounded
- * readThread call). A post whose replyToPostId does not resolve within this same list --
- * because it is genuinely a thread root, or because an ancestor aged out under a
- * retention policy -- degrades to being treated as a root of its own sub-tree, exactly
- * like Pi's own getTree() treats an orphaned entry. This never throws on that account.
- *
- * Bounded and cycle-safe: a post already visited while walking up cannot be revisited,
- * so a malformed or adversarial replyToPostId cycle cannot infinite-loop this function --
- * see the Pi /tree lessons doc for why that guard must be explicit, not assumed.
- */
-export function buildThreadTree(posts: readonly JournalPost[]): ThreadTreeNode[] {
-	const nodesById = new Map<string, ThreadTreeNode>();
-	for (const post of posts) nodesById.set(post.id, { post, children: [] });
-
-	const roots: ThreadTreeNode[] = [];
-	for (const post of posts) {
-		const node = nodesById.get(post.id)!;
-		const parent = post.replyToPostId ? nodesById.get(post.replyToPostId) : undefined;
-		if (parent) parent.children.push(node);
-		else roots.push(node);
-	}
-
-	for (const node of nodesById.values()) {
-		node.children.sort((left, right) => left.post.timestamp.localeCompare(right.post.timestamp) || left.post.id.localeCompare(right.post.id));
-	}
-	roots.sort((left, right) => left.post.timestamp.localeCompare(right.post.timestamp) || left.post.id.localeCompare(right.post.id));
-	return roots;
-}
-
-/**
- * Walks from a post back toward its thread root via replyToPostId, root-first order --
- * the host-neutral equivalent of Pi's getBranch(). Bounded by
- * CONVERSATION_JOURNAL_MAX_TRAVERSAL_DEPTH and tracks visited ids explicitly so a cycle
- * cannot infinite-loop this walk, unlike Pi's own getBranch() (a documented gap in Pi,
- * not something to assume away here).
- */
-export function ancestorChain(postId: string, postsById: ReadonlyMap<string, JournalPost>): JournalPost[] {
-	const chain: JournalPost[] = [];
-	const visited = new Set<string>();
-	let currentId: string | undefined = postId;
-	while (currentId !== undefined) {
-		if (visited.has(currentId)) break; // cycle guard
-		if (chain.length >= CONVERSATION_JOURNAL_MAX_TRAVERSAL_DEPTH) break; // depth guard
-		visited.add(currentId);
-		const post = postsById.get(currentId);
-		if (!post) break; // orphan: stop here, do not error
-		chain.push(post);
-		currentId = post.replyToPostId;
-	}
-	return chain.reverse();
-}

package/src/ports/conversation-journal-store.ts

@@ -1,17 +0,0 @@
-import type { JournalPost, JournalThread } from "../domain/conversation-journal.ts";
-
-/**
- * Persistence port for ConversationJournal. Deliberately minimal and host-neutral: no
- * mention of any host runtime, no query beyond what a bounded thread read needs. Idempotency
- * (checking operationId before insert) is the service's job, not the store's -- this port is
- * dumb storage, matching Discourse's own store/service split (see the layering decision doc).
- */
-export interface ConversationJournalStore {
-	ensureThread(threadId: string): JournalThread;
-	getThread(threadId: string): JournalThread | undefined;
-	findPostByOperationId(operationId: string): JournalPost | undefined;
-	insertPost(post: JournalPost): void;
-	getPost(id: string): JournalPost | undefined;
-	/** All posts for one thread, unbounded at the store layer -- the service applies the read bound. */
-	postsForThread(threadId: string): readonly JournalPost[];
-}