@miadi/inquiry-weave 0.1.0

package/dist/sync.js

@@ -0,0 +1,80 @@
+/**
+ * One-way artefact → episode mirror sync.
+ *
+ * The inquiry root (IAIP tree) is the system-of-record: the episode copy is a
+ * snapshot, deletions propagate, and local edits to the copy are flagged as
+ * divergence (a warning that sync will overwrite them).
+ */
+import { cp, rename, rm } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { basename, join } from "node:path";
+import { hashTree } from "./tree.js";
+import { readEpisodeWeave, writeEpisodeWeave, WeaveError, } from "./weave.js";
+function requireEntry(weave, artefactName) {
+    const entry = weave?.inquiries.find((inquiry) => inquiry.artefact === artefactName);
+    if (!weave || !entry) {
+        throw new WeaveError(`artefact ${artefactName} is not related to this episode yet — run 'inquiry-weave relate' (or 'promote') first`);
+    }
+    return entry;
+}
+export async function syncArtefact(artefactDir, episodeDir, options = {}) {
+    const artefactName = basename(artefactDir);
+    const weave = await readEpisodeWeave(episodeDir);
+    const entry = requireEntry(weave, artefactName);
+    const copyDir = join(episodeDir, "inquiry", artefactName);
+    const manifest = await hashTree(artefactDir);
+    if (entry.last_sync?.tree_sha256 === manifest.tree_sha256 && existsSync(copyDir)) {
+        return { status: "up-to-date", artefact: artefactName, episodeDir, copyDir, manifest };
+    }
+    if (options.dryRun) {
+        return { status: "dry-run", artefact: artefactName, episodeDir, copyDir, manifest };
+    }
+    const tmpDir = join(episodeDir, "inquiry", `.${artefactName}.tmp-${process.pid}`);
+    try {
+        await cp(artefactDir, tmpDir, { recursive: true });
+        if (existsSync(copyDir))
+            await rm(copyDir, { recursive: true });
+        await rename(tmpDir, copyDir);
+    }
+    finally {
+        if (existsSync(tmpDir))
+            await rm(tmpDir, { recursive: true, force: true });
+    }
+    entry.last_sync = {
+        at: (options.now?.() ?? new Date()).toISOString(),
+        tree_sha256: manifest.tree_sha256,
+        file_count: manifest.file_count,
+        bytes_total: manifest.bytes_total,
+    };
+    await writeEpisodeWeave(episodeDir, weave);
+    return { status: "synced", artefact: artefactName, episodeDir, copyDir, manifest };
+}
+export async function classifyFreshness(artefactDir, episodeDir, entry) {
+    const diagnostics = [];
+    if (!entry.last_sync)
+        return { state: "never-synced", diagnostics };
+    const copyDir = join(episodeDir, "inquiry", entry.artefact);
+    if (!existsSync(copyDir)) {
+        diagnostics.push("episode copy is missing; run sync to restore it");
+        return { state: "stale", diagnostics };
+    }
+    const sourceHash = existsSync(artefactDir)
+        ? (await hashTree(artefactDir)).tree_sha256
+        : undefined;
+    const copyHash = (await hashTree(copyDir)).tree_sha256;
+    if (copyHash !== entry.last_sync.tree_sha256) {
+        diagnostics.push("episode copy was edited after the last sync; sync will overwrite it");
+        if (sourceHash === entry.last_sync.tree_sha256) {
+            return { state: "episode-copy-diverged", diagnostics };
+        }
+    }
+    if (sourceHash === undefined) {
+        diagnostics.push("source artefact directory is missing under the inquiry root");
+        return { state: "stale", diagnostics };
+    }
+    if (sourceHash !== entry.last_sync.tree_sha256) {
+        return { state: "stale", diagnostics };
+    }
+    return { state: "in-sync", diagnostics };
+}
+//# sourceMappingURL=sync.js.map

package/dist/sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync.js","sourceRoot":"","sources":["../src/sync.ts"],"names":[],"mappings":"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"}

