@medicine-wheel/app 0.5.1 → 0.5.3

package/ALPHA.md

@@ -0,0 +1,59 @@
+# This suite is experimental alpha
+
+**Read this before depending on anything here.**
+
+The Medicine Wheel Developer Suite is under active development and is published
+in the open so the work can be examined, discussed, and improved. It is not
+finished software. Publishing early is deliberate — but so is telling you what
+you are installing.
+
+## What that means concretely
+
+- **APIs change between patch versions.** All packages move in lockstep, so a
+  bump you would normally read as "nothing changed for me" may still change
+  what you depend on. Pin exact versions.
+- **Packages appear, and their boundaries move.** Three packages were added in
+  `0.5.3`. Where a responsibility lives is still being decided.
+- **Some packages are intentionally small first cuts.** They express an
+  intention with a working minimum rather than a finished surface. Their
+  READMEs say so where it applies.
+- **Storage shapes are still settling.** Records written by one version may
+  need repair by a later one. Do not treat any store here as an archive of
+  record yet.
+- **Test coverage is real but uneven.** 210 tests pass at `0.5.3`; that is a
+  floor, not a claim of completeness.
+
+## What it does *not* mean
+
+It does not mean the work is careless. Defects found are fixed and written
+down, specifications are versioned alongside the code in `rispecs/`, and
+sessions are chronicled. The alpha label is about **stability of contract**,
+not about standard of care.
+
+## Cultural material
+
+Parts of this suite encode Indigenous relational research methodology —
+Four Directions structure, ceremony protocol, OCAP® compliance surfaces,
+relational accountability. That material is included because the software is
+*for* that way of working, not as decoration.
+
+If you are building on those parts, please read them as an invitation to work
+relationally rather than as a finished implementation of anyone's protocol.
+Where a design question is properly a knowledge holder's decision rather than
+an engineer's, the specs try to say so. Where we have got that wrong, telling
+us is a contribution.
+
+## If you are evaluating this
+
+The most useful things to read first:
+
+- `rispecs/` — the specifications, versioned with the code
+- `README.md` — what the suite is
+- Open issues — where the known edges are, stated plainly
+
+Feedback is genuinely wanted at this stage, including "this boundary is wrong"
+and "this should not be software".
+
+## License
+
+MIT — see `LICENSE`.

package/Dockerfile

@@ -6,7 +6,7 @@
 #   mwsrv --docker -D /path/to/project
 #
 # Manual usage:
-#   docker run --rm -p 3940:3940 \
+#   docker run --rm -p 8040:8040 \
 #     -v /path/to/project/.mw/store:/data/store \
 #     -e MW_DATA_DIR=/data/store \
 #     jgwill/medicine-wheel:app
@@ -41,7 +41,7 @@ FROM node:22-alpine AS runner
 WORKDIR /app
 
 ENV NODE_ENV=production
-ENV PORT=3940
+ENV PORT=8040
 ENV MW_STORAGE_PROVIDER=jsonl
 ENV MW_DATA_DIR=/data/store
 
@@ -63,6 +63,6 @@ RUN chmod +x /usr/local/bin/docker-entrypoint.sh
 # Volume for persistent data
 VOLUME ["/data/store"]
 
-EXPOSE 3940
+EXPOSE 8040
 
 ENTRYPOINT ["/usr/local/bin/docker-entrypoint.sh"]

package/README.md

@@ -2,6 +2,12 @@
 
 > A first experimental TypeScript framework for relational healing, ceremonial inquiry, and Indigenous-aligned software development — grounded in the Four Directions, Wilson's three R's (Respect, Reciprocity, Responsibility), and OCAP® data sovereignty principles.
 
+> [!WARNING]
+> **Experimental alpha.** APIs change between patch versions, packages appear and
+> their boundaries move, and storage shapes are still settling. Published in the
+> open so the work can be examined and improved — pin exact versions, and read
+> [ALPHA.md](./ALPHA.md) before depending on any of it.
+
 ## NEWS
 
 * Full postgres (neon) data provider !

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

