@karmaniverous/jeeves-meta 0.8.0 → 0.9.0

package/README.md

@@ -10,6 +10,7 @@ HTTP service for the Jeeves knowledge synthesis engine. Provides a Fastify API,
 - **Three-step orchestration** — architect, builder, critic with conditional re-architecture
 - **Discovery via watcher** — filesystem-based meta discovery via `/walk` endpoint (no Qdrant dependency)
 - **Ownership tree** — hierarchical scoping with child meta rollup
+- **Cross-meta references** — `_crossRefs` declares relationships to other metas; referenced `_content` included as architect/builder context
 - **Archive management** — timestamped snapshots with configurable pruning
 - **Lock staging** — write to `.lock` → copy to `meta.json` → archive (crash-safe)
 - **Virtual rule registration** — registers 3 watcher inference rules at startup with retry
@@ -54,7 +55,7 @@ jeeves-meta service install --config /path/to/jeeves-meta.config.json
 | GET | `/metas/:path` | Single meta detail with optional archive |
 | GET | `/preview` | Dry-run: preview inputs for next synthesis |
 | POST | `/synthesize` | Enqueue synthesis (stalest or specific path) |
-| POST | `/seed` | Create `.meta/` directory + meta.json |
+| POST | `/seed` | Create `.meta/` directory + meta.json (optional `crossRefs`) |
 | POST | `/unlock` | Remove `.lock` file from a meta entity |
 | GET | `/config` | Query sanitized config with optional JSONPath (`?path=$.schedule`) |
 

package/dist/cli/jeeves-meta/index.js

@@ -1230,6 +1230,22 @@ function condenseScopeFiles(files, maxIndividual = 30) {
         .map(([pattern, count]) => pattern + ' (' + count.toString() + ' files)')
         .join('\n');
 }