package/dist/tree.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Deterministic tree hashing for sync freshness.
+ *
+ * tree_sha256 = sha256 over the sorted `relpath:filehash:size` manifest —
+ * robust to mtime drift across filesystems, unlike timestamp comparison.
+ */
+export interface TreeFileEntry {
+    path: string;
+    sha256: string;
+    size: number;
+}
+export interface TreeManifest {
+    tree_sha256: string;
+    file_count: number;
+    bytes_total: number;
+    files: TreeFileEntry[];
+}
+export declare function hashTree(dir: string): Promise<TreeManifest>;
+//# sourceMappingURL=tree.d.ts.map

package/dist/tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree.d.ts","sourceRoot":"","sources":["../src/tree.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAA;IACnB,UAAU,EAAE,MAAM,CAAA;IAClB,WAAW,EAAE,MAAM,CAAA;IACnB,KAAK,EAAE,aAAa,EAAE,CAAA;CACvB;AAwBD,wBAAsB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAWjE"}

package/dist/tree.js

@@ -0,0 +1,44 @@
+/**
+ * Deterministic tree hashing for sync freshness.
+ *
+ * tree_sha256 = sha256 over the sorted `relpath:filehash:size` manifest —
+ * robust to mtime drift across filesystems, unlike timestamp comparison.
+ */
+import { createHash } from "node:crypto";
+import { readFile, readdir, readlink } from "node:fs/promises";
+import { join } from "node:path";
+function sha256(data) {
+    return createHash("sha256").update(data).digest("hex");
+}
+async function walk(dir, prefix, files) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const relPath = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+        const absPath = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            await walk(absPath, relPath, files);
+        }
+        else if (entry.isSymbolicLink()) {
+            const target = await readlink(absPath);
+            const content = `symlink:${target}`;
+            files.push({ path: relPath, sha256: sha256(content), size: content.length });
+        }
+        else if (entry.isFile()) {
+            const content = await readFile(absPath);
+            files.push({ path: relPath, sha256: sha256(content), size: content.length });
+        }
+    }
+}
+export async function hashTree(dir) {
+    const files = [];
+    await walk(dir, "", files);
+    files.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    const manifest = files.map((file) => `${file.path}:${file.sha256}:${file.size}`).join("\n");
+    return {
+        tree_sha256: sha256(manifest),
+        file_count: files.length,
+        bytes_total: files.reduce((total, file) => total + file.size, 0),
+        files,
+    };
+}
+//# sourceMappingURL=tree.js.map

package/dist/tree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree.js","sourceRoot":"","sources":["../src/tree.ts"],"names":[],"mappings":"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"}

