@scalemule/news-publication 0.0.80 → 0.0.81

package/README.md

@@ -338,6 +338,40 @@ The platform contract and a complete example live in
 `docs/news-platform/ARTICLE-WORKFLOW-V1.md` in the ScaleMule meta-repo.
 Do not use direct SQL, S3 paths, base64 bodies or invented media readiness.
 
+### Edit article prose, cards and citations
+
+```sh
+npx --yes --package @scalemule/news-publication@0.0.81 scalemule-article edit \
+  --url "$ARTICLE_URL" --patch ./approved-edit.json --operation-key correction-v1
+```
+
+The patch may contain title, subtitle, content_markdown, excerpt, section,
+community, format, layout, cards and citations. 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
+`--enable-review-policy` only as a legitimate editorial onboarding decision.
+Scheduled legacy articles stop before onboarding. Normal API-key/member grants
+remain authoritative; the deployed server must advertise
+`versioned_editorial_fields`.
+
+The 10-second default deadline bounds the operation; `--timeout-ms` may raise it
+to at most 120 seconds. Keep the same patch/key and private checkpoint
+(`--state` or `~/.scalemule/newsroom/operations`) on retries. The checkpoint
+contains the submitted document and private provenance: never publish it.
+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
+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
+checkpoint store. This is local resumability over the existing server save
+receipt, not a distributed transaction covering entities, syndication, media
+commissioning or human review. The notices-only `/editorial` endpoint is not
+an article-body/card editor. Routine content corrections require no backend PR.
+
 ### Replace a published article photo from a local file
 
 ```sh

package/bin/scalemule-article.mjs

@@ -4,17 +4,27 @@ import { homedir } from 'node:os';
 import { dirname, join, basename } from 'node:path';
 import { createHash } from 'node:crypto';
 import { parseArgs } from 'node:util';
-import { PublicationArticleClient, articlePhotoHtmlMatches } from '../dist/article-workflow-client.js';
+import { PublicationArticleClient, articlePhotoHtmlMatches,articleEditHtmlMatches } from '../dist/article-workflow-client.js';
 
 const help = `Usage:
   scalemule-article inspect --publication ID --article ID
   scalemule-article replace-cover --publication ID --article ID --file-id ID --expected-version N --metadata photo.json
   scalemule-article replace-photo --url ARTICLE_URL --file PHOTO --metadata photo.json --operation-key KEY
+  scalemule-article edit --url ARTICLE_URL --patch edit.json --operation-key KEY [--release]
 
 Credentials: SCALEMULE_API_KEY and SCALEMULE_ACCESS_TOKEN (normal authorized member).
 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.
+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
+--enable-review-policy value. Scheduled legacy articles stop before onboarding.
+Use --expected-generation when coordinating an edit with another editor.
+Default edit deadline: 10000 ms. Reuse the same patch/key/checkpoint on retry.
+RELEASE_HELD means the revision is saved and existing review gates remain.
+
 replace-photo accepts a local file and uses normal member/API-key credentials.
 It requires developer-level asset access and publication approval rights.
 It resolves the publication from its authorized API inventory, saves a private
@@ -44,17 +54,17 @@ that every website/CDN cache already displays the new image.
 try {
   const { values, positionals } = parseArgs({
     allowPositionals: true, strict: true,
-    options: Object.fromEntries(['publication', 'article', 'file-id', 'expected-version', 'metadata', 'application-id', 'api-url', 'url', 'file', 'operation-key', 'state', 'timeout-ms'].map(k => [k, { type: 'string' }]).concat([['help', { type: 'boolean' }]])),
+    options: Object.fromEntries(['publication', 'article', 'file-id', 'expected-version', 'metadata', 'application-id', 'api-url', 'url', 'file', 'operation-key', 'state', 'timeout-ms','patch','expected-generation','enable-review-policy'].map(k => [k, { type: 'string' }]).concat([['help', { type: 'boolean' }],['release',{type:'boolean'}]])),
   });
   if (values.help || !positionals.length) {
     console.log(help);
   } else {
     const [command, ...extra] = positionals;
     const commandStarted = performance.now();
-    const budget = Number(values['timeout-ms'] ?? 30000);
+    const budget = Number(values['timeout-ms'] ?? (command==='edit'?10000:30000));
     if (!Number.isFinite(budget) || budget < 100 || budget > 120000) throw Error('--timeout-ms must be between 100 and 120000');
     const remaining = () => { const ms = Math.floor(budget - (performance.now()-commandStarted)); if (ms < 1) throw Error('Operation deadline reached; resume the same operation'); return ms; };
-    if (extra.length || !['inspect', 'replace-cover', 'replace-photo'].includes(command)) throw Error('Use inspect, replace-cover or replace-photo; see --help');
+    if (extra.length || !['inspect', 'replace-cover', 'replace-photo','edit'].includes(command)) throw Error('Use inspect, edit, replace-cover or replace-photo; see --help');
     if (values.url) {
       if (!process.env.SCALEMULE_API_KEY || !process.env.SCALEMULE_ACCESS_TOKEN || values['application-id']) throw Error('URL resolution requires normal publication member/API-key credentials');
       const url = new URL(values.url);
@@ -99,6 +109,47 @@ try {
         capabilities: options.capabilities, narration: processing.narration,
         assets: processing.assets, collaboration, elapsed_ms: Math.round(performance.now() - started),
       }, null, 2));
+    } else if (command==='edit') {
+      for(const key of ['patch','operation-key'])if(!values[key])throw Error('Missing --'+key);
+      const patch=JSON.parse(await readFile(values.patch,'utf8'));
+      const key=createHash('sha256').update(JSON.stringify(['edit',values['api-url']??'https://api.scalemule.com',values.publication,values.article,values['operation-key']])).digest('hex');
+      const statePath=values.state??join(homedir(),'.scalemule','newsroom','operations',key+'.json');
+      await mkdir(dirname(statePath),{recursive:true,mode:0o700});
+      const lockPath=statePath+'.lock';let lock;
+      try{lock=await open(lockPath,'wx',0o600);}catch(error){
+        if(error.code!=='EEXIST')throw error;
+        const pid=Number(await readFile(lockPath,'utf8'));if(!Number.isSafeInteger(pid)||pid<1)throw Error('Invalid operation lock; inspect '+lockPath);
+        let alive=true;try{process.kill(pid,0);}catch(e){if(e.code==='ESRCH')alive=false;else throw e;}
+        if(alive)throw Error('This edit operation is already running');
+        await unlink(lockPath);lock=await open(lockPath,'wx',0o600);
+      }
+      await lock.writeFile(String(process.pid));await lock.close();
+      try{
+        let checkpoint;try{checkpoint=JSON.parse(await readFile(statePath,'utf8'));}catch(error){if(error.code!=='ENOENT')throw error;}
+        const result=await client.editArticle({articleId:values.article,operationKey:values['operation-key'],patch,
+          expectedGeneration:values['expected-generation']===undefined?undefined:Number(values['expected-generation']),
+          enableReviewPolicy:values['enable-review-policy'],release:values.release,checkpoint,timeoutMs:remaining(),
+          saveCheckpoint:async state=>{const temp=statePath+'.'+process.pid+'.tmp';await writeFile(temp,JSON.stringify(state),{mode:0o600});await rename(temp,statePath);checkpoint=state;},
+        });
+        if(values.url&&values.release&&['published','already_published'].includes(result.state)){
+          let verified=false,reason;
+          try{
+            const snapshot=await client.publicArticle(checkpoint.sourceIdentity.slug,AbortSignal.timeout(remaining()));
+            const article=snapshot.article;
+            if(!article||!article.content_html||article.id!==values.article)throw Error('Published reader snapshot is missing');
+            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)});
+              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;}
+          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));
+        }
+      }finally{await unlink(lockPath);}
     } else if (command === 'replace-photo') {
       for (const key of ['file','metadata','operation-key']) if (!values[key]) throw Error(`Missing --${key}`);
       if (values['application-id']) throw Error('Local-photo intake uses normal publication member credentials');
@@ -182,6 +233,6 @@ try {
     }
   }
 } catch (error) {
-  console.error(JSON.stringify({ error: error.message, status: error.status, code:error.code, stage:error.stage, file_id:error.fileId }));
-  process.exitCode = 1;
+  console.error(JSON.stringify({ error: error.message, status: error.status, code:error.code, stage:error.stage, file_id:error.fileId,revision_id:error.revisionId }));
+  process.exitCode = error.code==='RELEASE_HELD'?2:1;
 }

