@scalemule/news-publication 0.0.83 → 0.0.85

package/README.md

@@ -324,7 +324,7 @@ The publisher-supplied `PawMark` preserves the approved SVG paths. Hosts may set
 
 ### Homepage image identity
 
-`NewsItem.visual_identity` is a versioned public identity from the Blog feed. `composeEdition` allocates covers across the entire bounded inventory, gives the selected lead priority, and holds repeated covers as `null` without dropping stories or mutating inputs. Never re-add duplicate images as fallback. Legacy Photo rendition URLs are normalized by tenant/asset ID; server-side Photo identity detects copies under different IDs and ordinary resize/re-encoding/crop variants. Do not fetch or decode images in page components. Preserve existing caption/credit policy. See platform `docs/HOMEPAGE-PHOTO-IDENTITY.md` for storage, rights, concurrency and rollout tests.
+`NewsItem.visual_identity` is a versioned public identity from the Blog feed. `composeEdition` allocates covers across the entire bounded inventory and holds repeated covers as `null` without mutating inputs. Lead, secondary, compact and section image placements require a usable distinct cover, including pinned stories. A held lead yields to the first ready story; an entirely unready inventory has no visual lead. Intentional briefs retain their editorial selection rules. `pendingImages` and the complete `navigation` inventory retain unresolved stories for repair and discovery: excluding them from image placements does not mean their photos were repaired. Consumer planners must not refill image placements from raw inventory or reintroduce duplicate covers. Legacy Photo rendition URLs are normalized by tenant/asset ID; server-side Photo identity detects copies under different IDs and ordinary resize/re-encoding/crop variants. Do not fetch or decode images in page components. Preserve existing caption/credit policy. See platform `docs/HOMEPAGE-PHOTO-IDENTITY.md` for storage, rights, concurrency and rollout tests.
 
 ### Standard article submission
 
@@ -377,7 +377,7 @@ matches one declared slot. Credentials are normal project/member credentials.
 The operation key is retained for 30 days. A legacy article must first have an
 explicitly selected collaboration policy; this endpoint never downgrades review.
 
-### Edit article prose, cards and citations
+### Edit article prose, cards, citations and tags
 
 ```sh
 npx --yes --package @scalemule/news-publication@0.0.81 scalemule-article edit \
@@ -385,7 +385,10 @@ npx --yes --package @scalemule/news-publication@0.0.81 scalemule-article edit \
 ```
 
 The patch may contain title, subtitle, content_markdown, excerpt, section,
-community, format, layout, cards and citations. It preserves omitted fields and
+community, format, layout, cards, citations and `tag_ids`. Tag edits require SDK
+0.0.85+ and the deployed `versioned_editorial_tags` capability. Supply up to 32
+existing tenant-owned tag UUIDs; an empty array clears assignments. Create or
+select tags using the ordinary Blog tags API first. It preserves omitted fields and
 media and saves one immutable revision. Default: save for review. Add
 `--release` only to request release through the existing policy; the command
 never issues APPROVE or downgrades review. On a legacy article, explicitly choose
@@ -402,7 +405,7 @@ Unknown save/release responses reconcile against the original revision; another
 current revision stops rather than being overwritten. Completed replay and no-op
 edits add no revision. `RELEASE_HELD`/exit 2 preserves the saved revision while
 review is pending. With `--url --release`, success requires the rendered
-headline, prose and actual card components; public visibility pending is also
+headline, prose, actual card components and requested canonical tag links; public visibility pending is also
 exit 2. A saved revision and a rendered published correction are separate states.
 
 Use the same client method, `client.editArticle`, for a caller-supplied durable

package/bin/scalemule-article.mjs

