@medicine-wheel/app 0.14.3 → 0.15.0

package/README.md

@@ -34,6 +34,7 @@ storage alongside its composable libraries.
     ├── @medicine-wheel/data-store-postgres  ← PostgreSQL / Neon provider scaffold
     ├── @medicine-wheel/storage-provider     ← Canonical persistence contract (JSONL ⇄ Neon)
     ├── @medicine-wheel/infra                ← Hosts, tenants, services, port bindings as facets
+    ├── @medicine-wheel/honcho               ← The wheel's projection into Honcho, memory that reasons
     ├── @medicine-wheel/perception-layer     ← Witness recordings as typed perceptual events
     ├── @medicine-wheel/narrative-cluster    ← Events → clusters → beats → Film Edit Brief
     ├── @medicine-wheel/ceremonial-diary     ← A participant's voice across the Five Phases
@@ -156,6 +157,11 @@ Typed infrastructure facets — hosts, tenants, services and port bindings — k
 
 - **Dependencies:** `@medicine-wheel/ontology-core`, `zod`
 
+### [@medicine-wheel/honcho](src/honcho)
+The wheel's projection into [Honcho](https://honcho.dev), memory that reasons. The wheel stays canonical; Honcho holds what the history has come to mean about each peer. A beat becomes a message from its speaker in the session of its ceremony, a speaker's evolving representation is recalled before they speak again, and a derived conclusion returns as a `knowledge` node carrying `metadata.kind: "memory_projection"` with its status and provenance. Zero dependencies, `/v3` only, configured by `HONCHO_URL`. Nothing is filtered here.
+
+- **Dependencies:** `@medicine-wheel/ontology-core`
+
 ### [@medicine-wheel/perception-layer](src/perception-layer)
 Eyes and ears of agent-supported film production — witness a belt-device recording as typed perceptual events and seed a production knowledge graph.
 

package/app/api/ceremonies/route.ts

