@medicine-wheel/app 0.17.10 → 0.18.0

package/README.md

@@ -354,6 +354,48 @@ start, every five minutes, and after any projection that gets through —
 `honcho.pending` counts what waits. A running server holds its old
 build and its old environment — restart it for either to take effect.
 
+### Event log
+
+Every write to a cycle, beat, ceremony, diary entry, node or relation leaves one
+line in `events.jsonl` beside the store (`MW_EVENTS_FILE` overrides). Nodes
+include circles, chronicle episodes and memory conclusions. Captures, inquiry
+weaves, plan perspectives, charts and MMOTs are not recorded yet. Each line is
+a `MiadiEventEnvelope` (jgwill/Miadi
+`rispecs/events/00-miadi-event-spine.rispec.md`) namespaced `medicine-wheel.*`:
+`cycle.opened`, `beat.recorded`, `ceremony.closed`, `circle.created`,
+`chronicle.episode.registered`, `relation.made`, … — 29 in all, catalogued in
+[`@medicine-wheel/events`](src/events/README.md).
+
+- A payload names records and carries labels. A cycle's question, a beat's
+  words and a diary entry's text stay in the store.
+- A write that changes nothing writes no event.
+- A log that cannot be written never fails the write.
+- The MCP server's local store records its own writes the same way.
+
+```bash
+curl 'localhost:8040/api/events?type=cycle.&limit=20'   # newest first; type, subject, correlation, since, limit
+mw events --correlation <cycle-id>                      # a cycle's moments; also on the cycle's page
+mw events schema [--asyncapi]                           # the JSON Schema, or the AsyncAPI document
+```
+
+Set `MW_INSTANCE` (e.g. `ilex:8040`) to name this wheel in each event's
+`source.instance`.
+
+**Publishing.** Nothing leaves the machine until `MW_EVENTS_PUBLISH_URL` is set.
+Once it is, the wheel POSTs each event, in log order, after every write and
+every minute (`MW_EVENTS_PUBLISH_INTERVAL_MS`).
+
+- **Headers:** `Idempotency-Key`, `X-Event-Type`, and `Authorization: Bearer
+  $MW_EVENTS_PUBLISH_TOKEN` when a token is set.
+- **Delivery records:** a cursor and receipts beside the log record
+  `arrived`, `failed` (retried) or `refused` (passed).
+- **Checking and replaying:** `mw events status`, `mw events publish` and
+  `mw events replay <event-id|all>` (also `GET`/`POST /api/events/publish`).
+- **What can receive it:** a webhook endpoint, a Hookdeck source, a Cloudflare
+  Worker in front of a queue, or the Miadi hooks-gateway. A broker client is
+  another publisher beside it. The events keep their names
+  (jgwill/medicine-wheel#164, miadi-chronicle://548).
+
 ## License
 
 Indigenous Knowledge Stewardship License (IKSL) v1.0 MIT Derived   see [LICENSE](LICENSE)

package/app/api/ceremonies/[id]/route.ts

@@ -1,6 +1,8 @@
 import { NextResponse } from "next/server";
 import { createProvider, detectProvider } from "@medicine-wheel/storage-provider";
+import { ceremonyRemoved } from "@medicine-wheel/events";
 import { getAllBeats } from "@/lib/store";
+import { recordEvent } from "@/lib/event-log";
 
 type RouteContext = { params: Promise<{ id: string }> };
 
@@ -52,6 +54,7 @@ export async function DELETE(_request: Request, context: RouteContext) {
       );
     }
     await store.deleteCeremony(id);
