@danypops/papyrus 0.17.2 → 0.19.0

package/src/db.ts

@@ -134,7 +134,8 @@ CREATE INDEX IF NOT EXISTS task_events_history_idx ON task_events(task_id, occur
 CREATE TRIGGER IF NOT EXISTS task_events_no_update BEFORE UPDATE ON task_events
 BEGIN SELECT RAISE(ABORT, 'task_events are append-only'); END;
 CREATE TRIGGER IF NOT EXISTS task_events_no_delete BEFORE DELETE ON task_events
-BEGIN SELECT RAISE(ABORT, 'task_events are append-only'); END;
+WHEN NOT EXISTS (SELECT 1 FROM artifact_trash WHERE artifact_id = OLD.task_id AND purge_after <= strftime('%Y-%m-%dT%H:%M:%fZ','now'))
+BEGIN SELECT RAISE(ABORT, 'task_events are append-only except during an explicit, elapsed-grace-period artifact trash purge'); END;
 CREATE TABLE IF NOT EXISTS task_scopes (
 	task_id       TEXT PRIMARY KEY REFERENCES artifacts(id),
 	project_root  TEXT,
@@ -170,7 +171,8 @@ CREATE INDEX IF NOT EXISTS artifact_events_session_idx ON artifact_events(sessio
 CREATE TRIGGER IF NOT EXISTS artifact_events_no_update BEFORE UPDATE ON artifact_events
 BEGIN SELECT RAISE(ABORT, 'artifact_events are append-only'); END;
 CREATE TRIGGER IF NOT EXISTS artifact_events_no_delete BEFORE DELETE ON artifact_events
-BEGIN SELECT RAISE(ABORT, 'artifact_events are append-only'); END;
+WHEN NOT EXISTS (SELECT 1 FROM artifact_trash WHERE artifact_id = OLD.artifact_id AND purge_after <= strftime('%Y-%m-%dT%H:%M:%fZ','now'))
+BEGIN SELECT RAISE(ABORT, 'artifact_events are append-only except during an explicit, elapsed-grace-period artifact trash purge'); END;
 CREATE TABLE IF NOT EXISTS graph_projection_checkpoints (
 	producer_id    TEXT PRIMARY KEY,
 	last_sequence  INTEGER NOT NULL,
@@ -218,6 +220,29 @@ CREATE TABLE IF NOT EXISTS session_identities (
 	registered_at TEXT NOT NULL,
 	last_seen_at  TEXT NOT NULL
 );
+CREATE TABLE IF NOT EXISTS artifact_trash (
+	artifact_id  TEXT PRIMARY KEY REFERENCES artifacts(id),
+	trashed_at   TEXT NOT NULL,
+	purge_after  TEXT NOT NULL,
+	reason       TEXT
+);
+CREATE INDEX IF NOT EXISTS artifact_trash_purge_idx ON artifact_trash(purge_after);
+CREATE TABLE IF NOT EXISTS discussion_rounds (
+	id            INTEGER PRIMARY KEY AUTOINCREMENT,
+	discussion_id TEXT NOT NULL REFERENCES artifacts(id),
+	round_number  INTEGER NOT NULL,
+	actor         TEXT NOT NULL,
+	content       TEXT NOT NULL,
+	occurred_at   TEXT NOT NULL,
+	event_schema_version INTEGER NOT NULL DEFAULT 1,
+	UNIQUE (discussion_id, round_number)
+);
+CREATE INDEX IF NOT EXISTS discussion_rounds_discussion_idx ON discussion_rounds(discussion_id, round_number, id);
+CREATE TRIGGER IF NOT EXISTS discussion_rounds_no_update BEFORE UPDATE ON discussion_rounds
+BEGIN SELECT RAISE(ABORT, 'discussion_rounds are append-only'); END;
+CREATE TRIGGER IF NOT EXISTS discussion_rounds_no_delete BEFORE DELETE ON discussion_rounds
+WHEN NOT EXISTS (SELECT 1 FROM artifact_trash WHERE artifact_id = OLD.discussion_id AND purge_after <= strftime('%Y-%m-%dT%H:%M:%fZ','now'))
+BEGIN SELECT RAISE(ABORT, 'discussion_rounds are append-only except during an explicit, elapsed-grace-period artifact trash purge'); END;
 `;
 
 const SEED_SQL = `
@@ -243,7 +268,7 @@ INSERT OR IGNORE INTO relation_names VALUES ('implements','This work satisfies t
 INSERT OR IGNORE INTO relation_names VALUES ('follows','This work obeys that (task→rule, task→skill)');
 INSERT OR IGNORE INTO relation_names VALUES ('depends_on','DAG ordering (task→task)');
 INSERT OR IGNORE INTO relation_names VALUES ('documents','Describes (doc→task, doc→rule, doc→skill)');
-INSERT OR IGNORE INTO relation_names VALUES ('blocks','Blocking relationship (task→task)');
+INSERT OR IGNORE INTO relation_names VALUES ('blocks','Blocking relationship (task→task, or an active Discussion doc→task)');
 INSERT OR IGNORE INTO relation_names VALUES ('supersedes','Replaces (doc→doc, rule→rule)');
 INSERT OR IGNORE INTO relation_names VALUES ('relates_to','Catch-all (any→any)');
 INSERT OR IGNORE INTO relation_names VALUES ('gates','This rule gates that task (rule→task)');
@@ -296,6 +321,8 @@ const CORE_LEDGER_VERSIONS: ReadonlyArray<{ version: number; name: string; check
 	{ version: 3, name: "log-domain", checksum: "c87f43c22b2608619ada9a529d7899ae74b7f38cd554135c8034116fc96e1eff" },
 	{ version: 4, name: "remove-discourse", checksum: "b923f41c44460f0aaeb2f4e60e28f8b8e1425d03f527955bd991434b46de4c82" },
 	{ version: 5, name: "session-identity", checksum: "1c6a165bbe37f82a100fd34762db70c3f8ab15ff20c3a53c2e60448edc815a5e" },
+	{ version: 6, name: "artifact-trash", checksum: "4a75dbec2892deb54bcc1afdf0d51d81f03a8d10861787d083784a29e5c7e8f9" },
+	{ version: 7, name: "discuss-native", checksum: "ab7bdd04824bd93681917807b817d6e08b9825af90161e3ccd6d6663021dc6a0" },
 ];
 
 export function migrationLedger(db: Db): ModuleMigrationRow[] {
@@ -388,8 +415,62 @@ export interface PapyrusMigration {
 	up: (db: Db) => void;
 }
 
-/** Currently empty -- no schema version beyond LEGACY_MIGRATION_CHAIN_TARGET_VERSION exists yet. The next migration is appended here, never as a new branch in the legacy chain above. */
-const FUTURE_MIGRATIONS: ReadonlyArray<PapyrusMigration> = [];
+const FUTURE_MIGRATIONS: ReadonlyArray<PapyrusMigration> = [
+	{
+		version: 14,
+		name: "artifact-trash",
+		// See domain/artifact-trash.ts for the full design rationale. The two trigger bodies here
+		// must match SCHEMA's fresh-bootstrap versions of the same triggers byte-for-byte -- DROP
+		// then CREATE is required since SQLite has no ALTER TRIGGER.
+		up: (db) => {
+			db.exec(`
+				CREATE TABLE IF NOT EXISTS artifact_trash (
+					artifact_id  TEXT PRIMARY KEY REFERENCES artifacts(id),
+					trashed_at   TEXT NOT NULL,
+					purge_after  TEXT NOT NULL,
+					reason       TEXT
+				);
+				CREATE INDEX IF NOT EXISTS artifact_trash_purge_idx ON artifact_trash(purge_after);
+				DROP TRIGGER IF EXISTS task_events_no_delete;
+				CREATE TRIGGER task_events_no_delete BEFORE DELETE ON task_events
+				WHEN NOT EXISTS (SELECT 1 FROM artifact_trash WHERE artifact_id = OLD.task_id AND purge_after <= strftime('%Y-%m-%dT%H:%M:%fZ','now'))
+				BEGIN SELECT RAISE(ABORT, 'task_events are append-only except during an explicit, elapsed-grace-period artifact trash purge'); END;
+				DROP TRIGGER IF EXISTS artifact_events_no_delete;
+				CREATE TRIGGER artifact_events_no_delete BEFORE DELETE ON artifact_events
+				WHEN NOT EXISTS (SELECT 1 FROM artifact_trash WHERE artifact_id = OLD.artifact_id AND purge_after <= strftime('%Y-%m-%dT%H:%M:%fZ','now'))
+				BEGIN SELECT RAISE(ABORT, 'artifact_events are append-only except during an explicit, elapsed-grace-period artifact trash purge'); END;
+			`);
+		},
+	},
+	{
+		version: 15,
+		name: "discuss-native",
+		// See domain/discussion.ts. discussion_rounds mirrors task_events' proven shape (append-only,
+		// with the identical trash-purge trigger carve-out); the blocks relation's description is
+		// widened to reflect that an active Discussion doc can now block a task too.
+		up: (db) => {
+			db.exec(`
+				CREATE TABLE IF NOT EXISTS discussion_rounds (
+					id            INTEGER PRIMARY KEY AUTOINCREMENT,
+					discussion_id TEXT NOT NULL REFERENCES artifacts(id),
+					round_number  INTEGER NOT NULL,
+					actor         TEXT NOT NULL,
+					content       TEXT NOT NULL,
+					occurred_at   TEXT NOT NULL,
+					event_schema_version INTEGER NOT NULL DEFAULT 1,
+					UNIQUE (discussion_id, round_number)
+				);
+				CREATE INDEX IF NOT EXISTS discussion_rounds_discussion_idx ON discussion_rounds(discussion_id, round_number, id);
+				CREATE TRIGGER IF NOT EXISTS discussion_rounds_no_update BEFORE UPDATE ON discussion_rounds
+				BEGIN SELECT RAISE(ABORT, 'discussion_rounds are append-only'); END;
+				CREATE TRIGGER IF NOT EXISTS discussion_rounds_no_delete BEFORE DELETE ON discussion_rounds
+				WHEN NOT EXISTS (SELECT 1 FROM artifact_trash WHERE artifact_id = OLD.discussion_id AND purge_after <= strftime('%Y-%m-%dT%H:%M:%fZ','now'))
+				BEGIN SELECT RAISE(ABORT, 'discussion_rounds are append-only except during an explicit, elapsed-grace-period artifact trash purge'); END;
+				UPDATE relation_names SET description = 'Blocking relationship (task→task, or an active Discussion doc→task)' WHERE name = 'blocks';
+			`);
+		},
+	},
+];
 
 /**
  * Adapts Papyrus's own Db/inTransaction to daemon-kit's storage-agnostic

package/src/discussion-service.ts

@@ -0,0 +1,159 @@
+/**
+ * Discuss: application service composing the Discussion Doc (via ArtifactStore) with its
+ * append-only rounds (via DiscussionRoundStore). See domain/discussion.ts for the full
+ * design rationale.
+ */
+import { DISCUSSION_MAX_ROUNDS } from "./constants.ts";
+import {
+	DISCUSSION_SUBTYPE,
+	isDiscussionArtifact,
+	readDiscussionExtra,
+	validateDeferReason,
+	validateDiscussionActor,
+	validateDiscussionContent,
+	validateSettlement,
+	type DiscussionExtra,
+	type DiscussionRound,
+} from "./domain/discussion.ts";
+import type { Artifact } from "./domain/artifact.ts";
+import type { ArtifactEventContext } from "./domain/artifact-event.ts";
+import type { AtomicArtifactStore } from "./ports/atomic-artifact-store.ts";
+import type { DiscussionRoundStore } from "./ports/discussion-round-store.ts";
+
+export class DiscussionError extends Error {}
+
+export interface OpenDiscussionInput {
+	title: string;
+	actor: string;
+	content: string;
+	body?: string;
+	labels?: string[];
+	blocksTaskIds?: string[];
+	projectRoot?: string;
+}
+
+export interface DiscussionAndRounds {
+	discussion: Artifact;
+	rounds: DiscussionRound[];
+}
+
+function requireDiscussion(artifact: Artifact | null, id: string): Artifact {
+	if (!artifact) throw new DiscussionError(`discussion "${id}" not found`);
+	if (!isDiscussionArtifact(artifact)) throw new DiscussionError(`artifact "${id}" is not a Discussion`);
+	return artifact;
+}
+
+export class Discussions {
+	constructor(
+		private readonly artifacts: AtomicArtifactStore,
+		private readonly rounds: DiscussionRoundStore,
+	) {}
+
+	private extra(discussion: Artifact): DiscussionExtra {
+		return readDiscussionExtra(discussion.extra);
+	}
+
+	open(input: OpenDiscussionInput, context?: ArtifactEventContext): DiscussionAndRounds {
+		const actor = validateDiscussionActor(input.actor);
+		const content = validateDiscussionContent(input.content);
+		return this.artifacts.atomic(() => {
+			const discussion = this.artifacts.create({
+				kind: "doc",
+				subtype: DISCUSSION_SUBTYPE,
+				title: input.title,
+				body: input.body ?? "",
+				status: "active",
+				labels: input.labels,
+				extra: { discussion: { state: "active", roundCount: 1 } },
+			}, context);
+			const round = this.rounds.append({ discussionId: discussion.id, roundNumber: 1, actor, content }, new Date().toISOString());
+			for (const taskId of input.blocksTaskIds ?? []) this.block(discussion.id, taskId, context);
+			return { discussion: this.artifacts.get(discussion.id)!, rounds: [round] };
+		});
+	}
+
+	reply(discussionId: string, actor: string, content: string, context?: ArtifactEventContext): DiscussionAndRounds {
+		const validActor = validateDiscussionActor(actor);
+		const validContent = validateDiscussionContent(content);
+		return this.artifacts.atomic(() => {
+			const discussion = requireDiscussion(this.artifacts.get(discussionId), discussionId);
+			const state = this.extra(discussion);
+			if (state.state !== "active") throw new DiscussionError(`discussion "${discussionId}" is ${state.state}; resume it before replying`);
+			if (state.roundCount >= DISCUSSION_MAX_ROUNDS) throw new DiscussionError(`discussion "${discussionId}" has reached its ${DISCUSSION_MAX_ROUNDS}-round limit; settle or defer it`);
+			const nextRound = state.roundCount + 1;
+			const round = this.rounds.append({ discussionId, roundNumber: nextRound, actor: validActor, content: validContent }, new Date().toISOString());
+			const updated = this.artifacts.setExtra(discussionId, { ...discussion.extra, discussion: { ...state, roundCount: nextRound } }, context)!;
+			return { discussion: updated, rounds: [round] };
+		});
+	}
+
+	defer(discussionId: string, reason?: string, context?: ArtifactEventContext): Artifact {
+		const validReason = reason === undefined ? undefined : validateDeferReason(reason);
+		return this.artifacts.atomic(() => {
+			const discussion = requireDiscussion(this.artifacts.get(discussionId), discussionId);
+			const state = this.extra(discussion);
+			if (state.state !== "active") throw new DiscussionError(`discussion "${discussionId}" is ${state.state}; only an active Discussion can be deferred`);
+			return this.artifacts.setExtra(discussionId, {
+				...discussion.extra,
+				discussion: { ...state, state: "deferred", ...(validReason === undefined ? {} : { deferredReason: validReason }) },
+			}, context)!;
+		});
+	}
+
+	resume(discussionId: string, context?: ArtifactEventContext): Artifact {
+		return this.artifacts.atomic(() => {
+			const discussion = requireDiscussion(this.artifacts.get(discussionId), discussionId);
+			const state = this.extra(discussion);
+			if (state.state !== "deferred") throw new DiscussionError(`discussion "${discussionId}" is ${state.state}; only a deferred Discussion can be resumed`);
+			const { deferredReason: _deferredReason, ...rest } = state;
+			return this.artifacts.setExtra(discussionId, { ...discussion.extra, discussion: { ...rest, state: "active" } }, context)!;
+		});
+	}
+
+	settle(discussionId: string, settlement: string, context?: ArtifactEventContext): Artifact {
+		const validSettlement = validateSettlement(settlement);
+		return this.artifacts.atomic(() => {
+			const discussion = requireDiscussion(this.artifacts.get(discussionId), discussionId);
+			const state = this.extra(discussion);
+			if (state.state === "settled") throw new DiscussionError(`discussion "${discussionId}" is already settled`);
+			const updated = this.artifacts.setExtra(discussionId, {
+				...discussion.extra,
+				discussion: { ...state, state: "settled", settlement: validSettlement, settledAt: new Date().toISOString() },
+			}, context)!;
+			return this.artifacts.setStatus(discussionId, "archived", context) ?? updated;
+		});
+	}
+
+	/** Links an existing active Discussion to a Task it blocks; refuses a non-task target or an already-settled Discussion. */
+	block(discussionId: string, taskId: string, context?: ArtifactEventContext): void {
+		const discussion = requireDiscussion(this.artifacts.get(discussionId), discussionId);
+		if (this.extra(discussion).state === "settled") throw new DiscussionError(`discussion "${discussionId}" is settled; it can no longer block anything`);
+		const task = this.artifacts.get(taskId);
+		if (!task) throw new DiscussionError(`task "${taskId}" not found`);
+		if (task.kind !== "task") throw new DiscussionError(`artifact "${taskId}" is not a task`);
+		this.artifacts.link({ from: discussionId, relation: "blocks", to: taskId }, context);
+	}
+
+	/** Idempotent: unblocking an already-absent relationship is a no-op. */
+	unblock(discussionId: string, taskId: string, context?: ArtifactEventContext): boolean {
+		return this.artifacts.unlink({ from: discussionId, relation: "blocks", to: taskId }, context);
+	}
+
+	show(discussionId: string): DiscussionAndRounds {
+		const discussion = requireDiscussion(this.artifacts.get(discussionId), discussionId);
+		return { discussion, rounds: this.rounds.list({ discussionId }) };
+	}
+
+	listRounds(discussionId: string, afterRound?: number, limit?: number): DiscussionRound[] {
+		requireDiscussion(this.artifacts.get(discussionId), discussionId);
+		return this.rounds.list({ discussionId, afterRound, limit });
+	}
+
+	list(filter: { state?: string; limit?: number } = {}): Artifact[] {
+		const rows = this.artifacts.query({ kind: "doc", subtype: DISCUSSION_SUBTYPE, limit: filter.limit });
+		if (!filter.state) return rows;
+		return rows.filter((row) => {
+			try { return this.extra(row).state === filter.state; } catch { return false; }
+		});
+	}
+}

package/src/domain/artifact-event.ts

@@ -10,7 +10,7 @@
  */
 import { ARTIFACT_EVENT_ACTOR_MAX_LENGTH, ARTIFACT_EVENT_HISTORY_DEFAULT_LIMIT, ARTIFACT_EVENT_HISTORY_MAX_LIMIT } from "../constants.ts";
 
-export const ARTIFACT_EVENT_TYPES = ["created", "updated", "status_changed", "extra_set", "linked", "unlinked"] as const;
+export const ARTIFACT_EVENT_TYPES = ["created", "updated", "status_changed", "extra_set", "linked", "unlinked", "trashed", "restored"] as const;
 export type ArtifactEventType = typeof ARTIFACT_EVENT_TYPES[number];
 export type ArtifactEventDirection = "asc" | "desc";
 

package/src/domain/artifact-trash.ts

@@ -0,0 +1,29 @@
+/**
+ * Artifact trash: Option B from the design discussion (Doc-worthy decision, recorded here
+ * since there is no other durable home for it yet) -- `artifact.remove` is a real, narrow,
+ * time-gated exception to Papyrus's otherwise-absolute append-only invariant, not a mere
+ * status flip.
+ *
+ * The constraint that shaped this design: every artifact gets a mandatory "created" row in
+ * artifact_events at creation time (see ops.ts's createArtifact), and artifact_events is
+ * DB-trigger-enforced immutable (no UPDATE, no DELETE, ever). That means a literal
+ * `DELETE FROM artifacts` can never succeed for ANY artifact while that FK and that trigger
+ * both hold unconditionally -- there is no such thing as an artifact with "no history to
+ * protect". A real purge therefore requires the DB's own append-only triggers to carry an
+ * explicit, narrow carve-out (see db.ts's artifact_events_no_delete / task_events_no_delete),
+ * gated on the exact same elapsed-time deadline recorded here -- enforced by the database
+ * itself, not merely by application-code discipline, so a bug in the purge sweep cannot
+ * delete history before its own stated deadline.
+ *
+ * Removing an artifact does not touch it immediately: it inserts one row here recording when
+ * it becomes eligible, and from that moment the artifact is excluded from ordinary listings
+ * (see ops.ts's queryArtifacts) but still directly reachable by id (get/show) and fully
+ * restorable via artifact.restore, until purgeAfter passes and the daemon's periodic sweep
+ * (see daemon.ts) performs the real, cascading, irreversible deletion.
+ */
+export interface ArtifactTrashRecord {
+	artifactId: string;
+	trashedAt: string;
+	purgeAfter: string;
+	reason?: string;
+}

package/src/domain/artifact.ts

@@ -46,6 +46,8 @@ export interface ArtifactQuery {
 	labels?: string[];
 	extraEquals?: Record<string, string | number | boolean>;
 	limit?: number;
+	/** Trashed artifacts (see artifact-trash.ts) are excluded from every query by default; set true to include them, e.g. for a trash-listing view. */
+	includeTrashed?: boolean;
 }
 
 export interface ArtifactGraphOptions {

package/src/domain/discussion.ts

@@ -0,0 +1,107 @@
+/**
+ * Discuss: a native Papyrus deliberation with a real lifecycle, distinct from a one-shot
+ * "ask" (see the design discussion this implements) and from Discourse's forum (kept fully
+ * standalone by design -- no dependency here, Discuss reuses none of its storage or wire
+ * shape). A Discussion is a `doc` artifact with subtype "discussion": real graph citizenship
+ * (edges, show/list) without a fifth enforced artifact kind. Its fine-grained lifecycle
+ * lives in extra.discussion rather than the shared doc status vocabulary, since Papyrus
+ * enforces status per-kind, not per-subtype -- "deferred" has no equivalent among a plain
+ * doc's draft/active/archived. The doc's own status column follows loosely: "active" while
+ * extra.discussion.state is active or deferred, "archived" once settled.
+ *
+ * Blocking is the forcing, load-bearing behavior a Discussion adds over a passive record:
+ * an "active" Discussion that `blocks` a Task refuses that Task's completion (see
+ * task-service.ts's blockingDiscussions) until the Discussion is settled or deferred.
+ * Deferred is explicitly non-blocking -- "we will get back to this," not "resolved".
+ */
+import {
+	DISCUSSION_ACTOR_MAX_LENGTH,
+	DISCUSSION_DEFER_REASON_MAX_CHARACTERS,
+	DISCUSSION_ROUND_CONTENT_MAX_CHARACTERS,
+	DISCUSSION_SETTLEMENT_MAX_CHARACTERS,
+} from "../constants.ts";
+
+export const DISCUSSION_SUBTYPE = "discussion";
+
+export const DISCUSSION_STATES = ["active", "deferred", "settled"] as const;
+export type DiscussionState = typeof DISCUSSION_STATES[number];
+
+/** Persisted in a discussion Doc's `extra.discussion`. */
+export interface DiscussionExtra {
+	state: DiscussionState;
+	roundCount: number;
+	deferredReason?: string;
+	settlement?: string;
+	settledAt?: string;
+}
+
+/** One append-only round of a Discussion -- opening statement is round 1. */
+export interface DiscussionRound {
+	id: number;
+	discussionId: string;
+	roundNumber: number;
+	actor: string;
+	content: string;
+	occurredAt: string;
+}
+
+export interface AppendDiscussionRound {
+	discussionId: string;
+	roundNumber: number;
+	actor: string;
+	content: string;
+}
+
+export interface DiscussionRoundQuery {
+	discussionId: string;
+	afterRound?: number;
+	limit?: number;
+}
+
+function boundedString(value: string, field: string, maximum: number): string {
+	if (value.length === 0 || value.length > maximum) throw new Error(`${field} must be between 1 and ${maximum} characters`);
+	return value;
+}
+
+export function validateDiscussionContent(content: string): string {
+	return boundedString(content, "content", DISCUSSION_ROUND_CONTENT_MAX_CHARACTERS);
+}
+
+export function validateDiscussionActor(actor: string): string {
+	return boundedString(actor, "actor", DISCUSSION_ACTOR_MAX_LENGTH);
+}
+
+export function validateDeferReason(reason: string): string {
+	return boundedString(reason, "reason", DISCUSSION_DEFER_REASON_MAX_CHARACTERS);
+}
+
+export function validateSettlement(settlement: string): string {
+	return boundedString(settlement, "settlement", DISCUSSION_SETTLEMENT_MAX_CHARACTERS);
+}
+
+/** True for any artifact (already fetched) that is a Discussion, regardless of its current lifecycle state. */
+export function isDiscussionArtifact(artifact: { kind: string; subtype: string }): boolean {
+	return artifact.kind === "doc" && artifact.subtype === DISCUSSION_SUBTYPE;
+}
+
+/** Reads and defensively validates the extra.discussion shape; throws on a corrupt/foreign shape rather than silently treating it as some default state. */
+export function readDiscussionExtra(extra: Record<string, unknown>): DiscussionExtra {
+	const raw = extra["discussion"];
+	if (typeof raw !== "object" || raw === null) throw new Error("artifact is not a Discussion (missing extra.discussion)");
+	const record = raw as Record<string, unknown>;
+	const state = record["state"];
+	if (typeof state !== "string" || !(DISCUSSION_STATES as readonly string[]).includes(state)) {
+		throw new Error(`invalid Discussion state "${String(state)}"`);
+	}
+	const roundCount = record["roundCount"];
+	if (typeof roundCount !== "number" || !Number.isInteger(roundCount) || roundCount < 0) {
+		throw new Error("invalid Discussion roundCount");
+	}
+	return {
+		state: state as DiscussionState,
+		roundCount,
+		...(typeof record["deferredReason"] === "string" ? { deferredReason: record["deferredReason"] } : {}),
+		...(typeof record["settlement"] === "string" ? { settlement: record["settlement"] } : {}),
+		...(typeof record["settledAt"] === "string" ? { settledAt: record["settledAt"] } : {}),
+	};
+}

package/src/modules/discuss.ts

@@ -0,0 +1,87 @@
+/**
+ * modules/discuss.ts — Discuss as a Papyrus-native registered module. See
+ * domain/discussion.ts and discussion-service.ts for the full design.
+ */
+import type { ArtifactEventContext } from "../domain/artifact-event.ts";
+import type { Discussions } from "../discussion-service.ts";
+import type { OperationDefinition } from "../module-registry.ts";
+
+const MODULE_ID = "discuss";
+
+type OperationInput = Record<string, unknown>;
+
+function string(input: OperationInput, key: string): string {
+	const value = input[key];
+	if (typeof value !== "string" || value.length === 0) throw new Error(`${key} is required`);
+	return value;
+}
+
+function optionalString(input: OperationInput, key: string): string | undefined {
+	const value = input[key];
+	if (value === undefined) return undefined;
+	if (typeof value !== "string") throw new Error(`${key} must be a string`);
+	return value;
+}
+
+function optionalStringArray(input: OperationInput, key: string): string[] | undefined {
+	const value = input[key];
+	if (value === undefined) return undefined;
+	if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) throw new Error(`${key} must be an array of strings`);
+	return value as string[];
+}
+
+function optionalNumber(input: OperationInput, key: string): number | undefined {
+	const value = input[key];
+	if (value === undefined) return undefined;
+	if (typeof value !== "number" || !Number.isFinite(value)) throw new Error(`${key} must be a number`);
+	return value;
+}
+
+const eventContext = (input: OperationInput): ArtifactEventContext => ({
+	actor: optionalString(input, "actor"),
+	source: optionalString(input, "source"),
+	sessionId: optionalString(input, "session_id") ?? optionalString(input, "sessionId"),
+});
+
+function taskId(input: OperationInput): string {
+	const value = optionalString(input, "task_id") ?? optionalString(input, "taskId");
+	if (!value) throw new Error("task_id is required");
+	return value;
+}
+
+/** This module's own operation names, the single source of truth src/service.ts's EXPECTED_OPERATION_NAMES spreads in rather than re-listing by hand. */
+export const DISCUSS_OPERATION_NAMES = [
+	"discuss.open", "discuss.reply", "discuss.defer", "discuss.resume", "discuss.settle",
+	"discuss.block", "discuss.unblock", "discuss.show", "discuss.rounds", "discuss.list",
+] as const;
+
+/** Registers every discuss.* operation against one Discussions instance. */
+export function discussOperations(discussions: Discussions): OperationDefinition[] {
+	const define = <Input, Output>(name: string, execute: (input: Input) => Output): OperationDefinition<Input, Output> => ({
+		name, moduleId: MODULE_ID, execute,
+	});
+	return [
+		define("discuss.open", (input: OperationInput) => discussions.open({
+			title: string(input, "title"),
+			actor: string(input, "actor"),
+			content: string(input, "content"),
+			body: optionalString(input, "body"),
+			labels: optionalStringArray(input, "labels"),
+			blocksTaskIds: optionalStringArray(input, "blocks_task_ids") ?? optionalStringArray(input, "blocksTaskIds"),
+		}, eventContext(input))),
+		define("discuss.reply", (input: OperationInput) => discussions.reply(string(input, "id"), string(input, "actor"), string(input, "content"), eventContext(input))),
+		define("discuss.defer", (input: OperationInput) => discussions.defer(string(input, "id"), optionalString(input, "reason"), eventContext(input))),
+		define("discuss.resume", (input: OperationInput) => discussions.resume(string(input, "id"), eventContext(input))),
+		define("discuss.settle", (input: OperationInput) => discussions.settle(string(input, "id"), string(input, "settlement"), eventContext(input))),
+		define("discuss.block", (input: OperationInput) => {
+			discussions.block(string(input, "id"), taskId(input), eventContext(input));
+			return { blocked: true };
+		}),
+		define("discuss.unblock", (input: OperationInput) => ({
+			unblocked: discussions.unblock(string(input, "id"), taskId(input), eventContext(input)),
+		})),
+		define("discuss.show", (input: OperationInput) => discussions.show(string(input, "id"))),
+		define("discuss.rounds", (input: OperationInput) => discussions.listRounds(string(input, "id"), optionalNumber(input, "after_round") ?? optionalNumber(input, "afterRound"), optionalNumber(input, "limit"))),
+		define("discuss.list", (input: OperationInput) => discussions.list({ state: optionalString(input, "state"), limit: optionalNumber(input, "limit") })),
+	];
+}