@@ -2,6 +2,8 @@ import { NextResponse } from "next/server";
 import { parseLimit } from "@/lib/api-paging";
 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";
 
 /** 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-]+$/;
@@ -139,6 +141,9 @@ export async function POST(request: Request) {
     };
 
     await store.logCeremony(ceremony);
+    // The river: the stored ceremony leaves for Honcho in the background when
+    // HONCHO_URL is set. Never awaited.
+    projectAfterWrite(() => projectCeremony(ceremony), `ceremony ${ceremony.id}`);
     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/route.ts

@@ -3,6 +3,8 @@ import { parseLimit } from "@/lib/api-paging";
 import { createProvider, detectProvider } from "@medicine-wheel/storage-provider";
 import type { DiaryEntryFilters, DiaryEntryRecord } from "@medicine-wheel/storage-provider";
 import { createDiaryEntry } from "@medicine-wheel/ceremonial-diary";
+import { projectDiaryEntry } from "@medicine-wheel/honcho";
+import { projectAfterWrite } from "@/lib/honcho-projection";
 
 /**
  * The ceremonial diary door (0.14.0).
@@ -122,6 +124,9 @@ export async function POST(request: Request) {
       ...(typeof body.agent === "string" && body.agent ? { agent: body.agent } : {}),
       ...(typeof body.chronicle === "string" && body.chronicle ? { chronicle: body.chronicle } : {}),
     });
+    // The river: the participant's voice leaves for Honcho in the background
+    // when HONCHO_URL is set. Never awaited.
+    projectAfterWrite(() => projectDiaryEntry(entry), `diary entry ${entry.id}`);
     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/health/route.ts

@@ -1,5 +1,6 @@
 import { NextResponse } from 'next/server';
 import { createProvider, detectProvider } from '@medicine-wheel/storage-provider';
+import { honchoProjectionStatus } from '@/lib/honcho-projection';
 
 export async function GET() {
   const providerType = detectProvider();
@@ -26,6 +27,9 @@ export async function GET() {
         nodes,
         ceremonies,
       },
+      // The river to Honcho: enabled when HONCHO_URL is set. A wheel that
+      // reports enabled projects every stored beat, ceremony and diary entry.
+      honcho: honchoProjectionStatus(),
       env: {
         MW_STORAGE_PROVIDER: process.env.MW_STORAGE_PROVIDER || 'not set',
         DATABASE_URL: process.env.DATABASE_URL ? 'configured' : 'not configured',

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

@@ -1,5 +1,7 @@
 import { NextResponse } from "next/server";
 import { getAllBeats, createBeat } from "@/lib/store";
+import { projectBeat } from "@medicine-wheel/honcho";
+import { projectAfterWrite } from "@/lib/honcho-projection";
 
 export async function GET() {
   try {
@@ -33,6 +35,9 @@ export async function POST(request: Request) {
       speaker: body.speaker,
       witnesses: Array.isArray(body.witnesses) ? body.witnesses : undefined,
     });
+    // 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(() => projectBeat(beat), `beat ${beat.id}`);
     // 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/docker-entrypoint.sh

@@ -8,6 +8,10 @@ set -e
 #   MW_DATA_DIR          — path to JSONL store directory (default: /data/store)
 #   MW_STORAGE_PROVIDER  — storage backend (default: jsonl)
 #   PORT                 — HTTP port (default: 8040)
+#   HONCHO_URL           — when set, every stored beat, ceremony and diary entry
+#                          is projected into Honcho (memory that reasons);
+#                          HONCHO_WORKSPACE_ID (default medicine-wheel),
+#                          HONCHO_API_KEY (unset while Honcho's auth is off)
 
 STORE_DIR="${MW_DATA_DIR:-/data/store}"
 PORT="${PORT:-8040}"
@@ -17,6 +21,11 @@ mkdir -p "$STORE_DIR"
 echo "🌿 Medicine Wheel"
 echo "📁 Store: $STORE_DIR"
 echo "🌐 http://localhost:$PORT"
+if [ -n "${HONCHO_URL:-}" ]; then
+  echo "🧠 Honcho: $HONCHO_URL (workspace ${HONCHO_WORKSPACE_ID:-medicine-wheel})"
+else
+  echo "🧠 Honcho: off (set HONCHO_URL to project the wheel into memory)"
+fi
 echo ""
 
 export MW_DATA_DIR="$STORE_DIR"

package/lib/honcho-projection.ts

@@ -0,0 +1,72 @@
+/**
+ * Automatic projection — the wheel pushes to Honcho on write.
+ *
+ * `@medicine-wheel/honcho` is the door; this is the river. Every write route
+ * that lands a beat, a ceremony or a diary entry calls {@link projectAfterWrite}
+ * once the record is stored. With `HONCHO_URL` set the record leaves for Honcho
+ * in the background; unset, nothing happens and nothing is logged. Either way
+ * the wheel's own answer to its caller is unchanged: a projection never delays
+ * a response and never turns a stored record into an error.
+ *
+ * A failure is reported once on stderr with the record's id, because a silent
+ * memory is worse than a noisy one. `awaitProjections()` exists for tests and
+ * for anything that must know the river has run dry before it exits.
+ */
+
+import {
+  createHonchoClient,
+  honchoFromEnv,
+  project,
+  type HonchoClient,
+  type HonchoConfig,
+  type Projection,
+} from '@medicine-wheel/honcho';
+
+const inFlight = new Set<Promise<unknown>>();
+
+let cached: { key: string; client: HonchoClient } | null = null;
+
+function clientFor(cfg: HonchoConfig): HonchoClient {
+  const key = `${cfg.baseUrl}|${cfg.workspace}|${cfg.apiKey ?? ''}`;
+  if (cached?.key !== key) cached = { key, client: createHonchoClient(cfg) };
+  return cached.client;
+}
+
+/** What `/api/health` reports: whether the river runs, and where to. */
+export function honchoProjectionStatus(): { enabled: boolean; url?: string; workspace?: string } {
+  const cfg = honchoFromEnv();
+  return cfg ? { enabled: true, url: cfg.baseUrl, workspace: cfg.workspace } : { enabled: false };
+}
+
+/**
+ * Fire-and-forget. Returns immediately; the projection runs in the background.
+ * `label` names the record in the one line written when Honcho refuses or is
+ * unreachable.
+ *
+ * The projection is built by `shape`, called *inside* the error boundary. It
+ * used to be built by the caller, in the route's own expression — so a record
+ * the projection could not shape (a `learnings` that arrived as a string, say)
+ * threw synchronously and turned an already-stored write into a 500 for the
+ * writer. The wheel's answer to its caller must not depend on the river, and
+ * that includes the part that reads the record.
+ */
+export function projectAfterWrite(shape: () => Projection, label: string): void {
+  const cfg = honchoFromEnv();
+  if (!cfg) return;
+  const run = Promise.resolve()
+    .then(() => project(clientFor(cfg), shape()))
+    .catch((error: unknown) => {
+      const err = error as { message?: string; status?: number; body?: string };
+      console.error(
+        `[honcho] projection of ${label} into ${cfg.workspace}@${cfg.baseUrl} failed: ${err?.message ?? String(error)}` +
+          (err?.body ? ` — ${err.body}` : ''),
+      );
+    })
+    .finally(() => { inFlight.delete(run); });
+  inFlight.add(run);
+}
+
+/** Resolves once every projection started so far has settled. */
+export async function awaitProjections(): Promise<void> {
+  while (inFlight.size) await Promise.allSettled([...inFlight]);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@medicine-wheel/app",
-  "version": "0.14.3",
+  "version": "0.15.0",
   "description": "Medicine Wheel — Interactive visual layer for Indigenous relational research with Four Directions, ceremonies, and narrative arcs",
   "bin": {
     "mw": "dist/cli/mw.js",
@@ -32,6 +32,7 @@
     "src/ceremony-protocol",
     "src/storage-provider",
     "src/client",
+    "src/honcho",
     "src/data-store",
     "src/data-store-postgres",
     "src/graph-viz",
@@ -88,29 +89,30 @@
     "release:major": "npm run version:major && npm run publish:all && npm run release:commit"
   },
   "dependencies": {
-    "@medicine-wheel/ceremonial-diary": "^0.14.3",
-    "@medicine-wheel/ceremony-protocol": "^0.14.3",
-    "@medicine-wheel/community-review": "^0.14.3",
-    "@medicine-wheel/consent-lifecycle": "^0.14.3",
-    "@medicine-wheel/creative-orientation": "^0.14.3",
-    "@medicine-wheel/data-store": "^0.14.3",
-    "@medicine-wheel/data-store-postgres": "^0.14.3",
-    "@medicine-wheel/fire-keeper": "^0.14.3",
-    "@medicine-wheel/github-ceremony": "^0.14.3",
-    "@medicine-wheel/graph-viz": "^0.14.3",
-    "@medicine-wheel/importance-unit": "^0.14.3",
-    "@medicine-wheel/mcp": "^4.14.3",
-    "@medicine-wheel/narrative-cluster": "^0.14.3",
-    "@medicine-wheel/narrative-engine": "^0.14.3",
-    "@medicine-wheel/ontology-core": "^0.14.3",
-    "@medicine-wheel/perception-layer": "^0.14.3",
-    "@medicine-wheel/prompt-decomposition": "^0.14.3",
-    "@medicine-wheel/relational-index": "^0.14.3",
-    "@medicine-wheel/relational-query": "^0.14.3",
-    "@medicine-wheel/session-reader": "^0.14.3",
-    "@medicine-wheel/storage-provider": "^0.14.3",
-    "@medicine-wheel/transformation-tracker": "^0.14.3",
-    "@medicine-wheel/ui-components": "^0.14.3",
+    "@medicine-wheel/ceremonial-diary": "^0.15.0",
+    "@medicine-wheel/ceremony-protocol": "^0.15.0",
+    "@medicine-wheel/community-review": "^0.15.0",
+    "@medicine-wheel/consent-lifecycle": "^0.15.0",
+    "@medicine-wheel/creative-orientation": "^0.15.0",
+    "@medicine-wheel/data-store": "^0.15.0",
+    "@medicine-wheel/data-store-postgres": "^0.15.0",
+    "@medicine-wheel/fire-keeper": "^0.15.0",
+    "@medicine-wheel/github-ceremony": "^0.15.0",
+    "@medicine-wheel/graph-viz": "^0.15.0",
+    "@medicine-wheel/honcho": "^0.15.0",
+    "@medicine-wheel/importance-unit": "^0.15.0",
+    "@medicine-wheel/mcp": "^4.15.0",
+    "@medicine-wheel/narrative-cluster": "^0.15.0",
+    "@medicine-wheel/narrative-engine": "^0.15.0",
+    "@medicine-wheel/ontology-core": "^0.15.0",
+    "@medicine-wheel/perception-layer": "^0.15.0",
+    "@medicine-wheel/prompt-decomposition": "^0.15.0",
+    "@medicine-wheel/relational-index": "^0.15.0",
+    "@medicine-wheel/relational-query": "^0.15.0",
+    "@medicine-wheel/session-reader": "^0.15.0",
+    "@medicine-wheel/storage-provider": "^0.15.0",
+    "@medicine-wheel/transformation-tracker": "^0.15.0",
+    "@medicine-wheel/ui-components": "^0.15.0",
     "@neondatabase/serverless": "^0.10.0",
     "@xyflow/react": "^12.3.0",
     "clsx": "^2.1.1",