@@ -12,15 +12,24 @@ export async function GET() {
 export async function POST(request: Request) {
   try {
     const body = await request.json();
+    // 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.
     const beat = createBeat({
+      id: body.id,
+      timestamp: body.timestamp,
       direction: body.direction,
       title: body.title,
       description: body.description,
       prose: body.prose,
       ceremonies: body.ceremonies ?? [],
       learnings: body.learnings ?? [],
-      act: body.act ?? 1,
+      act: body.act,
       relations_honored: body.relations_honored ?? [],
+      cycle_id: body.cycle_id,
+      parent_beat_id: body.parent_beat_id,
+      sub_beats: body.sub_beats,
+      origin: body.origin,
     });
     return NextResponse.json(beat, { status: 201 });
   } catch (error: any) {

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

@@ -1,5 +1,5 @@
 import { NextResponse } from "next/server";
-import { getAllCycles, createCycle } from "@/lib/store";
+import { getAllCycles, createCycle, upsertCycle } from "@/lib/store";
 
 export async function GET() {
   try {
@@ -12,6 +12,17 @@ export async function GET() {
 export async function POST(request: Request) {
   try {
     const body = await request.json();
+
+    // A body carrying an id names the cycle the caller already holds — amend
+    // it if we know it, open it under that id if we do not. Minting a fresh
+    // 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 cycle = createCycle({
       research_question: body.research_question,
       current_direction: body.current_direction,

package/dist/cli/mw.js

@@ -47,7 +47,7 @@ const path = __importStar(require("path"));
 const fs = __importStar(require("fs"));
 const skills_1 = require("./skills");
 // ── Config ────────────────────────────────────────────────────────
-const MW_API_URL = process.env.MW_API_URL ?? 'http://localhost:3940';
+const MW_API_URL = process.env.MW_API_URL ?? 'http://localhost:8040';
 const MW_FORMAT = process.env.MW_FORMAT ?? 'pretty';
 function resolvePackageRoot() {
     try {
@@ -268,7 +268,7 @@ ${C.bold}🌿 mw — Medicine Wheel CLI${C.reset}
     mw help                                This help
 
   ENVIRONMENT
-    MW_API_URL   API base URL (default: http://localhost:3940)
+    MW_API_URL   API base URL (default: http://localhost:8040)
     MW_MCP_PATH  Optional MCP server path (auto-detected when locally available)
     MW_FORMAT    Output format: pretty (default), json, quiet
 `);

package/dist/cli/mwsrv.js

@@ -10,7 +10,7 @@
  *   mwsrv --docker -D /path/to/project
  *
  * Options:
- *   --port, -p <port>        Port to listen on (default: 3940)
+ *   --port, -p <port>        Port to listen on (default: 8040)
  *   --directory, -D <dir>    Host directory containing (or for) .mw/store (default: cwd)
  *   --docker                 Run in Docker container
  *   --pull                   Pull Docker image before starting
@@ -63,8 +63,8 @@ const C = {
     south: '\x1b[31m',
     reset: '\x1b[0m',
 };
-const DEFAULT_PORT = 3940;
-const CONTAINER_PORT = 3940;
+const DEFAULT_PORT = 8040;
+const CONTAINER_PORT = 8040;
 function parseArgs(argv) {
     const args = argv.slice(2);
     const flags = {};

package/docker-build-push.sh

@@ -12,4 +12,4 @@ docker push "${IMAGE}"
 
 echo "✅ Done: ${IMAGE}"
 echo "Run with:"
-echo "  docker run --rm -p 3940:3940 -v /abs/path/to/project/.mw/store:/data/store ${IMAGE}"
+echo "  docker run --rm -p 8040:8040 -v /abs/path/to/project/.mw/store:/data/store ${IMAGE}"

package/docker-entrypoint.sh

@@ -7,10 +7,10 @@ set -e
 # Environment variables:
 #   MW_DATA_DIR          — path to JSONL store directory (default: /data/store)
 #   MW_STORAGE_PROVIDER  — storage backend (default: jsonl)
-#   PORT                 — HTTP port (default: 3940)
+#   PORT                 — HTTP port (default: 8040)
 
 STORE_DIR="${MW_DATA_DIR:-/data/store}"
-PORT="${PORT:-3940}"
+PORT="${PORT:-8040}"
 
 mkdir -p "$STORE_DIR"
 

package/lib/beat-response.ts

@@ -0,0 +1,58 @@
+import type { DirectionName, NarrativeBeat } from "./types";
+
+interface BeatListResponse {
+  beats?: unknown;
+}
+
+const DIRECTION_NAMES = new Set<DirectionName>(["east", "south", "west", "north"]);
+
+function asStringArray(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.filter((entry): entry is string => typeof entry === "string")
+    : [];
+}
+
+/**
+ * Repair one stored beat into a shape the arc readers can render.
+ *
+ * Unlike the cycle normalizer this keeps every field it was handed instead of
+ * rebuilding from a whitelist: beats carry additive provenance (origin,
+ * sub_beats, parent_beat_id, act) and a whitelist would silently drop whatever
+ * the narrative engine adds after this file was written. Only the fields a
+ * reader indexes into are coerced — a beat recorded before `learnings` and
+ * `relations_honored` existed takes down a page that reads `.length` on them,
+ * and one with no `direction` is looked up as a colour key that does not exist.
+ */
+export function normalizeNarrativeBeat(value: unknown): NarrativeBeat | null {
+  if (!value || typeof value !== "object") return null;
+
+  const beat = value as Record<string, unknown>;
+  if (typeof beat.id !== "string") return null;
+
+  return {
+    ...(beat as unknown as NarrativeBeat),
+    id: beat.id,
+    direction:
+      typeof beat.direction === "string" &&
+      DIRECTION_NAMES.has(beat.direction as DirectionName)
+        ? (beat.direction as DirectionName)
+        : "east",
+    ceremonies: asStringArray(beat.ceremonies),
+    learnings: asStringArray(beat.learnings),
+    relations_honored: asStringArray(beat.relations_honored),
+    timestamp:
+      typeof beat.timestamp === "string" ? beat.timestamp : new Date(0).toISOString(),
+  };
+}
+
+export function extractBeats(response: unknown): NarrativeBeat[] {
+  const candidate = Array.isArray(response)
+    ? response
+    : response && typeof response === "object" && Array.isArray((response as BeatListResponse).beats)
+      ? ((response as BeatListResponse).beats as unknown[])
+      : [];
+
+  return candidate
+    .map(normalizeNarrativeBeat)
+    .filter((beat): beat is NarrativeBeat => beat !== null);
+}

package/lib/ceremony-response.ts

@@ -1,16 +1,63 @@
-import type { CeremonyLog } from "@/lib/types";
+import type { CeremonyLog, CeremonyType, DirectionName } from "@/lib/types";
 
 interface CeremonyListResponse {
   ceremonies?: unknown;
 }
 
-export function extractCeremonyLogs(response: unknown): CeremonyLog[] {
-  if (Array.isArray(response)) return response as CeremonyLog[];
-
-  if (!response || typeof response !== "object") return [];
+const DIRECTION_NAMES = new Set<DirectionName>(["east", "south", "west", "north"]);
 
-  const candidate = response as CeremonyListResponse;
-  return Array.isArray(candidate.ceremonies)
-    ? (candidate.ceremonies as CeremonyLog[])
+function asStringArray(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.filter((entry): entry is string => typeof entry === "string")
     : [];
 }
+
+/**
+ * Repair one stored ceremony into a shape the timeline can render.
+ *
+ * Returns null only when the record carries no identity — a ceremony with no
+ * id or type cannot be opened, filtered, or spoken about. Everything else is
+ * filled in: the timeline reads `.length` on participants, medicines, and
+ * intentions, and sorts on `timestamp`, so a ceremony logged before any of
+ * those fields existed takes the whole page down rather than rendering thin.
+ */
+export function normalizeCeremonyLog(value: unknown): CeremonyLog | null {
+  if (!value || typeof value !== "object") return null;
+
+  const ceremony = value as Record<string, unknown>;
+  if (typeof ceremony.id !== "string" || typeof ceremony.type !== "string") {
+    return null;
+  }
+
+  return {
+    id: ceremony.id,
+    type: ceremony.type as CeremonyType,
+    direction:
+      typeof ceremony.direction === "string" &&
+      DIRECTION_NAMES.has(ceremony.direction as DirectionName)
+        ? (ceremony.direction as DirectionName)
+        : "east",
+    participants: asStringArray(ceremony.participants),
+    medicines_used: asStringArray(ceremony.medicines_used),
+    intentions: asStringArray(ceremony.intentions),
+    timestamp:
+      typeof ceremony.timestamp === "string"
+        ? ceremony.timestamp
+        : new Date(0).toISOString(),
+    ...(typeof ceremony.research_context === "string"
+      ? { research_context: ceremony.research_context }
+      : {}),
+  };
+}
+
+export function extractCeremonyLogs(response: unknown): CeremonyLog[] {
+  const candidate = Array.isArray(response)
+    ? response
+    : response && typeof response === "object" && Array.isArray((response as CeremonyListResponse).ceremonies)
+      ? ((response as CeremonyListResponse).ceremonies as unknown[])
+      : [];
+
+  return candidate
+    .map(normalizeCeremonyLog)
+    .filter((ceremony): ceremony is CeremonyLog => ceremony !== null);
+}

package/lib/jsonl-store.ts

@@ -67,6 +67,10 @@ interface StoredBeat {
   timestamp: string;
   act: number;
   relations_honored: string[];
+  cycle_id?: string;
+  parent_beat_id?: string;
+  sub_beats?: string[];
+  origin?: { producer: string; source_ref?: string; method?: string };
 }
 
 interface StoredCycle {
@@ -114,28 +118,81 @@ interface StoredMmot {
 // Inside the lock, flush performs read-modify-write so concurrent
 // writers merge rather than clobber each other.
 
+function isProcessAlive(pid: number): boolean {
+  try {
+    // Signal 0 checks process existence without sending a real signal.
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Read the owner token stamped in a lock file, or null when unreadable. */
+function readLockOwner(lockPath: string): string | null {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(lockPath, 'utf-8').trim()) as { token?: unknown };
+    return typeof parsed.token === 'string' ? parsed.token : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * A lock is stale only when its owner is provably gone.
+ *
+ * Age alone is not evidence: a slow but living writer holding the lock past
+ * the grace period would have it reaped from under it, and two processes
+ * would then rewrite the same file from divergent snapshots — the second
+ * rename silently discards the first one's records.
+ */
+function isLockStale(lockPath: string): boolean {
+  let mtimeMs: number;
+  try {
+    mtimeMs = fs.statSync(lockPath).mtimeMs;
+  } catch {
+    return false; // Lock already gone — nothing to reap.
+  }
+
+  try {
+    const parsed = JSON.parse(fs.readFileSync(lockPath, 'utf-8').trim()) as { pid?: unknown };
+    if (typeof parsed.pid === 'number' && isProcessAlive(parsed.pid)) return false;
+  } catch {
+    // Locks written by older builds (and by the mcp/ copy of this store) carry
+    // no payload, so they name no owner — fall through to the age check.
+  }
+
+  return Date.now() - mtimeMs > 30_000;
+}
+
 function withWriteLock<T>(filePath: string, fn: () => T): T {
   const lockPath = filePath + '.lock';
+  const ownerToken = `${process.pid}:${Date.now()}:${Math.random().toString(36).slice(2)}`;
+  const payload = JSON.stringify({
+    token: ownerToken,
+    pid: process.pid,
+    created_at: new Date().toISOString(),
+  });
   let locked = false;
 
-  // Stale lock recovery: if a previous process crashed while holding the lock,
-  // the .lock file persists forever. Remove it if older than 30 seconds.
-  try {
-    const stat = fs.statSync(lockPath);
-    if (Date.now() - stat.mtimeMs > 30_000) {
-      console.error(`[jsonl-store] Removing stale lock: ${lockPath} (age: ${Math.round((Date.now() - stat.mtimeMs) / 1000)}s)`);
-      fs.unlinkSync(lockPath);
-    }
-  } catch { /* lock file doesn't exist — normal */ }
-
   for (let attempt = 0; attempt < 20; attempt++) {
     try {
       const fd = fs.openSync(lockPath, 'wx'); // O_EXCL — fails if exists
-      fs.closeSync(fd);
+      try {
+        fs.writeFileSync(fd, payload, 'utf-8');
+      } finally {
+        fs.closeSync(fd);
+      }
       locked = true;
       break;
     } catch {
-      // Lock held by another process; spin-wait with linear back-off
+      // Lock held elsewhere. Reap it only once its owner is provably gone,
+      // otherwise spin-wait with linear back-off.
+      if (isLockStale(lockPath)) {
+        console.error(`[jsonl-store] Removing stale lock: ${lockPath}`);
+        try { fs.unlinkSync(lockPath); } catch { /* another writer got there first */ }
+        continue;
+      }
       const delayMs = Math.min(25 * (attempt + 1), 250);
       const deadline = Date.now() + delayMs;
       while (Date.now() < deadline) { /* spin */ }
@@ -149,20 +206,25 @@ function withWriteLock<T>(filePath: string, fn: () => T): T {
   try {
     return fn();
   } finally {
-    try { fs.unlinkSync(lockPath); } catch { /* best effort */ }
+    // Release only the lock we still hold: if a reaper judged us dead and
+    // handed the lock on, unlinking would release someone else's write.
+    try {
+      if (readLockOwner(lockPath) === ownerToken) fs.unlinkSync(lockPath);
+    } catch { /* best effort */ }
   }
 }
 
 // ── JSONL File Helpers ──
 
 /**
- * Read all records from a JSONL file.
- * Returns [] if the file does not exist (normal for first run).
+ * Read all records from a JSONL file, keeping the raw text of any line that
+ * would not parse so a caller about to rewrite the file can set it aside.
+ * Returns no records if the file does not exist (normal for first run).
  * Throws on permission errors or other real FS failures so the caller
  * knows not to proceed with a potentially-stale empty state.
  */
-function readJsonl<T>(filePath: string): T[] {
-  if (!fs.existsSync(filePath)) return [];
+function readJsonlWithMalformed<T>(filePath: string): { records: T[]; malformed: string[] } {
+  if (!fs.existsSync(filePath)) return { records: [], malformed: [] };
 
   let content: string;
   try {
@@ -173,6 +235,7 @@ function readJsonl<T>(filePath: string): T[] {
   }
 
   const records: T[] = [];
+  const malformed: string[] = [];
   for (const line of content.split('\n')) {
     const trimmed = line.trim();
     if (!trimmed) continue;
@@ -182,9 +245,37 @@ function readJsonl<T>(filePath: string): T[] {
       // Skip individual malformed lines — log so they don't disappear silently
       const message = error instanceof Error ? error.message : String(error);
       console.warn(`[jsonl-store] Skipping malformed line in ${filePath}: ${message}`);
+      malformed.push(trimmed);
     }
   }
-  return records;
+  return { records, malformed };
+}
+
+function readJsonl<T>(filePath: string): T[] {
+  return readJsonlWithMalformed<T>(filePath).records;
+}
+
+/**
+ * Set unparseable lines aside before a rewrite erases them.
+ *
+ * flush() rebuilds the whole file from the records it could parse, so a line
+ * readJsonl skipped — a half-written record from a killed writer, a truncated
+ * tail — is gone for good the moment anything else is saved. Appending the raw
+ * text to a sidecar keeps it recoverable by hand. Nothing reads the sidecar
+ * back; it exists so the loss is not silent.
+ */
+function quarantineMalformedLines(filePath: string, malformed: string[]): void {
+  if (malformed.length === 0) return;
+
+  const quarantinePath = `${filePath}.quarantine`;
+  try {
+    fs.appendFileSync(quarantinePath, malformed.join('\n') + '\n', 'utf-8');
+    console.error(`[jsonl-store] Quarantined ${malformed.length} unparseable line(s) from ${filePath} to ${quarantinePath}`);
+  } catch (error) {
+    // Best effort — a failed sidecar must not block the write itself.
+    const message = error instanceof Error ? error.message : String(error);
+    console.warn(`[jsonl-store] Failed to quarantine malformed lines from ${filePath}: ${message}`);
+  }
 }
 
 /**
@@ -249,7 +340,8 @@ class JsonlCollection<T extends { id?: string }> {
   private flush(): void {
     withWriteLock(this.filePath, () => {
       // Read disk state inside the lock so we don't clobber concurrent writes
-      const diskRecords = readJsonl<T>(this.filePath);
+      const { records: diskRecords, malformed } = readJsonlWithMalformed<T>(this.filePath);
+      quarantineMalformedLines(this.filePath, malformed);
       const merged = new Map<string, T>();
       for (const r of diskRecords) {
         const id = (r as any).id as string | undefined;
@@ -326,8 +418,11 @@ class EdgeCollection {
   }
 
   private edgeKey(edge: StoredEdge): string {
-    // Use explicit id if present, otherwise derive from endpoints
-    return (edge as any).id || `${edge.from_id}:${edge.to_id}`;
+    // JSON-array encoding of the endpoints, matching @medicine-wheel/storage-provider.
+    // A plain `from:to` join collides whenever an id carries the delimiter — the
+    // store already holds ids like `memory:1775381859564:e2e` — and the collision
+    // silently overwrites one relation with an unrelated one.
+    return JSON.stringify([edge.from_id, edge.to_id]);
   }
 
   private sync(): void {
@@ -346,7 +441,8 @@ class EdgeCollection {
   private flush(): void {
     withWriteLock(this.filePath, () => {
       // Read-modify-write inside lock to merge concurrent changes
-      const diskRecords = readJsonl<StoredEdge>(this.filePath);
+      const { records: diskRecords, malformed } = readJsonlWithMalformed<StoredEdge>(this.filePath);
+      quarantineMalformedLines(this.filePath, malformed);
       const merged = new Map<string, StoredEdge>();
       for (const r of diskRecords) {
         merged.set(this.edgeKey(r), r);

package/lib/store.ts

@@ -22,6 +22,8 @@ import type {
   MedicineWheelCycle,
 } from '@/lib/types';
 
+import { actForDirection } from '@medicine-wheel/narrative-engine';
+import { extractBeats } from './beat-response';
 import { extractCycles, normalizeMedicineWheelCycle } from './cycle-response';
 import { getJsonlStore } from './jsonl-store';
 
@@ -123,14 +125,22 @@ export function createCeremony(data: Omit<CeremonyLog, 'id' | 'timestamp'> & { i
 // ── Narrative Beats ──
 
 export function getAllBeats(): NarrativeBeat[] {
-  return store.getAllBeats() as unknown as NarrativeBeat[];
+  // Beats written before ceremonies/learnings/relations_honored existed reach
+  // readers as bare records; normalizing here keeps one legacy line from
+  // taking down every arc that reads the collection.
+  return extractBeats(store.getAllBeats());
 }
 
 export function getBeatsByDirection(direction: string): NarrativeBeat[] {
-  return store.getBeatsByDirection(direction) as unknown as NarrativeBeat[];
+  return extractBeats(store.getBeatsByDirection(direction));
 }
 
-export function createBeat(data: Omit<NarrativeBeat, 'id' | 'timestamp'> & { id?: string; timestamp?: string }): NarrativeBeat {
+// `act` is optional because it is derived from `direction`, not supplied.
+// Requiring it invited callers to pass a constant, which is how a west beat
+// came to be recorded in act 1.
+export function createBeat(
+  data: Omit<NarrativeBeat, 'id' | 'timestamp' | 'act'> & { id?: string; timestamp?: string; act?: number },
+): NarrativeBeat {
   const id = data.id || crypto.randomUUID();
   const beat: NarrativeBeat = {
     id,
@@ -141,10 +151,36 @@ export function createBeat(data: Omit<NarrativeBeat, 'id' | 'timestamp'> & { id?
     ceremonies: data.ceremonies ?? [],
     learnings: data.learnings ?? [],
     timestamp: data.timestamp || new Date().toISOString(),
-    act: data.act ?? 1,
+    // Derive the act from the direction rather than defaulting to 1. A west
+    // beat posted without an act was being recorded as an opening moment,
+    // which places it wrongly on the wheel for every reader downstream.
+    act: data.act ?? actForDirection(data.direction),
     relations_honored: data.relations_honored ?? [],
   };
+  if (data.cycle_id !== undefined) beat.cycle_id = data.cycle_id;
+  if (data.parent_beat_id !== undefined) beat.parent_beat_id = data.parent_beat_id;
+  if (data.sub_beats !== undefined) beat.sub_beats = data.sub_beats;
+  if (data.origin !== undefined) beat.origin = data.origin;
+
   store.createBeat(beat as any);
+
+  // Bind the cycle side of the relation. A beat naming a cycle that does not
+  // list it back is invisible to every arc reader that starts from the cycle.
+  if (beat.cycle_id) {
+    const cycle = store.getCycle(beat.cycle_id) as any;
+    if (cycle && !(cycle.beats ?? []).includes(beat.id)) {
+      store.createCycle({ ...cycle, beats: [...(cycle.beats ?? []), beat.id] });
+    }
+  }
+
+  // Likewise the parent side of a telescoped beat.
+  if (beat.parent_beat_id) {
+    const parent = store.getBeat(beat.parent_beat_id) as any;
+    if (parent && !(parent.sub_beats ?? []).includes(beat.id)) {
+      store.createBeat({ ...parent, sub_beats: [...(parent.sub_beats ?? []), beat.id] });
+    }
+  }
+
   return beat;
 }
 
@@ -172,6 +208,36 @@ export function createCycle(data: { research_question: string; current_direction
   return normalizeMedicineWheelCycle(cycle) ?? cycle;
 }
 
+/**
+ * Write a cycle under an id the caller already holds.
+ *
+ * When the id names a stored cycle this amends it, merging the patch over the
+ * existing record. When it names none, the cycle is created under that id
+ * rather than rejected: a client that minted its own id and is now telling us
+ * about it is opening a cycle, not amending a missing one. Rejecting it left
+ * MCP's create_research_cycle reporting a cycle_id for a cycle that was never
+ * stored — the same divergence in a louder costume.
+ */
+export function upsertCycle(patch: { id: string } & Partial<MedicineWheelCycle>): MedicineWheelCycle {
+  const existing = store.getCycle(patch.id) as any;
+
+  const base = existing ?? {
+    id: patch.id,
+    research_question: '',
+    start_date: new Date().toISOString(),
+    current_direction: 'east',
+    beats: [],
+    ceremonies_conducted: 0,
+    relations_mapped: 0,
+    wilson_alignment: 0,
+    ocap_compliant: false,
+  };
+
+  const merged = { ...base, ...patch, id: patch.id };
+  store.createCycle(merged);
+  return normalizeMedicineWheelCycle(merged) ?? merged;
+}
+
 // ── Seed Data ──
 
 export function seedDemoData() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@medicine-wheel/app",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Medicine Wheel — Interactive visual layer for Indigenous relational research with Four Directions, ceremonies, and narrative arcs",
   "bin": {
     "mw": "dist/cli/mw.js",
@@ -20,9 +20,13 @@
     "Dockerfile",
     "docker-entrypoint.sh",
     "docker-build-push.sh",
-    "README.md"
+    "README.md",
+    "ALPHA.md"
   ],
   "workspaces": [
+    "src/brainstorming",
+    "src/creative-orientation",
+    "src/gap-analysis",
     "src/ceremony-protocol",
     "src/community-review",
     "src/consent-lifecycle",
@@ -52,9 +56,9 @@
     "clean:packages": "npm run clean --workspaces --if-present",
     "prebuild": "npm run build:packages",
     "predev": "npm run build:packages",
-    "dev": "next dev -p 3940",
+    "dev": "next dev -p 8040",
     "build": "next build",
-    "start": "next start -p 3940",
+    "start": "next start -p 8040",
     "lint": "next lint",
     "test": "vitest run",
     "test:watch": "vitest",
@@ -78,29 +82,30 @@
     "release:major": "npm run version:major && npm run publish:all && npm run release:commit"
   },
   "dependencies": {
-    "@medicine-wheel/ceremonial-diary": "^0.5.1",
-    "@medicine-wheel/ceremony-protocol": "^0.5.1",
-    "@medicine-wheel/community-review": "^0.5.1",
-    "@medicine-wheel/consent-lifecycle": "^0.5.1",
-    "@medicine-wheel/data-store": "^0.5.1",
-    "@medicine-wheel/data-store-postgres": "^0.5.1",
-    "@medicine-wheel/fire-keeper": "^0.5.1",
-    "@medicine-wheel/github-ceremony": "^0.5.1",
-    "@medicine-wheel/graph-viz": "^0.5.1",
-    "@medicine-wheel/importance-unit": "^0.5.1",
-    "@medicine-wheel/mcp": "^4.5.0",
-    "@medicine-wheel/narrative-cluster": "^0.5.1",
-    "@medicine-wheel/narrative-engine": "^0.5.1",
-    "@medicine-wheel/ontology-core": "^0.5.1",
-    "@medicine-wheel/perception-layer": "^0.5.1",
-    "@medicine-wheel/prompt-decomposition": "^0.5.1",
-    "@medicine-wheel/relational-index": "^0.5.1",
-    "@medicine-wheel/relational-query": "^0.5.1",
-    "@medicine-wheel/session-reader": "^0.5.1",
-    "@medicine-wheel/storage-provider": "^0.5.1",
-    "@medicine-wheel/transformation-tracker": "^0.5.1",
-    "@medicine-wheel/ui-components": "^0.5.1",
+    "@medicine-wheel/ceremonial-diary": "^0.5.3",
+    "@medicine-wheel/ceremony-protocol": "^0.5.3",
+    "@medicine-wheel/community-review": "^0.5.3",
+    "@medicine-wheel/consent-lifecycle": "^0.5.3",
+    "@medicine-wheel/data-store": "^0.5.3",
+    "@medicine-wheel/data-store-postgres": "^0.5.3",
+    "@medicine-wheel/fire-keeper": "^0.5.3",
+    "@medicine-wheel/github-ceremony": "^0.5.3",
+    "@medicine-wheel/graph-viz": "^0.5.3",
+    "@medicine-wheel/importance-unit": "^0.5.3",
+    "@medicine-wheel/mcp": "^4.5.3",
+    "@medicine-wheel/narrative-cluster": "^0.5.3",
+    "@medicine-wheel/narrative-engine": "^0.5.3",
+    "@medicine-wheel/ontology-core": "^0.5.3",
+    "@medicine-wheel/perception-layer": "^0.5.3",
+    "@medicine-wheel/prompt-decomposition": "^0.5.3",
+    "@medicine-wheel/relational-index": "^0.5.3",
+    "@medicine-wheel/relational-query": "^0.5.3",
+    "@medicine-wheel/session-reader": "^0.5.3",
+    "@medicine-wheel/storage-provider": "^0.5.3",
+    "@medicine-wheel/transformation-tracker": "^0.5.3",
+    "@medicine-wheel/ui-components": "^0.5.3",
     "@neondatabase/serverless": "^0.10.0",
+    "@xyflow/react": "^12.3.0",
     "clsx": "^2.1.1",
     "lucide-react": "^0.475.0",
     "next": "^15.3.0",
@@ -110,7 +115,7 @@
     "recharts": "^2.15.4",
     "sonner": "^1.7.0",
     "tailwind-merge": "^3.0.2",
-    "@xyflow/react": "^12.3.0"
+    "zod": "^3.23.0"
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4.1.0",
@@ -121,5 +126,9 @@
     "tailwindcss": "^4.1.0",
     "typescript": "^5.7.0",
     "vitest": "^4.1.8"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jgwill/medicine-wheel.git"
   }
 }