@khorsheed/dsh-room 0.1.0

package/lib/invariant.js

@@ -0,0 +1,26 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@khorsheed/dsh-room`.
+* @module @khorsheed/dsh-room/invariant
+*/
+const PACKAGE_NAME = "@khorsheed/dsh-room";
+/** Cordis companion plugin name. */
+const name = "room-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* Placeholder (Step 0/1 spike): no runtime invariant yet. The `room/created`
+* marker write passes through Session.append, whose validation rejects any
+* non-JSON payload, and the client contributions ride the slot/locale
+* lifecycles disposed with the plugin fiber. Later steps (roster transition
+* validation, dispatch invariants) install real checks here.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/journal-CuRnWk66.js

@@ -0,0 +1,435 @@
+//#region lib/types/deliveries.js
+/** Accepted delivery intents and their latest durable outcomes. */
+function replayDeliveries(events) {
+	const rows = /* @__PURE__ */ new Map();
+	for (const event of events) if (event.type === "room/dispatch" && event.data.targetIds !== void 0) for (const memberId of event.data.targetIds) {
+		const id = `${event.seq}:${memberId}`;
+		if (!rows.has(id)) rows.set(id, {
+			id,
+			dispatchSeq: event.seq,
+			memberId,
+			status: "queued",
+			text: event.data.text,
+			origin: event.data.origin ?? "human",
+			...event.data.plan === void 0 ? {} : { plan: event.data.plan }
+		});
+	}
+	else if (event.type === "room/delivery-state") {
+		const row = rows.get(event.data.id);
+		if (row === void 0 || row.memberId !== event.data.memberId || row.dispatchSeq !== event.data.dispatchSeq) continue;
+		rows.set(row.id, {
+			...row,
+			status: event.data.state,
+			...event.data.error === void 0 ? {} : { error: event.data.error }
+		});
+	}
+	return [...rows.values()];
+}
+//#endregion
+//#region lib/types/journal.js
+/**
+* Room journal replay: folds the room session's `room/*` custom events into
+* the derived {@link RoomState} — roster, notification relays, the task
+* board, and run states. Pure: the Remote surface reads through it, the
+* dispatch engine reads instruction cursors through it, and the unit tests
+* exercise it without a cordis composition. Reload-replay recovers the exact
+* same state, which is what makes the journal the room's single source of
+* truth. There is NO blackboard fold: member prompts never consume the
+* room's running log (see the design note) — speech/dispatch events are
+* journaled for UI projection and replay only.
+* @module @khorsheed/dsh-room/journal
+*/
+/**
+* The native DSH member's addressing name in new rooms. It starts as the
+* coordinator; bare messages follow the selected coordinator thereafter.
+* Existing journals retain their recorded names, including legacy main.
+*/
+const MAIN_AGENT_MEMBER = "dsh";
+/**
+* Every `room/*` session-event type this package introduces. Room registers
+* them into the harness's KNOWN_SESSION_EVENT_TYPES persistence catalog at
+* apply time (see the RoomService constructor): the catalog's read-path
+* refusal exists so a build that does NOT understand an event type never
+* silently mangles the log — a build with room mounted understands these, so
+* registration is the semantically correct declaration, and a build without
+* room keeps refusing them. The catalog's own header defers a registration
+* surface for out-of-repo plugins "until such a consumer exists"; this
+* in-place add is that surface's temporary form — migrate to the official
+* one when it lands upstream.
+*/
+const ROOM_EVENT_TYPES = [
+	"room/created",
+	"room/plan-state",
+	"room/coordinator",
+	"room/delivery-state",
+	"room/member-added",
+	"room/member-updated",
+	"room/member-removed",
+	"room/dispatch",
+	"room/speech",
+	"room/run-state",
+	"room/relay",
+	"room/relay-resolved",
+	"room/task-added",
+	"room/task-updated",
+	"room/task-edited",
+	"room/goal"
+];
+/** Whether an event log carries the room identity marker. */
+function isRoomLog(events) {
+	return events.some((event) => event.type === "room/created");
+}
+/**
+* Parse the leading `@name` tokens of a raw composer message.
+* @param raw - the raw text.
+* @returns the addressed names (deduped, order-preserving) and the body with
+* the mention prefix stripped. Only LEADING tokens address: an `@name`
+* inside prose is plain text (a bare message goes to the selected coordinator).
+*/
+function parseMentions(raw) {
+	const targets = [];
+	let rest = raw.trim();
+	for (;;) {
+		const match = /^@(\S+)(?:\s+|$)/.exec(rest);
+		if (match === null) break;
+		const name = match[1];
+		if (!targets.includes(name)) targets.push(name);
+		rest = rest.slice(match[0].length).trim();
+	}
+	return {
+		targets,
+		text: rest
+	};
+}
+/**
+* The fallback notification channel: a member reply's TRAILING own line of
+* the form `@name <content>` (the format the roster injection teaches).
+* Only the last line counts — an `@name` inside prose is a mention, not a
+* notification. Leading whitespace on that line is tolerated (models indent
+* under their own bullet/list style). The caller checks the target against
+* the roster.
+* @param text - the member's reply text.
+* @returns the parsed directive, or undefined.
+*/
+function parseRelayDirective(text) {
+	const trimmed = text.trimEnd();
+	if (trimmed === "") return void 0;
+	const last = trimmed.slice(trimmed.lastIndexOf("\n") + 1).trimStart();
+	const match = /^@(\S+)\s+(\S[\s\S]*)$/.exec(last);
+	if (match === null) return void 0;
+	return {
+		to: match[1],
+		content: match[2].trim()
+	};
+}
+/**
+* Fold a session's event log into the room state.
+*
+* Write-side invariants (invite/update/remove validate before appending) are
+* NOT re-enforced here: a replayed log may be hand-edited or forked, so the
+* fold is defensive — a duplicate member-added keeps the first record (first
+* wins, a replay cannot re-seat a member), and updates/removals naming an
+* unknown member are dropped. Unknown event types (e.g. a `room/note` from
+* the dropped blackboard design) fall through the switch and are skipped.
+* Removal also drops the member's run state: the roster reads clean after a
+* remove. Relays and tasks fold by id, latest resolution winning.
+* @param events - the session's event log.
+* @returns the folded room state (empty for a non-room log).
+*/
+function replay(events) {
+	const members = [];
+	const byName = /* @__PURE__ */ new Map();
+	const relays = [];
+	const relayById = /* @__PURE__ */ new Map();
+	const tasks = [];
+	const taskById = /* @__PURE__ */ new Map();
+	const runs = /* @__PURE__ */ new Map();
+	let goal;
+	let coordinator;
+	for (const event of events) switch (event.type) {
+		case "room/coordinator":
+			if (event.data.revision > (coordinator?.revision ?? 0)) coordinator = event.data;
+			break;
+		case "room/member-added": {
+			if (byName.has(event.data.name)) break;
+			const added = {
+				id: event.data.id ?? `legacy:${event.seq}`,
+				name: event.data.name,
+				kind: event.data.kind,
+				invitedBy: event.data.invitedBy,
+				...event.data.provider === void 0 ? {} : { provider: event.data.provider },
+				...event.data.instructions === void 0 ? {} : { instructions: event.data.instructions },
+				...event.data.cwd === void 0 ? {} : { cwd: event.data.cwd },
+				...event.data.model === void 0 ? {} : { model: event.data.model },
+				...event.data.childSessionId === void 0 ? {} : { childSessionId: event.data.childSessionId }
+			};
+			byName.set(added.name, added);
+			members.push(added);
+			break;
+		}
+		case "room/member-updated": {
+			const member = byName.get(event.data.name);
+			if (member === void 0) break;
+			const withoutInstructions = event.data.instructions === null ? (({ instructions: _cleared, ...rest }) => rest)(member) : {
+				...member,
+				...event.data.instructions === void 0 ? {} : { instructions: event.data.instructions }
+			};
+			const withoutCwd = event.data.cwd === null ? (({ cwd: _cleared, ...rest }) => rest)(withoutInstructions) : {
+				...withoutInstructions,
+				...event.data.cwd === void 0 ? {} : { cwd: event.data.cwd }
+			};
+			const patched = {
+				...event.data.model === null ? (({ model: _cleared, ...rest }) => rest)(withoutCwd) : {
+					...withoutCwd,
+					...event.data.model === void 0 ? {} : { model: event.data.model }
+				},
+				...event.data.childSessionId === void 0 ? {} : { childSessionId: event.data.childSessionId }
+			};
+			const rename = event.data.rename;
+			if (rename === void 0 || rename === member.name || byName.has(rename)) {
+				byName.set(member.name, patched);
+				members[members.indexOf(member)] = patched;
+				break;
+			}
+			const renamed = {
+				...patched,
+				name: rename
+			};
+			byName.delete(member.name);
+			byName.set(rename, renamed);
+			members[members.indexOf(member)] = renamed;
+			for (let index = 0; index < tasks.length; index++) {
+				const task = tasks[index];
+				if (task.member !== member.name && task.blockedBy !== member.name) continue;
+				const migrated = {
+					...task,
+					...task.member === member.name ? { member: rename } : {},
+					...task.blockedBy === member.name ? { blockedBy: rename } : {}
+				};
+				taskById.set(migrated.id, migrated);
+				tasks[index] = migrated;
+			}
+			for (let index = 0; index < relays.length; index++) {
+				const relay = relays[index];
+				if (relay.from !== member.name && relay.to !== member.name) continue;
+				const migrated = {
+					...relay,
+					from: relay.from === member.name ? rename : relay.from,
+					to: relay.to === member.name ? rename : relay.to
+				};
+				relayById.set(migrated.id, migrated);
+				relays[index] = migrated;
+			}
+			const run = runs.get(member.name);
+			if (run !== void 0) {
+				runs.delete(member.name);
+				runs.set(rename, {
+					...run,
+					member: rename
+				});
+			}
+			break;
+		}
+		case "room/member-removed": {
+			const member = byName.get(event.data.name);
+			if (member === void 0) break;
+			byName.delete(event.data.name);
+			members.splice(members.indexOf(member), 1);
+			runs.delete(event.data.name);
+			break;
+		}
+		case "room/relay": {
+			if (relayById.has(event.data.id)) break;
+			const relay = {
+				id: event.data.id,
+				from: event.data.from,
+				to: event.data.to,
+				content: event.data.content,
+				state: "pending",
+				...event.data.provenance === void 0 ? {} : { provenance: event.data.provenance }
+			};
+			relayById.set(relay.id, relay);
+			relays.push(relay);
+			break;
+		}
+		case "room/relay-resolved": {
+			const relay = relayById.get(event.data.id);
+			if (relay === void 0) break;
+			const resolved = {
+				...relay,
+				state: event.data.state
+			};
+			relayById.set(resolved.id, resolved);
+			relays[relays.indexOf(relay)] = resolved;
+			break;
+		}
+		case "room/task-added": {
+			if (taskById.has(event.data.id)) break;
+			const task = {
+				id: event.data.id,
+				member: event.data.member,
+				title: event.data.title,
+				...event.data.deliveryId === void 0 ? {} : { deliveryId: event.data.deliveryId },
+				status: event.data.status,
+				...event.data.blockedBy === void 0 ? {} : { blockedBy: event.data.blockedBy },
+				updatedAt: event.time
+			};
+			taskById.set(task.id, task);
+			tasks.push(task);
+			break;
+		}
+		case "room/task-updated": {
+			const task = taskById.get(event.data.id);
+			if (task === void 0) break;
+			const updated = {
+				...task,
+				status: event.data.status,
+				updatedAt: event.time
+			};
+			taskById.set(updated.id, updated);
+			tasks[tasks.indexOf(task)] = updated;
+			break;
+		}
+		case "room/task-edited": {
+			const task = taskById.get(event.data.id);
+			if (task === void 0) break;
+			const edited = {
+				...event.data.blockedBy === null ? (({ blockedBy: _cleared, ...rest }) => rest)(task) : {
+					...task,
+					...event.data.blockedBy === void 0 ? {} : { blockedBy: event.data.blockedBy }
+				},
+				...event.data.title === void 0 ? {} : { title: event.data.title },
+				updatedAt: event.time
+			};
+			taskById.set(edited.id, edited);
+			tasks[tasks.indexOf(task)] = edited;
+			break;
+		}
+		case "room/goal": {
+			const text = event.data.text.trim();
+			goal = text === "" ? void 0 : text;
+			break;
+		}
+		case "room/run-state": {
+			const current = runs.get(event.data.member);
+			if (event.data.state !== "running" && event.data.runId !== void 0 && current?.runId !== void 0 && current.runId !== event.data.runId) break;
+			runs.set(event.data.member, {
+				member: event.data.member,
+				state: event.data.state,
+				startedAt: event.data.startedAt,
+				...event.data.runId === void 0 ? {} : { runId: event.data.runId },
+				...event.data.elapsedMs === void 0 ? {} : { elapsedMs: event.data.elapsedMs },
+				...event.data.error === void 0 ? {} : { error: event.data.error }
+			});
+			break;
+		}
+	}
+	const planEvent = events.filter((event) => event.type === "room/plan-state").at(-1);
+	const plan = planEvent?.type === "room/plan-state" ? (({ requests: _requests, ...view }) => view)(planEvent.data) : void 0;
+	const deliveries = replayDeliveries(events);
+	return {
+		members,
+		relays,
+		tasks,
+		...plan === void 0 ? {} : { plan },
+		...deliveries.length === 0 ? {} : { deliveries },
+		runs: [...runs.values()],
+		...coordinator === void 0 ? {} : { coordinator },
+		...goal === void 0 ? {} : { goal }
+	};
+}
+/**
+* The member's dispatch cursor as of JUST BEFORE a given dispatch event: the
+* latest earlier dispatch naming them. The engine reads the role-instruction
+* carry against this cursor (pass {@link Number.MAX_SAFE_INTEGER} for a
+* dispatch that is not itself journaled, e.g. a relay delivery).
+* @param events - the session's event log.
+* @param member - the dispatch target.
+* @param beforeSeq - the current dispatch event's seq.
+* @returns the previous dispatch seq, or undefined on the member's first dispatch.
+*/
+function previousCursor(events, member, beforeSeq) {
+	let cursor;
+	for (const event of events) {
+		if (event.type !== "room/dispatch" || event.seq >= beforeSeq) continue;
+		if (event.data.targets.includes(member)) cursor = event.seq;
+	}
+	return cursor;
+}
+/**
+* Whether the roster a member was last told about is stale: any roster-visible
+* change with a seq past their dispatch cursor — a member-added or
+* member-removed, or a member-updated that touches what the roster section
+* shows (instructions = the one-line role, rename = the addressing name). A
+* childSessionId/cwd/model-only update is NOT roster-visible (the delegation
+* handle is journaled right after a first run; counting it would re-send the
+* roster on every member's next dispatch for nothing — the model intent never
+* enters any prompt either). A member with no cursor has
+* never seen the roster, so their first dispatch always counts as stale.
+* @param events - the session's event log.
+* @param cursor - the member's pre-dispatch cursor ({@link previousCursor}).
+* @returns true when the next dispatch must carry the roster section.
+*/
+function rosterStaleSince(events, cursor) {
+	if (cursor === void 0) return true;
+	for (const event of events) {
+		if (event.seq <= cursor) continue;
+		if (event.type === "room/member-added" || event.type === "room/member-removed") return true;
+		if (event.type === "room/member-updated" && (event.data.instructions !== void 0 || event.data.rename !== void 0)) return true;
+	}
+	return false;
+}
+/**
+* The role-instructions carry for the next dispatch to a member: 'initial'
+* when the member has never been dispatched (their instructions open the
+* first prompt), 'update' when the latest member-added/member-updated event
+* naming them postdates their dispatch cursor (an edit rides the next
+* dispatch as a context update). Instructions events older than the cursor
+* were already carried.
+* @param events - the session's event log.
+* @param member - the dispatch target.
+* @param cursor - the member's pre-dispatch cursor ({@link previousCursor}).
+* @returns the carry, or undefined when nothing needs carrying.
+*/
+function pendingInstructions(events, member, cursor) {
+	let lastSeq;
+	let lastInstructions;
+	for (const event of events) if (event.type === "room/member-added" && event.data.name === member && event.data.instructions !== void 0) {
+		lastSeq = event.seq;
+		lastInstructions = event.data.instructions;
+	} else if (event.type === "room/member-updated" && event.data.name === member) {
+		if (event.data.instructions === null) {
+			lastSeq = void 0;
+			lastInstructions = void 0;
+		} else if (event.data.instructions !== void 0) {
+			lastSeq = event.seq;
+			lastInstructions = event.data.instructions;
+		}
+	}
+	if (lastSeq === void 0 || lastInstructions === void 0) return void 0;
+	if (cursor === void 0) return {
+		kind: "initial",
+		instructions: lastInstructions
+	};
+	if (lastSeq > cursor) return {
+		kind: "update",
+		instructions: lastInstructions
+	};
+}
+/** Resolve legacy join identity through renames; never key a new dispatch by display name. */
+function memberId(events, member) {
+	if (member.id !== void 0) return member.id;
+	let name = member.name;
+	for (let index = events.length - 1; index >= 0; index--) {
+		const event = events[index];
+		if (event.type === "room/member-updated" && event.data.rename === name) name = event.data.name;
+		if (event.type === "room/member-added" && event.data.name === name) return event.data.id ?? `legacy:${event.seq}`;
+	}
+	throw new Error("Room member has no join identity");
+}
+function coordinatorMember(state, events) {
+	if (state.coordinator === void 0) return state.members.find((member) => member.kind === "main-agent");
+	return state.members.find((member) => (member.id ?? (events === void 0 ? void 0 : memberId(events, member))) === state.coordinator.memberId);
+}
+//#endregion
+export { memberId as a, pendingInstructions as c, rosterStaleSince as d, replayDeliveries as f, isRoomLog as i, previousCursor as l, ROOM_EVENT_TYPES as n, parseMentions as o, coordinatorMember as r, parseRelayDirective as s, MAIN_AGENT_MEMBER as t, replay as u };