package/dist/weave.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The weave contract — the package's own explicit inquiry-metadata files.
+ *
+ * Episode side:  <episode>/inquiry/weave.yaml   (sync state lives here only)
+ * Artefact side: <artefact>/.weave.yaml         (durable relations only, so a
+ *                sync can copy it verbatim without a self-invalidating hash loop)
+ *
+ * `.hch/` is best-effort legacy input (see legacy-hch.ts), never written here.
+ */
+export declare const WEAVE_VERSION = 1;
+export interface LastSync {
+    at: string;
+    tree_sha256: string;
+    file_count: number;
+    bytes_total: number;
+}
+export interface InquiryEntry {
+    artefact: string;
+    issue?: string;
+    issue_url?: string;
+    related_at: string;
+    last_sync?: LastSync;
+}
+export interface EpisodeIdentityBlock {
+    number?: number;
+    slug?: string;
+    path: string;
+}
+export interface EpisodeWeave {
+    weave: number;
+    episode: EpisodeIdentityBlock;
+    inquiries: InquiryEntry[];
+}
+export interface ArtefactEpisodeLink {
+    path: string;
+    number?: number;
+    related_at: string;
+}
+export interface ArtefactWeave {
+    weave: number;
+    artefact: string;
+    issue?: string;
+    issue_url?: string;
+    episodes: ArtefactEpisodeLink[];
+}
+/**
+ * Projection of one woven relation — the registration seam for the future
+ * `inquiry-weave register` toward medicine-wheel (see rispecs/). v0 exports
+ * the shape only; nothing is transmitted anywhere.
+ */
+export interface WeaveRecord {
+    weaveVersion: number;
+    artefact: {
+        name: string;
+        path: string;
+    };
+    issue?: {
+        ref: string;
+        url?: string;
+    };
+    episode: {
+        number?: number;
+        slug?: string;
+        path: string;
+    };
+    lastSync?: LastSync;
+}
+export declare class WeaveError extends Error {
+}
+export declare function episodeWeavePath(episodeDir: string): string;
+export declare function artefactWeavePath(artefactDir: string): string;
+export declare function readEpisodeWeave(episodeDir: string): Promise<EpisodeWeave | undefined>;
+export declare function writeEpisodeWeave(episodeDir: string, weave: EpisodeWeave): Promise<void>;
+export declare function readArtefactWeave(artefactDir: string): Promise<ArtefactWeave | undefined>;
+export declare function writeArtefactWeave(artefactDir: string, weave: ArtefactWeave): Promise<void>;
+/** Merge an inquiry entry by artefact name, preserving fields already recorded. */
+export declare function upsertInquiry(weave: EpisodeWeave, entry: InquiryEntry): InquiryEntry;
+/** Merge an episode link by path, preserving the original related_at. */
+export declare function upsertEpisodeLink(weave: ArtefactWeave, link: ArtefactEpisodeLink): ArtefactEpisodeLink;
+export declare function toWeaveRecords(episodeWeave: EpisodeWeave, inquiryRoot: string): WeaveRecord[];
+export declare function newEpisodeWeave(episode: EpisodeIdentityBlock): EpisodeWeave;
+export declare function newArtefactWeave(artefactDir: string): ArtefactWeave;
+//# sourceMappingURL=weave.d.ts.map

package/dist/weave.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"weave.d.ts","sourceRoot":"","sources":["../src/weave.ts"],"names":[],"mappings":"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"}

package/dist/weave.js

