@medicine-wheel/app 0.18.0 → 0.19.0

package/README.md

@@ -363,7 +363,7 @@ 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
+`chronicle.episode.registered`, `chronicle.lineage.made`, `relation.made`, … — 32 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
@@ -381,6 +381,16 @@ mw events schema [--asyncapi]                           # the JSON Schema, or th
 Set `MW_INSTANCE` (e.g. `ilex:8040`) to name this wheel in each event's
 `source.instance`.
 
+**Carried by git.** Set `MW_EVENTS_GIT_SYNC=push` and the wheel commits
+`events.jsonl` (that file only) in its data repository and pushes it. It never
+pushes someone else's commit. A follower elsewhere runs
+`mw-events follow <clone> --exec <command>` and handles each event it has not
+seen yet. See the [package README](src/events/README.md#carried-by-git).
+
+Two chronicle episodes related through the Miadi lineage door (`POST /api/edges`
+between two `chronicle_episode` nodes) produce `chronicle.lineage.made`, which
+carries the manifest's sentence that says why.
+
 **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`).

package/app/api/edges/route.ts

@@ -178,8 +178,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));
+    // amended in what moved. Between two chronicle episodes it is lineage,
+    // and carries the sentence that says why.
+    recordEvent(relationWritten(previous, edge, { from: fromNode, to: toNode }));
     return NextResponse.json(
       { success: true, edge, replaced, provider: detectProvider() },
       { status: 201 },
@@ -216,7 +217,8 @@ 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));
+    const [fromNode, toNode] = await Promise.all([store.getNode(pair.from), store.getNode(pair.to)]);
+    recordEvent(relationWritten(previous ?? edge, edge, { from: fromNode, to: toNode }));
     return NextResponse.json({ success: true, edge, provider: detectProvider() });
   } catch (error: unknown) {
     if (error instanceof EdgeNotFoundError) {
@@ -234,8 +236,9 @@ export async function DELETE(request: Request) {
 
     const store = await createProvider();
     const previous = await store.getEdge(pair.from, pair.to);
+    const [fromNode, toNode] = await Promise.all([store.getNode(pair.from), store.getNode(pair.to)]);
     await store.deleteEdge(pair.from, pair.to);
-    recordEvent(relationRemoved(previous ?? { from_id: pair.from, to_id: pair.to }));
+    recordEvent(relationRemoved(previous ?? { from_id: pair.from, to_id: pair.to }, { from: fromNode, to: toNode }));
     return NextResponse.json({
       success: true,
       deleted: { from_id: pair.from, to_id: pair.to },

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

@@ -0,0 +1,23 @@
+import { NextResponse } from "next/server";
+import { eventGitStatus, gitSyncMode, syncEventsToGit } from "@/lib/event-log";
+
+const OFF = {
+  error: "The git carriage is off — events.jsonl is not committed by the wheel.",
+  hint: "Set MW_EVENTS_GIT_SYNC=push (or commit) and restart the wheel.",
+};
+
+/**
+ * The event log carried by git (#164). GET: the mode and the last pass —
+ * what was committed, whether it was pushed, how many commits the remote
+ * still lacks, the last error. POST: commit (and push) now.
+ */
+export async function GET() {
+  if (gitSyncMode() === "off") return NextResponse.json(OFF, { status: 409 });
+  return NextResponse.json(eventGitStatus());
+}
+
+export async function POST() {
+  if (gitSyncMode() === "off") return NextResponse.json(OFF, { status: 409 });
+  const result = await syncEventsToGit();
+  return NextResponse.json(result, { status: result?.error ? 502 : 200 });
+}

package/dist/cli/mw.js

@@ -308,6 +308,7 @@ ${C.bold}🌿 mw — Medicine Wheel CLI${C.reset}
     mw events status                       What the publisher still owes
     mw events publish                      Send what waits now
     mw events replay <event-id|all>        Send again from that event
+    mw events sync                         Commit (and push) events.jsonl now
     mw events schema [--asyncapi]          Print the JSON Schema (or AsyncAPI)
 
   SYSTEM
@@ -842,11 +843,18 @@ async function cmdEvents(positional, flags) {
                 process.exitCode = 1;
             break;
         }
+        case 'sync': {
+            const { status, data } = await eventsApi('POST', '/api/events/git');
+            if (status !== 200)
+                return failed(status, data);
+            ppValue(data);
+            break;
+        }
         case 'schema':
             console.log(JSON.stringify(flags['asyncapi'] ? (0, events_1.asyncApiDocument)() : (0, events_1.wheelEventsJsonSchema)(), null, 2));
             break;
         default:
-            unknownSub('events', sub, ['list', 'status', 'publish', 'replay', 'schema']);
+            unknownSub('events', sub, ['list', 'status', 'publish', 'replay', 'sync', 'schema']);
     }
 }
 // ── Main dispatch ─────────────────────────────────────────────────

package/instrumentation.ts

@@ -8,11 +8,16 @@
  * Starts the event publisher's clock (#164): events in `events.jsonl` that the
  * configured publisher has not taken are sent on start and every minute after.
  * With `MW_EVENTS_PUBLISH_URL` unset this does nothing.
+ *
+ * Starts the event log's git carriage (#164): with `MW_EVENTS_GIT_SYNC` set,
+ * `events.jsonl` is committed in its data repository (and pushed) on start
+ * and every ten minutes, besides soon after each recorded event.
  */
 export async function register() {
   if (process.env.NEXT_RUNTIME !== "nodejs") return;
   const { startPendingRetries } = await import("@/lib/honcho-projection");
   startPendingRetries();
-  const { startEventPublishing } = await import("@/lib/event-log");
+  const { startEventPublishing, startEventGitSync } = await import("@/lib/event-log");
   startEventPublishing();
+  startEventGitSync();
 }

package/lib/event-log.ts

@@ -19,9 +19,16 @@
  * `MW_EVENTS_PUBLISH_INTERVAL_MS` (default one minute), from this wheel's
  * cursor, with receipts beside the log. Unset, nothing leaves the machine.
  *
+ * Carried by git, before any broker: with `MW_EVENTS_GIT_SYNC=push` (or
+ * `commit`), the wheel commits `events.jsonl` — that file only — in the data
+ * repository it lives in, about half a minute after events are recorded
+ * (`MW_EVENTS_GIT_DELAY_MS`), on start, and every ten minutes
+ * (`MW_EVENTS_GIT_INTERVAL_MS`), then pushes. A follower elsewhere pulls a
+ * clone and acts on what it has not seen (`mw-events follow`).
+ *
  * Never the caller's error: a line that cannot be written is reported once on
- * stderr with the record's id, and a publisher that cannot be reached is a
- * receipt, not a failed write.
+ * stderr with the record's id, and a publisher or a remote that cannot be
+ * reached is a receipt or a status, not a failed write.
  */
 
 import { buildEvent, filterEvents, type EventFilter, type WheelEvent, type WheelEventInput } from '@medicine-wheel/events';
@@ -37,6 +44,7 @@ import {
   type PublisherStatus,
   type Receipt,
 } from '@medicine-wheel/events/publish';
+import { commitEventLog, type CommitResult } from '@medicine-wheel/events/git';
 import { resolveProjectDataDir } from '@/lib/jsonl-store';
 
 /** Where the log lives: `MW_EVENTS_FILE`, else beside the wheel's JSONL store. */
@@ -68,6 +76,7 @@ export function recordEvent(input: WheelEventInput | null): WheelEvent | undefin
     return undefined;
   }
   kickPublisher();
+  kickGitSync();
   return event;
 }
 
@@ -170,8 +179,90 @@ export function eventPublisherReport(limit = 20): { publisher: PublisherStatus;
   return { publisher: publisherStatus(file, publisher.name), receipts: readReceipts(file, publisher.name).slice(-limit).reverse() };
 }
 
-/** What `/api/health` reports: how many events, the last one, and what the publisher still owes. */
-export function eventLogStatus(): { count: number; last_at?: string; publisher?: PublisherStatus } | { error: string } {
+// ── carried by git ──────────────────────────────────────────────────────────
+
+export type GitSyncMode = 'off' | 'commit' | 'push';
+
+/** `MW_EVENTS_GIT_SYNC`: `push` (or `1`, `true`), `commit`, else off. */
+export function gitSyncMode(): GitSyncMode {
+  const value = process.env.MW_EVENTS_GIT_SYNC?.trim().toLowerCase();
+  if (value === 'push' || value === '1' || value === 'true') return 'push';
+  if (value === 'commit') return 'commit';
+  return 'off';
+}
+
+const GIT = Symbol.for('@medicine-wheel/app.event-git');
+type GitState = {
+  running?: Promise<CommitResult | null>;
+  again?: boolean;
+  timer?: ReturnType<typeof setTimeout>;
+  interval?: ReturnType<typeof setInterval>;
+  failing?: boolean;
+  last?: CommitResult & { at: string };
+};
+const gitState: GitState = ((globalThis as Record<symbol, GitState>)[GIT] ??= {});
+
+async function gitPass(): Promise<CommitResult | null> {
+  const mode = gitSyncMode();
+  if (mode === 'off') return null;
+  const result = await commitEventLog(eventLogFile(), { push: mode === 'push', instance: eventInstance() });
+  gitState.last = { ...result, at: new Date().toISOString() };
+  if (result.error && !gitState.failing) {
+    console.error(`[events] git carriage stopped: ${result.error} — the log keeps growing and the next pass tries again`);
+  } else if (!result.error && gitState.failing) {
+    console.log('[events] git carriage resumed');
+  }
+  if (result.committed) {
+    console.log(`[events] committed ${result.events} event(s) in ${result.commit?.slice(0, 8)}${result.pushed ? ', pushed' : ''}`);
+  }
+  gitState.failing = Boolean(result.error);
+  return result;
+}
+
+/** Commit (and push) the log now. A pass already running is joined, and runs once more after it. */
+export function syncEventsToGit(): Promise<CommitResult | null> {
+  if (gitState.running) {
+    gitState.again = true;
+    return gitState.running;
+  }
+  const run = gitPass().then(async (result) => {
+    while (gitState.again) {
+      gitState.again = false;
+      result = (await gitPass()) ?? result;
+    }
+    return result;
+  }).finally(() => {
+    if (gitState.running === run) gitState.running = undefined;
+  });
+  gitState.running = run;
+  return run;
+}
+
+/** After a recorded event: commit soon, so a burst of writes travels as one commit. */
+export function kickGitSync(): void {
+  if (gitSyncMode() === 'off' || gitState.timer) return;
+  gitState.timer = setTimeout(() => {
+    gitState.timer = undefined;
+    void syncEventsToGit();
+  }, Number(process.env.MW_EVENTS_GIT_DELAY_MS) || 30_000);
+  gitState.timer.unref?.();
+}
+
+/** Start the carriage clock from `instrumentation.ts`: a pass now, then every ten minutes. */
+export function startEventGitSync(intervalMs = Number(process.env.MW_EVENTS_GIT_INTERVAL_MS) || 10 * 60_000): void {
+  if (gitSyncMode() === 'off' || gitState.interval) return;
+  gitState.interval = setInterval(() => { void syncEventsToGit(); }, intervalMs);
+  gitState.interval.unref?.();
+  void syncEventsToGit();
+}
+
+/** The carriage's mode and its last pass. */
+export function eventGitStatus(): { mode: GitSyncMode; last?: GitState['last'] } {
+  return { mode: gitSyncMode(), ...(gitState.last ? { last: gitState.last } : {}) };
+}
+
+/** What `/api/health` reports: how many events, the last one, what the publisher owes, how the git carriage stands. */
+export function eventLogStatus(): { count: number; last_at?: string; publisher?: PublisherStatus; git?: ReturnType<typeof eventGitStatus> } | { error: string } {
   try {
     const events = readEvents();
     const last = events[events.length - 1];
@@ -180,6 +271,7 @@ export function eventLogStatus(): { count: number; last_at?: string; publisher?:
       count: events.length,
       ...(last ? { last_at: last.observed_at } : {}),
       ...(publisher ? { publisher: publisherStatus(eventLogFile(), publisher.name) } : {}),
+      ...(gitSyncMode() !== 'off' ? { git: eventGitStatus() } : {}),
     };
   } catch (error) {
     return { error: (error as Error)?.message ?? String(error) };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@medicine-wheel/app",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Medicine Wheel — Interactive visual layer for Indigenous relational research with Four Directions, ceremonies, and narrative arcs",
   "bin": {
     "mw": "dist/cli/mw.js",
@@ -92,33 +92,33 @@
     "release:major": "npm run version:major && npm run publish:all && npm run release:commit"
   },
   "dependencies": {
-    "@medicine-wheel/ceremonial-diary": "^0.18.0",
-    "@medicine-wheel/ceremony-protocol": "^0.18.0",
-    "@medicine-wheel/community-identity": "^0.18.0",
-    "@medicine-wheel/community-review": "^0.18.0",
-    "@medicine-wheel/consent-lifecycle": "^0.18.0",
-    "@medicine-wheel/creative-orientation": "^0.18.0",
-    "@medicine-wheel/data-store": "^0.18.0",
-    "@medicine-wheel/data-store-postgres": "^0.18.0",
-    "@medicine-wheel/events": "^0.18.0",
-    "@medicine-wheel/fire-keeper": "^0.18.0",
-    "@medicine-wheel/github-ceremony": "^0.18.0",
-    "@medicine-wheel/graph-viz": "^0.18.0",
-    "@medicine-wheel/honcho": "^0.18.0",
-    "@medicine-wheel/importance-unit": "^0.18.0",
-    "@medicine-wheel/mcp": "^4.18.0",
-    "@medicine-wheel/memory": "^0.18.0",
-    "@medicine-wheel/narrative-cluster": "^0.18.0",
-    "@medicine-wheel/narrative-engine": "^0.18.0",
-    "@medicine-wheel/ontology-core": "^0.18.0",
-    "@medicine-wheel/perception-layer": "^0.18.0",
-    "@medicine-wheel/prompt-decomposition": "^0.18.0",
-    "@medicine-wheel/relational-index": "^0.18.0",
-    "@medicine-wheel/relational-query": "^0.18.0",
-    "@medicine-wheel/session-reader": "^0.18.0",
-    "@medicine-wheel/storage-provider": "^0.18.0",
-    "@medicine-wheel/transformation-tracker": "^0.18.0",
-    "@medicine-wheel/ui-components": "^0.18.0",
+    "@medicine-wheel/ceremonial-diary": "^0.19.0",
+    "@medicine-wheel/ceremony-protocol": "^0.19.0",
+    "@medicine-wheel/community-identity": "^0.19.0",
+    "@medicine-wheel/community-review": "^0.19.0",
+    "@medicine-wheel/consent-lifecycle": "^0.19.0",
+    "@medicine-wheel/creative-orientation": "^0.19.0",
+    "@medicine-wheel/data-store": "^0.19.0",
+    "@medicine-wheel/data-store-postgres": "^0.19.0",
+    "@medicine-wheel/events": "^0.19.0",
+    "@medicine-wheel/fire-keeper": "^0.19.0",
+    "@medicine-wheel/github-ceremony": "^0.19.0",
+    "@medicine-wheel/graph-viz": "^0.19.0",
+    "@medicine-wheel/honcho": "^0.19.0",
+    "@medicine-wheel/importance-unit": "^0.19.0",
+    "@medicine-wheel/mcp": "^4.19.0",
+    "@medicine-wheel/memory": "^0.19.0",
+    "@medicine-wheel/narrative-cluster": "^0.19.0",
+    "@medicine-wheel/narrative-engine": "^0.19.0",
+    "@medicine-wheel/ontology-core": "^0.19.0",
+    "@medicine-wheel/perception-layer": "^0.19.0",
+    "@medicine-wheel/prompt-decomposition": "^0.19.0",
+    "@medicine-wheel/relational-index": "^0.19.0",
+    "@medicine-wheel/relational-query": "^0.19.0",
+    "@medicine-wheel/session-reader": "^0.19.0",
+    "@medicine-wheel/storage-provider": "^0.19.0",
+    "@medicine-wheel/transformation-tracker": "^0.19.0",
+    "@medicine-wheel/ui-components": "^0.19.0",
     "@miadi/episode-vessel": "^0.2.1",
     "@neondatabase/serverless": "^0.10.0",
     "@xyflow/react": "^12.3.0",