@333eco/corpus 2.1.7 → 2.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@333eco/corpus",
-    "version": "2.1.7",
+    "version": "2.3.0",
     "description": "An MCP server for an open-licensed corpus, served with verifiable provenance — every document carries its sha256, DOI and OpenTimestamps proof so a consuming agent can check its own citation.",
     "license": "CC0-1.0",
     "author": "Thon Ly",

package/src/base-tools.mjs

@@ -63,10 +63,66 @@ export const BASE_TOOLS = [
         inputSchema: {
             type: "object",
             properties: {
-                genre: { type: "string", description: "Optional: restrict to a genre — essays, defensive-publications, positions, white-papers, letters, program." },
-                category: { type: "string", description: "Optional: restrict to a topic category — institutional (the four-body architecture and the institution itself), mechanism, alignment, essays, letters, program, capabilities. The response lists every category with its count." },
+                genre: { type: "string", description: "Optional: restrict to a genre." },
+                category: { type: "string", description: "Optional: restrict to a topic category. The response lists every category with its count." },
+                voice: { type: "string", description: "Optional: restrict by whose voice a document is in." },
                 licence: { type: "string", description: "Optional: restrict to a licence id, e.g. CC0-1.0 or CC-BY-4.0." }
             }
         }
     }
 ];
+
+
+// ── the facet enumerations, DERIVED ─────────────────────────────────────────
+//
+// ⚠️ THEY WERE TYPED INTO THE DESCRIPTIONS ABOVE. `list_documents` listed its own
+// genres and categories in prose — "essays, defensive-publications, positions,
+// white-papers, letters, program" — in a file nothing checks, read by agents that
+// act on it. Adding the `about` genre and the `voice` axis would have made two of
+// them wrong on the same day.
+//
+// ⭐ So the values come from the artifact being served. Both surfaces load the
+// same pinned corpus, so they cannot disagree, and a facet that gains a value
+// gains it in the description at the same moment it gains it in the data.
+//
+// ⚠️ The hand-written GLOSSES stay: "institutional" is worth explaining and no
+// count can explain it. A value with no gloss degrades to its bare name rather
+// than disappearing, which is the failure mode worth avoiding — an enumeration
+// that silently omits a value is worse than one with a terse entry.
+const GLOSS = {
+    institutional: "the four-body architecture and the institution itself",
+    founder: "Thon Ly's own voice",
+    collaborative: "the research corpus, disclosed as co-authored with Miss Aquarius\u2120",
+    "defensive-publications": "prior-art publications",
+    program: "the research programme and its register"
+};
+
+const enumerate = (values) =>
+    values
+        .map((v) => (GLOSS[v] ? `${v} (${GLOSS[v]})` : v))
+        .join(", ");
+
+/**
+ * Fill `list_documents`' facet enumerations from the corpus this server serves.
+ * Everything else is passed through untouched.
+ */
+export function withFacets(tools, corpus) {
+    if (!corpus || !Array.isArray(corpus.documents)) return tools;
+    const uniq = (key) =>
+        [...new Set(corpus.documents.map((d) => d[key]).filter(Boolean))].sort();
+    const genres = uniq("genre");
+    const categories = uniq("category");
+    const voices = Object.keys(corpus.voices || {}).sort();
+
+    return tools.map((t) => {
+        if (t.name !== "list_documents") return t;
+        const props = { ...t.inputSchema.properties };
+        if (genres.length)
+            props.genre = { ...props.genre, description: `Optional: restrict to a genre — ${enumerate(genres)}.` };
+        if (categories.length)
+            props.category = { ...props.category, description: `Optional: restrict to a topic category — ${enumerate(categories)}. The response lists every category with its count.` };
+        if (voices.length)
+            props.voice = { ...props.voice, description: `Optional: restrict by whose voice a document is in — ${enumerate(voices)}. Orthogonal to genre and category.` };
+        return { ...t, inputSchema: { ...t.inputSchema, properties: props } };
+    });
+}

package/src/search.mjs

@@ -10,7 +10,11 @@
 // ⚠️ WHY THIS REPLACED A BARE `indexOf`, and the evidence was a real caller.
 // The first external client to reach the hosted endpoint searched
 // `"gratitude alignment human wellbeing kindness"` and got ZERO results — while