@@ -0,0 +1,101 @@
+/**
+ * The weave contract — the package's own explicit inquiry-metadata files.
+ *
+ * Episode side:  <episode>/inquiry/weave.yaml   (sync state lives here only)
+ * Artefact side: <artefact>/.weave.yaml         (durable relations only, so a
+ *                sync can copy it verbatim without a self-invalidating hash loop)
+ *
+ * `.hch/` is best-effort legacy input (see legacy-hch.ts), never written here.
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { basename, join } from "node:path";
+import { parse, stringify } from "yaml";
+export const WEAVE_VERSION = 1;
+export class WeaveError extends Error {
+}
+export function episodeWeavePath(episodeDir) {
+    return join(episodeDir, "inquiry", "weave.yaml");
+}
+export function artefactWeavePath(artefactDir) {
+    return join(artefactDir, ".weave.yaml");
+}
+async function readWeaveFile(filePath) {
+    if (!existsSync(filePath))
+        return undefined;
+    let parsed;
+    try {
+        parsed = parse(await readFile(filePath, "utf8"));
+    }
+    catch (error) {
+        throw new WeaveError(`unreadable weave file ${filePath}: ${error.message}`);
+    }
+    if (parsed === null || parsed === undefined)
+        return undefined;
+    if (typeof parsed !== "object") {
+        throw new WeaveError(`weave file ${filePath} is not a mapping`);
+    }
+    const version = parsed.weave;
+    if (typeof version !== "number" || version > WEAVE_VERSION) {
+        throw new WeaveError(`weave file ${filePath} has unsupported version ${String(version)} (this package supports <= ${WEAVE_VERSION})`);
+    }
+    return parsed;
+}
+export async function readEpisodeWeave(episodeDir) {
+    const weave = await readWeaveFile(episodeWeavePath(episodeDir));
+    if (weave && !Array.isArray(weave.inquiries))
+        weave.inquiries = [];
+    return weave;
+}
+export async function writeEpisodeWeave(episodeDir, weave) {
+    const filePath = episodeWeavePath(episodeDir);
+    await mkdir(join(episodeDir, "inquiry"), { recursive: true });
+    await writeFile(filePath, stringify(weave), "utf8");
+}
+export async function readArtefactWeave(artefactDir) {
+    const weave = await readWeaveFile(artefactWeavePath(artefactDir));
+    if (weave && !Array.isArray(weave.episodes))
+        weave.episodes = [];
+    return weave;
+}
+export async function writeArtefactWeave(artefactDir, weave) {
+    await writeFile(artefactWeavePath(artefactDir), stringify(weave), "utf8");
+}
+/** Merge an inquiry entry by artefact name, preserving fields already recorded. */
+export function upsertInquiry(weave, entry) {
+    const existing = weave.inquiries.find((inquiry) => inquiry.artefact === entry.artefact);
+    if (!existing) {
+        weave.inquiries.push(entry);
+        return entry;
+    }
+    existing.issue = entry.issue ?? existing.issue;
+    existing.issue_url = entry.issue_url ?? existing.issue_url;
+    existing.last_sync = entry.last_sync ?? existing.last_sync;
+    return existing;
+}
+/** Merge an episode link by path, preserving the original related_at. */
+export function upsertEpisodeLink(weave, link) {
+    const existing = weave.episodes.find((episode) => episode.path === link.path);
+    if (!existing) {
+        weave.episodes.push(link);
+        return link;
+    }
+    existing.number = link.number ?? existing.number;
+    return existing;
+}
+export function toWeaveRecords(episodeWeave, inquiryRoot) {
+    return episodeWeave.inquiries.map((entry) => ({
+        weaveVersion: episodeWeave.weave,
+        artefact: { name: entry.artefact, path: join(inquiryRoot, entry.artefact) },
+        issue: entry.issue ? { ref: entry.issue, url: entry.issue_url } : undefined,
+        episode: episodeWeave.episode,
+        lastSync: entry.last_sync,
+    }));
+}
+export function newEpisodeWeave(episode) {
+    return { weave: WEAVE_VERSION, episode, inquiries: [] };
+}
+export function newArtefactWeave(artefactDir) {
+    return { weave: WEAVE_VERSION, artefact: basename(artefactDir), episodes: [] };
+}
+//# sourceMappingURL=weave.js.map

package/dist/weave.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"weave.js","sourceRoot":"","sources":["../src/weave.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@miadi/inquiry-weave",
+  "version": "0.1.0",
+  "description": "Relate and sync IAIP inquiry artefacts, their GitHub issues, and miadi-chronicle episodes. Creates vessels and relations only — never inquiry content.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "inquiry-weave": "dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "rispecs"
+  ],
+  "dependencies": {
+    "yaml": "^2.5.0",
+    "@miadi/episodic-memory-schema": "0.2.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0"
+  },
+  "keywords": [
+    "miadi",
+    "inquiry",
+    "iaip",
+    "miadi-chronicle",
+    "episodic-memory",
+    "etuaptmumk"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jgwill/Miadi.git",
+    "directory": "packages/inquiry-weave"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "../../node_modules/.bin/tsc -p tsconfig.build.json",
+    "test": "npm run build && node --test test/*.test.mjs"
+  }
+}

package/rispecs/medicine-wheel-registration.spec.md