+    recordEvent(ceremonyRemoved(ceremony));
     return NextResponse.json({ success: true, deleted: { id }, provider: detectProvider() });
   } catch (error: unknown) {
     const message = error instanceof Error ? error.message : String(error);

package/app/api/ceremonies/route.ts

@@ -4,6 +4,8 @@ import { createProvider, detectProvider } from "@medicine-wheel/storage-provider
 import { ceremonyBelongsToEpisode, ceremonyEpisodePath } from "@/lib/ceremony-response";
 import { projectCeremony } from "@medicine-wheel/honcho";
 import { projectAfterWrite } from "@/lib/honcho-projection";
+import { ceremonyWritten } from "@medicine-wheel/events";
+import { recordEvent } from "@/lib/event-log";
 
 /** Episode directory names are `YYYY-MM-DD-episode-NNN-slug`; nothing else may bind. */
 const EPISODE_PATH = /^\d{4}-\d{2}-\d{2}-episode-\d{3,}-[a-z0-9-]+$/;
@@ -159,10 +161,14 @@ export async function POST(request: Request) {
       ...(typeof body.subject_id === "string" ? { subject_id: body.subject_id } : {}),
     };
 
+    const existed = typeof body.id === "string" && body.id ? await store.getCeremony(body.id) : null;
     await store.logCeremony(ceremony);
     // The river: the stored ceremony leaves for Honcho in the background when
     // HONCHO_URL is set. Never awaited.
     projectAfterWrite({ kind: "ceremony", id: ceremony.id }, () => projectCeremony(ceremony));
+    // The event log (#164). A closing names the ceremony it closes, and both
+    // share that ceremony's id as their correlation.
+    recordEvent(ceremonyWritten(Boolean(existed), ceremony));
     return NextResponse.json({ success: true, ceremony, provider: detectProvider() }, { status: 201 });
   } catch (error: unknown) {
     const message = error instanceof Error ? error.message : String(error);

package/app/api/diary/[id]/route.ts

@@ -1,5 +1,7 @@
 import { NextResponse } from "next/server";
 import { createProvider, detectProvider } from "@medicine-wheel/storage-provider";
+import { diaryRemoved } from "@medicine-wheel/events";
+import { recordEvent } from "@/lib/event-log";
 
 type RouteContext = { params: Promise<{ id: string }> };
 
@@ -23,6 +25,7 @@ export async function DELETE(_request: Request, context: RouteContext) {
     const entry = await store.getDiaryEntry(id);
     if (!entry) return NextResponse.json({ error: `No diary entry with id ${id}` }, { status: 404 });
     await store.deleteDiaryEntry(id);
+    recordEvent(diaryRemoved(entry));
     return NextResponse.json({ success: true, deleted: { id }, provider: detectProvider() });
   } catch (error: unknown) {
     const message = error instanceof Error ? error.message : String(error);

package/app/api/diary/route.ts

@@ -5,6 +5,8 @@ import type { DiaryEntryFilters, DiaryEntryRecord } from "@medicine-wheel/storag
 import { createDiaryEntry } from "@medicine-wheel/ceremonial-diary";
 import { projectDiaryEntry } from "@medicine-wheel/honcho";
 import { projectAfterWrite } from "@/lib/honcho-projection";
+import { diaryWritten } from "@medicine-wheel/events";
+import { recordEvent } from "@/lib/event-log";
 
 /**
  * The ceremonial diary door (0.14.0).
@@ -113,6 +115,7 @@ export async function POST(request: Request) {
       }
       metadata.ceremony_id = body.ceremony_id;
     }
+    const existed = typeof body.id === "string" && body.id ? await store.getDiaryEntry(body.id) : null;
     const entry = await createDiaryEntry(store, {
       ...(typeof body.id === "string" && body.id ? { id: body.id } : {}),
       ...(typeof body.timestamp === "string" && body.timestamp ? { timestamp: body.timestamp } : {}),
@@ -127,6 +130,9 @@ export async function POST(request: Request) {
     // The river: the participant's voice leaves for Honcho in the background
     // when HONCHO_URL is set. Never awaited.
     projectAfterWrite({ kind: "diary", id: entry.id }, () => projectDiaryEntry(entry));
+    // The event log (#164): who wrote, in which phase and ceremony — not what
+    // they wrote, which stays in the diary.
+    recordEvent(diaryWritten(Boolean(existed), entry));
     return NextResponse.json({ success: true, entry, provider: detectProvider() }, { status: 201 });
   } catch (error: unknown) {
     const message = error instanceof Error ? error.message : String(error);

package/app/api/edges/route.ts

@@ -5,7 +5,9 @@ import {
   detectProvider,
   EdgeNotFoundError,
 } from "@medicine-wheel/storage-provider";
+import { relationRemoved, relationWritten } from "@medicine-wheel/events";
 import { parseLimit } from "@/lib/api-paging";
+import { recordEvent } from "@/lib/event-log";
 
 const EdgeCreateSchema = z.object({
   from_id: z.string({ required_error: "from_id is required" }).trim().min(1),
@@ -160,7 +162,8 @@ export async function POST(request: Request) {
       );
     }
 
-    const replaced = Boolean(await store.getEdge(parsed.data.from_id, parsed.data.to_id));
+    const previous = await store.getEdge(parsed.data.from_id, parsed.data.to_id);
+    const replaced = Boolean(previous);
 
     const edge = {
       from_id: parsed.data.from_id,
@@ -174,6 +177,9 @@ export async function POST(request: Request) {
     };
 
     await store.createEdge(edge);
+    // The event log (#164): a relation made, or — over an existing pair —
+    // amended in what moved.
+    recordEvent(relationWritten(previous, edge));
     return NextResponse.json(
       { success: true, edge, replaced, provider: detectProvider() },
       { status: 201 },
@@ -208,7 +214,9 @@ export async function PATCH(request: Request) {
     }
 
     const store = await createProvider();
+    const previous = await store.getEdge(pair.from, pair.to);
     const edge = await store.updateEdge(pair.from, pair.to, parsed.data);
+    recordEvent(relationWritten(previous ?? edge, edge));
     return NextResponse.json({ success: true, edge, provider: detectProvider() });
   } catch (error: unknown) {
     if (error instanceof EdgeNotFoundError) {
@@ -225,7 +233,9 @@ export async function DELETE(request: Request) {
     if (!pair) return pairRequired();
 
     const store = await createProvider();
+    const previous = await store.getEdge(pair.from, pair.to);
     await store.deleteEdge(pair.from, pair.to);
+    recordEvent(relationRemoved(previous ?? { from_id: pair.from, to_id: pair.to }));
     return NextResponse.json({
       success: true,
       deleted: { from_id: pair.from, to_id: pair.to },

package/app/api/events/publish/route.ts

@@ -0,0 +1,42 @@
+import { NextResponse } from "next/server";
+import { eventPublisherReport, publishPending, replayEvents } from "@/lib/event-log";
+
+const NO_PUBLISHER = {
+  error: "No publisher is configured — the events wait in events.jsonl.",
+  hint: "Set MW_EVENTS_PUBLISH_URL (and MW_EVENTS_PUBLISH_TOKEN) and restart the wheel.",
+};
+
+/**
+ * The publisher's side of the log (#164) — episode 548's Send, Receipt,
+ * Failure and Replay.
+ *
+ * GET: where the configured publisher stands (`pending`, the last event it is
+ * done with, the last arrival, the last failure) and its latest receipts.
+ * POST: send what waits now. `{ "replay_from": "<event id>" }` first moves the
+ * cursor back so that event and every later one go out again, with the same
+ * idempotency keys; `{ "replay_from": "all" }` replays the whole log.
+ */
+export async function GET() {
+  const report = eventPublisherReport();
+  if (!report) return NextResponse.json(NO_PUBLISHER, { status: 409 });
+  return NextResponse.json(report);
+}
+
+export async function POST(request: Request) {
+  const body = (await request.json().catch(() => ({}))) as { replay_from?: unknown };
+  let replay: { pending: number } | null = null;
+  if (body?.replay_from !== undefined) {
+    if (typeof body.replay_from !== "string" || !body.replay_from) {
+      return NextResponse.json({ error: 'replay_from must be an event id, or "all"' }, { status: 400 });
+    }
+    try {
+      replay = replayEvents(body.replay_from === "all" ? undefined : body.replay_from);
+    } catch (error: unknown) {
+      return NextResponse.json({ error: error instanceof Error ? error.message : String(error) }, { status: 404 });
+    }
+    if (!replay) return NextResponse.json(NO_PUBLISHER, { status: 409 });
+  }
+  const result = await publishPending();
+  if (!result) return NextResponse.json(NO_PUBLISHER, { status: 409 });
+  return NextResponse.json({ ...(replay ? { replayed: replay.pending } : {}), ...result });
+}

package/app/api/events/route.ts

@@ -0,0 +1,39 @@
+import { NextResponse } from "next/server";
+import { parseLimit } from "@/lib/api-paging";
+import { filterEvents, readEvents } from "@/lib/event-log";
+
+/**
+ * The wheel's event log, read (#164).
+ *
+ * `?type=cycle.opened` (or the namespaced `medicine-wheel.cycle.opened`; a
+ * trailing dot, `cycle.`, takes the family), `?subject=<record id>`,
+ * `?correlation=<id>` (a cycle's events and the beats recorded in it),
+ * `?since=<ISO time>`, `?limit=<n>|all`. Newest first, so the moments a person
+ * is looking for come before the history behind them. `total` counts every
+ * match, so a caller holding a page knows it holds one.
+ */
+export async function GET(request: Request) {
+  try {
+    const url = new URL(request.url);
+    const limit = parseLimit(url.searchParams.get("limit"));
+    if (limit instanceof NextResponse) return limit;
+    const since = url.searchParams.get("since") ?? undefined;
+    if (since !== undefined && Number.isNaN(Date.parse(since))) {
+      return NextResponse.json(
+        { error: `Invalid since: ${since} — nothing was returned.`, hint: "since must be an ISO 8601 time." },
+        { status: 400 },
+      );
+    }
+    const matching = filterEvents(readEvents(), {
+      type: url.searchParams.get("type") ?? undefined,
+      subject: url.searchParams.get("subject") ?? undefined,
+      correlation: url.searchParams.get("correlation") ?? undefined,
+      since,
+    }).reverse();
+    const events = limit === null ? matching : matching.slice(0, limit);
+    return NextResponse.json({ events, total: matching.length });
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    return NextResponse.json({ error: message }, { status: 500 });
+  }
+}

package/app/api/health/route.ts

@@ -1,6 +1,7 @@
 import { NextResponse } from 'next/server';
 import { createProvider, detectProvider } from '@medicine-wheel/storage-provider';
 import { honchoProjectionStatus } from '@/lib/honcho-projection';
+import { eventLogStatus } from '@/lib/event-log';
 
 export async function GET() {
   const providerType = detectProvider();
@@ -31,6 +32,10 @@ export async function GET() {
       // reports enabled projects every stored beat, ceremony and diary entry;
       // `pending` counts those still waiting for Honcho to take them (#147).
       honcho: honchoProjectionStatus(),
+      // The event log (#164): how many events the wheel has written beside its
+      // store, when the last one was, and — with a publisher configured — how
+      // many it still owes. Read them on /api/events.
+      events: eventLogStatus(),
       env: {
         MW_STORAGE_PROVIDER: process.env.MW_STORAGE_PROVIDER || 'not set',
         DATABASE_URL: process.env.DATABASE_URL ? 'configured' : 'not configured',

package/app/api/memory/conclusions/[id]/route.ts

@@ -1,6 +1,8 @@
 import { NextResponse } from 'next/server';
 import { MEMORY_PROJECTION_KIND } from '@medicine-wheel/honcho';
 import { createProvider } from '@medicine-wheel/storage-provider';
+import { conclusionJudged } from '@medicine-wheel/events';
+import { recordEvent } from '@/lib/event-log';
 
 export const dynamic = 'force-dynamic';
 type RouteContext = { params: Promise<{ id: string }> };
@@ -27,6 +29,8 @@ export async function PATCH(request: Request, context: RouteContext) {
     const updated = await store.updateNode(id, {
       metadata: { ...node.metadata, status: body.status, judged_by: by, judged_at: new Date().toISOString() },
     });
+    // The event log (#164): a person confirmed or rejected it.
+    recordEvent(conclusionJudged(node, updated));
     return NextResponse.json({ node: updated }, { headers: { 'cache-control': 'no-store' } });
   } catch (error) {
     return NextResponse.json({ error: error instanceof Error ? error.message : String(error) }, { status: 500 });

package/app/api/memory/conclusions/route.ts

@@ -1,6 +1,8 @@
 import { NextResponse } from 'next/server';
 import { honchoIdFor, memoryProjectionNode, type MemoryProjectionKind, type MemoryProjectionStatus } from '@medicine-wheel/honcho';
 import { createProvider } from '@medicine-wheel/storage-provider';
+import { nodeWritten } from '@medicine-wheel/events';
+import { recordEvent } from '@/lib/event-log';
 
 export const dynamic = 'force-dynamic';
 
@@ -36,7 +38,10 @@ export async function POST(request: Request) {
     });
     node.metadata.about = about;
     const store = await createProvider();
+    const before = await store.getNode(node.id);
     await store.createNode(node as never);
+    // The event log (#164): memory.conclusion.recorded, about its person.
+    recordEvent(nodeWritten(before, node));
     return NextResponse.json({ node }, { status: 201, headers: { 'cache-control': 'no-store' } });
   } catch (error) {
     return NextResponse.json({ error: error instanceof Error ? error.message : String(error) }, { status: 500 });

package/app/api/narrative/beats/[id]/route.ts

@@ -1,6 +1,8 @@
 import { NextResponse } from "next/server";
 import { z } from "zod";
 import { getBeat, witnessBeat } from "@/lib/store";
+import { beatWitnessed } from "@medicine-wheel/events";
+import { recordEvent } from "@/lib/event-log";
 
 type RouteContext = { params: Promise<{ id: string }> };
 
@@ -49,7 +51,11 @@ export async function PATCH(request: Request, context: RouteContext) {
       { status: 400 },
     );
   }
+  const before = getBeat(id);
   const beat = witnessBeat(id, parsed.data);
   if (!beat) return notFound(id);
+  // The event log (#164): a witness added or a speaker named. A name already
+  // witnessing, or the speaker restated, adds nothing and records nothing.
+  recordEvent(beatWitnessed(before, beat));
   return NextResponse.json(beat);
 }

package/app/api/narrative/beats/route.ts

@@ -1,7 +1,9 @@
 import { NextResponse } from "next/server";
-import { getAllBeats, createBeat } from "@/lib/store";
+import { getAllBeats, getBeat, createBeat } from "@/lib/store";
 import { projectBeat } from "@medicine-wheel/honcho";
 import { projectAfterWrite } from "@/lib/honcho-projection";
+import { beatWritten } from "@medicine-wheel/events";
+import { recordEvent } from "@/lib/event-log";
 
 export async function GET() {
   try {
@@ -14,6 +16,7 @@ export async function GET() {
 export async function POST(request: Request) {
   try {
     const body = await request.json();
+    const before = typeof body.id === "string" && body.id ? getBeat(body.id) : undefined;
     // Pass the caller's id and timestamp through when supplied. A client that
     // authored a beat holds its id and will look it up again — minting a fresh
     // one here hands back a beat the caller can never find.
@@ -38,6 +41,11 @@ export async function POST(request: Request) {
     // The river: a stored beat leaves for Honcho in the background when
     // HONCHO_URL is set. Never awaited — the wheel answers on its own clock.
     projectAfterWrite({ kind: "beat", id: beat.id }, () => projectBeat(beat));
+    // The event log (#164): a new beat is recorded; a known one is amended
+    // only in what moved — re-posting a beat as it stands is not an occurrence.
+    // Read back through the same normalization as `before`, so a field the
+    // reader fills in is not mistaken for one the write moved.
+    recordEvent(beatWritten(before, before ? getBeat(beat.id) ?? beat : beat));
     // Warnings ride on the created beat rather than replacing it, so clients
     // that read the beat back by id keep working while advisory findings stop
     // being computed-and-discarded.

package/app/api/narrative/cycles/route.ts

@@ -1,5 +1,8 @@
 import { NextResponse } from "next/server";
 import { getAllCycles, createCycle, upsertCycle } from "@/lib/store";
+import { cycleWritten } from "@medicine-wheel/events";
+import type { ApiMedicineWheelCycle } from "@/lib/cycle-response";
+import { recordEvent } from "@/lib/event-log";
 
 export async function GET() {
   try {
@@ -18,15 +21,19 @@ export async function POST(request: Request) {
     // id here is how archiving and beat-binding duplicated cycles instead of
     // amending them; refusing outright is how a client's own id vanished.
     if (typeof body.id === "string" && body.id.length > 0) {
-      const existed = getAllCycles().some((c) => c.id === body.id);
-      const cycle = upsertCycle(body);
-      return NextResponse.json(cycle, { status: existed ? 200 : 201 });
+      const before: ApiMedicineWheelCycle | undefined = getAllCycles().find((c) => c.id === body.id);
+      const cycle: ApiMedicineWheelCycle = upsertCycle(body);
+      // The event log (#164): opened, archived, or amended in the fields that
+      // moved. Writing back what is already stored is not an occurrence.
+      recordEvent(cycleWritten(before, cycle, Object.keys(body)));
+      return NextResponse.json(cycle, { status: before ? 200 : 201 });
     }
 
     const cycle = createCycle({
       research_question: body.research_question,
       current_direction: body.current_direction,
     });
+    recordEvent(cycleWritten(null, cycle, []));
     return NextResponse.json(cycle, { status: 201 });
   } catch (error: any) {
     return NextResponse.json({ error: error.message }, { status: 500 });

package/app/api/nodes/[id]/route.ts

@@ -7,6 +7,8 @@ import {
   NodeNotFoundError,
   NodeHasRelationsError,
 } from "@medicine-wheel/storage-provider";
+import { nodeRemoved, nodeWritten } from "@medicine-wheel/events";
+import { recordEvent } from "@/lib/event-log";
 
 // `direction: null` releases the node from its direction.
 const NodePatchSchema = z
@@ -82,8 +84,8 @@ export async function PATCH(request: Request, context: RouteContext) {
     // silently drops its siblings breaks that everywhere it is used. A caller
     // that genuinely wants to clear a key now says so with `null`.
     let patch = parsed.data;
+    const existing = await store.getNode(id);
     if (patch.metadata) {
-      const existing = await store.getNode(id);
       if (existing) {
         const merged: Record<string, unknown> = {
           ...(existing.metadata ?? {}),
@@ -99,6 +101,8 @@ export async function PATCH(request: Request, context: RouteContext) {
     }
 
     const node = await store.updateNode(id, patch);
+    // The event log (#164): amended in the fields and metadata keys that moved.
+    recordEvent(nodeWritten(existing, node));
     return NextResponse.json({ success: true, node, provider: detectProvider() });
   } catch (error: unknown) {
     if (error instanceof NodeNotFoundError) return notFound(error.nodeId);
@@ -110,7 +114,9 @@ export async function DELETE(_request: Request, context: RouteContext) {
   try {
     const { id } = await context.params;
     const store = await createProvider();
+    const node = await store.getNode(id);
     await store.deleteNode(id);
+    if (node) recordEvent(nodeRemoved(node));
     return NextResponse.json({ success: true, deleted: id, provider: detectProvider() });
   } catch (error: unknown) {
     if (error instanceof NodeNotFoundError) return notFound(error.nodeId);

package/app/api/nodes/route.ts

@@ -2,7 +2,9 @@ import { NextResponse } from "next/server";
 import { z } from "zod";
 import { DirectionNameSchema, NodeTypeSchema } from "@medicine-wheel/ontology-core";
 import { createProvider, detectProvider } from "@medicine-wheel/storage-provider";
+import { nodeWritten } from "@medicine-wheel/events";
 import { parseLimit } from "@/lib/api-paging";
+import { recordEvent } from "@/lib/event-log";
 
 const NodeCreateSchema = z.object({
   id: z.string().trim().min(1).optional(),
@@ -171,7 +173,11 @@ export async function POST(request: Request) {
       updated_at: new Date().toISOString(),
     };
 
+    const before = parsed.data.id ? await store.getNode(parsed.data.id) : null;
     await store.createNode(node);
+    // The event log (#164): a circle created, an episode registered, a node
+    // created — or, under a known id, amended in what moved.
+    recordEvent(nodeWritten(before, node));
     return NextResponse.json({ success: true, node, provider: detectProvider() }, { status: 201 });
   } catch (error: unknown) {
     const message = error instanceof Error ? error.message : String(error);

package/app/narrative/cycles/page.tsx

@@ -5,6 +5,7 @@ import type { FormEvent } from "react";
 import { type MedicineWheelCycle, type DirectionName } from "@/lib/types";
 import { extractCycles } from "@/lib/cycle-response";
 import { toast } from "sonner";
+import { CycleEvents } from "@/components/cycle-events";
 
 const dirVar = (d: string) => `var(--mw-${d})`;
 const dirInk = (d: string) => `var(--mw-${d}-ink)`;
@@ -138,6 +139,7 @@ export default function CyclesPage() {
                       <p className="font-bold">{cycle.relations_mapped}</p>
                     </div>
                   </div>
+                  <CycleEvents cycleId={cycle.id} />
                   <p className="mt-3 text-xs text-muted-foreground">Cycle ID: {cycle.id}</p>
                 </div>
               )}

package/components/cycle-events.tsx

@@ -0,0 +1,82 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { shortName, type WheelEvent } from "@medicine-wheel/events";
+import { relativeTime, absoluteTime } from "@/lib/format-time";
+
+/**
+ * A cycle's moments, newest first: when it was opened, amended, archived, and
+ * each beat recorded or witnessed in it (#164). Read from `/api/events` by the
+ * cycle's id as correlation. The events carry ids, not words, so a beat's title
+ * is read from the beats the wheel holds.
+ */
+
+/** `chronicle.episode.registered` → "Chronicle episode registered". */
+export function eventLabel(eventType: string): string {
+  const words = shortName(eventType).split(".").join(" ").replace(/_/g, " ");
+  return words.charAt(0).toUpperCase() + words.slice(1);
+}
+
+/** What one line adds beside its label: the beat's title, the fields that moved, the witnesses added. */
+export function eventDetail(event: WheelEvent, beatTitles: Record<string, string>): string {
+  const payload = event.payload as Record<string, unknown>;
+  const parts: string[] = [];
+  if (event.subject.kind === "beat" && beatTitles[event.subject.id]) parts.push(`“${beatTitles[event.subject.id]}”`);
+  if (Array.isArray(payload.changed) && payload.changed.length) parts.push(`changed ${payload.changed.join(", ")}`);
+  if (Array.isArray(payload.added_witnesses) && payload.added_witnesses.length) {
+    parts.push(`${payload.added_witnesses.length} witness${payload.added_witnesses.length === 1 ? "" : "es"} added`);
+  }
+  if (typeof payload.speaker === "string" && event.event_type.endsWith("witnessed")) parts.push(`speaker ${payload.speaker}`);
+  if (typeof payload.current_direction === "string" && event.event_type.endsWith("cycle.opened")) parts.push(`in the ${payload.current_direction}`);
+  return parts.join(" · ");
+}
+
+export function CycleEvents({ cycleId }: { cycleId: string }) {
+  const [events, setEvents] = useState<WheelEvent[] | null>(null);
+  const [total, setTotal] = useState(0);
+  const [beatTitles, setBeatTitles] = useState<Record<string, string>>({});
+
+  useEffect(() => {
+    let live = true;
+    fetch(`/api/events?correlation=${encodeURIComponent(cycleId)}&limit=50`)
+      .then((r) => r.json())
+      .then((d) => {
+        if (!live) return;
+        setEvents(Array.isArray(d.events) ? d.events : []);
+        setTotal(typeof d.total === "number" ? d.total : 0);
+      })
+      .catch(() => live && setEvents([]));
+    fetch("/api/narrative/beats")
+      .then((r) => r.json())
+      .then((d) => {
+        if (!live || !Array.isArray(d)) return;
+        setBeatTitles(Object.fromEntries(d.map((b: { id: string; title: string }) => [b.id, b.title])));
+      })
+      .catch(() => {});
+    return () => { live = false; };
+  }, [cycleId]);
+
+  return (
+    <div className="mt-4" onClick={(e) => e.stopPropagation()}>
+      <p className="text-xs font-medium text-muted-foreground mb-2">
+        Moments {events && total > events.length ? `(${events.length} of ${total})` : ""}
+      </p>
+      {events === null && <p className="text-xs text-muted-foreground">Reading the event log…</p>}
+      {events?.length === 0 && (
+        <p className="text-xs text-muted-foreground">No events yet. This wheel records them from the moment the event log was installed; earlier moments were not kept.</p>
+      )}
+      {!!events?.length && (
+        <ol className="space-y-1.5 border-l pl-3">
+          {events.map((event) => (
+            <li key={event.id} className="text-xs">
+              <span className="text-muted-foreground" title={absoluteTime(event.observed_at)}>{relativeTime(event.observed_at)}</span>
+              {" · "}
+              <span className="font-medium">{eventLabel(event.event_type)}</span>
+              {eventDetail(event, beatTitles) && <span className="text-muted-foreground"> · {eventDetail(event, beatTitles)}</span>}
+            </li>
+          ))}
+        </ol>
+      )}
+    </div>
+  );
+}

package/components/episode-file-tree.tsx

@@ -0,0 +1,67 @@
+/**
+ * The folders of an episode, drawn — every one open to begin with, so a file's
+ * folder is plain to see. Presentational: the panel owns which folders are
+ * closed and how a file's own row looks.
+ *
+ * @see lib/episode-file-tree.ts — how the paths are grouped and in what order
+ */
+
+import type { ReactNode } from "react";
+import type { FileTreeFolder, TreeableFile } from "@/lib/episode-file-tree";
+
+export interface EpisodeFileTreeProps<T extends TreeableFile> {
+  tree: FileTreeFolder<T>;
+  /** Paths of the folders the reader closed. Any folder not here is open. */
+  collapsed: ReadonlySet<string>;
+  onToggleFolder: (path: string) => void;
+  /** One file's row, and whatever opens beneath it. `name` is the path's last segment. */
+  renderFile: (file: T, name: string) => ReactNode;
+}
+
+export function EpisodeFileTree<T extends TreeableFile>({
+  tree,
+  collapsed,
+  onToggleFolder,
+  renderFile,
+}: EpisodeFileTreeProps<T>) {
+  return (
+    <ul className="space-y-1">
+      {tree.children.map((node) => {
+        if (node.type === "file") {
+          return <li key={node.path}>{renderFile(node.file, node.name)}</li>;
+        }
+        const isOpen = !collapsed.has(node.path);
+        return (
+          <li key={node.path} data-folder={node.path}>
+            <button
+              type="button"
+              onClick={() => onToggleFolder(node.path)}
+              aria-expanded={isOpen}
+              title={node.path}
+              className="w-full p-2 flex items-baseline gap-2 text-left text-sm font-semibold hover:underline"
+            >
+              <span aria-hidden="true" className="text-muted-foreground w-[1ch]">
+                {isOpen ? "▾" : "▸"}
+              </span>
+              <span aria-hidden="true">{isOpen ? "📂" : "📁"}</span>
+              <span className="font-mono break-all">{node.name}</span>
+              <span className="ml-auto text-xs font-normal text-muted-foreground shrink-0">
+                {node.fileCount} {node.fileCount === 1 ? "file" : "files"}
+              </span>
+            </button>
+            {isOpen && (
+              <div className="ml-4 pl-2 border-l">
+                <EpisodeFileTree
+                  tree={node}
+                  collapsed={collapsed}
+                  onToggleFolder={onToggleFolder}
+                  renderFile={renderFile}
+                />
+              </div>
+            )}
+          </li>
+        );
+      })}
+    </ul>
+  );
+}