@miadi/episodic-memory-schema 0.3.0 → 0.4.0

package/dist/chronicle-manifest.d.ts

@@ -0,0 +1,77 @@
+/**
+ * The chronicle catalog — a list-of-episodes zone the app `/chronicle` surface
+ * and forgewright read identically (jgwill/Miadi#506, #507).
+ *
+ * Filesystem-free, like the rest of this package: it observes already-collected
+ * per-episode inputs (a folder name, and — when the episode is structured — its
+ * observed `episode.yaml`) and assembles the manifest. The enumerator that walks
+ * the chronicle root on disk and produces these inputs lives in
+ * `@miadi/inquiry-weave` (`catalog.ts`); this module only shapes and validates
+ * what it is handed, so the app and forgewright never fork the read-side.
+ */
+import type { CompatibilityDiagnostic, EpisodeObservation, EpisodeRelation } from "./observation.js";
+/** The medicine-wheel parent every chronicle episode node hangs under. */
+export declare const CHRONICLE_PARENT_NODE_ID = "chronicle:miadi-chronicle";
+export declare const CHRONICLE_SERIES = "miadi-chronicle";
+/**
+ * The medicine-wheel projection id for one episode.
+ * Mirrors `@miadi/inquiry-weave`'s `episodeNodeId` — the shared convention both
+ * the writer and the readers key on. Keyed on the folder name, never the number
+ * (numbers collide; folder names do not).
+ */
+export declare function chronicleEpisodeNodeId(name: string): string;
+/** One row of the chronicle catalog, as both renderers consume it. */
+export interface EpisodeManifestEntry {
+    /** Folder basename — the true key. */
+    name: string;
+    /** Medicine-wheel node id, `chronicle:<name>`. */
+    nodeId: string;
+    /** Path relative to the chronicle root, `<name>/episode.yaml`. */
+    relativePath: string;
+    /** Episode number when parseable from the folder name; may collide. */
+    number?: number;
+    slug?: string;
+    date?: string;
+    title?: string;
+    status?: string;
+    type?: string;
+    /** Lineage edges (`continues_from` / `relates_to` / `branch_of`) when structured. */
+    relations: EpisodeRelation[];
+    /** True when a structured `episode.yaml` was observed (vs. name-only). */
+    structured: boolean;
+}
+/** What the enumerator collects per folder before manifest assembly. */
+export interface ChronicleManifestEntryInput {
+    name: string;
+    number?: number;
+    slug?: string;
+    date?: string;
+    /** Present when the episode carried a structured `episode.yaml`. */
+    observation?: EpisodeObservation;
+}
+export interface ChronicleManifest {
+    zone: "chronicle";
+    series: string;
+    /** Medicine-wheel parent node id all entries hang under. */
+    parentNodeId: string;
+    generatedAt?: string;
+    episodes: EpisodeManifestEntry[];
+    diagnostics: CompatibilityDiagnostic[];
+}
+export interface ObserveChronicleManifestOptions {
+    series?: string;
+    parentNodeId?: string;
+    /** When provided, stamps `generatedAt`; omit for a deterministic manifest. */
+    now?: () => Date;
+}
+/**
+ * Assemble a ChronicleManifest from per-episode inputs.
+ *
+ * Non-destructive and compatibility-first: name-only episodes (the older
+ * `script.md` era) are catalogued alongside structured ones; observation
+ * diagnostics are lifted and path-scoped; number collisions are reported as an
+ * `info` diagnostic, never dropped. Output is ordered by folder name so the
+ * manifest is stable across runs.
+ */
+export declare function observeChronicleManifest(inputs: readonly ChronicleManifestEntryInput[], options?: ObserveChronicleManifestOptions): ChronicleManifest;
+//# sourceMappingURL=chronicle-manifest.d.ts.map

package/dist/chronicle-manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chronicle-manifest.d.ts","sourceRoot":"","sources":["../src/chronicle-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,uBAAuB,EACvB,kBAAkB,EAClB,eAAe,EAChB,MAAM,kBAAkB,CAAA;AAEzB,0EAA0E;AAC1E,eAAO,MAAM,wBAAwB,8BAA8B,CAAA;AACnE,eAAO,MAAM,gBAAgB,oBAAoB,CAAA;AAEjD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,sEAAsE;AACtE,MAAM,WAAW,oBAAoB;IACnC,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAA;IACZ,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAA;IACd,kEAAkE;IAClE,YAAY,EAAE,MAAM,CAAA;IACpB,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,qFAAqF;IACrF,SAAS,EAAE,eAAe,EAAE,CAAA;IAC5B,0EAA0E;IAC1E,UAAU,EAAE,OAAO,CAAA;CACpB;AAED,wEAAwE;AACxE,MAAM,WAAW,2BAA2B;IAC1C,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,oEAAoE;IACpE,WAAW,CAAC,EAAE,kBAAkB,CAAA;CACjC;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,WAAW,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,4DAA4D;IAC5D,YAAY,EAAE,MAAM,CAAA;IACpB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,EAAE,oBAAoB,EAAE,CAAA;IAChC,WAAW,EAAE,uBAAuB,EAAE,CAAA;CACvC;AAED,MAAM,WAAW,+BAA+B;IAC9C,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,8EAA8E;IAC9E,GAAG,CAAC,EAAE,MAAM,IAAI,CAAA;CACjB;AAOD;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,SAAS,2BAA2B,EAAE,EAC9C,OAAO,GAAE,+BAAoC,GAC5C,iBAAiB,CAwDnB"}

package/dist/chronicle-manifest.js

