@danypops/papyrus 0.11.4 → 0.12.0

package/src/domain/conversation-journal.ts

@@ -0,0 +1,168 @@
+/**
+ * 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/domain/discourse-store.ts

@@ -0,0 +1,142 @@
+import {
+	DISCOURSE_CONTENT_MAX_BYTES,
+	DISCOURSE_EVENT_RETENTION_DEFAULT,
+	DISCOURSE_EVENT_RETENTION_MAX,
+	DISCOURSE_QUERY_MAX_LIMIT,
+} from "../constants.ts";
+
+/** Papyrus-owned Doc subtypes reserved for the Discourse persistence adapter. */
+export const DISCOURSE_THREAD_SUBTYPE = "context-thread";
+export const DISCOURSE_MESSAGE_SUBTYPE = "context-message";
+export const DISCOURSE_RELATIONS = new Set(["reply_to", "discusses"]);
+
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue };
+export interface ArtifactReference { kind: string; id: string }
+export interface ThreadAddress { forumId: string; topicId: string; threadId: string }
+export interface AppendPostCommand extends ThreadAddress {
+	schemaVersion: "discourse.command.v1";
+	operationId: string;
+	authorId: string;
+	content: JsonValue;
+	correlationId?: string;
+	causationId?: string;
+	replyToPostId?: string;
+	references?: ArtifactReference[];
+}
+export interface Post extends ThreadAddress {
+	id: string;
+	authorId: string;
+	content: JsonValue;
+	timestamp: number;
+	sequence: number;
+	operationId: string;
+	correlationId?: string;
+	causationId?: string;
+	replyToPostId?: string;
+	references: ArtifactReference[];
+}
+export type DiscourseEventType = "post-added" | "thread-changed" | "question-opened" | "question-answered" | "subscription-resync-required";
+export interface DiscourseEvent extends ThreadAddress {
+	schemaVersion: "discourse.event.v1";
+	type: DiscourseEventType;
+	sequence: number;
+	timestamp: number;
+	postId?: string;
+	operationId?: string;
+	correlationId?: string;
+	causationId?: string;
+	responseId?: string;
+	retainedFromSequence?: number;
+}
+export interface Page<T> {
+	items: T[];
+	truncated: boolean;
+	nextSequence?: number;
+	completeness: "complete" | "truncated";
+}
+export interface TopicSummary { forumId: string; topicId: string; threadCount: number; postCount: number; lastActivity: number }
+export interface ThreadSummary extends ThreadAddress { postCount: number; participantIds: string[]; lastActivity: number }
+export interface OpenQuestion { responseId: string; post: Post }
+export interface ProjectionRecord { sequence: number; post: Post }
+
+export function isDiscourseSubtype(subtype: string | undefined): boolean {
+	return subtype === DISCOURSE_THREAD_SUBTYPE || subtype === DISCOURSE_MESSAGE_SUBTYPE;
+}
+
+function record(value: unknown, name: string): Record<string, unknown> {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error(`${name} must be an object`);
+	return value as Record<string, unknown>;
+}
+
+export function requiredString(value: unknown, name: string): string {
+	if (typeof value !== "string" || value.length === 0) throw new Error(`${name} is required`);
+	return value;
+}
+
+export function optionalString(value: unknown, name: string): string | undefined {
+	if (value === undefined) return undefined;
+	if (typeof value !== "string" || value.length === 0) throw new Error(`${name} must be a non-empty string`);
+	return value;
+}
+
+export function nonNegativeInteger(value: unknown, name: string): number {
+	if (!Number.isSafeInteger(value) || (value as number) < 0) throw new Error(`${name} must be a non-negative safe integer`);
+	return value as number;
+}
+
+export function queryLimit(value: unknown): number {
+	const limit = nonNegativeInteger(value, "limit");
+	if (limit < 1 || limit > DISCOURSE_QUERY_MAX_LIMIT) throw new Error(`limit must be between 1 and ${DISCOURSE_QUERY_MAX_LIMIT}`);
+	return limit;
+}
+
+export function eventRetention(value: unknown): number {
+	if (value === undefined) return DISCOURSE_EVENT_RETENTION_DEFAULT;
+	const retention = nonNegativeInteger(value, "event_retention");
+	if (retention < 1 || retention > DISCOURSE_EVENT_RETENTION_MAX) {
+		throw new Error(`event_retention must be between 1 and ${DISCOURSE_EVENT_RETENTION_MAX}`);
+	}
+	return retention;
+}
+
+function jsonValue(value: unknown, name: string): JsonValue {
+	const encoded = JSON.stringify(value);
+	if (encoded === undefined) throw new Error(`${name} must be JSON-serializable`);
+	if (new TextEncoder().encode(encoded).byteLength > DISCOURSE_CONTENT_MAX_BYTES) {
+		throw new Error(`${name} cannot exceed ${DISCOURSE_CONTENT_MAX_BYTES} bytes`);
+	}
+	return JSON.parse(encoded) as JsonValue;
+}
+
+export function appendCommand(value: unknown): AppendPostCommand {
+	const input = record(value, "command");
+	if (input["schemaVersion"] !== "discourse.command.v1") throw new Error("unsupported Discourse command schema");
+	const referencesValue = input["references"] ?? [];
+	if (!Array.isArray(referencesValue)) throw new Error("references must be an array");
+	const references = referencesValue.map((entry, index) => {
+		const reference = record(entry, `references[${index}]`);
+		return { kind: requiredString(reference["kind"], `references[${index}].kind`), id: requiredString(reference["id"], `references[${index}].id`) };
+	});
+	return {
+		schemaVersion: "discourse.command.v1",
+		operationId: requiredString(input["operationId"], "operationId"),
+		forumId: requiredString(input["forumId"], "forumId"),
+		topicId: requiredString(input["topicId"], "topicId"),
+		threadId: requiredString(input["threadId"], "threadId"),
+		authorId: requiredString(input["authorId"], "authorId"),
+		content: jsonValue(input["content"], "content"),
+		...(optionalString(input["correlationId"], "correlationId") ? { correlationId: input["correlationId"] as string } : {}),
+		...(optionalString(input["causationId"], "causationId") ? { causationId: input["causationId"] as string } : {}),
+		...(optionalString(input["replyToPostId"], "replyToPostId") ? { replyToPostId: input["replyToPostId"] as string } : {}),
+		references,
+	};
+}
+
+export function threadAddress(value: Record<string, unknown>): ThreadAddress {
+	return {
+		forumId: requiredString(value["forumId"], "forumId"),
+		topicId: requiredString(value["topicId"], "topicId"),
+		threadId: requiredString(value["threadId"], "threadId"),
+	};
+}