package/dist/article-workflow-client.cjs

@@ -12,6 +12,47 @@ function articlePhotoHtmlMatches(html, lead, social) {
   return image && openGraph;
 }
 
+// src/article-edit-verification.ts
+var decode = (value) => value.replace(/&(?:amp|lt|gt|quot|apos|#39|#\d+|#x[\da-f]+);/giu, (s) => {
+  const named = {
+    "&": "&",
+    "&lt;": "<",
+    "&gt;": ">",
+    "&quot;": '"',
+    "&apos;": "'",
+    "&#39;": "'"
+  };
+  if (named[s.toLowerCase()]) return named[s.toLowerCase()];
+  const hex = s.toLowerCase().startsWith("&#x");
+  const n = parseInt(s.slice(hex ? 3 : 2, -1), hex ? 16 : 10);
+  return Number.isFinite(n) && n >= 0 && n <= 1114111 ? String.fromCodePoint(n) : s;
+});
+var text = (html) => decode(html.replace(/<[^>]*>/gu, " ")).replace(/\s+/gu, " ").trim();
+var plain = (value) => value.replace(/\s+/gu, " ").trim();
+function articleEditHtmlMatches(html, expected) {
+  const visible = html.replace(/<script\b[^>]*>[\s\S]*?<\/script>/giu, " ").replace(/<style\b[^>]*>[\s\S]*?<\/style>/giu, " ");
+  const headline = [...visible.matchAll(/<h1\b[^>]*>([\s\S]*?)<\/h1>/giu)].some(
+    (m) => text(m[1]) === plain(expected.title)
+  );
+  if (!headline) return false;
+  const paragraphs = [
+    ...expected.content_html.matchAll(
+      /<(p|li|h[2-6]|blockquote)\b[^>]*>([\s\S]*?)<\/\1>/giu
+    )
+  ].map((m) => text(m[2])).filter(Boolean);
+  const all = text(visible);
+  if (!paragraphs.length || !paragraphs.every((p) => all.includes(p)))
+    return false;
+  const titles = [
+    ...visible.matchAll(
+      /<aside\b[^>]*class=["'][^"']*\barticle-verified-card\b[^"']*["'][^>]*>([\s\S]*?)<\/aside>/giu
+    )
+  ].flatMap(
+    (m) => [...m[1].matchAll(/<h2\b[^>]*>([\s\S]*?)<\/h2>/giu)].map((m2) => text(m2[1]))
+  );
+  return JSON.stringify(titles.sort()) === JSON.stringify(expected.card_titles.map(plain).sort());
+}
+
 // src/article-photo-operation.ts
 var ArticlePhotoOperationError = class extends Error {
   constructor(code, stage, message, fileId, status) {
@@ -287,6 +328,325 @@ async function runArticlePhoto(t, input) {
   }
 }
 
+// src/article-edit-operation.ts
+var ArticleEditOperationError = class extends Error {
+  constructor(code, stage, message, status, revisionId) {
+    super(message);
+    this.code = code;
+    this.stage = stage;
+    this.status = status;
+    this.revisionId = revisionId;
+    this.name = "ArticleEditOperationError";
+  }
+  code;
+  stage;
+  status;
+  revisionId;
+};
+var canonical2 = (v) => Array.isArray(v) ? v.map(canonical2) : v && typeof v === "object" ? Object.fromEntries(
+  Object.keys(v).sort().map((k) => [k, canonical2(v[k])])
+) : v;
+var equal = (a, b) => JSON.stringify(canonical2(a)) === JSON.stringify(canonical2(b));
+var digest2 = async (v) => [
+  ...new Uint8Array(
+    await crypto.subtle.digest(
+      "SHA-256",
+      new TextEncoder().encode(JSON.stringify(canonical2(v)))
+    )
+  )
+].map((v2) => v2.toString(16).padStart(2, "0")).join("");
+var patchKeys = /* @__PURE__ */ new Set([
+  "title",
+  "subtitle",
+  "content_markdown",
+  "excerpt",
+  "section",
+  "community",
+  "format",
+  "layout",
+  "cards",
+  "citations"
+]);
+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)
+    throw Error(
+      "Supply an article, stable operation key and nonempty editorial patch"
+    );
+  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 (!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))
+        throw Error("Select an existing versioned layout");
+    } else if (typeof value !== "string")
+      throw Error(key + " must be a string");
+  }
+  if (input.expectedGeneration !== void 0 && (!Number.isSafeInteger(input.expectedGeneration) || input.expectedGeneration < 1))
+    throw Error("Expected generation must be positive");
+  if (input.enableReviewPolicy && ![
+    "NONE",
+    "FACT_CHECK",
+    "CONTRIBUTOR_REVIEW",
+    "SUBJECT_APPROVAL_REQUIRED",
+    "SUBJECT_APPROVAL_PLUS_EDITOR"
+  ].includes(input.enableReviewPolicy))
+    throw Error("Select an explicit supported review policy");
+  if (new TextEncoder().encode(JSON.stringify(input.patch)).length > 128 * 1024)
+    throw Error("Editorial patch exceeds 128 KiB");
+}
+async function runArticleEdit(t, input) {
+  validate(input);
+  const started = performance.now();
+  let stage = "preflight";
+  const timeout = input.timeoutMs ?? 1e4;
+  if (!Number.isFinite(timeout) || timeout < 100 || timeout > 12e4)
+    throw Error("Edit deadline must be between 100 and 120000 milliseconds");
+  const signal = AbortSignal.timeout(timeout);
+  const request = (path, method, body, extra) => t.request(path, method, body, extra, signal);
+  const identity = await digest2([
+    t.publicationId,
+    input.articleId,
+    input.operationKey,
+    input.patch,
+    input.expectedGeneration ?? null,
+    input.enableReviewPolicy ?? null
+  ]);
+  if (input.checkpoint && (input.checkpoint.version !== 1 || input.checkpoint.identity !== identity || input.checkpoint.articleId !== input.articleId))
+    throw new ArticleEditOperationError(
+      "OPERATION_CONFLICT",
+      "validation",
+      "This checkpoint belongs to different input; reuse its original patch and operation key"
+    );
+  let state = input.checkpoint ? structuredClone(input.checkpoint) : { version: 1, identity, articleId: input.articleId, stage };
+  const save = async (next) => {
+    stage = next;
+    state.stage = next;
+    await input.saveCheckpoint(structuredClone(state));
+  };
+  const article = "/articles/" + encodeURIComponent(input.articleId);
+  const currentRevision = (record) => record.revisions?.find((v) => v.id === record.current_revision_id);
+  const identityOf = (post) => ({
+    slug: post.slug,
+    published_at: post.published_at ?? null,
+    canonical_url: post.canonical_url ?? null
+  });
+  const identityMatches = (post) => !state.sourceIdentity || state.sourceIdentity.slug === post.slug && (state.sourceIdentity.published_at === null || state.sourceIdentity.published_at === (post.published_at ?? null)) && (state.sourceIdentity.canonical_url === null || state.sourceIdentity.canonical_url === (post.canonical_url ?? null));
+  const result = (record, status) => ({
+    article_id: input.articleId,
+    revision_id: state.revisionId ?? record.current_revision_id,
+    generation: record.generation,
+    state: status,
+    editorial_status: record.status,
+    elapsed_ms: Math.round(performance.now() - started)
+  });
+  try {
+    const [options, source, initial] = await Promise.all([
+      request(
+        "/article-workflow/options?article_id=" + encodeURIComponent(input.articleId)
+      ),
+      request(article + "/document"),
+      request(article + "/collaboration").catch((error) => {
+        if (error.status === 404 && error.message === "Story collaboration is not enabled")
+          return null;
+        throw error;
+      })
+    ]);
+    if (options.workflow_version !== 1 || options.capabilities?.versioned_editorial_fields !== true)
+      throw new ArticleEditOperationError(
+        "CAPABILITY_UNAVAILABLE",
+        stage,
+        "The server must expose versioned_editorial_fields before this edit; no article was changed"
+      );
+    if (!identityMatches(source))
+      throw new ArticleEditOperationError(
+        "ARTICLE_IDENTITY_CHANGED",
+        stage,
+        "Article URL, publication date or canonical identity changed; inspect before continuing"
+      );
+    state.sourceIdentity ??= identityOf(source);
+    let record = initial;
+    if (!record) {
+      if (!input.enableReviewPolicy)
+        throw new ArticleEditOperationError(
+          "ENROLLMENT_REQUIRED",
+          stage,
+          "Legacy article: choose an explicit review policy for versioned editorial onboarding; no content was changed"
+        );
+      if (source.status === "scheduled")
+        throw new ArticleEditOperationError(
+          "SCHEDULED_ARTICLE",
+          stage,
+          "Onboarding cancels an old schedule; handle this scheduled article explicitly"
+        );
+      await save("enroll");
+      await request(article + "/collaboration/enable", "POST", {
+        review_policy: input.enableReviewPolicy
+      });
+      record = await request(article + "/collaboration");
+    }
+    if (state.revisionId) {
+      if (record.current_revision_id !== state.revisionId)
+        throw new ArticleEditOperationError(
+          "ARTICLE_CHANGED",
+          stage,
+          "Another revision is current; this operation cannot release or overwrite it",
+          409,
+          state.revisionId
+        );
+      const selected = currentRevision(record);
+      if (!selected || !equal(selected.document, state.document))
+        throw new ArticleEditOperationError(
+          "VERIFICATION_CONFLICT",
+          stage,
+          "The saved revision differs from this operation",
+          409,
+          state.revisionId
+        );
+    } else {
+      if (!state.document) {
+        if (input.expectedGeneration !== void 0 && record.generation !== input.expectedGeneration)
+          throw new ArticleEditOperationError(
+            "ARTICLE_CHANGED",
+            stage,
+            "The article generation changed; reload before applying this patch",
+            409
+          );
+        const selected = currentRevision(record);
+        if (!selected?.complete_snapshot && selected?.complete_snapshot !== void 0)
+          throw new ArticleEditOperationError(
+            "INCOMPLETE_REVISION",
+            stage,
+            "Inspect this historical revision before editing"
+          );
+        if (!selected?.document)
+          throw Error("Current immutable article document is missing");
+        const effective = { ...selected.document };
+        for (const key of ["cards", "citations"])
+          if (effective[key] === void 0 && selected.editorial_metadata?.[key] !== void 0)
+            effective[key] = selected.editorial_metadata[key];
+        if (effective.excerpt === void 0 && source.excerpt !== null && source.excerpt !== void 0)
+          effective.excerpt = source.excerpt;
+        const changed = Object.entries(input.patch).some(
+          ([key, value]) => !equal(effective[key], value)
+        );
+        if (!changed) {
+          state.document = selected.document;
+          state.revisionId = record.current_revision_id;
+          state.savedGeneration = record.generation;
+          state.unchanged = true;
+          await save("verify");
+          if (!input.release) return result(record, "unchanged");
+        } else {
+          const document = { ...selected.document, ...input.patch };
+          if (document.excerpt === void 0 && source.excerpt !== null && source.excerpt !== void 0)
+            document.excerpt = source.excerpt;
+          state.document = document;
+          state.expectedGeneration = record.generation;
+          await save("save");
+        }
+      }
+      if (!state.revisionId) {
+        const saved = await request(
+          "/article-workflow",
+          "POST",
+          {
+            operation: "save",
+            article_id: input.articleId,
+            expected_generation: state.expectedGeneration,
+            document: state.document,
+            reason: state.sourceIdentity?.published_at ? "POST_PUBLICATION_CORRECTION" : "EDITOR_EDIT"
+          },
+          { "Idempotency-Key": input.operationKey }
+        );
+        state.revisionId = saved.revision_id;
+        state.savedGeneration = saved.generation;
+        await save("verify");
+        record = await request(article + "/collaboration");
+        if (record.current_revision_id !== state.revisionId || !equal(currentRevision(record)?.document, state.document))
+          throw new ArticleEditOperationError(
+            "ARTICLE_CHANGED",
+            stage,
+            "A different revision is current; no release was attempted",
+            409,
+            state.revisionId
+          );
+      }
+    }
+    if (record.published_revision_id === state.revisionId) {
+      await save("published");
+      return result(record, "already_published");
+    }
+    if (!input.release) {
+      await save("saved");
+      return result(record, state.unchanged ? "unchanged" : "saved_for_review");
+    }
+    await save("release");
+    try {
+      await request(article + "/collaboration", "POST", {
+        action: "RELEASE",
+        expected_generation: record.generation,
+        scheduled_at: null
+      });
+    } catch (error) {
+      const checked = await request(article + "/collaboration");
+      if (checked.published_revision_id === state.revisionId && checked.current_revision_id === state.revisionId) {
+        record = checked;
+      } else throw error;
+    }
+    record = await request(article + "/collaboration");
+    if (record.current_revision_id !== state.revisionId || record.published_revision_id !== state.revisionId)
+      throw new ArticleEditOperationError(
+        "VERIFICATION_CONFLICT",
+        stage,
+        "This exact revision has not been confirmed published",
+        409,
+        state.revisionId
+      );
+    const after = await request(article + "/document");
+    if (!identityMatches(after))
+      throw new ArticleEditOperationError(
+        "ARTICLE_IDENTITY_CHANGED",
+        stage,
+        "The release changed a permanent article identity",
+        409,
+        state.revisionId
+      );
+    for (const key of ["title", "subtitle", "content_markdown", "excerpt"])
+      if (state.document?.[key] !== void 0 && !equal(after[key] ?? "", state.document[key]))
+        throw new ArticleEditOperationError(
+          "VERIFICATION_CONFLICT",
+          stage,
+          "Public article field differs after release: " + key,
+          409,
+          state.revisionId
+        );
+    const normalizedCards = state.document?.cards;
+    if (normalizedCards && after.metadata?.cards?.length !== normalizedCards.length)
+      throw new ArticleEditOperationError(
+        "VERIFICATION_CONFLICT",
+        stage,
+        "Public card count differs from the saved revision",
+        409,
+        state.revisionId
+      );
+    await save("published");
+    return result(record, "published");
+  } catch (error) {
+    if (error instanceof ArticleEditOperationError) throw error;
+    const status = error?.status;
+    const message = error instanceof Error ? error.message : "Article edit failed";
+    const code = signal.aborted ? "DEADLINE_EXCEEDED" : status === 401 || status === 403 ? "PERMISSION_DENIED" : status === 409 && stage === "release" ? "RELEASE_HELD" : status === 409 ? "ARTICLE_CHANGED" : "STEP_FAILED";
+    throw new ArticleEditOperationError(
+      code,
+      stage,
+      signal.aborted ? "Edit reached its deadline; resume the same patch, operation key and checkpoint. Success was not asserted." : message,
+      status,
+      state.revisionId
+    );
+  }
+}
+
 // src/article-workflow-client.ts
 var ArticleWorkflowError = class extends Error {
   constructor(message, status, articleId) {
@@ -343,6 +703,9 @@ var PublicationArticleClient = class {
       `/article-workflow/options${articleId ? `?article_id=${encodeURIComponent(articleId)}` : ""}`
     );
   }
+  publicArticle(slug, signal) {
+    return this.request("/article-content/" + encodeURIComponent(slug), void 0, void 0, void 0, signal);
+  }
   /** Explicit approver-authorized onboarding for a legacy article; never called by get().
    * Existing schedules are cancelled by the server; public content remains unchanged.
    * Missing immutable media identities must be resolved through newsroom media controls.
@@ -371,6 +734,10 @@ var PublicationArticleClient = class {
   uploadAndReplacePublishedCover(input) {
     return runArticlePhoto({ publicationId: this.config.publicationId, apiUrl: this.config.apiUrl, fetch: this.config.fetch ?? fetch, request: this.request.bind(this) }, input);
   }
+  /** Save one exact revision; release is explicit and never manufactures approval. */
+  editArticle(input) {
+    return runArticleEdit({ publicationId: this.config.publicationId, request: this.request.bind(this) }, input);
+  }
   /** Replace a legacy publication cover using ready, measured public Photo renditions.
    * This never enrolls a story, publishes text, creates narration or retries a conflict.
    * Collaboration-managed stories retain their server-enforced immutable revision workflow.
@@ -556,7 +923,7 @@ var PublicationArticleClient = class {
       const selected = [];
       for (const asset of input.assets ?? []) {
         let current = await this.get(created.article_id);
-        const digest2 = Array.from(
+        const digest3 = Array.from(
           new Uint8Array(
             await crypto.subtle.digest(
               "SHA-256",
@@ -565,7 +932,7 @@ var PublicationArticleClient = class {
           )
         ).map((v) => v.toString(16).padStart(2, "0")).join("");
         const existing = current.contributions.find(
-          (c) => c.kind === "MEDIA" && c.state !== "REJECTED" && c.state !== "WITHDRAWN" && c.payload.sha256 === digest2 && Object.entries(asset.metadata).every(
+          (c) => c.kind === "MEDIA" && c.state !== "REJECTED" && c.state !== "WITHDRAWN" && c.payload.sha256 === digest3 && Object.entries(asset.metadata).every(
             ([k, v]) => c.payload[k] === v
           )
         );
@@ -646,10 +1013,14 @@ var PublicationArticleClient = class {
   }
 };
 function sameDocument(a, b) {
-  const canonical2 = (d) => [
+  const sorted = (v) => Array.isArray(v) ? v.map(sorted) : v && typeof v === "object" ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, sorted(v[k])])) : v;
+  const canonical3 = (d) => [
     d.title,
     d.subtitle || "",
     d.content_markdown,
+    d.excerpt ?? null,
+    sorted(d.cards ?? null),
+    sorted(d.citations ?? null),
     d.section,
     d.community || "",
     d.format || null,
@@ -664,10 +1035,12 @@ function sameDocument(a, b) {
       m.position
     ])
   ];
-  return JSON.stringify(canonical2(a)) === JSON.stringify(canonical2(b));
+  return JSON.stringify(canonical3(a)) === JSON.stringify(canonical3(b));
 }
 
+exports.ArticleEditOperationError = ArticleEditOperationError;
 exports.ArticlePhotoOperationError = ArticlePhotoOperationError;
 exports.ArticleWorkflowError = ArticleWorkflowError;
 exports.PublicationArticleClient = PublicationArticleClient;
+exports.articleEditHtmlMatches = articleEditHtmlMatches;
 exports.articlePhotoHtmlMatches = articlePhotoHtmlMatches;

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

@@ -3,6 +3,13 @@ import { A as ArticleFormat, b as ArticleLayout } from './article-presentation-0
 /** Check rendered image tags, not a URL mentioned only in serialized page data. */
 declare function articlePhotoHtmlMatches(html: string, lead: string | string[], social: string): boolean;
 
+/** Requires visible body and actual card asides; serialized page data is not delivery. */
+declare function articleEditHtmlMatches(html: string, expected: {
+    title: string;
+    content_html: string;
+    card_titles: string[];
+}): boolean;
+
 type PhotoOperationCheckpoint = {
     version: 1;
     identity: string;
@@ -41,10 +48,51 @@ 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 ArticleEditCheckpoint = {
+    version: 1;
+    identity: string;
+    articleId: string;
+    stage: string;
+    expectedGeneration?: number;
+    document?: ArticleDocument;
+    revisionId?: string;
+    savedGeneration?: number;
+    unchanged?: boolean;
+    sourceIdentity?: {
+        slug: string;
+        published_at: string | null;
+        canonical_url: string | null;
+    };
+};
+type ArticleEditInput = {
+    articleId: string;
+    operationKey: string;
+    patch: ArticleEditPatch;
+    expectedGeneration?: number;
+    /** Explicit legacy onboarding only. Existing policies are never changed. */
+    enableReviewPolicy?: "NONE" | "FACT_CHECK" | "CONTRIBUTOR_REVIEW" | "SUBJECT_APPROVAL_REQUIRED" | "SUBJECT_APPROVAL_PLUS_EDITOR";
+    /** Execute RELEASE under the caller's grants. Does not issue APPROVE. */
+    release?: boolean;
+    checkpoint?: ArticleEditCheckpoint;
+    saveCheckpoint: (checkpoint: ArticleEditCheckpoint) => Promise<void>;
+    timeoutMs?: number;
+};
+declare class ArticleEditOperationError extends Error {
+    code: string;
+    stage: string;
+    status?: number | undefined;
+    revisionId?: string | undefined;
+    constructor(code: string, stage: string, message: string, status?: number | undefined, revisionId?: string | undefined);
+}
+
 type ArticleDocument = {
     title: string;
     subtitle?: string;
     content_markdown: string;
+    excerpt?: string;
+    cards?: unknown[];
+    citations?: unknown[];
     section: string;
     community?: string;
     format?: ArticleFormat;
@@ -146,6 +194,7 @@ type ArticleWorkflowOptions = {
         automatic_public_narration?: boolean;
         prioritized_narration_processing?: boolean;
         content_first_editor_document?: boolean;
+        versioned_editorial_fields?: boolean;
     };
 };
 type ArticleOperation = {
@@ -194,6 +243,7 @@ declare class PublicationArticleClient {
     });
     private request;
     options(articleId?: string): Promise<ArticleWorkflowOptions>;
+    publicArticle(slug: string, signal?: AbortSignal): Promise<any>;
     /** Explicit approver-authorized onboarding for a legacy article; never called by get().
      * Existing schedules are cancelled by the server; public content remains unchanged.
      * Missing immutable media identities must be resolved through newsroom media controls.
@@ -212,6 +262,15 @@ declare class PublicationArticleClient {
         state: string;
         elapsed_ms: number;
     }>;
+    /** Save one exact revision; release is explicit and never manufactures approval. */
+    editArticle(input: ArticleEditInput): Promise<{
+        article_id: string;
+        revision_id: any;
+        generation: any;
+        state: string;
+        editorial_status: any;
+        elapsed_ms: number;
+    }>;
     /** Replace a legacy publication cover using ready, measured public Photo renditions.
      * This never enrolls a story, publishes text, creates narration or retries a conflict.
      * Collaboration-managed stories retain their server-enforced immutable revision workflow.
@@ -262,4 +321,4 @@ declare class PublicationArticleClient {
     }): Promise<ArticleOperation>;
 }
 
-export { type ArticleDocument, type ArticleMedia, type ArticleOperation, type ArticlePhotoInput, ArticlePhotoOperationError, type ArticleProcessing, ArticleWorkflowError, type ArticleWorkflowOptions, type AssetMetadata, type PhotoOperationCheckpoint, PublicationArticleClient, type PublishedCoverReplacement, articlePhotoHtmlMatches };
+export { type ArticleDocument, type ArticleEditCheckpoint, type ArticleEditInput, ArticleEditOperationError, type ArticleEditPatch, type ArticleMedia, type ArticleOperation, type ArticlePhotoInput, ArticlePhotoOperationError, type ArticleProcessing, ArticleWorkflowError, type ArticleWorkflowOptions, type AssetMetadata, type PhotoOperationCheckpoint, PublicationArticleClient, type PublishedCoverReplacement, articleEditHtmlMatches, articlePhotoHtmlMatches };

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

@@ -3,6 +3,13 @@ import { A as ArticleFormat, b as ArticleLayout } from './article-presentation-0
 /** Check rendered image tags, not a URL mentioned only in serialized page data. */
 declare function articlePhotoHtmlMatches(html: string, lead: string | string[], social: string): boolean;
 
+/** Requires visible body and actual card asides; serialized page data is not delivery. */
+declare function articleEditHtmlMatches(html: string, expected: {
+    title: string;
+    content_html: string;
+    card_titles: string[];
+}): boolean;
+
 type PhotoOperationCheckpoint = {
     version: 1;
     identity: string;
@@ -41,10 +48,51 @@ 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 ArticleEditCheckpoint = {
+    version: 1;
+    identity: string;
+    articleId: string;
+    stage: string;
+    expectedGeneration?: number;
+    document?: ArticleDocument;
+    revisionId?: string;
+    savedGeneration?: number;
+    unchanged?: boolean;
+    sourceIdentity?: {
+        slug: string;
+        published_at: string | null;
+        canonical_url: string | null;
+    };
+};
+type ArticleEditInput = {
+    articleId: string;
+    operationKey: string;
+    patch: ArticleEditPatch;
+    expectedGeneration?: number;
+    /** Explicit legacy onboarding only. Existing policies are never changed. */
+    enableReviewPolicy?: "NONE" | "FACT_CHECK" | "CONTRIBUTOR_REVIEW" | "SUBJECT_APPROVAL_REQUIRED" | "SUBJECT_APPROVAL_PLUS_EDITOR";
+    /** Execute RELEASE under the caller's grants. Does not issue APPROVE. */
+    release?: boolean;
+    checkpoint?: ArticleEditCheckpoint;
+    saveCheckpoint: (checkpoint: ArticleEditCheckpoint) => Promise<void>;
+    timeoutMs?: number;
+};
+declare class ArticleEditOperationError extends Error {
+    code: string;
+    stage: string;
+    status?: number | undefined;
+    revisionId?: string | undefined;
+    constructor(code: string, stage: string, message: string, status?: number | undefined, revisionId?: string | undefined);
+}
+
 type ArticleDocument = {
     title: string;
     subtitle?: string;
     content_markdown: string;
+    excerpt?: string;
+    cards?: unknown[];
+    citations?: unknown[];
     section: string;
     community?: string;
     format?: ArticleFormat;
@@ -146,6 +194,7 @@ type ArticleWorkflowOptions = {
         automatic_public_narration?: boolean;
         prioritized_narration_processing?: boolean;
         content_first_editor_document?: boolean;
+        versioned_editorial_fields?: boolean;
     };
 };
 type ArticleOperation = {
@@ -194,6 +243,7 @@ declare class PublicationArticleClient {
     });
     private request;
     options(articleId?: string): Promise<ArticleWorkflowOptions>;
+    publicArticle(slug: string, signal?: AbortSignal): Promise<any>;
     /** Explicit approver-authorized onboarding for a legacy article; never called by get().
      * Existing schedules are cancelled by the server; public content remains unchanged.
      * Missing immutable media identities must be resolved through newsroom media controls.
@@ -212,6 +262,15 @@ declare class PublicationArticleClient {
         state: string;
         elapsed_ms: number;
     }>;
+    /** Save one exact revision; release is explicit and never manufactures approval. */
+    editArticle(input: ArticleEditInput): Promise<{
+        article_id: string;
+        revision_id: any;
+        generation: any;
+        state: string;
+        editorial_status: any;
+        elapsed_ms: number;
+    }>;
     /** Replace a legacy publication cover using ready, measured public Photo renditions.
      * This never enrolls a story, publishes text, creates narration or retries a conflict.
      * Collaboration-managed stories retain their server-enforced immutable revision workflow.
@@ -262,4 +321,4 @@ declare class PublicationArticleClient {
     }): Promise<ArticleOperation>;
 }
 
-export { type ArticleDocument, type ArticleMedia, type ArticleOperation, type ArticlePhotoInput, ArticlePhotoOperationError, type ArticleProcessing, ArticleWorkflowError, type ArticleWorkflowOptions, type AssetMetadata, type PhotoOperationCheckpoint, PublicationArticleClient, type PublishedCoverReplacement, articlePhotoHtmlMatches };
+export { type ArticleDocument, type ArticleEditCheckpoint, type ArticleEditInput, ArticleEditOperationError, type ArticleEditPatch, type ArticleMedia, type ArticleOperation, type ArticlePhotoInput, ArticlePhotoOperationError, type ArticleProcessing, ArticleWorkflowError, type ArticleWorkflowOptions, type AssetMetadata, type PhotoOperationCheckpoint, PublicationArticleClient, type PublishedCoverReplacement, articleEditHtmlMatches, articlePhotoHtmlMatches };

package/dist/article-workflow-client.js

@@ -10,6 +10,47 @@ function articlePhotoHtmlMatches(html, lead, social) {
   return image && openGraph;
 }
 
+// src/article-edit-verification.ts
+var decode = (value) => value.replace(/&(?:amp|lt|gt|quot|apos|#39|#\d+|#x[\da-f]+);/giu, (s) => {
+  const named = {
+    "&": "&",
+    "&lt;": "<",
+    "&gt;": ">",
+    "&quot;": '"',
+    "&apos;": "'",
+    "&#39;": "'"
+  };
+  if (named[s.toLowerCase()]) return named[s.toLowerCase()];
+  const hex = s.toLowerCase().startsWith("&#x");
+  const n = parseInt(s.slice(hex ? 3 : 2, -1), hex ? 16 : 10);
+  return Number.isFinite(n) && n >= 0 && n <= 1114111 ? String.fromCodePoint(n) : s;
+});
+var text = (html) => decode(html.replace(/<[^>]*>/gu, " ")).replace(/\s+/gu, " ").trim();
+var plain = (value) => value.replace(/\s+/gu, " ").trim();
+function articleEditHtmlMatches(html, expected) {
+  const visible = html.replace(/<script\b[^>]*>[\s\S]*?<\/script>/giu, " ").replace(/<style\b[^>]*>[\s\S]*?<\/style>/giu, " ");
+  const headline = [...visible.matchAll(/<h1\b[^>]*>([\s\S]*?)<\/h1>/giu)].some(
+    (m) => text(m[1]) === plain(expected.title)
+  );
+  if (!headline) return false;
+  const paragraphs = [
+    ...expected.content_html.matchAll(
+      /<(p|li|h[2-6]|blockquote)\b[^>]*>([\s\S]*?)<\/\1>/giu
+    )
+  ].map((m) => text(m[2])).filter(Boolean);
+  const all = text(visible);
+  if (!paragraphs.length || !paragraphs.every((p) => all.includes(p)))
+    return false;
+  const titles = [
+    ...visible.matchAll(
+      /<aside\b[^>]*class=["'][^"']*\barticle-verified-card\b[^"']*["'][^>]*>([\s\S]*?)<\/aside>/giu
+    )
+  ].flatMap(
+    (m) => [...m[1].matchAll(/<h2\b[^>]*>([\s\S]*?)<\/h2>/giu)].map((m2) => text(m2[1]))
+  );
+  return JSON.stringify(titles.sort()) === JSON.stringify(expected.card_titles.map(plain).sort());
+}
+
 // src/article-photo-operation.ts
 var ArticlePhotoOperationError = class extends Error {
   constructor(code, stage, message, fileId, status) {
@@ -285,6 +326,325 @@ async function runArticlePhoto(t, input) {
   }
 }
 
+// src/article-edit-operation.ts
+var ArticleEditOperationError = class extends Error {
+  constructor(code, stage, message, status, revisionId) {
+    super(message);
+    this.code = code;
+    this.stage = stage;
+    this.status = status;
+    this.revisionId = revisionId;
+    this.name = "ArticleEditOperationError";
+  }
+  code;
+  stage;
+  status;
+  revisionId;
+};
+var canonical2 = (v) => Array.isArray(v) ? v.map(canonical2) : v && typeof v === "object" ? Object.fromEntries(
+  Object.keys(v).sort().map((k) => [k, canonical2(v[k])])
+) : v;
+var equal = (a, b) => JSON.stringify(canonical2(a)) === JSON.stringify(canonical2(b));
+var digest2 = async (v) => [
+  ...new Uint8Array(
+    await crypto.subtle.digest(
+      "SHA-256",
+      new TextEncoder().encode(JSON.stringify(canonical2(v)))
+    )
+  )
+].map((v2) => v2.toString(16).padStart(2, "0")).join("");
+var patchKeys = /* @__PURE__ */ new Set([
+  "title",
+  "subtitle",
+  "content_markdown",
+  "excerpt",
+  "section",
+  "community",
+  "format",
+  "layout",
+  "cards",
+  "citations"
+]);
+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)
+    throw Error(
+      "Supply an article, stable operation key and nonempty editorial patch"
+    );
+  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 (!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))
+        throw Error("Select an existing versioned layout");
+    } else if (typeof value !== "string")
+      throw Error(key + " must be a string");
+  }
+  if (input.expectedGeneration !== void 0 && (!Number.isSafeInteger(input.expectedGeneration) || input.expectedGeneration < 1))
+    throw Error("Expected generation must be positive");
+  if (input.enableReviewPolicy && ![
+    "NONE",
+    "FACT_CHECK",
+    "CONTRIBUTOR_REVIEW",
+    "SUBJECT_APPROVAL_REQUIRED",
+    "SUBJECT_APPROVAL_PLUS_EDITOR"
+  ].includes(input.enableReviewPolicy))
+    throw Error("Select an explicit supported review policy");
+  if (new TextEncoder().encode(JSON.stringify(input.patch)).length > 128 * 1024)
+    throw Error("Editorial patch exceeds 128 KiB");
+}
+async function runArticleEdit(t, input) {
+  validate(input);
+  const started = performance.now();
+  let stage = "preflight";
+  const timeout = input.timeoutMs ?? 1e4;
+  if (!Number.isFinite(timeout) || timeout < 100 || timeout > 12e4)
+    throw Error("Edit deadline must be between 100 and 120000 milliseconds");
+  const signal = AbortSignal.timeout(timeout);
+  const request = (path, method, body, extra) => t.request(path, method, body, extra, signal);
+  const identity = await digest2([
+    t.publicationId,
+    input.articleId,
+    input.operationKey,
+    input.patch,
+    input.expectedGeneration ?? null,
+    input.enableReviewPolicy ?? null
+  ]);
+  if (input.checkpoint && (input.checkpoint.version !== 1 || input.checkpoint.identity !== identity || input.checkpoint.articleId !== input.articleId))
+    throw new ArticleEditOperationError(
+      "OPERATION_CONFLICT",
+      "validation",
+      "This checkpoint belongs to different input; reuse its original patch and operation key"
+    );
+  let state = input.checkpoint ? structuredClone(input.checkpoint) : { version: 1, identity, articleId: input.articleId, stage };
+  const save = async (next) => {
+    stage = next;
+    state.stage = next;
+    await input.saveCheckpoint(structuredClone(state));
+  };
+  const article = "/articles/" + encodeURIComponent(input.articleId);
+  const currentRevision = (record) => record.revisions?.find((v) => v.id === record.current_revision_id);
+  const identityOf = (post) => ({
+    slug: post.slug,
+    published_at: post.published_at ?? null,
+    canonical_url: post.canonical_url ?? null
+  });
+  const identityMatches = (post) => !state.sourceIdentity || state.sourceIdentity.slug === post.slug && (state.sourceIdentity.published_at === null || state.sourceIdentity.published_at === (post.published_at ?? null)) && (state.sourceIdentity.canonical_url === null || state.sourceIdentity.canonical_url === (post.canonical_url ?? null));
+  const result = (record, status) => ({
+    article_id: input.articleId,
+    revision_id: state.revisionId ?? record.current_revision_id,
+    generation: record.generation,
+    state: status,
+    editorial_status: record.status,
+    elapsed_ms: Math.round(performance.now() - started)
+  });
+  try {
+    const [options, source, initial] = await Promise.all([
+      request(
+        "/article-workflow/options?article_id=" + encodeURIComponent(input.articleId)
+      ),
+      request(article + "/document"),
+      request(article + "/collaboration").catch((error) => {
+        if (error.status === 404 && error.message === "Story collaboration is not enabled")
+          return null;
+        throw error;
+      })
+    ]);
+    if (options.workflow_version !== 1 || options.capabilities?.versioned_editorial_fields !== true)
+      throw new ArticleEditOperationError(
+        "CAPABILITY_UNAVAILABLE",
+        stage,
+        "The server must expose versioned_editorial_fields before this edit; no article was changed"
+      );
+    if (!identityMatches(source))
+      throw new ArticleEditOperationError(
+        "ARTICLE_IDENTITY_CHANGED",
+        stage,
+        "Article URL, publication date or canonical identity changed; inspect before continuing"
+      );
+    state.sourceIdentity ??= identityOf(source);
+    let record = initial;
+    if (!record) {
+      if (!input.enableReviewPolicy)
+        throw new ArticleEditOperationError(
+          "ENROLLMENT_REQUIRED",
+          stage,
+          "Legacy article: choose an explicit review policy for versioned editorial onboarding; no content was changed"
+        );
+      if (source.status === "scheduled")
+        throw new ArticleEditOperationError(
+          "SCHEDULED_ARTICLE",
+          stage,
+          "Onboarding cancels an old schedule; handle this scheduled article explicitly"
+        );
+      await save("enroll");
+      await request(article + "/collaboration/enable", "POST", {
+        review_policy: input.enableReviewPolicy
+      });
+      record = await request(article + "/collaboration");
+    }
+    if (state.revisionId) {
+      if (record.current_revision_id !== state.revisionId)
+        throw new ArticleEditOperationError(
+          "ARTICLE_CHANGED",
+          stage,
+          "Another revision is current; this operation cannot release or overwrite it",
+          409,
+          state.revisionId
+        );
+      const selected = currentRevision(record);
+      if (!selected || !equal(selected.document, state.document))
+        throw new ArticleEditOperationError(
+          "VERIFICATION_CONFLICT",
+          stage,
+          "The saved revision differs from this operation",
+          409,
+          state.revisionId
+        );
+    } else {
+      if (!state.document) {
+        if (input.expectedGeneration !== void 0 && record.generation !== input.expectedGeneration)
+          throw new ArticleEditOperationError(
+            "ARTICLE_CHANGED",
+            stage,
+            "The article generation changed; reload before applying this patch",
+            409
+          );
+        const selected = currentRevision(record);
+        if (!selected?.complete_snapshot && selected?.complete_snapshot !== void 0)
+          throw new ArticleEditOperationError(
+            "INCOMPLETE_REVISION",
+            stage,
+            "Inspect this historical revision before editing"
+          );
+        if (!selected?.document)
+          throw Error("Current immutable article document is missing");
+        const effective = { ...selected.document };
+        for (const key of ["cards", "citations"])
+          if (effective[key] === void 0 && selected.editorial_metadata?.[key] !== void 0)
+            effective[key] = selected.editorial_metadata[key];
+        if (effective.excerpt === void 0 && source.excerpt !== null && source.excerpt !== void 0)
+          effective.excerpt = source.excerpt;
+        const changed = Object.entries(input.patch).some(
+          ([key, value]) => !equal(effective[key], value)
+        );
+        if (!changed) {
+          state.document = selected.document;
+          state.revisionId = record.current_revision_id;
+          state.savedGeneration = record.generation;
+          state.unchanged = true;
+          await save("verify");
+          if (!input.release) return result(record, "unchanged");
+        } else {
+          const document = { ...selected.document, ...input.patch };
+          if (document.excerpt === void 0 && source.excerpt !== null && source.excerpt !== void 0)
+            document.excerpt = source.excerpt;
+          state.document = document;
+          state.expectedGeneration = record.generation;
+          await save("save");
+        }
+      }
+      if (!state.revisionId) {
+        const saved = await request(
+          "/article-workflow",
+          "POST",
+          {
+            operation: "save",
+            article_id: input.articleId,
+            expected_generation: state.expectedGeneration,
+            document: state.document,
+            reason: state.sourceIdentity?.published_at ? "POST_PUBLICATION_CORRECTION" : "EDITOR_EDIT"
+          },
+          { "Idempotency-Key": input.operationKey }
+        );
+        state.revisionId = saved.revision_id;
+        state.savedGeneration = saved.generation;
+        await save("verify");
+        record = await request(article + "/collaboration");
+        if (record.current_revision_id !== state.revisionId || !equal(currentRevision(record)?.document, state.document))
+          throw new ArticleEditOperationError(
+            "ARTICLE_CHANGED",
+            stage,
+            "A different revision is current; no release was attempted",
+            409,
+            state.revisionId
+          );
+      }
+    }
+    if (record.published_revision_id === state.revisionId) {
+      await save("published");
+      return result(record, "already_published");
+    }
+    if (!input.release) {
+      await save("saved");
+      return result(record, state.unchanged ? "unchanged" : "saved_for_review");
+    }
+    await save("release");
+    try {
+      await request(article + "/collaboration", "POST", {
+        action: "RELEASE",
+        expected_generation: record.generation,
+        scheduled_at: null
+      });
+    } catch (error) {
+      const checked = await request(article + "/collaboration");
+      if (checked.published_revision_id === state.revisionId && checked.current_revision_id === state.revisionId) {
+        record = checked;
+      } else throw error;
+    }
+    record = await request(article + "/collaboration");
+    if (record.current_revision_id !== state.revisionId || record.published_revision_id !== state.revisionId)
+      throw new ArticleEditOperationError(
+        "VERIFICATION_CONFLICT",
+        stage,
+        "This exact revision has not been confirmed published",
+        409,
+        state.revisionId
+      );
+    const after = await request(article + "/document");
+    if (!identityMatches(after))
+      throw new ArticleEditOperationError(
+        "ARTICLE_IDENTITY_CHANGED",
+        stage,
+        "The release changed a permanent article identity",
+        409,
+        state.revisionId
+      );
+    for (const key of ["title", "subtitle", "content_markdown", "excerpt"])
+      if (state.document?.[key] !== void 0 && !equal(after[key] ?? "", state.document[key]))
+        throw new ArticleEditOperationError(
+          "VERIFICATION_CONFLICT",
+          stage,
+          "Public article field differs after release: " + key,
+          409,
+          state.revisionId
+        );
+    const normalizedCards = state.document?.cards;
+    if (normalizedCards && after.metadata?.cards?.length !== normalizedCards.length)
+      throw new ArticleEditOperationError(
+        "VERIFICATION_CONFLICT",
+        stage,
+        "Public card count differs from the saved revision",
+        409,
+        state.revisionId
+      );
+    await save("published");
+    return result(record, "published");
+  } catch (error) {
+    if (error instanceof ArticleEditOperationError) throw error;
+    const status = error?.status;
+    const message = error instanceof Error ? error.message : "Article edit failed";
+    const code = signal.aborted ? "DEADLINE_EXCEEDED" : status === 401 || status === 403 ? "PERMISSION_DENIED" : status === 409 && stage === "release" ? "RELEASE_HELD" : status === 409 ? "ARTICLE_CHANGED" : "STEP_FAILED";
+    throw new ArticleEditOperationError(
+      code,
+      stage,
+      signal.aborted ? "Edit reached its deadline; resume the same patch, operation key and checkpoint. Success was not asserted." : message,
+      status,
+      state.revisionId
+    );
+  }
+}
+
 // src/article-workflow-client.ts
 var ArticleWorkflowError = class extends Error {
   constructor(message, status, articleId) {
@@ -341,6 +701,9 @@ var PublicationArticleClient = class {
       `/article-workflow/options${articleId ? `?article_id=${encodeURIComponent(articleId)}` : ""}`
     );
   }
+  publicArticle(slug, signal) {
+    return this.request("/article-content/" + encodeURIComponent(slug), void 0, void 0, void 0, signal);
+  }
   /** Explicit approver-authorized onboarding for a legacy article; never called by get().
    * Existing schedules are cancelled by the server; public content remains unchanged.
    * Missing immutable media identities must be resolved through newsroom media controls.
@@ -369,6 +732,10 @@ var PublicationArticleClient = class {
   uploadAndReplacePublishedCover(input) {
     return runArticlePhoto({ publicationId: this.config.publicationId, apiUrl: this.config.apiUrl, fetch: this.config.fetch ?? fetch, request: this.request.bind(this) }, input);
   }
+  /** Save one exact revision; release is explicit and never manufactures approval. */
+  editArticle(input) {
+    return runArticleEdit({ publicationId: this.config.publicationId, request: this.request.bind(this) }, input);
+  }
   /** Replace a legacy publication cover using ready, measured public Photo renditions.
    * This never enrolls a story, publishes text, creates narration or retries a conflict.
    * Collaboration-managed stories retain their server-enforced immutable revision workflow.
@@ -554,7 +921,7 @@ var PublicationArticleClient = class {
       const selected = [];
       for (const asset of input.assets ?? []) {
         let current = await this.get(created.article_id);
-        const digest2 = Array.from(
+        const digest3 = Array.from(
           new Uint8Array(
             await crypto.subtle.digest(
               "SHA-256",
@@ -563,7 +930,7 @@ var PublicationArticleClient = class {
           )
         ).map((v) => v.toString(16).padStart(2, "0")).join("");
         const existing = current.contributions.find(
-          (c) => c.kind === "MEDIA" && c.state !== "REJECTED" && c.state !== "WITHDRAWN" && c.payload.sha256 === digest2 && Object.entries(asset.metadata).every(
+          (c) => c.kind === "MEDIA" && c.state !== "REJECTED" && c.state !== "WITHDRAWN" && c.payload.sha256 === digest3 && Object.entries(asset.metadata).every(
             ([k, v]) => c.payload[k] === v
           )
         );
@@ -644,10 +1011,14 @@ var PublicationArticleClient = class {
   }
 };
 function sameDocument(a, b) {
-  const canonical2 = (d) => [
+  const sorted = (v) => Array.isArray(v) ? v.map(sorted) : v && typeof v === "object" ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, sorted(v[k])])) : v;
+  const canonical3 = (d) => [
     d.title,
     d.subtitle || "",
     d.content_markdown,
+    d.excerpt ?? null,
+    sorted(d.cards ?? null),
+    sorted(d.citations ?? null),
     d.section,
     d.community || "",
     d.format || null,
@@ -662,7 +1033,7 @@ function sameDocument(a, b) {
       m.position
     ])
   ];
-  return JSON.stringify(canonical2(a)) === JSON.stringify(canonical2(b));
+  return JSON.stringify(canonical3(a)) === JSON.stringify(canonical3(b));
 }
 
-export { ArticlePhotoOperationError, ArticleWorkflowError, PublicationArticleClient, articlePhotoHtmlMatches };
+export { ArticleEditOperationError, ArticlePhotoOperationError, ArticleWorkflowError, PublicationArticleClient, articleEditHtmlMatches, articlePhotoHtmlMatches };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scalemule/news-publication",
-  "version": "0.0.80",
+  "version": "0.0.81",
   "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": {