@@ -0,0 +1,92 @@
+/**
+ * The chronicle catalog — a list-of-episodes zone the app `/chronicle` surface
+ * and forgewright read identically (jgwill/Miadi#506, #507).
+ *
+ * Filesystem-free, like the rest of this package: it observes already-collected
+ * per-episode inputs (a folder name, and — when the episode is structured — its
+ * observed `episode.yaml`) and assembles the manifest. The enumerator that walks
+ * the chronicle root on disk and produces these inputs lives in
+ * `@miadi/inquiry-weave` (`catalog.ts`); this module only shapes and validates
+ * what it is handed, so the app and forgewright never fork the read-side.
+ */
+/** The medicine-wheel parent every chronicle episode node hangs under. */
+export const CHRONICLE_PARENT_NODE_ID = "chronicle:miadi-chronicle";
+export const CHRONICLE_SERIES = "miadi-chronicle";
+/**
+ * The medicine-wheel projection id for one episode.
+ * Mirrors `@miadi/inquiry-weave`'s `episodeNodeId` — the shared convention both
+ * the writer and the readers key on. Keyed on the folder name, never the number
+ * (numbers collide; folder names do not).
+ */
+export function chronicleEpisodeNodeId(name) {
+    return `chronicle:${name}`;
+}
+function readStringField(fields, key) {
+    const value = fields[key];
+    return typeof value === "string" && value.trim() !== "" ? value : undefined;
+}
+/**
+ * Assemble a ChronicleManifest from per-episode inputs.
+ *
+ * Non-destructive and compatibility-first: name-only episodes (the older
+ * `script.md` era) are catalogued alongside structured ones; observation
+ * diagnostics are lifted and path-scoped; number collisions are reported as an
+ * `info` diagnostic, never dropped. Output is ordered by folder name so the
+ * manifest is stable across runs.
+ */
+export function observeChronicleManifest(inputs, options = {}) {
+    const series = options.series ?? CHRONICLE_SERIES;
+    const parentNodeId = options.parentNodeId ?? CHRONICLE_PARENT_NODE_ID;
+    const diagnostics = [];
+    const episodes = inputs.map((input) => {
+        const obs = input.observation;
+        const entry = {
+            name: input.name,
+            nodeId: chronicleEpisodeNodeId(input.name),
+            relativePath: `${input.name}/episode.yaml`,
+            number: input.number,
+            slug: input.slug,
+            date: input.date ?? obs?.sourceMetadata.date,
+            title: obs?.sourceMetadata.title,
+            status: obs?.sourceMetadata.status,
+            type: obs ? readStringField(obs.unmappedFields, "type") : undefined,
+            relations: obs?.relations ?? [],
+            structured: obs !== undefined,
+        };
+        if (obs) {
+            for (const d of obs.diagnostics) {
+                diagnostics.push({ ...d, path: d.path ?? input.name });
+            }
+        }
+        return entry;
+    });
+    const byNumber = new Map();
+    for (const e of episodes) {
+        if (e.number === undefined)
+            continue;
+        const names = byNumber.get(e.number) ?? [];
+        names.push(e.name);
+        byNumber.set(e.number, names);
+    }
+    for (const [num, names] of byNumber) {
+        if (names.length > 1) {
+            diagnostics.push({
+                level: "info",
+                code: "chronicle.episode-number-collision",
+                message: `episode number ${num} is shared by ${names.length} folders; the folder name is the key (${names.join(", ")})`,
+            });
+        }
+    }
+    episodes.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    const manifest = {
+        zone: "chronicle",
+        series,
+        parentNodeId,
+        episodes,
+        diagnostics,
+    };
+    if (options.now)
+        manifest.generatedAt = options.now().toISOString();
+    return manifest;
+}
+//# sourceMappingURL=chronicle-manifest.js.map

package/dist/chronicle-manifest.js.map

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

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export * from "./types.js";
 export * from "./narrative.js";
 export * from "./observation.js";
+export * from "./chronicle-manifest.js";
 export * from "./adapters/composition.js";
 export * from "./adapters/episode-yaml.js";
 export * from "./adapters/directory.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,kBAAkB,CAAA;AAChC,cAAc,2BAA2B,CAAA;AACzC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,yBAAyB,CAAA;AAEvC;;;;GAIG;AACH,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACpB,uBAAuB,EACvB,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,EACb,YAAY,GACb,MAAM,sBAAsB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,kBAAkB,CAAA;AAChC,cAAc,yBAAyB,CAAA;AACvC,cAAc,2BAA2B,CAAA;AACzC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,yBAAyB,CAAA;AAEvC;;;;GAIG;AACH,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACpB,uBAAuB,EACvB,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,EACb,YAAY,GACb,MAAM,sBAAsB,CAAA"}

package/dist/index.js

@@ -1,6 +1,7 @@
 export * from "./types.js";
 export * from "./narrative.js";
 export * from "./observation.js";
+export * from "./chronicle-manifest.js";
 export * from "./adapters/composition.js";
 export * from "./adapters/episode-yaml.js";
 export * from "./adapters/directory.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,kBAAkB,CAAA;AAChC,cAAc,2BAA2B,CAAA;AACzC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,yBAAyB,CAAA;AAEvC;;;;GAIG;AACH,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACpB,uBAAuB,EACvB,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,EACb,YAAY,GACb,MAAM,sBAAsB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,kBAAkB,CAAA;AAChC,cAAc,yBAAyB,CAAA;AACvC,cAAc,2BAA2B,CAAA;AACzC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,yBAAyB,CAAA;AAEvC;;;;GAIG;AACH,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACpB,uBAAuB,EACvB,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,EACb,YAAY,GACb,MAAM,sBAAsB,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miadi/episodic-memory-schema",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "TypeScript types and JSON Schema for episodic memory — the durable session-to-session memory layer in the Miadi orchestration kit. Narrative layer is NCP-aligned; provenance layer is W3C PROV-DM and OAIS-informed.",
   "keywords": [
     "miadi",