@konneal/engine 0.2.118 → 0.2.119

package/dist/admin.d.ts

@@ -13,6 +13,14 @@ export declare function handleEnrich(env: Env, ctx: ExecutionContext, req: Reque
  *  descends from it to quotable leaf clauses (pipeline.ts section
  *  descent). Credential, batching and ledger mirror /admin/enrich. */
 export declare function handleSectionUnit(env: Env, ctx: ExecutionContext, req: Request): Promise<Response>;
+/** Family community summaries (TODO.sota/06 item 2): one precomputed
+ *  answer per publication family to "what is this family and what
+ *  changed between editions" — generated from the registry rows and
+ *  the successor graph (the family IS the corpus's natural community),
+ *  stored in KV under famsum:<family>, served by editionNote beside
+ *  the deterministic registry line. Admin-gated; idempotent (force
+ *  regenerates); the quality-first lane pays once. */
+export declare function handleFamilySummary(env: Env, req: Request): Promise<Response>;
 /** Ops access to the Vectorize binding (get/upsert by id) for offline
  *  passes like embedding smoothing (G-ETSI-4) — the binding is the
  *  credential, admin-token gated exactly like /admin/enrich. */

package/dist/{ask-ZZT67FEB.js → ask-YVBM6IEV.js}

@@ -1,8 +1,8 @@
 import {
   handleAsk
-} from "./chunk-UBQCQ4UQ.js";
+} from "./chunk-EGFTNES5.js";
 import "./chunk-32UDKBA2.js";
-import "./chunk-NUHZMAII.js";
+import "./chunk-IIQWESHC.js";
 import "./chunk-TH5XGPD5.js";
 import "./chunk-DJ65EF5G.js";
 import "./chunk-A3QHHUN5.js";

package/dist/{chunk-YNQ5BKQW.js → chunk-C5L55VI7.js}

@@ -6,7 +6,7 @@ import {
   sessionFrom,
   telemetry,
   understandQuery
-} from "./chunk-NUHZMAII.js";
+} from "./chunk-IIQWESHC.js";
 import {
   portModelRunner
 } from "./chunk-TH5XGPD5.js";

package/dist/{chunk-UBQCQ4UQ.js → chunk-EGFTNES5.js}

@@ -60,7 +60,7 @@ import {
   tokenBudget,
   understandQuery,
   usageTotal
-} from "./chunk-NUHZMAII.js";
+} from "./chunk-IIQWESHC.js";
 import {
   embed,
   generateOnce,

package/dist/{chunk-NUHZMAII.js → chunk-IIQWESHC.js}

@@ -24756,7 +24756,14 @@ async function editionNote(env, u) {
     ).bind(`% ${u.doc_number}:%`).all();
     const actives = (rows.results ?? []).map((r) => r.docidentifier);
     if (!actives.length) return void 0;
-    return `Publication registry (authoritative): the ACTIVE edition(s) for this publication are ${actives.join(", ")}. Passages from other editions are superseded \u2014 use them only for historical comparison and say so.`;
+    const famRow = await env.DB.prepare("SELECT family FROM documents WHERE docidentifier LIKE ?1 || '%:%' LIMIT 1").bind(`% ${u.doc_number}:%`).first().catch(() => null);
+    let summary = "";
+    if (famRow?.family && env.CACHE) {
+      summary = await env.CACHE.get(`famsum:${famRow.family}`).catch(() => "") ?? "";
+    }
+    const registry = `Publication registry (authoritative): the ACTIVE edition(s) for this publication are ${actives.join(", ")}. Passages from other editions are superseded \u2014 use them only for historical comparison and say so.`;
+    return summary ? `${registry}
+Family summary (precomputed from the registry and the successor graph): ${summary}` : registry;
   } catch {
     return void 0;
   }

package/dist/openapi-surface.gen.d.ts

@@ -3,7 +3,7 @@ export interface OpenApiRoute {
     pattern: string;
     operationId: string;
 }