-// `gratitude` alone returns 50, `alignment` 50, `kindness` 50, `wellbeing` 16.
+// while each of those terms alone matched many documents.
+// ⚠️ The per-term counts that used to sit on this line disagreed with the
+// README's copy of the same anecdote (50 here, 109 there, 112 in the live
+// corpus). A number in a comment about a corpus that grows is a number that
+// will be wrong; the point of the story does not need it.
 // The corpus was not missing the material; the matcher required that exact
 // five-word string to appear verbatim, which of course it never does. A literal
 // substring search silently punishes anyone who types a sentence, and it makes

package/src/server.mjs

@@ -38,7 +38,7 @@ import { RESOURCE_TEMPLATES, listResources, readResource, completeArgument } fro
 import { structured, structuredWithText } from "./results.mjs";
 import { provenanceHeader } from "./resources.mjs";
 import { PROMPTS, getPrompt } from "./prompts.mjs";
-import { BASE_TOOLS } from "./base-tools.mjs";
+import { BASE_TOOLS, withFacets } from "./base-tools.mjs";
 import { PROGRAM_TOOLS, PROGRAM_TOOL_NAMES, PROGRAM_INSTRUCTIONS, callProgramTool } from "./program-tools.mjs";
 import { match, rank, absentTerms } from "./search.mjs";
 
@@ -207,6 +207,14 @@ const callTool = (name, args) => {
         return structuredWithText(provenanceHeader(d) + "\n\n" + d.text, {
             ...envelope(d),
             genre: d.genre,
+            // ⚠️ category and voice were in list_documents and NOT here, so a
+            // caller who fetched ONE document could not see the facets it had
+            // just filtered on — the discovery call and the read call disagreed
+            // about what a document is. Both are cheap strings; the reason the
+            // body is excluded (it is in `content`, never sent twice) does not
+            // apply to them.
+            category: d.category,
+            voice: d.voice,
             repo: d.repo,
             path: d.path,
             metadata_convention: d.metadata_convention,
@@ -229,6 +237,7 @@ const callTool = (name, args) => {
         const list = corpus.documents
             .filter((d) => (!args?.genre || d.genre === args.genre) &&
                     (!args?.licence || d.licence.id === args.licence) &&
+                    (!args?.voice || d.voice === args.voice) &&
                     (!args?.category || d.category === args.category))
             .map((d) => ({
                 slug: d.slug,
@@ -239,6 +248,10 @@ const callTool = (name, args) => {
                 // `mechanism` the how-it-works shelf — the corpus already had a
                 // topic taxonomy and no way to ask it a question.
                 category: d.category,
+                // ⭐ WHO IS SPEAKING, derived from genre in the builder rather
+                // than stored per file. It is what makes "tell me about the
+                // founder" one call instead of three.
+                voice: d.voice,
                 date: d.date,
                 licence: d.licence.id,
                 doi: d.provenance.doi,
@@ -249,6 +262,10 @@ const callTool = (name, args) => {
             licences: corpus.licences,
             // The shelves, so a caller can narrow without guessing the vocabulary.
             categories: corpus.documents.reduce((a, d) => ((a[d.category ?? "uncategorised"] = (a[d.category ?? "uncategorised"] ?? 0) + 1), a), {}),
+            // Always the FULL count, never narrowed by the filter — a set of
+            // documents means nothing without the honest denominator beside it,
+            // the same reason list_predictions returns by_state unfiltered.
+            ...(corpus.voices ? { voices: corpus.voices } : {}),
             documents: list
         });
     }
@@ -277,7 +294,12 @@ const handlers = {
             "honour it. Text is returned verbatim and is never summarised, because a summary cannot be hash-verified." +
             (program ? PROGRAM_INSTRUCTIONS : "")
     }),
-    "tools/list": () => ({ tools: program ? [...TOOLS, ...PROGRAM_TOOLS] : TOOLS }),
+    // ⭐ withFacets fills list_documents' facet enumerations FROM THE CORPUS.
+    // They used to be typed into the description and would have been wrong twice
+    // over the day the `about` genre and the `voice` axis landed.
+    "tools/list": () => ({
+        tools: withFacets(program ? [...TOOLS, ...PROGRAM_TOOLS] : TOOLS, corpus)
+    }),
     "resources/list": (params) => listResources(corpus.documents, params?.cursor),
     "resources/templates/list": () => ({ resourceTemplates: RESOURCE_TEMPLATES }),
     "resources/read": (params) => readResource(params?.uri, bySlug),