+/**
+ * Read a meta.json file and extract its `_content` field.
+ *
+ * @param metaJsonPath - Absolute path to a meta.json file.
+ * @returns The `_content` string, or null if missing/unreadable.
+ */
+function readMetaContent(metaJsonPath) {
+    try {
+        const raw = readFileSync(metaJsonPath, 'utf8');
+        const meta = JSON.parse(raw);
+        return meta._content ?? null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Build the context package for a synthesis cycle.
  *
@@ -1245,15 +1261,18 @@ async function buildContextPackage(node, meta, watcher) {
     // Child meta outputs
     const childMetas = {};
     for (const child of node.children) {
-        const childMetaFile = join(child.metaPath, 'meta.json');
-        try {
-            const raw = readFileSync(childMetaFile, 'utf8');
-            const childMeta = JSON.parse(raw);
-            childMetas[child.ownerPath] = childMeta._content ?? null;
-        }
-        catch {
-            childMetas[child.ownerPath] = null;
-        }
+        childMetas[child.ownerPath] = readMetaContent(join(child.metaPath, 'meta.json'));
+    }
+    // Cross-referenced meta outputs
+    const crossRefMetas = {};
+    const seen = new Set();
+    for (const refPath of meta._crossRefs ?? []) {
+        if (refPath === node.ownerPath || refPath === node.metaPath)
+            continue;
+        if (seen.has(refPath))
+            continue;
+        seen.add(refPath);
+        crossRefMetas[refPath] = readMetaContent(join(refPath, '.meta', 'meta.json'));
     }
     // Archive paths
     const archives = listArchiveFiles(node.metaPath);
@@ -1262,6 +1281,7 @@ async function buildContextPackage(node, meta, watcher) {
         scopeFiles,
         deltaFiles,
         childMetas,
+        crossRefMetas,
         previousContent: meta._content ?? null,
         previousFeedback: meta._feedback ?? null,
         steer: meta._steer ?? null,
@@ -1275,6 +1295,15 @@ async function buildContextPackage(node, meta, watcher) {
  *
  * @module orchestrator/buildTask
  */
+/** Append a keyed record of meta outputs as subsections, if non-empty. */
+function appendMetaSections(sections, heading, metas) {
+    if (Object.keys(metas).length === 0)
+        return;
+    sections.push('', heading);
+    for (const [path, content] of Object.entries(metas)) {
+        sections.push(`### ${path}`, typeof content === 'string' ? content : '(not yet synthesized)');
+    }
+}
 /** Append optional context sections shared across all step prompts. */
 function appendSharedSections(sections, ctx, options) {
     const opts = {
@@ -1283,6 +1312,7 @@ function appendSharedSections(sections, ctx, options) {
         includePreviousFeedback: true,
         feedbackHeading: '## PREVIOUS FEEDBACK',
         includeChildMetas: true,
+        includeCrossRefs: true,
         ...options,
     };
     if (opts.includeSteer && ctx.steer) {
@@ -1294,11 +1324,11 @@ function appendSharedSections(sections, ctx, options) {
     if (opts.includePreviousFeedback && ctx.previousFeedback) {
         sections.push('', opts.feedbackHeading, ctx.previousFeedback);
     }
-    if (opts.includeChildMetas && Object.keys(ctx.childMetas).length > 0) {
-        sections.push('', '## CHILD META OUTPUTS');
-        for (const [childPath, content] of Object.entries(ctx.childMetas)) {
-            sections.push(`### ${childPath}`, typeof content === 'string' ? content : '(not yet synthesized)');
-        }
+    if (opts.includeChildMetas) {
+        appendMetaSections(sections, '## CHILD META OUTPUTS', ctx.childMetas);
+    }
+    if (opts.includeCrossRefs) {
+        appendMetaSections(sections, '## CROSS-REFERENCED METAS', ctx.crossRefMetas);
     }
 }
 /**
@@ -1382,6 +1412,7 @@ function buildCriticTask(ctx, meta, config) {
         includePreviousContent: false,
         feedbackHeading: '## YOUR PREVIOUS FEEDBACK',
         includeChildMetas: false,
+        includeCrossRefs: false,
     });
     sections.push('', '## OUTPUT FORMAT', 'Return your evaluation as Markdown text. Be specific and actionable.');
     return sections.join('\n');
@@ -1417,6 +1448,11 @@ const metaJsonSchema = z
     _id: z.uuid(),
     /** Human-provided steering prompt. Optional. */
     _steer: z.string().optional(),
+    /**
+     * Explicit cross-references to other meta owner paths.
+     * Referenced metas' _content is included as architect/builder context.
+     */
+    _crossRefs: z.array(z.string()).optional(),
     /** Architect system prompt used this turn. Defaults from config. */
     _architect: z.string().optional(),
     /**
@@ -9917,6 +9953,27 @@ function registerMetasRoutes(app, deps) {
                 score: Math.round(score * 100) / 100,
             },
         };
+        // Cross-refs status
+        const crossRefsRaw = meta._crossRefs;
+        if (Array.isArray(crossRefsRaw) && crossRefsRaw.length > 0) {
+            response.crossRefs = crossRefsRaw.map((refPath) => {
+                const rp = String(refPath);
+                const refMetaFile = join(rp, '.meta', 'meta.json');
+                if (!existsSync(refMetaFile))
+                    return { path: rp, status: 'missing' };
+                try {
+                    const refMeta = JSON.parse(readFileSync(refMetaFile, 'utf8'));
+                    return {
+                        path: rp,
+                        status: 'resolved',
+                        hasContent: Boolean(refMeta._content),
+                    };
+                }
+                catch {
+                    return { path: rp, status: 'missing' };
+                }
+            });
+        }
         // Archive
         if (query.includeArchive) {
             const archiveFiles = listArchiveFiles(targetNode.metaPath);
@@ -10034,6 +10091,7 @@ function registerPreviewRoute(app, deps) {
  */
 const seedBodySchema = z.object({
     path: z.string().min(1),
+    crossRefs: z.array(z.string()).optional(),
 });
 function registerSeedRoute(app, deps) {
     app.post('/seed', (request, reply) => {
@@ -10048,6 +10106,8 @@ function registerSeedRoute(app, deps) {
         deps.logger.info({ metaDir }, 'creating .meta directory');
         mkdirSync(metaDir, { recursive: true });
         const metaJson = { _id: randomUUID() };
+        if (body.crossRefs !== undefined)
+            metaJson._crossRefs = body.crossRefs;
         const metaJsonPath = join(metaDir, 'meta.json');
         deps.logger.info({ metaJsonPath }, 'writing meta.json');
         writeFileSync(metaJsonPath, JSON.stringify(metaJson, null, 2) + '\n');

package/dist/index.d.ts

@@ -125,6 +125,7 @@ type MetaError = z.infer<typeof metaErrorSchema>;
 declare const metaJsonSchema: z.ZodObject<{
     _id: z.ZodUUID;
     _steer: z.ZodOptional<z.ZodString>;
+    _crossRefs: z.ZodOptional<z.ZodArray<z.ZodString>>;
     _architect: z.ZodOptional<z.ZodString>;
     _builder: z.ZodOptional<z.ZodString>;
     _critic: z.ZodOptional<z.ZodString>;
@@ -253,6 +254,8 @@ interface MetaContext {
     deltaFiles: string[];
     /** Child _content outputs, keyed by relative path. */
     childMetas: Record<string, unknown>;
+    /** Cross-referenced meta _content outputs, keyed by owner path. */
+    crossRefMetas: Record<string, unknown>;
     /** _content from the last cycle, or null on first run. */
     previousContent: string | null;
     /** _feedback from the last cycle, or null on first run. */

package/dist/index.js

@@ -1222,6 +1222,22 @@ function condenseScopeFiles(files, maxIndividual = 30) {
         .map(([pattern, count]) => pattern + ' (' + count.toString() + ' files)')
         .join('\n');
 }
+/**
+ * Read a meta.json file and extract its `_content` field.
+ *
+ * @param metaJsonPath - Absolute path to a meta.json file.
+ * @returns The `_content` string, or null if missing/unreadable.
+ */
+function readMetaContent(metaJsonPath) {
+    try {
+        const raw = readFileSync(metaJsonPath, 'utf8');
+        const meta = JSON.parse(raw);
+        return meta._content ?? null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Build the context package for a synthesis cycle.
  *
@@ -1237,15 +1253,18 @@ async function buildContextPackage(node, meta, watcher) {
     // Child meta outputs
     const childMetas = {};
     for (const child of node.children) {
-        const childMetaFile = join(child.metaPath, 'meta.json');
-        try {
-            const raw = readFileSync(childMetaFile, 'utf8');
-            const childMeta = JSON.parse(raw);
-            childMetas[child.ownerPath] = childMeta._content ?? null;
-        }
-        catch {
-            childMetas[child.ownerPath] = null;
-        }
+        childMetas[child.ownerPath] = readMetaContent(join(child.metaPath, 'meta.json'));
+    }
+    // Cross-referenced meta outputs
+    const crossRefMetas = {};
+    const seen = new Set();
+    for (const refPath of meta._crossRefs ?? []) {
+        if (refPath === node.ownerPath || refPath === node.metaPath)
+            continue;
+        if (seen.has(refPath))
+            continue;
+        seen.add(refPath);
+        crossRefMetas[refPath] = readMetaContent(join(refPath, '.meta', 'meta.json'));
     }
     // Archive paths
     const archives = listArchiveFiles(node.metaPath);
@@ -1254,6 +1273,7 @@ async function buildContextPackage(node, meta, watcher) {
         scopeFiles,
         deltaFiles,
         childMetas,
+        crossRefMetas,
         previousContent: meta._content ?? null,
         previousFeedback: meta._feedback ?? null,
         steer: meta._steer ?? null,
@@ -1267,6 +1287,15 @@ async function buildContextPackage(node, meta, watcher) {
  *
  * @module orchestrator/buildTask
  */
+/** Append a keyed record of meta outputs as subsections, if non-empty. */
+function appendMetaSections(sections, heading, metas) {
+    if (Object.keys(metas).length === 0)
+        return;
+    sections.push('', heading);
+    for (const [path, content] of Object.entries(metas)) {
+        sections.push(`### ${path}`, typeof content === 'string' ? content : '(not yet synthesized)');
+    }
+}
 /** Append optional context sections shared across all step prompts. */
 function appendSharedSections(sections, ctx, options) {
     const opts = {
@@ -1275,6 +1304,7 @@ function appendSharedSections(sections, ctx, options) {
         includePreviousFeedback: true,
         feedbackHeading: '## PREVIOUS FEEDBACK',
         includeChildMetas: true,
+        includeCrossRefs: true,
         ...options,
     };
     if (opts.includeSteer && ctx.steer) {
@@ -1286,11 +1316,11 @@ function appendSharedSections(sections, ctx, options) {
     if (opts.includePreviousFeedback && ctx.previousFeedback) {
         sections.push('', opts.feedbackHeading, ctx.previousFeedback);
     }
-    if (opts.includeChildMetas && Object.keys(ctx.childMetas).length > 0) {
-        sections.push('', '## CHILD META OUTPUTS');
-        for (const [childPath, content] of Object.entries(ctx.childMetas)) {
-            sections.push(`### ${childPath}`, typeof content === 'string' ? content : '(not yet synthesized)');
-        }
+    if (opts.includeChildMetas) {
+        appendMetaSections(sections, '## CHILD META OUTPUTS', ctx.childMetas);
+    }
+    if (opts.includeCrossRefs) {
+        appendMetaSections(sections, '## CROSS-REFERENCED METAS', ctx.crossRefMetas);
     }
 }
 /**
@@ -1374,6 +1404,7 @@ function buildCriticTask(ctx, meta, config) {
         includePreviousContent: false,
         feedbackHeading: '## YOUR PREVIOUS FEEDBACK',
         includeChildMetas: false,
+        includeCrossRefs: false,
     });
     sections.push('', '## OUTPUT FORMAT', 'Return your evaluation as Markdown text. Be specific and actionable.');
     return sections.join('\n');
@@ -1409,6 +1440,11 @@ const metaJsonSchema = z
     _id: z.uuid(),
     /** Human-provided steering prompt. Optional. */
     _steer: z.string().optional(),
+    /**
+     * Explicit cross-references to other meta owner paths.
+     * Referenced metas' _content is included as architect/builder context.
+     */
+    _crossRefs: z.array(z.string()).optional(),
     /** Architect system prompt used this turn. Defaults from config. */
     _architect: z.string().optional(),
     /**
@@ -9913,6 +9949,27 @@ function registerMetasRoutes(app, deps) {
                 score: Math.round(score * 100) / 100,
             },
         };
+        // Cross-refs status
+        const crossRefsRaw = meta._crossRefs;
+        if (Array.isArray(crossRefsRaw) && crossRefsRaw.length > 0) {
+            response.crossRefs = crossRefsRaw.map((refPath) => {
+                const rp = String(refPath);
+                const refMetaFile = join(rp, '.meta', 'meta.json');
+                if (!existsSync(refMetaFile))
+                    return { path: rp, status: 'missing' };
+                try {
+                    const refMeta = JSON.parse(readFileSync(refMetaFile, 'utf8'));
+                    return {
+                        path: rp,
+                        status: 'resolved',
+                        hasContent: Boolean(refMeta._content),
+                    };
+                }
+                catch {
+                    return { path: rp, status: 'missing' };
+                }
+            });
+        }
         // Archive
         if (query.includeArchive) {
             const archiveFiles = listArchiveFiles(targetNode.metaPath);
@@ -10030,6 +10087,7 @@ function registerPreviewRoute(app, deps) {
  */
 const seedBodySchema = z.object({
     path: z.string().min(1),
+    crossRefs: z.array(z.string()).optional(),
 });
 function registerSeedRoute(app, deps) {
     app.post('/seed', (request, reply) => {
@@ -10044,6 +10102,8 @@ function registerSeedRoute(app, deps) {
         deps.logger.info({ metaDir }, 'creating .meta directory');
         mkdirSync(metaDir, { recursive: true });
         const metaJson = { _id: randomUUID() };
+        if (body.crossRefs !== undefined)
+            metaJson._crossRefs = body.crossRefs;
         const metaJsonPath = join(metaDir, 'meta.json');
         deps.logger.info({ metaJsonPath }, 'writing meta.json');
         writeFileSync(metaJsonPath, JSON.stringify(metaJson, null, 2) + '\n');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@karmaniverous/jeeves-meta",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "author": "Jason Williscroft",
   "description": "Fastify HTTP service for the Jeeves Meta synthesis engine",
   "license": "BSD-3-Clause",