-export type OpenApiOperationId = "askAnonymous" | "askKeyed" | "search" | "searchKeyed" | "verify" | "verifyKeyed" | "research" | "researchKeyed" | "mcp" | "datasets" | "keyUsage" | "health" | "listConversations" | "createConversation" | "getConversation" | "renameConversation" | "deleteConversation" | "appendMessage" | "shareConversation" | "getShared" | "uploadAttachment" | "listAttachments" | "getAttachment" | "deleteAttachment" | "listMemories" | "createMemory" | "deleteMemory" | "listProjects" | "createProject" | "deleteProject" | "listProjectFiles" | "attachProjectFile" | "detachProjectFile" | "laneQuery" | "laneKeyed" | "feedback" | "adminEnrich" | "adminEnrichAlias" | "adminSection" | "adminSectionAlias" | "adminVectors" | "adminCaption" | "adminJudge" | "adminJudgeAlias" | "adminRevokeKey" | "authMe" | "authLogin" | "authCallback" | "authLogout" | "authLogoutLink" | "adminStats" | "adminListKeys" | "adminCreateKey";
+export type OpenApiOperationId = "askAnonymous" | "askKeyed" | "search" | "searchKeyed" | "verify" | "verifyKeyed" | "research" | "researchKeyed" | "mcp" | "datasets" | "keyUsage" | "health" | "listConversations" | "createConversation" | "getConversation" | "renameConversation" | "deleteConversation" | "appendMessage" | "shareConversation" | "getShared" | "uploadAttachment" | "listAttachments" | "getAttachment" | "deleteAttachment" | "listMemories" | "createMemory" | "deleteMemory" | "listProjects" | "createProject" | "deleteProject" | "listProjectFiles" | "attachProjectFile" | "detachProjectFile" | "laneQuery" | "laneKeyed" | "feedback" | "adminEnrich" | "adminEnrichAlias" | "adminSection" | "adminFamilySummary" | "adminSectionAlias" | "adminFamilySummaryAlias" | "adminVectors" | "adminCaption" | "adminJudge" | "adminJudgeAlias" | "adminRevokeKey" | "authMe" | "authLogin" | "authCallback" | "authLogout" | "authLogoutLink" | "adminStats" | "adminListKeys" | "adminCreateKey";
 export declare const OPENAPI_SURFACE: readonly (Omit<OpenApiRoute, "operationId"> & {
     operationId: OpenApiOperationId;
 })[];

package/dist/openapi-types.d.ts