@@ -18,7 +18,7 @@ Credentials: SCALEMULE_API_KEY and SCALEMULE_ACCESS_TOKEN (normal authorized mem
 Platform admins may use their normal access token with --application-id ID.
 Optional --api-url URL defaults to https://api.scalemule.com.
 
-edit saves prose, excerpt, cards and citations in one immutable revision.
+edit saves prose, excerpt, cards, citations and tenant-owned tag_ids in one immutable revision.
 Unspecified fields and media are retained. Default: save for review.
 --release explicitly requests release under the existing policy; it never issues
 APPROVE or changes a policy. Legacy onboarding requires an explicit
@@ -157,11 +157,11 @@ try {
             while(!verified){
               const response=await fetch(values.url,{redirect:'error',cache:'no-store',signal:AbortSignal.timeout(Math.min(5000,remaining()))});
               const html=await response.text();
-              verified=response.ok&&articleEditHtmlMatches(html,{title:article.title,content_html:article.content_html,card_titles:(article.metadata?.cards??[]).map(c=>c.title)});
+              verified=response.ok&&articleEditHtmlMatches(html,{title:article.title,content_html:article.content_html,card_titles:(article.metadata?.cards??[]).map(c=>c.title),tags:checkpoint.document.tag_ids?article.tags:undefined});
               if(!verified)await new Promise(r=>setTimeout(r,Math.min(300,remaining())));
             }
           }catch(error){reason=error.message;}
-          if(!verified){console.error(JSON.stringify({...result,state:'published_public_verification_pending',stage:'public_page',message:'The exact revision is published; rendered prose/cards remain unverified. Resume the same edit.',reason}));process.exitCode=2;}
+          if(!verified){console.error(JSON.stringify({...result,state:'published_public_verification_pending',stage:'public_page',message:'The exact revision is published; rendered prose/cards/tags remain unverified. Resume the same edit.',reason}));process.exitCode=2;}
           else console.log(JSON.stringify({...result,public_page_verified:true,total_elapsed_ms:Math.round(performance.now()-commandStarted)},null,2));
         }else{
         console.log(JSON.stringify({...result,total_elapsed_ms:Math.round(performance.now()-commandStarted)},null,2));

package/dist/article-workflow-client.cjs

@@ -43,6 +43,17 @@ function articleEditHtmlMatches(html, expected) {
   const all = text(visible);
   if (!paragraphs.length || !paragraphs.every((p) => all.includes(p)))
     return false;
+  if (expected.tags?.length) {
+    const links = [...visible.matchAll(/<a\b[^>]*href=["']([^"']+)["'][^>]*>([\s\S]*?)<\/a>/giu)];
+    if (!expected.tags.every((tag) => links.some((link) => {
+      try {
+        const url = new URL(decode(link[1]), "https://publication.example");
+        return url.pathname === "/news" && url.searchParams.get("tag") === tag.slug && text(link[2]).replace(/^#\s*/u, "") === tag.name;
+      } catch {
+        return false;
+      }
+    }))) return false;
+  }
   const titles = [
     ...visible.matchAll(
       /<aside\b[^>]*class=["'][^"']*\barticle-verified-card\b[^"']*["'][^>]*>([\s\S]*?)<\/aside>/giu
@@ -365,7 +376,8 @@ var patchKeys = /* @__PURE__ */ new Set([
   "format",
   "layout",
   "cards",
-  "citations"
+  "citations",
+  "tag_ids"
 ]);
 function validate(input) {
   if (!input.operationKey || !/^[\w.:-]{1,128}$/u.test(input.operationKey) || !input.articleId || !input.patch || typeof input.patch !== "object" || Array.isArray(input.patch) || !Object.keys(input.patch).length)
@@ -374,7 +386,10 @@ function validate(input) {
     );
   for (const [key, value] of Object.entries(input.patch)) {
     if (!patchKeys.has(key)) throw Error("Unsupported edit field: " + key);
-    if (["cards", "citations"].includes(key)) {
+    if (key === "tag_ids") {
+      if (!Array.isArray(value) || value.length > 32 || new Set(value).size !== value.length || value.some((id) => typeof id !== "string" || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu.test(id) || /^0{8}-0{4}-0{4}-0{4}-0{12}$/u.test(id)))
+        throw Error("tag_ids must contain at most 32 distinct, nonempty UUIDs");
+    } else if (["cards", "citations"].includes(key)) {
       if (!Array.isArray(value)) throw Error(key + " must be an array");
     } else if (key === "layout") {
       if (!value || typeof value !== "object" || typeof value.id !== "string" || !Number.isInteger(value.version))
@@ -458,6 +473,8 @@ async function runArticleEdit(t, input) {
         stage,
         "The server must expose versioned_editorial_fields before this edit; no article was changed"
       );
+    if (input.patch.tag_ids !== void 0 && options.capabilities?.versioned_editorial_tags !== true)
+      throw new ArticleEditOperationError("CAPABILITY_UNAVAILABLE", stage, "The server must expose versioned_editorial_tags before changing tags; no article was changed");
     if (!identityMatches(source))
       throw new ArticleEditOperationError(
         "ARTICLE_IDENTITY_CHANGED",
@@ -621,6 +638,8 @@ async function runArticleEdit(t, input) {
           409,
           state.revisionId
         );
+    if (state.document?.tag_ids && !equal([...state.document.tag_ids].sort(), (after.tags ?? []).map((tag) => tag.id).sort()))
+      throw new ArticleEditOperationError("VERIFICATION_CONFLICT", stage, "Published tags differ from the saved revision", 409, state.revisionId);
     const normalizedCards = state.document?.cards;
     if (normalizedCards && after.metadata?.cards?.length !== normalizedCards.length)
       throw new ArticleEditOperationError(

package/dist/article-workflow-client.d.cts

@@ -8,6 +8,10 @@ declare function articleEditHtmlMatches(html: string, expected: {
     title: string;
     content_html: string;
     card_titles: string[];
+    tags?: {
+        name: string;
+        slug: string;
+    }[];
 }): boolean;
 
 type PhotoOperationCheckpoint = {
@@ -48,7 +52,7 @@ declare class ArticlePhotoOperationError extends Error {
     constructor(code: string, stage: string, message: string, fileId?: string | undefined, status?: number | undefined);
 }
 
-type ArticleEditPatch = Partial<Pick<ArticleDocument, "title" | "subtitle" | "content_markdown" | "excerpt" | "section" | "community" | "format" | "layout" | "cards" | "citations">>;
+type ArticleEditPatch = Partial<Pick<ArticleDocument, "title" | "subtitle" | "content_markdown" | "excerpt" | "section" | "community" | "format" | "layout" | "cards" | "citations" | "tag_ids">>;
 type ArticleEditCheckpoint = {
     version: 1;
     identity: string;
@@ -93,6 +97,7 @@ type ArticleDocument = {
     excerpt?: string;
     cards?: unknown[];
     citations?: unknown[];
+    tag_ids?: string[];
     section: string;
     community?: string;
     format?: ArticleFormat;
@@ -195,6 +200,7 @@ type ArticleWorkflowOptions = {
         prioritized_narration_processing?: boolean;
         content_first_editor_document?: boolean;
         versioned_editorial_fields?: boolean;
+        versioned_editorial_tags?: boolean;
         managed_submission_version?: number | null;
         multipart_submission?: boolean;
     };

package/dist/article-workflow-client.d.ts

@@ -8,6 +8,10 @@ declare function articleEditHtmlMatches(html: string, expected: {
     title: string;
     content_html: string;
     card_titles: string[];
+    tags?: {
+        name: string;
+        slug: string;
+    }[];
 }): boolean;
 
 type PhotoOperationCheckpoint = {
@@ -48,7 +52,7 @@ declare class ArticlePhotoOperationError extends Error {
     constructor(code: string, stage: string, message: string, fileId?: string | undefined, status?: number | undefined);
 }
 
-type ArticleEditPatch = Partial<Pick<ArticleDocument, "title" | "subtitle" | "content_markdown" | "excerpt" | "section" | "community" | "format" | "layout" | "cards" | "citations">>;
+type ArticleEditPatch = Partial<Pick<ArticleDocument, "title" | "subtitle" | "content_markdown" | "excerpt" | "section" | "community" | "format" | "layout" | "cards" | "citations" | "tag_ids">>;
 type ArticleEditCheckpoint = {
     version: 1;
     identity: string;
@@ -93,6 +97,7 @@ type ArticleDocument = {
     excerpt?: string;
     cards?: unknown[];
     citations?: unknown[];
+    tag_ids?: string[];
     section: string;
     community?: string;
     format?: ArticleFormat;
@@ -195,6 +200,7 @@ type ArticleWorkflowOptions = {
         prioritized_narration_processing?: boolean;
         content_first_editor_document?: boolean;
         versioned_editorial_fields?: boolean;
+        versioned_editorial_tags?: boolean;
         managed_submission_version?: number | null;
         multipart_submission?: boolean;
     };

package/dist/article-workflow-client.js

@@ -41,6 +41,17 @@ function articleEditHtmlMatches(html, expected) {
   const all = text(visible);
   if (!paragraphs.length || !paragraphs.every((p) => all.includes(p)))
     return false;
+  if (expected.tags?.length) {
+    const links = [...visible.matchAll(/<a\b[^>]*href=["']([^"']+)["'][^>]*>([\s\S]*?)<\/a>/giu)];
+    if (!expected.tags.every((tag) => links.some((link) => {
+      try {
+        const url = new URL(decode(link[1]), "https://publication.example");
+        return url.pathname === "/news" && url.searchParams.get("tag") === tag.slug && text(link[2]).replace(/^#\s*/u, "") === tag.name;
+      } catch {
+        return false;
+      }
+    }))) return false;
+  }
   const titles = [
     ...visible.matchAll(
       /<aside\b[^>]*class=["'][^"']*\barticle-verified-card\b[^"']*["'][^>]*>([\s\S]*?)<\/aside>/giu
@@ -363,7 +374,8 @@ var patchKeys = /* @__PURE__ */ new Set([
   "format",
   "layout",
   "cards",
-  "citations"
+  "citations",
+  "tag_ids"
 ]);
 function validate(input) {
   if (!input.operationKey || !/^[\w.:-]{1,128}$/u.test(input.operationKey) || !input.articleId || !input.patch || typeof input.patch !== "object" || Array.isArray(input.patch) || !Object.keys(input.patch).length)
@@ -372,7 +384,10 @@ function validate(input) {
     );
   for (const [key, value] of Object.entries(input.patch)) {
     if (!patchKeys.has(key)) throw Error("Unsupported edit field: " + key);
-    if (["cards", "citations"].includes(key)) {
+    if (key === "tag_ids") {
+      if (!Array.isArray(value) || value.length > 32 || new Set(value).size !== value.length || value.some((id) => typeof id !== "string" || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu.test(id) || /^0{8}-0{4}-0{4}-0{4}-0{12}$/u.test(id)))
+        throw Error("tag_ids must contain at most 32 distinct, nonempty UUIDs");
+    } else if (["cards", "citations"].includes(key)) {
       if (!Array.isArray(value)) throw Error(key + " must be an array");
     } else if (key === "layout") {
       if (!value || typeof value !== "object" || typeof value.id !== "string" || !Number.isInteger(value.version))
@@ -456,6 +471,8 @@ async function runArticleEdit(t, input) {
         stage,
         "The server must expose versioned_editorial_fields before this edit; no article was changed"
       );
+    if (input.patch.tag_ids !== void 0 && options.capabilities?.versioned_editorial_tags !== true)
+      throw new ArticleEditOperationError("CAPABILITY_UNAVAILABLE", stage, "The server must expose versioned_editorial_tags before changing tags; no article was changed");
     if (!identityMatches(source))
       throw new ArticleEditOperationError(
         "ARTICLE_IDENTITY_CHANGED",
@@ -619,6 +636,8 @@ async function runArticleEdit(t, input) {
           409,
           state.revisionId
         );
+    if (state.document?.tag_ids && !equal([...state.document.tag_ids].sort(), (after.tags ?? []).map((tag) => tag.id).sort()))
+      throw new ArticleEditOperationError("VERIFICATION_CONFLICT", stage, "Published tags differ from the saved revision", 409, state.revisionId);
     const normalizedCards = state.document?.cards;
     if (normalizedCards && after.metadata?.cards?.length !== normalizedCards.length)
       throw new ArticleEditOperationError(

package/dist/index.cjs

@@ -188,7 +188,7 @@ function composeEdition(items, selection = {}, now = Date.now()) {
     return true;
   });
   const pins = !selection.pinned_until || Date.parse(selection.pinned_until) > now ? selection : {};
-  const selectedLead = inventory.find((item) => item.slug === pins.lead_slug) ?? inventory[0];
+  const selectedLead = inventory.find((item) => item.slug === pins.lead_slug && coverIdentity(item)) ?? inventory.find((item) => coverIdentity(item));
   const rest = inventory.filter((item) => item !== selectedLead);
   const requested = new Set(pins.secondary_slugs ?? []);
   const ordered = [
@@ -197,13 +197,11 @@ function composeEdition(items, selection = {}, now = Date.now()) {
   ];
   const originalOrder = Array.from(new Map(ordered.map((item) => [item.id, item])).values());
   const seenImages = /* @__PURE__ */ new Set();
-  const duplicateImages = /* @__PURE__ */ new Set();
   const display = /* @__PURE__ */ new Map();
   for (const item of [selectedLead, ...originalOrder]) {
     if (!item) continue;
     const key = coverIdentity(item);
     if (key && seenImages.has(key)) {
-      duplicateImages.add(item.id);
       display.set(item.id, { ...item, cover_image_url: null });
     } else {
       display.set(item.id, item);
@@ -214,14 +212,7 @@ function composeEdition(items, selection = {}, now = Date.now()) {
   const lead = selectedLead ? display.get(selectedLead.id) : void 0;
   let remaining = rest.map((item) => display.get(item.id));
   const uniqueOrdered = originalOrder.map((item) => display.get(item.id));
-  const secondary = [];
-  const deferred = [];
-  for (const item of uniqueOrdered) {
-    if (secondary.length >= 3) break;
-    if (duplicateImages.has(item.id)) deferred.push(item);
-    else secondary.push(item);
-  }
-  while (secondary.length < 3 && deferred.length > 0) secondary.push(deferred.shift());
+  const secondary = uniqueOrdered.filter((item) => coverIdentity(item)).slice(0, 3);
   const secondaryIds = new Set(secondary.map((item) => item.id));
   remaining = remaining.filter((item) => !secondaryIds.has(item.id));
   const eligible2 = remaining.filter((item) => {
@@ -236,10 +227,11 @@ function composeEdition(items, selection = {}, now = Date.now()) {
     briefIds.add(item.id);
     return true;
   });
-  const compact = [...briefs, ...remaining.filter((item) => !briefIds.has(item.id))].slice(0, 4);
+  const compact = [...briefs, ...remaining.filter((item) => !briefIds.has(item.id))].filter((item) => coverIdentity(item)).slice(0, 4);
   const compactIds = new Set(compact.map((item) => item.id));
-  const sections2 = editorialSections(remaining.filter((item) => !compactIds.has(item.id)));
-  return { lead, secondary, briefs, compact, sections: sections2, navigation: editorialSections(inventory) };
+  const sections2 = editorialSections(remaining.filter((item) => !compactIds.has(item.id) && coverIdentity(item)));
+  const pendingImages = inventory.filter((item) => !coverIdentity(item));
+  return { lead, secondary, briefs, compact, sections: sections2, pendingImages, navigation: editorialSections(inventory) };
 }
 function displayHeadline(article, selection = {}) {
   return selection.stories?.[article.slug]?.display_title?.trim() || article.title;

package/dist/index.d.cts

@@ -246,6 +246,7 @@ declare function composeEdition(items: NewsItem[], selection?: HomepageSelection
     briefs: NewsItem[];
     compact: NewsItem[];
     sections: EditorialSection[];
+    pendingImages: NewsItem[];
     navigation: EditorialSection[];
 };
 declare function displayHeadline(article: NewsItem, selection?: HomepageSelection): string;

package/dist/index.d.ts

@@ -246,6 +246,7 @@ declare function composeEdition(items: NewsItem[], selection?: HomepageSelection
     briefs: NewsItem[];
     compact: NewsItem[];
     sections: EditorialSection[];
+    pendingImages: NewsItem[];
     navigation: EditorialSection[];
 };
 declare function displayHeadline(article: NewsItem, selection?: HomepageSelection): string;

package/dist/index.js

@@ -132,7 +132,7 @@ function composeEdition(items, selection = {}, now = Date.now()) {
     return true;
   });
   const pins = !selection.pinned_until || Date.parse(selection.pinned_until) > now ? selection : {};
-  const selectedLead = inventory.find((item) => item.slug === pins.lead_slug) ?? inventory[0];
+  const selectedLead = inventory.find((item) => item.slug === pins.lead_slug && coverIdentity(item)) ?? inventory.find((item) => coverIdentity(item));
   const rest = inventory.filter((item) => item !== selectedLead);
   const requested = new Set(pins.secondary_slugs ?? []);
   const ordered = [
@@ -141,13 +141,11 @@ function composeEdition(items, selection = {}, now = Date.now()) {
   ];
   const originalOrder = Array.from(new Map(ordered.map((item) => [item.id, item])).values());
   const seenImages = /* @__PURE__ */ new Set();
-  const duplicateImages = /* @__PURE__ */ new Set();
   const display = /* @__PURE__ */ new Map();
   for (const item of [selectedLead, ...originalOrder]) {
     if (!item) continue;
     const key = coverIdentity(item);
     if (key && seenImages.has(key)) {
-      duplicateImages.add(item.id);
       display.set(item.id, { ...item, cover_image_url: null });
     } else {
       display.set(item.id, item);
@@ -158,14 +156,7 @@ function composeEdition(items, selection = {}, now = Date.now()) {
   const lead = selectedLead ? display.get(selectedLead.id) : void 0;
   let remaining = rest.map((item) => display.get(item.id));
   const uniqueOrdered = originalOrder.map((item) => display.get(item.id));
-  const secondary = [];
-  const deferred = [];
-  for (const item of uniqueOrdered) {
-    if (secondary.length >= 3) break;
-    if (duplicateImages.has(item.id)) deferred.push(item);
-    else secondary.push(item);
-  }
-  while (secondary.length < 3 && deferred.length > 0) secondary.push(deferred.shift());
+  const secondary = uniqueOrdered.filter((item) => coverIdentity(item)).slice(0, 3);
   const secondaryIds = new Set(secondary.map((item) => item.id));
   remaining = remaining.filter((item) => !secondaryIds.has(item.id));
   const eligible2 = remaining.filter((item) => {
@@ -180,10 +171,11 @@ function composeEdition(items, selection = {}, now = Date.now()) {
     briefIds.add(item.id);
     return true;
   });
-  const compact = [...briefs, ...remaining.filter((item) => !briefIds.has(item.id))].slice(0, 4);
+  const compact = [...briefs, ...remaining.filter((item) => !briefIds.has(item.id))].filter((item) => coverIdentity(item)).slice(0, 4);
   const compactIds = new Set(compact.map((item) => item.id));
-  const sections2 = editorialSections(remaining.filter((item) => !compactIds.has(item.id)));
-  return { lead, secondary, briefs, compact, sections: sections2, navigation: editorialSections(inventory) };
+  const sections2 = editorialSections(remaining.filter((item) => !compactIds.has(item.id) && coverIdentity(item)));
+  const pendingImages = inventory.filter((item) => !coverIdentity(item));
+  return { lead, secondary, briefs, compact, sections: sections2, pendingImages, navigation: editorialSections(inventory) };
 }
 function displayHeadline(article, selection = {}) {
   return selection.stories?.[article.slug]?.display_title?.trim() || article.title;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scalemule/news-publication",
-  "version": "0.0.83",
+  "version": "0.0.85",
   "description": "Shared server framework for ScaleMule local news publications. Walnut Creek Times is the broadsheet default; each paper supplies its own identity and feature flags.",
   "type": "module",
   "bin": {