package/src/domain/graph-projection.ts

@@ -0,0 +1,74 @@
+/**
+ * domain/graph-projection.ts — the generic graph projection protocol for external bounded
+ * contexts (step 6 of the incremental refactor in
+ * reducing-papyrus-consumer-change-amplification-with-modules--pvdo), sketched in
+ * papyrus-full-context-mesh-and-domain-storage-ownership-bound-qhzp.
+ *
+ * An external bounded context owns its own operational state and command authority. It
+ * never becomes a Papyrus-native module just to appear in the graph. Instead it publishes
+ * bounded, sequenced batches of the context-bearing identities and edges it wants durably
+ * materialized in the Context Mesh. Papyrus is an idempotent materialized read model for
+ * that producer's data, not its command database.
+ *
+ * Deliberately out of scope for this walking skeleton, each a separate follow-up:
+ * - Producer identity is a request field (`producerId`), not yet derived from scoped
+ *   authentication -- the decision doc's constraint that "producer identity comes from
+ *   scoped authentication, not request payloads" is not yet met, since Papyrus's daemon
+ *   auth model today is one shared bearer token, not per-caller identity. Tracked as a
+ *   known gap, not silently assumed solved.
+ * - Edges reference other artifacts only via an externalId already projected by the SAME
+ *   producer in this batch or a prior one. Linking a projected artifact to an existing
+ *   Papyrus-native artifact (e.g. "this Discourse thread discusses this Task") is not yet
+ *   supported here -- a real, needed capability, but a second batch shape / edge kind, not
+ *   assumed away.
+ * - "Lag" is reported as Papyrus's own last-applied checkpoint; Papyrus has no way to know
+ *   a producer's true current sequence, so relative lag must be computed by the caller
+ *   (who does know its own latest sequence) by diffing against this checkpoint.
+ */
+
+export const GRAPH_PROJECTION_SCHEMA_VERSION = "papyrus.graph-projection/v1";
+
+export interface ProjectedArtifact {
+	/** The producer's own stable identity for this entity -- never a Papyrus artifact id. */
+	readonly externalId: string;
+	readonly kind: string;
+	readonly subtype?: string;
+	readonly title: string;
+	readonly body?: string;
+	readonly labels?: readonly string[];
+	readonly extra?: Record<string, unknown>;
+}
+
+export interface ProjectedEdge {
+	readonly from: string; // externalId, resolved against this producer's identity map
+	readonly relation: string;
+	readonly to: string; // externalId, resolved against this producer's identity map
+}
+
+export interface GraphProjectionBatch {
+	readonly schemaVersion: typeof GRAPH_PROJECTION_SCHEMA_VERSION;
+	readonly producerId: string;
+	readonly batchId: string;
+	/** Monotonic per-producer sequence, starting at 1. Enforced gapless -- see GraphProjection.apply. */
+	readonly sequence: number;
+	readonly artifacts: readonly ProjectedArtifact[];
+	readonly edges: readonly ProjectedEdge[];
+}
+
+export interface ProjectionCheckpoint {
+	readonly producerId: string;
+	readonly lastSequence: number;
+	readonly lastBatchId: string;
+	readonly appliedAt: string;
+}
+
+export interface GraphProjectionResult {
+	readonly producerId: string;
+	readonly batchId: string;
+	readonly sequence: number;
+	readonly artifactsUpserted: number;
+	readonly artifactsCreated: number;
+	readonly edgesUpserted: number;
+	/** True only when this exact batch was already applied and this call was a safe no-op replay. */
+	readonly alreadyApplied: boolean;
+}

package/src/domain/task-event.ts

@@ -24,6 +24,10 @@ export const TASK_EVENT_TYPES = [
 	"retried",
 	"completed",
 	"canceled",
+	"dependency_added",
+	"dependency_removed",
+	"containment_added",
+	"containment_removed",
 ] as const;
 
 export type TaskEventType = typeof TASK_EVENT_TYPES[number];