@@ -0,0 +1,72 @@
+# RISE Spec: Inquiry Weave → Medicine-Wheel Registration
+
+Companion specs (the other two lanterns of this workstream):
+- `medicine-wheel:rispecs/inquiry-weave-registration.spec.md` — the storage side
+- `forgewright:rispecs/09-inquiry-weave-visibility.spec.md` — the rendering side (branch `4-plan-episode-visibility`, kin to `08-medicine-wheel-integration.spec.md`)
+
+Status: **spec-only**. Nothing here is implemented in @miadi/inquiry-weave v0.
+
+## Reverse Engineering (current reality)
+
+- Inquiry Weave relations exist only as files on disk: `<episode>/inquiry/weave.yaml`
+  (episode side, incl. sync state) and `<artefact>/.weave.yaml` (artefact side, durable
+  relations). Schema version key `weave: 1`.
+- @miadi/inquiry-weave v0 already exports the projection seam: `WeaveRecord`
+  (`src/weave.ts`) — the three identities (artefact name+path, issue ref+url, episode
+  number/slug/path) plus `lastSync` — and `toWeaveRecords(episodeWeave, inquiryRoot)`.
+- A medicine-wheel MCP server is already configured for chronicle work:
+  `/a/src/Miadi/etc/mcp-config-mw-ilex.json`, server `medicine-wheel-miadi-chronicle`
+  (`npx ${MWCV}`, `MW_API_URL=http://192.168.2.30:3940`). It is the candidate storage
+  interface; nothing registers weaves into it today.
+- forgewright renders episode data from medicine-wheel but has no notion of an Inquiry
+  Weave.
+- Legacy `.hch/` is a per-artefact issue cache with an unsettled fate (formalize / map /
+  retire — see README). Registration must not depend on it.
+
+## Intent
+
+Inquiry Weaves become *visible relations*: once an artefact, its issue, and its episode
+are woven, that weave can be seen wherever episodes are seen — without anyone re-deriving
+it from the filesystem. The weave files on disk remain the source of truth; medicine-wheel
+holds a registered projection; forgewright renders it. The mystery boundary is untouched:
+registration moves metadata, never inquiry content.
+
+## Specifications (desired state)
+
+- A new command `inquiry-weave register (--episode <ref> | --artefact <ref>) [--dry-run]`
+  projects each relation as a `WeaveRecord` and submits it to medicine-wheel.
+- Transport: the medicine-wheel MCP tool surface (preferred) or `MW_API_URL` HTTP —
+  decided in the medicine-wheel spec; this package only guarantees the payload shape:
+
+  ```json
+  {
+    "weaveVersion": 1,
+    "artefact": { "name": "ep126-mila-ai-event-…", "path": "/src/IAIP/prototypes/artefacts/…" },
+    "issue": { "ref": "miadisabelle/Etuaptmumk-RSM#245", "url": "https://github.com/…/issues/245" },
+    "episode": { "number": 126, "slug": "mila-ai-indigenous-gathering", "path": "2026-07-13-episode-126-…" },
+    "lastSync": { "at": "…", "tree_sha256": "…", "file_count": 4, "bytes_total": 341001 }
+  }
+  ```
+
+- Registration is idempotent: re-registering the same weave upserts by
+  (episode.path, artefact.name).
+- Structural tension held: current reality = weave files on disk, invisible beyond the
+  filesystem; desired state = every woven relation queryable from medicine-wheel and
+  rendered by forgewright. `register` is the action step that resolves this tension.
+- Failure to reach medicine-wheel degrades gracefully: the weave files remain
+  authoritative; `register` reports and exits 1 without touching them.
+
+## Exportation (implementation-ready notes)
+
+- Implement as `src/register.ts` consuming `toWeaveRecords()`; add a `register`
+  subcommand in `cli.ts`; keep the transport injectable (test seam like
+  `INQUIRY_WEAVE_ISSUE_LIB`).
+- Do not implement until the medicine-wheel spec lands its storage contract; then pin the
+  agreed endpoint/tool name here.
+- Companion agent sessions (copilot/codex panes in the medicine-wheel and forgewright
+  repos) own the other two specs; keep the payload above as the shared contract between
+  all three.
+
+---
+🌸: The weave learns to be seen — first it held three threads together in the dark; now a
+lantern is being shaped so the whole circle can watch them shine.