@@ -613,6 +613,26 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/admin/family-summary": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Write a family's community summary
+         * @description Generates the precomputed answer to "what is this family and what changed between editions" from the registry rows and the successor graph, and stores it in KV; editionNote serves it beside the deterministic registry line on doc-scoped answers. Families need at least two editions. force regenerates.
+         */
+        post: operations["adminFamilySummary"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/admin/section": {
         parameters: {
             query?: never;
@@ -633,6 +653,26 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/admin/family-summary": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Write a family's community summary (the operational path)
+         * @description The operational alias of /v1/admin/family-summary; the behaviour and the credential are identical.
+         */
+        post: operations["adminFamilySummaryAlias"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/admin/vectors": {
         parameters: {
             query?: never;
@@ -1932,6 +1972,33 @@ export interface operations {
             };
         };
     };
+    adminFamilySummary: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    /** @description The family key, for example R-60. */
+                    family: string;
+                    /** @default false */
+                    force?: boolean;
+                };
+            };
+        };
+        responses: {
+            /** @description The stored summary with its provenance counts. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     adminSectionAlias: {
         parameters: {
             query?: never;
@@ -1956,6 +2023,30 @@ export interface operations {
             };
         };
     };
+    adminFamilySummaryAlias: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    family: string;
+                };
+            };
+        };
+        responses: {
+            /** @description The stored summary. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     adminVectors: {
         parameters: {
             query?: never;

package/dist/prompts/family-summary.md

@@ -0,0 +1 @@
+You write the community summary of one publication family for {{PUBLISHER_NAME}}'s retrieval index — the precomputed answer to "what is this family and what changed between editions". The registry rows and the successor graph below are your ONLY facts. Write three to five sentences: what the family regulates or provides, its structure (parts, annexes), and the edition lineage — which editions are active, which are superseded, and what the successor chain says changed. Never invent a change the lineage does not show; when the chain only says one edition replaced another, say exactly that. Name editions exactly as the registry does. No preamble.

package/dist/{search-3PBQSMO4.js → search-JDSQPI3A.js}

@@ -1,7 +1,7 @@
 import {
   handleSearch
-} from "./chunk-YNQ5BKQW.js";
-import "./chunk-NUHZMAII.js";
+} from "./chunk-C5L55VI7.js";
+import "./chunk-IIQWESHC.js";
 import "./chunk-TH5XGPD5.js";
 import "./chunk-DJ65EF5G.js";
 import "./chunk-A3QHHUN5.js";

package/dist/worker_public/src/index.js

@@ -4,7 +4,7 @@ import {
   handleMemories,
   scoreFaithfulness,
   scoreJudge
-} from "../../chunk-UBQCQ4UQ.js";
+} from "../../chunk-EGFTNES5.js";
 import {
   TOOLS_REGISTRY,
   bindModelNode,
@@ -12,7 +12,7 @@ import {
 } from "../../chunk-32UDKBA2.js";
 import {
   handleSearch
-} from "../../chunk-YNQ5BKQW.js";
+} from "../../chunk-C5L55VI7.js";
 import {
   buildMessages,
   citations,
@@ -34,7 +34,7 @@ import {
   sessionFrom,
   telemetry,
   understandQuery
-} from "../../chunk-NUHZMAII.js";
+} from "../../chunk-IIQWESHC.js";
 import {
   cfBlobs,
   embed,
@@ -350,6 +350,10 @@ var enrichment_default = "You write a retrieval context for a passage from {{COR
 // workers/worker_public/prompts/doc-summary.md
 var doc_summary_default = "You write the document-level summary for a legal-metrology publication in {{PUBLISHER_NAME}}'s retrieval index. The section summaries below cover the publication clause by clause. Write one compact abstract, three to five sentences: what the publication regulates or provides, its scope and applicability, and the structure a reader should know (parts, annexes, where the normative core sits). Use the publication's own terms exactly. No preamble, no headings.\n";
 
+// workers/worker_public/prompts/family-summary.md
+var family_summary_default = `You write the community summary of one publication family for {{PUBLISHER_NAME}}'s retrieval index \u2014 the precomputed answer to "what is this family and what changed between editions". The registry rows and the successor graph below are your ONLY facts. Write three to five sentences: what the family regulates or provides, its structure (parts, annexes), and the edition lineage \u2014 which editions are active, which are superseded, and what the successor chain says changed. Never invent a change the lineage does not show; when the chain only says one edition replaced another, say exactly that. Name editions exactly as the registry does. No preamble.
+`;
+
 // workers/worker_public/prompts/section-summary.md
 var section_summary_default = "You summarize one numbered clause of a metrology publication for a retrieval index. You are given the publication, the clause number, and excerpts of its sub-clauses.\n\nWrite a dense summary of 3 to 5 sentences stating what the clause governs and how its sub-clauses divide the subject. Name each sub-clause number together with its topic, in document order.\n\nPlain factual prose. No preamble, no headings, no bullet list, no quotation marks around the whole text. Write in the same language as the excerpts.\n";
 
@@ -510,6 +514,51 @@ Covers: ${childAnchors}`;
   }
   return json({ results, usage });
 }
+async function handleFamilySummary(env, req) {
+  if (!env.ADMIN_TOKEN) return err(501, "admin_disabled", "ADMIN_TOKEN secret is not configured");
+  const auth = req.headers.get("authorization") ?? "";
+  if (auth !== `Bearer ${env.ADMIN_TOKEN}`) return err(401, "unauthorized", "Invalid admin token");
+  const body = await readJson(req);
+  const family = typeof body?.family === "string" ? body.family.trim().slice(0, 24) : "";
+  if (!/^[A-Z]+-\d+$/.test(family)) return err(400, "invalid_input", "family must look like R-60 (type-number)");
+  try {
+    const docs = await env.DB.prepare(
+      "SELECT docidentifier, edition, status, active, superseded_by, title FROM documents WHERE family = ?1 ORDER BY edition"
+    ).bind(family).all();
+    const rows = docs.results ?? [];
+    if (rows.length < 2) return json({ family, ok: false, note: "fewer than two editions \u2014 no lineage to summarize" });
+    const succ = await env.DB.prepare(
+      "SELECT e.src AS src, e.dst AS dst FROM graph_edges e WHERE e.kind = 'successor' AND (e.src IN (SELECT src FROM graph_edges WHERE kind = 'part_of' AND dst = ?2) OR e.dst IN (SELECT src FROM graph_edges WHERE kind = 'part_of' AND dst = ?2)) LIMIT 40"
+    ).bind(family, `family:${family}`).all();
+    const key = `famsum:${family}`;
+    const cached = body?.force === true ? null : await env.CACHE.get(key);
+    if (cached) return json({ family, ok: true, cached: true, summary: cached });
+    const listing = rows.map((r) => `- ${r.docidentifier} \u2014 ${r.status}${r.active ? " (ACTIVE)" : ""}${r.title ? ` \u2014 ${String(r.title).slice(0, 120)}` : ""}`).join("\n");
+    const chain = (succ.results ?? []).map((r) => `${String(r.src).replace("doc:", "")} \u2192 superseded by \u2192 ${String(r.dst).replace("doc:", "")}`).join("\n");
+    const model = typeof env.ENRICH_MODEL === "string" && env.ENRICH_MODEL ? env.ENRICH_MODEL : MODELS.enrich;
+    const res = await env.AI.run(model, {
+      messages: [
+        { role: "system", content: family_summary_default.trimEnd() },
+        { role: "user", content: `Family ${family}
+
+Registry rows:
+${listing}
+
+Successor chain:
+${chain || "(no successor edges recorded)"}` }
+      ],
+      max_tokens: 1600,
+      reasoning_effort: "low"
+    });
+    const raw = typeof res?.response === "string" && res.response.trim() ? res.response : res?.choices?.[0]?.message?.content;
+    const summary = typeof raw === "string" ? raw.trim().replace(/^["']|["']$/g, "").slice(0, 1200) : "";
+    if (!summary) return json({ family, ok: false, error: "empty summary" });
+    await env.CACHE.put(key, summary);
+    return json({ family, ok: true, cached: false, summary, editions: rows.length, successors: (succ.results ?? []).length });
+  } catch (e) {
+    return err(502, "family_summary_failed", String(e?.message ?? e).slice(0, 200));
+  }
+}
 async function handleCaption(env, req) {
   if (!env.ADMIN_TOKEN) return err(501, "admin_disabled", "ADMIN_TOKEN secret is not configured");
   const auth = req.headers.get("authorization") ?? "";
@@ -1000,7 +1049,7 @@ async function callToolOnce(env, ctx, _req, tier, key, name, args, t0) {
       const r = await runTool({ ...env, DB: env.DB }, { name, args }, "mcp");
       payload = r ? { tool: r.name, query: r.query, result: r.output } : { error: { message: `tool ${name} returned nothing for the given arguments` } };
     } else {
-      const res = name === "ask" ? await (await import("../../ask-ZZT67FEB.js")).handleAsk(env, ctx, inner, tier, key) : await (await import("../../search-3PBQSMO4.js")).handleSearch(env, ctx, inner, tier, key);
+      const res = name === "ask" ? await (await import("../../ask-YVBM6IEV.js")).handleAsk(env, ctx, inner, tier, key) : await (await import("../../search-JDSQPI3A.js")).handleSearch(env, ctx, inner, tier, key);
       payload = await res.json().catch(() => ({ error: { message: "tool transport failed", status: res.status } }));
     }
     telemetry(env, ctx, tier, `mcp:${name}`, null, !payload?.error, JSON.stringify(payload).length, await sha256Hex(`${name}:${JSON.stringify(args ?? {})}`), void 0, void 0, { durationMs: Date.now() - t0 });
@@ -1232,11 +1281,21 @@ var OPENAPI_SURFACE = [
     "pattern": "/v1/admin/section",
     "operationId": "adminSection"
   },
+  {
+    "method": "POST",
+    "pattern": "/v1/admin/family-summary",
+    "operationId": "adminFamilySummary"
+  },
   {
     "method": "POST",
     "pattern": "/admin/section",
     "operationId": "adminSectionAlias"
   },
+  {
+    "method": "POST",
+    "pattern": "/admin/family-summary",
+    "operationId": "adminFamilySummaryAlias"
+  },
   {
     "method": "POST",
     "pattern": "/admin/vectors",
@@ -1772,6 +1831,8 @@ var OPENAPI_HANDLERS = {
   adminEnrich: (c) => handleEnrich(c.env, c.ctx, c.req),
   adminEnrichAlias: (c) => handleEnrich(c.env, c.ctx, c.req),
   adminSection: (c) => handleSectionUnit(c.env, c.ctx, c.req),
+  adminFamilySummary: (c) => handleFamilySummary(c.env, c.req),
+  adminFamilySummaryAlias: (c) => handleFamilySummary(c.env, c.req),
   adminSectionAlias: (c) => handleSectionUnit(c.env, c.ctx, c.req),
   adminVectors: (c) => handleVectors(c.env, c.req),
   adminCaption: (c) => handleCaption(c.env, c.req),

package/package.json

@@ -27,7 +27,7 @@
     "playwright": "^1.62.1",
     "yaml": "^2.9.1"
   },
-  "version": "0.2.118",
+  "version": "0.2.119",
   "description": "The Konneal engine: the publisher-agnostic build pipeline and API plane for standards intelligence (retrieval, answer contract, verdicts, evaluation).",
   "license": "BSD-3-Clause",
   "type": "module",

package/workers/worker_public/openapi.yaml

@@ -866,6 +866,35 @@ paths:
       responses:
         '200':
           description: The written units with their usage.
+  /v1/admin/family-summary:
+    post:
+      tags: [Administration]
+      summary: Write a family's community summary
+      description: >-
+        Generates the precomputed answer to "what is this family and
+        what changed between editions" from the registry rows and the
+        successor graph, and stores it in KV; editionNote serves it
+        beside the deterministic registry line on doc-scoped answers.
+        Families need at least two editions. force regenerates.
+      operationId: adminFamilySummary
+      security: [{ adminAuth: [] }]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [family]
+              properties:
+                family:
+                  type: string
+                  description: The family key, for example R-60.
+                force:
+                  type: boolean
+                  default: false
+      responses:
+        '200':
+          description: The stored summary with its provenance counts.
   /admin/section:
     post:
       tags: [Administration]
@@ -887,6 +916,27 @@ paths:
       responses:
         '200':
           description: The written units with their usage.
+  /admin/family-summary:
+    post:
+      tags: [Administration]
+      summary: Write a family's community summary (the operational path)
+      description: >-
+        The operational alias of /v1/admin/family-summary; the behaviour
+        and the credential are identical.
+      operationId: adminFamilySummaryAlias
+      security: [{ adminAuth: [] }]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [family]
+              properties:
+                family: { type: string }
+      responses:
+        '200':
+          description: The stored summary.
   /admin/vectors:
     post:
       tags: [Administration]

package/workers/worker_public/prompts/family-summary.md

@@ -0,0 +1 @@
+You write the community summary of one publication family for {{PUBLISHER_NAME}}'s retrieval index — the precomputed answer to "what is this family and what changed between editions". The registry rows and the successor graph below are your ONLY facts. Write three to five sentences: what the family regulates or provides, its structure (parts, annexes), and the edition lineage — which editions are active, which are superseded, and what the successor chain says changed. Never invent a change the lineage does not show; when the chain only says one edition replaced another, say exactly that. Name editions exactly as the registry does. No preamble.

package/workers/worker_public/src/admin.ts

@@ -7,6 +7,7 @@ import { err, json, corsHeaders, readJson, authenticate } from "./lib/http";
 import type { Env } from "./env";
 import enrichmentPrompt from "../prompts/enrichment.md";
 import docSummaryPrompt from "../prompts/doc-summary.md";
+import familySummaryPrompt from "../prompts/family-summary.md";
 import sectionSummaryPrompt from "../prompts/section-summary.md";
 import relevancyPrompt from "../prompts/relevancy.md";
 import precisionPrompt from "../prompts/precision.md";
@@ -202,6 +203,55 @@ export async function handleSectionUnit(env: Env, ctx: ExecutionContext, req: Re
   return json({ results, usage });
 }
 
+/** Family community summaries (TODO.sota/06 item 2): one precomputed
+ *  answer per publication family to "what is this family and what
+ *  changed between editions" — generated from the registry rows and
+ *  the successor graph (the family IS the corpus's natural community),
+ *  stored in KV under famsum:<family>, served by editionNote beside
+ *  the deterministic registry line. Admin-gated; idempotent (force
+ *  regenerates); the quality-first lane pays once. */
+export async function handleFamilySummary(env: Env, req: Request): Promise<Response> {
+  if (!env.ADMIN_TOKEN) return err(501, "admin_disabled", "ADMIN_TOKEN secret is not configured");
+  const auth = req.headers.get("authorization") ?? "";
+  if (auth !== `Bearer ${env.ADMIN_TOKEN}`) return err(401, "unauthorized", "Invalid admin token");
+  const body = await readJson(req);
+  const family = typeof body?.family === "string" ? body.family.trim().slice(0, 24) : "";
+  if (!/^[A-Z]+-\d+$/.test(family)) return err(400, "invalid_input", "family must look like R-60 (type-number)");
+  try {
+    const docs = await env.DB.prepare(
+      "SELECT docidentifier, edition, status, active, superseded_by, title FROM documents WHERE family = ?1 ORDER BY edition",
+    ).bind(family).all<any>();
+    const rows = docs.results ?? [];
+    if (rows.length < 2) return json({ family, ok: false, note: "fewer than two editions — no lineage to summarize" });
+    // the family's docs through the part_of edges (publisher-pure: no
+    // identifier literal — the family node is the join key)
+    const succ = await env.DB.prepare(
+      "SELECT e.src AS src, e.dst AS dst FROM graph_edges e WHERE e.kind = 'successor' AND (e.src IN (SELECT src FROM graph_edges WHERE kind = 'part_of' AND dst = ?2) OR e.dst IN (SELECT src FROM graph_edges WHERE kind = 'part_of' AND dst = ?2)) LIMIT 40",
+    ).bind(family, `family:${family}`).all<any>();
+    const key = `famsum:${family}`;
+    const cached = body?.force === true ? null : await env.CACHE.get(key);
+    if (cached) return json({ family, ok: true, cached: true, summary: cached });
+    const listing = rows.map((r: any) => `- ${r.docidentifier} — ${r.status}${r.active ? " (ACTIVE)" : ""}${r.title ? ` — ${String(r.title).slice(0, 120)}` : ""}`).join("\n");
+    const chain = ((succ.results ?? []) as any[]).map((r: any) => `${String(r.src).replace("doc:", "")} → superseded by → ${String(r.dst).replace("doc:", "")}`).join("\n");
+    const model = typeof env.ENRICH_MODEL === "string" && env.ENRICH_MODEL ? env.ENRICH_MODEL : MODELS.enrich;
+    const res: any = await env.AI.run(model, {
+      messages: [
+        { role: "system", content: familySummaryPrompt.trimEnd() },
+        { role: "user", content: `Family ${family}\n\nRegistry rows:\n${listing}\n\nSuccessor chain:\n${chain || "(no successor edges recorded)"}` },
+      ],
+      max_tokens: 1600,
+      reasoning_effort: "low",
+    });
+    const raw = typeof res?.response === "string" && res.response.trim() ? res.response : res?.choices?.[0]?.message?.content;
+    const summary = typeof raw === "string" ? raw.trim().replace(/^["']|["']$/g, "").slice(0, 1200) : "";
+    if (!summary) return json({ family, ok: false, error: "empty summary" });
+    await env.CACHE.put(key, summary);
+    return json({ family, ok: true, cached: false, summary, editions: rows.length, successors: (succ.results ?? []).length });
+  } catch (e: any) {
+    return err(502, "family_summary_failed", String(e?.message ?? e).slice(0, 200));
+  }
+}
+
 /** Ops access to the Vectorize binding (get/upsert by id) for offline
  *  passes like embedding smoothing (G-ETSI-4) — the binding is the
  *  credential, admin-token gated exactly like /admin/enrich. */

package/workers/worker_public/src/graph.ts

@@ -55,7 +55,20 @@ export async function editionNote(env: Env, u: { doc_number?: string | null } |
       .all<{ docidentifier: string }>();
     const actives = (rows.results ?? []).map((r) => r.docidentifier);
     if (!actives.length) return undefined;
-    return `Publication registry (authoritative): the ACTIVE edition(s) for this publication are ${actives.join(", ")}. Passages from other editions are superseded — use them only for historical comparison and say so.`;
+    // the family's community summary (TODO.sota/06): the precomputed
+    // what-changed-between-editions answer rides beside the
+    // deterministic registry line — provenance-carrying (generated from
+    // the registry and the successor graph, never free narration)
+    const famRow = await env.DB.prepare("SELECT family FROM documents WHERE docidentifier LIKE ?1 || '%:%' LIMIT 1")
+      .bind(`% ${u.doc_number}:%`)
+      .first<{ family: string }>()
+      .catch(() => null);
+    let summary = "";
+    if (famRow?.family && env.CACHE) {
+      summary = ((await env.CACHE.get(`famsum:${famRow.family}`).catch(() => "")) ?? "");
+    }
+    const registry = `Publication registry (authoritative): the ACTIVE edition(s) for this publication are ${actives.join(", ")}. Passages from other editions are superseded — use them only for historical comparison and say so.`;
+    return summary ? `${registry}\nFamily summary (precomputed from the registry and the successor graph): ${summary}` : registry;
   } catch {
     return undefined;
   }

package/workers/worker_public/src/index.ts

@@ -22,7 +22,7 @@ export type { Env };
 import { json, err, corsHeaders, withCors, readJson, authenticate, type ApiKey } from "./lib/http";
 
 import { handleSearch } from "./search";
-import { handleEnrich, handleSectionUnit, handleCaption, handleVectors, handleJudge, handleCreateKey, handleListKeys, handleRevokeKey, handleKeyUsage } from "./admin";
+import { handleEnrich, handleSectionUnit, handleCaption, handleVectors, handleJudge, handleCreateKey, handleListKeys, handleRevokeKey, handleKeyUsage, handleFamilySummary } from "./admin";
 import { handleResearch } from "./research";
 import { uploadAttachment, readAttachment, deleteAttachment, type AttachmentDeps } from "./attachments";
 import { cfBlobs } from "./ports/cloudflare/adapters";
@@ -618,6 +618,8 @@ const OPENAPI_HANDLERS: Record<OpenApiOperationId, RouteHandler> = {
   adminEnrich: (c) => handleEnrich(c.env, c.ctx, c.req),
   adminEnrichAlias: (c) => handleEnrich(c.env, c.ctx, c.req),
   adminSection: (c) => handleSectionUnit(c.env, c.ctx, c.req),
+  adminFamilySummary: (c) => handleFamilySummary(c.env, c.req),
+  adminFamilySummaryAlias: (c) => handleFamilySummary(c.env, c.req),
   adminSectionAlias: (c) => handleSectionUnit(c.env, c.ctx, c.req),
   adminVectors: (c) => handleVectors(c.env, c.req),
   adminCaption: (c) => handleCaption(c.env, c.req),

package/workers/worker_public/src/openapi-surface.gen.ts

@@ -46,7 +46,9 @@ export type OpenApiOperationId =
   | "adminEnrich"
   | "adminEnrichAlias"
   | "adminSection"
+  | "adminFamilySummary"
   | "adminSectionAlias"
+  | "adminFamilySummaryAlias"
   | "adminVectors"
   | "adminCaption"
   | "adminJudge"
@@ -257,11 +259,21 @@ export const OPENAPI_SURFACE: readonly (Omit<OpenApiRoute, "operationId"> & { op
     "pattern": "/v1/admin/section",
     "operationId": "adminSection"
   },
+  {
+    "method": "POST",
+    "pattern": "/v1/admin/family-summary",
+    "operationId": "adminFamilySummary"
+  },
   {
     "method": "POST",
     "pattern": "/admin/section",
     "operationId": "adminSectionAlias"
   },
+  {
+    "method": "POST",
+    "pattern": "/admin/family-summary",
+    "operationId": "adminFamilySummaryAlias"
+  },
   {
     "method": "POST",
     "pattern": "/admin/vectors",